@simplysm/core-common 14.0.22 → 14.0.24

package/docs/errors.md

@@ -1,68 +0,0 @@
-# Errors
-
-All error classes extend `SdError`, which extends the native `Error`.
-
-## `SdError`
-
-Tree-structured error class. Supports cause chaining via the ES2024 `cause` property. Messages are joined in reverse order with ` => ` separator.
-
-```typescript
-class SdError extends Error {
-  override cause?: Error;
-
-  constructor(cause: Error, ...messages: string[]);
-  constructor(...messages: string[]);
-}
-```
-
-| Constructor Overload | Description |
-|----------------------|-------------|
-| `new SdError(cause, ...messages)` | Wrap a cause error. Final message: `"outermost => ... => cause.message"` |
-| `new SdError(...messages)` | Messages only. Final message: `"outermost => ... => innermost"` |
-
-The cause chain stack trace is appended to the current stack under a `---- cause stack ----` separator.
-
-## `ArgumentError`
-
-Invalid argument error. Extends `SdError`. Formats the argument object as YAML in the error message for debugging.
-
-```typescript
-class ArgumentError extends SdError {
-  constructor(argObj: Record<string, unknown>);
-  constructor(message: string, argObj: Record<string, unknown>);
-}
-```
-
-| Constructor Overload | Description |
-|----------------------|-------------|
-| `new ArgumentError(argObj)` | Default message + YAML dump of arguments |
-| `new ArgumentError(message, argObj)` | Custom message + YAML dump of arguments |
-
-## `NotImplementedError`
-
-Unimplemented feature error. Extends `SdError`. Use for abstract method stubs or future branches.
-
-```typescript
-class NotImplementedError extends SdError {
-  constructor(message?: string);
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `message` | `string \| undefined` | Optional description of what is not implemented |
-
-## `TimeoutError`
-
-Timeout exceeded error. Extends `SdError`. Thrown by `wait.until()` when max retry count is exceeded.
-
-```typescript
-class TimeoutError extends SdError {
-  constructor(count?: number, message?: string);
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `count` | `number \| undefined` | Number of attempts made before timeout |
-| `message` | `string \| undefined` | Additional context message |

package/docs/features.md

@@ -1,112 +0,0 @@
-# Features
-
-## `DebounceQueue`
-
-Async debounce queue. When multiple calls arrive in quick succession, only the last enqueued function executes after the delay. Extends `EventEmitter<{ error: SdError }>`.
-
-If a new request arrives while a previous one is executing, it runs immediately after the current execution completes (no debounce delay).
-
-```typescript
-class DebounceQueue extends EventEmitter<{ error: SdError }> {
-  constructor(delay?: number);
-
-  run(fn: () => void | Promise<void>): void;
-  dispose(): void;
-  [Symbol.dispose](): void;
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `delay` | `number \| undefined` | Debounce delay in ms. If omitted, executes on next event loop tick. |
-
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `run(fn)` | Enqueue a function. Replaces any previously pending function. |
-| `dispose()` | Cancel pending work and clean up timers. |
-| `[Symbol.dispose]()` | Supports `using` statement. |
-
-### Error Handling
-
-Errors from the executed function are emitted as `"error"` events. If no listener is registered, errors are logged via `consola`.
-
----
-
-## `SerialQueue`
-
-Async serial queue. Functions are executed one at a time in FIFO order. Errors in one task do not prevent subsequent tasks from running. Extends `EventEmitter<{ error: SdError }>`.
-
-```typescript
-class SerialQueue extends EventEmitter<{ error: SdError }> {
-  constructor(gap?: number);
-
-  run(fn: () => void | Promise<void>): void;
-  dispose(): void;
-  [Symbol.dispose](): void;
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `gap` | `number` | Delay between tasks in ms. Default: `0`. |
-
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `run(fn)` | Add a function to the queue. Starts processing if not already running. |
-| `dispose()` | Clear the pending queue (current task completes). |
-| `[Symbol.dispose]()` | Supports `using` statement. |
-
-### Error Handling
-
-Same as `DebounceQueue`: errors are emitted as `"error"` events or logged if no listener.
-
----
-
-## `EventEmitter<TEvents>`
-
-Type-safe event emitter built on the `EventTarget` API. Works in both browser and Node.js. Duplicate listener registration for the same event is silently ignored.
-
-```typescript
-class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {
-  on<TEventName extends keyof TEvents & string>(
-    type: TEventName,
-    listener: (data: TEvents[TEventName]) => void,
-  ): void;
-
-  off<TEventName extends keyof TEvents & string>(
-    type: TEventName,
-    listener: (data: TEvents[TEventName]) => void,
-  ): void;
-
-  emit<TEventName extends keyof TEvents & string>(
-    type: TEventName,
-    ...args: TEvents[TEventName] extends void ? [] : [data: TEvents[TEventName]]
-  ): void;
-
-  listenerCount<TEventName extends keyof TEvents & string>(type: TEventName): number;
-
-  dispose(): void;
-  [Symbol.dispose](): void;
-}
-```
-
-### Type Parameter
-
-| Parameter | Description |
-|-----------|-------------|
-| `TEvents` | Object type mapping event names to their data types. Use `void` for events with no data. |
-
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `on(type, listener)` | Register a listener. Duplicate registration for same event is ignored. |
-| `off(type, listener)` | Remove a listener. |
-| `emit(type, ...args)` | Dispatch an event. For `void` event types, no data argument is needed. |
-| `listenerCount(type)` | Return the number of listeners for an event type. |
-| `dispose()` | Remove all listeners from all events. |
-| `[Symbol.dispose]()` | Supports `using` statement. |

package/docs/map-extensions.md

@@ -1,41 +0,0 @@
-# Map Extensions
-
-Prototype extensions added to the global `Map` type. Available after importing `@simplysm/core-common`.
-
-## `Map.prototype.getOrCreate`
-
-Get the value for a key. If the key does not exist, create a new value (using the provided value or factory function), store it, and return it.
-
-```typescript
-interface Map<K, V> {
-  getOrCreate(key: K, newValue: V): V;
-  getOrCreate(key: K, newValueFn: () => V): V;
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `key` | `K` | The key to look up |
-| `newValue` | `V` | Default value to store if key is absent |
-| `newValueFn` | `() => V` | Factory function called only if key is absent |
-
-**Returns:** `V` -- the existing or newly created value.
-
-**Note:** If `V` is a function type (e.g., `Map<string, () => void>`), passing a function directly as the second argument will be treated as a factory. Wrap it in another function: `map.getOrCreate("key", () => myFn)`.
-
----
-
-## `Map.prototype.update`
-
-Update the value for a key using a transform function. The function receives the current value (or `undefined` if the key does not exist) and its return value is stored.
-
-```typescript
-interface Map<K, V> {
-  update(key: K, updateFn: (v: V | undefined) => V): void;
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `key` | `K` | The key to update |
-| `updateFn` | `(v: V \| undefined) => V` | Transform function. Receives current value or `undefined`. |

package/docs/set-extensions.md

@@ -1,38 +0,0 @@
-# Set Extensions
-
-Prototype extensions added to the global `Set` type. Available after importing `@simplysm/core-common`.
-
-## `Set.prototype.adds`
-
-Add multiple values at once.
-
-```typescript
-interface Set<T> {
-  adds(...values: T[]): this;
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `values` | `T[]` | Values to add |
-
-**Returns:** `this` (for method chaining)
-
----
-
-## `Set.prototype.toggle`
-
-Toggle a value in the set. If the value exists, remove it; if absent, add it. Optionally force add or delete.
-
-```typescript
-interface Set<T> {
-  toggle(value: T, addOrDel?: "add" | "del"): this;
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `value` | `T` | The value to toggle |
-| `addOrDel` | `"add" \| "del" \| undefined` | Force `"add"` to always add, `"del"` to always remove. Omit for automatic toggle. |
-
-**Returns:** `this` (for method chaining)

package/docs/template-strings-and-zip.md

@@ -1,87 +0,0 @@
-# Template Strings and Zip
-
-## Template String Tag Functions
-
-All template tag functions perform the same operation: combine the template literals and normalize indentation. They exist as separate functions to enable IDE syntax highlighting for different languages.
-
-Each function:
-1. Joins the template strings with interpolated values
-2. Removes leading and trailing blank lines
-3. Calculates the minimum indentation across all non-empty lines
-4. Removes that minimum indentation from every line
-
-```typescript
-function js(strings: TemplateStringsArray, ...values: unknown[]): string;
-function ts(strings: TemplateStringsArray, ...values: unknown[]): string;
-function html(strings: TemplateStringsArray, ...values: unknown[]): string;
-function tsql(strings: TemplateStringsArray, ...values: unknown[]): string;
-function mysql(strings: TemplateStringsArray, ...values: unknown[]): string;
-function pgsql(strings: TemplateStringsArray, ...values: unknown[]): string;
-```
-
-| Function | Purpose |
-|----------|---------|
-| `js` | JavaScript code highlighting |
-| `ts` | TypeScript code highlighting |
-| `html` | HTML markup highlighting |
-| `tsql` | MSSQL T-SQL highlighting |
-| `mysql` | MySQL SQL highlighting |
-| `pgsql` | PostgreSQL SQL highlighting |
-
----
-
-## `ZipArchiveProgress`
-
-Progress callback data for ZIP extraction.
-
-```typescript
-interface ZipArchiveProgress {
-  fileName: string;
-  totalSize: number;
-  extractedSize: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `fileName` | `string` | Name of the file currently being extracted |
-| `totalSize` | `number` | Total uncompressed size of all files in bytes |
-| `extractedSize` | `number` | Cumulative bytes extracted so far |
-
----
-
-## `ZipArchive`
-
-ZIP archive processing class. Supports reading, writing, compressing, and extracting ZIP files. Uses internal caching to avoid duplicate decompression. Built on `@zip.js/zip.js`.
-
-```typescript
-class ZipArchive {
-  constructor(data?: Blob | Bytes);
-
-  get(fileName: string): Promise<Bytes | undefined>;
-  exists(fileName: string): Promise<boolean>;
-  write(fileName: string, bytes: Bytes): void;
-  extractAll(progressCallback?: (progress: ZipArchiveProgress) => void): Promise<Map<string, Bytes | undefined>>;
-  compress(): Promise<Bytes>;
-  close(): Promise<void>;
-  [Symbol.asyncDispose](): Promise<void>;
-}
-```
-
-### Constructor
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `data` | `Blob \| Bytes \| undefined` | Existing ZIP data to read. Omit to create a new empty archive. |
-
-### Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `get(fileName)` | `Promise<Bytes \| undefined>` | Extract a single file by name. Returns `undefined` if not found. Caches the result. |
-| `exists(fileName)` | `Promise<boolean>` | Check if a file exists in the archive. |
-| `write(fileName, bytes)` | `void` | Write a file to the cache (for later compression). |
-| `extractAll(progressCallback?)` | `Promise<Map<string, Bytes \| undefined>>` | Extract all files. Returns a Map of filename to bytes. Optionally reports progress. |
-| `compress()` | `Promise<Bytes>` | Compress all cached files into a new ZIP. Calls `extractAll()` internally first. |
-| `close()` | `Promise<void>` | Close the reader and clear the cache. |
-| `[Symbol.asyncDispose]()` | `Promise<void>` | Supports `await using` statement. Calls `close()`. |

package/docs/type-utilities.md

@@ -1,75 +0,0 @@
-# Type Utilities
-
-Exported from `common.types.ts`.
-
-## `Bytes`
-
-Alias for `Uint8Array`. Used in place of Node.js `Buffer` throughout the framework.
-
-```typescript
-type Bytes = Uint8Array;
-```
-
----
-
-## `PrimitiveTypeMap`
-
-Maps primitive type string keys to their TypeScript types. Shared with `orm-common`.
-
-```typescript
-type PrimitiveTypeMap = {
-  string: string;
-  number: number;
-  boolean: boolean;
-  DateTime: DateTime;
-  DateOnly: DateOnly;
-  Time: Time;
-  Uuid: Uuid;
-  Bytes: Bytes;
-};
-```
-
----
-
-## `PrimitiveTypeStr`
-
-Union of all primitive type name strings.
-
-```typescript
-type PrimitiveTypeStr = keyof PrimitiveTypeMap;
-// "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
-```
-
----
-
-## `PrimitiveType`
-
-Union of all primitive type values, plus `undefined`.
-
-```typescript
-type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
-```
-
----
-
-## `DeepPartial<T>`
-
-Recursively make all properties optional. Primitive types (string, number, boolean, DateTime, DateOnly, Time, Uuid, Bytes) are left as-is; only object/array types are recursively made partial.
-
-```typescript
-type DeepPartial<TObject> = Partial<{
-  [K in keyof TObject]: TObject[K] extends PrimitiveType ? TObject[K] : DeepPartial<TObject[K]>;
-}>;
-```
-
----
-
-## `Type<T>`
-
-Constructor type interface. Represents a class constructor that produces instances of type `T`. Used for dependency injection, factory patterns, and `instanceof` checks.
-
-```typescript
-interface Type<TInstance> extends Function {
-  new (...args: unknown[]): TInstance;
-}
-```