es-toolkit 1.10.1 → 1.11.0-dev.261

package/dist/chunk-YFN6KOC4.mjs

@@ -0,0 +1,15 @@
+// src/array/fill.ts
+function fill(array, value, start = 0, end = array.length) {
+  const length = array.length;
+  const finalStart = Math.max(start >= 0 ? start : length + start, 0);
+  const finalEnd = Math.min(end >= 0 ? end : length + end, length);
+  for (let i = finalStart; i < finalEnd; i++) {
+    array[i] = value;
+  }
+  return array;
+}
+
+export {
+  fill
+};
+//# sourceMappingURL=chunk-YFN6KOC4.mjs.map

package/dist/chunk-YFN6KOC4.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/array/fill.ts"],"sourcesContent":["/**\n * Fills elements of an array with a specified value from the start position up to, but not including, the end position.\n *\n * This function mutates the original array and replaces its elements with the provided value, starting from the specified\n * start index up to the end index (non-inclusive). If the start or end indices are not provided, it defaults to filling the\n * entire array.\n *\n * @param {Array<T | U>} array - The array to fill.\n * @param {U} value - The value to fill the array with.\n * @param {number} [start=0] - The start position. Defaults to 0.\n * @param {number} [end=arr.length] - The end position. Defaults to the array's length.\n * @returns {Array<T | U>} The array with the filled values.\n *\n * @example\n * const array = [1, 2, 3];\n * const result = fill(array, 'a');\n * // => ['a', 'a', 'a']\n *\n * const result = fill(Array(3), 2);\n * // => [2, 2, 2]\n *\n * const result = fill([4, 6, 8, 10], '*', 1, 3);\n * // => [4, '*', '*', 10]\n *\n * const result = fill(array, '*', -2, -1);\n * // => [1, '*', 3]\n */\nexport function fill<T>(array: unknown[], value: T): T[];\nexport function fill<T, U>(array: Array<T | U>, value: U, start: number): Array<T | U>;\nexport function fill<T, U>(array: Array<T | U>, value: U, start: number, end: number): Array<T | U>;\nexport function fill<T, U>(array: Array<T | U>, value: U, start = 0, end = array.length): Array<T | U> {\n  const length = array.length;\n  const finalStart = Math.max(start >= 0 ? start : length + start, 0);\n  const finalEnd = Math.min(end >= 0 ? end : length + end, length);\n\n  for (let i = finalStart; i < finalEnd; i++) {\n    array[i] = value;\n  }\n\n  return array;\n}\n"],"mappings":";AA8BO,SAAS,KAAW,OAAqB,OAAU,QAAQ,GAAG,MAAM,MAAM,QAAsB;AACrG,QAAM,SAAS,MAAM;AACrB,QAAM,aAAa,KAAK,IAAI,SAAS,IAAI,QAAQ,SAAS,OAAO,CAAC;AAClE,QAAM,WAAW,KAAK,IAAI,OAAO,IAAI,MAAM,SAAS,KAAK,MAAM;AAE/D,WAAS,IAAI,YAAY,IAAI,UAAU,KAAK;AAC1C,UAAM,CAAC,IAAI;AAAA,EACb;AAEA,SAAO;AACT;","names":[]}

package/dist/compat/index.d.mts

@@ -8,6 +8,7 @@ export { dropRight } from '../array/dropRight.mjs';
 export { dropRightWhile } from '../array/dropRightWhile.mjs';
 export { dropWhile } from '../array/dropWhile.mjs';
 export { fill } from '../array/fill.mjs';
+export { flatMap } from '../array/flatMap.mjs';
 export { flatten } from '../array/flatten.mjs';
 export { flattenDeep } from '../array/flattenDeep.mjs';
 export { forEachRight } from '../array/forEachRight.mjs';
@@ -48,6 +49,7 @@ export { toFilled } from '../array/toFilled.mjs';
 export { last } from '../array/last.mjs';
 export { initial } from '../array/initial.mjs';
 export { AbortError } from '../error/AbortError.mjs';
+export { TimeoutError } from '../error/TimeoutError.mjs';
 export { debounce } from '../function/debounce.mjs';
 export { noop } from '../function/noop.mjs';
 export { once } from '../function/once.mjs';
@@ -75,10 +77,12 @@ export { isNotNil } from '../predicate/isNotNil.mjs';
 export { isNull } from '../predicate/isNull.mjs';
 export { isUndefined } from '../predicate/isUndefined.mjs';
 export { delay } from '../promise/delay.mjs';
+export { withTimeout } from '../promise/withTimeout.mjs';
 export { camelCase } from '../string/camelCase.mjs';
 export { snakeCase } from '../string/snakeCase.mjs';
 export { kebabCase } from '../string/kebabCase.mjs';
 export { lowerCase } from '../string/lowerCase.mjs';
+export { startCase } from '../string/startCase.mjs';
 export { capitalize } from '../string/capitalize.mjs';
 
 /**
@@ -106,4 +110,359 @@ export { capitalize } from '../string/capitalize.mjs';
  */
 declare function chunk<T>(arr: readonly T[], size?: number): T[][];
 
-export { chunk };
+/**
+ * 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 {string[] | string[][]} 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 string | number | symbol, V>(keys: P[], values: V[]): {
+    [K in P]: V;
+};
+
+/**
+ * See the definition of `@types/lodash`.
+ */
+type GetIndexedField<T, K> = K extends keyof T ? T[K] : K extends `${number}` ? 'length' extends keyof T ? number extends T['length'] ? number extends keyof T ? T[number] : undefined : undefined : undefined : undefined;
+type FieldWithPossiblyUndefined<T, Key> = Get<Exclude<T, undefined>, Key> | Extract<T, undefined>;
+type IndexedFieldWithPossiblyUndefined<T, Key> = GetIndexedField<Exclude<T, undefined>, Key> | Extract<T, undefined>;
+type Get<T, P> = P extends `${infer Left}.${infer Right}` ? Left extends keyof Exclude<T, undefined> ? FieldWithPossiblyUndefined<Exclude<T, undefined>[Left], Right> | Extract<T, undefined> : Left extends `${infer FieldKey}[${infer IndexKey}]` ? FieldKey extends keyof T ? FieldWithPossiblyUndefined<IndexedFieldWithPossiblyUndefined<T[FieldKey], IndexKey>, Right> : undefined : undefined : P extends keyof T ? T[P] : P extends `${infer FieldKey}[${infer IndexKey}]` ? FieldKey extends keyof T ? IndexedFieldWithPossiblyUndefined<T[FieldKey], IndexKey> : undefined : IndexedFieldWithPossiblyUndefined<T, P>;
+
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K - The type of the key in the object.
+ * @template D - The type of the default value.
+ *
+ * @param {T} object - The object to query.
+ * @param {K | [K]} path - The path of the property to get.
+ * @returns {T[K]} - Returns the resolved value.
+ */
+declare function get<T extends object, K extends keyof T>(object: T, path: K | [K]): T[K];
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K - The type of the key in the object.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {K | [K]} path - The path of the property to get.
+ * @returns {T[K] | undefined} - Returns the resolved value.
+ */
+declare function get<T extends object, K extends keyof T>(object: T | null | undefined, path: K | [K]): T[K] | undefined;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K - The type of the key in the object.
+ * @template D - The type of the default value.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {K | [K]} path - The path of the property to get.
+ * @param {D} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {Exclude<T[K], undefined> | D} - Returns the resolved value.
+ */
+declare function get<T extends object, K extends keyof T, D>(object: T | null | undefined, path: K | [K], defaultValue: D): Exclude<T[K], undefined> | D;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ *
+ * @param {T} object - The object to query.
+ * @param {[K1, K2]} path - The path of the property to get.
+ * @returns {T[K1][K2]} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1]>(object: T, path: [K1, K2]): T[K1][K2];
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {[K1, K2]} path - The path of the property to get.
+ * @returns {T[K1][K2] | undefined} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1]>(object: T | null | undefined, path: [K1, K2]): T[K1][K2] | undefined;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ * @template D - The type of the default value.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {[K1, K2]} path - The path of the property to get.
+ * @param {D} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {Exclude<T[K1][K2], undefined> | D} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1], D>(object: T | null | undefined, path: [K1, K2], defaultValue: D): Exclude<T[K1][K2], undefined> | D;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ * @template K3 - The type of the third key in the object.
+ *
+ * @param {T} object - The object to query.
+ * @param {[K1, K2, K3]} path - The path of the property to get.
+ * @returns {T[K1][K2][K3]} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2]>(object: T, path: [K1, K2, K3]): T[K1][K2][K3];
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ * @template K3 - The type of the third key in the object.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {[K1, K2, K3]} path - The path of the property to get.
+ * @returns {T[K1][K2][K3] | undefined} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2]>(object: T | null | undefined, path: [K1, K2, K3]): T[K1][K2][K3] | undefined;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ * @template K3 - The type of the third key in the object.
+ * @template D - The type of the default value.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {[K1, K2, K3]} path - The path of the property to get.
+ * @param {D} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {Exclude<T[K1][K2][K3], undefined> | D} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2], D>(object: T | null | undefined, path: [K1, K2, K3], defaultValue: D): Exclude<T[K1][K2][K3], undefined> | D;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ * @template K3 - The type of the third key in the object.
+ * @template K4 - The type of the fourth key in the object.
+ *
+ * @param {T} object - The object to query.
+ * @param {[K1, K2, K3, K4]} path - The path of the property to get.
+ * @returns {T[K1][K2][K3][K4]} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2], K4 extends keyof T[K1][K2][K3]>(object: T, path: [K1, K2, K3, K4]): T[K1][K2][K3][K4];
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ * @template K3 - The type of the third key in the object.
+ * @template K4 - The type of the fourth key in the object.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {[K1, K2, K3, K4]} path - The path of the property to get.
+ * @returns {T[K1][K2][K3][K4] | undefined} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2], K4 extends keyof T[K1][K2][K3]>(object: T | null | undefined, path: [K1, K2, K3, K4]): T[K1][K2][K3][K4] | undefined;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template K1 - The type of the first key in the object.
+ * @template K2 - The type of the second key in the object.
+ * @template K3 - The type of the third key in the object.
+ * @template K4 - The type of the fourth key in the object.
+ * @template D - The type of the default value.
+ *
+ * @param {T | null | undefined} object - The object to query.
+ * @param {[K1, K2, K3, K4]} path - The path of the property to get.
+ * @param {D} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {Exclude<T[K1][K2][K3][K4], undefined> | D} - Returns the resolved value.
+ */
+declare function get<T extends object, K1 extends keyof T, K2 extends keyof T[K1], K3 extends keyof T[K1][K2], K4 extends keyof T[K1][K2][K3], D>(object: T | null | undefined, path: [K1, K2, K3, K4], defaultValue: D): Exclude<T[K1][K2][K3][K4], undefined> | D;
+/**
+ * Retrieves the value at a given path from an object with numeric keys. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the value.
+ *
+ * @param {Record<number, T>} object - The object to query.
+ * @param {number} path - The path of the property to get.
+ * @returns {T} - Returns the resolved value.
+ */
+declare function get<T>(object: Record<number, T>, path: number): T;
+/**
+ * Retrieves the value at a given path from an object with numeric keys. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the value.
+ *
+ * @param {Record<number, T> | null | undefined} object - The object to query.
+ * @param {number} path - The path of the property to get.
+ * @returns {T | undefined} - Returns the resolved value.
+ */
+declare function get<T>(object: Record<number, T> | null | undefined, path: number): T | undefined;
+/**
+ * Retrieves the value at a given path from an object with numeric keys. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the value.
+ * @template D - The type of the default value.
+ *
+ * @param {Record<number, T> | null | undefined} object - The object to query.
+ * @param {number} path - The path of the property to get.
+ * @param {D} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {T | D} - Returns the resolved value.
+ */
+declare function get<T, D>(object: Record<number, T> | null | undefined, path: number, defaultValue: D): T | D;
+/**
+ * Retrieves the value at a given path from a null or undefined object, returning the default value.
+ *
+ * @template D - The type of the default value.
+ *
+ * @param {null | undefined} object - The object to query.
+ * @param {PropertyKey} path - The path of the property to get.
+ * @param {D} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {D} - Returns the default value.
+ */
+declare function get<D>(object: null | undefined, path: PropertyKey, defaultValue: D): D;
+/**
+ * Retrieves the value at a given path from a null or undefined object, returning undefined.
+ *
+ * @param {null | undefined} object - The object to query.
+ * @param {PropertyKey} path - The path of the property to get.
+ * @returns {undefined} - Returns undefined.
+ */
+declare function get(object: null | undefined, path: PropertyKey): undefined;
+/**
+ * Retrieves the value at a given path from a string-keyed object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template P - The type of the path.
+ *
+ * @param {T} data - The object to query.
+ * @param {P} path - The path of the property to get.
+ * @returns {string extends P ? any : Get<T, P>} - Returns the resolved value.
+ */
+declare function get<T, P extends string>(data: T, path: P): string extends P ? any : Get<T, P>;
+/**
+ * Retrieves the value at a given path from a string-keyed object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @template T - The type of the object.
+ * @template P - The type of the path.
+ * @template D - The type of the default value.
+ *
+ * @param {T} data - The object to query.
+ * @param {P} path - The path of the property to get.
+ * @param {D} defaultValue - The value returned if the resolved value is undefined.
+ * @returns {Exclude<Get<T, P>, null | undefined> | D} - Returns the resolved value.
+ */
+declare function get<T, P extends string, D = Get<T, P>>(data: T, path: P, defaultValue: D): Exclude<Get<T, P>, null | undefined> | D;
+/**
+ * Retrieves the value at a given path from an object. If the resolved value is undefined, the defaultValue is returned instead.
+ *
+ * @param {unknown} object - The object to query.
+ * @param {PropertyKey | readonly PropertyKey[]} path - The path of the property to get.
+ * @param {unknown} [defaultValue] - The value returned if the resolved value is undefined.
+ * @returns {any} - Returns the resolved value.
+ */
+declare function get(object: unknown, path: PropertyKey | readonly PropertyKey[], defaultValue?: unknown): any;
+
+/**
+ * Sets the value at the specified path of the given object. If any part of the path does not exist, it will be created.
+ *
+ * @template T - The type of the object.
+ * @param {Settable} obj - The object to modify.
+ * @param {Path} path - The path of the property to set.
+ * @param {any} value - The value to set.
+ * @returns {T} - The modified object.
+ *
+ * @example
+ * // Set a value in a nested object
+ * const obj = { a: { b: { c: 3 } } };
+ * set(obj, 'a.b.c', 4);
+ * console.log(obj.a.b.c); // 4
+ *
+ * @example
+ * // Set a value in an array
+ * const arr = [1, 2, 3];
+ * set(arr, 1, 4);
+ * console.log(arr[1]); // 4
+ *
+ * @example
+ * // Create non-existent path and set value
+ * const obj = {};
+ * set(obj, 'a.b.c', 4);
+ * console.log(obj); // { a: { b: { c: 4 } } }
+ */
+declare function set<T>(obj: object, path: PropertyKey | readonly PropertyKey[], value: unknown): T;
+
+/**
+ * Checks if a string contains another string at the beginning of the string.
+ *
+ * Checks if one string startsWith another string. Optional position parameter to start searching from a certain index.
+ *
+ * @param {string} str - The string that might contain the target string.
+ * @param {string} target - The string to search for.
+ * @param {number} position - An optional offset to start searching in the str string
+ * @returns {boolean} - True if the str string starts with the target string.
+ *
+ * @example
+ * const isPrefix = startsWith('fooBar', 'foo') // returns true
+ * const isPrefix = startsWith('fooBar', 'bar') // returns false
+ * const isPrefix = startsWith('fooBar', 'abc') // returns false
+ * const isPrefix = startsWith('fooBar', 'Bar', 2) // returns true
+ * const isPrefix = startsWith('fooBar', 'Bar', 5) // returns false
+ */
+declare const startsWith: (str: string, target: string, position?: number) => boolean;
+
+/**
+ * Checks if a string contains another string at the end of the string.
+ *
+ * Checks if one string endsWith another string. Optional position parameter to offset searching before a certain index.
+ *
+ * @param {string} str - The string that might contain the target string.
+ * @param {string} target - The string to search for.
+ * @param {number} position - An optional position from the start to search up to this index
+ * @returns {boolean} - True if the str string ends with the target string.
+ *
+ * @example
+ * const isPrefix = endsWith('fooBar', 'foo') // returns true
+ * const isPrefix = endsWith('fooBar', 'bar') // returns false
+ * const isPrefix = endsWith('fooBar', 'abc') // returns false
+ * const isPrefix = endsWith('fooBar', 'foo', 3) // returns true
+ * const isPrefix = endsWith('fooBar', 'abc', 5) // returns false
+ */
+declare const endsWith: (str: string, target: string, position?: number) => boolean;
+
+export { chunk, endsWith, get, set, startsWith, zipObjectDeep };