@simplysm/core-common 13.0.100 → 14.0.4

package/docs/features.md

@@ -1,143 +1,128 @@
 # Features
 
-Feature classes for async control flow and event handling.
+Async queue and event emitter utilities. All support `using` syntax via `Symbol.dispose`.
 
-Source: `src/features/*.ts`
-
----
-
-## `EventEmitter`
+## `DebounceQueue`
 
-Type-safe event emitter that can be used in both browsers and Node.js. Internally implemented using `EventTarget`. Supports the `using` statement (`Symbol.dispose`).
+Async debounce queue. When called multiple times in rapid succession, only the last enqueued function executes after the delay. Extends `EventEmitter<{ error: SdError }>`.
 
 ```typescript
-export class EventEmitter<
-  TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>,
-> {
-  /**
-   * Register an event listener
-   * @note Duplicate registration of the same listener to the same event is ignored
-   */
-  on<TEventName extends keyof TEvents & string>(
-    type: TEventName,
-    listener: (data: TEvents[TEventName]) => void,
-  ): void;
-
-  /** Remove an event listener */
-  off<TEventName extends keyof TEvents & string>(
-    type: TEventName,
-    listener: (data: TEvents[TEventName]) => void,
-  ): void;
-
-  /**
-   * Emit an event
-   * @param args Event data (omitted if void type)
-   */
-  emit<TEventName extends keyof TEvents & string>(
-    type: TEventName,
-    ...args: TEvents[TEventName] extends void ? [] : [data: TEvents[TEventName]]
-  ): void;
-
-  /** Return the number of listeners for a specific event */
-  listenerCount<TEventName extends keyof TEvents & string>(type: TEventName): number;
+class DebounceQueue extends EventEmitter<{ error: SdError }> {
+  constructor(delay?: number);
 
-  /** Remove all event listeners */
+  run(fn: () => void | Promise<void>): void;
   dispose(): void;
-
   [Symbol.dispose](): void;
 }
 ```
 
-**Example:**
+### Constructor
 
-```typescript
-interface MyEvents {
-  data: string;
-  error: Error;
-  done: void;
-}
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `delay` | `number \| undefined` | `undefined` (next event loop) | Debounce delay in milliseconds |
 
-class MyEmitter extends EventEmitter<MyEvents> {}
+### Methods
 
-const emitter = new MyEmitter();
-emitter.on("data", (data) => console.log(data)); // data: string
-emitter.emit("data", "hello");
-emitter.emit("done"); // void type is called without arguments
-```
+| Method | Description |
+|--------|-------------|
+| `run(fn)` | Enqueue a function. Replaces any previously pending function. After the delay, executes the last enqueued function |
+| `dispose()` | Cancels pending timer and clears state |
 
----
+### Behavior
 
-## `DebounceQueue`
+- If a new `run()` call arrives while a previous function is executing, the new function runs immediately after the current one completes (no debounce delay).
+- Errors are emitted as `"error"` events if listeners exist; otherwise logged via consola.
 
-Asynchronous debounce queue. When called multiple times within a short time, only the last request is executed and previous requests are ignored. Extends `EventEmitter<{ error: SdError }>`. Supports the `using` statement.
+```typescript
+const queue = new DebounceQueue(300);
+queue.on("error", (err) => console.error(err));
 
-Requests added during execution are processed immediately after the current execution completes without debounce delay.
+queue.run(() => console.log("1")); // cancelled
+queue.run(() => console.log("2")); // cancelled
+queue.run(() => console.log("3")); // executes after 300ms
+```
 
-```typescript
-export class DebounceQueue extends EventEmitter<{ error: SdError }> {
-  /**
-   * @param _delay Debounce delay time (milliseconds). If omitted, executes immediately (next event loop)
-   */
-  constructor(delay?: number);
+## `SerialQueue`
 
-  /** Clean up pending tasks and timers */
-  dispose(): void;
+Async serial queue. Functions are executed one at a time in the order they are enqueued. Errors in one function do not prevent subsequent functions from running. Extends `EventEmitter<{ error: SdError }>`.
 
-  [Symbol.dispose](): void;
+```typescript
+class SerialQueue extends EventEmitter<{ error: SdError }> {
+  constructor(gap?: number);
 
-  /**
-   * Add a function to the queue
-   * If there was a previously added function, it will be replaced
-   */
   run(fn: () => void | Promise<void>): void;
+  dispose(): void;
+  [Symbol.dispose](): void;
 }
 ```
 
-**Error handling:** If there are `"error"` event listeners, errors are emitted as events. Otherwise, errors are logged via `consola`.
+### Constructor
 
-**Example:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `gap` | `number` | `0` | Delay between each task execution (ms) |
 
-```typescript
-const queue = new DebounceQueue(300); // 300ms delay
-queue.run(() => console.log("1")); // ignored
-queue.run(() => console.log("2")); // ignored
-queue.run(() => console.log("3")); // executed after 300ms
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `run(fn)` | Add a function to the queue. Starts processing if not already running |
+| `dispose()` | Clears the pending queue. The currently running task still completes |
 
+```typescript
+const queue = new SerialQueue();
 queue.on("error", (err) => console.error(err));
-```
 
----
+queue.run(async () => { await fetch("/api/1"); }); // runs first
+queue.run(async () => { await fetch("/api/2"); }); // runs after 1 completes
+queue.run(async () => { await fetch("/api/3"); }); // runs after 2 completes
+```
 
-## `SerialQueue`
+## `EventEmitter<TEvents>`
 
-Asynchronous serial queue. Functions added to the queue are executed sequentially. The next task starts only after one task completes. Subsequent tasks continue to execute even if an error occurs. Extends `EventEmitter<{ error: SdError }>`. Supports the `using` statement.
+Type-safe event emitter built on the `EventTarget` API. Works in both browser and Node.js.
 
 ```typescript
-export class SerialQueue extends EventEmitter<{ error: SdError }> {
-  /**
-   * @param gap Gap between each task (ms). Default: 0
-   */
-  constructor(gap?: number);
-
-  /** Clear pending queue (currently executing task will complete) */
+class EventEmitter<TEvents extends { [K in keyof TEvents]: unknown } = Record<string, unknown>> {
+  on<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
+  off<K extends keyof TEvents & string>(type: K, listener: (data: TEvents[K]) => void): void;
+  emit<K extends keyof TEvents & string>(
+    type: K,
+    ...args: TEvents[K] extends void ? [] : [data: TEvents[K]]
+  ): void;
+  listenerCount<K extends keyof TEvents & string>(type: K): number;
   dispose(): void;
-
   [Symbol.dispose](): void;
-
-  /** Add a function to the queue and execute it */
-  run(fn: () => void | Promise<void>): void;
 }
 ```
 
-**Error handling:** Same as `DebounceQueue` -- emitted as event if listeners exist, otherwise logged.
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `on(type, listener)` | Register a listener. Duplicate registration for the same event+listener is ignored |
+| `off(type, listener)` | Remove a listener |
+| `emit(type, data?)` | Dispatch an event. For `void` event types, data argument is omitted |
+| `listenerCount(type)` | Returns the number of registered listeners for an event type |
+| `dispose()` | Removes all listeners from all event types |
 
-**Example:**
+### Type Parameter
+
+`TEvents` is a map where keys are event names and values are event data types. Use `void` for events with no data.
 
 ```typescript
-const queue = new SerialQueue();
-queue.run(async () => { await fetch("/api/1"); });
-queue.run(async () => { await fetch("/api/2"); }); // executed after 1 completes
-queue.run(async () => { await fetch("/api/3"); }); // executed after 2 completes
+interface MyEvents {
+  data: string;
+  error: Error;
+  done: void;
+}
 
-queue.on("error", (err) => console.error(err));
+class MyService extends EventEmitter<MyEvents> {}
+
+const svc = new MyService();
+svc.on("data", (data) => {});   // data: string
+svc.on("done", () => {});       // no argument
+svc.emit("data", "hello");
+svc.emit("done");               // no argument needed
 ```

package/docs/type-utilities.md

@@ -0,0 +1,91 @@
+# Type Utilities
+
+TypeScript type aliases and interfaces exported from `common.types.ts`.
+
+## `Bytes`
+
+Type alias for `Uint8Array`. Used throughout the framework instead of `Buffer`.
+
+```typescript
+type Bytes = Uint8Array;
+```
+
+## `PrimitiveTypeMap`
+
+Maps primitive type string keys to their corresponding 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 keys in `PrimitiveTypeMap`.
+
+```typescript
+type PrimitiveTypeStr = keyof PrimitiveTypeMap;
+// "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes"
+```
+
+## `PrimitiveType`
+
+Union of all primitive type values (including `undefined`).
+
+```typescript
+type PrimitiveType = PrimitiveTypeMap[PrimitiveTypeStr] | undefined;
+// string | number | boolean | DateTime | DateOnly | Time | Uuid | Uint8Array | undefined
+```
+
+## `DeepPartial<TObject>`
+
+Recursively makes all properties optional. Primitive types (`PrimitiveType`) are preserved 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]>;
+}>;
+```
+
+```typescript
+interface User {
+  name: string;
+  profile: {
+    age: number;
+    address: { city: string };
+  };
+}
+
+const partial: DeepPartial<User> = {
+  profile: { address: {} },
+};
+```
+
+## `Type<TInstance>`
+
+Constructor type interface. Represents a class constructor that creates instances of `TInstance`. Used for dependency injection, factory patterns, and `instanceof` checks.
+
+```typescript
+interface Type<TInstance> extends Function {
+  new (...args: unknown[]): TInstance;
+}
+```
+
+```typescript
+function create<T>(ctor: Type<T>): T {
+  return new ctor();
+}
+
+class MyClass { name = "test"; }
+const instance = create(MyClass); // MyClass instance
+```