es-toolkit 1.13.1 → 1.14.0-dev.399

package/dist/compat/array/size.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Returns the length of an array, string, or object.
+ *
+ * This function takes an array, string, or object and returns its length.
+ * For arrays and strings, it returns the number of elements or characters, respectively.
+ * For objects, it returns the number of enumerable properties.
+ *
+ * @template T - The type of the input value.
+ * @param {T[] | object | string | Map<unknown, T> | Set<T> | null | undefined } target - The value whose size is to be determined. It can be an array, string, or object.
+ * @returns {number} The size of the input value.
+ *
+ * @example
+ * const arr = [1, 2, 3];
+ * const arrSize = size(arr);
+ * // arrSize will be 3
+ *
+ * const str = 'hello';
+ * const strSize = size(str);
+ * // strSize will be 5
+ *
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const objSize = size(obj);
+ * // objSize will be 3
+ *
+ * const emptyArr = [];
+ * const emptyArrSize = size(emptyArr);
+ * // emptyArrSize will be 0
+ *
+ * const emptyStr = '';
+ * const emptyStrSize = size(emptyStr);
+ * // emptyStrSize will be 0
+ *
+ * const emptyObj = {};
+ * const emptyObjSize = size(emptyObj);
+ * // emptyObjSize will be 0
+ */
+declare function size<T>(target: T[] | object | string | Map<unknown, T> | Set<T> | null | undefined): number;
+
+export { size };

package/dist/compat/array/size.mjs

@@ -0,0 +1,13 @@
+import { isNil } from '../../predicate/isNil.mjs';
+
+function size(target) {
+    if (isNil(target)) {
+        return 0;
+    }
+    if (target instanceof Map || target instanceof Set) {
+        return target.size;
+    }
+    return Object.keys(target).length;
+}
+
+export { size };

package/dist/compat/array/zipObjectDeep.d.mts

@@ -0,0 +1,37 @@
+/**
+ * Creates a deeply nested object given arrays of paths and values.
+ *
+ * This function takes two arrays: one containing arrays of property paths, and the other containing corresponding values.
+ * It returns a new object where paths from the first array are used as key paths to set values, with corresponding elements from the second array as values.
+ * Paths can be dot-separated strings or arrays of property names.
+ *
+ * If the `keys` array is longer than the `values` array, the remaining keys will have `undefined` as their values.
+ *
+ * @template V - The type of elements in the array.
+ * @param {P[] | P[][]} keys - An array of property paths, each path can be a dot-separated string or an array of property names.
+ * @param {V[]} values - An array of values corresponding to the property paths.
+ * @returns {object} A new object composed of the given property paths and values.
+ *
+ * @example
+ * const paths = ['a.b.c', 'd.e.f'];
+ * const values = [1, 2];
+ * const result = zipObjectDeep(paths, values);
+ * // result will be { a: { b: { c: 1 } }, d: { e: { f: 2 } } }
+ *
+ * @example
+ * const paths = [['a', 'b', 'c'], ['d', 'e', 'f']];
+ * const values = [1, 2];
+ * const result = zipObjectDeep(paths, values);
+ * // result will be { a: { b: { c: 1 } }, d: { e: { f: 2 } } }
+ *
+ * @example
+ * const paths = ['a.b[0].c', 'a.b[1].d'];
+ * const values = [1, 2];
+ * const result = zipObjectDeep(paths, values);
+ * // result will be { 'a': { 'b': [{ 'c': 1 }, { 'd': 2 }] } }
+ */
+declare function zipObjectDeep<P extends PropertyKey, V>(keys: P[] | P[][], values: V[]): {
+    [K in P]: V;
+};
+
+export { zipObjectDeep };

package/dist/compat/array/zipObjectDeep.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Creates a deeply nested object given arrays of paths and values.
+ *
+ * This function takes two arrays: one containing arrays of property paths, and the other containing corresponding values.
+ * It returns a new object where paths from the first array are used as key paths to set values, with corresponding elements from the second array as values.
+ * Paths can be dot-separated strings or arrays of property names.
+ *
+ * If the `keys` array is longer than the `values` array, the remaining keys will have `undefined` as their values.
+ *
+ * @template V - The type of elements in the array.
+ * @param {P[] | P[][]} keys - An array of property paths, each path can be a dot-separated string or an array of property names.
+ * @param {V[]} values - An array of values corresponding to the property paths.
+ * @returns {object} A new object composed of the given property paths and values.
+ *
+ * @example
+ * const paths = ['a.b.c', 'd.e.f'];
+ * const values = [1, 2];
+ * const result = zipObjectDeep(paths, values);
+ * // result will be { a: { b: { c: 1 } }, d: { e: { f: 2 } } }
+ *
+ * @example
+ * const paths = [['a', 'b', 'c'], ['d', 'e', 'f']];
+ * const values = [1, 2];
+ * const result = zipObjectDeep(paths, values);
+ * // result will be { a: { b: { c: 1 } }, d: { e: { f: 2 } } }
+ *
+ * @example
+ * const paths = ['a.b[0].c', 'a.b[1].d'];
+ * const values = [1, 2];
+ * const result = zipObjectDeep(paths, values);
+ * // result will be { 'a': { 'b': [{ 'c': 1 }, { 'd': 2 }] } }
+ */
+declare function zipObjectDeep<P extends PropertyKey, V>(keys: P[] | P[][], values: V[]): {
+    [K in P]: V;
+};
+
+export { zipObjectDeep };

package/dist/compat/array/zipObjectDeep.mjs

@@ -0,0 +1,16 @@
+import { zip } from '../../array/zip.mjs';
+import { set } from '../object/set.mjs';
+
+function zipObjectDeep(keys, values) {
+    const result = {};
+    const zipped = zip(keys, values);
+    for (let i = 0; i < zipped.length; i++) {
+        const [key, value] = zipped[i];
+        if (key != null) {
+            set(result, key, value);
+        }
+    }
+    return result;
+}
+
+export { zipObjectDeep };

package/dist/compat/function/ary.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Creates a function that invokes func, with up to n arguments, ignoring any additional arguments.
+ *
+ * @template F - The type of the function.
+ * @param {F} func - The function to cap arguments for.
+ * @param {number} n - The arity cap.
+ * @returns {(...args: any[]) => ReturnType<F>} Returns the new capped function.
+ */
+declare function ary<F extends (...args: any[]) => any>(func: F, n?: number, guard?: unknown): ((...args: any[]) => ReturnType<F>);
+
+export { ary };

package/dist/compat/function/ary.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates a function that invokes func, with up to n arguments, ignoring any additional arguments.
+ *
+ * @template F - The type of the function.
+ * @param {F} func - The function to cap arguments for.
+ * @param {number} n - The arity cap.
+ * @returns {(...args: any[]) => ReturnType<F>} Returns the new capped function.
+ */
+declare function ary<F extends (...args: any[]) => any>(func: F, n?: number, guard?: unknown): ((...args: any[]) => ReturnType<F>);
+
+export { ary };

package/dist/compat/function/ary.mjs

@@ -0,0 +1,13 @@
+import { ary as ary$1 } from '../../function/ary.mjs';
+
+function ary(func, n = func.length, guard) {
+    if (guard) {
+        n = func.length;
+    }
+    if (Number.isNaN(n) || n < 0) {
+        n = 0;
+    }
+    return ary$1(func, n);
+}
+
+export { ary };

package/dist/compat/function/bind.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Creates a function that invokes `func` with the `this` binding of `thisArg` and `partials` prepended to the arguments it receives.
+ *
+ * The `bind.placeholder` value, which defaults to a `symbol`, may be used as a placeholder for partially applied arguments.
+ *
+ * Note: Unlike native `Function#bind`, this method doesn't set the `length` property of bound functions.
+ *
+ * @param {(...args: any[]) => any} func  The function to bind.
+ * @param {any} thisArg  The `this` binding of `func`.
+ * @param {any[]} partials  The arguments to be partially applied.
+ * @returns {(...args: any[]) => any} Returns the new bound function.
+ *
+ * @example
+ * function greet(greeting, punctuation) {
+ *   return greeting + ' ' + this.user + punctuation;
+ * }
+ * const object = { user: 'fred' };
+ * let bound = bind(greet, object, 'hi');
+ * bound('!');
+ * // => 'hi fred!'
+ *
+ * bound = bind(greet, object, bind.placeholder, '!');
+ * bound('hi');
+ * // => 'hi fred!'
+ */
+declare function bind<F extends Function>(func: F, thisObj?: unknown, ...partialArgs: any[]): F;
+declare namespace bind {
+    var placeholder: typeof bindPlaceholder;
+}
+declare const bindPlaceholder: unique symbol;
+
+export { bind };

package/dist/compat/function/bind.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Creates a function that invokes `func` with the `this` binding of `thisArg` and `partials` prepended to the arguments it receives.
+ *
+ * The `bind.placeholder` value, which defaults to a `symbol`, may be used as a placeholder for partially applied arguments.
+ *
+ * Note: Unlike native `Function#bind`, this method doesn't set the `length` property of bound functions.
+ *
+ * @param {(...args: any[]) => any} func  The function to bind.
+ * @param {any} thisArg  The `this` binding of `func`.
+ * @param {any[]} partials  The arguments to be partially applied.
+ * @returns {(...args: any[]) => any} Returns the new bound function.
+ *
+ * @example
+ * function greet(greeting, punctuation) {
+ *   return greeting + ' ' + this.user + punctuation;
+ * }
+ * const object = { user: 'fred' };
+ * let bound = bind(greet, object, 'hi');
+ * bound('!');
+ * // => 'hi fred!'
+ *
+ * bound = bind(greet, object, bind.placeholder, '!');
+ * bound('hi');
+ * // => 'hi fred!'
+ */
+declare function bind<F extends Function>(func: F, thisObj?: unknown, ...partialArgs: any[]): F;
+declare namespace bind {
+    var placeholder: typeof bindPlaceholder;
+}
+declare const bindPlaceholder: unique symbol;
+
+export { bind };

package/dist/compat/function/bind.mjs

@@ -0,0 +1,27 @@
+function bind(func, thisObj, ...partialArgs) {
+    const binded = function (...providedArgs) {
+        const args = [];
+        let startIndex = 0;
+        for (let i = 0; i < partialArgs.length; i++) {
+            const arg = partialArgs[i];
+            if (arg === bind.placeholder) {
+                args.push(providedArgs[startIndex++]);
+            }
+            else {
+                args.push(arg);
+            }
+        }
+        for (let i = startIndex; i < providedArgs.length; i++) {
+            args.push(providedArgs[i]);
+        }
+        if (this instanceof binded) {
+            return new func(...args);
+        }
+        return func.apply(thisObj, args);
+    };
+    return binded;
+}
+const bindPlaceholder = Symbol('bind.placeholder');
+bind.placeholder = bindPlaceholder;
+
+export { bind };