@simplysm/core-common 14.0.1 → 14.0.4

package/README.md

@@ -0,0 +1,154 @@
+# @simplysm/core-common
+
+Platform-neutral utility library for the Simplysm framework. Provides type-safe primitives, collection extensions, error hierarchy, async utilities, and serialization helpers that work in both browser and Node.js environments.
+
+## Installation
+
+```bash
+npm install @simplysm/core-common
+```
+
+## API Overview
+
+### Environment
+
+| API | Type | Description |
+|-----|------|-------------|
+| `env` | `object` | Unified environment variables from `import.meta.env` and `process.env` |
+| `parseBoolEnv` | `function` | Parse a value to boolean (`"true"`, `"1"`, `"yes"`, `"on"` -> `true`) |
+
+-> See [docs/env.md](./docs/env.md) for details.
+
+### Array / Set / Map Extensions
+
+| API | Type | Description |
+|-----|------|-------------|
+| `Array.prototype.*` | extension | 30+ methods: `single`, `first`, `last`, `groupBy`, `toMap`, `distinct`, `orderBy`, `diffs`, `sum`, `min`, `max`, etc. |
+| `Set.prototype.adds` | extension | Add multiple values at once |
+| `Set.prototype.toggle` | extension | Toggle a value (add if absent, remove if present) |
+| `Map.prototype.getOrCreate` | extension | Get value or create with default/factory |
+| `Map.prototype.update` | extension | Update a value using a function |
+| `ArrayDiffsResult` | type | Result type for `diffs()` |
+| `ArrayOneWayDiffResult` | type | Result type for `oneWayDiffs()` |
+| `TreeArray` | type | Tree node type for `toTree()` |
+| `ComparableType` | type | Union of types usable in ordering |
+
+-> See [docs/array-extensions.md](./docs/array-extensions.md) for details.
+
+### Errors
+
+| API | Type | Description |
+|-----|------|-------------|
+| `SdError` | class | Tree-structured error with cause chaining |
+| `ArgumentError` | class | Invalid argument error with YAML-formatted details |
+| `NotImplementedError` | class | Unimplemented feature error |
+| `TimeoutError` | class | Timeout exceeded error |
+
+-> See [docs/errors.md](./docs/errors.md) for details.
+
+### Types
+
+| API | Type | Description |
+|-----|------|-------------|
+| `Uuid` | class | UUID v4 generation and parsing |
+| `LazyGcMap` | class | Auto-expiring Map with LRU-style GC |
+| `DateTime` | class | Immutable date-time wrapper with millisecond precision |
+| `DateOnly` | class | Immutable date-only wrapper (no time component) |
+| `Time` | class | Immutable time-only wrapper (no date component, 24h cyclic) |
+
+-> See [docs/types.md](./docs/types.md) for details.
+
+### Features
+
+| API | Type | Description |
+|-----|------|-------------|
+| `DebounceQueue` | class | Async debounce queue -- only executes the last enqueued function |
+| `SerialQueue` | class | Async serial queue -- executes functions one at a time in order |
+| `EventEmitter` | class | Type-safe event emitter built on EventTarget |
+
+-> See [docs/features.md](./docs/features.md) for details.
+
+### Utils (Namespace Exports)
+
+| API | Type | Description |
+|-----|------|-------------|
+| `obj` | namespace | Deep clone, deep equal, deep merge, 3-way merge, omit, pick, chain access, type-safe keys/entries |
+| `str` | namespace | Korean suffix, full-width conversion, case transforms, `isNullOrEmpty`, `insert` |
+| `num` | namespace | parseInt, parseFloat, parseRoundedInt, isNullOrEmpty, format |
+| `bytes` | namespace | Uint8Array concat, hex, base64 conversions |
+| `path` | namespace | POSIX-style path join, basename, extname (browser-safe) |
+| `json` | namespace | JSON stringify/parse with custom type support (DateTime, Uuid, Map, Set, etc.) |
+| `xml` | namespace | XML parse/stringify via fast-xml-parser |
+| `wait` | namespace | `until` (poll condition) and `time` (delay) |
+| `transfer` | namespace | Worker-transferable encode/decode for custom types |
+| `err` | namespace | Extract error message from unknown |
+| `dt` | namespace | Date/time format strings (C#-style patterns) |
+| `primitive` | namespace | Runtime primitive type string detection |
+| `js`, `ts`, `html`, `tsql`, `mysql`, `pgsql` | template tag | IDE syntax highlighting template tags with indent normalization |
+| `ZipArchive` | class | ZIP read/write/compress/extract |
+
+-> See [docs/utils.md](./docs/utils.md) for details.
+
+### Type Utilities
+
+| API | Type | Description |
+|-----|------|-------------|
+| `Bytes` | type alias | `Uint8Array` (replaces `Buffer`) |
+| `PrimitiveTypeMap` | type | Maps type-string keys to their TypeScript types |
+| `PrimitiveTypeStr` | type | `"string" \| "number" \| "boolean" \| "DateTime" \| "DateOnly" \| "Time" \| "Uuid" \| "Bytes"` |
+| `PrimitiveType` | type | Union of all primitive type values |
+| `DeepPartial<T>` | type | Recursively makes all properties optional |
+| `Type<T>` | interface | Constructor type (`new (...args) => T`) |
+
+-> See [docs/type-utilities.md](./docs/type-utilities.md) for details.
+
+## Usage Examples
+
+### Deep cloning and comparing objects
+
+```typescript
+import { obj } from "@simplysm/core-common";
+
+const original = { a: 1, b: { c: [2, 3] } };
+const cloned = obj.clone(original);
+obj.equal(original, cloned); // true
+
+const merged = obj.merge(original, { b: { d: 4 } });
+// { a: 1, b: { c: [2, 3], d: 4 } }
+```
+
+### Using Array extensions
+
+```typescript
+import "@simplysm/core-common";
+
+const users = [
+  { id: 1, role: "admin", name: "Alice" },
+  { id: 2, role: "user", name: "Bob" },
+  { id: 3, role: "user", name: "Carol" },
+];
+
+const grouped = users.groupBy((u) => u.role);
+// [{ key: "admin", values: [Alice] }, { key: "user", values: [Bob, Carol] }]
+
+const userMap = users.toMap((u) => u.id);
+// Map { 1 => Alice, 2 => Bob, 3 => Carol }
+
+const sorted = users.orderBy((u) => u.name);
+```
+
+### JSON serialization with custom types
+
+```typescript
+import { json, DateTime, Uuid } from "@simplysm/core-common";
+
+const data = {
+  id: Uuid.generate(),
+  createdAt: new DateTime(2025, 6, 15, 10, 30, 0),
+  tags: new Set(["a", "b"]),
+};
+
+const serialized = json.stringify(data);
+const restored = json.parse(serialized);
+// restored.id is Uuid, restored.createdAt is DateTime, restored.tags is Set
+```

package/dist/env.d.ts

@@ -1,6 +1,8 @@
 declare global {
+    interface ImportMetaEnv extends Record<string, unknown> {
+    }
     interface ImportMeta {
-        env?: Record<string, unknown>;
+        readonly env: ImportMetaEnv;
     }
 }
 /**

package/dist/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,UAAU;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B;CACF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAMD,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;KAAG;IAC1D,UAAU,UAAU;QAClB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;KAC7B;CACF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD;AAMD,eAAO,MAAM,GAAG,EAAE;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAKxB,CAAC"}

package/dist/env.js

@@ -5,7 +5,7 @@
 export function parseBoolEnv(value) {
     return ["true", "1", "yes", "on"].includes(String(value ?? "").toLowerCase());
 }
-const _metaEnv = import.meta.env ?? {};
+const _metaEnv = { ...import.meta.env };
 const _processEnv = typeof process !== "undefined" ? process.env : {};
 const _raw = { ..._metaEnv, ..._processEnv };
 export const env = {

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,QAAQ,GAA4B,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC;AAChE,MAAM,WAAW,GAA4B,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/F,MAAM,IAAI,GAA4B,EAAE,GAAG,QAAQ,EAAE,GAAG,WAAW,EAAE,CAAC;AAEtE,MAAM,CAAC,MAAM,GAAG,GAIZ;IACF,GAAG,IAAI;IACP,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,GAAG,EAAE,IAAI,CAAC,KAAK,CAAuB;CACvC,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,QAAQ,GAA4B,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;AACjE,MAAM,WAAW,GAA4B,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/F,MAAM,IAAI,GAA4B,EAAE,GAAG,QAAQ,EAAE,GAAG,WAAW,EAAE,CAAC;AAEtE,MAAM,CAAC,MAAM,GAAG,GAIZ;IACF,GAAG,IAAI;IACP,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,GAAG,EAAE,IAAI,CAAC,KAAK,CAAuB;CACvC,CAAC"}

package/docs/array-extensions.md

@@ -0,0 +1,430 @@
+# Array / Set / Map Extensions
+
+Prototype extensions added to `Array`, `Set`, and `Map` at import time. Importing `@simplysm/core-common` automatically installs these extensions.
+
+## Array -- Readonly Extensions
+
+These methods return new arrays/values without mutating the original.
+
+### `single(predicate?)`
+
+Returns the single matching element, or `undefined` if none. Throws `ArgumentError` if more than one element matches.
+
+```typescript
+single(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+### `first(predicate?)`
+
+Returns the first matching element, or `undefined` if none.
+
+```typescript
+first(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+### `last(predicate?)`
+
+Returns the last matching element, or `undefined` if none.
+
+```typescript
+last(predicate?: (item: T, index: number) => boolean): T | undefined;
+```
+
+### `filterAsync(predicate)`
+
+Async sequential filter.
+
+```typescript
+filterAsync(predicate: (item: T, index: number) => Promise<boolean>): Promise<T[]>;
+```
+
+### `filterExists()`
+
+Removes `null` and `undefined` elements. Returns `NonNullable<T>[]`.
+
+```typescript
+filterExists(): NonNullable<T>[];
+```
+
+### `ofType(type)`
+
+Filters elements by type. Accepts a `PrimitiveTypeStr` (`"string"`, `"number"`, `"boolean"`, `"DateTime"`, `"DateOnly"`, `"Time"`, `"Uuid"`, `"Bytes"`) or a constructor function.
+
+```typescript
+ofType<K extends PrimitiveTypeStr>(type: K): Extract<T, PrimitiveTypeMap[K]>[];
+ofType<N extends T>(type: Type<N>): N[];
+```
+
+### `mapAsync(selector)`
+
+Async sequential map.
+
+```typescript
+mapAsync<R>(selector: (item: T, index: number) => Promise<R>): Promise<R[]>;
+```
+
+### `mapMany(selector?)`
+
+Maps then flattens one level. Removes `null`/`undefined` from results.
+
+```typescript
+mapMany(): T extends readonly (infer U)[] ? U[] : T;
+mapMany<R>(selector: (item: T, index: number) => R[]): R[];
+```
+
+### `mapManyAsync(selector?)`
+
+Async version of `mapMany`.
+
+```typescript
+mapManyAsync<R>(selector: (item: T, index: number) => Promise<R[]>): Promise<R[]>;
+```
+
+### `parallelAsync(fn)`
+
+Runs `fn` for all items in parallel via `Promise.all`. If any rejects, the entire result rejects.
+
+```typescript
+parallelAsync<R>(fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+```
+
+### `groupBy(keySelector, valueSelector?)`
+
+Groups items by key. Supports both primitive keys (O(n) via Map) and object keys (O(n^2) via deep equality).
+
+```typescript
+groupBy<K>(keySelector: (item: T, index: number) => K): { key: K; values: T[] }[];
+groupBy<K, V>(
+  keySelector: (item: T, index: number) => K,
+  valueSelector: (item: T, index: number) => V,
+): { key: K; values: V[] }[];
+```
+
+### `toMap(keySelector, valueSelector?)`
+
+Converts array to `Map`. Throws `ArgumentError` on duplicate keys.
+
+```typescript
+toMap<K>(keySelector: (item: T, index: number) => K): Map<K, T>;
+toMap<K, V>(
+  keySelector: (item: T, index: number) => K,
+  valueSelector: (item: T, index: number) => V,
+): Map<K, V>;
+```
+
+### `toMapAsync(keySelector, valueSelector?)`
+
+Async version of `toMap`.
+
+```typescript
+toMapAsync<K>(keySelector: (item: T, index: number) => Promise<K>): Promise<Map<K, T>>;
+toMapAsync<K, V>(
+  keySelector: (item: T, index: number) => Promise<K> | K,
+  valueSelector: (item: T, index: number) => Promise<V> | V,
+): Promise<Map<K, V>>;
+```
+
+### `toArrayMap(keySelector, valueSelector?)`
+
+Converts array to `Map<K, V[]>` (groups values into arrays per key).
+
+```typescript
+toArrayMap<K>(keySelector: (item: T, index: number) => K): Map<K, T[]>;
+toArrayMap<K, V>(
+  keySelector: (item: T, index: number) => K,
+  valueSelector: (item: T, index: number) => V,
+): Map<K, V[]>;
+```
+
+### `toSetMap(keySelector, valueSelector?)`
+
+Converts array to `Map<K, Set<V>>`.
+
+```typescript
+toSetMap<K>(keySelector: (item: T, index: number) => K): Map<K, Set<T>>;
+toSetMap<K, V>(
+  keySelector: (item: T, index: number) => K,
+  valueSelector: (item: T, index: number) => V,
+): Map<K, Set<V>>;
+```
+
+### `toMapValues(keySelector, valueSelector)`
+
+Groups by key, then applies `valueSelector` to the group array to produce the final value.
+
+```typescript
+toMapValues<K, V>(
+  keySelector: (item: T, index: number) => K,
+  valueSelector: (items: T[]) => V,
+): Map<K, V>;
+```
+
+### `toObject(keySelector, valueSelector?)`
+
+Converts array to a plain object. Throws `ArgumentError` on duplicate keys.
+
+```typescript
+toObject(keySelector: (item: T, index: number) => string): Record<string, T>;
+toObject<V>(
+  keySelector: (item: T, index: number) => string,
+  valueSelector: (item: T, index: number) => V,
+): Record<string, V>;
+```
+
+### `toTree(keyProp, parentKey)`
+
+Converts a flat array to a tree structure. Items where `parentKey` is `null`/`undefined` become roots. O(n) complexity.
+
+```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?)`
+
+Returns a new array with duplicates removed.
+
+```typescript
+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) |
+
+### `orderBy(selector?)` / `orderByDesc(selector?)`
+
+Returns a sorted copy. Supports `string`, `number`, `DateTime`, `DateOnly`, `Time`.
+
+```typescript
+orderBy(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+orderByDesc(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+```
+
+### `diffs(target, options?)`
+
+Compares two arrays and returns INSERT/DELETE/UPDATE diff results.
+
+```typescript
+diffs<P>(target: P[], options?: {
+  keys?: string[];
+  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)
+
+### `oneWayDiffs(orgItems, keyPropNameOrGetValFn, options?)`
+
+One-way diff: compares current array against original items.
+
+```typescript
+oneWayDiffs<K extends keyof T>(
+  orgItems: T[] | Map<T[K], T>,
+  keyPropNameOrGetValFn: K | ((item: T) => string | number | undefined),
+  options?: { includeSame?: boolean; excludes?: string[]; includes?: string[] },
+): ArrayOneWayDiffResult<T>[];
+```
+
+Result types: `"create"`, `"update"`, `"same"` (only if `includeSame: true`).
+
+### `merge(target, options?)`
+
+Merges two arrays using deep merge on matched items and appends unmatched target items.
+
+```typescript
+merge<P>(target: P[], options?: {
+  keys?: string[];
+  excludes?: string[];
+}): (T | P | (T & P))[];
+```
+
+### `sum(selector?)`
+
+Returns the sum of elements. Returns `0` for empty arrays.
+
+```typescript
+sum(selector?: (item: T, index: number) => number): number;
+```
+
+### `min(selector?)` / `max(selector?)`
+
+Returns the minimum/maximum element. Returns `undefined` 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;
+```
+
+### `shuffle()`
+
+Returns a new array with elements in random order (Fisher-Yates algorithm).
+
+```typescript
+shuffle(): T[];
+```
+
+## Array -- Mutable Extensions
+
+These methods mutate the original array in place.
+
+### `distinctThis(options?)`
+
+Removes duplicates from the original array in place. Same options as `distinct()`.
+
+```typescript
+distinctThis(options?: boolean | {
+  matchAddress?: boolean;
+  keyFn?: (item: T) => string | number;
+}): T[];
+```
+
+### `orderByThis(selector?)` / `orderByDescThis(selector?)`
+
+Sorts the original array in place.
+
+```typescript
+orderByThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+orderByDescThis(selector?: (item: T) => string | number | DateTime | DateOnly | Time | undefined): T[];
+```
+
+### `insert(index, ...items)`
+
+Inserts items at the given index in place.
+
+```typescript
+insert(index: number, ...items: T[]): this;
+```
+
+### `remove(itemOrSelector)`
+
+Removes matching items in place.
+
+```typescript
+remove(item: T): this;
+remove(selector: (item: T, index: number) => boolean): this;
+```
+
+### `toggle(item)`
+
+Toggles an item: removes if present, adds if absent.
+
+```typescript
+toggle(item: T): this;
+```
+
+### `clear()`
+
+Removes all items from the array.
+
+```typescript
+clear(): this;
+```
+
+## Set Extensions
+
+### `adds(...values)`
+
+Adds multiple values at once. Returns `this` for chaining.
+
+```typescript
+adds(...values: T[]): this;
+```
+
+### `toggle(value, addOrDel?)`
+
+Toggles a value in the Set. Optionally force add or delete.
+
+```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}
+```
+
+## Map Extensions
+
+### `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).
+
+```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);
+```
+
+### `update(key, updateFn)`
+
+Updates a key's value using a function. If the key does not exist, `updateFn` receives `undefined`.
+
+```typescript
+update(key: K, updateFn: (v: V | undefined) => V): void;
+```
+
+```typescript
+const counts = new Map<string, number>();
+counts.update("hits", (v) => (v ?? 0) + 1);
+```
+
+## Exported Types
+
+### `ArrayDiffsResult<TOriginal, TOther>`
+
+```typescript
+type ArrayDiffsResult<TOriginal, TOther> =
+  | { source: undefined; target: TOther }       // INSERT
+  | { source: TOriginal; target: undefined }     // DELETE
+  | { source: TOriginal; target: TOther };       // UPDATE
+```
+
+### `ArrayOneWayDiffResult<TItem>`
+
+```typescript
+type ArrayOneWayDiffResult<TItem> =
+  | { type: "create"; item: TItem; orgItem: undefined }
+  | { type: "update"; item: TItem; orgItem: TItem }
+  | { type: "same"; item: TItem; orgItem: TItem };
+```
+
+### `TreeArray<TNode>`
+
+```typescript
+type TreeArray<TNode> = TNode & { children: TreeArray<TNode>[] };
+```
+
+### `ComparableType`
+
+```typescript
+type ComparableType = string | number | boolean | DateTime | DateOnly | Time | undefined;
+```

package/docs/env.md

@@ -0,0 +1,52 @@
+# 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.
+
+```typescript
+function parseBoolEnv(value: unknown): boolean;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `unknown` | The value to parse |
+
+**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`.
+
+```typescript
+const env: {
+  DEV: boolean;
+  VER?: string;
+  [key: string]: unknown;
+};
+```
+
+| 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
+}
+```