@zyno-io/dk-server-foundation 26.216.430

package/docs/content/configuration.md

@@ -0,0 +1,175 @@
+# Configuration
+
+Configuration is managed via `BaseAppConfig`, which uses `@zyno-io/config` to load values from environment variables. Extend it with your own properties.
+
+```typescript
+import { BaseAppConfig } from '@zyno-io/dk-server-foundation';
+
+class AppConfig extends BaseAppConfig {
+    STRIPE_KEY_SECRET!: string;
+    MAX_UPLOAD_SIZE: number = 10_000_000;
+}
+```
+
+Properties ending in `_SECRET` are treated as secrets by the config loader.
+
+## Built-in Configuration
+
+### Application
+
+| Variable  | Type     | Default | Description                                                 |
+| --------- | -------- | ------- | ----------------------------------------------------------- |
+| `APP_ENV` | `string` | —       | Application environment (`development`, `production`, etc.) |
+| `PORT`    | `number` | `3000`  | HTTP server port                                            |
+
+### MySQL Database
+
+| Variable                     | Type     | Default             | Description              |
+| ---------------------------- | -------- | ------------------- | ------------------------ |
+| `MYSQL_HOST`                 | `string` | —                   | Database host            |
+| `MYSQL_PORT`                 | `number` | —                   | Database port            |
+| `MYSQL_USER`                 | `string` | —                   | Database user            |
+| `MYSQL_PASSWORD_SECRET`      | `string` | —                   | Database password        |
+| `MYSQL_DATABASE`             | `string` | —                   | Database name            |
+| `MYSQL_CONNECTION_LIMIT`     | `number` | 10 (prod) / 5 (dev) | Max pool connections     |
+| `MYSQL_MIN_IDLE_CONNECTIONS` | `number` | — (prod) / 1 (dev)  | Minimum idle connections |
+| `MYSQL_IDLE_TIMEOUT_SECONDS` | `number` | 60 (prod) / 5 (dev) | Idle connection timeout  |
+
+### JWT Authentication
+
+| Variable                   | Type      | Default | Description                             |
+| -------------------------- | --------- | ------- | --------------------------------------- |
+| `AUTH_JWT_ISSUER`          | `string`  | —       | JWT issuer claim                        |
+| `AUTH_JWT_EXPIRATION_MINS` | `number`  | —       | Token expiration in minutes             |
+| `AUTH_JWT_COOKIE_NAME`     | `string`  | —       | Cookie name for JWT storage             |
+| `AUTH_JWT_SECRET`          | `string`  | —       | HMAC secret (plain string)              |
+| `AUTH_JWT_SECRET_B64`      | `string`  | —       | HMAC secret (base64-encoded)            |
+| `AUTH_JWT_ED_SECRET`       | `string`  | —       | EdDSA private key (PEM, base64-encoded) |
+| `AUTH_JWT_ENABLE_VERIFY`   | `boolean` | `true`  | Enable JWT signature verification       |
+
+### Basic Authentication
+
+| Variable            | Type     | Default | Description                  |
+| ------------------- | -------- | ------- | ---------------------------- |
+| `AUTH_BASIC_SECRET` | `string` | —       | Password for HTTP Basic Auth |
+
+### Cryptography
+
+| Variable           | Type     | Default | Description                                   |
+| ------------------ | -------- | ------- | --------------------------------------------- |
+| `CRYPTO_SECRET`    | `string` | —       | 32-byte key (or 64 hex chars) for AES-256-GCM |
+| `CRYPTO_IV_LENGTH` | `number` | `12`    | IV length for AES-GCM                         |
+
+### HTTP
+
+| Variable                         | Type      | Default | Description                                     |
+| -------------------------------- | --------- | ------- | ----------------------------------------------- |
+| `USE_REAL_IP_HEADER`             | `boolean` | —       | Trust `x-real-ip` header from reverse proxy     |
+| `HTTP_REQUEST_LOGGING_MODE`      | `string`  | `e2e`   | Logging mode: `none`, `e2e`, `finish`, `errors` |
+| `HEALTHZ_ENABLE_REQUEST_LOGGING` | `boolean` | `false` | Log healthcheck requests                        |
+
+### Redis
+
+All Redis configurations support both direct connection and Sentinel mode. The library uses separate Redis instances for different concerns:
+
+#### Default Redis
+
+| Variable              | Description                             |
+| --------------------- | --------------------------------------- |
+| `REDIS_HOST`          | Redis host                              |
+| `REDIS_PORT`          | Redis port                              |
+| `REDIS_PREFIX`        | Key prefix (falls back to package name) |
+| `REDIS_SENTINEL_HOST` | Sentinel host                           |
+| `REDIS_SENTINEL_PORT` | Sentinel port                           |
+| `REDIS_SENTINEL_NAME` | Sentinel master name                    |
+
+#### Cache Redis (`CACHE_REDIS_` prefix)
+
+Used by the `Cache` class. Falls back to default Redis settings.
+
+#### Broadcast Redis (`BROADCAST_REDIS_` prefix)
+
+Used by `createBroadcastChannel()` and `createDistributedMethod()`. Falls back to default Redis settings.
+
+#### BullMQ Redis (`BULL_REDIS_` prefix)
+
+Used by the worker system. Falls back to default Redis settings.
+
+| Variable     | Type     | Default   | Description               |
+| ------------ | -------- | --------- | ------------------------- |
+| `BULL_QUEUE` | `string` | `default` | Default BullMQ queue name |
+
+#### Mesh Redis (`MESH_REDIS_` prefix)
+
+Used by `MeshService`. Falls back to default Redis settings.
+
+#### Mutex Redis (`MUTEX_REDIS_` prefix)
+
+Used by `withMutex()` and `LeaderService`. Falls back to default Redis settings.
+
+| Variable     | Type     | Default | Description                                 |
+| ------------ | -------- | ------- | ------------------------------------------- |
+| `MUTEX_MODE` | `string` | `local` | Mutex mode: `local` (in-process) or `redis` |
+
+### Mail
+
+| Variable               | Type      | Default     | Description                         |
+| ---------------------- | --------- | ----------- | ----------------------------------- |
+| `MAIL_PROVIDER`        | `string`  | `smtp`      | Mail provider: `smtp` or `postmark` |
+| `MAIL_FROM`            | `string`  | —           | Sender email address                |
+| `MAIL_FROM_NAME`       | `string`  | —           | Sender display name                 |
+| `SMTP_HOST`            | `string`  | `127.0.0.1` | SMTP server host                    |
+| `SMTP_PORT`            | `number`  | `1025`      | SMTP server port                    |
+| `SMTP_USER`            | `string`  | —           | SMTP username                       |
+| `SMTP_PASSWORD_SECRET` | `string`  | —           | SMTP password                       |
+| `SMTP_TLS`             | `boolean` | `false`     | Enable TLS                          |
+| `POSTMARK_SECRET`      | `string`  | —           | Postmark API token                  |
+
+### Workers
+
+| Variable            | Type      | Default      | Description              |
+| ------------------- | --------- | ------------ | ------------------------ |
+| `ENABLE_JOB_RUNNER` | `boolean` | `true` (dev) | Enable BullMQ job runner |
+
+### Observability
+
+| Variable                              | Type      | Default | Description                           |
+| ------------------------------------- | --------- | ------- | ------------------------------------- |
+| `SENTRY_DSN`                          | `string`  | —       | Sentry DSN for error tracking         |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`         | `string`  | —       | OTLP endpoint for traces and metrics  |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`  | `string`  | —       | OTLP endpoint for traces only         |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | `string`  | —       | OTLP endpoint for metrics push        |
+| `OTEL_METRICS_ENDPOINT_ENABLED`       | `boolean` | —       | Enable `/metrics` Prometheus endpoint |
+| `OTEL_DEBUG`                          | `boolean` | —       | Enable debug logging                  |
+| `ALERTS_SLACK_WEBHOOK_URL`            | `string`  | —       | Slack webhook for alert-level errors  |
+
+### SRPC
+
+| Variable                   | Type     | Default | Description                         |
+| -------------------------- | -------- | ------- | ----------------------------------- |
+| `SRPC_AUTH_SECRET`         | `string` | —       | HMAC secret for SRPC authentication |
+| `SRPC_AUTH_CLOCK_DRIFT_MS` | `number` | `30000` | Allowed clock drift for SRPC auth   |
+
+### OpenAPI
+
+| Variable                | Type      | Default | Description                           |
+| ----------------------- | --------- | ------- | ------------------------------------- |
+| `ENABLE_OPENAPI_SCHEMA` | `boolean` | —       | Dump OpenAPI schema to `openapi.yaml` |
+
+## `isDevFeatureEnabled(envVar, defaultInDev?)`
+
+Helper function to check if a feature flag is enabled. Returns `true` in development/Jest by default.
+
+```typescript
+import { isDevFeatureEnabled } from '@zyno-io/dk-server-foundation';
+
+if (isDevFeatureEnabled(config.MY_FEATURE)) {
+    // enabled
+}
+```
+
+| Input              | Production | Development      |
+| ------------------ | ---------- | ---------------- |
+| `undefined`        | `false`    | `true` (default) |
+| `'1'` or `'true'`  | `true`     | `true`           |
+| `'0'` or `'false'` | `false`    | `false`          |

package/docs/content/database.md

@@ -0,0 +1,422 @@
+# Database
+
+MySQL/MariaDB ORM layer extending Deepkit's database with transaction hooks, session locks, raw query helpers, entity creation utilities, dirty tracking, relationship resolution, and a migration system.
+
+## Creating a Database
+
+Use `createMySQLDatabase()` to define a database class with your entities:
+
+```typescript
+import { createMySQLDatabase } from '@zyno-io/dk-server-foundation';
+
+class AppDB extends createMySQLDatabase({ enableLocksTable: true }, [User, Post, Comment]) {}
+```
+
+Pass the database class to `createApp()`:
+
+```typescript
+const app = createApp({
+    config: AppConfig,
+    db: AppDB
+});
+```
+
+### `createMySQLDatabase(config, entities?)`
+
+| Option             | Type      | Default | Description                                          |
+| ------------------ | --------- | ------- | ---------------------------------------------------- |
+| `enableLocksTable` | `boolean` | `false` | Create the `_locks` table for session-level locking. |
+
+All other MySQL connection options are configured via environment variables (see [Configuration](./configuration.md)).
+
+## Entity Creation
+
+Type-safe entity creation with automatic inference of optional fields (auto-increment, nullable, or `HasDefault`).
+
+### Create Without Persisting
+
+```typescript
+import { createEntity, createEntities } from '@zyno-io/dk-server-foundation';
+
+const user = createEntity(User, { email: 'a@b.com', name: 'Alice' });
+const users = createEntities(User, [
+    { email: 'a@b.com', name: 'Alice' },
+    { email: 'b@c.com', name: 'Bob' }
+]);
+```
+
+### Create and Queue for Persistence
+
+Entities are added to the session's unit of work but not flushed until `session.flush()`:
+
+```typescript
+import { createQueuedEntity } from '@zyno-io/dk-server-foundation';
+
+await db.transaction(async session => {
+    const user = createQueuedEntity(User, { email: 'a@b.com', name: 'Alice' }, session);
+    const post = createQueuedEntity(Post, { userId: user.id, title: 'Hello' }, session);
+    // Both persisted on commit
+});
+```
+
+### Create and Persist Immediately
+
+```typescript
+import { createPersistedEntity, createPersistedEntities } from '@zyno-io/dk-server-foundation';
+
+const user = await createPersistedEntity(User, { email: 'a@b.com', name: 'Alice' }, session);
+```
+
+### Persist Existing Entities
+
+```typescript
+import { persistEntity, persistEntities } from '@zyno-io/dk-server-foundation';
+
+const user = createEntity(User, { email: 'a@b.com', name: 'Alice' });
+await persistEntity(user, session);
+```
+
+## Entity Retrieval
+
+```typescript
+import { getEntityOr404, getEntityOrUndefined, getEntity, entityExists } from '@zyno-io/dk-server-foundation';
+
+// Throws HttpNotFoundError if not found
+const user = await getEntityOr404(User, { id: 1 });
+
+// Returns undefined if not found
+const user = await getEntityOrUndefined(User, { id: 1 });
+
+// Throws Deepkit ItemNotFound if not found
+const user = await getEntity(User, { id: 1 });
+
+// Check existence
+const exists = await entityExists(User, { email: 'a@b.com' });
+```
+
+## Transactions and Sessions
+
+### Transactions
+
+```typescript
+await db.transaction(async session => {
+    // All operations within this callback are wrapped in a transaction
+    const user = createQueuedEntity(User, { name: 'Alice' }, session);
+    // Auto-commits on success, auto-rollbacks on error
+});
+```
+
+### Sessions (No Transaction)
+
+```typescript
+await db.session(async session => {
+    // Unit of work without an explicit transaction
+});
+```
+
+### Reuse or Create
+
+```typescript
+// Uses existing session if provided, otherwise creates a new transaction
+await db.withTransaction(existingSession, async session => {
+    // ...
+});
+
+// Same for sessions (no transaction)
+await db.withSession(existingSession, async session => {
+    // ...
+});
+```
+
+### Transaction Hooks
+
+```typescript
+await db.transaction(async session => {
+    session.addPreCommitHook(async () => {
+        // Runs before the transaction commits
+    });
+
+    session.addPostCommitHook(async () => {
+        // Runs after successful commit
+        // Good for sending notifications, invalidating caches
+    });
+});
+```
+
+### Session Locks
+
+Acquire database-level locks that are held until the transaction completes. Requires `enableLocksTable: true` in database config.
+
+```typescript
+await db.transaction(async session => {
+    await session.acquireSessionLock(['wallet', walletId]);
+    // Lock held until commit/rollback
+    // Other transactions attempting the same lock will wait
+});
+```
+
+Lock keys can be a single value or an array that gets flattened: `['wallet', 123]` becomes `wallet:123`.
+
+## Raw Queries
+
+### Tagged Template Literals
+
+Use Deepkit's `sql` tagged template for parameterized queries:
+
+```typescript
+import { sql } from '@deepkit/sql';
+
+const users = await db.rawFind<User>(sql`SELECT * FROM users WHERE active = ${true} AND age > ${18}`);
+
+await db.rawExecute(sql`UPDATE users SET last_login = NOW() WHERE id = ${userId}`);
+```
+
+### Single Result
+
+```typescript
+const user = await db.rawFindOne<User>(sql`SELECT * FROM users WHERE id = ${id}`);
+// Returns undefined if not found
+```
+
+### Unsafe (Manual Bindings)
+
+```typescript
+const users = await db.rawFindUnsafe<User>('SELECT * FROM users WHERE name LIKE ?', ['%alice%']);
+```
+
+### Execute Results
+
+```typescript
+const result = await db.rawExecute(sql`INSERT INTO users ...`);
+// result: { affectedRows, insertId, warningStatus }
+```
+
+## Dirty Tracking
+
+Track changes to entities loaded from the database:
+
+```typescript
+import {
+    isEntityDirty,
+    getDirtyFields,
+    getDirtyDetails,
+    isFieldDirty,
+    getFieldOriginal,
+    getEntityOriginal,
+    revertDirtyEntity
+} from '@zyno-io/dk-server-foundation';
+
+user.name = 'Bob';
+
+isEntityDirty(user); // true
+getDirtyFields(user); // ['name']
+isFieldDirty(user, 'name'); // true
+getFieldOriginal(user, 'name'); // 'Alice'
+
+getDirtyDetails(user);
+// { name: { original: 'Alice', current: 'Bob' } }
+
+getEntityOriginal(user);
+// { id: 1, name: 'Alice', email: '...' }
+
+revertDirtyEntity(user);
+// user.name is now 'Alice' again
+```
+
+## Bulk Loading
+
+### Keyed Entities
+
+Load entities indexed by a field:
+
+```typescript
+import { getKeyedEntities, getKeyedGroupedEntities, getEntitiesById } from '@zyno-io/dk-server-foundation';
+
+// Returns { [userId]: User }
+const usersById = await getKeyedEntities({
+    schema: User,
+    ids: [1, 2, 3],
+    keyField: 'id'
+});
+
+// Returns { [departmentId]: User[] }
+const usersByDept = await getKeyedGroupedEntities({
+    schema: User,
+    ids: [10, 20],
+    keyField: 'departmentId'
+});
+
+// Returns User[]
+const users = await getEntitiesById({
+    schema: User,
+    ids: [1, 2, 3],
+    fields: ['id', 'name', 'email']
+});
+```
+
+### Relationship Resolution
+
+Resolve one-to-one/many-to-one and many-to-many relationships:
+
+```typescript
+import { resolveRelated, resolveRelatedByPivot } from '@zyno-io/dk-server-foundation';
+
+// Many-to-one: attach department to each user
+await resolveRelated({
+    src: users,
+    srcIdField: 'departmentId',
+    targetField: 'department',
+    targetSchema: Department,
+    targetFields: ['id', 'name']
+});
+// users[0].department = Department { id, name }
+
+// Many-to-many via pivot table
+await resolveRelatedByPivot({
+    src: posts,
+    srcIdField: 'id',
+    pivotSchema: PostTag,
+    pivotIdKey: 'postId',
+    pivotRelatedKey: 'tagId',
+    targetField: 'tags',
+    targetSchema: Tag,
+    targetFields: ['id', 'name']
+});
+// posts[0].tags = [{ ...Tag, pivot: PostTag }, ...]
+```
+
+## Custom Types
+
+### Coordinate (POINT)
+
+```typescript
+import { Coordinate, MySQLCoordinate, NullableMySQLCoordinate } from '@zyno-io/dk-server-foundation';
+
+class Location {
+    coords!: MySQLCoordinate; // NOT NULL POINT
+    altCoords!: NullableMySQLCoordinate; // NULLABLE POINT
+}
+```
+
+### DateString
+
+```typescript
+import { DateString } from '@zyno-io/dk-server-foundation';
+
+class Event {
+    date!: DateString; // MySQL DATE column, stored as 'YYYY-MM-DD'
+}
+```
+
+### UuidString
+
+```typescript
+import { UuidString } from '@zyno-io/dk-server-foundation';
+
+class Resource {
+    id!: UuidString; // Type annotation for UUID fields
+}
+```
+
+### Length
+
+```typescript
+import { Length } from '@zyno-io/dk-server-foundation';
+
+class Token {
+    code!: Length<6>; // Validated fixed-length string
+}
+```
+
+### HasDefault
+
+Mark fields that have application-level defaults so they become optional in `createEntity()`:
+
+```typescript
+import { HasDefault } from '@zyno-io/dk-server-foundation';
+
+class User {
+    role!: string & HasDefault; // Optional in createEntity()
+}
+```
+
+## Migrations
+
+### Generating Migrations
+
+The `migration:create` command diffs entity definitions against the live database and generates a migration file:
+
+```bash
+# Interactive mode (prompts for column renames)
+node app.js migration:create
+
+# Non-interactive (CI-safe, treats ambiguous changes as drop+add)
+node app.js migration:create --non-interactive
+```
+
+It detects: table creation/removal, column additions/removals/modifications/renames, index and foreign key changes, primary key changes, and PostgreSQL enum type management. Both MySQL and PostgreSQL are supported.
+
+### Writing Migrations Manually
+
+```typescript
+// src/migrations/20240101_120000_add_users.ts
+import { createMigration } from '@zyno-io/dk-server-foundation';
+
+export default createMigration(async db => {
+    await db.rawExecute(sql`
+        CREATE TABLE users (
+            id INT AUTO_INCREMENT PRIMARY KEY,
+            email VARCHAR(255) NOT NULL,
+            name VARCHAR(255) NOT NULL
+        )
+    `);
+});
+```
+
+### Running Migrations
+
+```bash
+# Via CLI
+node app.js migration:run
+
+# Programmatically
+import { runMigrations } from '@zyno-io/dk-server-foundation';
+await runMigrations();
+```
+
+### Reset Migrations
+
+Removes all existing migrations and generates a single base migration from entity definitions:
+
+```bash
+node app.js migration:reset
+```
+
+### Character Set Standardization
+
+```bash
+node app.js migration:characters [charset] [collation]
+# Defaults: utf8mb4, utf8mb4_0900_ai_ci
+```
+
+Or programmatically:
+
+```typescript
+import { standardizeDbCollation } from '@zyno-io/dk-server-foundation';
+await standardizeDbCollation(db);
+```
+
+## Entity Utility Functions
+
+```typescript
+import { getPKFieldForEntity, getEntityFields, logSql } from '@zyno-io/dk-server-foundation';
+
+// Get primary key field name
+const pk = getPKFieldForEntity(User); // 'id'
+
+// Extract only data fields (no methods or relations)
+const fields = getEntityFields(user);
+
+// Debug SQL output
+logSql('SELECT * FROM users WHERE id = ?', [1]);
+```