@zyno-io/ts-server-foundation 26.712.36

package/docs/content/redis.md

@@ -0,0 +1,174 @@
+# Redis
+
+Utilities for Redis-backed caching, distributed locking, and inter-process communication.
+
+## Client Creation
+
+```typescript
+import { createRedis, createRedisOptions } from '@zyno-io/ts-server-foundation';
+
+// Create with default config (REDIS_HOST, REDIS_PORT)
+const { client, prefix } = createRedis();
+
+// Create with specific config prefix (uses CACHE_REDIS_* and falls back to REDIS_*)
+const { client, prefix } = createRedis('CACHE');
+```
+
+Each call creates a separate connection. All clients are tracked and can be disconnected with `disconnectAllRedis()`.
+
+## Cache
+
+Redis-backed cache with TTL support:
+
+```typescript
+import { Cache } from '@zyno-io/ts-server-foundation';
+
+// String values
+await Cache.set('key', 'value', 3600); // TTL in seconds
+const value = await Cache.get('key');
+
+// Object values (auto JSON serialization)
+await Cache.setObj('user:123', { name: 'Alice', role: 'admin' }, 3600);
+const user = await Cache.getObj<{ name: string; role: string }>('user:123');
+```
+
+| Method                        | Description                                    |
+| ----------------------------- | ---------------------------------------------- |
+| `Cache.get(key)`              | Get a string value (returns `null` if missing) |
+| `Cache.set(key, val, ttl)`    | Set a string value with TTL in seconds         |
+| `Cache.getObj<T>(key)`        | Get and deserialize a JSON value               |
+| `Cache.setObj(key, val, ttl)` | Serialize and set a JSON value with TTL        |
+
+Uses `CACHE_REDIS_*` environment variables (falls back to `REDIS_*`).
+
+## Distributed Mutex
+
+Redis-backed distributed locking for coordinating work across multiple instances:
+
+```typescript
+import { withMutex, withMutexes, MutexAcquisitionError } from '@zyno-io/ts-server-foundation';
+
+// Single mutex
+const result = await withMutex({
+    key: ['user', userId],
+    fn: async didWait => {
+        // Critical section - only one instance executes at a time
+        // didWait: true if we had to wait for the lock
+        return await processPayment(userId);
+    },
+    retryCount: 30, // Max retry attempts (default: 30)
+    retryDelay: 1000, // Delay between retries in ms (default: 1000)
+    renewInterval: 1000 // Lock renewal interval in ms (default: 1000)
+});
+
+// Multiple mutexes (acquired in order)
+const result = await withMutexes({
+    keys: [
+        ['resource', resourceA],
+        ['resource', resourceB]
+    ],
+    fn: async didWait => {
+        return await updateResources(resourceA, resourceB);
+    }
+});
+```
+
+### Keys
+
+Mutex keys can be primitives or arrays: `['resource', 123]` becomes `resource:123`.
+
+### Error Handling
+
+Throws `MutexAcquisitionError` if the lock cannot be acquired within the retry window.
+
+### Options
+
+| Option          | Type                               | Default | Description                            |
+| --------------- | ---------------------------------- | ------- | -------------------------------------- |
+| `key` / `keys`  | `MutexKey`                         | —       | Lock key(s) — string, number, or array |
+| `fn`            | `(didWait: boolean) => Promise<T>` | —       | Function to execute under lock         |
+| `retryCount`    | `number`                           | `30`    | Max retry attempts                     |
+| `retryDelay`    | `number`                           | `1000`  | Delay between retries (ms)             |
+| `renewInterval` | `number`                           | `1000`  | Lock renewal interval (ms)             |
+
+### Modes
+
+Configure via `MUTEX_MODE`:
+
+- **`local`** (default) — In-process locking with no Redis dependency. Useful for single-instance or testing scenarios.
+- **`redis`** — Uses Redis Lua scripts for atomic acquire/release/renew. Suitable for multi-instance deployments.
+
+Uses `MUTEX_REDIS_*` environment variables (falls back to `REDIS_*`).
+
+### DevConsole Integration
+
+Active mutexes and acquisition history are visible in the [DevConsole](./devconsole.md) Mutex view.
+
+## Broadcast Channels
+
+Redis pub/sub for inter-process communication:
+
+```typescript
+import { createBroadcastChannel } from '@zyno-io/ts-server-foundation';
+
+// Create a typed broadcast channel
+const channel = createBroadcastChannel<{ userId: string; action: string }>('user-events');
+
+channel.subscribe(data => {
+    console.log(`${data.userId}: ${data.action}`);
+});
+
+channel.publish({ userId: '123', action: 'login' });
+```
+
+### Distributed Methods
+
+Execute a function locally and broadcast to all instances:
+
+```typescript
+import { createDistributedMethod } from '@zyno-io/ts-server-foundation';
+
+class CacheManager {
+    invalidate = createDistributedMethod<{ key: string }>(
+        {
+            name: 'invalidate',
+            logger: () => this.logger
+        },
+        async data => {
+            this.localCache.delete(data.key);
+        }
+    );
+}
+
+// Calling invalidate() runs locally AND broadcasts to all instances
+await cacheManager.invalidate({ key: 'user:123' });
+```
+
+The `logger` option takes a getter function so it can reference `this.logger` even when used as a class field initializer. If omitted, a default logger scoped to `Distributed:<name>` is used.
+
+Uses `BROADCAST_REDIS_*` environment variables (falls back to `REDIS_*`).
+
+## Configuration
+
+All Redis utilities support independent connection configuration via environment variable prefixes:
+
+| Utility   | Env Prefix          | Fallback  |
+| --------- | ------------------- | --------- |
+| Cache     | `CACHE_REDIS_*`     | `REDIS_*` |
+| Mutex     | `MUTEX_REDIS_*`     | `REDIS_*` |
+| Broadcast | `BROADCAST_REDIS_*` | `REDIS_*` |
+| Mesh      | `MESH_REDIS_*`      | `REDIS_*` |
+| BullMQ    | `BULL_REDIS_*`      | `REDIS_*` |
+
+Common variables for each prefix:
+
+| Variable                | Description                | Default      |
+| ----------------------- | -------------------------- | ------------ |
+| `*_REDIS_HOST`          | Redis host                 | unset        |
+| `*_REDIS_PORT`          | Redis port                 | `6379`       |
+| `*_REDIS_PREFIX`        | Key prefix                 | package name |
+| `*_REDIS_SENTINEL_HOST` | Redis Sentinel host        | unset        |
+| `*_REDIS_SENTINEL_PORT` | Redis Sentinel port        | `26379`      |
+| `*_REDIS_SENTINEL_NAME` | Redis Sentinel master name | unset        |
+
+For the default shared connection, omit the utility prefix and use `REDIS_HOST`, `REDIS_PORT`, `REDIS_PREFIX`, and `REDIS_SENTINEL_*`.

package/docs/content/reflection.md

@@ -0,0 +1,180 @@
+# Type Reflection
+
+TSF's compiler emits runtime descriptions of TypeScript types. Routing, dependency injection, validation, deserialization, OpenAPI, configuration, and database metadata all consume this shared representation.
+
+This page documents the public runtime APIs. See [Type Reflection Architecture](./type-reflection-architecture.md) for compiler policy and subsystem boundaries.
+
+## Compiler Requirement
+
+Generic reflection calls work because the TSF compiler adds a metadata argument to recognized calls. Configure the transform as described in [Getting Started](./getting-started.md#typescript-configuration), and build application code with `ttsc` or the TSF commands.
+
+The compiler recognizes these generic entrypoints:
+
+- `typeOf<T>()`
+- `deserialize<T>()`
+- `validate<T>()`
+- `validatedDeserialize<T>()`
+- `cast<T>()`
+- `assert<T>()`
+- `is<T>()`
+
+Calling `typeOf<T>()`, `deserialize<T>()`, or `validatedDeserialize<T>()` from JavaScript that did not pass through the transform throws a missing-metadata error. `validate(value, Class)` can instead read metadata already attached to a compiled class.
+
+An untransformed `validate<T>(plainObject)` call has no target metadata and therefore returns no errors. Do not treat that fail-open result as validation; compile the call, or pass a compiled class/reflected `Type` explicitly.
+
+The compiler recognizes the short compatibility exports `cast<T>()`, `assert<T>()`, and `is<T>()` only when they are imported from `@zyno-io/ts-server-foundation`. Import identity keeps application functions with the same common names from being transformed. Calls that do not pass through the compiler or do not specify a generic type must provide an explicit reflected `Type`; otherwise they throw a missing-metadata error.
+
+## Inspecting A Type
+
+`typeOf<T>()` returns a reflected `Type`. Narrow it with `ReflectionKind` before reading kind-specific fields.
+
+```ts
+import { ReflectionKind, typeOf } from '@zyno-io/ts-server-foundation';
+
+interface CreateUser {
+    email: string;
+    displayName?: string;
+}
+
+const type = typeOf<CreateUser>();
+
+if (type.kind === ReflectionKind.objectLiteral) {
+    for (const property of type.types) {
+        console.log(String(property.name), property.optional === true, property.type.kind);
+    }
+}
+```
+
+The `Type` union includes primitives, literals, arrays, tuples, unions, intersections, object literals, classes, promises, enums, and property signatures. Prefer narrowing by `kind` over relying on a `typeName`: names are descriptive and are not a substitute for annotation metadata.
+
+## Inspecting Classes
+
+Use `ReflectionClass.from(Class)` for a compiled class. It throws when neither that class nor an inherited base class has runtime metadata.
+
+```ts
+import { ReflectionClass } from '@zyno-io/ts-server-foundation';
+import { User } from './entities/User';
+
+const reflection = ReflectionClass.from(User);
+const primary = reflection.getPrimary();
+const save = reflection.getMethod('save');
+
+console.log(reflection.name);
+console.log(primary.getNameAsString(), primary.getType());
+console.log(save.getParameters(), save.getReturnType());
+```
+
+Public reflection wrappers:
+
+| Wrapper               | Available information                                                                                                                  |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `ReflectionClass`     | Runtime class, name, collection name, indexes, migration exclusion, properties, methods, constructor parameters, and primary property. |
+| `ReflectionProperty`  | Name, type, description, optional/null state, primary/auto-increment markers, database metadata, and reference metadata.               |
+| `ReflectionMethod`    | JSDoc description, parameters, and return type.                                                                                        |
+| `ReflectionParameter` | Name, type, optional state, and whether a default exists.                                                                              |
+
+`getProperty()`, `getMethod()`, and `getPrimary()` throw when the requested member is absent. `getConstructorOrUndefined()` returns `undefined` for a zero-argument constructor without reflected parameters. Inherited properties and methods are included, with derived declarations replacing same-named base declarations.
+
+`registerClassMetadata()` is exported for compiler and integration tooling that already has a complete `ClassMetadata` object. Normal applications should let the compiler attach metadata.
+
+## Reading Annotations
+
+Annotation readers accept a reflected `Type` and search the relevant nested metadata surfaces.
+
+```ts
+import {
+    databaseAnnotation,
+    ReflectionKind,
+    typeAnnotation,
+    typeOf,
+    validationAnnotation,
+    type DateString,
+    type Length
+} from '@zyno-io/ts-server-foundation';
+
+const reflected = typeOf<{ birthday: DateString; code: Length<8> }>();
+if (reflected.kind !== ReflectionKind.objectLiteral) throw new Error('Expected an object literal');
+
+const birthday = reflected.types.find(property => property.name === 'birthday')!.type;
+const code = reflected.types.find(property => property.name === 'code')!.type;
+
+typeAnnotation.getType(birthday, 'tsf:type');
+databaseAnnotation.getDatabase(birthday, 'mysql');
+validationAnnotation.getAnnotations(code);
+```
+
+The readers have distinct roles:
+
+| Reader                                          | Result                                                                                                                     |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `typeAnnotation.getType(type, name)`            | The reflected annotation payload, including compatible `typia.tag` metadata for TSF/OpenAPI annotation names.              |
+| `typeAnnotation.getOption(type, name)`          | Compatibility alias of `getType()`.                                                                                        |
+| `validationAnnotation.getAnnotations(type)`     | Deduplicated length, numeric-bound, pattern, format-derived, and named-validator annotations.                              |
+| `databaseAnnotation.getDatabase(type, dialect)` | Database options for the requested dialect, with generic `'*'` metadata as fallback. MySQL-only tags do not leak to `'*'`. |
+
+Do not infer behavior from alias names. For example, a user type merely named `UuidString` is not a UUID unless its reflected annotations say so.
+
+## Custom Named Validators
+
+Register a validator name once during application/module initialization, then attach that name with `Validate<'name'>`.
+
+```ts
+import { ValidatorError, validate, validationRegistry, type Validate } from '@zyno-io/ts-server-foundation';
+
+validationRegistry.register('uppercaseCode', value => {
+    if (typeof value !== 'string' || !/^[A-Z]+$/.test(value)) {
+        return new ValidatorError('uppercaseCode', 'The value must contain uppercase letters only.');
+    }
+});
+
+type UppercaseCode = string & Validate<'uppercaseCode'>;
+
+const errors = validate<{ code: UppercaseCode }>({ code: 'abc' });
+```
+
+A validator returns `undefined`/`void` for success or a `ValidatorError` for failure. TSF replaces the returned error path with the actual nested input path. Registering the same name again replaces its function. If no function is registered for a reflected validator name, that annotation does not produce a validation error, so shared validator modules must be imported before input is handled.
+
+## Custom Deserializers
+
+The exported `deserializer` is a process-global registry of incoming transforms. A decorator predicate selects reflected types, and its handler adds one or more value transforms.
+
+```ts
+import { deserializer, deserialize, typeAnnotation, type TsfTypiaTag } from '@zyno-io/ts-server-foundation';
+
+type LowercaseString = string & TsfTypiaTag<'string', 'tsf:lowercase'>;
+
+deserializer.addDecorator(
+    type => typeAnnotation.getType(type, 'tsf:lowercase') !== undefined,
+    (_type, state) => {
+        state.addTransform(value => (typeof value === 'string' ? value.toLowerCase() : value));
+    }
+);
+
+const value = deserialize<{ name: LowercaseString }>({ name: 'ALICE' });
+```
+
+Matching decorators run in registration order, and each decorator's transforms run in the order they were added. The registry has no removal API, so libraries should use specific annotation names and register decorators once at module load. Deserialization is not a final validation pass; use `validatedDeserialize<T>()` when transformed input must also be validated.
+
+There is intentionally no reflected outbound serializer registry. HTTP output uses ordinary JSON serialization, while database I/O uses column-specific conversion.
+
+## Shared Package Aliases
+
+The compiler can preserve a named type alias imported from another package when that package was also built with the TSF compiler. Its emitted JavaScript exposes a generated `__tsfTypeAliases` map keyed by exported alias name.
+
+For a shared package:
+
+1. Compile the package with the TSF transform, not plain `tsc`.
+2. Export the aliases from a runtime-loadable package entrypoint.
+3. Publish the transformed JavaScript and its declarations together.
+4. Preserve the generated `__tsfTypeAliases` export when bundling or rewriting output.
+5. Compile the consuming application with the TSF transform as well.
+
+`__tsfTypeAliases` is generated compiler data, not an application API to edit by hand. The consumer resolves it by package import/export identity; TSF does not rely on a monorepo path, workspace name, or consumer-specific model name.
+
+If a package is built without emitted alias metadata, the consumer may retain only an unresolved external type boundary. Validation, deserialization, and OpenAPI cannot safely reconstruct missing alias semantics from the alias name alone.
+
+## Runtime Boundaries
+
+Reflection availability does not mean every subsystem automatically validates values. HTTP input and `validatedDeserialize<T>()` deserialize and validate; database entity I/O performs storage conversion without reflected validation; controller return values use ordinary JSON serialization.
+
+See [Helpers](./helpers.md#reflected-deserialization-and-validation) for conversion behavior and [Database](./database.md#runtime-value-conversion-and-validation) for the storage boundary.

package/docs/content/release.md

@@ -0,0 +1,100 @@
+# Release Checklist
+
+This page captures the package-level checks that should pass before publishing or handing off a release candidate.
+
+## Package Manager
+
+Use Yarn Berry through Corepack.
+
+```bash
+corepack yarn --version
+corepack yarn install --immutable
+```
+
+The repository uses Yarn 4 and `nodeLinker: node-modules`.
+
+## Build
+
+```bash
+corepack yarn build
+```
+
+The build performs a clean TypeScript compile, builds the DevConsole assets, and makes compiled CLI files executable.
+
+For local iteration:
+
+```bash
+corepack yarn build:dirty
+```
+
+## Tests
+
+```bash
+corepack yarn test
+corepack yarn test-app
+```
+
+`test` builds the package and runs compiled `node:test` specs. `test-app` builds and runs the integration-style sample app under `test-app/`.
+
+Database tests require local database services according to the testing config. See [Testing](./testing.md).
+
+## Docs
+
+```bash
+corepack yarn docs:build
+```
+
+The generated VitePress output is written to `docs/.vitepress/dist/` and should not be committed as source.
+
+## OpenAPI
+
+For apps that generate clients from the schema, regenerate OpenAPI from the compiled app.
+
+```bash
+corepack yarn tsf-dev openapi:generate
+```
+
+This builds the app and invokes the package `main` with the built-in `openapi:generate` app command.
+
+The runtime can also serve `/openapi.json` and `/openapi.yaml` when `ENABLE_OPENAPI_ROUTE=true`.
+
+## Package Contents
+
+The package publishes:
+
+- `dist/src/`
+- `dist/devconsole/`
+- `docs/content/`
+- `docs/.vitepress/config.mts`
+- `docs/openapi.md`
+- `resources/`
+- `template-app/`
+- `types.d.ts`
+- `package.json`
+
+The supported import paths are the root export and the `/otel` OpenTelemetry bootstrap export. Although `package.json` is included in the tarball, it is not exposed through the package `exports` map. See [Public API](./public-api.md).
+
+## Local Pack Inspection
+
+Use a dry run to inspect the tarball list.
+
+```bash
+npm pack --dry-run
+```
+
+Confirm generated build outputs are present and local-only artifacts such as `docs/.vitepress/dist/` are absent unless intentionally published.
+
+## Versioning Notes
+
+CI derives release versions from the commit timestamp in UTC using `YY.MDD.HHmm`-style calendar versioning (for example, `26.711.1430` for July 11, 2026 at 14:30 UTC). Non-`main` builds append `-canary.<short-sha>`. Consumers that require reproducible behavior should pin an exact version rather than assuming semantic-version compatibility between calendar releases.
+
+Treat these as breaking changes:
+
+- removing or renaming a root export
+- changing package export paths
+- changing HTTP parameter resolution semantics
+- changing database migration output for existing annotations
+- changing OpenAPI operation IDs or schema shapes
+- changing CLI command names or required flags
+
+Update docs in the same change as API behavior changes.

package/docs/content/sql.md

@@ -0,0 +1,121 @@
+# SQL
+
+The `sql` helper builds parameterized SQL fragments that render correctly for MySQL/MariaDB and PostgreSQL.
+
+```ts
+import { renderSql, sql } from '@zyno-io/ts-server-foundation';
+
+const query = sql`
+    SELECT ${sql.identifier('id')}, ${sql.identifier('email')}
+    FROM ${sql.identifier('users')}
+    WHERE ${sql.identifier('active')} = ${true}
+`;
+
+renderSql(query, 'postgres');
+// { sql: 'SELECT "id", "email" FROM "users" WHERE "active" = $1', bindings: [true] }
+```
+
+## Values
+
+Interpolated plain values become bindings.
+
+```ts
+await db.rawFind(sql`SELECT * FROM ${sql.identifier('users')} WHERE ${sql.identifier('id')} = ${userId}`);
+```
+
+Rendering uses `?` placeholders for MySQL/MariaDB and `$1`, `$2`, ... placeholders for PostgreSQL.
+
+## Identifiers
+
+Use `sql.identifier()` for table, schema, and column names.
+
+```ts
+sql.identifier('users');
+sql.identifier('public', 'users');
+```
+
+Identifiers are quoted for the target dialect. Identifier segments cannot be empty or contain null bytes.
+
+## Joining Fragments
+
+Use `sql.join()` when building dynamic lists.
+
+```ts
+const columns = ['id', 'email', 'name'].map(name => sql.identifier(name));
+const query = sql`SELECT ${sql.join(columns)} FROM ${sql.identifier('users')}`;
+```
+
+The default separator is `, `. Pass a custom SQL fragment for other separators.
+
+```ts
+const where = sql.join(
+    filters.map(filter => sql`${sql.identifier(filter.field)} = ${filter.value}`),
+    sql` AND `
+);
+```
+
+## Trusted Raw SQL
+
+Use `sql.rawTrusted()` only for static SQL keywords or expressions that are not user input.
+
+```ts
+const direction = sortDescending ? sql.rawTrusted('DESC') : sql.rawTrusted('ASC');
+const query = sql`SELECT * FROM ${sql.identifier('users')} ORDER BY ${sql.identifier('name')} ${direction}`;
+```
+
+Never pass untrusted strings to `rawTrusted()`.
+
+## Placeholder Strings
+
+`createSqlQuery(sqlText, bindings)` accepts `?` placeholders and a bindings array.
+
+```ts
+import { createSqlQuery } from '@zyno-io/ts-server-foundation';
+
+const query = createSqlQuery('SELECT * FROM users WHERE email = ?', ['a@example.com']);
+await db.rawFind(query);
+```
+
+The number of `?` placeholders must match the number of bindings.
+
+## Raw Database Methods
+
+```ts
+const rows = await db.rawFind<UserRow>(sql`SELECT * FROM ${sql.identifier('users')}`);
+const row = await db.rawFindOne<UserRow>(sql`SELECT * FROM ${sql.identifier('users')} WHERE ${sql.identifier('id')} = ${id}`);
+const result = await db.rawExecute(sql`DELETE FROM ${sql.identifier('users')} WHERE ${sql.identifier('id')} = ${id}`);
+```
+
+`rawFind<T>()` and `rawFindOne<T>()` return driver-provided row values; their generic type is not a runtime deserialization or validation request. SQL bindings normalize valid `Date` values to UTC SQL date-time strings and JavaScript `bigint` values to decimal strings, but raw methods do not have entity column metadata for UUID, date-only, binary, JSON, or point conversion.
+
+Session methods mirror database methods and run on the session connection:
+
+```ts
+await db.transaction(async session => {
+    await session.rawExecute(sql`INSERT INTO ${sql.identifier('audit_log')} (${sql.identifier('message')}) VALUES (${'started'})`);
+});
+```
+
+## Unsafe Methods
+
+The unsafe methods take a string and bindings array directly.
+
+```ts
+await db.rawFindUnsafe('SELECT * FROM users WHERE email = ?', ['a@example.com']);
+await session.rawExecuteUnsafe('UPDATE users SET active = ? WHERE id = ?', [false, id]);
+```
+
+Prefer the `sql` tag for new code because identifiers and values stay explicit in the same expression.
+
+When TSF's metadata compiler can provide `T`, `rawFindUnsafe<T>()` and `rawFindOneUnsafe<T>()` reflected-deserialize returned rows. They still do not validate them. This behavior is specific to the unsafe methods' receive-type signature; use query-builder entity reads for column-aware hydration.
+
+## Rendering For Logs Or Tests
+
+```ts
+const rendered = renderSql(sql`SELECT ${1}`, 'mysql');
+
+rendered.sql; // 'SELECT ?'
+rendered.bindings; // [1]
+```
+
+`renderSql()` is useful for assertions, debugging, and custom drivers.