js-cool v5.19.1

js-cool

Collection of common JavaScript / TypeScript utilities

Documentation • Change Log

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

• Installation
• Usage
  • Es6 module
  • Node.js require
  • Using unpkg CDN
• 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
    • 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

• 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
}

Extras for String & Array & Object & Function

clearAttr

Remove all attributes of HTML tags

• Since: 1.0.1

• Arguments:

• 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:

• 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:

• 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:

• Returns: string

• Example:

unescape('<div>test<br />string</div>')
// '<div>test<br />string</div>'

• Types:

declare function unescape(string: string): string

getNumber

Get the number in the string

• Since: 1.0.1

• Arguments:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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

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:

• 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:

• 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:

• 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:

• 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'
  version: string
}

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

browserVersion

Get the browser name and version

• Since: 5.2.0

• Arguments:

• 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: 'Windows' | 'MacOS' | 'Android' | 'iOS' | 'WindowsPhone' | 'Debian' | 'WebOS'
  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:

• 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:

• 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)

• Since: 5.3.0

• Arguments:

• Returns: string

• Example:

spliceUrlParam({ key1: '100', key2: 'true', key3: 'null', key4: 'undefined', key4: '测试' })
// ?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' }, true, false)
// key1=100&key2=true&key3=&key4=

• Types:

declare function spliceUrlParam(
  params: Record<string, unknown>,
  covert?: boolean,
  withQuestionsMark?: boolean
): string | null

safeParse

Secure parsing of JSON strings

support BigInt since v5.17.1

• Since: 5.16.0

• Arguments:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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

localStorage & sessionStorage & Cookie

getCache

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

• Since: 1.0.2

• Arguments:

• 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:

• 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:

• 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:

• 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:

• 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:

• Returns: void

• Example:

delSession('data')

• Types:

declare function delSession(name: string): void

getCookie

Get cookie by name

• Since: 1.0.2

• Arguments:

• 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:

• 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:

• 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:

• Returns: void

• Example:

encodeBase64('data')

• Types:

declare function encodeBase64(name: string): string

decodeBase64

base64 decoding

• Since: 1.0.1

• Arguments:

• Returns: void

• Example:

decodeBase64('data')

• Types:

declare function decodeBase64(name: string): string

encodeUtf8

convert strings, numbers to utf8

• Since: 1.0.1

• Arguments:

• Returns: void

• Example:

encodeUtf8('data')

• Types:

declare function encodeUtf8(name: string): string

decodeUtf8

utf8 decoding

• Since: 1.0.1

• Arguments:

• Returns: void

• Example:

decodeUtf8('data')

• Types:

declare function decodeUtf8(name: string): string

Events

stopBubble

stop bubbling

• Since: 1.0.2

• Arguments:

• Returns: boolean

• Example:

stopBubble(event)

• Types:

declare function stopBubble(e: Event): boolean

stopDefault

stop default events

• Since: 1.0.2

• Arguments:

• Returns: boolean

• Example:

stopDefault(event)

• Types:

declare function stopDefault(e: Event): boolean

addEvent

event delegate, support multiple delegates

• Since: 1.0.2

• Arguments:

• 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:

• 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:

• 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:

• 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

• Since: 5.18.0

• Arguments:

• Returns: void

• Example:

const printDate = () => console.log(new Date())
punctualTimer(printDate, 1000)

• Types:

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

promiseFactory

Convert an object to a promise like api

• Since: 5.10.0

• Arguments:

• 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: