@simplysm/core-common 14.0.4 → 14.0.6

package/docs/array-extensions.md

@@ -1,96 +1,98 @@
-# Array / Set / Map Extensions
+# Array Extensions
 
-Prototype extensions added to `Array`, `Set`, and `Map` at import time. Importing `@simplysm/core-common` automatically installs these extensions.
+Prototype extensions added to both `Array` and `ReadonlyArray`. Available after importing `@simplysm/core-common`.
 
-## Array -- Readonly Extensions
+Also exports helper functions and result types.
 
-These methods return new arrays/values without mutating the original.
+## ReadonlyArray Extensions
 
-### `single(predicate?)`
+These methods do not mutate the original array.
 
-Returns the single matching element, or `undefined` if none. Throws `ArgumentError` if more than one element matches.
+### `single`
+
+Return the single element matching the predicate. Returns `undefined` if no match. Throws `ArgumentError` if more than one element matches.
 
 ```typescript
 single(predicate?: (item: T, index: number) => boolean): T | undefined;
 ```
 
-### `first(predicate?)`
+### `first`
 
-Returns the first matching element, or `undefined` if none.
+Return the first element, or the first element matching the predicate.
 
 ```typescript
 first(predicate?: (item: T, index: number) => boolean): T | undefined;
 ```
 
-### `last(predicate?)`
+### `last`
 
-Returns the last matching element, or `undefined` if none.
+Return the last element, or the last element matching the predicate.
 
 ```typescript
 last(predicate?: (item: T, index: number) => boolean): T | undefined;
 ```
 
-### `filterAsync(predicate)`
+### `filterExists`
 
-Async sequential filter.
+Remove all `null` and `undefined` elements.
 
 ```typescript
-filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
+filterExists(): NonNullable<T>[];
 ```
 
-### `filterExists()`
+### `ofType`
 
-Removes `null` and `undefined` elements. Returns `NonNullable<T>[]`.
+Filter elements by type. Accepts a `PrimitiveTypeStr` (e.g., `"string"`, `"DateTime"`) or a constructor function.
 
 ```typescript
-filterExists(): NonNullable<T>[];
+ofType<TKey extends PrimitiveTypeStr>(type: TKey): Extract<T, PrimitiveTypeMap[TKey]>[];
+ofType<TNarrow extends T>(type: Type<TNarrow>): TNarrow[];
 ```
 
-### `ofType(type)`
+### `filterAsync`
 
-Filters elements by type. Accepts a `PrimitiveTypeStr` (`"string"`, `"number"`, `"boolean"`, `"DateTime"`, `"DateOnly"`, `"Time"`, `"Uuid"`, `"Bytes"`) or a constructor function.
+Async sequential filter. Evaluates the predicate for each element in order.
 
 ```typescript
-ofType<K extends PrimitiveTypeStr>(type: K): Extract<T, PrimitiveTypeMap[K]>[];
-ofType<N extends T>(type: Type<N>): N[];
+filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
 ```
 
-### `mapAsync(selector)`
+### `mapAsync`
 
-Async sequential map.
+Async sequential map. Evaluates the selector for each element in order.
 
 ```typescript
 mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
 ```
 
-### `mapMany(selector?)`
+### `mapMany`
 
-Maps then flattens one level. Removes `null`/`undefined` from results.
+Flatten a nested array, or map then flatten. Filters out null/undefined from the result.
 
 ```typescript
 mapMany(): T extends readonly (infer U)[] ? U[] : T;
 mapMany<R>(selector: (item: T, index: number) => R[]): R[];
 ```
 
-### `mapManyAsync(selector?)`
+### `mapManyAsync`
 
-Async version of `mapMany`.
+Async map then flatten.
 
 ```typescript
 mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
 ```
 
-### `parallelAsync(fn)`
+### `parallelAsync`
 
-Runs `fn` for all items in parallel via `Promise.all`. If any rejects, the entire result rejects.
+Parallel async map using `Promise.all`. All promises run concurrently.
 
 ```typescript
 parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
 ```
 
-### `groupBy(keySelector, valueSelector?)`
+### `groupBy`
 
-Groups items by key. Supports both primitive keys (O(n) via Map) and object keys (O(n^2) via deep equality).
+Group elements by a key selector. Supports object keys via deep comparison (O(n^2)). Primitive keys use Map-based O(n) lookup.
 
 ```typescript
 groupBy<K>(keySelector: (item: T, index: number) => K): { key: K; values: T[] }[];
@@ -100,9 +102,9 @@ groupBy<K, V>(
 ): { key: K; values: V[] }[];
 ```
 
-### `toMap(keySelector, valueSelector?)`
+### `toMap`
 
-Converts array to `Map`. Throws `ArgumentError` on duplicate keys.
+Convert to a `Map`. Throws `ArgumentError` on duplicate keys.
 
 ```typescript
 toMap<K>(keySelector: (item: T, index: number) => K): Map<K, T>;
@@ -112,7 +114,7 @@ toMap<K, V>(
 ): Map<K, V>;
 ```
 
-### `toMapAsync(keySelector, valueSelector?)`
+### `toMapAsync`
 
 Async version of `toMap`.
 
@@ -124,9 +126,9 @@ toMapAsync<K, V>(
 ): Promise<Map<K, V>>;
 ```
 
-### `toArrayMap(keySelector, valueSelector?)`
+### `toArrayMap`
 
-Converts array to `Map<K, V[]>` (groups values into arrays per key).
+Convert to a `Map<K, V[]>`. Multiple items with the same key are grouped into an array.
 
 ```typescript
 toArrayMap<K>(keySelector: (item: T, index: number) => K): Map<K, T[]>;
@@ -136,9 +138,9 @@ toArrayMap<K, V>(
 ): Map<K, V[]>;
 ```
 
-### `toSetMap(keySelector, valueSelector?)`
+### `toSetMap`
 
-Converts array to `Map<K, Set<V>>`.
+Convert to a `Map<K, Set<V>>`.
 
 ```typescript
 toSetMap<K>(keySelector: (item: T, index: number) => K): Map<K, Set<T>>;
@@ -148,9 +150,9 @@ toSetMap<K, V>(
 ): Map<K, Set<V>>;
 ```
 
-### `toMapValues(keySelector, valueSelector)`
+### `toMapValues`
 
-Groups by key, then applies `valueSelector` to the group array to produce the final value.
+Group by key, then aggregate each group's items using a value selector.
 
 ```typescript
 toMapValues<K, V>(
@@ -159,9 +161,9 @@ toMapValues<K, V>(
 ): Map<K, V>;
 ```
 
-### `toObject(keySelector, valueSelector?)`
+### `toObject`
 
-Converts array to a plain object. Throws `ArgumentError` on duplicate keys.
+Convert to a plain object `Record<string, V>`. Throws `ArgumentError` on duplicate keys.
 
 ```typescript
 toObject(keySelector: (item: T, index: number) => string): Record<string, T>;
@@ -171,68 +173,70 @@ toObject<V>(
 ): Record<string, V>;
 ```
 
-### `toTree(keyProp, parentKey)`
+### `toTree`
 
-Converts a flat array to a tree structure. Items where `parentKey` is `null`/`undefined` become roots. O(n) complexity.
+Convert a flat array to a tree structure. Items where `parentKey` is null/undefined become root nodes. Uses O(n) Map-based indexing internally.
 
 ```typescript
 toTree<K extends keyof T, P extends keyof T>(keyProp: K, parentKey: P): TreeArray<T>[];
 ```
 
-```typescript
-const items = [
-  { id: 1, parentId: undefined, name: "root" },
-  { id: 2, parentId: 1, name: "child" },
-];
-const tree = items.toTree("id", "parentId");
-// [{ id: 1, name: "root", children: [{ id: 2, name: "child", children: [] }] }]
-```
-
-### `distinct(options?)`
+### `distinct`
 
-Returns a new array with duplicates removed.
+Remove duplicates (returns a new array).
 
 ```typescript
-distinct(options?: boolean | {
-  matchAddress?: boolean;
-  keyFn?: (item: T) => string | number;
-}): T[];
+distinct(
+  options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number },
+): T[];
 ```
 
 | Option | Description |
 |--------|-------------|
-| `true` or `{ matchAddress: true }` | Use reference equality (Set-based, O(n)) |
-| `{ keyFn }` | Use custom key function (O(n)) |
-| No options | Deep equality comparison (O(n^2) for objects) |
+| `true` or `{ matchAddress: true }` | Reference equality (Set-based, O(n)) |
+| `{ keyFn }` | Custom key function (O(n)) |
+| Default (no options) | Deep equality for objects (O(n^2)), type-based for primitives (O(n)) |
 
-### `orderBy(selector?)` / `orderByDesc(selector?)`
+### `orderBy`
 
-Returns a sorted copy. Supports `string`, `number`, `DateTime`, `DateOnly`, `Time`.
+Sort ascending (returns a new array). Supports `string`, `number`, `DateTime`, `DateOnly`, `Time`.
 
 ```typescript
 orderBy(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+```
+
+### `orderByDesc`
+
+Sort descending (returns a new array).
+
+```typescript
 orderByDesc(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
 ```
 
-### `diffs(target, options?)`
+### `diffs`
 
-Compares two arrays and returns INSERT/DELETE/UPDATE diff results.
+Compare this array (source) with a target array. Returns a list of insert/delete/update operations.
 
 ```typescript
-diffs<P>(target: P[], options?: {
-  keys?: string[];
-  excludes?: string[];
-}): ArrayDiffsResult<T, P>[];
+diffs<P>(target: P[]): ArrayDiffsResult<T, P>[];
+diffs<P extends Record<string, unknown>>(
+  target: P[],
+  options: { keys: string[]; excludes?: string[] },
+): ArrayDiffsResult<T, P>[];
+diffs<P extends Record<string, unknown>>(
+  target: P[],
+  options: { excludes: string[] },
+): ArrayDiffsResult<T, P>[];
 ```
 
-Result items:
-- `{ source: T, target: undefined }` -- item exists only in source (DELETE)
-- `{ source: undefined, target: P }` -- item exists only in target (INSERT)
-- `{ source: T, target: P }` -- item exists in both but differs (UPDATE)
+| Option | Description |
+|--------|-------------|
+| `keys` | Properties to use for matching source to target items |
+| `excludes` | Properties to ignore in equality comparison |
 
-### `oneWayDiffs(orgItems, keyPropNameOrGetValFn, options?)`
+### `oneWayDiffs`
 
-One-way diff: compares current array against original items.
+One-way diff: compare this array against original items. Returns create/update/same results.
 
 ```typescript
 oneWayDiffs<K extends keyof T>(
@@ -242,160 +246,124 @@ oneWayDiffs<K extends keyof T>(
 ): ArrayOneWayDiffResult<T>[];
 ```
 
-Result types: `"create"`, `"update"`, `"same"` (only if `includeSame: true`).
+### `merge`
 
-### `merge(target, options?)`
-
-Merges two arrays using deep merge on matched items and appends unmatched target items.
+Merge this array with a target array. Matched items are deep-merged; unmatched target items are appended.
 
 ```typescript
-merge<P>(target: P[], options?: {
-  keys?: string[];
-  excludes?: string[];
-}): (T | P | (T & P))[];
+merge<P>(target: P[]): (T | P | (T & P))[];
+merge<P extends Record<string, unknown>>(
+  target: P[],
+  options: { keys: string[]; excludes?: string[] },
+): (T | P | (T & P))[];
+merge<P extends Record<string, unknown>>(
+  target: P[],
+  options: { excludes: string[] },
+): (T | P | (T & P))[];
 ```
 
-### `sum(selector?)`
+### `sum`
 
-Returns the sum of elements. Returns `0` for empty arrays.
+Sum of elements. If no selector is provided, elements must be numbers.
 
 ```typescript
 sum(selector?: (item: T, index: number) => number): number;
 ```
 
-### `min(selector?)` / `max(selector?)`
-
-Returns the minimum/maximum element. Returns `undefined` for empty arrays.
+Returns `0` for empty arrays.
 
-```typescript
-min(selector?: (item: T, index: number) => string | number): string | number | undefined;
-max(selector?: (item: T, index: number) => string | number): string | number | undefined;
-```
+### `min`
 
-### `shuffle()`
-
-Returns a new array with elements in random order (Fisher-Yates algorithm).
+Minimum element or minimum selected value.
 
 ```typescript
-shuffle(): T[];
+min(): T extends number | string ? T | undefined : never;
+min<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
 ```
 
-## Array -- Mutable Extensions
-
-These methods mutate the original array in place.
+### `max`
 
-### `distinctThis(options?)`
-
-Removes duplicates from the original array in place. Same options as `distinct()`.
+Maximum element or maximum selected value.
 
 ```typescript
-distinctThis(options?: boolean | {
-  matchAddress?: boolean;
-  keyFn?: (item: T) => string | number;
-}): T[];
+max(): T extends number | string ? T | undefined : never;
+max<P extends number | string>(selector?: (item: T, index: number) => P): P | undefined;
 ```
 
-### `orderByThis(selector?)` / `orderByDescThis(selector?)`
+### `shuffle`
 
-Sorts the original array in place.
+Return a new array with elements in random order (Fisher-Yates algorithm).
 
 ```typescript
-orderByThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
-orderByDescThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+shuffle(): T[];
 ```
 
-### `insert(index, ...items)`
+---
 
-Inserts items at the given index in place.
+## Mutable Array Extensions
 
-```typescript
-insert(index: number, ...items: T[]): this;
-```
+These methods mutate the original array in-place.
 
-### `remove(itemOrSelector)`
+### `distinctThis`
 
-Removes matching items in place.
+Remove duplicates in-place. Same options as `distinct`.
 
 ```typescript
-remove(item: T): this;
-remove(selector: (item: T, index: number) => boolean): this;
+distinctThis(
+  options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number },
+): T[];
 ```
 
-### `toggle(item)`
+### `orderByThis`
 
-Toggles an item: removes if present, adds if absent.
+Sort ascending in-place.
 
 ```typescript
-toggle(item: T): this;
+orderByThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
 ```
 
-### `clear()`
+### `orderByDescThis`
 
-Removes all items from the array.
+Sort descending in-place.
 
 ```typescript
-clear(): this;
+orderByDescThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
 ```
 
-## Set Extensions
+### `insert`
 
-### `adds(...values)`
-
-Adds multiple values at once. Returns `this` for chaining.
+Insert items at a given index. Mutates the array.
 
 ```typescript
-adds(...values: T[]): this;
+insert(index: number, ...items: T[]): this;
 ```
 
-### `toggle(value, addOrDel?)`
+### `remove`
 
-Toggles a value in the Set. Optionally force add or delete.
+Remove items by value or predicate. Mutates the array.
 
 ```typescript
-toggle(value: T, addOrDel?: "add" | "del"): this;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `value` | `T` | Value to toggle |
-| `addOrDel` | `"add" \| "del" \| undefined` | Force add or delete. Omit for auto-toggle |
-
-```typescript
-const set = new Set([1, 2, 3]);
-set.toggle(2);           // removes 2 -> {1, 3}
-set.toggle(4);           // adds 4    -> {1, 3, 4}
-set.toggle(5, "add");    // force add -> {1, 3, 4, 5}
-set.toggle(5, "del");    // force del -> {1, 3, 4}
+remove(item: T): this;
+remove(selector: (item: T, index: number) => boolean): this;
 ```
 
-## Map Extensions
+### `toggle`
 
-### `getOrCreate(key, newValue)`
-
-Returns the value for `key`. If the key does not exist, creates it with `newValue` (or calls `newValue` as a factory function if it is a function).
+Toggle an item: remove if present, add (push) if absent.
 
 ```typescript
-getOrCreate(key: K, newValue: V): V;
-getOrCreate(key: K, newValueFn: () => V): V;
-```
-
-**Note:** If `V` is a function type, wrap it in a factory to avoid it being called:
-```typescript
-fnMap.getOrCreate("key", () => myFunction);
+toggle(item: T): this;
 ```
 
-### `update(key, updateFn)`
+### `clear`
 
-Updates a key's value using a function. If the key does not exist, `updateFn` receives `undefined`.
+Remove all items from the array.
 
 ```typescript
-update(key: K, updateFn: (v: V | undefined) => V): void;
+clear(): this;
 ```
 
-```typescript
-const counts = new Map<string, number>();
-counts.update("hits", (v) => (v ?? 0) + 1);
-```
+---
 
 ## Exported Types
 
@@ -428,3 +396,42 @@ type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
 ```typescript
 type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
 ```
+
+---
+
+## Exported Helper Functions
+
+### `toComparable`
+
+Convert DateTime, DateOnly, or Time to their tick value for comparison. Primitives pass through unchanged.
+
+```typescript
+function toComparable(value: ComparableType): string | number | boolean | undefined;
+```
+
+### `compareForOrder`
+
+Comparison function for sorting. Handles null/undefined (sorted first in ascending, last in descending). Supports string (locale-aware), number, and boolean.
+
+```typescript
+function compareForOrder(pp: ComparableType, pn: ComparableType, desc: boolean): number;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pp` | `ComparableType` | First value |
+| `pn` | `ComparableType` | Second value |
+| `desc` | `boolean` | `true` for descending order |
+
+**Returns:** Negative if `pp` should come first, positive if `pn` should come first, `0` if equal.
+
+### `getDistinctIndices`
+
+Get the set of indices to keep for deduplication. Handles all strategies: address comparison, custom key function, and deep equality.
+
+```typescript
+function getDistinctIndices<T>(
+  items: readonly T[],
+  options?: boolean | { matchAddress?: boolean; keyFn?: (item: T) => string | number },
+): Set<number>;
+```

package/docs/env.md

@@ -1,10 +1,8 @@
 # Environment
 
-Unified access to environment variables from both `import.meta.env` (Vite/browser) and `process.env` (Node.js). `process.env` takes precedence when both are available.
-
 ## `parseBoolEnv`
 
-Parses an unknown value to a boolean. Returns `true` for `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive), `false` for everything else.
+Parse a value to boolean. Recognizes `"true"`, `"1"`, `"yes"`, `"on"` (case-insensitive) as `true`; everything else is `false`.
 
 ```typescript
 function parseBoolEnv(value: unknown): boolean;
@@ -12,22 +10,13 @@ function parseBoolEnv(value: unknown): boolean;
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `value` | `unknown` | The value to parse |
+| `value` | `unknown` | The value to parse. Converted to string internally. |
 
 **Returns:** `boolean`
 
-```typescript
-parseBoolEnv("true");  // true
-parseBoolEnv("1");     // true
-parseBoolEnv("yes");   // true
-parseBoolEnv("on");    // true
-parseBoolEnv("false"); // false
-parseBoolEnv(undefined); // false
-```
-
 ## `env`
 
-A pre-built environment object that merges `import.meta.env` and `process.env`.
+Unified environment variable object. Merges `import.meta.env` and `process.env` (process.env takes precedence). `DEV` is auto-parsed as boolean, `VER` is typed as optional string.
 
 ```typescript
 const env: {
@@ -37,16 +26,8 @@ const env: {
 };
 ```
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `DEV` | `boolean` | Whether in development mode (parsed via `parseBoolEnv` from `DEV` env var) |
-| `VER` | `string \| undefined` | Version string from `VER` env var |
-| `[key]` | `unknown` | Any other environment variable |
-
-```typescript
-import { env } from "@simplysm/core-common";
-
-if (env.DEV) {
-  // development-only logic
-}
-```
+| Field | Type | Description |
+|-------|------|-------------|
+| `DEV` | `boolean` | Whether the app is running in development mode. Parsed from raw `DEV` env var via `parseBoolEnv`. |
+| `VER` | `string \| undefined` | Application version string, if set. |
+| `[key: string]` | `unknown` | Any other environment variable. |