@pawells/typescript-common 1.1.0 → 1.1.3

package/README.md

@@ -186,124 +186,7 @@ Cross-cutting assertions not tied to a single type, plus the shared assertion in
 
 ```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.
-
-
-## 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 build          # Compile TypeScript (tsconfig.build.json) → ./build/
 yarn dev            # Build + run
 yarn watch          # Watch mode
 yarn typecheck      # Type check without building

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

@@ -1,10 +1,16 @@
 /**
  * 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.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to split
+ * @param size - Size of each chunk (last chunk may be smaller)
+ * @returns Array of arrays, each of the specified size
+ *
  * @example
- * const chunks = ArrayChunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * ```typescript
+ * ArrayChunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * ArrayChunk(['a', 'b', 'c'], 2); // [['a', 'b'], ['c']]
+ * ```
  */
 export declare function ArrayChunk<T>(array: T[], size: number): T[][];
 //# sourceMappingURL=array-chunk.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"array-chunk.d.ts","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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

@@ -1,10 +1,16 @@
 /**
  * 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.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to split
+ * @param size - Size of each chunk (last chunk may be smaller)
+ * @returns Array of arrays, each of the specified size
+ *
  * @example
- * const chunks = ArrayChunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * ```typescript
+ * ArrayChunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ * ArrayChunk(['a', 'b', 'c'], 2); // [['a', 'b'], ['c']]
+ * ```
  */
 export function ArrayChunk(array, size) {
     if (!array || size <= 0) {

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

@@ -1 +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"}
+{"version":3,"file":"array-chunk.js","sourceRoot":"","sources":["../../src/array/array-chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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-contains.d.ts

@@ -1,9 +1,17 @@
 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.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to check
+ * @param predicate - A function that tests each element; returns `true` to signal a match
+ * @returns `true` if at least one element passes the test, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * ArrayContains([1, 2, 3], (n) => n > 2);   // true
+ * ArrayContains([1, 2, 3], (n) => n > 10);  // false
+ * ```
  */
 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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;GAaG;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

@@ -1,8 +1,16 @@
 /**
  * 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.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to check
+ * @param predicate - A function that tests each element; returns `true` to signal a match
+ * @returns `true` if at least one element passes the test, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * ArrayContains([1, 2, 3], (n) => n > 2);   // true
+ * ArrayContains([1, 2, 3], (n) => n > 10);  // false
+ * ```
  */
 export function ArrayContains(array, predicate) {
     if (!array || array.length === 0) {

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

@@ -1 +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"}
+{"version":3,"file":"array-contains.js","sourceRoot":"","sources":["../../src/array/array-contains.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;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-group-by.d.ts

@@ -1,13 +1,22 @@
 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.
+ *
+ * @template T - The type of array elements
+ * @template K - The key type (string, number, or symbol)
+ * @param array - The array to group
+ * @param keyFn - Function that returns the grouping key for each element
+ * @returns A record where each key maps to an array of matching elements
+ *
  * @example
+ * ```typescript
  * const items = [{ category: 'fruit', name: 'apple' }, { category: 'vegetable', name: 'carrot' }];
- * const grouped = ArrayGroupBy(items, item => item.category);
- * // grouped.fruit is [{ category: 'fruit', name: 'apple' }]
+ * ArrayGroupBy(items, (item) => item.category);
+ * // { fruit: [{ category: 'fruit', name: 'apple' }], vegetable: [{ category: 'vegetable', name: 'carrot' }] }
+ *
+ * ArrayGroupBy(['one', 'two', 'three'], (s) => s.length);
+ * // { 3: ['one', 'two'], 5: ['three'] }
+ * ```
  */
 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

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;GAkBG;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"}

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

@@ -1,12 +1,21 @@
 /**
  * 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.
+ *
+ * @template T - The type of array elements
+ * @template K - The key type (string, number, or symbol)
+ * @param array - The array to group
+ * @param keyFn - Function that returns the grouping key for each element
+ * @returns A record where each key maps to an array of matching elements
+ *
  * @example
+ * ```typescript
  * const items = [{ category: 'fruit', name: 'apple' }, { category: 'vegetable', name: 'carrot' }];
- * const grouped = ArrayGroupBy(items, item => item.category);
- * // grouped.fruit is [{ category: 'fruit', name: 'apple' }]
+ * ArrayGroupBy(items, (item) => item.category);
+ * // { fruit: [{ category: 'fruit', name: 'apple' }], vegetable: [{ category: 'vegetable', name: 'carrot' }] }
+ *
+ * ArrayGroupBy(['one', 'two', 'three'], (s) => s.length);
+ * // { 3: ['one', 'two'], 5: ['three'] }
+ * ```
  */
 export function ArrayGroupBy(array, keyFn) {
     if (!array) {

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

@@ -1 +1 @@
-{"version":3,"file":"array-group-by.js","sourceRoot":"","sources":["../../src/array/array-group-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAwC,KAAU,EAAE,KAAuB;IACtG,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAoB,CAAC;IAC7B,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACf,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACf,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO,GAAG,CAAC;IACZ,CAAC,EAAE,EAAoB,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"array-group-by.js","sourceRoot":"","sources":["../../src/array/array-group-by.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAwC,KAAU,EAAE,KAAuB;IACtG,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAoB,CAAC;IAC7B,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACjC,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACf,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACf,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO,GAAG,CAAC;IACZ,CAAC,EAAE,EAAoB,CAAC,CAAC;AAC1B,CAAC"}

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

@@ -1,8 +1,17 @@
 /**
  * Returns a shuffled copy of the array using the Fisher-Yates algorithm.
- * @param array The array to shuffle.
- * @returns A new shuffled array.
- * @note Uses Math.random() — not cryptographically secure. Do not use for security-sensitive operations.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to shuffle
+ * @returns A new shuffled array (original is not mutated)
+ *
+ * @remarks Uses `Math.random()` — not cryptographically secure. Do not use for
+ * security-sensitive operations.
+ *
+ * @example
+ * ```typescript
+ * ArrayShuffle([1, 2, 3, 4, 5]); // e.g. [3, 1, 5, 2, 4]
+ * ```
  */
 export declare function ArrayShuffle<T>(array: T[]): T[];
 //# sourceMappingURL=array-shuffle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"array-shuffle.d.ts","sourceRoot":"","sources":["../../src/array/array-shuffle.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAa/C"}
+{"version":3,"file":"array-shuffle.d.ts","sourceRoot":"","sources":["../../src/array/array-shuffle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAa/C"}

package/build/array/array-shuffle.js

@@ -1,8 +1,17 @@
 /**
  * Returns a shuffled copy of the array using the Fisher-Yates algorithm.
- * @param array The array to shuffle.
- * @returns A new shuffled array.
- * @note Uses Math.random() — not cryptographically secure. Do not use for security-sensitive operations.
+ *
+ * @template T - The type of array elements
+ * @param array - The array to shuffle
+ * @returns A new shuffled array (original is not mutated)
+ *
+ * @remarks Uses `Math.random()` — not cryptographically secure. Do not use for
+ * security-sensitive operations.
+ *
+ * @example
+ * ```typescript
+ * ArrayShuffle([1, 2, 3, 4, 5]); // e.g. [3, 1, 5, 2, 4]
+ * ```
  */
 export function ArrayShuffle(array) {
     if (!array)

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

@@ -1 +1 @@
-{"version":3,"file":"array-shuffle.js","sourceRoot":"","sources":["../../src/array/array-shuffle.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAI,KAAU;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAE1B,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAM,CAAC;QAC3B,MAAM,CAAC,CAAC,CAAC,GAAG,IAAS,CAAC;IACvB,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}
+{"version":3,"file":"array-shuffle.js","sourceRoot":"","sources":["../../src/array/array-shuffle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAI,KAAU;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IAE1B,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAM,CAAC;QAC3B,MAAM,CAAC,CAAC,CAAC,GAAG,IAAS,CAAC;IACvB,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/build/array/unique.d.ts

@@ -1,8 +1,18 @@
 /**
  * Returns a new array with duplicate values removed.
- * @param array The input array.
- * @returns A new array with unique values.
- * @note Uses reference equality for objects. Two distinct objects with identical property values are NOT deduplicated.
+ *
+ * @template T - The type of array elements
+ * @param array - The input array
+ * @returns A new array containing only unique values (preserves first occurrence order)
+ *
+ * @remarks Uses reference equality for objects. Two distinct objects with
+ * identical property values are **not** considered equal and will both be kept.
+ *
+ * @example
+ * ```typescript
+ * Unique([1, 2, 2, 3, 1]); // [1, 2, 3]
+ * Unique(['a', 'b', 'a']); // ['a', 'b']
+ * ```
  */
 export declare function Unique<T>(array: T[]): T[];
 //# sourceMappingURL=unique.d.ts.map

package/build/array/unique.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAMzC"}
+{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAMzC"}

package/build/array/unique.js

@@ -1,8 +1,18 @@
 /**
  * Returns a new array with duplicate values removed.
- * @param array The input array.
- * @returns A new array with unique values.
- * @note Uses reference equality for objects. Two distinct objects with identical property values are NOT deduplicated.
+ *
+ * @template T - The type of array elements
+ * @param array - The input array
+ * @returns A new array containing only unique values (preserves first occurrence order)
+ *
+ * @remarks Uses reference equality for objects. Two distinct objects with
+ * identical property values are **not** considered equal and will both be kept.
+ *
+ * @example
+ * ```typescript
+ * Unique([1, 2, 2, 3, 1]); // [1, 2, 3]
+ * Unique(['a', 'b', 'a']); // ['a', 'b']
+ * ```
  */
 export function Unique(array) {
     if (!array) {

package/build/array/unique.js.map

@@ -1 +1 @@
-{"version":3,"file":"unique.js","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAI,KAAU;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"unique.js","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,MAAM,CAAI,KAAU;IACnC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5B,CAAC"}

package/build/asserts/errors.d.ts

@@ -1,45 +1,129 @@
 /**
- * Base error class for all custom errors
+ * Base error class for all custom errors in the assertion library.
+ *
+ * Extends the built-in `Error` with a machine-readable `Code` string and an
+ * optional `Context` bag for structured diagnostic metadata. All other error
+ * classes in this module extend `BaseError`.
+ *
+ * @example
+ * ```typescript
+ * class MyError extends BaseError {
+ *   constructor(message: string) {
+ *     super(message, 'MY_ERROR');
+ *   }
+ * }
+ * throw new MyError('Something went wrong');
+ * ```
  */
 export declare class BaseError extends Error {
     readonly Code: string;
     readonly Context: Record<string, unknown> | undefined;
+    /**
+     * @param message - Human-readable description of the error
+     * @param code - Machine-readable error code (e.g. `'VALIDATION_ERROR'`)
+     * @param context - Optional structured metadata for diagnostics
+     */
     constructor(message: string, code: string, context?: Record<string, unknown>);
 }
 /**
- * Error thrown when validation fails
+ * Error thrown when input data fails a validation rule.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Email address is not valid', { field: 'email' });
+ * ```
  */
 export declare class ValidationError extends BaseError {
+    /**
+     * @param message - Description of the validation failure
+     * @param context - Optional structured metadata for diagnostics
+     */
     constructor(message: string, context?: Record<string, unknown>);
 }
 /**
- * Error thrown when a type assertion fails
+ * Error thrown when a runtime type assertion fails.
+ *
+ * @example
+ * ```typescript
+ * throw new AssertionError('Expected string but received number');
+ * ```
  */
 export declare class AssertionError extends BaseError {
+    /**
+     * @param message - Description of the failed assertion
+     * @param context - Optional structured metadata for diagnostics
+     */
     constructor(message: string, context?: Record<string, unknown>);
 }
 /**
- * Error thrown when an argument is invalid
+ * Error thrown when a function argument is invalid.
+ * The error message is auto-formatted as
+ * `"Invalid argument '<argumentName>': <reason>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new InvalidArgumentError('userId', 'must be a positive integer');
+ * // message: "Invalid argument 'userId': must be a positive integer"
+ * ```
  */
 export declare class InvalidArgumentError extends BaseError {
+    /**
+     * @param argumentName - Name of the invalid argument
+     * @param reason - Explanation of why the argument is invalid
+     * @param context - Optional structured metadata for diagnostics
+     */
     constructor(argumentName: string, reason: string, context?: Record<string, unknown>);
 }
 /**
- * Error thrown when an operation is not supported
+ * Error thrown when a requested operation is not supported in the current context.
+ * The error message is auto-formatted as `"Operation not supported: <operation>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new NotSupportedError('bulk delete in read-only mode');
+ * // message: "Operation not supported: bulk delete in read-only mode"
+ * ```
  */
 export declare class NotSupportedError extends BaseError {
+    /**
+     * @param operation - Description of the unsupported operation
+     * @param context - Optional structured metadata for diagnostics
+     */
     constructor(operation: string, context?: Record<string, unknown>);
 }
 /**
- * Error thrown when a required value is not found
+ * Error thrown when a required resource or value cannot be found.
+ * The error message is auto-formatted as `"Not found: <item>"`.
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('user with id 42');
+ * // message: "Not found: user with id 42"
+ * ```
  */
 export declare class NotFoundError extends BaseError {
+    /**
+     * @param item - Description of the resource that was not found
+     * @param context - Optional structured metadata for diagnostics
+     */
     constructor(item: string, context?: Record<string, unknown>);
 }
 /**
- * Error thrown when buffer overflow occurs
+ * Error thrown when a buffer or collection exceeds its maximum capacity.
+ * The error message is auto-formatted as
+ * `"Buffer overflow: maximum size <maxSize> exceeded"`.
+ *
+ * @example
+ * ```typescript
+ * throw new BufferOverflowError(1000);
+ * // message: "Buffer overflow: maximum size 1000 exceeded"
+ * ```
  */
 export declare class BufferOverflowError extends BaseError {
+    /**
+     * @param maxSize - The maximum capacity that was exceeded
+     * @param context - Optional structured metadata for diagnostics
+     */
     constructor(maxSize: number, context?: Record<string, unknown>);
 }
 //# sourceMappingURL=errors.d.ts.map

package/build/asserts/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/asserts/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAEjD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAS5E;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBACjC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;gBAChC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACtC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGnF;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;gBACnC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGhE;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,SAAS;gBAC/B,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG3D;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/asserts/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAE7D;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAS5E;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC7C;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC5C;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD;;;;OAIG;gBACS,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGnF;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C;;;OAGG;gBACS,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGhE;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC3C;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG3D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D"}