🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more →

Book a Demo Install Sign in

js-cool

Package Overview

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

js-cool

Collection of common JavaScript / TypeScript utilities

5.23.1

latest

Source

npm

Version published: 5 months ago

Weekly downloads: 25

Maintainers: 0

Weekly downloads

Created: 4 years ago

Source

js-cool

Collection of common JavaScript / TypeScript utilities

Documentation • Change Log

Read this in other languages: English | 简体中文

Installation
Usage
API Reference
- Global Parameters
  - client - The client method returns a browser result object
  - pattern - Collection of common regular expressions
- Extras for String & Array & Object & Function
  - clearAttr - Remove all attributes of HTML tags
  - clearHtml - Removing HTML tags
  - escape - Escaping HTML Special Characters
  - unescape - Restore HTML Special Characters
  - getNumber - Get the number in the string
  - camel2Dash - Converts humped strings to -spaced and all lowercase Dash pattern
  - dash2Camel - Converts -spaced and all lowercase Dash patterns to humped strings
  - randomColor - Generate random hexadecimal colors
  - randomNumber - Get a random number
  - randomNumbers - Generate n random integers that sum to a fixed sum
  - randomString - Get a random string
  - shuffle - shuffling algorithm, Reordering arrays or strings
  - fingerprint - Generating Browser Fingerprints
  - getCHSLength - Get the length of the string, Chinese counts as 2 characters
  - cutCHSString - Intercept string, Chinese counts as 2 bytes
  - upperFirst - First letter capitalized
- Determine
  - isDigitals - Determine if a string is a number
  - isExitsFunction - Determine if a function is defined
  - isExitsVariable - Determine if a variable is defined
  - isEqual - Determine if 2 objects are equal
  - isWindow - Determine if window object
  - isPlainObject - Determine if target is an plain object
  - isDarkMode - Determine if dark color mode
  - isObject - Determine if target is an object
  - isDate - Determine if target is Date
  - isRegExp - Determine if target is RegExp
  - isArray - Determine if it is an array
  - isIterable - Determine if it is iterable
  - inBrowser - Determine if it is running on the browser side
  - inNodeJs - Determine if it is running on node.js
  - isNumberBrowser - Detect if the client is a 360 browser
  - windowSize - Get the window size
  - getAppVersion - Get the APP version number
  - appVersion - Get the app version number
  - getOsVersion - Get the phone system version
  - osVersion - get the system version
  - browserVersion - Get the browser name and version
  - compareVersion - Version number size comparison, tag version: rc > beta > alpha > other
  - parseUrlParam - parse url params. (If covert is passed true: Scientific notation, binary, octal and hexadecimal types of data are not converted, like: 0b111, 0o13, 0xFF, 1e3, -1e-2)
  - spliceUrlParam - Splice URL parameters (single layer only)
  - safeParse - Secure parsing of JSON strings
  - safeStringify - Secure stringify of JSON Object
  - getDirParam - Get the URL parameter in the form of a directory
  - getQueryParam - Get a single query parameter (behind "#")
  - getQueryParams - Get all query parameters (behind "#"). (If covert is passed true: Scientific notation, binary, octal and hexadecimal types of data are not converted, like: 0b111, 0o13, 0xFF, 1e3, -1e-2)
  - getUrlParam - Get a single URL parameter (from the "location.search", before "#")
  - getUrlParams - Get all URL parameters (from the "location.search", before "#"). (If covert is passed true: Scientific notation, binary, octal and hexadecimal types of data are not converted, like: 0b111, 0o13, 0xFF, 1e3, -1e-2)
- localStorage & sessionStorage & Cookie
  - getCache - Get the cache, if the deposited is Object, the retrieved is also Object, no need to convert again
  - setCache - Set the cache, if the deposited is Object, the retrieved is also Object, no need to convert again
  - delCache - Delete localStorage
  - getSession - Get the session, if the deposited is Object, the retrieved is also Object, no need to convert again
  - setSession - Set the session, if the deposited is Object, the retrieved is also Object, no need to convert again
  - delSession - Delete sessionStorage
  - getCookie - Get cookie by name
  - getCookies - Get all cookies
  - setCookie - Set cookie
  - delCookie - Delete cookie
- Base64 & UTF8
  - encodeBase64 - convert strings, numbers to base64
  - decodeBase64 - base64 decoding
  - encodeUtf8 - convert strings, numbers to utf8
  - decodeUtf8 - utf8 decoding
- Events
  - stopBubble - stop bubbling
  - stopDefault - stop default events
  - addEvent - event delegate, support multiple delegates
  - removeEvent - removeEvent removes the event delegate created by addEvent
  - getScrollPosition - Get slide to top and bottom return 'top' 'bottom', recommend using limit flow
- Utilities
  - nextIndex - return the next zIndex value
  - nextVersion - return the next version, Only version types with no more than 3 digits are supported. (Follow the npm version rules)
  - punctualTimer - punctual setInterval
  - promiseFactory - Convert an object to a promise like api
  - fixNumber - truncate a few decimal places, not 0 for shortage
  - mapTemplate - Replacing specific data in a template string, support ${xxxx} {{xxxx}} and {xxxx}
  - extend - deep copy & merge objects
  - clone - deep copy (Buffer, Promise, Set, Map are not supported)
  - delay - anti-dither throttling
  - getType - Get the target type
  - getFileType - Determine file type based on link suffix
  - sorter - Sorter factory function
  - sortPinyin - Sort Chinese by Chinese phonetic alphabet
  - cleanData - Data cleaning methods
  - download - Several ways of file downloading
  - searchObject - tree object depth lookup
  - openUrl - Open link in new tab (file jump download if browser can't parse)
  - copy - copy to clipboard
  - toThousands - Digital thousandths division
  - all - return true if the provided predicate function returns true for all elements in a set, otherwise return false
  - any - Returns true if the provided predicate function returns true for at least one element of a set, false otherwise
  - uuid - generate uuid on browser side, use v4 method
  - CSVToArray - Converts a comma-separated string of values (CSV) to a 2D array.
  - arrayToCSV - Converts a two-dimensional array to a comma-separated string of values (CSV).
  - CSVToJSON - Converts a comma-separated string of values (CSV) to an array of 2D objects. The first line of the string is used as the header line.
  - JSONToCSV - Converts an array of objects to a comma-separated value (CSV) string containing only the specified columns.
  - RGBToHex - Converts RGB component values to color codes.
  - intersect - Find the intersection of multiple arrays
  - union - Find the concatenation of multiple arrays
  - minus - Find the set of differences of multiple arrays that belong to A but not to B/C/D... of the elements of
  - complement - Find the complement of multiple arrays
  - contains - Whether the array contains the specified element
  - unique - Array de-duplication
  - fillIPv6 - ipv6 address completion
  - getProperty - Get array, object property values based on path string
  - setProperty - Set array, object property values based on path string
  - loadSource - load resources dynamically, support js, images, css links, css style strings
  - mountCss - dynamically load css link resources
  - mountImg - load image resource dynamically
  - mountJs - load js link resources dynamically
  - mountStyle - load css styles dynamically
  - preloader - Image preloading
  - waiting - waiting for a while
  - awaitTo - Async await wrapper for easy error handling
- Blob arrayBuffer base64 file blobUrl
  - arrayBufferToBase64 - arrayBuffer to base64
  - arrayBufferToBlob - arrayBuffer to blob
  - base64ToArrayBuffer - base64 to arrayBuffer
  - base64ToBlob - base64 to blob
  - base64ToFile - base64 to file
  - blobToArrayBuffer - blob to arrayBuffer
  - blobToBase64 - blob to base64
  - blobToUrl - blob to url
  - fileToBase64 - file to base64
  - svgToBlob - svg to blob
  - urlToBlob - url to blob
Support & Issues
License

Installation

# use pnpm
pnpm install js-cool

## use npm
npm install --save js-cool

Usage

ES6 module

import { osVersion } from 'js-cool'

osVersion()

Node.js require

const { osVersion } = require('js-cool')

osVersion()

Using unpkg CDN

<script src="https://unpkg.com/js-cool@latest/dist/index.global.prod.js"></script>
<script>
  jsCool.browserVersion()
</script>

API Reference

Global Parameters

client

The client method returns a browser result object

Since: 1.0.1
Arguments: none
Returns: object
Example:

import { client } from 'js-cool'

client.get(['device', 'browser', 'engine', 'os']) // { device: 'xxx', browser: 'xxx', os: 'xxx', engine: 'xxx' }
client.get('device') // { device: 'xxx' }

Types:

declare class Client {
  matchMap: Record<InfoKeys, boolean>
  root: Window & typeof globalThis
  navigator: Navigator
  constructor(options: ClientOptions)

  get(names?: InfoTypes | InfoTypes[]): Partial<{
    device: InfoKeys | undefined
    os: InfoKeys | undefined
    browser: InfoKeys | undefined
    engine: InfoKeys | undefined
    language: any
    network: any
    orientation: string | undefined
  }>

  getInfoByType(infoKey: InfoKey): InfoKeys | undefined
  getOrientationStatus(): 'vertical' | 'horizontal' | undefined
  getNetwork(): any
  getLanguage(): any
}

pattern

Collection of common regular expressions

v5.21.2 pattern support mac/ip4/ip4_pri

Since: 1.0.1
Arguments: none
Returns: none
Example:

pattern.number.test('333') // true

Types:

declare const pattern: {
  any: RegExp
  number: RegExp
  string: RegExp
  postcode: RegExp
  url: RegExp
  username: RegExp
  float: RegExp
  email: RegExp
  mobile: RegExp
  chinese: RegExp
  tel: RegExp
  qq: RegExp
  pass: RegExp
  json: RegExp
  arrjson: RegExp
  array: RegExp
  isjson: RegExp
  textarea: RegExp
  mac: RegExp
  ip4: RegExp
  ip4_pri: RegExp
}

Extras for String & Array & Object & Function

clearAttr

Remove all attributes of HTML tags

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	string with html tags	`string`	-	`true`	-

Returns: string
Example:

clearAttr('<div id="testID">test</div>')
// '<div>test</div>'

Types:

declare function clearAttr(string: string): string

clearHtml

Remove HTML tags

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	string with html tags	`string`	-	`true`	-

Returns: string
Example:

clearHtml('<div>test<br />string</div>')
// 'teststring'

Types:

declare function clearHtml(string: string): string

escape

Escaping HTML Special Characters

Since: 5.5.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	string with html tags	`string`	-	`true`	-

Returns: string
Example:

escape('<div>test<br />string</div>')
// '&lt;div&gt;test&lt;br /&gt;string&lt;/div&gt;'

Types:

declare function escape(string: string): string

unescape

Restore HTML Special Characters

Since: 5.5.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	string	`string`	-	`true`	-

Returns: string
Example:

unescape('&lt;div&gt;test&lt;br /&gt;string&lt;/div&gt;')
// '<div>test<br />string</div>'

Types:

declare function unescape(string: string): string

getNumber

Get the number in the string

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	pass in a string with a number	`string`	-	`true`	-

Returns: string
Example:

getNumber('Chrome123.33')
// '123.33'

getNumber('234test.88')
// '234.88'

Types:

declare function getNumber(string: string): string

camel2Dash

Converts humped strings to -spaced and all lowercase Dash pattern

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	the string to be converted	`string`	-	`true`	-

Returns: string
Example:

camel2Dash('jsCool') // js-cool

Types:

declare function camel2Dash(string: string): string

dash2Camel

Converts -spaced and all lowercase Dash patterns to humped strings

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	the string to be converted	`string`	-	`true`	-

Returns: string
Example:

dash2Camel('js-cool') // jsCool

Types:

declare function dash2Camel(string: string): string

randomColor

Generate random hexadecimal colors

Support for custom color value ranges starting with version 5.17.0, which can be used to customize the generation of darker, lighter, warmer colors, etc.

Since: 5.5.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
min	the minimum value of the random numbers	`number` / `[number, number, number]`	-	`false`	-
max	the maximum value of the random numbers	`number` / `[number, number, number]`	-	`false`	-

Returns: string
Example:

randomColor()
// #bf444b

randomColor(200)
// #d6e9d7

randomColor(200, 255)
// #d3f9e4

randomColor([0, 0, 0], [255, 255, 255])
// #e2f2f3

Types:

declare function randomColor(
  min?: number | [number, number, number],
  max?: number | [number, number, number]
): string

randomNumber

Get a random number

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
min	the minimum value of the random number	`number`	-	`false`	1
max	the maximum value of the random number	`number`	-	`false`	10

Returns: number
Example:

randomNumber() // 8
randomNumber(0.1, 0.9) // 0.8

Types:

declare function randomNumber(min?: number, max?: number): number

randomNumbers

Generate n random integers that sum to a fixed sum

Since: 5.4.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
n	Number of generated integers	`number`	-	`false`	1
sum	Sum of generated integers	`number`	-	`false`	100
noZero	Generate integers that are not zero	`boolean`	-	`false`	`true`

Returns: Array<number>
Example:

randomNumbers()
// [8]

randomNumbers(4, 5)
// [1, 1, 2, 1]

randomNumbers(4, 5, false)
// [0, 1, 2, 2]

Types:

declare function randomNumbers(n?: number, sum?: number): number[]

randomString

Get a random string

v5.4.0 widthSpecialChar changed to options, still compatible with old usage, widthSpecialChar=true equivalent to { charTypes: ['uppercase', 'lowercase', 'number', 'special'] }

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
len	the length of the random string that needs to be obtained	`number`	-	`false`	32
options	randomString options	`RandomStringOptions` `boolean`	-	`false`	`{ charTypes: ['uppercase', 'lowercase', 'number'] }`

Returns: string
Example:

// 1. No parameters are passed, a 32-bit (possibly) string containing upper and lower case letters and numbers is generated by default
randomString()
// PVSjz902EqYbmxaLtvDnggtnlvt5uFTZ

// 2. Generate a 16-bit random string
randomString(16)
// coTgZy0mqqMJ1sMM

// 3. Same effect as #2 above
randomString({
  length: 16
})
// ngCI5aPqJm84t90d

// 4. Generate containing special characters (old way of passing values, not recommended)
randomString(true)
// 0Uby@op3B-sK5]dHl4S|15As.OlHiNXd

// 5. Same effect as #4 above (recommended)
randomString({
  charTypes: ['uppercase', 'lowercase', 'number', 'special']
})
// m,2^vpkrE,F,DbcSFk0=vr&@DJ27j9XK

// 6. Same effect as #4 above, Limit string length to 16 bits
randomString(16, true)
// dXz[J_sYM^3d8fnA

// 7. Generate a 16-bit random number
randomString({
  length: 16,
  charTypes: 'number'
})
// 7450026301030286

// 8. Elimination of confusing characters: oOLl,9gq,Vv,Uu,I1
randomString({
  length: 16,
  noConfuse: true
})
// 8DEGna8ppC4mqyew

// 9. The generated random string must contain at least 1 character of each type of character specified, e.g. to generate a 16-bit password that must contain upper and lower case letters, numbers, and special characters.
randomString({
  length: 16,
  strict: true
})
// PFYAPD5KFqOHIADL

Types:

declare function randomString(len?: number, options?: RandomStringOptions | boolean): string

declare function randomString(
  len?: RandomStringOptions | boolean,
  options?: RandomStringOptions | boolean
): string

declare type RandomStringCharType = 'uppercase' | 'lowercase' | 'number' | 'special'

declare interface RandomStringOptions {
  length?: number
  charTypes?: RandomStringCharType | ArrayOneMore<RandomStringCharType>
  /**
   * Elimination of confusing characters: oOLl,9gq,Vv,Uu,I1
   */
  noConfuse?: boolean
  /**
   * The generated random string must contain each of the listed character types
   */
  strict?: boolean
}

shuffle

shuffling algorithm, Reordering arrays or strings

Since: 5.4.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
value	arrays or strings	`array` `string`	-	`true`	-
size	new array or string length	`number`	-	`false`	-

Returns: array | string
Example:

const str = 'abcde'
const arr = [1, 2, 3]

shuffle(str)
// cdbse

shuffle(arr)
// [3, 1, 2]

shuffle(arr, 2)
// [3, 2]

Types:

declare function shuffle(value: string, size?: number): string

declare function shuffle<T extends unknown[] = unknown[]>(value: T, size?: number): T

fingerprint

Generating Browser Fingerprints

Since: 5.2.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
domain	key string	`string`	-	`false`	location.host

Returns: string
Example:

fingerprint('www.saqqdy.com') // wc7sWJJA8

Types:

declare function fingerprint(domain?: string): string | null

getCHSLength

Get the length of the string, Chinese counts as 2 characters

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
str	input string	`string`	-	`true`	-

Returns: number
Example:

getCHSLength('测试') // 2

Types:

declare function getCHSLength(str: string): number

cutCHSString

Intercept string, Chinese counts as 2 bytes

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
str	the string to be intercepted	`string`	-	`true`	-
len	length	`number`	-	`false`	-
hasDot	output with dot	`boolean`	-	`false`	`false`

Returns: string
Example:

cutCHSString('测试', 1) // 测
cutCHSString('测试', 1, true) // 测...

Types:

declare function cutCHSString(str: string, len?: number, hasDot?: boolean): string

upperFirst

First letter capitalized

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
string	the string to be converted	`string`	-	`true`	-

Returns: string
Example:

upperFirst('saqqdy') // Saqqdy

Types:

declare function upperFirst(string: string): string

Determine

isDigitals

Determine if a string is a number

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
str	the string to be tested	`string`	-	`true`	-

Returns: boolean
Example:

isDigitals('2.11') // true
isDigitals('2.3x') // false

Types:

declare function isDigitals(str: string): boolean

isExitsFunction

Determine if a function is defined

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	function name	`string`	-	`true`	-

Returns: boolean
Example:

isExitsFunction('test') // false
isExitsFunction('console.log') // true

Types:

declare function isExitsFunction(name: string): boolean

isExitsVariable

Determine if a variable is defined

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	variable name	`string`	-	`true`	-

Returns: boolean
Example:

isExitsVariable('test') // false
isExitsVariable('window') // true

Types:

declare function isExitsVariable(name: string): boolean

isEqual

Determine if 2 objects are equal

Since: 5.12.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
a	source	`any`	-	`true`	-
b	compare	`any`	-	`true`	-

Returns: boolean
Example:

isEqual({ a: 22, b: {} }, { b: {}, a: 22 })
// true

isEqual([1, 2], [2, 1])
// false

isEqual(NaN, NaN)
// true

Types:

declare function isEqual<T, P>(a: T, b: P): boolean

isWindow

Determine if window object

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: boolean
Example:

isWindow({}) // false
isWindow(window) // true

Types:

declare function isWindow<T = any>(target: T): target is Window

isPlainObject

Determine if target is an plain object

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: boolean
Example:

isPlainObject({}) // true
isPlainObject(window) // false

Types:

type Primitive = bigint | boolean | null | number | string | symbol | undefined

type JSONValue = Primitive | PlainObject | JSONArray

// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
interface PlainObject {
  [key: string]: JSONValue
}

interface JSONArray extends Array<JSONValue> {}

declare function isPlainObject(target: unknown): target is PlainObject

isDarkMode

Determine if dark color mode

Since: 5.5.0
Arguments: none
Returns: boolean
Example:

isDarkMode() // false

Types:

declare function isDarkMode(): boolean

isObject

Determine if target is an object

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: boolean
Example:

isObject({}) // true

Types:

declare function isObject<T = any>(target: T): target is Object

isDate

Determine if target is Date

Since: 5.15.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: boolean
Example:

const now = new Date()

isDate(now)
// true

Types:

declare function isDate<T = any>(target: T): target is Date

isRegExp

Determine if target is RegExp

Since: 5.15.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: boolean
Example:

isRegExp(/\d/) // true

Types:

declare function isRegExp<T = any>(target: T): target is RegExp

isArray

Determine if it is an array

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: boolean
Example:

isArray([]) // true

Types:

declare function isIterable(target: any): target is any[]

isIterable

Determine if it is iterable

Since: 5.7.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: boolean
Example:

isIterable([]) // true

Types:

declare function isIterable<T = any>(target: T | Iterable<T>): target is Iterable<T>

inBrowser

Determine if it is running on the browser side

Since: 4.5.0
Arguments: none
Returns: boolean
Example:

function test() {
  if (!inBrowser) return null
  // ...
}

Types:

declare const inBrowser: boolean

inNodeJs

Determine if it is running on node.js

Since: 5.13.0
Arguments: none
Returns: boolean
Example:

if (inNodeJs) {
  //
}

Types:

declare const inNodeJs: boolean

isNumberBrowser

Detect if the client is a 360 browser

Since: 5.22.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
userAgent	ua or any ua like string, allowed to be undefined	`string`	-	`false`	`navigator.userAgent`

Returns: boolean
Example:

// 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.95 Safari/537.36 QIHU 360EE'
// true

// 'Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.95 Safari/537.36'
// true

Types:

declare function isNumberBrowser(userAgent?: string): boolean

windowSize

Get the window size

Since: 1.0.1
Arguments: none
Returns: { width, height }
Example:

windowSize()
// { width: 1280, height: 800 }

Types:

declare interface WindowSizeObj {
  width: number
  height: number
}

declare function windowSize(): WindowSizeObj

getAppVersion

Get the APP version number

deprecated please use 'appVersion' instead

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
appName	app name	`string`	-	`true`	-
withApp	whether to bring the name	`boolean`	-	`false`	-
userAgent	ua or any ua like string, allowed to be undefined	`string`	-	`false`	`navigator.userAgent`

Returns: string | boolean | null
Example:

// navigator.userAgent => '5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 AppName/1.0.0-beta.8'

getAppVersion('Chrome') // 114.0.0.0
getAppVersion('Safari', true) // Safari/537.36

Types:

declare function getAppVersion(
  appName: string,
  withApp?: boolean,
  userAgent?: string
): string | boolean | null

appVersion

Get the app version number

Since: 5.1.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
appName	app name	`string`	-	`true`	-
ua	ua or any ua like string, allowed to be undefined	`string`	-	`false`	navigator.userAgent
ignoreCase	whether to ignore case	`boolean`	`true`/`false`	`false`	`true`

Returns: string | null
Example:

// navigator.userAgent => '5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 AppName/1.0.0-beta.8'

appVersion('Chrome') // 114.0.0.0
appVersion('Safari') // 537.36
appVersion('appname', false) // null
appVersion('appname') // 1.0.0-beta.8

Types:

declare function appVersion(appName: string): string | null
declare function appVersion(appName: string, ua: string): string | null
declare function appVersion(appName: string, ua: boolean): string | null
declare function appVersion(appName: string, ua: string, ignoreCase: boolean): string | null

getOsVersion

Get the phone system version

deprecated: please use 'osVersion' instead

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
osName	system type string Android, iPod, iWatch or iPhone	`string`	-	`true`	-
withOS	whether to bring the name	`string`	-	`false`	-
userAgent	ua or any ua like string, allowed to be undefined	`string`	-	`false`	`navigator.userAgent`

Returns: string | boolean | null
Example:

getOsVersion('iPhone')
// '13.2.3'

getOsVersion('iPhone', true)
// 'iPhone/13.2.3'

Types:

declare function getOsVersion(
  osName: string,
  withOS?: boolean,
  userAgent?: string
): string | boolean | null

osVersion

get the system version

Since: 5.1.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
ua	ua or any ua like string, allowed to be undefined	`string`	-	`false`	navigator.userAgent

Returns: OsVersion | null
Example:

// ipad => 'Mozilla/5.0 (iPad; CPU OS 13_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/87.0.4280.77 Mobile/15E148 Safari/604.1'
osVersion() // \{ name: 'iOS', version: '13.3' \}
// iphone => 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_2_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.3 Mobile/15E148 Safari/604.1'
osVersion() // \{ name: 'iOS', version: '13.2.3' \}
//  mac os => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36'
osVersion() // \{ name: 'MacOS', version: '10.15.7' \}
// windows => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36'
osVersion() // \{ name: 'Windows', version: '10.0' \}
// windows xp => 'Mozilla/5.0 (Windows NT 5.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36'
osVersion() // \{ name: 'Windows', version: 'XP' \}
// windows phone => 'Mozilla/5.0 (Windows Phone OS 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.82 Safari/537.36'
osVersion() // \{ name: 'WindowsPhone', version: '10.0' \}

Types:

declare interface OsVersion {
  name: 'Windows' | 'MacOS' | 'Android' | 'iOS' | 'WindowsPhone' | 'Debian' | 'WebOS' | 'Harmony'
  version: string
}

declare function osVersion(ua?: string): OsVersion | null

browserVersion

Get the browser name and version

Since: 5.2.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
ua	ua or any ua like string, allowed to be undefined	`string`	-	`false`	navigator.userAgent

Returns: BrowserVersion | null
Example:

// Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Ap…KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36
browserVersion() // \{ name: 'Chrome', version: '114.0.0.0' \}

Types:

declare interface BrowserVersion {
  name:
    | 'Safari'
    | 'Chrome'
    | 'IE'
    | 'Edge'
    | 'Firefox'
    | 'Firefox Focus'
    | 'Chromium'
    | 'Opera'
    | 'Vivaldi'
    | 'Yandex'
    | 'Arora'
    | 'Lunascape'
    | 'QupZilla'
    | 'Coc Coc'
    | 'Kindle'
    | 'Iceweasel'
    | 'Konqueror'
    | 'Iceape'
    | 'SeaMonkey'
    | 'Epiphany'
    | '360'
    | '360SE'
    | '360EE'
    | 'Maxthon'
    | 'QQBrowser'
    | 'QQ'
    | 'Baidu'
    | 'UC'
    | 'Sogou'
    | 'Liebao'
    | 'LBBROWSER'
    | '2345Explorer'
    | '115Browser'
    | 'TheWorld'
    | 'XiaoMi'
    | 'Vivo'
    | 'Quark'
    | 'Qiyu'
    | 'Wechat'
    | 'WechatWork'
    | 'Taobao'
    | 'Alipay'
    | 'Weibo'
    | 'Douban'
    | 'Suning'
    | 'iQiYi'
    | 'DingTalk'
    | 'Huawei'
  version: string
}

declare function browserVersion(ua?: string): BrowserVersion | null

compareVersion

v5.8.0 support compare tag version

Version number size comparison, tag version: rc > beta > alpha > other

Since: 4.7.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	input version	`string`	-	`true`	-
compare	compare version	`string`	-	`true`	-

Returns: 0 | 1 | -1
Example:

compareVersion('1.11.0', '1.9.9')
// => 1: 1=Version 1.11.0 is newer than 1.9.9

compareVersion('1.11.0', '1.11.0')
// => 0: 0=Versions 1.11.0 and 1.11.0 are the same

compareVersion('1.11.0', '1.99.0')
// => -1: -1=Version 1.11.0 is older than 1.99.0

compareVersion('1.0.0.0.0.10', '1.0')
// => -1

// compare tag version: rc > beta > alpha > other
compareVersion('1.11.0', '1.11.0-beta.1')
// => -1

compareVersion('1.11.0-beta.1', '1.11.0')
// => -1

compareVersion('1.11.0-beta.10', '1.11.0-beta.10')
// => 0

compareVersion('1.11.0-alpha.10', '1.11.0-beta.1')
// => -1

compareVersion('1.11.0-alpha.10', '1.11.0-rc.1')
// => -1

compareVersion('1.11.0-tag.10', '1.11.0-alpha.1')
// => -1

compareVersion('1.11.0-tag.10', '1.11.0-tag.1')
// => 1

compareVersion('1.11.0-release.10', '1.11.0-tag.1')
// => 1

Types:

declare function compareVersion(input: string, compare: string): 0 | 1 | -1

parseUrlParam

parse url params. (If covert is passed true: Scientific notation, binary, octal and hexadecimal types of data are not converted, like: 0b111, 0o13, 0xFF, 1e3, -1e-2)

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	url string (like: ?key1=value1&key2=value2)	`string`	-	`true`	-
covert	Converts a specific string to a corresponding value	`boolean`	`true`/`false`	`false`	`false`

Returns: object
Example:

parseUrlParam(
  '?key1=100&key2=true&key3=null&key4=undefined&key5=NaN&key6=10.888&key7=Infinity&key8=test'
)
// \{"key1":"100","key2":"true","key3":"null","key4":"undefined","key5":"NaN","key6":"10.888","key7":"Infinity","key8":"test"\}

parseUrlParam(
  '?key1=100&key2=true&key3=null&key4=undefined&key5=NaN&key6=10.888&key7=Infinity&key8=test',
  true
)
// \{"key1":100,"key2":true,"key3":null,"key5":NaN,"key6":10.888,"key7":Infinity,"key8":"test"\}

Types:

declare function parseUrlParam(url: string, covert?: boolean): Record<string, unknown>

spliceUrlParam

Splice URL parameters (single layer only)

v5.20.0 Breaking change: remove encodeURIComponent
v5.21.0 Breaking change: covert support boolean & SpliceUrlParamOptions

Since: 5.3.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
params	json object	`object`	-	`true`	-
covert	Convert a null value type (null/undefined/) to an empty string or spliceUrlParamOptions	`boolean` \| `SpliceUrlParamOptions`	-	`false`	`false`

Returns: string
Example:

spliceUrlParam({ key1: '100', key2: true, key3: null, key4: undefined, key5: '测试' })
// ?key1=100&key2=true&key3=null&key4=undefined&key5=测试

spliceUrlParam(
  { key1: '100', key2: true, key3: null, key4: undefined, key5: '测试' },
  { encode: true }
)
// ?key1=100&key2=true&key3=null&key4=undefined&key5=%E6%B5%8B%E8%AF%95

spliceUrlParam({ key1: '100', key2: true, key3: null, key4: undefined }, true)
// ?key1=100&key2=true&key3=&key4=

spliceUrlParam(
  { key1: '100', key2: true, key3: null, key4: undefined },
  { covert: true, withQuestionsMark: false }
)
// key1=100&key2=true&key3=&key4=

Types:

declare function spliceUrlParam<T extends Record<string, unknown>>(
  params: T,
  covert?: SpliceUrlParamOptions | boolean
): string

declare interface SpliceUrlParamOptions {
  covert?: boolean
  encode?: boolean
  withQuestionsMark?: boolean
}

safeParse

Secure parsing of JSON strings

support BigInt since v5.17.1

Since: 5.16.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
data	JSON string	`string`	-	`true`	-
covert	Whether to convert data	`boolean`	`true`/`false`	`false`	`true`

Returns: Object
Example:

safeParse('100')
// 100

safeParse('{"a":"undefined","b":"NaN","c":"Infinity","d":"9007199254740993"}')
// { b: NaN, c: Infinity, d: 9007199254740993n }

Types:

declare function safeParse(data: string, covert?: boolean): any

safeStringify

Secure stringify of JSON Object

support BigInt since v5.17.1

Since: 5.16.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
data	JSON Object	`any`	-	`true`	-
covert	Whether to convert data	`boolean`	`true`/`false`	`false`	`true`

Returns: string
Example:

safeStringify(100)
// "100"

safeStringify(undefined)
// "undefined"

safeStringify(NaN)
// "NaN"

safeStringify(Infinity)
// "Infinity"

safeStringify({ a: undefined, b: NaN, c: Infinity, d: BigInt(Number.MAX_SAFE_INTEGER) + 2n })
// {"a":"undefined","b":"NaN","c":"Infinity","d":"9007199254740993"}

Types:

declare function safeStringify(data: any, covert?: boolean): string

getDirParam

Get the URL parameter in the form of a directory

It will be refactored and renamed getDirParams in the next major release.

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	http url	`object`	-	`true`	-

Returns: object
Example:

//

Types:

declare interface DirParamType {
  path?: string[]
  host?: string
}

declare function getDirParam(url: string): DirParamType

getQueryParam

Get a single query parameter (behind "#")

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
key	key name	`string`	-	`true`	-
url	pass in the url string	`string`	-	`false`	`location.href`

Returns: string
Example:

getQueryParam('key1')
// key1 => xxx

getQueryParam('key1', 'https://test.com?key1=100#/home?key1=200')
// key1 => 200

Types:

declare function getQueryParam(key: string): string | undefined

declare function getQueryParam(key: string, url: string): string | undefined

getQueryParams

Get all query parameters (behind "#"). (If covert is passed true: Scientific notation, binary, octal and hexadecimal types of data are not converted, like: 0b111, 0o13, 0xFF, 1e3, -1e-2)

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	pass in the url string	`string`	-	`false`	`location.href`
covert	Converts a specific string to a corresponding value	`boolean`	`true`/`false`	`false`	`false`

Returns: object
Example:

getQueryParams('https://test.com?key1=100#/home?key1=200')
// \{"key1":"200"\}

getQueryParams('https://test.com?key1=100#/home?key1=200', true)
// \{"key1":200\}

getQueryParams(true)
// \{"key1":200\}

Types:

declare function getQueryParams(url?: string, covert?: boolean): Record<string, unknown> | null

getUrlParam

Get a single URL parameter (from the "location.search", before "#")

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
key	key name	`string`	-	`true`	-
url	pass in the url string	`string`	-	`false`	`location.href`

Returns: string
Example:

getUrlParam('key1')
// key1 => xxx

getUrlParam('key1', 'https://test.com?key1=100#/home?key1=200')
// key1 => 100

Types:

declare function getUrlParam(key: string): string | undefined

declare function getUrlParam(key: string, url: string): string | undefined

getUrlParams

Get all URL parameters (from the "location.search", before "#"). (If covert is passed true: Scientific notation, binary, octal and hexadecimal types of data are not converted, like: 0b111, 0o13, 0xFF, 1e3, -1e-2)

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	pass in the url string	`string`	-	`false`	`location.href`
covert	Converts a specific string to a corresponding value	`boolean`	`true`/`false`	`false`	`false`

Returns: object
Example:

getUrlParams('https://test.com?key1=100#/home?key1=200')
// \{"key1":"100"\}

getUrlParams('https://test.com?key1=100#/home?key1=200', true)
// \{"key1":100\}

getUrlParams(true)
// \{"key1":100\}

Types:

declare function getUrlParams(url?: string, covert?: boolean): Record<string, unknown> | null

getCache

Get the cache, if the deposited is Object, the retrieved is also Object, no need to convert again

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	cache key name	`string`	-	`true`	-

Returns: any
Example:

import { getCache, setCache } from 'js-cool'

const data1 = 100
const data2 = { a: 10 }
const data3 = null

setCache('data1', data1)
setCache('data2', data2)
setCache('data3', data3)

getCache('data1') // 100
getCache('data2') // {a:10}
getCache('data3') // null

getCache('data4') // null

Types:

declare function getCache(name: string): any

setCache

Set the cache, if the deposited is Object, the retrieved is also Object, no need to convert again

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	cache key name	`string`	-	`true`	-
value	cache data, can be passed directly into Object	`any`	-	`true`	-
seconds	cache time (seconds)	`number`	-	`false`	-

Returns: void
Example:

import { getCache, setCache } from 'js-cool'

const data1 = 100
const data2 = { a: 10 }
const data3 = null

setCache('data1', data1)
setCache('data2', data2, 10)

getCache('data1') // 100
getCache('data2') // {a:10}

setTimeout(() => {
  getCache('data2') // null
}, 15000)

Types:

declare function setCache<T = unknown>(name: string, value: T, seconds?: number | string): void

delCache

Delete localStorage

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	cache key name	`string`	-	`true`	-

Returns: void
Example:

delCache('data')

Types:

declare function delCache(name: string): void

getSession

Get the session, if the deposited is Object, the retrieved is also Object, no need to convert again

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	session key name	`string`	-	`true`	-

Returns: any
Example:

const data1 = 100
const data2 = { a: 10 }
const data3 = null

setSession('data1', data1)
setSession('data2', data2)
setSession('data3', data3)

getSession('data1') // 100
getSession('data2') // {a:10}
getSession('data3') // null

getSession('data4') // null

Types:

declare function getSession(name: string): any

setSession

Set the session, if the deposited is Object, the retrieved is also Object, no need to convert again

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	session key name	`string`	-	`true`	-
value	session data, can be passed directly into Object	`any`	-	`true`	-
seconds	session time (seconds)	`number`	-	`false`	-

Returns: void
Example:

import { getSession, setSession } from 'js-cool'

const data1 = 100
const data2 = { a: 10 }
const data3 = null

setSession('data1', data1)
setSession('data2', data2, 10)

getSession('data1') // 100
getSession('data2') // {a:10}

setTimeout(() => {
  getSession('data2') // null
}, 15000)

Types:

declare function setSession<T = unknown>(name: string, value: T, seconds?: number | string): void

delSession

Delete sessionStorage

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	session key name	`string`	-	`true`	-

Returns: void
Example:

delSession('data')

Types:

declare function delSession(name: string): void

getCookie

Get cookie by name

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	cookie key name	`string`	-	`true`	-

Returns: any
Example:

getCookie('data1') // 100

Types:

declare function getCookie(name: string): string

getCookies

Get all cookies

Since: 5.6.0
Arguments: 'none'
Returns: object
Example:

getCookies()
// { token: 'xxx', name: 'saqqdy' }

Types:

declare function getCookies(): Record<string, string>

setCookie

Set cookie

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	cookie key name	`string`	-	`true`	-
value	cookie data, can be passed directly into Object	`any`	-	`true`	-
seconds	cookie time (seconds)	`number`	-	`false`	-
path	cookie path	`string`	-	`false`	`/`
samesite	SameSite type	`string`	`Strict`/`Lax` /`None`	`false`	`None`

Returns: void
Example:

import { getCookie, setCookie } from 'js-cool'

const data1 = 100
const data2 = 200

setCookie('data1', data1)
setCookie('data2', data2, 10)

getCookie('data1') // 100
getCookie('data2') // 200

setTimeout(() => {
  getCookie('data2') // null
}, 15000)

Types:

declare function setCookie<T extends string | number | boolean>(
  name: string,
  value: T,
  seconds: string | number,
  path?: string,
  samesite?: boolean
): void

delCookie

Delete cookie

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
name	cookie key name	`string`	-	`true`	-

Returns: void
Example:

delCookie('data')

Types:

declare function delCookie(name: string): void

Base64 & UTF8

encodeBase64

convert strings, numbers to base64

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	the string to be encoded	`string`/`number`	-	`true`	-

Returns: void
Example:

encodeBase64('data')

Types:

declare function encodeBase64(name: string): string

decodeBase64

base64 decoding

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	the string to be decoded	`string`/`number`	-	`true`	-

Returns: void
Example:

decodeBase64('data')

Types:

declare function decodeBase64(name: string): string

encodeUtf8

convert strings, numbers to utf8

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	the string to be encoded	`string`/`number`	-	`true`	-

Returns: void
Example:

encodeUtf8('data')

Types:

declare function encodeUtf8(name: string): string

decodeUtf8

utf8 decoding

Since: 1.0.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	the string to be decoded	`string`/`number`	-	`true`	-

Returns: void
Example:

decodeUtf8('data')

Types:

declare function decodeUtf8(name: string): string

Events

stopBubble

stop bubbling

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
e	dom's event object	`Event`	-	`true`	-

Returns: boolean
Example:

stopBubble(event)

Types:

declare function stopBubble(e: Event): boolean

stopDefault

stop default events

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
e	dom's event object	`Event`	-	`true`	-

Returns: boolean
Example:

stopDefault(event)

Types:

declare function stopDefault(e: Event): boolean

addEvent

event delegate, support multiple delegates

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
element	js dom object	`HTMLElement`	-	`true`	-
type	The type of the event. No need to add on	`string`	-	`true`	-
handler	Callback method	`function`	-	`true`	-

Returns: void
Example:

addEvent(document, 'click', functionName)

Types:

declare function addEvent(element: AnyObject, type: string, handler: AnyFunction): void

removeEvent

removeEvent removes the event delegate created by addEvent

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
element	js dom object	`HTMLElement`	-	`true`	-
type	The type of the event. No need to add on	`string`	-	`true`	-
handler	Callback method	`function`	-	`true`	-

Returns: void
Example:

removeEvent(document, 'click', functionName)

Types:

declare function removeEvent(element: AnyObject, type: string, handler: AnyFunction): void

getScrollPosition

Get slide to top and bottom return 'top' 'bottom', recommend using limit flow

Since: 1.0.2
Arguments: none
Returns: 'top' | 'bottom' | undefined
Example:

getScrollPosition() // ‘bottom’

Types:

declare function getScrollPosition(): string | void

Utilities

nextIndex

return the next zIndex value

change mix defaults to 0

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
min	minimum value	`number`	-	`false`	`0`
max	maximum value	`number`	-	`false`	-

Returns: number
Example:

nextIndex() // 1

nextIndex(1000) // 1001

nextIndex(10, 100) // 100

Types:

declare function nextIndex(min?: number, max?: number): number

nextVersion

return the next version, Only version types with no more than 3 digits are supported. (Follow the npm version rules)

Since: 5.10.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
version	version(like: 1.0.0)	`string`	-	`true`	-
type	version type	`major` \| `minor` \| `patch` \| `premajor` \| `preminor` \| `prepatch` \| `prerelease`	-	`false`	`patch`
preid	prerelease id	`string`	-	`false`	''

Returns: string
Example:

nextVersion('1.2.33') // 1.2.34

nextVersion('1.2.33', 'major') // 2.0.0

nextVersion('1.2.33', 'premajor', 'alpha') // 2.0.0-alpha.1

Types:

declare function nextVersion(
  version: string,
  type?: 'major' | 'minor' | 'patch' | 'premajor' | 'preminor' | 'prepatch' | 'prerelease',
  preid?: string
): string

punctualTimer

punctual setInterval

v5.23.0 got returns of PunctualTimerReturns

Since: 5.18.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
handler	A function to be executed after the timer expires.	`function`	-	`true`	-
delay	The time, in milliseconds that the timer should wait before the specified function or code is executed. If this parameter is omitted, a value of 0 is used, meaning execute "immediately", or more accurately, the next event cycle.	`number`	-	`true`	-
...args	Additional arguments which are passed through to the function specified by handler.	`any[]`	-	`false`	-

Returns: PunctualTimerReturns
Example:

const printDate = () => console.log(new Date())
const timer = punctualTimer(printDate, 1000)
console.log(timer.count) // 10
timer.clear() // clear punctualTimer or use clearTimeout(timer.timer)

Types:

declare function punctualTimer<TArgs extends any[]>(
  handler: (args: void) => void,
  delay: number,
  [...args]?: TArgs
): PunctualTimerReturns

declare function punctualTimer<TArgs extends any[]>(
  handler: (...args: TArgs) => void,
  delay: number,
  [...args]?: TArgs
): PunctualTimerReturns

declare interface PunctualTimerReturns {
  count: number
  timer: number | null
  clear: () => void
}

promiseFactory

Convert an object to a promise like api

Since: 5.10.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
original	original object	`object`	-	`true`	-
resolver	resolver function	`Function`	-	`true`	-

Returns: T & PromiseLike<T>
Example:

import { promiseFactory, waiting } from 'js-cool'

function promise() {
  const stats = {
    value: 100
  }

  const resolver = () =>
    new Promise(resolve =>
      waiting(2000).then(() => {
        stats.value = 200
        resolve(stats)
      })
    )

  return promiseFactory(stats, resolver)
}

const res = promise()
// res => 100
const res = await promise()
// res => 200

Types:

declare function promiseFactory<T extends object>(
  original: T,
  resolver: () => Promise<any>
): T & PromiseLike<T>

fixNumber

truncate a few decimal places, not 0 for shortage

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
number	the number of digits to be processed	`number`/`string`	-	`true`	-
n	the number of decimal places to keep	`number`	-	`false`	`2`

Returns: string | number
Example:

fixNumber('100.888')
// 100.88

fixNumber('100.8', 2)
// 100.8

fixNumber('100.8888', 3)
// 100.888

Types:

declare function fixNumber(number: string | number, n?: number): number

mapTemplate

Replacing specific data in a template string, support ${xxxx} {{xxxx}} and {xxxx}

Since: 5.9.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
tmp	Template string	`string`	-	`true`	-
data	Template data of map function	`Function`\| `Object`	-	`true`	-

Returns: string
Example:

const tmp = "My name is ${name}, I'm ${age} years old."
mapTemplate(tmp, {
  name: 'saqqdy',
  age: 18
})
// My name is saqqdy, I'm 18 years old.

mapTemplate(tmp, key => ({ name: 'saqqdy', age: 28 })[key])
// My name is saqqdy, I'm 28 years old.

const tmp1 = "My name is {{name}}, I'm {{age}} years old."
mapTemplate(tmp1, {
  name: 'saqqdy',
  age: 18
})
// My name is saqqdy, I'm 18 years old.

Types:

declare function mapTemplate(
  tmp: string,
  data: ((value: string) => unknown) | Record<string, unknown>
): string

extend

deep copy & merge objects

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	boolean or array or object	`boolean`/`ArrayOneMore<ExtendData>`	-	`true`	-
...args	array or object	`ArrayOneMore<ExtendData>`	-	`true`	-

Returns: array | object
Example:

extend(true, {}, {})

Types:

declare function extend(
  target: ExtendObjectData,
  ...args: ArrayOneMore<ExtendObjectData>
): ExtendObjectData

declare function extend(target: boolean, ...args: ArrayOneMore<ExtendObjectData>): ExtendObjectData

declare function extend(
  target: ExtendArrayData,
  ...args: ArrayOneMore<ExtendArrayData>
): ExtendArrayData

declare function extend(target: boolean, ...args: ArrayOneMore<ExtendArrayData>): ExtendArrayData

declare type ExtendArrayData = any[]

declare type ExtendData = ExtendArrayData | ExtendObjectData

declare type ExtendObjectData = Record<string, any>

clone

deep copy (Buffer, Promise, Set, Map are not supported)

Since: 5.15.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
source	source object	`any`	-	`true`	-

Returns: object
Example:

const source = { a: 100, reg: /\d+/g, arr: [1, 2] }
const res = clone(source)
// { a: 100, reg: /\d+/g, arr: [1, 2] }

Types:

declare function clone<T = any>(parent: T): T

delay

anti-dither throttling

Since: 1.0.2
Arguments: none
Returns: void
Example:

const delay = new Delay()

delay.register('key', () => {
  //
})

Types:

declare function delay(): {
  map: any
  register(id: string, fn: AnyFunction, time: number, boo: boolean): void
  destroy(id: string): void
}

getType

Get the target type

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	any target	`any`	-	`true`	-

Returns: string
Example:

getType({}) // object
getType([]) // array
getType(new Promise()) // promise
getType(new Date()) // date
getType(async () => {}) // function
getType(navigator) // navigator
getType(global) // global
getType(window) // window
getType(Symbol('')) // symbol

Types:

declare function getType<T = any>(
  target: T
):
  | 'string'
  | 'number'
  | 'bigint'
  | 'boolean'
  | 'symbol'
  | 'undefined'
  | 'object'
  | 'function'
  | 'window'
  | 'error'
  | 'promise'
  | 'math'
  | 'document'
  | 'navigator'
  | 'global'
  | 'array'
  | 'date'
  | 'regexp'
  | 'null'

getFileType

Determine file type based on link suffix

Since: 5.11.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	file url	`string`	-	`true`	-

Returns: object
Example:

getFileType('/name.png')
// { "suffix": "png", "type": "image" }

getFileType('/name.PDF')
// { "suffix": "pdf", "type": "pdf" }

getFileType('/name.xyz')
// { "suffix": "xyz", "type": "other" }

Types:

declare function getFileType(url: string): {
  suffix: string
  type: 'audio' | 'video' | 'image' | 'other' | 'word' | 'txt' | 'excel' | 'pdf' | 'ppt' | 'zip'
}

sorter

Sorter factory function

Since: 5.14.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
locales	A string with a BCP 47 language tag, or an array of such strings	`string` `Array`	-	`false`	-
options	An object adjusting the output format.	`Intl.CollatorOptions`	-	`false`	-

Returns: Function
Example:

const items = ['啊我', '波拉', 'abc', 0, 3, '10', ',11', 13, null, '阿吧', 'ABB', 'BDD', 'ACD', 'ä']

items.sort(
  sorter('zh-Hans-CN', {
    ignorePunctuation: true,
    sensitivity: 'variant',
    numeric: true
  })
)
// [ 0, 3, "10", ",11", 13, "ä", "ABB", "abc", "ACD", "BDD", null, "阿吧", "啊我", "波拉" ]

Types:

declare function sorter(
  locales?: string | string[],
  options?: Intl.CollatorOptions
): <T = string, P = string>(a: T, b: P) => number

sortPinyin

Sort Chinese by Chinese phonetic alphabet

Since: 5.14.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
a	The first element for comparison.	`any`	-	`true`	-
b	The second element for comparison.	`any`	-	`true`	-
options	An object adjusting the output format.	`Intl.CollatorOptions`	-	`false`	-

Returns: number
Example:

const items = ['啊我', '波拉', 'abc', 0, 3, '10', ',11', 13, null, '阿吧', 'ABB', 'BDD', 'ACD', 'ä']

items.sort(sortPinyin)
// [ ",11", 0, "10", 13, 3, "ä", "ABB", "abc", "ACD", "BDD", null, "阿吧", "啊我", "波拉" ]

items.sort((a, b) => sortPinyin(a, b, { ignorePunctuation: true, numeric: true }))
// [ 0, 3, "10", ",11", 13, "ä", "ABB", "abc", "ACD", "BDD", null, "阿吧", "啊我", "波拉" ]

Types:

declare function sortPinyin<T = string, P = string>(
  a: T,
  b: P,
  options?: Intl.CollatorOptions
): number

cleanData

Data cleaning methods

Since: 1.0.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
data	the object to be cleaned	`object`	-	`true`	-
map	the data queue to be cleaned, can be passed as array or object	`array`/`object`	-	`true`	-
nullFix	the value returned if there is no corresponding property, the default does not return the property	`any`	-	`false`	-

Returns: any
Example:

//

Types:

declare function cleanData(data: any, map: any[] | AnyObject, nullFix?: any): any

download

Several ways of file downloading:

For file formats that some browsers do not recognize. Enter the file URL in the address bar, window.location.href = URL, window.open(URL);
using a tag download attribute (or js create a tag);
browser-recognizable pdf, txt files, back-end compatible with handling attachment;
add token in the header for authenticated download, use XmlHttpRequest to want to backend to launch the request

Since: 1.0.5
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	url link	`string`	-	`true`	-
filename	file name	`string`	-	`true`	-
type	download type	`string`	`href`/`open`/`download`/`request`	`false`	`download`

Returns: void
Example:

download('https://unpkg.com/browse/js-cool@5.2.0/dist/index.global.prod.js')

Types:

declare function download(url: string, filename: string, type?: string): void

searchObject

tree object depth lookup

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
tree	tree object	`array`/`object`	-	`true`	-
expression	required Query method	`any`	-	`true`	-
keySet	optional Default subclass name, query name	`SearchKeySet`	-	`true`	-
number	optional Number of lookups, if not passed, query all	`number`	-	`false`	-

Returns: any
Example:

//

Types:

declare function searchObject(
  tree: object | any[],
  expression: any,
  keySet: SearchKeySet,
  number?: number
): any[]

openUrl

Open link in new tab (file jump download if browser can't parse)

Since: 1.0.6
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	http url	`string`	-	`true`	-

Returns: boolean | undefined
Example:

openUrl('https://www.saqqdy.com/js-cool')

Types:

declare function openUrl(url: string): void

copy

copy to clipboard

Since: 5.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
value	any value	`any`	-	`true`	-

Returns: boolean | undefined
Example:

copy('10000')

Types:

declare function copy(value: string): boolean | undefined

toThousands

Digital thousandths division

Since: 3.0.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
num	the number	`string`/`number`	-	`true`	-

Returns: string
Example:

toThousands(10000) // '10,000'

Types:

declare function toThousands(num: string | number): string

all

return true if the provided predicate function returns true for all elements in a set, otherwise return false

Since: 1.0.9
Arguments:

Parameters	Description	Type	Optional	Required	Default
arr	the target array	`array`	-	`true`	-
fn	the judgment method	`function`	-	`true`	-

Returns: boolean
Example:

all([4, 2, 3], x => x > 1)
// true

Types:

declare const all: <T = unknown>(arr: T[], fn: AnyFunction) => boolean

any

Returns true if the provided predicate function returns true for at least one element of a set, false otherwise

Since: 1.0.9
Arguments:

Parameters	Description	Type	Optional	Required	Default
arr	the target array	`array`	-	`true`	-
fn	the judgment method	`function`	-	`true`	-

Returns: boolean
Example:

any([0, 1, 2, 0], x => x >= 2)
// true

Types:

declare const any: <T = unknown>(arr: T[], fn: AnyFunction) => boolean

uuid

generate uuid on browser side, use v4 method

Since: 1.0.9
Arguments: none
Returns: string
Example:

uuid() // '4222fcfe-5721-4632-bede-6043885be57d'

Types:

declare const uuid: () => string

CSVToArray

Converts a comma-separated string of values (CSV) to a 2D array.

Since: 1.0.9
Arguments:

Parameters	Description	Type	Optional	Required	Default
data	csv data	`string`	-	`true`	-
delimiter	delimiter	`string`	-	`false`	','
omitFirstRow	the first row is the table header data	`boolean`	-	`false`	`false`

Returns: string
Example:

CSVToArray('a,b\\nc,d') // `[['a','b'],['c','d']]`
CSVToArray('a;b\\\nc;d', ';') // `[['a','b'],['c','d']]`
CSVToArray('col1,col2\\\na,b\\\nc,d', ',', true) // `[['a','b'],['c','d']]`

Types:

declare const CSVToArray: (data: string, delimiter?: string, omitFirstRow?: boolean) => string[][]

arrayToCSV

Converts a two-dimensional array to a comma-separated string of values (CSV).

Since: 1.0.9
Arguments:

Parameters	Description	Type	Optional	Required	Default
arr	json data	`array`	-	`true`	-
delimiter	delimiter	`string`	-	`false`	','

Returns: string
Example:

arrayToCSV([
  ['a', 'b'],
  ['c', 'd']
])
// '"a", "b" \n "c", "d"'

arrayToCSV(
  [
    ['a', 'b'],
    ['c', 'd']
  ],
  ';'
)
// '"a"; "b"\n "c"; "d"'

arrayToCSV([
  ['a', '"b" great'],
  ['c', 3.1415]
])
// '"a", """b"" great"\n "c",3.1415'

Types:

declare function arrayToCSV<T extends unknown[][]>(data: T, delimiter?: string): string

CSVToJSON

Converts a comma-separated string of values (CSV) to an array of 2D objects. The first line of the string is used as the header line.

Since: 1.0.9
Arguments:

Parameters	Description	Type	Optional	Required	Default
data	csv data	`string`	-	`true`	-
delimiter	delimiter	`string`	-	`false`	','

Returns: string
Example:

CSVToJSON('col1,col2\\na,b\\\nc,d')
// `[{'col1': 'a', 'col2': 'b'}, {'col1': 'c', 'col2': 'd'}]`

CSVToJSON('col1;col2\\\na;b\\\nc;d', ';')
// `[{'col1': 'a', 'col2': 'b'}, {'col1': 'c', 'col2': 'd'}]`

Types:

declare function CSVToJSON(data: string, delimiter?: string): any[]

JSONToCSV

Converts an array of objects to a comma-separated value (CSV) string containing only the specified columns.

Since: 1.0.9
Arguments:

Parameters	Description	Type	Optional	Required	Default
arr	json data	`array`	-	`true`	-
columns	the specified columns	`array`	-	`true`	-
delimiter	delimiter	`string`	-	`false`	','

Returns: string
Example:

JSONToCSV([{ a: 1, b: 2 }, { a: 3, b: 4, c: 5 }, { a: 6 }, { b: 7 }], ['a', 'b']) // 'a,b\n "1", "2"\n "3", "4"\n "6",""\n"", "7"'
JSONToCSV([{ a: 1, b: 2 }, { a: 3, b: 4, c: 5 }, { a: 6 }, { b: 7 }], ['a', 'b'], ';') // 'a;b\n "1"; "2"\n "3"; "4"\n "6";""\n""; "7"'

Types:

declare const JSONToCSV: (arr: any[], columns: any[], delimiter?: string) => string

RGBToHex

Converts RGB component values to color codes.

Since: 1.0.9
Arguments:

Parameters	Description	Type	Optional	Required	Default
r	the 1st value of RGB	`number`	-	`true`	-
g	RGB's 2nd value	`number`	-	`true`	-
b	RGB's 3nd value	`number`	-	`true`	-

Returns: string
Example:

RGBToHex(255, 165, 1) // 'ffa501'

Types:

declare const RGBToHex: (r: number, g: number, b: number) => string

intersect

Find the intersection of multiple arrays

Since: 2.2.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
...arr	array targets	`array`	-	`true`	-

Returns: array
Example:

intersect([1, 2], [2, 3, 4], [2, 8], [2, '33']) // [2]

Types:

declare function intersect<T = unknown>(...args: T[][]): T[]

union

Find the concatenation of multiple arrays

Since: 2.2.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
...arr	array targets	`array`	-	`true`	-

Returns: array
Example:

union([1, 2], [2, '33']) // [1, 2, '33']

Types:

declare function union<T = unknown>(...args: T[][]): T[]

minus

Find the set of differences of multiple arrays that belong to A but not to B/C/D... of the elements of

Since: 2.2.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
...arr	array targets	`array`	-	`true`	-

Returns: array
Example:

minus([1, 2], [2, '33'], [2, 4]) // [1]

Types:

declare function minus<T = unknown>(...args: T[][]): T[]

complement

Find the complement of multiple arrays

Since: 2.2.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
...arr	array targets	`array`	-	`true`	-

Returns: array
Example:

complement([1, 2], [2, '33'], [2]) // [1, '33']

Types:

declare function complement<T = unknown>(...args: T[][]): T[]

contains

Whether the array contains the specified element

Since: 2.2.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
arr	array target	`array`	-	`true`	-
item	any array member	`any`	-	`true`	-

Returns: boolean
Example:

contains([1, 2], 2) // true
contains([1, 2], 3) // false

Types:

declare function contains(arr: any[], item: any): boolean

unique

Array de-duplication

Since: 2.2.1
Arguments:

Parameters	Description	Type	Optional	Required	Default
arr	array target	`array`	-	`true`	-

Returns: array
Example:

unique([1, 2, 2, '33']) // [1, 2, '33']

Types:

declare function unique<T = unknown>(arr: T[]): T[]

fillIPv6

ipv6 address completion

Since: 2.2.2
Arguments:

Parameters	Description	Type	Optional	Required	Default
ip	ip address	`string`	-	`true`	-

Returns: string
Example:

fillIPv6('2409:8005:800::2') // '2409:8005:0800:0000:0000:0000:0000:0002'
fillIPv6('2409:8005:800::1c') // '2409:8005:0800:0000:0000:0000:0000:001c'

Types:

declare function fillIPv6(ip: string): string

getProperty

Get array, object property values based on path string

v5.19.0 support defaultValue

Since: 2.2.4
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	target array, object	`array`/`object`	-	`true`	-
prop	query target, can pass function	`string`/`function`	-	`true`	-
defaultValue	default value	`any`	-	`false`	-

Returns: any
Example:

const target = {
  a: 1,
  b: [
    {
      c: 2,
      d: NaN
    }
  ]
}
getProperty(target, 'a') // 1
getProperty(target, 'd', 100) // 100
getProperty(target, 'b[0].c') // 2
getProperty(target, 'b[0].d', 100) // 100
getProperty(target, () => 'a') // 1

Types:

export declare function getProperty<T extends Record<string, any>>(
  target: T,
  prop:
    | string
    | {
        (): string
      },
  defaultValue?: any
): any

export declare function getProperty<T extends Array<any>>(
  target: T,
  prop:
    | string
    | {
        (): string
      },
  defaultValue?: any
): any

setProperty

Set array, object property values based on path string

Since: 2.7.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
target	target array, object	`array`/`object`	-	`true`	-
prop	set target, support function, 'a' \| 'a[1].c'	`string`/`function`	-	`true`	-
value	value	`any`	-	`true`	-

Returns: any
Example:

const target = {
  a: 1,
  b: [
    {
      c: 2
    }
  ]
}
setProperty(target, 'a', 2)
setProperty(target, 'b[0].c', 3)
setProperty(target, () => 'a', 100)

Types:

declare function setProperty(
  target: any,
  prop:
    | string
    | {
        (): string
      },
  value: any
): any

loadSource

load resources dynamically, support js, images, css links, css style strings

Since: 2.8.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	link to the resource, type must be passed when passing in styleString	`string`	-	`true`	-
options	parameters: attrs, props, force	`SourceOptions`	-	`false`	-

Returns: boolean | imageUrl
Example:

loadSource('/source/url', options)

Types:

import { ImageAttributes } from 'mount-image'
import { LinkAttributes } from 'mount-css'
import { ScriptAttributes } from 'mount-script'
import { StyleAttributes } from 'mount-style'

declare function loadSource(
  url: string,
  option: SourceFileType | SourceOptions
): Promise<boolean | string>

declare type SourceFileType = 'js' | 'img' | 'css' | 'style' | string

declare interface SourceOptions {
  type: SourceFileType
  attrs?: LinkAttributes | StyleAttributes | ScriptAttributes | ImageAttributes
  props?: LinkAttributes | StyleAttributes | ScriptAttributes | ImageAttributes
  force?: boolean
}

mountCss

dynamically load css link resources

Since: 2.8.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	resource url	`string`	-	`true`	-
options	parameters: attrs, props, force	`CssOptions`	-	`false`	-

Returns: boolean
Example:

mountCss('/source/url', options)

Types:

declare interface CssOptions {
  attrs?: LinkAttributes
  props?: LinkAttributes
  force?: boolean
}

declare interface HTMLLinkElementEX extends HTMLLinkElement {
  onreadystatechange?: any
  readyState?: 'loaded' | 'complete'
}

declare type LinkAttributes = Pick<
  HTMLLinkElement,
  | 'as'
  | 'charset'
  | 'crossOrigin'
  | 'disabled'
  | 'href'
  | 'hreflang'
  | 'imageSizes'
  | 'imageSrcset'
  | 'integrity'
  | 'media'
  | 'referrerPolicy'
  | 'rel'
  | 'rev'
  | 'target'
  | 'type'
>

declare function mountCss(src: string, option?: CssOptions): Promise<boolean>

mountImg

load image resource dynamically

Since: 2.8.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	resource url	`string`	-	`true`	-
options	parameters: attrs, props, force	`ImgOptions`	-	`false`	-

Returns: boolean | imageUrl
Example:

mountImg('/source/url', options)

Types:

declare interface HTMLImageElementEX extends HTMLImageElement {
  onreadystatechange?: any
  readyState?: 'loaded' | 'complete'
}

declare type ImageAttributes = Pick<
  HTMLImageElement,
  | 'align'
  | 'alt'
  | 'border'
  | 'crossOrigin'
  | 'decoding'
  | 'height'
  | 'hspace'
  | 'isMap'
  | 'loading'
  | 'longDesc'
  | 'lowsrc'
  | 'name'
  | 'referrerPolicy'
  | 'sizes'
  | 'src'
  | 'srcset'
  | 'useMap'
  | 'vspace'
  | 'width'
>

declare interface ImgOptions {
  attrs?: ImageAttributes
  props?: ImageAttributes
  force?: boolean
}

declare function mountImage(src: string, option?: ImgOptions): Promise<boolean | string>

mountJs

load js link resources dynamically

Since: 2.8.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	resource url	`string`	-	`true`	-
options	parameters: attrs, props, force	`JsOptions`	-	`false`	-

Returns: boolean
Example:

mountJs('/source/url', options)

Types:

declare interface HTMLScriptElementEX extends HTMLScriptElement {
  onreadystatechange?: any
  readyState?: 'loaded' | 'complete'
}

declare interface JsOptions {
  attrs?: ScriptAttributes
  props?: ScriptAttributes
  force?: boolean
}

declare function mountJs(src: string, option?: JsOptions): Promise<boolean>

declare type ScriptAttributes = Pick<
  HTMLScriptElement,
  | 'async'
  | 'charset'
  | 'crossOrigin'
  | 'defer'
  | 'event'
  | 'htmlFor'
  | 'integrity'
  | 'noModule'
  | 'referrerPolicy'
  | 'src'
  | 'text'
  | 'type'
>

mountStyle

load css styles dynamically

Since: 2.8.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
url	resource url	`string`	-	`true`	-
options	parameters: attrs, props, force	`StyleOptions`	-	`false`	-

Returns: boolean
Example:

mountStyle('/source/url', options)

Types:

declare function mountStyle(css: string, option?: StyleOptions): Promise<boolean>

declare type StyleAttributes = Pick<HTMLStyleElement, 'disabled' | 'media' | 'type'>

declare interface StyleOptions {
  attrs?: StyleAttributes
  props?: StyleAttributes
}

preloader

Image preloading

Since: 5.5.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
images	images url	`string` `array`	-	`true`	-

Returns: void
Example:

preloader('path/of/image')

preloader(['path/of/image'])

Types:

declare function preloader(images: string): HTMLImageElement

declare function preloader(images: string[]): Record<string, HTMLImageElement>

waiting

v5.8.1 Support throw on timeout

waiting for a while

Since: 5.5.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
milliseconds	waiting time (milliseconds)	`number`	-	`true`	-
throwOnTimeout	throw on timeout	`boolean`	-	`false`	`false`

Returns: Promise<void>
Example:

waiting(2000)

await waiting(2000, true)
// reject

Types:

declare function waiting(milliseconds: number, throwOnTimeout?: boolean): Promise<void>

awaitTo

Async await wrapper for easy error handling

v5.7.0 Extend awaitTo to support passing in multiple promises

Since: 5.2.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
promise	promise function	`Promise` `Promise[]`	-	`true`	-
...promises	Promise rest params	`Promise[]`	-	`false`	-

Returns: [Error, undefined] or [null, data | data[]]
Example:

import { awaitTo as to } from 'js-cool'

// 1. simple use
const [err, data] = await to(new Promise())
if (err) {
  // handle request error
}

// 2. Pass in multiple promises
const [err, data] = await to(promise1, promise2)
// or
const [err, data] = await to([promise1, promise2])

Types:

declare function awaitTo<T, E = Error>(promise: Promise<T>): Promise<[E, undefined] | [null, T]>

declare function awaitTo<P extends readonly unknown[] | [], E = Error>(
  promise: PromiseAll<P>
): Promise<[E, undefined] | [null, P]>

declare function awaitTo<T, P extends readonly unknown[] | [], E = Error>(
  promise: Promise<T>,
  ...promises: PromiseAll<P>
): Promise<[E, undefined] | [null, [T, ...P]]>

export declare type PromiseAll<P extends readonly unknown[] | []> = {
  -readonly [K in keyof P]: Promise<P[K]>
}

Blob arrayBuffer base64 file blobUrl

arrayBufferToBase64

arrayBuffer to base64

v5.19.1 remove default params of mime

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	arrayBuffer data	`ArrayBuffer`	-	`true`	-
mime	image mime	`String`	-	`false`	-

Returns: String
Example:

arrayBufferToBase64(arrayBuffer, 'image/png')
// data:image/png;base64,xxxxxxxxxxxx

arrayBufferToBase64(arrayBuffer)
// xxxxxxxxxxxx

Types:

declare function arrayBufferToBase64(input: ArrayBuffer, mime?: string): string

arrayBufferToBlob

arrayBuffer to blob

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	arrayBuffer data	`ArrayBuffer`	-	`true`	-
mime	image mime	`String`	-	`false`	`image/png`

Returns: Blob
Example:

arrayBufferToBlob(arrayBuffer, 'image/png')
// Blob

Types:

declare function arrayBufferToBlob(input: ArrayBuffer, mime?: string): Blob

base64ToArrayBuffer

base64 to arrayBuffer

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	base64 string	`String`	-	`true`	-

Returns: ArrayBuffer
Example:

base64ToArrayBuffer(base64)
// ArrayBuffer

Types:

declare function base64ToArrayBuffer(input: string): ArrayBuffer

base64ToBlob

base64 to blob

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	base64 string	`String`	-	`true`	-

Returns: Blob
Example:

base64ToBlob(base64)
// Blob

Types:

declare function base64ToBlob(input: string): Blob

base64ToFile

base64 to file

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	base64 string	`String`	-	`true`	-
fileName	file name	`String`	-	`true`	-

Returns: File
Example:

base64ToFile(base64, 'image.png')
// File

Types:

declare function base64ToFile(input: string, fileName: string): File

blobToArrayBuffer

blob to arrayBuffer

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	blob data	`Blob`	-	`true`	-

Returns: ArrayBuffer
Example:

blobToArrayBuffer(blob).then(data => {
  // ArrayBuffer
})

Types:

declare function blobToArrayBuffer(input: Blob): Promise<ArrayBuffer | null>

blobToBase64

blob to base64

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	blob data	`Blob`	-	`true`	-

Returns: String
Example:

blobToBase64(blob).then(data => {
  // data:image/png;base64,xxxxxxxxxxxx
})

Types:

declare function blobToBase64(input: Blob): Promise<string | null>

blobToUrl

blob to url

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	blob data	`Blob`	-	`true`	-

Returns: Object
Example:

blobToUrl(blob)
// blob:xxxxxxx

Types:

declare function blobToUrl(input: Blob): string

fileToBase64

file to base64

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	file data	`File`	-	`true`	-

Returns: String
Example:

fileToBase64(file).then(data => {
  // data:image/png;base64,xxxxxxxxxxxx
})

Types:

declare function fileToBase64(input: File): Promise<string | null>

svgToBlob

svg to blob

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	svg string	`String`	-	`true`	-

Returns: Blob
Example:

svgToBlob(svg)
// Blob

Types:

declare function svgToBlob(input: string): Blob

urlToBlob

url to blob

Since: 5.13.0
Arguments:

Parameters	Description	Type	Optional	Required	Default
input	url	`String`	-	`true`	-

Returns: Blob
Example:

urlToBlob(url).then(blob => {
  // Blob
})

Types:

declare function urlToBlob(input: string): Promise<Blob | null>

Support & Issues

Please open an issue here.

License

MIT

Keywords

FAQs

What is js-cool?

Is js-cool popular?

Is js-cool well maintained?

Package last updated on 17 Jan 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

js-cool

js-cool

Documentation • Change Log

Installation

Usage

ES6 module

Node.js require

Using unpkg CDN

API Reference

Global Parameters

client

pattern

Extras for String & Array & Object & Function

clearAttr

clearHtml

escape

unescape

getNumber

camel2Dash

dash2Camel

randomColor

randomNumber

randomNumbers

randomString

shuffle

fingerprint

getCHSLength

cutCHSString

upperFirst

Determine

isDigitals

isExitsFunction

isExitsVariable

isEqual

isWindow

isPlainObject

isDarkMode

isObject

isDate

isRegExp

isArray

isIterable

inBrowser

inNodeJs

isNumberBrowser

windowSize

getAppVersion

appVersion

getOsVersion

osVersion

browserVersion

compareVersion

parseUrlParam

spliceUrlParam

safeParse

safeStringify

getDirParam

getQueryParam

getQueryParams

getUrlParam

getUrlParams

localStorage & sessionStorage & Cookie

getCache

setCache

delCache

getSession

setSession

delSession

getCookie

getCookies

setCookie

delCookie

Base64 & UTF8

encodeBase64

decodeBase64

encodeUtf8

decodeUtf8

Events

stopBubble

stopDefault