@zyno-io/ts-server-foundation 26.712.36

package/docs/content/getting-started.md

@@ -0,0 +1,324 @@
+# Getting Started
+
+## Install
+
+Scaffold a project:
+
+```bash
+npx @zyno-io/ts-server-foundation create-app @myorg/my-api
+cd my-api
+corepack yarn install
+corepack yarn dev
+```
+
+Manual installation:
+
+```bash
+corepack yarn add @zyno-io/ts-server-foundation
+corepack yarn tsf-install
+```
+
+`tsf-install` adds the supported TypeScript/`ttsc` compiler dependencies and configures TSF's metadata transform. Scaffolded applications run it from `postinstall`.
+
+## Scaffold Anatomy
+
+The generated project is intentionally small:
+
+| Path                                                 | Purpose                                                                                                                                           |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/index.ts`                                       | Executable entrypoint. Initializes `@zyno-io/ts-server-foundation/otel` before loading the application, then calls `app.run()`.                   |
+| `src/app.ts`                                         | Creates and exports the application, database, controllers, and providers. Tests should import this module rather than the executable entrypoint. |
+| `src/config.ts`                                      | Application config class extending `BaseAppConfig`.                                                                                               |
+| `src/database.ts`                                    | MySQL database class and entity registry used by the example.                                                                                     |
+| `src/controllers/`, `src/services/`, `src/entities/` | Example HTTP, service, and database layers.                                                                                                       |
+| `src/migrations/`                                    | Source migration files; their compiled output under `dist/src/migrations/` is used by migration commands.                                         |
+| `tests/`                                             | Node test-runner tests compiled with `tsconfig.test.json`.                                                                                        |
+| `.env.development`                                   | Local port, MySQL connection, database adapter, and Redis key prefix. Do not commit real secrets.                                                 |
+| `package.json`                                       | Sets `main` to `./dist/src/index.js`, allowing `node . <command>` to dispatch through the compiled entrypoint.                                    |
+
+The generated scripts map to the development wrapper:
+
+| Script                | Command                       |
+| --------------------- | ----------------------------- |
+| `yarn build`          | `tsf-dev build`               |
+| `yarn dev`            | `tsf-dev run -- server:start` |
+| `yarn test`           | `tsf-dev test`                |
+| `yarn test:debug`     | `tsf-dev test --debug`        |
+| `yarn migrate`        | `tsf-dev migrate`             |
+| `yarn migrate:create` | `tsf-dev migrate:create`      |
+| `postinstall`         | `tsf-install`                 |
+
+The OTel-first entrypoint matters: instrumentation must load before HTTP, database, Redis, and other modules it patches. Keep application construction in `app.ts` so tests can import it without running command dispatch.
+
+## TypeScript Configuration
+
+Reflected type metadata is required for constructor injection, route parameter metadata, OpenAPI schemas, config loading, entity metadata, and custom type annotations.
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "lib": ["ES2022"],
+        "module": "commonjs",
+        "rootDir": ".",
+        "outDir": "dist",
+        "sourceMap": true,
+        "strict": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "skipLibCheck": true,
+        "experimentalDecorators": true,
+        "emitDecoratorMetadata": true,
+        "importHelpers": true,
+        "types": ["node"],
+        "plugins": [
+            {
+                "transform": "./node_modules/@zyno-io/ts-server-foundation/dist/src/type-compiler/index.cjs"
+            }
+        ]
+    },
+    "include": ["src/**/*.ts"],
+    "reflection": true
+}
+```
+
+Build with `ttsc`, as the scaffold and `tsf-dev` commands do. `tsf-install` installs the supported compiler and adds the transform plus top-level `reflection` setting; the full scaffold configuration above is the recommended baseline for a new application. The TSF compiler emits the reflected metadata used by these runtime systems. See [Type Reflection Architecture](./type-reflection-architecture.md) for the compiler and runtime metadata policy.
+
+For tests, extend the main config and include both source and tests:
+
+```json
+{
+    "extends": "./tsconfig.json",
+    "include": ["src/**/*.ts", "tests/**/*.ts"],
+    "reflection": true
+}
+```
+
+## Create an App
+
+```ts
+import { BaseAppConfig, createApp, createDatabase, http } from '@zyno-io/ts-server-foundation';
+
+class AppConfig extends BaseAppConfig {
+    APP_ENV = 'development';
+}
+
+@http.controller('/health-example')
+class ExampleController {
+    @http.GET()
+    get() {
+        return { ok: true };
+    }
+}
+
+class AppDatabase extends createDatabase('mysql', {}, []) {}
+
+export const app = createApp({
+    config: AppConfig,
+    db: AppDatabase,
+    controllers: [ExampleController]
+});
+
+if (require.main === module) {
+    void app.run();
+}
+```
+
+Run the server entrypoint with an explicit command:
+
+```bash
+node . server:start
+```
+
+`app.run()` handles command dispatch for `server:start`, `worker:start`, `migrate:run`, `openapi:generate`, and commands registered on the app. Direct HTTP server APIs live under `app.http`; for tests, demos, or embedded usage call `app.http.listen()`:
+
+Running `node .` without a command, or with an unknown command, prints usage and sets a failing exit code. Production process definitions should always include the intended command.
+
+```ts
+const server = await app.http.listen(0, '127.0.0.1');
+await app.stop();
+```
+
+Register app commands with `@cli.controller()` and the `commands` option:
+
+```ts
+import { cli, createApp, ScopedLogger } from '@zyno-io/ts-server-foundation';
+
+@cli.controller('receipts:requeue', { description: 'Requeue queued receipts' })
+class ReceiptsRequeueCommand {
+    constructor(private logger: ScopedLogger) {}
+
+    async execute(args: string[]) {
+        this.logger.info('Running receipts:requeue', { args });
+    }
+}
+
+export const app = createApp({
+    commands: [ReceiptsRequeueCommand]
+});
+```
+
+Run custom commands through the same compiled entrypoint:
+
+```bash
+node . receipts:requeue
+```
+
+## `createApp()` Options
+
+```ts
+interface CreateAppOptions<C extends BaseAppConfig = BaseAppConfig> extends ModuleDefinition<C> {
+    config?: ClassType<C>;
+    defaultConfig?: Partial<C>;
+    db?: ClassType;
+    frameworkConfig?: Record<string, unknown>;
+    serverConfig?: Record<string, unknown>;
+    cors?: HttpCorsConfig<C>;
+    staticFiles?: boolean | StaticFilesOptions;
+    httpResolvers?: RouteParameterResolverRegistry;
+    enableHealthcheck?: boolean;
+    enableWorker?: boolean;
+    enableDkRpc?: boolean;
+}
+```
+
+Common fields:
+
+| Option              | Description                                                                                   |
+| ------------------- | --------------------------------------------------------------------------------------------- |
+| `config`            | Config class. Defaults to `BaseAppConfig`.                                                    |
+| `defaultConfig`     | Default values applied before env files and `Env`.                                            |
+| `db`                | Database class from `createDatabase`, `createMySQLDatabase`, or `createPostgresDatabase`.     |
+| `controllers`       | HTTP controllers registered with the owned router.                                            |
+| `providers`         | DI providers. Classes, `useValue`, `useClass`, `useExisting`, and `useFactory` are supported. |
+| `imports`           | Imported modules. Exported providers from imported modules become globally injectable.        |
+| `exports`           | Providers exported by this module for global injection.                                       |
+| `listeners`         | Lifecycle/event listener classes.                                                             |
+| `commands`          | Classes decorated with `@cli.command()` or `@cli.controller()`.                               |
+| `frameworkConfig`   | HTTP runtime options; `port` overrides `config.PORT`.                                         |
+| `serverConfig`      | Secondary HTTP runtime options; `frameworkConfig` takes precedence for `port`.                |
+| `cors`              | Static CORS options or a config-driven factory.                                               |
+| `staticFiles`       | Static-file options, or `true` for the default `static/` directory with SPA fallback.         |
+| `httpResolvers`     | App-wide custom HTTP parameter resolvers keyed by reflected class name.                       |
+| `enableHealthcheck` | Set to `false` to skip the default `/healthz` endpoint.                                       |
+| `enableWorker`      | Registers worker services and job runners.                                                    |
+| `enableDkRpc`       | Legacy compatibility flag; the current runtime does not act on it.                            |
+
+## Application And HTTP Runtime
+
+`App` owns lifecycle, DI, config, command entrypoints, and module wiring. HTTP server behavior is exposed through `app.http`:
+
+```ts
+const app = createApp({ controllers: [ExampleController] });
+
+await app.start(); // optional; app.http.listen() starts it automatically
+const server = await app.http.listen(3000, '0.0.0.0');
+
+app.http.registerUpgradeHandler((request, socket, head) => {
+    // WebSocket or other upgrade handling
+});
+
+app.http.registerObserver(entry => {
+    // completed HTTP request observation
+});
+
+await app.stop();
+```
+
+Transport APIs live under `app.http` so the base application class stays focused on application lifecycle.
+
+## Dependency Injection
+
+Constructor dependencies are read from reflected type metadata:
+
+```ts
+class UserService {
+    constructor(private db: BaseDatabase) {}
+}
+```
+
+Resolve app-level providers outside constructor injection with `resolve()` or `r()`:
+
+```ts
+import { BaseAppConfig, r, resolve } from '@zyno-io/ts-server-foundation';
+
+const config = resolve(BaseAppConfig);
+const sameConfig = r(BaseAppConfig);
+```
+
+Exported providers from imported modules are globally injectable. You do not need to explicitly import a module at the injection site when a provider is exported by a module in the app graph.
+
+## AutoConstruct
+
+`@AutoConstruct()` instantiates a registered provider during app startup. The decorator does not register the class by itself:
+
+```ts
+import { AutoConstruct, createApp } from '@zyno-io/ts-server-foundation';
+
+@AutoConstruct()
+class StartupProbe {
+    constructor() {
+        // Runs when app.start() creates AutoConstruct providers.
+    }
+}
+
+const app = createApp({ providers: [StartupProbe] });
+```
+
+## Environment
+
+`APP_ENV` is required only when `NODE_ENV=production`. Tests infer `APP_ENV=test` from the Node test runner; other non-production processes default to `development`.
+
+Configuration is loaded from env files and `Env`. Values consumed by reflected config properties remain in `process.env`, so later code and child processes inherit the same environment.
+
+## Development, Test, And Production Setup
+
+For the generated MySQL example, create the database named by `MYSQL_DATABASE` and make the `.env.development` credentials usable before running migrations or calling the example endpoints. The scaffold unit test only constructs the app and does not require a live database. Redis is not required by the base scaffold; configure it when enabling BullMQ workers, mutexes, leader election, mesh services, caches, or broadcasts.
+
+Local development:
+
+```bash
+corepack enable
+corepack yarn install
+corepack yarn migrate
+corepack yarn dev
+```
+
+Tests compile source and tests with the reflection transform before invoking Node's test runner:
+
+```bash
+corepack yarn test
+corepack yarn test:debug
+```
+
+For production, provide environment variables through the deployment secret/config system, build once, and execute the compiled package entrypoint explicitly:
+
+```bash
+corepack yarn build
+APP_ENV=production node . server:start
+```
+
+Run migrations as a separate release step with `node . migrate:run`. If workers are enabled, use a separate `node . worker:start` process; see [Workers](./worker.md). A production database is required when the app registers one. Redis remains feature-dependent rather than an unconditional server prerequisite.
+
+## CLI
+
+Primary commands:
+
+```bash
+tsf create-app <package-name> [path]
+tsf test [node-test-options] [test-files-or-dirs...]
+tsf gen-proto <proto-file-or-dir> <output-dir> [options]
+
+tsf-dev build
+tsf-dev run -- server:start
+tsf-dev test
+tsf-dev migrate
+tsf-dev migrate:create
+tsf-dev migrate:reset
+tsf-dev migrate:charset
+tsf-dev openapi:generate
+```
+
+See [CLI Tools](./cli.md) for the detailed command reference.
+
+See [Public API](./public-api.md) for package export rules and import guidance.

package/docs/content/health.md

@@ -0,0 +1,64 @@
+# Health Checks
+
+TSF includes a health service and a default HTTP endpoint at `/healthz`.
+
+## Endpoint
+
+```http
+GET /healthz
+```
+
+Successful response:
+
+```json
+{ "version": "0.0.0-dev" }
+```
+
+The version comes from the cached `package.json` in the process working directory and falls back to `unknown` when that metadata is unavailable. If a registered health check throws, the endpoint returns a normalized HTTP error response.
+
+Disable the default endpoint with `createApp({ enableHealthcheck: false })`.
+
+## Registering Checks
+
+Inject `HealthcheckService` and register named checks.
+
+```ts
+import { HealthcheckService, sql } from '@zyno-io/ts-server-foundation';
+
+class DatabaseHealth {
+    constructor(health: HealthcheckService, db: AppDatabase) {
+        health.register('database', async () => {
+            await db.rawFind(sql`SELECT ${1}`);
+        });
+    }
+}
+```
+
+Checks return `void` or `Promise<void>`. Throw to mark the check unhealthy.
+
+## Service API
+
+```ts
+import { HealthcheckService } from '@zyno-io/ts-server-foundation';
+
+health.register('cache', async () => {
+    await cache.ping();
+});
+
+await health.check();
+const results = await health.checkIndividual();
+```
+
+| Method               | Description                                               |
+| -------------------- | --------------------------------------------------------- |
+| `register(name, fn)` | Adds a named check.                                       |
+| `check()`            | Runs all checks and throws on the first failure.          |
+| `checkIndividual()`  | Runs all checks and returns `{ name, status, error? }[]`. |
+
+## Request Logging
+
+Health check request logging is controlled separately from other HTTP routes.
+
+| Config key                       | Description                                                       |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `HEALTHZ_ENABLE_REQUEST_LOGGING` | Enables request logs for `/healthz` when true. Defaults to false. |

package/docs/content/helpers.md

@@ -0,0 +1,294 @@
+# Helpers
+
+TSF exports small utility helpers from the package root. They are grouped by async context, data manipulation, streams, Redis, security, dates, errors, and package metadata.
+
+## Async Context
+
+```ts
+import { getContext, getContextProp, removeContextProp, setContextProp, withContext, withContextData } from '@zyno-io/ts-server-foundation';
+
+await withContext(async () => {
+    setContextProp('reqId', 'abc');
+    getContextProp<string>('reqId'); // 'abc'
+});
+
+await withContextData({ userId: '123' }, async () => {
+    getContext(); // { userId: '123' }
+});
+```
+
+`withContextData()` restores overwritten values when the callback completes.
+
+## Promises And Processes
+
+```ts
+import { createSemaphore, deferred, execProcess } from '@zyno-io/ts-server-foundation';
+
+const semaphore = createSemaphore();
+semaphore.release();
+await semaphore.promise;
+
+const pending = deferred<string>();
+pending.resolve('done');
+await pending.promise;
+
+const result = await execProcess('git', ['status'], { cwd: process.cwd() });
+result.stdout.toString();
+```
+
+`execProcess()` throws on non-zero exit codes unless `errorOnNonZero: false` is passed.
+
+`ExecProcessOptions` also accepts `cwd`, `env`, `stdio`, `shell`, and `onSpawn`. Captured `stdout` and `stderr` are `Buffer` values; they are empty when the selected `stdio` mode does not expose child pipes. `onSpawn` receives the `ChildProcess` after spawn, and throwing from it kills the child and rejects the operation. Spawn and exit failures are wrapped with the command in the outer error message and the original failure as `cause`.
+
+## Arrays
+
+```ts
+import { asyncMap, chunk, toArray, unique } from '@zyno-io/ts-server-foundation';
+
+toArray('one'); // ['one']
+unique([1, 1, 2]); // [1, 2]
+chunk([1, 2, 3, 4], 2); // [[1, 2], [3, 4]]
+await asyncMap(items, async item => processItem(item));
+```
+
+`asyncMap()` runs sequentially.
+
+`chunk()` throws when its size is zero or negative. `unique()` uses JavaScript `Set` equality and preserves first-seen order.
+
+## Objects
+
+```ts
+import { extractKV, extractUpdates, extractValues, objectAssign, objectEntries, objectKeys, patchObject } from '@zyno-io/ts-server-foundation';
+
+const keys = objectKeys(user);
+const entries = objectEntries(user);
+const subset = extractValues(user, ['id', 'email'] as const);
+const updates = extractUpdates(current, next);
+patchObject(current, { name: 'Alice' });
+const namesById = extractKV(users, 'id', 'name');
+```
+
+`extractUpdates()` supports `equals` and `matches` comparison modes. `matches` recursively compares plain-object subsets.
+
+## Transformer
+
+```ts
+import { Transformer } from '@zyno-io/ts-server-foundation';
+
+const rows = await Transformer.create(users)
+    .apply(items => items.filter(item => item.active))
+    .applyEach(item => ({ ...item, label: item.name.toUpperCase() }))
+    .narrow('id', 'label')
+    .get();
+```
+
+Methods:
+
+| Method                             | Description                                         |
+| ---------------------------------- | --------------------------------------------------- |
+| `apply(fn, shouldApply?)`          | Transforms the whole array.                         |
+| `applyEach(fn, shouldApply?)`      | Maps each item synchronously.                       |
+| `applyEachAsync(fn, shouldApply?)` | Maps each item sequentially with an async function. |
+| `narrow(...keys)`                  | Keeps selected keys.                                |
+| `get()`                            | Resolves the transformed array.                     |
+
+## JSON
+
+```ts
+import { fromJson, safeJsonStringify, toJson } from '@zyno-io/ts-server-foundation';
+
+const text = toJson({ ok: true });
+const value = fromJson<{ ok: boolean }>(text);
+safeJsonStringify(circularObject);
+```
+
+`safeJsonStringify()` replaces circular references with `"[Circular]"`.
+
+## Streams
+
+```ts
+import { safePipe, PipeError } from '@zyno-io/ts-server-foundation';
+
+try {
+    await safePipe(input, output);
+} catch (error) {
+    if (error instanceof PipeError) {
+        error.side; // 'input' | 'output'
+    }
+}
+```
+
+`safePipe()` destroys the opposite stream when one side fails.
+
+## Resource Cleanup
+
+`withResourceCleanup()` owns temporary files and streams for the duration of an async operation:
+
+```ts
+import { createReadStream } from 'node:fs';
+import { withResourceCleanup } from '@zyno-io/ts-server-foundation';
+
+const result = await withResourceCleanup(async tracker => {
+    tracker.addFile('/tmp/generated-report');
+    tracker.addStream(createReadStream('/tmp/generated-report'));
+    return processReport();
+});
+```
+
+The callback receives a `ResourceTracker`:
+
+| Method          | Behavior                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------------- |
+| `addFile(path)` | Records a file to unlink during cleanup. Missing/unlink-failed files are ignored.               |
+| `addStream(s)`  | Records a readable or writable stream, captures its first emitted error, and destroys it later. |
+| `getFailure()`  | Returns the first recorded stream error, if any.                                                |
+| `cleanup()`     | Unlinks tracked files and destroys tracked streams that are not already destroyed.              |
+
+Cleanup runs in `finally` after success or failure. If the callback finishes but a tracked stream has already emitted an error, `withResourceCleanup()` rejects with that error. Its optional `onError` callback observes callback/recorded failures before cleanup; it does not suppress them.
+
+## Package Metadata
+
+```ts
+import { getPackageJson, getPackageName, getPackageVersion, resetPackageJsonCache } from '@zyno-io/ts-server-foundation';
+
+getPackageName();
+getPackageVersion();
+resetPackageJsonCache();
+```
+
+Package metadata is read from `process.cwd()/package.json` and cached.
+
+## Security
+
+```ts
+import {
+    AlphanumericCharacters,
+    Crypto,
+    NumericCharacters,
+    PrintableCharacters,
+    UpperCaseAlphanumericCharacters,
+    randomBytes,
+    randomBytesSync,
+    randomString,
+    randomStringSync
+} from '@zyno-io/ts-server-foundation';
+
+const token = await randomString(32, AlphanumericCharacters);
+const pin = randomStringSync(6, NumericCharacters);
+const recoveryCode = randomStringSync(12, UpperCaseAlphanumericCharacters);
+const printable = randomStringSync(24, PrintableCharacters);
+const bytes = await randomBytes(32);
+const hex = randomBytesSync(16, true);
+
+const encrypted = Crypto.encrypt('secret');
+const decrypted = Crypto.decrypt(encrypted);
+```
+
+`Crypto` uses AES-256-GCM. `CRYPTO_SECRET` must be 32 bytes or 64 hex characters. `CRYPTO_IV_LENGTH` defaults to 12.
+
+The four exported character sources are `PrintableCharacters` (ASCII 32 through 126), `AlphanumericCharacters`, `UpperCaseAlphanumericCharacters`, and `NumericCharacters`. `randomString()` and `randomStringSync()` default to `AlphanumericCharacters` and reject an empty source. Character selection uses random bytes modulo the source length.
+
+`randomBytes(length, true)` and `randomBytesSync(length, true)` return hex strings; without `true` they return `Buffer` values. String encryption returns base64 and string decryption returns UTF-8. Buffer input produces Buffer output. Invalid/truncated payloads or authentication-tag failures throw. Use `new Crypto({ secret })` for app-independent settings with the default 12-byte IV, or also pass `ivLength` to override it. When `secret` is omitted, construction reads application configuration. The static methods share a lazily created instance, and `Crypto.reset()` clears that instance so changed application configuration is read on the next static call.
+
+`assertInput()` and `isValidEmail()` provide lightweight boundary checks independent of reflection:
+
+```ts
+import { assertInput, isValidEmail } from '@zyno-io/ts-server-foundation';
+
+assertInput(value, 'email');
+if (!isValidEmail(value)) throw new Error('Invalid email');
+```
+
+`assertInput()` rejects `undefined`, `null`, and `''`; it does not reject other falsey values such as `0` or `false`. `isValidEmail()` is a simple whitespace/`@`/dot shape check, not mailbox verification.
+
+## Reflected Deserialization And Validation
+
+```ts
+import { assertInput, deserialize, validate, validatedDeserialize } from '@zyno-io/ts-server-foundation';
+
+const deserialized = deserialize<MyInput>(payload);
+const errors = validate<MyInput>(payload);
+const input = validatedDeserialize<MyInput>(payload);
+assertInput(payload.name, 'name');
+```
+
+The generic `deserialize<T>()`, `validate<T>()`, and `validatedDeserialize<T>()` calls require TSF's metadata compiler transform when the reflected type is supplied only through `T`.
+
+| Helper                      | Deserializes | Validates | Failure behavior                                 |
+| --------------------------- | ------------ | --------- | ------------------------------------------------ |
+| `deserialize<T>()`          | Yes          | No        | Returns the transformed value.                   |
+| `validate<T>()`             | No           | Yes       | Returns every reflected `ValidatorError`.        |
+| `validatedDeserialize<T>()` | Yes          | Yes       | Deserializes first, then throws the first error. |
+
+The compatibility exports `cast<T>()`, `assert<T>()`, and `is<T>()` receive generic metadata when they are imported directly from `@zyno-io/ts-server-foundation`. The compiler checks import identity so application helpers with the same short names are not transformed. Uncompiled calls and calls without a generic type require an explicit reflected `Type` argument and throw when it is absent.
+
+Deserialization recursively coerces supported primitives, arrays, tuples, objects, unions, intersections, and reflected classes. It also applies registered transforms such as `TrimmedString` trimming and phone normalization. Reflected object DTOs are reconstructed from their declared properties, so undeclared input properties are generally dropped rather than rejected. Union deserialization uses validation internally to select the first matching branch, but `deserialize<T>()` does not perform a final whole-value validation pass.
+
+Validation checks required/null handling, primitive and structured shapes, literals, enums, unions, and reflected constraints such as patterns, lengths, numeric bounds, and custom validators. `NaN` is not a valid reflected `number`; positive and negative infinity remain valid JavaScript numbers unless a narrower constraint rejects them.
+
+Use `validatedDeserialize<T>()` for untrusted input whenever a type has transforms. Calling `validate<T>()` directly does not trim or normalize first. The exported `deserializer` is the global transform registry used by library-provided and custom reflected types; there is intentionally no reflected outbound serializer registry.
+
+`assertInput()` is separate from reflected validation. It throws `HttpBadRequestError` when a value is `undefined`, `null`, or an empty string.
+
+## Dates And UUIDs
+
+```ts
+import { extractDate, sleepMs, sleepSecs, uuid4, uuid7, uuid7FromDate } from '@zyno-io/ts-server-foundation';
+
+await sleepMs(100);
+await sleepSecs(2);
+const day = extractDate(new Date());
+const id = uuid7();
+const randomId = uuid4();
+const historicalId = uuid7FromDate(new Date('2026-01-01T00:00:00Z'));
+```
+
+`extractDate()` accepts a `Date`, timestamp, or date string and returns the UTC `YYYY-MM-DD` portion of its ISO representation. Invalid date input throws when converted to ISO.
+
+`uuid7()` creates time-ordered UUID v7 strings. `uuid7FromDate()` creates a v7 value using the supplied date's timestamp; it is not a deterministic hash of the date. `uuid4()` creates random UUID v4 strings.
+
+## Error Helpers And Reporting
+
+```ts
+import { getErrorMessage, isError, reportError, setGlobalErrorReporter, toError, tryOrError, tryOrErrorSync } from '@zyno-io/ts-server-foundation';
+
+const error = toError('failed to process input', unknownError);
+const parsed = tryOrErrorSync(() => JSON.parse(text));
+const fetched = await tryOrError(() => fetchData());
+
+setGlobalErrorReporter((level, reported, context) => {
+    auditError(level, reported, context);
+});
+reportError(3, error, { scope: 'ImportJob', data: { fileId } });
+```
+
+`isError()` recognizes ordinary and native errors. `getErrorMessage()` returns an error's message or `String(value)`. `toError()` preserves an existing `Error`, converts other values with `String`, and attaches a recursively normalized `cause` when supplied. `tryOrErrorSync()` and `tryOrError()` return caught failures as `Error` values instead of throwing, so callers must distinguish the result with `isError()`.
+
+`reportError()` synchronously calls the registered global reporter, sends the exception to Sentry when installed, and starts a Slack webhook notification only for level `1`. A throwing global reporter is isolated and logged so it does not prevent Sentry or Slack handling. Level `1` maps to Sentry `fatal`, level `3` to `warning`, and other levels to `error`. Populate `SentryLiftKeysToTagsFromLoggerContext` with primitive logger-context keys that should be lifted to Sentry tags; the remaining logger context stays in the event details. Slack delivery is asynchronous and delivery errors are logged rather than thrown to the caller.
+
+See [Logging](./logging.md#error-handling) for logger integration and alert configuration.
+
+## Redis Helpers
+
+```ts
+import { Cache, createBroadcastChannel, createRedis, createRedisOptions, disconnectAllRedis, withMutex } from '@zyno-io/ts-server-foundation';
+
+const { client, prefix } = createRedis('CACHE');
+await Cache.setObj('settings', { enabled: true }, 60);
+
+const channel = createBroadcastChannel<{ id: string }>('item.changed');
+channel.subscribe(message => console.log(message.id));
+channel.publish({ id: '123' });
+
+await withMutex({
+    key: ['job', 'daily'],
+    fn: async didWait => runJob(didWait),
+    mode: 'redis'
+});
+
+await disconnectAllRedis();
+```
+
+Redis config prefixes map keys like `CACHE_REDIS_HOST` to the base Redis option names for that connection.
+
+See [Redis](./redis.md) for cache, mutex, broadcast, and distributed-method details.