@zyno-io/dk-server-foundation 26.216.430

package/docs/content/telemetry.md

@@ -0,0 +1,166 @@
+# Telemetry
+
+OpenTelemetry auto-instrumentation and Sentry error tracking.
+
+## OpenTelemetry Setup
+
+Call `init()` **before** other imports to enable auto-instrumentation:
+
+```typescript
+import { init } from '@zyno-io/dk-server-foundation/telemetry/otel';
+
+init();
+
+// Now import everything else
+import { createApp } from '@zyno-io/dk-server-foundation';
+```
+
+### `init(options?)`
+
+| Option                             | Type                                          | Description                               |
+| ---------------------------------- | --------------------------------------------- | ----------------------------------------- |
+| `instrumentations`                 | `Instrumentation[]`                           | Additional OpenTelemetry instrumentations |
+| `httpIncomingRequestAttributeHook` | `(request) => Record<string, AttributeValue>` | Add custom attributes to HTTP spans       |
+| `enableMetricsEndpoint`            | `boolean`                                     | Enable `/metrics` Prometheus endpoint     |
+
+### Built-in Instrumentations
+
+| Instrumentation | Package                                  | Notes                                      |
+| --------------- | ---------------------------------------- | ------------------------------------------ |
+| HTTP            | `@opentelemetry/instrumentation-http`    | Ignores `/healthz` and Sentry requests     |
+| Undici (fetch)  | `@opentelemetry/instrumentation-undici`  | Ignores `/healthz` and Sentry requests     |
+| DNS             | `@opentelemetry/instrumentation-dns`     | —                                          |
+| ioredis         | `@opentelemetry/instrumentation-ioredis` | —                                          |
+| BullMQ          | `@opentelemetry/instrumentation-bullmq`  | —                                          |
+| MariaDB         | Custom                                   | Traces queries and connection pool metrics |
+
+### Trace Export
+
+- **Development**: `SimpleSpanProcessor` (immediate export)
+- **Production**: `BatchSpanProcessor` (buffered export)
+
+### Metric Export
+
+- **Pull**: `/metrics` endpoint (Prometheus format, restricted to private IPs)
+- **Push**: OTLP endpoint with 10-second interval
+
+### Database Transaction Tracing
+
+The library automatically wraps `Database.prototype.transaction` to create spans named `sql.transaction`.
+
+## Tracing Helpers
+
+```typescript
+import { withSpan, withRootSpan, withRemoteSpan, setSpanAttributes } from '@zyno-io/dk-server-foundation';
+
+// Create a child span
+const result = await withSpan('processOrder', async () => {
+    return await doWork();
+});
+
+// With attributes
+const result = await withSpan('processOrder', { orderId: '123' }, async () => {
+    return await doWork();
+});
+
+// Create a root span (ignores current context)
+const result = await withRootSpan('backgroundJob', async () => {
+    return await doWork();
+});
+
+// Continue a trace from a remote context
+const result = await withRemoteSpan('handleRequest', { traceparent: '00-abc...' }, undefined, async () => {
+    return await doWork();
+});
+
+// Add attributes to the active span
+setSpanAttributes({ 'user.id': userId, 'order.total': total });
+```
+
+### State Inspection
+
+```typescript
+import { isTracingInstalled, getTracer, getActiveSpan, getTraceContext, disableActiveTrace } from '@zyno-io/dk-server-foundation';
+
+if (isTracingInstalled()) {
+    const tracer = getTracer();
+    const span = getActiveSpan();
+    const context = getTraceContext(); // { traceId, spanId, traceFlags }
+}
+
+// Suppress tracing for a section
+disableActiveTrace();
+```
+
+### `SpanInfo`
+
+Remote span context for `withRemoteSpan`:
+
+```typescript
+type SpanInfo = { traceId: string; spanId: string; traceFlags?: number } | { traceparent: string } | undefined;
+```
+
+## Sentry
+
+Sentry functions are available from the `telemetry/sentry` subpath (not re-exported from the package root):
+
+```typescript
+import { installSentry, isSentryInstalled, flushSentry } from '@zyno-io/dk-server-foundation/telemetry/sentry';
+
+installSentry({ dsn: 'https://...' });
+
+// Check if installed
+if (isSentryInstalled()) {
+    /* ... */
+}
+
+// Flush pending events (5s timeout)
+await flushSentry();
+```
+
+Sentry is automatically installed by `createApp()` when `SENTRY_DSN` is configured. It integrates with OpenTelemetry tracing (adds trace context to Sentry events).
+
+### Automatic Error Handling
+
+`createApp()` sets up handlers for `uncaughtException` and `unhandledRejection` that report to Sentry and flush before exit.
+
+## MariaDB Instrumentation
+
+Custom OpenTelemetry instrumentation for the `mariadb` package:
+
+- Wraps `createConnection`, `createPool`, `createPoolCluster`
+- Creates spans for each SQL query
+- Tracks connection pool metrics via `db.client.connections.usage` counter
+- Reports `idle` and `used` connection states
+
+## Metrics Endpoint
+
+The `/metrics` endpoint serves Prometheus-formatted metrics. It is:
+
+- Restricted to private LAN IPs (10.x, 172.16-31.x, 192.168.x, 127.x, ::1, fc00::/7, fe80::/10)
+- Returns 403 for non-private IPs
+- Returns 503 if the Prometheus exporter is not available
+
+## Configuration
+
+| Variable                              | Description                           |
+| ------------------------------------- | ------------------------------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`         | OTLP endpoint for traces and metrics  |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`  | OTLP endpoint for traces only         |
+| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | OTLP endpoint for metrics push        |
+| `OTEL_METRICS_ENDPOINT_ENABLED`       | Enable `/metrics` Prometheus endpoint |
+| `OTEL_DEBUG`                          | Enable debug logging                  |
+| `SENTRY_DSN`                          | Sentry DSN                            |
+| `APP_ENV`                             | Environment name sent to Sentry       |
+
+### Resource Attributes
+
+Traces and metrics include:
+
+| Attribute                     | Source          |
+| ----------------------------- | --------------- |
+| `service.name`                | Package name    |
+| `service.version`             | Package version |
+| `deployment.environment.name` | `APP_ENV`       |
+| `host.name`                   | OS hostname     |
+| `process.pid`                 | Process ID      |

package/docs/content/testing.md

@@ -0,0 +1,222 @@
+# Testing
+
+Test facades with per-test database isolation, entity fixtures, request mocking, and SQL mocking.
+
+## Setup
+
+Tests use `node:test` runner against compiled output. The global setup enforces UTC timezone.
+
+```bash
+# Run all tests
+yarn test
+
+# Run a single test file
+yarn test tests/helpers/array.spec.ts
+
+# Run with debugger
+yarn test:debug
+```
+
+## Testing Facade
+
+`TestingFacade` wraps a Deepkit app for testing with database isolation and lifecycle hooks.
+
+```typescript
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { TestingHelpers, makeMockRequest } from '@zyno-io/dk-server-foundation';
+
+// Pass app options (not an app instance) -- the facade creates the app for you
+const tf = TestingHelpers.createTestingFacade(
+    {
+        db: MyDB,
+        controllers: [UserController],
+        providers: [UserService]
+    },
+    {
+        enableDatabase: true,
+        seedData: async facade => {
+            await loadEntityFixtures([fixtures.user1, fixtures.admin1]);
+        }
+    }
+);
+
+TestingHelpers.installStandardHooks(tf);
+
+describe('UserController', () => {
+    it('should return user', async () => {
+        const res = await makeMockRequest(tf, 'GET', '/api/users/1', {});
+        assert.strictEqual(res.statusCode, 200);
+    });
+});
+```
+
+### `createTestingFacade(appOptions, facadeOptions?)`
+
+Creates a `TestingFacade` instance. The first argument is app options (same as `CreateAppOptions` but with `config` optional -- defaults to `BaseAppConfig`). The facade calls `createApp()` internally with `port: 0`.
+
+### `ITestingFacadeOptions`
+
+| Option               | Type                        | Default                        | Description                                                     |
+| -------------------- | --------------------------- | ------------------------------ | --------------------------------------------------------------- |
+| `enableDatabase`     | `boolean`                   | `false`                        | Create an isolated test database                                |
+| `enableMigrations`   | `boolean`                   | `true` (when database enabled) | Run migrations after database creation. Set to `false` to skip. |
+| `autoSeedData`       | `boolean`                   | `false`                        | Run `seedData` automatically before each test                   |
+| `databasePrefix`     | `string`                    | `'test'`                       | Prefix for test database names                                  |
+| `onBeforeStart`      | `(facade) => Promise<void>` | —                              | Hook before app starts                                          |
+| `onStart`            | `(facade) => Promise<void>` | —                              | Hook after app starts                                           |
+| `onBeforeStop`       | `(facade) => Promise<void>` | —                              | Hook before app stops                                           |
+| `onStop`             | `(facade) => Promise<void>` | —                              | Hook after app stops                                            |
+| `seedData`           | `(facade) => Promise<void>` | —                              | Seed test data                                                  |
+| `defaultTestHeaders` | `Record<string, string>`    | —                              | Default headers for mock requests                               |
+
+### Facade Methods
+
+| Method              | Description                                |
+| ------------------- | ------------------------------------------ |
+| `start()`           | Start the app and create the test database |
+| `stop()`            | Stop the app and destroy the test database |
+| `createDatabase()`  | Create the isolated test database          |
+| `destroyDatabase()` | Drop the test database                     |
+| `truncateTables()`  | Truncate all tables                        |
+| `runMigrations()`   | Run pending migrations                     |
+| `resetToSeed()`     | Truncate tables and re-seed                |
+
+### Database Isolation
+
+Each test process gets its own database: `{prefix}_{timestamp}_{pid}_1`. Databases are created on `start()` and dropped on `stop()`.
+
+Environment variables:
+
+| Variable       | Description                       |
+| -------------- | --------------------------------- |
+| `TEST_KEEP_DB` | Skip database destruction on stop |
+
+## Standard Hooks
+
+`installStandardHooks(tf)` sets up test lifecycle hooks:
+
+- `before` -- Start the facade
+- `after` -- Stop the facade
+- `beforeEach` -- Reset to seed data; install DB rejection hooks if database is disabled
+- `afterEach` -- Reset timers, restore all mocks, clear SQL mocks
+
+## Entity Fixtures
+
+Define reusable test data with automatic date handling:
+
+```typescript
+import { TestingHelpers } from '@zyno-io/dk-server-foundation';
+
+const { defineEntityFixtures, loadEntityFixtures } = TestingHelpers;
+
+const fixtures = defineEntityFixtures(User, {
+    alice: {
+        id: 1,
+        name: 'Alice',
+        email: 'alice@example.com',
+        createdAt: '2024-01-01T00:00:00Z' // String dates auto-converted
+    },
+    bob: {
+        id: 2,
+        name: 'Bob',
+        email: 'bob@example.com',
+        createdAt: '2024-01-02T00:00:00Z'
+    }
+});
+
+// Load into database
+await loadEntityFixtures([fixtures.alice, fixtures.bob]);
+```
+
+### `defineEntityFixtures(entityClass, data)`
+
+- Date fields accept ISO strings (converted to `Date` on load)
+- Fields with defaults (auto-increment, nullable, `HasDefault`) are optional
+- Returns an object with the same keys, each containing prepared fixture data
+
+### `prepareEntityFixtures(entityClass, data)`
+
+Lower-level function to prepare a single fixture record:
+
+```typescript
+const prepared = TestingHelpers.prepareEntityFixtures(User, {
+    name: 'Charlie',
+    email: 'charlie@example.com'
+});
+```
+
+## Mock HTTP Requests
+
+```typescript
+import { makeMockRequest } from '@zyno-io/dk-server-foundation';
+
+// Without custom headers
+const res = await makeMockRequest(tf, 'GET', '/api/users', {});
+
+// With custom headers
+const res = await makeMockRequest(
+    tf,
+    'POST',
+    '/api/users',
+    {
+        Authorization: 'Bearer token123',
+        'Content-Type': 'application/json'
+    },
+    { name: 'Alice', email: 'alice@example.com' }
+);
+
+// Response
+assert.strictEqual(res.statusCode, 200);
+assert.deepStrictEqual(res.json, { id: 1, name: 'Alice' });
+```
+
+Methods: `GET`, `PUT`, `POST`, `DELETE`.
+
+Default headers from `options.defaultTestHeaders` are merged with per-request headers.
+
+## SQL Mocking
+
+Mock database queries without a real database:
+
+```typescript
+import { SqlTestingHelper } from '@zyno-io/dk-server-foundation';
+
+const sql = new SqlTestingHelper();
+
+// Mock entity data
+sql.mockEntity(User, [
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' }
+]);
+
+// Queries against User will return mocked data
+const users = await db.query(User).find();
+// [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+
+// Throws if no mock is set up
+// "No mock data found for entity: User"
+
+// Clear all mocks
+sql.clearMocks();
+```
+
+Uses Deepkit's `MemoryDatabaseAdapter` internally. Automatically cleared by `installStandardHooks`.
+
+## Configuration
+
+For tests without a database, set `MYSQL_MIN_IDLE_CONNECTIONS=0` to avoid connection attempts.
+
+## Redis Cleanup
+
+If your tests use Redis-backed features, call `disconnectAllRedis()` in your `after()` hook:
+
+```typescript
+import { after } from 'node:test';
+import { disconnectAllRedis } from '@zyno-io/dk-server-foundation';
+
+after(async () => {
+    await tf.stop();
+    await disconnectAllRedis();
+});
+```

package/docs/content/types.md

@@ -0,0 +1,215 @@
+# Types
+
+Custom validated types that integrate with Deepkit's type system for automatic validation and transformation during deserialization.
+
+## Date Types
+
+### `DateString`
+
+MySQL DATE column type. Stored as `YYYY-MM-DD` string, validated via regex pattern.
+
+```typescript
+import { DateString } from '@zyno-io/dk-server-foundation';
+
+class Event {
+    date!: DateString; // MySQL DATE column
+}
+```
+
+### `ValidDate`
+
+A `Date` that rejects `Invalid Date` values during validation.
+
+```typescript
+import { ValidDate } from '@zyno-io/dk-server-foundation';
+
+class Booking {
+    startDate!: ValidDate;
+}
+```
+
+## String Types
+
+### `TrimmedString` / `NonEmptyTrimmedString`
+
+Strings that are automatically trimmed during Deepkit deserialization.
+
+```typescript
+import { TrimmedString, NonEmptyTrimmedString } from '@zyno-io/dk-server-foundation';
+
+class UserInput {
+    name!: NonEmptyTrimmedString; // Trimmed + must be non-empty
+    notes!: TrimmedString; // Trimmed, can be empty
+}
+```
+
+### `EmailAddress`
+
+Regex-validated email address:
+
+```typescript
+import { EmailAddress } from '@zyno-io/dk-server-foundation';
+
+class User {
+    email!: EmailAddress; // Validated against /^[a-z0-9_+.-]+@[a-z0-9-.]+\.[a-z]+$/i
+}
+```
+
+## Phone Types
+
+Validated phone numbers using Google's libphonenumber library. Automatically cleaned and validated during Deepkit deserialization.
+
+### `PhoneNumber`
+
+International E.164 format with `+` prefix:
+
+```typescript
+import { PhoneNumber } from '@zyno-io/dk-server-foundation';
+
+class Contact {
+    phone!: PhoneNumber; // e.g., '+15551234567'
+}
+```
+
+### `PhoneNumberNANP`
+
+North American Numbering Plan format (US/Canada) without the `+1` prefix:
+
+```typescript
+import { PhoneNumberNANP } from '@zyno-io/dk-server-foundation';
+
+class Contact {
+    phone!: PhoneNumberNANP; // e.g., '5551234567'
+}
+```
+
+### Phone Utilities
+
+```typescript
+import { cleanPhone, formatPhoneFriendly } from '@zyno-io/dk-server-foundation';
+
+// Clean and validate (returns null if invalid)
+cleanPhone('(555) 123-4567'); // '+15551234567'
+cleanPhone('555-1234567', 'US'); // '+15551234567'
+cleanPhone('invalid'); // null
+
+// Format for display
+formatPhoneFriendly('+15551234567'); // '(555) 123-4567'
+formatPhoneFriendly('+15551234567', 'US'); // '(555) 123-4567'
+```
+
+## Database Types
+
+### `Coordinate`
+
+MySQL POINT geometry type:
+
+```typescript
+import { Coordinate, MySQLCoordinate, NullableMySQLCoordinate } from '@zyno-io/dk-server-foundation';
+
+class Location {
+    coords!: MySQLCoordinate; // NOT NULL POINT column
+    altCoords!: NullableMySQLCoordinate; // NULLABLE POINT column
+}
+
+// Usage
+const loc = new Location();
+loc.coords = { x: -73.9857, y: 40.7484 }; // longitude, latitude
+```
+
+### `UuidString`
+
+Type annotation for UUID string fields:
+
+```typescript
+import { UuidString } from '@zyno-io/dk-server-foundation';
+
+class Resource {
+    id!: UuidString;
+}
+```
+
+### `Length<N>`
+
+Fixed-length string validator:
+
+```typescript
+import { Length } from '@zyno-io/dk-server-foundation';
+
+class VerificationCode {
+    code!: Length<6>; // Must be exactly 6 characters
+}
+```
+
+### `OnUpdate<T>`
+
+MySQL `ON UPDATE` column expression annotation. Used by `migration:create` to generate and detect `ON UPDATE` clauses:
+
+```typescript
+import { OnUpdate } from '@zyno-io/dk-server-foundation';
+
+class User {
+    updatedAt!: Date & OnUpdate<'CURRENT_TIMESTAMP'>; // ON UPDATE CURRENT_TIMESTAMP
+}
+```
+
+This is MySQL-only. The annotation is ignored on PostgreSQL.
+
+### `HasDefault`
+
+Mark fields with application-level defaults so they become optional in entity creation:
+
+```typescript
+import { HasDefault } from '@zyno-io/dk-server-foundation';
+
+class User {
+    role!: string & HasDefault; // Optional in createEntity/createPersistedEntity
+}
+```
+
+## Utility Types
+
+### Primitives
+
+```typescript
+type ConcretePrimitive = string | number | boolean;
+type DefinedPrimitive = ConcretePrimitive | null;
+type Primitive = DefinedPrimitive | undefined;
+type StrictBool = true | false;
+```
+
+### Object Types
+
+```typescript
+type KVObject<T = any> = Record<string, T>;
+type NestedKVObject<T = any> = KVObject<T | T[] | KVObject<T>>;
+type Serializable<T = ConcretePrimitive> = T | T[] | NestedKVObject<T> | NestedKVObject<T>[];
+```
+
+### Field Manipulation
+
+```typescript
+// Make specific fields required
+type RequireFields<T, K extends keyof T> = T & { [P in K]-?: T[P] };
+
+// Get keys where values match a type
+type ObjectKeysMatching<O, V> = { [K in keyof O]: O[K] extends V ? K : never }[keyof O];
+```
+
+### Function Types
+
+```typescript
+type ArrowFunction = (...args: any) => any;
+type ArrowFunctionNoArgs = () => any;
+type VoidFunction = () => void;
+```
+
+### Method Extraction
+
+```typescript
+// Get only the method keys of a type
+type MethodKeys<T> = keyof MethodsOf<T>;
+
+// Get an object with only the methods
+type MethodsOf<T> = { [K in keyof T as IsFunction<T[K]> extends never ? never : K]: T[K] };
+```