zhiaiwan-utils 1.0.3

package/dist/esm/convert/toPairs.js

@@ -0,0 +1,21 @@
+/**
+ * 将 object 转为自身可枚举属性的 `[key, value]` 数组。
+ *
+ * @param object - 待转换的对象
+ * @returns 键值对数组
+ *
+ * @example
+ * ```ts
+ * toPairs({ a: 1, b: 2 });
+ * // => [['a', 1], ['b', 2]]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toPairs(object) {
+    if (object == null) {
+        return [];
+    }
+    return Object.keys(object).map((key) => [key, object[key]]);
+}

package/dist/esm/convert/toPairsIn.js

@@ -0,0 +1,29 @@
+/**
+ * 将 object 转为可枚举属性（含继承）的 `[key, value]` 数组。
+ *
+ * @param object - 待转换的对象
+ * @returns 键值对数组
+ *
+ * @example
+ * ```ts
+ * const parent = { a: 1 };
+ * const child = Object.create(parent);
+ * child.b = 2;
+ *
+ * toPairsIn(child);
+ * // => [['a', 1], ['b', 2]]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toPairsIn(object) {
+    if (object == null) {
+        return [];
+    }
+    const result = [];
+    for (const key in object) {
+        result.push([key, object[key]]);
+    }
+    return result;
+}

package/dist/esm/convert/toPath.js

@@ -0,0 +1,16 @@
+/**
+ * 将 path 转为键数组，支持 `'a.b[0].c'` 与数组路径。
+ *
+ * @param value - 属性路径
+ * @returns 键数组
+ *
+ * @example
+ * ```ts
+ * toPath('a.b[0].c');
+ * // => ['a', 'b', '0', 'c']
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export { default } from '../_internal/toPath';

package/dist/esm/convert/toPlainObject.js

@@ -0,0 +1,36 @@
+function keysIn(object) {
+    const result = [];
+    for (const key in object) {
+        result.push(key);
+    }
+    return result;
+}
+/**
+ * 将 value 转为普通对象，复制可枚举属性（含继承属性）。
+ *
+ * @param value - 待转换的值
+ * @returns 普通对象
+ *
+ * @example
+ * ```ts
+ * class Foo {
+ *   a = 1;
+ * }
+ * toPlainObject(new Foo());
+ * // => { a: 1 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toPlainObject(value) {
+    const result = {};
+    if (value == null || typeof value !== 'object') {
+        return result;
+    }
+    const keys = keysIn(value);
+    for (const key of keys) {
+        result[key] = value[key];
+    }
+    return result;
+}

package/dist/esm/convert/toSafeInteger.js

@@ -0,0 +1,28 @@
+import toInteger from './toInteger';
+const MIN_SAFE_INTEGER = Number.MIN_SAFE_INTEGER;
+const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER;
+/**
+ * 将 value 转为安全整数，超出范围时截断到边界值。
+ *
+ * @param value - 待转换的值
+ * @returns 安全整数
+ *
+ * @example
+ * ```ts
+ * toSafeInteger('3');
+ * // => 3
+ *
+ * toSafeInteger(Number.MAX_SAFE_INTEGER + 1);
+ * // => 9007199254740991
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toSafeInteger(value) {
+    const result = toInteger(value);
+    if (result >= MIN_SAFE_INTEGER && result <= MAX_SAFE_INTEGER) {
+        return result;
+    }
+    return result < 0 ? MIN_SAFE_INTEGER : MAX_SAFE_INTEGER;
+}

package/dist/esm/convert/toString.js

@@ -0,0 +1,31 @@
+/**
+ * 将 value 转为字符串；`null` / `undefined` 转为 `''`。
+ *
+ * @param value - 待转换的值
+ * @returns 字符串
+ *
+ * @example
+ * ```ts
+ * toString(null);
+ * // => ''
+ *
+ * toString(-0);
+ * // => '-0'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toString(value) {
+    if (value == null) {
+        return '';
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'symbol') {
+        return Symbol.prototype.toString.call(value);
+    }
+    const result = String(value);
+    return result === '0' && 1 / value === -Infinity ? '-0' : result;
+}

package/dist/esm/convert/toUpper.js

@@ -0,0 +1,19 @@
+import toString from './toString';
+/**
+ * 将 value 转为大写字符串。
+ *
+ * @param value - 待转换的值
+ * @returns 大写字符串
+ *
+ * @example
+ * ```ts
+ * toUpper('--Foo-Bar--');
+ * // => '--FOO-BAR--'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toUpper(value) {
+    return toString(value).toUpperCase();
+}

package/dist/esm/function/after.js

@@ -0,0 +1,29 @@
+/**
+ * 创建一个跳过前 `n - 1` 次调用的函数；从第 n 次起执行 func。
+ *
+ * @param n - 开始执行的调用序号（从 1 起计）
+ * @param func - 要延迟执行的函数
+ * @returns 包装后的新函数
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const delayed = after(3, () => ++count);
+ * delayed(); // => undefined
+ * delayed(); // => undefined
+ * delayed(); // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function after(n, func) {
+    let remaining = n;
+    let result;
+    return function (...args) {
+        if (--remaining < 1) {
+            result = func.apply(this, args);
+        }
+        return result;
+    };
+}

package/dist/esm/function/before.js

@@ -0,0 +1,29 @@
+/**
+ * 创建一个最多调用 func `n - 1` 次的函数；达到上限后返回最后一次调用结果。
+ *
+ * @param n - 调用次数上限（不含第 n 次实际执行）
+ * @param func - 要限制的函数
+ * @returns 限制后的新函数
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const limited = before(3, () => ++count);
+ * limited(); // => 1
+ * limited(); // => 2
+ * limited(); // => 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function before(n, func) {
+    let remaining = n;
+    let result;
+    return function (...args) {
+        if (--remaining > 0) {
+            result = func.apply(this, args);
+        }
+        return result;
+    };
+}

package/dist/esm/function/curry.js

@@ -0,0 +1,53 @@
+const FUNC_ERROR_TEXT = 'Expected a function';
+export const curryPlaceholder = {};
+function mergeArgs(previous, next) {
+    const result = [...previous];
+    let nextIndex = 0;
+    for (let index = 0; index < result.length; index++) {
+        if (result[index] === curryPlaceholder && nextIndex < next.length) {
+            result[index] = next[nextIndex++];
+        }
+    }
+    while (nextIndex < next.length) {
+        result.push(next[nextIndex++]);
+    }
+    return result;
+}
+function countProvided(args) {
+    return args.filter((arg) => arg !== curryPlaceholder).length;
+}
+/**
+ * 创建可柯里化的函数。
+ *
+ * @param func - 原函数
+ * @param arity - 参数个数，默认 func.length
+ * @returns 柯里化函数
+ *
+ * @example
+ * ```ts
+ * const curried = zhiaiwanUtils.curry((a: number, b: number, c: number) => [a, b, c]);
+ * curried(1)(2)(3);
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function curry(func, arity = func.length) {
+    if (typeof func !== 'function') {
+        throw new TypeError(FUNC_ERROR_TEXT);
+    }
+    function wrapper(...args) {
+        const merged = mergeArgs([], args);
+        if (countProvided(merged) >= arity) {
+            const finalArgs = merged.slice(0, arity);
+            return func(...finalArgs);
+        }
+        const next = (...nextArgs) => wrapper(...mergeArgs(merged, nextArgs));
+        next.placeholder = curryPlaceholder;
+        return next;
+    }
+    wrapper.placeholder = curryPlaceholder;
+    return wrapper;
+}
+curry.placeholder = curryPlaceholder;

package/dist/esm/function/debounce.js

@@ -0,0 +1,104 @@
+export default function debounce(func, wait = 0, options = {}) {
+    if (typeof func !== 'function') {
+        throw new TypeError('Expected a function');
+    }
+    let lastArgs;
+    let lastThis;
+    let maxWait = 0;
+    let result;
+    let timerId;
+    let lastCallTime;
+    let lastInvokeTime = 0;
+    let leading = false;
+    let maxing = false;
+    let trailing = true;
+    const normalizedWait = Number(wait) || 0;
+    if (options && typeof options === 'object') {
+        leading = !!options.leading;
+        maxing = 'maxWait' in options;
+        maxWait = maxing ? Math.max(Number(options.maxWait) || 0, normalizedWait) : 0;
+        trailing = 'trailing' in options ? !!options.trailing : trailing;
+    }
+    function invokeFunc(time) {
+        const args = lastArgs;
+        const thisArg = lastThis;
+        lastArgs = lastThis = undefined;
+        lastInvokeTime = time;
+        if (args) {
+            result = func.apply(thisArg, args);
+        }
+        return result;
+    }
+    function leadingEdge(time) {
+        lastInvokeTime = time;
+        timerId = setTimeout(timerExpired, normalizedWait);
+        return leading ? invokeFunc(time) : result;
+    }
+    function remainingWait(time) {
+        const timeSinceLastCall = time - (lastCallTime !== null && lastCallTime !== void 0 ? lastCallTime : 0);
+        const timeSinceLastInvoke = time - lastInvokeTime;
+        const timeWaiting = normalizedWait - timeSinceLastCall;
+        return maxing ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke) : timeWaiting;
+    }
+    function shouldInvoke(time) {
+        const timeSinceLastCall = time - (lastCallTime !== null && lastCallTime !== void 0 ? lastCallTime : 0);
+        const timeSinceLastInvoke = time - lastInvokeTime;
+        return (lastCallTime === undefined ||
+            timeSinceLastCall >= normalizedWait ||
+            timeSinceLastCall < 0 ||
+            (maxing && timeSinceLastInvoke >= maxWait));
+    }
+    function timerExpired() {
+        const time = Date.now();
+        if (shouldInvoke(time)) {
+            trailingEdge(time);
+        }
+        else {
+            timerId = setTimeout(timerExpired, remainingWait(time));
+        }
+    }
+    function trailingEdge(time) {
+        timerId = undefined;
+        if (trailing && lastArgs) {
+            return invokeFunc(time);
+        }
+        lastArgs = lastThis = undefined;
+        return result;
+    }
+    function cancel() {
+        if (timerId !== undefined) {
+            clearTimeout(timerId);
+        }
+        lastInvokeTime = 0;
+        lastArgs = lastCallTime = lastThis = timerId = undefined;
+    }
+    function flush() {
+        return timerId === undefined ? result : trailingEdge(Date.now());
+    }
+    function debounced(...args) {
+        const time = Date.now();
+        const isInvoking = shouldInvoke(time);
+        lastArgs = args;
+        // 延迟执行需保留调用方 this，与 Lodash debounce 行为一致
+        // eslint-disable-next-line @typescript-eslint/no-this-alias -- 异步 invoke 须缓存调用方 this
+        lastThis = this;
+        lastCallTime = time;
+        if (isInvoking) {
+            if (timerId === undefined) {
+                return leadingEdge(lastCallTime);
+            }
+            if (maxing) {
+                clearTimeout(timerId);
+                timerId = setTimeout(timerExpired, normalizedWait);
+                return invokeFunc(lastCallTime);
+            }
+        }
+        if (timerId === undefined) {
+            timerId = setTimeout(timerExpired, normalizedWait);
+        }
+        return result;
+    }
+    debounced.cancel = cancel;
+    debounced.flush = flush;
+    return debounced;
+}

package/dist/esm/function/flow.js

@@ -0,0 +1,49 @@
+const FUNC_ERROR_TEXT = 'Expected a function';
+function flattenFlowArgs(funcs) {
+    const result = [];
+    for (const item of funcs) {
+        if (Array.isArray(item)) {
+            result.push(...item);
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+function createFlow(fromRight) {
+    return (...funcs) => {
+        const pipeline = flattenFlowArgs(funcs);
+        if (fromRight) {
+            pipeline.reverse();
+        }
+        for (const func of pipeline) {
+            if (typeof func !== 'function') {
+                throw new TypeError(FUNC_ERROR_TEXT);
+            }
+        }
+        return function flowed(...args) {
+            let result = pipeline[0].apply(this, args);
+            for (let index = 1; index < pipeline.length; index++) {
+                result = pipeline[index].call(this, result);
+            }
+            return result;
+        };
+    };
+}
+/**
+ * 创建一个按顺序组合多个函数的复合函数。
+ *
+ * @param funcs - 待组合的函数（可传数组）
+ * @returns 复合函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.flow([(a: number) => a + 1, (a: number) => a * 2])(1);
+ * // => 4
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default createFlow(false);

package/dist/esm/function/flowRight.js

@@ -0,0 +1,43 @@
+const FUNC_ERROR_TEXT = 'Expected a function';
+function flattenFlowArgs(funcs) {
+    const result = [];
+    for (const item of funcs) {
+        if (Array.isArray(item)) {
+            result.push(...item);
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * 创建一个从右向左组合多个函数的复合函数。
+ *
+ * @param funcs - 待组合的函数（可传数组）
+ * @returns 复合函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.flowRight([(a: number) => a + 1, (a: number) => a * 2])(1);
+ * // => 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function flowRight(...funcs) {
+    const pipeline = flattenFlowArgs(funcs).reverse();
+    for (const func of pipeline) {
+        if (typeof func !== 'function') {
+            throw new TypeError(FUNC_ERROR_TEXT);
+        }
+    }
+    return function flowed(...args) {
+        let result = pipeline[0].apply(this, args);
+        for (let index = 1; index < pipeline.length; index++) {
+            result = pipeline[index].call(this, result);
+        }
+        return result;
+    };
+}

package/dist/esm/function/index.js

@@ -0,0 +1,11 @@
+export { default as once } from './once';
+export { default as debounce } from './debounce';
+export { default as throttle } from './throttle';
+export { default as before } from './before';
+export { default as after } from './after';
+export { default as memoize } from './memoize';
+export { default as partial, partialPlaceholder } from './partial';
+export { default as partialRight } from './partialRight';
+export { default as flow } from './flow';
+export { default as flowRight } from './flowRight';
+export { default as curry, curryPlaceholder } from './curry';

package/dist/esm/function/memoize.js

@@ -0,0 +1,20 @@
+import MapCache from '../_internal/MapCache';
+export default function memoize(func, resolver) {
+    if (typeof func !== 'function') {
+        throw new TypeError('Expected a function');
+    }
+    const Cache = memoize.Cache;
+    const cache = new Cache();
+    const memoized = function (...args) {
+        const key = resolver ? resolver.apply(this, args) : args[0];
+        if (cache.has(key)) {
+            return cache.get(key);
+        }
+        const result = func.apply(this, args);
+        cache.set(key, result);
+        return result;
+    };
+    memoized.cache = cache;
+    return memoized;
+}
+memoize.Cache = MapCache;

package/dist/esm/function/once.js

@@ -0,0 +1,28 @@
+/**
+ * 创建一个只能调用 func 一次的函数。重复调用返回首次调用的结果。
+ *
+ * @param func - 要限制的函数
+ * @returns 限制后的新函数
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const init = once(() => ++count);
+ * init(); // => 1
+ * init(); // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function once(func) {
+    let called = false;
+    let result;
+    return function (...args) {
+        if (!called) {
+            called = true;
+            result = func.apply(this, args);
+        }
+        return result;
+    };
+}

package/dist/esm/function/partial.js

@@ -0,0 +1,31 @@
+import { mergePartialArgs, partialPlaceholder } from '../_internal/composePartials';
+export { partialPlaceholder };
+/**
+ * 创建一个偏函数，将 partials 参数预置到 func 参数列表前部。
+ * 可用 `partial.placeholder` 占位，调用时再填入实参。
+ *
+ * @param func - 原函数
+ * @param partials - 预置参数
+ * @returns 偏函数
+ *
+ * @example
+ * ```ts
+ * const fn = (a: number, b: number, c: number) => [a, b, c];
+ * const preset = partial(fn, partial.placeholder, 2);
+ * preset(1, 3);
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function partial(func, ...partials) {
+    if (typeof func !== 'function') {
+        throw new TypeError('Expected a function');
+    }
+    return function (...args) {
+        const composed = mergePartialArgs(args, partials, 'left');
+        return func.apply(this, composed);
+    };
+}
+partial.placeholder = partialPlaceholder;

package/dist/esm/function/partialRight.js

@@ -0,0 +1,30 @@
+import { mergePartialArgs, partialPlaceholder } from '../_internal/composePartials';
+/**
+ * 创建一个偏函数，将 partials 参数预置到 func 参数列表尾部。
+ * 可用 `partialRight.placeholder` 占位，调用时再填入实参。
+ *
+ * @param func - 原函数
+ * @param partials - 预置参数
+ * @returns 偏函数
+ *
+ * @example
+ * ```ts
+ * const fn = (a: number, b: number, c: number) => [a, b, c];
+ * const preset = partialRight(fn, 2, partialRight.placeholder);
+ * preset(1, 3);
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function partialRight(func, ...partials) {
+    if (typeof func !== 'function') {
+        throw new TypeError('Expected a function');
+    }
+    return function (...args) {
+        const composed = mergePartialArgs(args, partials, 'right');
+        return func.apply(this, composed);
+    };
+}
+partialRight.placeholder = partialPlaceholder;

package/dist/esm/function/throttle.js

@@ -0,0 +1,14 @@
+import debounce from './debounce';
+export default function throttle(func, wait = 0, options = {}) {
+    if (typeof func !== 'function') {
+        throw new TypeError('Expected a function');
+    }
+    const leading = 'leading' in options ? !!options.leading : true;
+    const trailing = 'trailing' in options ? !!options.trailing : true;
+    const normalizedWait = Number(wait) || 0;
+    return debounce(func, normalizedWait, {
+        leading,
+        maxWait: normalizedWait,
+        trailing,
+    });
+}

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+export { version } from './version';
+export * from './array';
+export * from './object';
+export * from './string';
+export * from './convert';
+export * from './tree';
+export * from './util';
+export * from './verify';
+export * from './function';
+export * from './color';

package/dist/esm/object/assign.js

@@ -0,0 +1,21 @@
+import { assignSources } from '../_internal/assignSources';
+/**
+ * 将 sources 的自有可枚举属性浅合并到 object，后续来源覆盖先前值。
+ *
+ * @param object - 目标对象
+ * @param sources - 一个或多个源对象
+ * @returns 合并后的 object
+ *
+ * @example
+ * ```ts
+ * const obj = { a: 1 };
+ * zhiaiwanUtils.assign(obj, { b: 2 }, { b: 3, c: 4 });
+ * // => { a: 1, b: 3, c: 4 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function assign(object, ...sources) {
+    return assignSources(object, sources, false);
+}