@pawells/typescript-common 2.0.0 → 2.1.5

package/README.md

@@ -1,288 +1,414 @@
-# TypeScript Common Utilities
+# @pawells/typescript-common
 
-[![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%3D22-brightgreen)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/@pawells/typescript-common.svg)](https://www.npmjs.com/package/@pawells/typescript-common)
 [![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.
+## Description
+
+Shared TypeScript utility library providing strongly-typed, well-tested utility functions across eight domains: array, asserts, boolean, enum, function, lru-cache, object, string, and time. All functions are documented with JSDoc, fully typed, and tested to 80% coverage across all metrics.
+
+## Requirements
+
+- **Node.js**: 22.0.0 or later
+- **TypeScript**: 6.0.0 or later (if consuming from source)
+
+### Local Development
+
+During local development, the package exports a `local` condition that resolves to TypeScript source directly without requiring a build step. This enables fast iteration when developing consuming packages.
+
+To use the local condition in your `tsconfig.json`, ensure your resolver is configured to recognize the `@pawells/typescript-common-workspace` condition:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "customConditions": ["@pawells/typescript-common-workspace"]
+  }
+}
+```
 
 ## Installation
 
+Install from npm:
+
 ```bash
 npm install @pawells/typescript-common
-# or
+```
+
+Or with yarn:
+
+```bash
 yarn add @pawells/typescript-common
 ```
 
-## Usage
+## Quick Start
+
+All exports are available from the main entry point or from domain-specific entry points for tree-shaking.
 
-All utilities are available as namespace imports or as individual named exports for tree-shaking.
+### Array Domain
 
 ```typescript
-// Namespace import
-import {
-  ArrayUtils, BooleanUtils, NumberUtils,
-  ObjectUtils, StringUtils, TimeUtils,
-  EnumUtils, FunctionUtils, AssertsUtils,
-} from '@pawells/typescript-common';
+import { ArrayChunk, ArrayFilter, ArrayShuffle, Unique } from '@pawells/typescript-common';
 
-ArrayUtils.ArrayChunk([1, 2, 3, 4], 2); // [[1, 2], [3, 4]]
-ArrayUtils.AssertArray(value);           // throws if not an array
-ObjectUtils.IsObject(value);             // returns true/false (type-guard)
-BooleanUtils.AssertBoolean(value);       // throws if not a boolean
-NumberUtils.AssertNumber(value, { gte: 0, integer: true });
+const items = [1, 2, 3, 4, 5];
+const chunked = ArrayChunk(items, 2); // [[1, 2], [3, 4], [5]]
 
-// Direct named import (tree-shakeable)
-import { ArrayChunk, ObjectPick, KebabCase, Sleep, AssertString, LRUCache } from '@pawells/typescript-common';
-```
+const filtered = ArrayFilter([1, 2, 3, 4], (x) => x > 2); // [3, 4]
 
-## Features & Patterns
+const shuffled = ArrayShuffle([1, 2, 3]); // Random order
 
-### Readonly Array Support
+const unique = Unique([1, 2, 2, 3]); // [1, 2, 3]
+```
 
-All array utilities accept `readonly T[]` arrays, enabling zero-copy usage with frozen constants:
+### Asserts Domain
 
 ```typescript
-const colors = Object.freeze(['red', 'green', 'blue']); // readonly string[]
-ArrayChunk(colors, 2); // Works without casting!
-ArrayFilter(colors, c => c.length > 3); // ✓ No type errors
-```
+import { AssertString, AssertNumber, AssertArray } from '@pawells/typescript-common';
 
-### Custom RNG for Deterministic Testing
+AssertString(value); // Throws if value is not a string
+AssertNumber(42); // Passes
+AssertArray([1, 2, 3]); // Passes
+```
 
-`ArraySample` and `ArrayShuffle` accept an optional custom RNG function for reproducible randomization:
+### Boolean Domain
 
 ```typescript
-const seededRng = Mulberry32(42); // Your seeded PRNG
-ArrayShuffle([1, 2, 3], seededRng); // Same output every time
-ArraySample([1, 2, 3], 2, seededRng); // Deterministic sampling
+import { AssertBoolean } from '@pawells/typescript-common';
 
-// Without RNG, defaults to Math.random() for normal usage
-ArrayShuffle([1, 2, 3]); // Random shuffle
+AssertBoolean(true); // Passes
+AssertBoolean('not a boolean'); // Throws
 ```
 
-### Predicate Functions in ObjectFilter
+### Enum Domain
 
-Filter by predicate functions in addition to equality checks:
+```typescript
+import { EnumKeys, EnumValues, ValidateEnumValue, EnumSafeValue } from '@pawells/typescript-common';
+
+enum Color {
+  Red = 'RED',
+  Green = 'GREEN',
+  Blue = 'BLUE',
+}
+
+const keys = EnumKeys(Color); // ['Red', 'Green', 'Blue']
+const values = EnumValues(Color); // ['RED', 'GREEN', 'BLUE']
+const isValid = ValidateEnumValue(Color, 'RED'); // true
+const safe = EnumSafeValue(Color, 'INVALID', Color.Red); // Color.Red
+```
+
+### Function Domain
 
 ```typescript
-const user = { name: 'John', age: 30, active: true };
-
-// Basic equality filtering
-ObjectFilter(user, { name: 'John' }); // true
-
-// Predicate functions as filter values
-ObjectFilter(user, { age: (v) => v > 18 }); // true
-ObjectFilter(user, { age: (v) => v < 18 }); // false
-
-// Mix predicates and values
-ObjectFilter(user, {
-  active: true,
-  age: (v) => v >= 21
-}); // true
-
-// Supports dot notation with predicates
-const order = { user: { age: 25 }, total: 100 };
-ObjectFilter(order, {
-  'user.age': (v) => v >= 21,
-  'total': (v) => v > 50
-}); // true
+import { Memoize, Debounce, Throttle, Once, Compose } from '@pawells/typescript-common';
+
+// Memoization
+const expensiveCalc = Memoize((n: number) => n * n);
+expensiveCalc(4); // Computed: 16
+expensiveCalc(4); // Cached: 16
+
+// Debouncing
+const handleSearch = Debounce((query: string) => console.log(query), 300);
+handleSearch('a');
+handleSearch('ab');
+handleSearch('abc'); // Only this logs after 300ms
+
+// Throttling
+const handleResize = Throttle(() => console.log('resized'), 100);
+
+// Single execution
+const initialize = Once(() => console.log('init'));
+initialize(); // logs
+initialize(); // no-op
+
+// Function composition
+const add = (x: number) => x + 1;
+const double = (x: number) => x * 2;
+const composed = Compose(double, add);
+composed(5); // (5 + 1) * 2 = 12
 ```
 
-## API
+### LRU Cache Domain
 
-### Array utilities — `ArrayUtils`
+```typescript
+import { LRUCache } from '@pawells/typescript-common';
 
-| 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, rng?)` | Return a shuffled copy of an array (optional custom RNG for deterministic results) |
-| `ArraySample(array, n?, rng?)` | Random element or `n` random elements (optional custom RNG for deterministic results) |
-| `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 |
-| `AssertArray(value, args?, exception?)` | Assert value is an array (with optional size constraints) |
-| `AssertArray2D(value, args?, exception?)` | Assert value is a rectangular 2D array |
-| `AssertArrayNotEmpty(value, exception?)` | Assert array has at least one element |
-| `AssertArrayAll(array, predicate, exception?)` | Assert every element satisfies a predicate |
-| `AssertArrayAny(array, predicate, exception?)` | Assert at least one element satisfies a predicate |
-
-### Boolean utilities — `BooleanUtils`
-
-| Export | Description |
-|--------|-------------|
-| `AssertBoolean(value, exception?)` | Assert value is a boolean primitive |
+const cache = new LRUCache<string, number>(2);
+cache.set('a', 1);
+cache.set('b', 2);
+cache.set('c', 3); // Evicts 'a' (least recently used)
 
-### Number utilities — `NumberUtils`
+console.log(cache.get('a')); // undefined
+console.log(cache.get('b')); // 2
+```
 
-| Export | Description |
-|--------|-------------|
-| `AssertNumber(value, args?, exception?)` | Assert value is a number with optional range/type constraints (`finite`, `integer`, `gt`, `gte`, `lt`, `lte`, `eq`) |
+### Number Domain
 
-### Object utilities — `ObjectUtils`
+```typescript
+import { AssertNumber, AssertFinite } from '@pawells/typescript-common';
 
-| Export | Description |
-|--------|-------------|
-| `IsObject(value)` | Type-guard: returns `true` if value is a non-null, non-array object |
-| `ObjectClone(obj)` | Deep-clone an object |
-| `ObjectEquals(a, b)` | Deep equality check |
-| `ObjectFilter(obj, filter, options?)` | Filter object by property values or predicate functions (supports dot notation, deep equality, case-insensitive matching, and predicate functions) |
-| `ObjectFilterCached(options?)` | Returns a cached filter function for repeated filtering operations with optional deep equality and case-insensitive matching |
-| `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 |
-| `MapObjectCached(options?)` | Returns a cached map function for repeated mapping operations with optional async support |
-| `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 |
-| `ObjectHasCircularReference(obj)` | Detect circular references in an object |
-| `CreateJsonCircularReplacer(placeholder?)` | Create a `JSON.stringify` replacer that handles circular refs |
-| `AssertObject(value, exception?)` | Assert value is a plain object (not null, array, or function), narrowing to `Record<string, unknown>` |
-| `AssertObjectHasProperty(value, property, exception?)` | Assert object has an inherited or own property |
-| `AssertObjectHasOwnProperty(value, property, exception?)` | Assert object has a direct own property |
-| `AssertObjectPropertyNotNull(value, property, exception?)` | Assert object property is not null/undefined |
-
-### String utilities — `StringUtils`
-
-| Export | Description |
-|--------|-------------|
-| `CamelCase(str)` | Convert a string to camelCase |
-| `Capitalize(str)` | Capitalize the first letter of a string |
-| `PascalCase(str)` | Convert a string to PascalCase |
-| `KebabCase(str)` | Convert a string to kebab-case |
-| `SnakeCase(str)` | Convert a string to snake_case |
-| `ScreamingSnakeCase(str)` | Convert a string to SCREAMING_SNAKE_CASE |
-| `FormatString(template, values)` | Simple string template formatting |
-| `TruncateString(str, maxLength, ellipsis?)` | Truncate a string with ellipsis |
-| `PadString(str, length, char?, padEnd?)` | Pad a string to a specified length |
-| `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 |
-| `ReverseString(str)` | Reverse a string |
-| `Slugify(str)` | Convert a string to a URL-friendly slug |
-| `IsBlankString(str)` | Check if a string is empty or whitespace-only |
-| `IsHexString(str)` | Check if a string is a valid hexadecimal value |
-| `StringEquals(a, b, caseInsensitive?)` | Compare two strings with optional case-insensitive matching |
-| `AssertString(value, exception?)` | Assert value is a string primitive |
-| `AssertStringNotEmpty(value, exception?)` | Assert value is a non-empty, non-whitespace string |
-| `AssertStringMatches(value, regex, exception?)` | Assert string matches a regular expression |
-
-### Time utilities — `TimeUtils`
-
-| Export | Description |
-|--------|-------------|
-| `ElapsedTime` | Class for measuring elapsed time with human-readable output |
-| `FormatElapsedTime(ms, options?)` | Format milliseconds using concise format |
-| `Stopwatch` | Lap-based stopwatch for benchmarking |
+AssertNumber(42); // Passes
+AssertNumber('not a number'); // Throws
+```
 
-### Enum utilities — `EnumUtils`
+### Object Domain
 
-| 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` |
+```typescript
+import {
+  ObjectClone,
+  ObjectEquals,
+  ObjectFilter,
+  ObjectPick,
+  ObjectOmit,
+  ObjectMerge,
+  ObjectHash,
+} from '@pawells/typescript-common';
 
-### Function utilities — `FunctionUtils`
+const original = { a: 1, b: { c: 2 } };
+const cloned = ObjectClone(original);
 
-| 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 |
+const obj1 = { x: 1 };
+const obj2 = { x: 1 };
+console.log(ObjectEquals(obj1, obj2)); // true
 
-### LRU Cache — `LRUCache`
+const filtered = ObjectFilter({ a: 1, b: 2, c: 3 }, (v) => v > 1); // { b: 2, c: 3 }
 
-| Export | Description |
-|--------|-------------|
-| `LRUCache<K, V>` | Generic Least Recently Used cache with configurable capacity |
+const picked = ObjectPick({ a: 1, b: 2, c: 3 }, ['a', 'b']); // { a: 1, b: 2 }
+
+const omitted = ObjectOmit({ a: 1, b: 2, c: 3 }, ['c']); // { a: 1, b: 2 }
+
+const merged = ObjectMerge({ a: 1 }, { b: 2 }); // { a: 1, b: 2 }
+
+const hash = ObjectHash({ a: 1, b: 2 }); // 'e4f3...'
+```
+
+### String Domain
 
 ```typescript
-const cache = new LRUCache<string, number>(100);
-cache.set('key', 42);
-cache.get('key'); // 42 (marks as recently used)
-cache.has('key'); // true
-cache.clear();    // removes all entries
+import {
+  CamelCase,
+  PascalCase,
+  KebabCase,
+  SnakeCase,
+  EscapeHTML,
+  TruncateString,
+  StringEquals,
+} from '@pawells/typescript-common';
+
+console.log(CamelCase('hello-world')); // 'helloWorld'
+console.log(PascalCase('hello-world')); // 'HelloWorld'
+console.log(KebabCase('helloWorld')); // 'hello-world'
+console.log(SnakeCase('helloWorld')); // 'hello_world'
+
+console.log(EscapeHTML('<script>alert("xss")</script>')); // '&lt;script&gt;...'
+
+console.log(TruncateString('Hello World', 8)); // 'Hello...'
+
+console.log(StringEquals('hello', 'HELLO', true)); // true (case-insensitive)
 ```
 
-### Assertion utilities — `AssertsUtils`
+### Time Domain
 
-Cross-cutting assertions not tied to a single type, plus the shared assertion infrastructure.
+```typescript
+import { ElapsedTime, Stopwatch } from '@pawells/typescript-common';
+
+// Elapsed time value object
+const elapsed = new ElapsedTime(5000); // 5 seconds
+console.log(elapsed.seconds()); // 5
+console.log(elapsed.toString()); // '5.00s'
+
+// Stopwatch for timing events
+const stopwatch = new Stopwatch();
+stopwatch.start();
+// ... do work ...
+stopwatch.stop();
+console.log(stopwatch.elapsed().toString()); // Duration of work
+```
 
-| Export | Description |
-|--------|-------------|
-| `AssertEquals(value, expected, exception?)` | Assert two values are deeply equal |
-| `AssertNotEquals(value, expected, exception?)` | Assert two values are not deeply equal |
-| `AssertNull(value, exception?)` | Assert value is `null` or `undefined` |
-| `AssertNotNull(value, exception?)` | Assert value is neither `null` nor `undefined` |
-| `AssertPredicate(value, predicate, exception?)` | Assert a custom predicate holds |
-| `AssertIsType(value, typeGuard, exception?)` | Assert via a type-guard function |
-| `AssertInstanceOf(value, constructor, exception?)` | Assert value is an instance of a constructor |
-| `AssertFunction(value, exception?)` | Assert value is a function |
-| `AssertSymbol(value, exception?)` | Assert value is a symbol |
-| `AssertExtends(derived, base, exception?)` | Assert one class extends another |
-| `ThrowException(exception)` | Throw using an `IAssertException` config object |
-| `SetExceptionClass(exception, class, force?)` | Configure the error class for an assertion |
-| `SetExceptionMessage(exception, message, force?)` | Configure the error message for an assertion |
+## API Reference
 
-**All type-specific assertions** (`AssertArray`, `AssertBoolean`, `AssertNumber`, `AssertObject` (throwing), `AssertString`, etc.) are also accessible through `AssertsUtils` as a single convenience namespace.
+### Array
 
-**Note:** `AssertObject` is a throwing assertion available in both `ObjectUtils` and `AssertsUtils` (narrows to `Record<string, unknown>`). Use `ObjectUtils.IsObject` for a non-throwing boolean type-guard that returns `true`/`false`.
+| Symbol | Description |
+|--------|-------------|
+| `ArrayChunk` | Splits an array into fixed-size chunks |
+| `ArrayCompact` | Removes null and undefined values from an array |
+| `ArrayContains` | Checks if array contains element matching predicate |
+| `ArrayDifference` | Returns elements in first array but not in second |
+| `ArrayFilter` | Filters array by object criteria or predicate function |
+| `ArrayFlatten` | Flattens nested arrays to specified depth |
+| `ArrayGroupBy` | Groups array elements by a key function |
+| `ArrayIntersection` | Returns elements present in all arrays |
+| `ArrayPartition` | Splits array into two based on predicate |
+| `ArrayRange` | Generates array of numbers in range |
+| `ArraySample` | Returns random element(s) from array |
+| `ArrayShuffle` | Returns shuffled copy of array |
+| `ArraySortBy` | Sorts array by key function with optional comparator |
+| `ArrayCountBy` | Counts elements grouped by key function |
+| `ArrayZip` | Combines multiple arrays element-wise |
+| `Unique` | Returns array with duplicate elements removed |
+| `TPredicate` | Type for predicate function: `(value: T) => boolean` |
+| `TTransform` | Type for transform function: `(input: T) => U` |
+| `TComparator` | Type for comparator: `(a: T, b: T) => number` |
+| `TEqualityComparator` | Type for equality: `(a: T, b: T) => boolean` |
+
+### Asserts
+
+| Symbol | Description |
+|--------|-------------|
+| `AssertEquals` | Asserts two values are strictly equal |
+| `AssertNotEquals` | Asserts two values are not strictly equal |
+| `AssertNull` | Asserts value is null |
+| `AssertNotNull` | Asserts value is not null |
+| `AssertPredicate` | Asserts value satisfies predicate function |
+| `AssertIsType` | Asserts value is of specific type |
+| `AssertInstanceOf` | Asserts value is instance of class/constructor |
+| `AssertFunction` | Asserts value is a function |
+| `AssertSymbol` | Asserts value is a symbol |
+| `AssertExtends` | Asserts value extends interface type |
+| `AssertArray` | Asserts value is an array |
+| `AssertBoolean` | Asserts value is a boolean |
+| `AssertNumber` | Asserts value is a number |
+| `AssertFinite` | Asserts value is a finite number |
+| `AssertObject` | Asserts value is a plain object |
+| `AssertString` | Asserts value is a string |
+| `AssertStringNotEmpty` | Asserts value is non-empty string |
+| `AssertObjectHasProperty` | Asserts object has property (including inherited) |
+| `AssertObjectHasOwnProperty` | Asserts object has own property |
+| `NullError` | Custom error for null assertion failure |
+| `NotNullError` | Custom error for not-null assertion failure |
+| `PredicateError` | Custom error for predicate assertion failure |
+| `TypeGuardError` | Custom error for type guard assertion failure |
+| `InstanceOfError` | Custom error for instanceof assertion failure |
+| `ExtendsError` | Custom error for type extends assertion failure |
+
+### Boolean
+
+| Symbol | Description |
+|--------|-------------|
+| `AssertBoolean` | Asserts value is a boolean |
 
-#### Error classes
+### Enum
 
-`BaseError`, `ValidationError`, `AssertionError`, `InvalidArgumentError`, `NotFoundError`, `NotSupportedError`, `BufferOverflowError`, `ArrayError`, `BooleanError`, `NumberError`, `NumberRangeError`, `ObjectError`, `ObjectPropertyError`, `StringError`, `NullError`, `NotNullError`, `PredicateError`, `TypeGuardError`, `InstanceOfError`, `FunctionError`, `SymbolError`, `ExtendsError`.
+| Symbol | Description |
+|--------|-------------|
+| `EnumKeys` | Returns array of enum keys |
+| `EnumValues` | Returns array of enum values |
+| `EnumEntries` | Returns array of [key, value] tuples |
+| `EnumKeyByValue` | Looks up enum key by value |
+| `ValidateEnumValue` | Checks if value is valid enum member |
+| `EnumSafeValue` | Returns value if valid enum member, else fallback |
 
-## Development
+### Function
 
-```bash
-yarn install        # Install dependencies
-yarn build          # Compile TypeScript (tsconfig.build.json) → ./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
-```
+| Symbol | Description |
+|--------|-------------|
+| `Debounce` | Delays function execution until after time period with no calls |
+| `Throttle` | Limits function execution to at most once per time period |
+| `Memoize` | Caches function results by serialized arguments (LRU eviction) |
+| `Once` | Returns wrapper that executes function at most once |
+| `Compose` | Creates right-to-left function composition |
+| `Sleep` | Returns promise that resolves after delay |
+
+> **⚠️ Security Warning — Memoize**
+>
+> Do not memoize functions with sensitive parameters (passwords, tokens, API keys). The cache stores return values keyed by serialized arguments, which could expose sensitive data if the cache is inspected or if the key function inadvertently includes sensitive data.
+>
+> For functions handling sensitive data, consider:
+> - Not memoizing at all
+> - Using a custom key function that excludes sensitive parameters
+> - Implementing manual cache invalidation after processing sensitive data
+>
+> See JSDoc `@warning` in source for full details.
+
+### LRU Cache
+
+| Symbol | Description |
+|--------|-------------|
+| `LRUCache` | Generic Least Recently Used cache with fixed capacity |
+
+> **⚠️ Security Warning — LRU Cache**
+>
+> Do not cache sensitive objects (API keys, tokens, passwords, PII). Cache entries remain in memory until evicted or cleared. If the cache is inspected (via debugger, memory dump, or compromised process), sensitive values will be exposed.
+>
+> For sensitive data, prefer:
+> - Ephemeral processing without caching
+> - Implementing automatic expiration
+> - Secure clearing (e.g., overwrite before eviction)
+>
+> See JSDoc `@warning` in source for full details.
+
+### Number
+
+| Symbol | Description |
+|--------|-------------|
+| `AssertNumber` | Asserts value is a number |
+| `AssertFinite` | Asserts value is a finite number |
 
-## Requirements
+### Object
 
-- Node.js >= 22.0.0
+| Symbol | Description |
+|--------|-------------|
+| `ObjectClone` | Deep clones object with circular reference detection |
+| `TransformObject` | Transforms object using visitor pattern |
+| `ObjectEquals` | Deep equality comparison for objects |
+| `ObjectFilter` | Filters object properties by predicate |
+| `FilterObject` | Variant of ObjectFilter |
+| `ObjectFilterCached` | Filters object with caching |
+| `MapObject` | Maps object values by transform function |
+| `MapObjectCached` | Maps object with caching |
+| `ObjectHash` | Generates hash for object |
+| `ObjectGetPropertyByPath` | Gets property value by dot-notation path |
+| `ObjectSetPropertyByPath` | Sets property value by dot-notation path |
+| `ObjectSortKeys` | Returns object with keys sorted |
+| `ObjectFromKeyValuePairs` | Creates object from [key, value] tuples |
+| `ObjectToKeyValuePairs` | Converts object to [key, value] tuples |
+| `ObjectPick` | Returns new object with selected keys |
+| `ObjectOmit` | Returns new object without selected keys |
+| `ObjectMerge` | Shallowly merges objects |
+| `IsObject` | Type guard for plain objects |
+| `ObjectInvert` | Inverts object keys and values |
+| `ObjectFlatten` | Flattens nested object to dot-notation keys |
+| `ObjectDiff` | Computes differences between two objects |
+| `ObjectHasCircularReference` | Detects circular references |
+| `CreateJsonCircularReplacer` | Creates replacer for JSON.stringify with circular refs |
+| `IsPropertyKeySafe` | Checks if property key is safe (not prototype-pollution) |
+| `IsPropertyPathSafe` | Checks if property path is safe |
+| `SanitizePropertyKey` | Removes dangerous characters from key |
+| `FilterDangerousKeys` | Filters dangerous keys from object |
+| `CreateCircularReferenceDetector` | Creates detector for circular references |
+| `IsInputSafe` | Comprehensive input safety check |
+
+### String
+
+| Symbol | Description |
+|--------|-------------|
+| `CamelCase` | Converts string to camelCase |
+| `PascalCase` | Converts string to PascalCase |
+| `KebabCase` | Converts string to kebab-case |
+| `SnakeCase` | Converts string to snake_case |
+| `EscapeHTML` | Escapes HTML special characters |
+| `StripHTML` | Removes HTML tags from string |
+| `FormatString` | Formats string using template parameters |
+| `TruncateString` | Truncates string to max length with ellipsis |
+| `PadString` | Pads string to length with character |
+| `Pluralize` | Returns plural form based on count |
+| `WordCount` | Counts words in string |
+| `CountOccurrences` | Counts occurrences of substring |
+| `StringEquals` | Case-sensitive or case-insensitive equality |
+| `IsEmpty` | Checks if string is empty or whitespace only |
+| `AssertString` | Asserts value is a string |
+| `AssertStringNotEmpty` | Asserts value is non-empty string |
+
+### Time
+
+| Symbol | Description |
+|--------|-------------|
+| `ElapsedTime` | Value object representing duration in milliseconds |
+| `Stopwatch` | Utility for recording timestamped events and intervals |
+| `StopwatchEntry` | Represents single stopwatch event (start, stop, lap, etc.) |
 
 ## License
 
-MIT — See [LICENSE](./LICENSE) for details.
+MIT — See [LICENSE](../../LICENSE) for details.

package/{build → dist}/array/array-chunk.d.ts

@@ -4,7 +4,7 @@
  * @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
+ * @returns Array of arrays, each of the specified size. Returns `[]` if `array` is `null`, `undefined`, or `size` is not positive.
  *
  * @example
  * ```typescript