@pawells/typescript-common 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phillip Aaron Wells
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# TypeScript Common Utilities
+
+[![npm](https://img.shields.io/npm/v/@pawells/typescript-common)](https://www.npmjs.com/package/@pawells/typescript-common)
+[![GitHub Release](https://img.shields.io/github/v/release/PhillipAWells/typescript-common)](https://github.com/PhillipAWells/typescript-common/releases)
+[![CI](https://github.com/PhillipAWells/typescript-common/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/typescript-common/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/PhillipAWells?style=social)](https://github.com/sponsors/PhillipAWells)
+
+Shared TypeScript utility library. ESM-only, no runtime dependencies, targets ES2022.
+
+## Installation
+
+```bash
+npm install @pawells/typescript-common
+# or
+yarn add @pawells/typescript-common
+```
+
+## Usage
+
+All utilities are available as namespace imports or as individual named exports for tree-shaking.
+
+```typescript
+// Namespace import
+import { ArrayUtils, ObjectUtils, StringUtils, TimeUtils, EnumUtils, FunctionUtils } from '@pawells/typescript-common';
+
+ArrayUtils.ArrayChunk([1, 2, 3, 4], 2); // [[1, 2], [3, 4]]
+
+// Direct named import (tree-shakeable)
+import { ArrayChunk, ObjectPick, CamelCase, Sleep } from '@pawells/typescript-common';
+```
+
+## API
+
+### Array utilities — `ArrayUtils`
+
+| Export | Description |
+|--------|-------------|
+| `ArrayChunk(array, size)` | Split an array into chunks of a given size |
+| `ArrayContains(array, predicate)` | Check if any element satisfies a predicate |
+| `ArrayFilter(array, predicate)` | Type-safe array filter |
+| `ArrayGroupBy(array, keyFn)` | Group array elements by a key function |
+| `ArrayIntersection(a, b)` | Return elements present in both arrays |
+| `ArrayShuffle(array)` | Return a shuffled copy of an array |
+| `Unique(array)` | Remove duplicate values |
+| `ArrayDifference(a, b)` | Elements in `a` not present in `b` |
+| `ArrayFlatten(array, depth?)` | Flatten a nested array to a given depth |
+| `ArrayCompact(array)` | Remove `null`/`undefined`, narrowing the type |
+| `ArrayPartition(array, predicate)` | Split into `[matches, rest]` |
+| `ArrayZip(...arrays)` | Zip multiple arrays into tuples |
+| `ArrayRange(start, end, step?)` | Generate a numeric sequence |
+| `ArraySortBy(array, keyFn, direction?)` | Immutable sort by a computed key |
+| `ArrayCountBy(array, keyFn)` | Count elements per group key |
+| `ArraySample(array, n?)` | Random element or `n` random elements |
+
+### Object utilities — `ObjectUtils`
+
+| Export | Description |
+|--------|-------------|
+| `AssertObject(value)` | Assert a value is a non-null object |
+| `ObjectClone(obj)` | Deep-clone an object |
+| `ObjectEquals(a, b)` | Deep equality check |
+| `ObjectFilter(obj, predicate)` | Filter object entries by predicate |
+| `FilterObject(obj, keys)` | Keep only specified keys |
+| `ObjectPick(obj, keys)` | Pick a subset of keys |
+| `ObjectOmit(obj, keys)` | Omit specified keys |
+| `ObjectMerge(target, ...sources)` | Deep merge objects |
+| `MapObject(obj, fn)` | Map over object values |
+| `TransformObject(obj, fn)` | Transform object entries |
+| `ObjectHash(obj)` | Compute a stable hash of an object |
+| `ObjectSortKeys(obj)` | Return object with keys sorted |
+| `ObjectFromKeyValuePairs(pairs)` | Build an object from `[key, value]` pairs |
+| `ObjectToKeyValuePairs(obj)` | Convert an object to `[key, value]` pairs |
+| `ObjectGetPropertyByPath(obj, path)` | Get a nested property by dot-path |
+| `ObjectSetPropertyByPath(obj, path, value)` | Set a nested property by dot-path |
+| `ObjectInvert(obj)` | Swap keys and values |
+| `ObjectFlatten(obj, separator?)` | Flatten nested object to dot-separated keys |
+| `ObjectDiff(objA, objB)` | Compute added/removed/changed keys between two objects |
+
+### String utilities — `StringUtils`
+
+| Export | Description |
+|--------|-------------|
+| `CamelCase(str)` | Convert a string to camelCase |
+| `PASCAL_CASE(str)` | Convert a string to PascalCase |
+| `KEBAB_CASE(str)` | Convert a string to kebab-case |
+| `SNAKE_CASE(str)` | Convert a string to snake_case |
+| `SCREAMING_SNAKE_CASE(str)` | Convert a string to SCREAMING_SNAKE_CASE |
+| `FormatString(template, values)` | Simple string template formatting |
+| `EscapeHTML(str)` | Escape HTML special characters |
+| `StripHTML(str)` | Remove all HTML tags from a string |
+| `Pluralize(word, count, plural?)` | Return singular or plural form based on count |
+| `WordCount(str)` | Count the number of words in a string |
+| `CountOccurrences(str, substr)` | Count non-overlapping occurrences of a substring |
+
+### Time utilities — `TimeUtils`
+
+| Export | Description |
+|--------|-------------|
+| `ElapsedTime` | Measure elapsed time with human-readable output |
+| `Stopwatch` | Lap-based stopwatch for benchmarking |
+
+### Enum utilities — `EnumUtils`
+
+| Export | Description |
+|--------|-------------|
+| `EnumKeys(enumObj)` | Get keys of a TypeScript enum |
+| `EnumValues(enumObj)` | Get values of a TypeScript enum |
+| `EnumEntries(enumObj)` | Get key-value pairs of a TypeScript enum |
+| `ValidateEnumValue(enumObj, value)` | Check if a value is a valid enum member |
+| `EnumKeyByValue(enumObj, value)` | Look up an enum key by its value |
+| `EnumSafeValue(enumObj, value)` | Return the value if valid, or `undefined` |
+
+### Function utilities — `FunctionUtils`
+
+| Export | Description |
+|--------|-------------|
+| `Debounce(fn, ms)` | Delay execution until `ms` ms after the last call |
+| `Throttle(fn, ms)` | Limit execution to at most once per `ms` ms |
+| `Memoize(fn, keyFn?)` | Cache results by serialised arguments |
+| `Once(fn)` | Execute a function at most once, caching the result |
+| `Pipe(...fns)` | Compose functions left-to-right |
+| `Compose(...fns)` | Compose functions right-to-left |
+| `Sleep(ms)` | Return a `Promise` that resolves after `ms` ms |
+
+## Development
+
+```bash
+yarn install        # Install dependencies
+yarn build          # Compile TypeScript → ./build/
+yarn dev            # Build + run
+yarn watch          # Watch mode
+yarn typecheck      # Type check without building
+yarn lint           # ESLint
+yarn lint:fix       # ESLint with auto-fix
+yarn test           # Run tests
+yarn test:ui        # Interactive Vitest UI
+yarn test:coverage  # Tests with coverage report
+```
+
+## Requirements
+
+- Node.js >= 24.0.0
+
+## License
+
+MIT — See [LICENSE](./LICENSE) for details.

package/build/array/array-chunk.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Chunks an array into smaller arrays of a specified size.
+ * @param array The array to split.
+ * @param size Size of each chunk.
+ * @returns Array of arrays, each of the specified size.
+ * @example
+ * const chunks = ArrayChunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ */
+export declare function ArrayChunk<T>(array: T[], size: number): T[][];
+//# sourceMappingURL=array-chunk.d.ts.map

package/build/array/array-chunk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-chunk.d.ts","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAY7D"}

package/build/array/array-chunk.js

@@ -0,0 +1,19 @@
+/**
+ * Chunks an array into smaller arrays of a specified size.
+ * @param array The array to split.
+ * @param size Size of each chunk.
+ * @returns Array of arrays, each of the specified size.
+ * @example
+ * const chunks = ArrayChunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ */
+export function ArrayChunk(array, size) {
+    if (!array || size <= 0) {
+        return [];
+    }
+    const result = [];
+    for (let i = 0; i < array.length; i += size) {
+        result.push(array.slice(i, i + size));
+    }
+    return result;
+}
+//# sourceMappingURL=array-chunk.js.map

package/build/array/array-chunk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-chunk.js","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAI,KAAU,EAAE,IAAY;IACrD,IAAI,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,MAAM,GAAU,EAAE,CAAC;IAEzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/build/array/array-compact.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Removes `null` and `undefined` values from an array, narrowing the element type.
+ *
+ * @template T - The non-nullish element type
+ * @param array - The array to compact
+ * @returns A new array with `null`/`undefined` entries removed
+ *
+ * @example
+ * ```typescript
+ * ArrayCompact([1, null, 2, undefined, 3]); // [1, 2, 3]
+ * // Return type is narrowed: number[]
+ *
+ * const names: (string | null)[] = ['Alice', null, 'Bob'];
+ * const clean: string[] = ArrayCompact(names);
+ * ```
+ */
+export declare function ArrayCompact<T>(array: (T | null | undefined)[]): T[];
+//# sourceMappingURL=array-compact.d.ts.map

package/build/array/array-compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-compact.d.ts","sourceRoot":"","sources":["../../src/array/array-compact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAGpE"}

package/build/array/array-compact.js

@@ -0,0 +1,22 @@
+/**
+ * Removes `null` and `undefined` values from an array, narrowing the element type.
+ *
+ * @template T - The non-nullish element type
+ * @param array - The array to compact
+ * @returns A new array with `null`/`undefined` entries removed
+ *
+ * @example
+ * ```typescript
+ * ArrayCompact([1, null, 2, undefined, 3]); // [1, 2, 3]
+ * // Return type is narrowed: number[]
+ *
+ * const names: (string | null)[] = ['Alice', null, 'Bob'];
+ * const clean: string[] = ArrayCompact(names);
+ * ```
+ */
+export function ArrayCompact(array) {
+    if (!array)
+        return [];
+    return array.filter((item) => item !== null && item !== undefined);
+}
+//# sourceMappingURL=array-compact.js.map

package/build/array/array-compact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-compact.js","sourceRoot":"","sources":["../../src/array/array-compact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAI,KAA+B;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAa,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC;AAC/E,CAAC"}

package/build/array/array-contains.d.ts

@@ -0,0 +1,9 @@
+import type { TPredicate } from './types';
+/**
+ * Checks if an array contains at least one element that passes a predicate test.
+ * @param array The array to check.
+ * @param predicate TPredicate function to test each element.
+ * @returns True if at least one element passes the test, false otherwise.
+ */
+export declare function ArrayContains<T>(array: T[], predicate: TPredicate<T>): boolean;
+//# sourceMappingURL=array-contains.d.ts.map

package/build/array/array-contains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-contains.d.ts","sourceRoot":"","sources":["../../src/array/array-contains.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAM9E"}

package/build/array/array-contains.js

@@ -0,0 +1,13 @@
+/**
+ * Checks if an array contains at least one element that passes a predicate test.
+ * @param array The array to check.
+ * @param predicate TPredicate function to test each element.
+ * @returns True if at least one element passes the test, false otherwise.
+ */
+export function ArrayContains(array, predicate) {
+    if (!array || array.length === 0) {
+        return false;
+    }
+    return array.some(predicate);
+}
+//# sourceMappingURL=array-contains.js.map

package/build/array/array-contains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-contains.js","sourceRoot":"","sources":["../../src/array/array-contains.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAI,KAAU,EAAE,SAAwB;IACpE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAC9B,CAAC"}

package/build/array/array-count-by.d.ts

@@ -0,0 +1,21 @@
+import type { TTransform } from './types';
+/**
+ * Counts how many elements fall into each group defined by `keyFn`.
+ *
+ * @template T - The type of array elements
+ * @template K - The key type (string, number, or symbol)
+ * @param array - The array to count
+ * @param keyFn - Function that assigns each element to a group key
+ * @returns A record where keys are group identifiers and values are occurrence counts
+ *
+ * @example
+ * ```typescript
+ * ArrayCountBy(['one', 'two', 'three'], (s) => s.length);
+ * // { 3: 2, 5: 1 }
+ *
+ * ArrayCountBy(users, (u) => u.role);
+ * // { admin: 3, member: 12, guest: 1 }
+ * ```
+ */
+export declare function ArrayCountBy<T, K extends string | number | symbol>(array: T[], keyFn: TTransform<T, K>): Record<K, number>;
+//# sourceMappingURL=array-count-by.d.ts.map

package/build/array/array-count-by.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-count-by.d.ts","sourceRoot":"","sources":["../../src/array/array-count-by.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EACjE,KAAK,EAAE,CAAC,EAAE,EACV,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACrB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAWnB"}

package/build/array/array-count-by.js

@@ -0,0 +1,29 @@
+/**
+ * Counts how many elements fall into each group defined by `keyFn`.
+ *
+ * @template T - The type of array elements
+ * @template K - The key type (string, number, or symbol)
+ * @param array - The array to count
+ * @param keyFn - Function that assigns each element to a group key
+ * @returns A record where keys are group identifiers and values are occurrence counts
+ *
+ * @example
+ * ```typescript
+ * ArrayCountBy(['one', 'two', 'three'], (s) => s.length);
+ * // { 3: 2, 5: 1 }
+ *
+ * ArrayCountBy(users, (u) => u.role);
+ * // { admin: 3, member: 12, guest: 1 }
+ * ```
+ */
+export function ArrayCountBy(array, keyFn) {
+    if (!array)
+        return {};
+    const result = {};
+    for (const item of array) {
+        const key = keyFn(item);
+        result[key] = (result[key] ?? 0) + 1;
+    }
+    return result;
+}
+//# sourceMappingURL=array-count-by.js.map

package/build/array/array-count-by.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-count-by.js","sourceRoot":"","sources":["../../src/array/array-count-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAC3B,KAAU,EACV,KAAuB;IAEvB,IAAI,CAAC,KAAK;QAAE,OAAO,EAAuB,CAAC;IAE3C,MAAM,MAAM,GAAG,EAAuB,CAAC;IAEvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAE,MAAM,CAAC,GAAG,CAAwB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/build/array/array-difference.d.ts

@@ -0,0 +1,25 @@
+import type { TEqualityComparator } from './types';
+/**
+ * Returns elements present in the first array but not in the second (set difference).
+ * Optimised O(n+m) using a Set when no custom comparator is provided.
+ *
+ * @template T - The type of array elements
+ * @param array1 - The source array
+ * @param array2 - Elements to exclude
+ * @param comparator - Optional custom equality comparator
+ * @returns Array of elements in `array1` that are not in `array2`
+ *
+ * @example
+ * ```typescript
+ * ArrayDifference([1, 2, 3, 4], [2, 4]); // [1, 3]
+ * ArrayDifference(
+ *   [{ id: 1 }, { id: 2 }],
+ *   [{ id: 2 }],
+ *   (a, b) => a.id === b.id,
+ * ); // [{ id: 1 }]
+ * ```
+ *
+ * @complexity O(n+m) for primitive values, O(n*m) when a comparator is provided
+ */
+export declare function ArrayDifference<T>(array1: T[], array2: T[], comparator?: TEqualityComparator<T>): T[];
+//# sourceMappingURL=array-difference.d.ts.map

package/build/array/array-difference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-difference.d.ts","sourceRoot":"","sources":["../../src/array/array-difference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAChC,MAAM,EAAE,CAAC,EAAE,EACX,MAAM,EAAE,CAAC,EAAE,EACX,UAAU,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,GACjC,CAAC,EAAE,CAUL"}

package/build/array/array-difference.js

@@ -0,0 +1,34 @@
+/**
+ * Returns elements present in the first array but not in the second (set difference).
+ * Optimised O(n+m) using a Set when no custom comparator is provided.
+ *
+ * @template T - The type of array elements
+ * @param array1 - The source array
+ * @param array2 - Elements to exclude
+ * @param comparator - Optional custom equality comparator
+ * @returns Array of elements in `array1` that are not in `array2`
+ *
+ * @example
+ * ```typescript
+ * ArrayDifference([1, 2, 3, 4], [2, 4]); // [1, 3]
+ * ArrayDifference(
+ *   [{ id: 1 }, { id: 2 }],
+ *   [{ id: 2 }],
+ *   (a, b) => a.id === b.id,
+ * ); // [{ id: 1 }]
+ * ```
+ *
+ * @complexity O(n+m) for primitive values, O(n*m) when a comparator is provided
+ */
+export function ArrayDifference(array1, array2, comparator) {
+    if (!array1)
+        return [];
+    if (!array2 || array2.length === 0)
+        return [...array1];
+    if (comparator) {
+        return array1.filter((item) => !array2.some((other) => comparator(item, other)));
+    }
+    const set2 = new Set(array2);
+    return array1.filter((item) => !set2.has(item));
+}
+//# sourceMappingURL=array-difference.js.map

package/build/array/array-difference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-difference.js","sourceRoot":"","sources":["../../src/array/array-difference.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAW,EACX,MAAW,EACX,UAAmC;IAEnC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAEvD,IAAI,UAAU,EAAE,CAAC;QAChB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/build/array/array-element.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extracts the element type from an array type.
+ * @example
+ * type T = TArrayElement<string[]>; // T is string
+ */
+export type TArrayElement<A> = A extends readonly (infer T)[] ? T : never;
+//# sourceMappingURL=array-element.d.ts.map

package/build/array/array-element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-element.d.ts","sourceRoot":"","sources":["../../src/array/array-element.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC"}

package/build/array/array-element.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=array-element.js.map

package/build/array/array-element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-element.js","sourceRoot":"","sources":["../../src/array/array-element.ts"],"names":[],"mappings":""}

package/build/array/array-filter.d.ts

@@ -0,0 +1,37 @@
+import type { TPredicate } from './types';
+/**
+ * Filters an array based on criteria that can be an object filter or a predicate function.
+ * Supports nested property filtering with dot notation and array property filtering.
+ *
+ * @param array - The array to filter
+ * @param criteria - Either an object with filter criteria or a predicate function
+ * @returns A new array containing only items that match the criteria
+ *
+ * @example
+ * // Simple property filtering
+ * const users = [{ name: 'John', age: 25 }, { name: 'Jane', age: 30 }];
+ * ArrayFilter(users, { age: 30 }); // [{ name: 'Jane', age: 30 }]
+ *
+ * @example
+ * // Nested property filtering
+ * const profiles = [
+ *   { user: { name: 'John', active: true } },
+ *   { user: { name: 'Jane', active: false } }
+ * ];
+ * ArrayFilter(profiles, { 'user.name': 'John' }); // [{ user: { name: 'John', active: true } }]
+ *
+ * @example
+ * // Array property filtering
+ * const posts = [
+ *   { tags: ['js', 'web'] },
+ *   { tags: ['ts', 'node'] }
+ * ];
+ * ArrayFilter(posts, { tags: 'js' }); // [{ tags: ['js', 'web'] }]
+ *
+ * @example
+ * // Predicate function filtering
+ * const numbers = [1, 2, 3, 4, 5];
+ * ArrayFilter(numbers, (n) => n > 3); // [4, 5]
+ */
+export declare function ArrayFilter<T>(array: T[], criteria: Partial<Record<string, unknown>> | TPredicate<T>): T[];
+//# sourceMappingURL=array-filter.d.ts.map

package/build/array/array-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-filter.d.ts","sourceRoot":"","sources":["../../src/array/array-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAoC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,KAAK,EAAE,CAAC,EAAE,EACV,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GACxD,CAAC,EAAE,CAaL"}

package/build/array/array-filter.js

@@ -0,0 +1,78 @@
+/**
+ * Gets nested property value from an object using dot notation
+ * @param obj - The object to get value from
+ * @param path - The property path (e.g., 'user.name')
+ * @returns The value at the path, or undefined
+ */
+function getNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (const key of keys) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Checks if a value matches the filter criteria
+ * @param value - The value to check
+ * @param filterValue - The filter criteria
+ * @returns true if matches, false otherwise
+ */
+function matchesValue(value, filterValue) {
+    // If value is an array, check if it contains the filter value
+    if (Array.isArray(value)) {
+        return value.includes(filterValue);
+    }
+    // Direct equality check
+    return value === filterValue;
+}
+/**
+ * Filters an array based on criteria that can be an object filter or a predicate function.
+ * Supports nested property filtering with dot notation and array property filtering.
+ *
+ * @param array - The array to filter
+ * @param criteria - Either an object with filter criteria or a predicate function
+ * @returns A new array containing only items that match the criteria
+ *
+ * @example
+ * // Simple property filtering
+ * const users = [{ name: 'John', age: 25 }, { name: 'Jane', age: 30 }];
+ * ArrayFilter(users, { age: 30 }); // [{ name: 'Jane', age: 30 }]
+ *
+ * @example
+ * // Nested property filtering
+ * const profiles = [
+ *   { user: { name: 'John', active: true } },
+ *   { user: { name: 'Jane', active: false } }
+ * ];
+ * ArrayFilter(profiles, { 'user.name': 'John' }); // [{ user: { name: 'John', active: true } }]
+ *
+ * @example
+ * // Array property filtering
+ * const posts = [
+ *   { tags: ['js', 'web'] },
+ *   { tags: ['ts', 'node'] }
+ * ];
+ * ArrayFilter(posts, { tags: 'js' }); // [{ tags: ['js', 'web'] }]
+ *
+ * @example
+ * // Predicate function filtering
+ * const numbers = [1, 2, 3, 4, 5];
+ * ArrayFilter(numbers, (n) => n > 3); // [4, 5]
+ */
+export function ArrayFilter(array, criteria) {
+    // If criteria is a function, use it as predicate
+    if (typeof criteria === 'function') {
+        return array.filter(criteria);
+    }
+    // Object-based filtering with nested support
+    return array.filter((item) => {
+        return Object.entries(criteria).every(([key, filterValue]) => {
+            const itemValue = getNestedValue(item, key);
+            return matchesValue(itemValue, filterValue);
+        });
+    });
+}
+//# sourceMappingURL=array-filter.js.map

package/build/array/array-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-filter.js","sourceRoot":"","sources":["../../src/array/array-filter.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,SAAS,cAAc,CAAC,GAAY,EAAE,IAAY;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,OAAO,GAAQ,GAAG,CAAC;IAEvB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAChE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAc,EAAE,WAAoB;IACzD,8DAA8D;IAC9D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACpC,CAAC;IAED,wBAAwB;IACxB,OAAO,KAAK,KAAK,WAAW,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,WAAW,CAC1B,KAAU,EACV,QAA0D;IAE1D,iDAAiD;IACjD,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,6CAA6C;IAC7C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5B,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE;YAC5D,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC5C,OAAO,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC"}

package/build/array/array-flatten.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Flattens a nested array to a specified depth (default: all levels).
+ *
+ * @template T - The leaf element type
+ * @param array - The nested array to flatten
+ * @param depth - How many levels deep to flatten (default: `Infinity`)
+ * @returns Flattened array of `T`
+ *
+ * @example
+ * ```typescript
+ * ArrayFlatten([1, [2, [3, [4]]]]); // [1, 2, 3, 4]
+ * ArrayFlatten([1, [2, [3]]], 1);   // [1, 2, [3]]
+ * ```
+ */
+export declare function ArrayFlatten<T = unknown>(array: any[], depth?: number): T[];
+//# sourceMappingURL=array-flatten.d.ts.map

package/build/array/array-flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-flatten.d.ts","sourceRoot":"","sources":["../../src/array/array-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAG3E"}

package/build/array/array-flatten.js

@@ -0,0 +1,20 @@
+/**
+ * Flattens a nested array to a specified depth (default: all levels).
+ *
+ * @template T - The leaf element type
+ * @param array - The nested array to flatten
+ * @param depth - How many levels deep to flatten (default: `Infinity`)
+ * @returns Flattened array of `T`
+ *
+ * @example
+ * ```typescript
+ * ArrayFlatten([1, [2, [3, [4]]]]); // [1, 2, 3, 4]
+ * ArrayFlatten([1, [2, [3]]], 1);   // [1, 2, [3]]
+ * ```
+ */
+export function ArrayFlatten(array, depth) {
+    if (!array)
+        return [];
+    return array.flat(depth ?? Infinity);
+}
+//# sourceMappingURL=array-flatten.js.map

package/build/array/array-flatten.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-flatten.js","sourceRoot":"","sources":["../../src/array/array-flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAAc,KAAY,EAAE,KAAc;IACrE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAQ,CAAC;AAC7C,CAAC"}

package/build/array/array-group-by.d.ts

@@ -0,0 +1,13 @@
+import type { TTransform } from './types';
+/**
+ * Groups array elements by a key generated by a provided function.
+ * @param array The array to group.
+ * @param keyFn TTransform function that returns the grouping key for each element.
+ * @returns An object with keys as group names and values as arrays of grouped elements.
+ * @example
+ * const items = [{ category: 'fruit', name: 'apple' }, { category: 'vegetable', name: 'carrot' }];
+ * const grouped = ArrayGroupBy(items, item => item.category);
+ * // grouped.fruit is [{ category: 'fruit', name: 'apple' }]
+ */
+export declare function ArrayGroupBy<T, K extends string | number | symbol>(array: T[], keyFn: TTransform<T, K>): Record<K, T[]>;
+//# sourceMappingURL=array-group-by.d.ts.map

package/build/array/array-group-by.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-group-by.d.ts","sourceRoot":"","sources":["../../src/array/array-group-by.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAavH"}