reslib 1.0.0

package/build/utils/object.d.ts

@@ -0,0 +1,567 @@
+import { Primitive } from '../types';
+/**
+ * Determines whether a value is a plain object (POJO - Plain Old JavaScript Object).
+ *
+ * A plain object is an object created by the Object constructor or one with a null prototype.
+ * This function performs comprehensive checks to distinguish plain objects from other object types
+ * like arrays, dates, DOM elements, regular expressions, class instances, and functions.
+ * It also handles cross-frame compatibility where objects might be created in different execution contexts.
+ *
+ * @template T - The type of the value being checked
+ * @param {T} obj - The value to test for being a plain object
+ *
+ * @returns {obj is (T extends (Record<any, any> | object) ? T : T extends string | undefined | null | boolean | Array<any> ? never : any)}
+ * Type predicate that narrows the type to a plain object if the check passes, or never for non-object types
+ *
+ * @example
+ * ```typescript
+ * // Basic plain object detection
+ * const plainObj = { name: "John", age: 30 };
+ * console.log(isObj(plainObj)); // true
+ *
+ * // Object created with Object.create(null)
+ * const nullProtoObj = Object.create(null);
+ * nullProtoObj.prop = "value";
+ * console.log(isObj(nullProtoObj)); // true
+ *
+ * // Arrays are not plain objects
+ * const array = [1, 2, 3];
+ * console.log(isObj(array)); // false
+ *
+ * // Dates are not plain objects
+ * const date = new Date();
+ * console.log(isObj(date)); // false
+ *
+ * // Regular expressions are not plain objects
+ * const regex = /pattern/;
+ * console.log(isObj(regex)); // false
+ *
+ * // Class instances are not plain objects
+ * class MyClass {
+ *   constructor(public value: string) {}
+ * }
+ * const instance = new MyClass("test");
+ * console.log(isObj(instance)); // false
+ *
+ * // Functions are not plain objects
+ * const func = () => {};
+ * console.log(isObj(func)); // false
+ *
+ * // Primitives are not plain objects
+ * console.log(isObj("string")); // false
+ * console.log(isObj(42)); // false
+ * console.log(isObj(true)); // false
+ * console.log(isObj(null)); // false
+ * console.log(isObj(undefined)); // false
+ *
+ * // DOM elements are not plain objects (in browser environment)
+ * const element = document.createElement('div');
+ * console.log(isObj(element)); // false
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Type narrowing with TypeScript
+ * function processValue<T>(value: T): void {
+ *   if (isObj(value)) {
+ *     // TypeScript now knows 'value' is a plain object
+ *     // Safe to access object properties
+ *     Object.keys(value).forEach(key => {
+ *       console.log(`${key}: ${value[key]}`);
+ *     });
+ *   } else {
+ *     // Handle non-object values
+ *     console.log("Not a plain object:", value);
+ *   }
+ * }
+ *
+ * // Cross-frame compatibility example
+ * // Works even when objects are created in different iframes
+ * const iframe = document.createElement('iframe');
+ * document.body.appendChild(iframe);
+ * const iframeWindow = iframe.contentWindow;
+ * const crossFrameObj = new iframeWindow.Object();
+ * crossFrameObj.prop = "value";
+ * console.log(isObj(crossFrameObj)); // true (handles cross-frame objects)
+ * ```
+ *
+ * @remarks
+ * This function is particularly useful for:
+ * - Object serialization/deserialization logic
+ * - Deep cloning or merging operations where you need to distinguish plain objects
+ * - API response validation where you expect plain data objects
+ * - Library functions that need to handle various object types differently
+ * - Cross-frame scenarios in browser environments
+ *
+ * The function performs several layers of validation:
+ * 1. **Early rejection**: Filters out null, primitives, arrays, dates, regex, and DOM elements
+ * 2. **Null prototype check**: Accepts objects created with `Object.create(null)`
+ * 3. **Constructor validation**: Verifies the object's constructor is a function
+ * 4. **Standard Object check**: Accepts objects with `Object` as constructor
+ * 5. **Prototype chain validation**: Ensures the prototype chain is standard
+ * 6. **Cross-frame compatibility**: Handles objects from different execution contexts
+ *
+ *
+ * @category Type Guards
+ * @see {@link cloneObject} - For cloning plain objects
+ * @see {@link extendObj} - For merging plain objects
+ * @see {@link defaultObj} - For providing default plain objects
+ */
+export declare function isObj<T = any>(obj: T): obj is T extends Record<any, any> | object ? T : T extends string | undefined | null | boolean | Array<any> ? never : any;
+/**
+ * Clones a source object by returning a non-reference copy of the object.
+ *
+ * This function creates a deep copy of the provided object.
+ * Any nested objects or arrays within the source will also be cloned, ensuring that the
+ * returned object does not reference the original object.
+ *
+ * @template T - The type of the object to clone. This can be any type, including arrays and nested objects.
+ * @param {T} source - The object to clone. This can be any type, including arrays and nested objects.
+ *
+ * @returns {T} A deep cloned copy of the source object. The return type can be
+ * either an object or an array, depending on the input.
+ *
+ * @example
+ * ```ts
+ * // Example with a simple object
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = cloneObject(original);
+ * console.log(cloned); // Outputs: { a: 1, b: { c: 2 } }
+ *
+ * // Modifying the cloned object does not affect the original
+ * cloned.b.c = 3;
+ * console.log(original.b.c); // Outputs: 2 (original remains unchanged)
+ *
+ * // Example with an array
+ * const originalArray = [1, 2, { a: 3 }];
+ * const clonedArray = cloneObject(originalArray);
+ * console.log(clonedArray); // Outputs: [1, 2, { a: 3 }]
+ *
+ * // Modifying the cloned array does not affect the original
+ * clonedArray[2].a = 4;
+ * console.log(originalArray[2].a); // Outputs: 3 (original remains unchanged)
+ *
+ * // Example with a nested structure
+ * const complexObject = { a: 1, b: [2, { c: 3 }] };
+ * const clonedComplex = cloneObject(complexObject);
+ * console.log(clonedComplex); // Outputs: { a: 1, b: [2, { c: 3 }] }
+ * ```
+ */
+export declare function cloneObject<T = any>(source: T): T;
+/**
+ * Calculates the size of an object or array.
+ *
+ * This function returns the number of own properties of an object or the length of an array.
+ * If the input is null or not an object, it returns 0.
+ *
+ * @param {any} obj - The object or array whose size is to be calculated.
+ * @param {boolean} [breakOnFirstElementFound=false] - Optional flag to determine if the function should
+ * return the size immediately upon finding the first property or element.
+ *
+ * @returns {number} The size of the object or array. Returns 0 if the input is null or not an object.
+ *
+ * @example
+ * // Example with an object
+ * const exampleObject = { a: 1, b: 2, c: 3 };
+ * const size = objectSize(exampleObject);
+ * console.log(size); // Outputs: 3
+ *
+ * @example
+ * // Example with an array
+ * const exampleArray = [1, 2, 3, 4];
+ * const arraySize = objectSize(exampleArray);
+ * console.log(arraySize); // Outputs: 4
+ *
+ * @example
+ * // Example with breakOnFirstElementFound
+ * const earlyExitSize = objectSize(exampleObject, true);
+ * console.log(earlyExitSize); // Outputs: 1, as it returns after the first property
+ *
+ * @example
+ * // Example with a null input
+ * const nullSize = objectSize(null);
+ * console.log(nullSize); // Outputs: 0
+ *
+ * @example
+ * // Example with a non-object input
+ * const nonObjectSize = objectSize(42);
+ * console.log(nonObjectSize); // Outputs: 0
+ */
+export declare const objectSize: (obj: any, breakOnFirstElementFound?: boolean) => number;
+/**
+ * Returns a default object based on the provided arguments.
+ *
+ * This function takes multiple arguments and returns the first non-empty object found.
+ * If only one argument is provided, it returns that argument if it is an object; otherwise, it returns an empty object.
+ * If no valid object is found among the arguments, it returns an empty object.
+ *
+ * @param {...any[]} args - The arguments to check for objects.
+ * @template T - The type of the object to return.
+ *
+ * @returns {object} The first non-empty object found among the arguments, or an empty object if none is found.
+ *
+ * @example
+ * ```ts
+ * // Example with one valid object
+ * const result1 = defaultObj({ a: 1 });
+ * console.log(result1); // Outputs: { a: 1 }
+ *
+ * // Example with one invalid argument
+ * const result2 = defaultObj("not an object");
+ * console.log(result2); // Outputs: {}
+ *
+ * // Example with multiple arguments, returning the first non-empty object
+ * const result3 = defaultObj({}, { b: 2 }, { c: 3 });
+ * console.log(result3); // Outputs: { b: 2 }
+ *
+ * // Example with multiple arguments, returning the last valid object
+ * const result4 = defaultObj({}, {}, { d: 4 });
+ * console.log(result4); // Outputs: { d: 4 }
+ *
+ * // Example with no valid objects
+ * const result5 = defaultObj(null, undefined, "string");
+ * console.log(result5); // Outputs: {}
+ * ```
+ */
+export declare function defaultObj<T extends object = any>(...args: any[]): T;
+/**
+ * Declares a global interface extension for the built-in `Object` type.
+ */
+declare global {
+    /**
+     * Interface extension for the built-in `Object` type.
+     */
+    interface Object {
+        /**
+         * Clones a source object by returning a non-reference copy of the object.
+         *
+         * This method creates a deep clone of the provided object, ensuring that nested objects
+         * are also cloned, and modifications to the cloned object do not affect the original.
+         *
+         * @param {any} obj - The object to clone. This can be any type, including arrays and nested objects.
+         * @returns {any} The cloned object, which can be an object or an array.
+         *
+         * @example
+         * ```ts
+         * const original = { a: 1, b: { c: 2 } };
+         * const cloned = Object.clone(original);
+         * console.log(cloned); // Outputs: { a: 1, b: { c: 2 } }
+         *
+         * cloned.b.c = 3;
+         * console.log(original.b.c); // Outputs: 2 (original remains unchanged)
+         * ```
+         * @template T - The type of the object to clone.
+         * @param {T} obj - The object to clone.
+         * @returns {T} A clone of the object.
+         */
+        clone: <T = any>(obj: T) => T;
+        /**
+         * Determines the size of an object or array.
+         *
+         * This method calculates the number of own enumerable properties in an object or
+         * the number of elements in an array. If the `breakOnFirstElementFound` parameter
+         * is set to true, it will return 1 immediately upon finding the first element or property.
+         *
+         * @param {any} obj - The object or array to determine the size of.
+         * @param {boolean} [breakOnFirstElementFound=false] - Whether to return immediately after the first element is found.
+         * @returns {number} The size of the object or array. Returns 0 if the input is not an object or array.
+         *
+         * @example
+         * ```ts
+         * const obj = { a: 1, b: 2, c: 3 };
+         * const size = Object.getSize(obj);
+         * console.log(size); // Outputs: 3
+         *
+         * const arr = [1, 2, 3];
+         * const arrSize = Object.getSize(arr);
+         * console.log(arrSize); // Outputs: 3
+         *
+         * const singleElementSize = Object.getSize(arr, true);
+         * console.log(singleElementSize); // Outputs: 1 (returns immediately)
+         *
+         * const emptyObjSize = Object.getSize({});
+         * console.log(emptyObjSize); // Outputs: 0
+         * ```
+         */
+        getSize: (obj: any, breakOnFirstElementFound?: boolean) => number;
+        /**
+         * Flattens a nested object structure into a single-level object with dot/bracket notation keys.
+         * Handles various data structures including Arrays, Sets, Maps, and plain objects.
+         * Skips non-primitive values like functions, class instances.
+         *
+         * @param {any} obj - The object to flatten
+         * @param {string} [prefix=''] - The prefix to use for nested keys
+         * @returns {Record<string, Primitive>} A flattened object with primitive values
+         *
+         * @example
+         * // Basic object flattening
+         * _flattenObject({
+         *   a: {
+         *     b: 'value',
+         *     c: 42
+         *   }
+         * })
+         * // Returns: { 'a.b': 'value', 'a.c': 42 }
+         *
+         * @example
+         * // Array handling
+         * _flattenObject({
+         *   items: ['a', 'b', { nested: 'value' }]
+         * })
+         * // Returns: { 'items[0]': 'a', 'items[1]': 'b', 'items[2].nested': 'value' }
+         *
+         * @example
+         * // Map handling
+         * _flattenObject({
+         *   map: new Map([
+         *     ['key1', 'value1'],
+         *     ['key2', { nested: 'value2' }]
+         *   ])
+         * })
+         * // Returns: { 'map[key1]': 'value1', 'map[key2].nested': 'value2' }
+         *
+         * @example
+         * // Complex nested structure
+         * _flattenObject({
+         *   array: [1, { a: 2 }],
+         *   set: new Set(['x', { b: 'y' }]),
+         *   map: new Map([['k', { c: 'v' }]]),
+         *   obj: {
+         *     deep: {
+         *       nested: 'value',
+         *       fn: () => {}, // Will be skipped
+         *       date: new Date() // Will be skipped
+         *     }
+         *   }
+         * })
+         * // Returns: {
+         * //   'array[0]': 1,
+         * //   'array[1].a': 2,
+         * //   'set[0]': 'x',
+         * //   'set[1].b': 'y',
+         * //   'map[k].c': 'v',
+         * //   'obj.deep.nested': 'value'
+         * // }
+         *
+         * @throws {Error} Will not throw errors, but silently skips non-primitive values
+         *
+         * @category Utilities
+         *
+         */
+        flatten(obj: any): Record<string, Primitive>;
+        /**
+         * Enhanced version of Object.entries that preserves key types in TypeScript inference.
+         *
+         * Unlike the standard Object.entries which types all keys as string, this method
+         * maintains the original key types (string | number | symbol) in TypeScript's type system
+         * while still following JavaScript's runtime behavior where all keys are strings.
+         *
+         * @template T - The object type extending Record<string | number, any>
+         * @param obj - The object to extract entries from
+         * @returns Array of key-value tuples with preserved key types in TypeScript
+         *
+         * @example
+         * ```typescript
+         * const obj = { 1: "one", "foo": "bar", 42: "answer" } as const;
+         *
+         * // Standard Object.entries - all keys typed as string
+         * const standard = Object.entries(obj); // [string, string][]
+         *
+         * // Enhanced Object.typedEntries - preserves original key types
+         * const typed = Object.typedEntries(obj);
+         * // Type: (["1", "one"] | ["foo", "bar"] | ["42", "answer"])[]
+         * ```
+         *
+         * @remarks
+         * - Runtime behavior is identical to Object.entries (all keys are strings)
+         * - Only TypeScript inference is enhanced to remember original key types
+         * - Works best with objects declared with 'as const' for literal type inference
+         * - Particularly useful for objects with mixed string and numeric keys
+         *
+         *
+         */
+        typedEntries<T extends Record<any, unknown> = any>(obj: T): Array<{
+            [K in keyof T]: [K, T[K]];
+        }[keyof T]>;
+    }
+}
+/**
+ * Extends an object by merging properties from one or more source objects.
+ *
+ * This function takes a target object and one or more source objects, merging the properties
+ * from the source objects into the target object. If a property exists in both the target
+ * and a source object, the value from the source object will overwrite the target's value.
+ * For arrays, the function merges the contents of the arrays, preserving the original order of the elements.
+ *@template T - The type of the target object.
+ * @param {T} target - The object to extend. It will receive the new properties.
+ * @param {...any[]} sources - The source objects to merge into the target. These objects will not be modified.
+ * @returns {T} The extended target object, which contains properties from the source objects.
+ *
+ * @example
+ * ```ts
+ * const target = { a: 1, b: 2 };
+ * const source1 = { b: 3, c: 4 };
+ * const source2 = { d: 5 };
+ *
+ * const extended = extendObj(target, source1, source2);
+ * console.log(extended); // Outputs: { a: 1, b: 3, c: 4, d: 5 }
+ * console.log(target);   // Outputs: { a: 1, b: 3 } (target is modified)
+ * ```
+ * Merges the contents of two or more objects together into the first object.
+ * Similar to jQuery's $.extend function.
+ * @remarks
+ * This function is used to merge the contents of multiple objects into a single object. It takes an optional target object as the first argument and one or more source objects as additional arguments. The function returns the merged object, which is a new object that contains all the properties from the source objects.
+ *
+ * If the target object is not provided or is not a plain object, an empty object is returned.
+ *
+ * If the target object is a plain object, the function iterates over the sources and copies the properties from each source object to the target object. If a property with the same name already exists in the target object, it is overwritten with the corresponding value from the source object.
+ *
+ * If the target object is a plain object, the function iterates over the sources and copies the properties from each source object to the target object. If a property with the same name already exists in the target object, it is overwritten with the corresponding value from the source object.
+ * For arrays, The function replaces the contents of the arrays, preserving the original order of the elements.
+ * Empty values like null, undefined, and empty strings are ignored.
+ */
+export declare function extendObj<T extends Record<any, any> = any>(target: any, ...sources: any[]): T;
+/**
+ * Flattens a nested object structure into a single-level object with dot/bracket notation keys.
+ * Handles various data structures including Arrays, Sets, Maps, and plain objects.
+ * Skips non-primitive values like functions, class instances.
+ *
+ * @param {any} obj - The object to flatten
+ * @param {string} [prefix=''] - The prefix to use for nested keys
+ * @returns {Record<string, Primitive>} A flattened object with primitive values
+ *
+ * @example
+ * // Basic object flattening
+ * _flattenObject({
+ *   a: {
+ *     b: 'value',
+ *     c: 42
+ *   }
+ * })
+ * // Returns: { 'a.b': 'value', 'a.c': 42 }
+ *
+ * @example
+ * // Array handling
+ * _flattenObject({
+ *   items: ['a', 'b', { nested: 'value' }]
+ * })
+ * // Returns: { 'items[0]': 'a', 'items[1]': 'b', 'items[2].nested': 'value' }
+ *
+ * @example
+ * // Map handling
+ * _flattenObject({
+ *   map: new Map([
+ *     ['key1', 'value1'],
+ *     ['key2', { nested: 'value2' }]
+ *   ])
+ * })
+ * // Returns: { 'map[key1]': 'value1', 'map[key2].nested': 'value2' }
+ *
+ * @example
+ * // Complex nested structure
+ * _flattenObject({
+ *   array: [1, { a: 2 }],
+ *   set: new Set(['x', { b: 'y' }]),
+ *   map: new Map([['k', { c: 'v' }]]),
+ *   obj: {
+ *     deep: {
+ *       nested: 'value',
+ *       fn: () => {}, // Will be skipped
+ *       date: new Date() // Will be skipped
+ *     }
+ *   }
+ * })
+ * // Returns: {
+ * //   'array[0]': 1,
+ * //   'array[1].a': 2,
+ * //   'set[0]': 'x',
+ * //   'set[1].b': 'y',
+ * //   'map[k].c': 'v',
+ * //   'obj.deep.nested': 'value'
+ * // }
+ *
+ * @throws {Error} Will not throw errors, but silently skips non-primitive values
+ *
+ * @category Utilities
+ *
+ */
+export declare function flattenObject(obj: any, options?: FlattenObjectOptions): Record<string, any>;
+/**
+ * Checks if a value is an iterable data structure (Array, Set, Map, WeakMap, WeakSet).
+ *
+ * @param {any} value - The value to check
+ * @returns {boolean} True if the value is an iterable structure, false otherwise
+ *
+ * @example
+ * isIterableStructure([1, 2, 3])           // returns true
+ * isIterableStructure(new Set([1, 2, 3]))  // returns true
+ * isIterableStructure(new Map())           // returns true
+ * isIterableStructure({})                  // returns false
+ */
+export declare function isIterableStructure(value: any): boolean;
+/**
+ * Enhanced version of Object.entries that preserves key types in TypeScript inference.
+ *
+ * Unlike the standard Object.entries which types all keys as string, this method
+ * maintains the original key types (string | number | symbol) in TypeScript's type system
+ * while still following JavaScript's runtime behavior where all keys are strings.
+ *
+ * @template T - The object type extending Record<string | number, any>
+ * @param obj - The object to extract entries from
+ * @returns Array of key-value tuples with preserved key types in TypeScript
+ *
+ * @example
+ * ```typescript
+ * const obj = { 1: "one", "foo": "bar", 42: "answer" } as const;
+ *
+ * // Standard Object.entries - all keys typed as string
+ * const standard = Object.entries(obj); // [string, string][]
+ *
+ * // Enhanced Object.typedEntries - preserves original key types
+ * const typed = Object.typedEntries(obj);
+ * // Type: (["1", "one"] | ["foo", "bar"] | ["42", "answer"])[]
+ * ```
+ *
+ * @remarks
+ * - Runtime behavior is identical to Object.entries (all keys are strings)
+ * - Only TypeScript inference is enhanced to remember original key types
+ * - Works best with objects declared with 'as const' for literal type inference
+ * - Particularly useful for objects with mixed string and numeric keys
+ *
+ *
+ */
+export declare function typedEntries<T extends Record<any, unknown> = any>(obj: T): Array<{
+    [K in keyof T]: [K, T[K]];
+}[keyof T]>;
+export interface FlattenObjectOptions {
+    /**
+     * Whether to skip arrays during the flattening process.
+     *
+     * When set to `true`, arrays will be treated as primitive values and included
+     * directly in the flattened result instead of being recursively flattened.
+     * This can be useful for performance optimization or when you want to preserve
+     * array structures in your flattened output.
+     *
+     * @default false - Arrays are recursively flattened by default
+     *
+     * @example
+     * ```typescript
+     * const obj = {
+     *   name: 'John',
+     *   tags: ['developer', 'typescript'],
+     *   scores: [85, 92, 78]
+     * };
+     *
+     * // Default behavior (skipArrays: false)
+     * flattenObject(obj);
+     * // Result: { 'name': 'John', 'tags[0]': 'developer', 'tags[1]': 'typescript', 'scores[0]': 85, 'scores[1]': 92, 'scores[2]': 78 }
+     *
+     * // With skipArrays: true
+     * flattenObject(obj, { skipArrays: true });
+     * // Result: { 'name': 'John', 'tags': ['developer', 'typescript'], 'scores': [85, 92, 78] }
+     * ```
+     *
+     *
+     */
+    skipArrays?: boolean;
+}

package/build/utils/object.js

@@ -0,0 +1 @@
+'use strict';function p(n){return !n||typeof n!="object"?false:n instanceof Date?true:typeof n.getTime!="function"?false:!(Object.prototype.toString.call(n)!=="[object Date]"||isNaN(n.getTime()))}function d(n){return typeof window!="object"||!window||typeof document=="undefined"||typeof HTMLElement=="undefined"||!HTMLElement?false:n===document?true:"HTMLElement"in window?!!n&&n instanceof HTMLElement:!!n&&typeof n=="object"&&n.nodeType===1&&!!n.nodeName}function T(n){return n==null||typeof n=="string"||typeof n=="number"||typeof n=="boolean"}function m(n){if(n instanceof RegExp)return  true;if(!n||typeof n!="object"||!Object.prototype.toString.call(n).includes("RegExp"))return  false;try{return new RegExp(n),!0}catch(e){return  false}}function f(n){if(n===null||typeof n!="object"||d(n)||p(n)||m(n)||T(n))return  false;let e=Object.getPrototypeOf(n);if(e===null)return  true;let t=e.constructor;if(typeof t!="function")return  false;if(t===Object)return  true;let r=t.prototype;return typeof r!="object"?false:r===Object.prototype?true:typeof e.hasOwnProperty=="function"&&Object.prototype.hasOwnProperty.call(e,"isPrototypeOf")&&typeof e.isPrototypeOf=="function"}function A(n){if(Array.isArray(n)){let r=[];for(var e=0;e<n.length;e++)r[e]=A(n[e]);return r}else if(f(n)&&n){let r={};for(var t in n)n.hasOwnProperty(t)&&(r[t]=A(n[t]));return r}else return n}var $=Object.getSize=function(n,e=false){if(!n||typeof n!="object")return 0;if(Array.isArray(n))return n.length;typeof e!="boolean"&&(e=false);let t=0;for(let r in n)if(Object.prototype.hasOwnProperty.call(n,r)&&(t++,e===true))return t;return t};function C(...n){if(n.length===1)return f(n[0])?n[0]:{};let e=null;for(var t in n){let r=n[t];if(f(r)){if(Object.getSize(r,true)>0)return r;e||(e=r);}}return e||{}}function h(n,...e){let t=Array.isArray(n),r=f(n);(n==null||!t&&!r)&&(n={});for(let i=0;i<e.length;i++){let o=e[i];if(o==null)continue;let a=f(o),y=Array.isArray(o);if(!(!a&&!y)){if(t){y&&w(n,o);continue}else if(y)continue;for(let c in o){let s=o[c];if(s==null)continue;if(s===o){n[c]=n;continue}let u=n[c],x=Array.isArray(u),O=Array.isArray(s);if(x){O?w(n[c],s):n[c]=s;continue}else if(!f(u)){n[c]=s;continue}if(O||!f(s)){n[c]=s;continue}n[c]=h({},u,s);}}}return n}var w=(n,e)=>{let t=e.length,r=0;for(let i=0;i<n.length;i++){let o=n[i],a=e[i];if(i<t){let y=Array.isArray(o),c=Array.isArray(a),s=f(o),u=f(a);y&&c||s&&u?(n[r]=h(y?[]:{},o,a),r++):a!=null?(n[r]=a,r++):o!=null&&(n[r]=o,r++);}}for(let i=n.length;i<t;i++)e[i]!==void 0&&e[i]!==null&&n.push(e[i]);return n};function b(n,e){return l(n,"",{},e)}function l(n,e="",t={},r){if(t=f(t)?t:{},T(n)||p(n)||m(n)||Array.isArray(n)&&(r!=null&&r.skipArrays))return e&&(t[e]=n),t;if(typeof n=="function"||typeof n=="object"&&!f(n)&&!g(n))return t;if(n instanceof Map||n instanceof WeakMap)return Array.from(n.entries()).forEach(([i,o])=>{let a=e?`${e}[${String(i)}]`:String(i);l(o,a,t,r);}),t;if(Array.isArray(n)||n instanceof Set||n instanceof WeakSet)return (Array.isArray(n)?n:Array.from(n)).forEach((o,a)=>{let y=e?`${e}[${a}]`:String(a);l(o,y,t,r);}),t;if(f(n))for(let i in n){if(!Object.prototype.hasOwnProperty.call(n,i))continue;let o=n[i],a=e?e.endsWith("]")?`${e}.${i}`:`${e}.${i}`:i;l(o,a,t,r);}return t}function g(n){return Array.isArray(n)||n instanceof Set||n instanceof Map||n instanceof WeakMap||n instanceof WeakSet}function S(n){return Object.entries(n)}Object.typedEntries=S;Object.flatten=b;Object.clone=A;exports.cloneObject=A;exports.defaultObj=C;exports.extendObj=h;exports.flattenObject=b;exports.isIterableStructure=g;exports.isObj=f;exports.objectSize=$;exports.typedEntries=S;

package/build/utils/sort.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A highly optimized sorting function capable of efficiently handling billions of array elements
+ * with support for complex objects and various data types.
+ *
+ * For very large arrays (millions of elements), this function automatically switches to
+ * a chunked sorting algorithm that reduces memory pressure and improves cache efficiency.
+ * You can control the chunk size with the `chunkSize` option.
+ *
+ * @template T - The type of array elements being sorted
+ * @template V - The type of values being compared for sorting
+ *
+ * @param data - The array to be sorted
+ * @param getItemValue - Function that extracts the comparable value from each array item
+ * @param options - Configuration options to control the sorting behavior
+ *
+ * @returns The sorted array (either the original array modified in-place or a new array)
+ *
+ * @example
+ * // Sort an array of objects by their 'name' property
+ * const users = [
+ *   { id: 101, name: "Alice", age: 28 },
+ *   { id: 102, name: "bob", age: 34 },
+ *   { id: 103, name: "Charlie", age: 21 }
+ * ];
+ *
+ * // Case-sensitive sort (default)
+ * const sortedByName = sortBy(users, user => user.name);
+ * // Result: [{ id: 101, name: "Alice", age: 28 }, { id: 103, name: "Charlie", age: 21 }, { id: 102, name: "bob", age: 34 }]
+ *
+ * // Case-insensitive sort
+ * const sortedIgnoringCase = sortBy(users, user => user.name, { ignoreCase: true });
+ * // Result: [{ id: 101, name: "Alice", age: 28 }, { id: 102, name: "bob", age: 34 }, { id: 103, name: "Charlie", age: 21 }]
+ *
+ * @example
+ * // Sort by date values in descending order (newest first)
+ * const tasks = [
+ *   { id: 1, title: "Task 1", deadline: new Date("2023-12-01") },
+ *   { id: 2, title: "Task 2", deadline: new Date("2023-05-15") },
+ *   { id: 3, title: "Task 3", deadline: new Date("2024-02-20") }
+ * ];
+ *
+ * const sortedByDeadline = sortBy(tasks, task => task.deadline, { direction: 'desc' });
+ * // Result: Tasks ordered with newest deadline first
+ *
+ * @example
+ * // Create a new sorted array without modifying the original
+ * const numbers = [5, 2, 9, 1, 5, 6];
+ * const sortedNumbers = sortBy(numbers, n => n, { inPlace: false });
+ * // numbers is still [5, 2, 9, 1, 5, 6]
+ * // sortedNumbers is [1, 2, 5, 5, 6, 9]
+ *
+ * @example
+ * // Handle very large datasets with custom chunk size for memory efficiency
+ * const largeDataset = Array.from({ length: 1000000 }, () => Math.random());
+ * const sortedLarge = sortBy(largeDataset, n => n, { chunkSize: 25000 });
+ * // Uses chunked sorting to reduce memory pressure on large arrays
+ */
+export declare function sortBy<T, V = unknown>(data: T[], getItemValue: (item: T) => V, options?: {
+    direction?: SortOrder;
+    inPlace?: boolean;
+    /** Controls chunk size for large array sorting. Arrays larger than chunkSize
+     * will be sorted using a memory-efficient chunked algorithm. Default: 50000 */
+    chunkSize?: number;
+    ignoreCase?: boolean;
+}): T[];
+type SortOrder = 'asc' | 'desc';
+export {};

package/build/utils/sort.js

@@ -0,0 +1 @@
+'use strict';function S(n,t,e={}){if(!Array.isArray(n))return [];if(n.length<=1)return e.inPlace===false?[...n]:n;let f=e.direction==="desc"?"desc":"asc",s=e.ignoreCase!==false,c=e.inPlace!==false,i=e.chunkSize&&e.chunkSize>0?e.chunkSize:5e4,r=c?n:[...n];return r.length>i?T(r,t,f,s,i):r.sort((o,l)=>u(t(o),t(l),f,s))}function u(n,t,e,f){if(n==null&&t==null)return 0;if(n==null)return e==="asc"?-1:1;if(t==null)return e==="asc"?1:-1;if(typeof n=="number"&&typeof t=="number"){let r=n-t;return e==="asc"?r:-r}if(typeof n=="string"&&typeof t=="string"){let r=n,o=t;f&&(r=r.toLowerCase(),o=o.toLowerCase());let l=r<o?-1:r>o?1:0;return e==="asc"?l:-l}if(n instanceof Date&&t instanceof Date){let r=n.getTime()-t.getTime();return e==="asc"?r:-r}let s=String(n),c=String(t),i=f?s.toLowerCase()<c.toLowerCase()?-1:s.toLowerCase()>c.toLowerCase()?1:0:s<c?-1:s>c?1:0;return e==="asc"?i:-i}function T(n,t,e,f,s){if(n.length<=s)return n.sort((r,o)=>u(t(r),t(o),e,f));let c=[];for(let r=0;r<n.length;r+=s)c.push(n.slice(r,r+s));let i=c.map(r=>r.sort((o,l)=>u(t(o),t(l),e,f)));return h(i,t,e,f)}function h(n,t,e,f){if(n.length===0)return [];if(n.length===1)return n[0];let s=[],c=new Array(n.length).fill(0);for(;;){let i=-1,r=null;for(let o=0;o<n.length;o++)if(c[o]<n[o].length){let l=n[o][c[o]];(r===null||u(t(l),t(r),e,f)<0)&&(r=l,i=o);}if(i===-1)break;s.push(r),c[i]++;}return s}exports.sortBy=S;