js-cool
Version:
Collection of common JavaScript / TypeScript utilities
1,889 lines (1,308 loc) • 108 kB
Markdown
<div style="text-align: center;" align="center">
# js-cool
Collection of common JavaScript / TypeScript utilities
[![NPM version][npm-image]][npm-url]
[![Codacy Badge][codacy-image]][codacy-url]
[![tree shaking][tree-shaking-image]][tree-shaking-url]
![typescript][typescript-url]
[![Test coverage][codecov-image]][codecov-url]
[![npm download][download-image]][download-url]
[![gzip][gzip-image]][gzip-url]
[![License][license-image]][license-url]
[![Sonar][sonar-image]][sonar-url]
</div>
<div style="text-align: center; margin-bottom: 20px;" align="center">
### **[Documentation](https://www.saqqdy.com/js-cool)** • **[Change Log](./CHANGELOG.md)**
**Read this in other languages: English | [简体中文](./README-zh_CN.md)**
</div>
- [Installation](#installation)
- [Usage](#usage)
- [Es6 module](#es6-module)
- [Node.js require](#nodejs-require)
- [Using unpkg CDN](#using-unpkg-cdn)
- [API Reference](#api-reference)
- [Global Parameters](#global-parameters)
- [client](#client) - The client method returns a browser result object
- [pattern](#pattern) - Collection of common regular expressions
- [Extras for String & Array & Object & Function](#extras-for-string--array--object--function)
- [clearAttr](#clearattr) - Remove all attributes of HTML tags
- [clearHtml](#clearhtml) - Removing HTML tags
- [escape](#escape) - Escaping HTML Special Characters
- [unescape](#unescape) - Restore HTML Special Characters
- [getNumber](#getnumber) - Get the number in the string
- [camel2Dash](#camel2dash) - Converts humped strings to -spaced and all lowercase Dash pattern
- [dash2Camel](#dash2camel) - Converts -spaced and all lowercase Dash patterns to humped strings
- [randomColor](#randomcolor) - Generate random hexadecimal colors
- [randomNumber](#randomnumber) - Get a random number
- [randomNumbers](#randomnumbers) - Generate n random integers that sum to a fixed sum
- [randomString](#randomstring) - Get a random string
- [shuffle](#shuffle) - shuffling algorithm, Reordering arrays or strings
- [fingerprint](#fingerprint) - Generating Browser Fingerprints
- [getCHSLength](#getchslength) - Get the length of the string, Chinese counts as 2 characters
- [cutCHSString](#cutchsstring) - Intercept string, Chinese counts as 2 bytes
- [upperFirst](#upperfirst) - First letter capitalized
- [Determine](#determine)
- [isDigitals](#isdigitals) - Determine if a string is a number
- [isExitsFunction](#isexitsfunction) - Determine if a function is defined
- [isExitsVariable](#isexitsvariable) - Determine if a variable is defined
- [isEqual](#isequal) - Determine if 2 objects are equal
- [isWindow](#iswindow) - Determine if window object
- [isPlainObject](#isplainobject) - Determine if target is an plain object
- [isDarkMode](#isdarkmode) - Determine if dark color mode
- [isObject](#isobject) - Determine if target is an object
- [isDate](#isdate) - Determine if target is Date
- [isRegExp](#isregexp) - Determine if target is RegExp
- [isArray](#isarray) - Determine if it is an array
- [isIterable](#isiterable) - Determine if it is iterable
- [inBrowser](#inbrowser) - Determine if it is running on the browser side
- [inNodeJs](#innodejs) - Determine if it is running on node.js
- [isNumberBrowser](#isnumberbrowser) - Detect if the client is a 360 browser
- [windowSize](#windowsize) - Get the window size
- [getAppVersion](#getappversion) - Get the APP version number
- [appVersion](#appversion) - Get the app version number
- [getOsVersion](#getosversion) - Get the phone system version
- [osVersion](#osversion) - get the system version
- [browserVersion](#browserversion) - Get the browser name and version
- [compareVersion](#compareversion) - Version number size comparison, tag version: `rc` > `beta` > `alpha` > `other`
- [parseUrlParam](#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](#spliceurlparam) - Splice URL parameters (single layer only)
- [safeParse](#safeparse) - Secure parsing of JSON strings
- [safeStringify](#safestringify) - Secure stringify of JSON Object
- [getDirParam](#getdirparam) - Get the URL parameter in the form of a directory
- [getQueryParam](#getqueryparam) - Get a single query parameter (behind "#")
- [getQueryParams](#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](#geturlparam) - Get a single URL parameter (from the "location.search", before "#")
- [getUrlParams](#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](#localstorage--sessionstorage--cookie)
- [getCache](#getcache) - Get the cache, if the deposited is Object, the retrieved is also Object, no need to convert again
- [setCache](#setcache) - Set the cache, if the deposited is Object, the retrieved is also Object, no need to convert again
- [delCache](#delcache) - Delete localStorage
- [getSession](#getsession) - Get the session, if the deposited is Object, the retrieved is also Object, no need to convert again
- [setSession](#setsession) - Set the session, if the deposited is Object, the retrieved is also Object, no need to convert again
- [delSession](#delsession) - Delete sessionStorage
- [getCookie](#getcookie) - Get cookie by name
- [getCookies](#getcookies) - Get all cookies
- [setCookie](#setcookie) - Set cookie
- [delCookie](#delcookie) - Delete cookie
- [Base64 & UTF8](#base64--utf8)
- [encodeBase64](#encodebase64) - convert strings, numbers to base64
- [decodeBase64](#decodebase64) - base64 decoding
- [encodeUtf8](#encodeutf8) - convert strings, numbers to utf8
- [decodeUtf8](#decodeutf8) - utf8 decoding
- [Events](#events)
- [stopBubble](#stopbubble) - stop bubbling
- [stopDefault](#stopdefault) - stop default events
- [addEvent](#addevent) - event delegate, support multiple delegates
- [removeEvent](#removeevent) - removeEvent removes the event delegate created by addEvent
- [getScrollPosition](#getscrollposition) - Get slide to top and bottom return 'top' 'bottom', recommend using limit flow
- [Utilities](#utilities)
- [nextIndex](#nextindex) - return the next zIndex value
- [nextVersion](#nextversion) - return the next version, **Only version types with no more than 3 digits are supported**. (Follow the npm version rules)
- [punctualTimer](#punctualtimer) - punctual setInterval
- [promiseFactory](#promisefactory) - Convert an object to a promise like api
- [fixNumber](#fixnumber) - truncate a few decimal places, not 0 for shortage
- [mapTemplate](#maptemplate) - Replacing specific data in a template string, support `${xxxx}` `{{xxxx}}` and `{xxxx}`
- [extend](#extend) - deep copy & merge objects
- [clone](#clone) - deep copy (Buffer, Promise, Set, Map are not supported)
- [delay](#delay) - anti-dither throttling
- [getType](#gettype) - Get the target type
- [getFileType](#getfiletype) - Determine file type based on link suffix
- [sorter](#sorter) - Sorter factory function
- [sortPinyin](#sortpinyin) - Sort Chinese by Chinese phonetic alphabet
- [cleanData](#cleandata) - Data cleaning methods
- [download](#download) - Several ways of file downloading
- [searchObject](#searchobject) - tree object depth lookup
- [openUrl](#openurl) - Open link in new tab (file jump download if browser can't parse)
- [copy](#copy) - copy to clipboard
- [toThousands](#tothousands) - Digital thousandths division
- [all](#all) - return true if the provided predicate function returns true for all elements in a set, otherwise return false
- [any](#any) - Returns true if the provided predicate function returns true for at least one element of a set, false otherwise
- [uuid](#uuid) - generate uuid on browser side, use v4 method
- [CSVToArray](#csvtoarray) - Converts a comma-separated string of values (CSV) to a 2D array.
- [arrayToCSV](#arraytocsv) - Converts a two-dimensional array to a comma-separated string of values (CSV).
- [CSVToJSON](#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](#jsontocsv) - Converts an array of objects to a comma-separated value (CSV) string containing only the specified columns.
- [RGBToHex](#rgbtohex) - Converts RGB component values to color codes.
- [intersect](#intersect) - Find the intersection of multiple arrays
- [union](#union) - Find the concatenation of multiple arrays
- [minus](#minus) - Find the set of differences of multiple arrays that belong to A but not to B/C/D... of the elements of
- [complement](#complement) - Find the complement of multiple arrays
- [contains](#contains) - Whether the array contains the specified element
- [unique](#unique) - Array de-duplication
- [fillIPv6](#fillipv6) - ipv6 address completion
- [getProperty](#getproperty) - Get array, object property values based on path string
- [setProperty](#setproperty) - Set array, object property values based on path string
- [loadSource](#loadsource) - load resources dynamically, support js, images, css links, css style strings
- [mountCss](#mountcss) - dynamically load css link resources
- [mountImg](#mountimg) - load image resource dynamically
- [mountJs](#mountjs) - load js link resources dynamically
- [mountStyle](#mountstyle) - load css styles dynamically
- [preloader](#preloader) - Image preloading
- [waiting](#waiting) - waiting for a while
- [awaitTo](#awaitto) - Async await wrapper for easy error handling
- [Blob arrayBuffer base64 file blobUrl](#blob-arraybuffer-base64-file-bloburl)
- [arrayBufferToBase64](#arraybuffertobase64) - arrayBuffer to base64
- [arrayBufferToBlob](#arraybuffertoblob) - arrayBuffer to blob
- [base64ToArrayBuffer](#base64toarraybuffer) - base64 to arrayBuffer
- [base64ToBlob](#base64toblob) - base64 to blob
- [base64ToFile](#base64tofile) - base64 to file
- [blobToArrayBuffer](#blobtoarraybuffer) - blob to arrayBuffer
- [blobToBase64](#blobtobase64) - blob to base64
- [blobToUrl](#blobtourl) - blob to url
- [fileToBase64](#filetobase64) - file to base64
- [svgToBlob](#svgtoblob) - svg to blob
- [urlToBlob](#urltoblob) - url to blob
- [Support & Issues](#support--issues)
- [License](#license)
## Installation
```bash
# use pnpm
pnpm install js-cool
## use npm
npm install --save js-cool
```
## Usage
### ES6 module
```js
import { osVersion } from 'js-cool'
osVersion()
```
### Node.js require
```js
const { osVersion } = require('js-cool')
osVersion()
```
### Using unpkg CDN
```html
<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:
```ts
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:
```ts
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:
```ts
pattern.number.test('333') // true
```
- Types:
```ts
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:
```ts
clearAttr('<div id="testID">test</div>')
// '<div>test</div>'
```
- Types:
```ts
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:
```ts
clearHtml('<div>test<br />string</div>')
// 'teststring'
```
- Types:
```ts
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:
```ts
escape('<div>test<br />string</div>')
// '<div>test<br />string</div>'
```
- Types:
```ts
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:
```ts
unescape('<div>test<br />string</div>')
// '<div>test<br />string</div>'
```
- Types:
```ts
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:
```ts
getNumber('Chrome123.33')
// '123.33'
getNumber('234test.88')
// '234.88'
```
- Types:
```ts
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:
```ts
camel2Dash('jsCool') // js-cool
```
- Types:
```ts
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:
```ts
dash2Camel('js-cool') // jsCool
```
- Types:
```ts
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:
```ts
randomColor()
// #bf444b
randomColor(200)
// #d6e9d7
randomColor(200, 255)
// #d3f9e4
randomColor([0, 0, 0], [255, 255, 255])
// #e2f2f3
```
- Types:
```ts
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:
```ts
randomNumber() // 8
randomNumber(0.1, 0.9) // 0.8
```
- Types:
```ts
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:
```ts
randomNumbers()
// [8]
randomNumbers(4, 5)
// [1, 1, 2, 1]
randomNumbers(4, 5, false)
// [0, 1, 2, 2]
```
- Types:
```ts
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:
```ts
// 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:
```ts
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:
```ts
const str = 'abcde'
const arr = [1, 2, 3]
shuffle(str)
// cdbse
shuffle(arr)
// [3, 1, 2]
shuffle(arr, 2)
// [3, 2]
```
- Types:
```ts
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:
```ts
fingerprint('www.saqqdy.com') // wc7sWJJA8
```
- Types:
```ts
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:
```ts
getCHSLength('测试') // 2
```
- Types:
```ts
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:
```ts
cutCHSString('测试', 1) // 测
cutCHSString('测试', 1, true) // 测...
```
- Types:
```ts
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:
```ts
upperFirst('saqqdy') // Saqqdy
```
- Types:
```ts
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:
```ts
isDigitals('2.11') // true
isDigitals('2.3x') // false
```
- Types:
```ts
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:
```ts
isExitsFunction('test') // false
isExitsFunction('console.log') // true
```
- Types:
```ts
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:
```ts
isExitsVariable('test') // false
isExitsVariable('window') // true
```
- Types:
```ts
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:
```ts
isEqual({ a: 22, b: {} }, { b: {}, a: 22 })
// true
isEqual([1, 2], [2, 1])
// false
isEqual(NaN, NaN)
// true
```
- Types:
```ts
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:
```ts
isWindow({}) // false
isWindow(window) // true
```
- Types:
```ts
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:
```ts
isPlainObject({}) // true
isPlainObject(window) // false
```
- Types:
```ts
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:
```ts
isDarkMode() // false
```
- Types:
```ts
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:
```ts
isObject({}) // true
```
- Types:
```ts
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:
```ts
const now = new Date()
isDate(now)
// true
```
- Types:
```ts
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:
```ts
isRegExp(/\d/) // true
```
- Types:
```ts
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:
```ts
isArray([]) // true
```
- Types:
```ts
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:
```ts
isIterable([]) // true
```
- Types:
```ts
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:
```ts
function test() {
if (!inBrowser) return null
// ...
}
```
- Types:
```ts
declare const inBrowser: boolean
```
#### inNodeJs
Determine if it is running on node.js
- Since: `5.13.0`
- Arguments: `none`
- Returns: `boolean`
- Example:
```ts
if (inNodeJs) {
//
}
```
- Types:
```ts
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:
```ts
// '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:
```ts
declare function isNumberBrowser(userAgent?: string): boolean
```
#### windowSize
Get the window size
- Since: `1.0.1`
- Arguments: `none`
- Returns: `{ width, height }`
- Example:
```ts
windowSize()
// { width: 1280, height: 800 }
```
- Types:
```ts
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:
```ts
// 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:
```ts
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:
```ts
// 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:
```ts
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:
```ts
getOsVersion('iPhone')
// '13.2.3'
getOsVersion('iPhone', true)
// 'iPhone/13.2.3'
```
- Types:
```ts
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:
```ts
// 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:
```ts
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:
```ts
// 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:
```ts
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:
```ts
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:
```ts
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:
```ts
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:
```ts
declare function parseUrlParam(url: string, covert?: boolean): Record<string, unknown>
```
#### spliceUrlParam
Splice URL parameters (single layer only)
> v5.20.0 Breaking change: remove encodeURIComponent</br>
> 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:
```ts
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:
```ts
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:
```ts
safeParse('100')
// 100
safeParse('{"a":"undefined","b":"NaN","c":"Infinity","d":"9007199254740993"}')
// { b: NaN, c: Infinity, d: 9007199254740993n }
```
- Types:
```ts
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:
```ts
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:
```ts
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:
```ts
//
```
- Types:
```ts
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:
```ts
getQueryParam('key1')
// key1 => xxx
getQueryParam('key1', 'https://test.com?key1=100#/home?key1=200')
// key1 => 200
```
- Types:
```ts
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:
```ts
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:
```ts
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:
```ts
getUrlParam('key1')
// key1 => xxx
getUrlParam('key1', 'https://test.com?key1=100#/home?key1=200')
// key1 => 100
```
- Types:
```ts
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