@modyqyw/utils

English | 简体中文

开箱即用的工具方法，适用于不同的 JavaScript / TypeScript 项目。要求 node >= 14.18。

安装

npm install @modyqyw/utils

API

base

• 如果你正在寻找一个关于合并 merge 的解决方案，请尝试 deepmerge、deepmerge-ts 或 ts-deepmerge。
• 如果你正在寻找一个关于克隆 clone 的解决方案，请尝试 deepmerge、deepmerge-ts、ts-deepmerge、clone 或 structuredClone。

getType

获取值的类型名称。

import { getType } from '@modyqyw/utils';

getType(null); // Null
getType(); // Undefined
getType(undefined); // Undefined
getType(true); // Boolean
getType(0); // Number
getType(0n); // BigInt
getType(''); // String
getType({}); // Object
getType([]); // Array

isString

判断一个值是否为 string。

import { isString } from '@modyqyw/utils';

isString(''); // true
isString(0); // false
isString(0n); // false
isString(true); // false
isString(undefined); // false
isString(null); // false
isString(Symbol()); // false
isString({}); // false
isString(() => {}); // false
isString([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isNumber

判断一个值是否为 number。

import { isNumber } from '@modyqyw/utils';

isNumber(''); // false
isNumber(0); // true
isNumber(0n); // false
isNumber(true); // false
isNumber(undefined); // false
isNumber(null); // false
isNumber(Symbol()); // false
isNumber({}); // false
isNumber(() => {}); // false
isNumber([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isBigInt

判断一个值是否为 bigint。

import { isBigInt } from '@modyqyw/utils';

isBigInt(''); // false
isBigInt(0); // false
isBigInt(0n); // true
isBigInt(true); // false
isBigInt(undefined); // false
isBigInt(null); // false
isBigInt(Symbol()); // false
isBigInt({}); // false
isBigInt(() => {}); // false
isBigInt([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isBoolean

判断一个值是否为 boolean。

import { isBoolean } from '@modyqyw/utils';

isBoolean(''); // false
isBoolean(0); // false
isBoolean(0n); // false
isBoolean(true); // true
isBoolean(undefined); // false
isBoolean(null); // false
isBoolean(Symbol()); // false
isBoolean({}); // false
isBoolean(() => {}); // false
isBoolean([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isUndefined

判断一个值是否为 undefined。

import { isUndefined } from '@modyqyw/utils';

isUndefined(''); // false
isUndefined(0); // false
isUndefined(0n); // false
isUndefined(true); // false
isUndefined(undefined); // true
isUndefined(null); // false
isUndefined(Symbol()); // false
isUndefined({}); // false
isUndefined(() => {}); // false
isUndefined([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isNull

判断一个值是否为 null。

import { isNull } from '@modyqyw/utils';

isNull(''); // false
isNull(0); // false
isNull(0n); // false
isNull(true); // false
isNull(undefined); // false
isNull(null); // true
isNull(Symbol()); // false
isNull({}); // false
isNull(() => {}); // false
isNull([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isNullish

判断一个值是否为 null 或 undefined。

import { isNullish } from '@modyqyw/utils';

isNullish(''); // false
isNullish(0); // false
isNullish(0n); // false
isNullish(true); // false
isNullish(undefined); // true
isNullish(null); // true
isNullish(Symbol()); // false
isNullish({}); // false
isNullish(() => {}); // false
isNullish([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isSymbol

判断一个值是否为 symbol。

import { isSymbol } from '@modyqyw/utils';

isSymbol(''); // false
isSymbol(0); // false
isSymbol(0n); // false
isSymbol(true); // false
isSymbol(undefined); // false
isSymbol(null); // false
isSymbol(Symbol()); // true
isSymbol({}); // false
isSymbol(() => {}); // false
isSymbol([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isObject

判断一个值是否为 object。

import { isObject } from '@modyqyw/utils';

isObject(''); // false
isObject(0); // false
isObject(0n); // false
isObject(true); // false
isObject(undefined); // false
isObject(null); // false
isObject(Symbol()); // false
isObject({}); // true
isObject(() => {}); // false
isObject([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isFunction

判断一个值是否为 function。

import { isFunction } from '@modyqyw/utils';

isFunction(''); // false
isFunction(0); // false
isFunction(0n); // false
isFunction(true); // false
isFunction(undefined); // false
isFunction(null); // false
isFunction(Symbol()); // false
isFunction({}); // false
isFunction(() => {}); // true
isFunction([]); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isArray

判断一个值是否为 array。

import { isArray } from '@modyqyw/utils';

isArray(''); // false
isArray(0); // false
isArray(0n); // false
isArray(true); // false
isArray(undefined); // false
isArray(null); // false
isArray(Symbol()); // false
isArray({}); // false
isArray(() => {}); // false
isArray([]); // true

你可能想要判断一个值是否为 array 且所有元素是否为 number，以下是一个例子。

import { isArray, isNumber } from '@modyqyw/utils';

isArray([1, 2, 3], isNumber); // true
isArray([1, 2, '3'], isNumber); // false

如果你有额外需求，比如 ix.xxx 和类型断言，请查看 @sindresorhus/is。

isBlob

判断一个值是否为 blob。

isFile

判断一个值是否为 file。

getTimestamp

获取毫秒级时间戳。

import { getTimestamp } from '@modyqyw/utils';

const timestamp = getTimestamp();

isEqual

直接使用 Object.is 来判断两个值是否相等。如果你需要深层比较，请使用 isDeepEqual。

import { isEqual } from '@modyqyw/utils';

isEqual(null, null); // true
isEqual(undefined, null); // false
isEqual(undefined, undefined); // true
isEqual(true, true); // true
isEqual(false, false); // true
isEqual(true, false); // true
isEqual(1, 2); // false
isEqual(1, 1); // true
isEqual({}, {}); // false
isEqual({ a: 1 }, { a: 1, b: 2 }); // false
isEqual({ a: 1 }, { a: 1 }); // false
isEqual({ a: 1, b: { c: true } }, { a: 1, b: { c: true } }); // false
isEqual({ a: 1, b: { c: true } }, { a: 1, b: { c: false } }); // false
isEqual([], []); // false
isEqual([1, 2, 3, { a: 1, b: { c: true } }], [1, 2, 3, { a: 1, b: { c: true } }]); // false
isEqual([1, 2, 3, { a: 1, b: { c: true } }], [1, 2, 3, { a: 1, b: { c: false } }]); // false

isDeepEqual

判断两个值是否相等。对于数组，递归地判断每个下标的值。对于对象，递归地判断每个键对应的值。其它情况使用 Object.is 来判断。

import { isDeepEqual } from '@modyqyw/utils';

isDeepEqual(null, null); // true
isDeepEqual(undefined, null); // false
isDeepEqual(undefined, undefined); // true
isDeepEqual(true, true); // true
isDeepEqual(false, false); // true
isDeepEqual(true, false); // true
isDeepEqual(1, 2); // false
isDeepEqual(1, 1); // true
isDeepEqual({}, {}); // true
isDeepEqual({ a: 1 }, { a: 1, b: 2 }); // false
isDeepEqual({ a: 1 }, { a: 1 }); // true
isDeepEqual({ a: 1, b: { c: true } }, { a: 1, b: { c: true } }); // true
isDeepEqual({ a: 1, b: { c: true } }, { a: 1, b: { c: false } }); // false
isDeepEqual([], []); // true
isDeepEqual([1, 2, 3, { a: 1, b: { c: true } }], [1, 2, 3, { a: 1, b: { c: true } }]); // true
isDeepEqual([1, 2, 3, { a: 1, b: { c: true } }], [1, 2, 3, { a: 1, b: { c: false } }]); // false

string

lowerCase

将字符串转换成小写。

import { lowerCase } from '@modyqyw/utils';

lowerCase(''); // ''
lowerCase('test'); // 'test'
lowerCase('TEST'); // 'test'
lowerCase('test string'); // 'test string'
lowerCase('TEST STRING'); // 'test string'

localeLowerCase

将字符串转换成本地小写。

import { localeLowerCase } from '@modyqyw/utils';

localeLowerCase('STRING', 'en-US'); // 'string'

lowerCaseFirst

将第一个字符转换成小写。

import { lowerCaseFirst } from '@modyqyw/utils';

lowerCaseFirst(''); // ''
lowerCaseFirst('test'); // 'test'
lowerCaseFirst('TEST'); // 'tEST'
lowerCaseFirst('test string'); // 'test string'
lowerCaseFirst('TEST STRING'); // 'tEST STRING'

upperCase

将字符串转换成大写。

import { upperCase } from '@modyqyw/utils';

upperCase(''); // ''
upperCase('test'); // 'TEST'
upperCase('TEST'); // 'TEST'
upperCase('test string'); // 'TEST STRING'
upperCase('TEST STRING'); // 'TEST STRING'

localeUpperCase

将字符串转换成本地大写。

import { localeLowerCase } from '@modyqyw/utils';

localeLowerCase('string', 'en-US'); // 'STRING'

upperCaseFirst

将第一个字符转换成大写。

import { lowerCaseFirst } from '@modyqyw/utils';

lowerCaseFirst(''); // ''
lowerCaseFirst('test'); // 'test'
lowerCaseFirst('TEST'); // 'tEST'
lowerCaseFirst('test string'); // 'test string'
lowerCaseFirst('TEST STRING'); // 'tEST STRING'

toString

将值转换成字符串。首先尝试 value.toString()，然后再尝试 Object#toString.call(value)。

import { toString } from '@modyqyw/utils';

toString(undefined); // '[object Undefined]'
toString(null); // '[object Null]'
toString(0); // '0'
toString(Symbol('test')); // 'Symbol(test)'
toString([1, 2, 3]); // '1,2,3'

array

arrayIncludes

和 Array#includes 一致，但拥有更好的类型。来源于 ts-extras。

toArray

将值转换成数组。

import { toArray } from '@modyqyw/utils';

toArray(); // []
toArray(undefined); // []
toArray(null); // []
toArray(1); // [1]
toArray('abc'); // ['abc']
toArray({ a: 1, b: 2 }); // [{ a: 1, b: 2 }]
toArray([1, 2]); // [1, 2]

difference

找到两个数组中不同的元素。内部默认使用 Array#includes 判断相等性，你也可以传入一个自定义方法。返回一个新数组。

import { difference, isDeepEqual } from '@modyqyw/utils';

difference([1, '2'], [1]); // ['2']
difference([1, '2', {}], [1, {}]); // ['2', {}]
difference([1, '2', { a: { b: 'c' } }], [1, { a: { b: 'c' } }]); // ['2', { a: { b: 'c' } }]
difference([1, '2', {}], [1, {}], isDeepEqual); // ['2']
difference([1, '2', { a: { b: 'c' } }], [1, { a: { b: 'c' } }], isDeepEqual); // ['2']

intersection

找到两个数组中相同的元素。内部默认使用 Array#includes 判断相等性，你也可以传入一个自定义方法。返回一个新数组。

import { intersection, isDeepEqual } from '@modyqyw/utils';

intersection([1, '2'], [1]); // [1]
intersection([1, '2', {}], [1, {}]); // [1]
intersection([1, '2', { a: { b: 'c' } }], [1, { a: { b: 'c' } }]); // [1]
intersection([1, '2', {}], [1, {}], isDeepEqual); // [1, {}]
intersection([1, '2', { a: { b: 'c' } }], [1, { a: { b: 'c' } }], isDeepEqual); // [1, { a: { b: 'c' } }]

uniq

数组去重。内部默认使用 Array#includes 判断相等性，你也可以传入一个自定义方法。返回一个新数组。

import { uniq, isDeepEqual } from '@modyqyw/utils';

uniq([1, '2', 2, 2, '2']); // [1, '2', 2]
uniq([1, '2', 2, 2, '2', {}, {}]); // [1, '2', 2, {}, {}]
uniq([1, '2', 2, 2, '2', {}, {}], isDeepEqual); // [1, '2', 2, {}]

union

找到两个数组所有不同元素。内部使用 uniq。返回一个新数组。

import { union, isDeepEqual } from '@modyqyw/utils';

union([1, '2'], [1, 3]); // [1, '2', 3]
union([1, '2', {}], [1, 3, {}]); // [1, '2', {}, 3, {}]
union([1, '2', { a: { b: 'c' } }], [1, 3, { a: { b: 'c' } }]); // [1, '2', { a: { b: 'c' } }, 3, { a: { b: 'c' } }])
union([1, '2', {}], [1, 3, {}], isDeepEqual); // [1, '2', {}, 3]
union([1, '2', { a: { b: 'c' } }], [1, 3, { a: { b: 'c' } }], isDeepEqual); // [1, '2', { a: { b: 'c' } }, 3]

range

创建一个从 start 到不包括 end 的数组。

start 默认设置为 0，你可以直接传入 end。

当 start < end 时，step 默认为 1，否则默认为 -1。

返回一个新数组。

import { range } from '@modyqyw/utils';

range(4); // [0, 1, 2, 3]
range(-4); // [0, -1, -2, -3]
range(1, 5); // [1, 2, 3, 4]
range(0, 20, 5); // [0, 5, 10, 15]
range(0, -4, -1); // [0, -1, -2, -3]
range(1, 4, 0); // [1, 1, 1]
range(0); // []

object

objectKeys

和 Object.keys 一致，但拥有更好的类型。来源于 ts-extras。

objectEntries

和 Object.entries 一致，但拥有更好的类型。来源于 ts-extras。

objectFromEntries

和 Object.fromEntries 一致，但拥有更好的类型。来源于 ts-extras。

set

setHas

和 Set#has 一致，但拥有更好的类型。来源于 ts-extras。

promise

如果你有额外需求，请查看 promise-fun。

sleep

休眠 💤，之后如果传递了 callback 就会调用它。

import { sleep } from '@modyqyw/utils';

await sleep(1000); // sleep 1s
await sleep(1000, () => {
  console.log('Hi.');
}); // sleep 1s, then log `Hi.`

function

throttle

创建一个节流函数，每 delay 毫秒最多只调用一次 callback。

import { throttle } from '@modyqyw/utils';

const throttled = throttle(fn, 1000);
throttled(); // called
throttled();
throttled();
throttled(); // called
setTimeout(throttled, 1200); // called

你可以在第三个参数中禁用 leading 或 trailing，默认为 { leading: true, trailing: true }。

import { throttle } from '@modyqyw/utils';

const throttled = throttle(fn, 1000, { trailing: false });
throttled(); // called
throttled();
throttled();
throttled();
setTimeout(throttled, 1200); // called

import { throttle } from '@modyqyw/utils';

const throttled = throttle(fn, 1000, { leading: false });
throttled();
throttled();
throttled();
throttled(); // called
setTimeout(throttled, 1200); // called

import { throttle } from '@modyqyw/utils';

const throttled = throttle(fn, 1000, { leading: false, trailing: false });
throttled();
throttled();
throttled();
throttled();
setTimeout(throttled, 1200);

使用 .abort() 中止下一次调用，传入 true 表示中止之后所有调用。

import { throttle } from '@modyqyw/utils';

const throttled = throttle(fn, 1000);
throttled(); // called
throttled();
throttled.abort(true);
throttled(); // called
throttled.abort();
throttled();
throttled();

你可以在 这里 了解更多节流和防抖的区别。

debounce

创建一个防抖函数，自上次调用以来过去了 delay 毫秒再调用 callback。

import { debounce } from '@modyqyw/utils';

const debounced = debounce(fn, 1000);
debounced();
debounced();
debounced();
debounced(); // called
setTimeout(debounced, 1200); // called

你可以在第三个参数中禁用 leading 或 trailing，默认为 { leading: false, trailing: true }。

import { debounce } from '@modyqyw/utils';

const debounced = debounce(fn, 1000, { leading: false, trailing: false });
debounced();
debounced();
debounced();
debounced();
setTimeout(debounced, 1200);

import { debounce } from '@modyqyw/utils';

const debounced = debounce(fn, 1000, { leading: true, trailing: true });
debounced(); // called
debounced();
debounced();
debounced(); // called
setTimeout(debounced, 1200); // called

import { debounce } from '@modyqyw/utils';

const debounced = debounce(fn, 1000, { leading: true, trailing: false });
debounced(); // called
debounced();
debounced();
debounced();
setTimeout(debounced, 1200); // called

使用 .abort() 中止下一次调用，传入 true 表示中止之后所有调用。

import { debounce } from '@modyqyw/utils';

const debounced = debounce(fn, 1000);
debounced();
debounced();
debounced.abort(true);
debounced(); // called
debounced.abort();
debounced();
debounced();

你可以在 这里 了解更多节流和防抖的区别。

pipe

执行从左到右的函数组合。

import { pipe } from '@modyqyw/utils';

const fn = pipe(
  (a: number, b: number) => a + b, // first do
  (a) => Math.pow(a, 2), // second do
  (a) => a * 3,
  (a) => a / 4,
  (a) => a - 2,
);
fn(1, 1); // 1

noop

空函数。

import { noop } from '@modyqyw/utils';

// nothing happen
noop();

types

如果你有额外需求，请查看 type-fest、ts-toolbelt 和 ts-essentials。

AnyRecord

type AnyRecord = Record<string, any>;

Falsy

type Falsy = false | 0 | 0n | '' | null | undefined;

MaybePromise

type MaybePromise<T> = T | Promise<T>;

MaybePromiseLike

type MaybePromiseLike<T> = T | PromiseLike<T>;

Promisable

type Promisable<T> = T | PromiseLike<T>;

Awaitable

type Awaitable<T> = T | PromiseLike<T>;

MaybeNull

type MaybeNull<T> = T | null;

Nullable

type Nullable<T> = T | null;

NonNullable

这个类型和 TypeScript 自带的 NonNullable 不一样。

type NonNullable<T> = Exclude<T, null>;

MaybeUndefined

type MaybeUndefined<T> = T | undefined;

Optional

type Optional<T> = T | undefined;

Undefinable

type Undefinable<T> = Optional<T>;

Nullish

type Nullish<T> = T | undefined | null;

NonNullish

这个类型和 TypeScript 自带的 NonNullable 一样。

type NonNullish<T> = Exclude<T, undefined | null>

MaybeArray

type MaybeArray<T> = T | Array<T>;

Arrayable

type Arrayable<T> = T | Array<T>;

ElementOf

type ElementOf<T> = T extends (infer E)[] ? E : never;

Fn

type Fn = () => void;

PromisifyFn

type PromisifyFn<T extends Fn> = () => Promise<ReturnType<T>>;

AnyFn

type AnyFn<T = any> = (...args: any[]) => T;

PromisifyAnyFn

type PromisifyAnyFn<T extends AnyFn> = (...args: Parameters<T>) => Promise<ReturnType<T>>;

致谢

灵感源自 @antfu/utils。

我已经查看并学习了这些库。非常感谢维护者们的付出！如果需要，请查看它们以了解更多信息。

• lodash
• ramda
• remeda
• fp-ts
• io-ts
• change-case
• promise-fun
• rxjs
• mlly
• pkg-types
• local-pkg
• type-fest
• ts-essentials
• ts-toolbelt
• throttle-debounce
• js-sdsl
• joi
• zod
• yup

赞助者们