Skip to content

saqqdy/js-cool

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

328 Commits
.github
.github
 
 
.vscode
.vscode
 
 
build
build
 
 
scripts
scripts
 
 
src
src
 
 
.codacy.yml
.codacy.yml
 
 
.eslintignore
.eslintignore
 
 
.eslintrc.js
.eslintrc.js
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
.markdownlint.json
.markdownlint.json
 
 
.npmrc
.npmrc
 
 
.nvmrc
.nvmrc
 
 
.prettierignore
.prettierignore
 
 
.prettierrc.js
.prettierrc.js
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README-zh_CN.md
README-zh_CN.md
 
 
README.md
README.md
 
 
api-extractor.json
api-extractor.json
 
 
babel.config.js
babel.config.js
 
 
package.json
package.json
 
 
pnpm-lock.yaml
pnpm-lock.yaml
 
 
sonar-project.properties
sonar-project.properties
 
 
tsconfig.json
tsconfig.json
 
 
typedoc.js
typedoc.js
 
 

Repository files navigation

js-cool

Collection of common JavaScript / TypeScript utilities

NPM version Codacy Badge tree shaking typescript Test coverage npm download gzip License

Sonar

Documentation • Change Log

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

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

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:

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:

  1. For file formats that some browsers do not recognize. Enter the file URL in the address bar, window.location.href = URL, window.open(URL);
  2. using a tag download attribute (or js create a tag);
  3. browser-recognizable pdf, txt files, back-end compatible with handling attachment;
  4. 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

About

Collection of common JavaScript / TypeScript utilities

www.saqqdy.com/js-cool

Topics

library uuid csv tool cache random cookies localstorage fingerprint js-functions utilties osversion js-cool compareversion get-types await-to

Resources

Readme

License

MIT license
Activity

Stars

17 stars

Watchers

2 watching

Forks

2 forks
Report repository

Releases 77

v5.23.0 Latest
Nov 18, 2024
+ 76 releases

Sponsor this project

Packages

No packages published

Contributors 2

  •  
  •  

Languages