@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/best-practices/index.md

@@ -102,6 +102,9 @@ Controller → Service → Repository → DataSource
 // ✅ Error Handling
 throw getError({ statusCode: 404, message: 'User not found' });
 
+// ✅ Scoped Logging (ILogger - never names a provider)
+this.logger.for('createUser').info('User created | id: %s', user.id);
+
 // ✅ Input Validation
 request: { body: jsonContent({ schema: z.object({ email: z.string().email() }) }) }
 ```
@@ -120,6 +123,9 @@ async getUser(c: Context) {
 // ❌ Catching all errors silently
 try { await riskyOperation(); } catch (e) { /* swallowed */ }
 
+// ❌ Raw Error - loses statusCode, messageCode and the normalized response shape
+throw new Error('User not found'); // Use getError()
+
 // ❌ Using `any` type
 const data: any = await fetchData(); // Use proper types!
 ```

package/content/best-practices/performance-optimization.md

@@ -9,6 +9,7 @@ Identify bottlenecks before optimizing:
 ```typescript
 import { executeWithPerformanceMeasure } from '@venizia/ignis-helpers';
 
+// `logger` is optional and typed `ILogger` - it falls back to `console` when omitted.
 await executeWithPerformanceMeasure({
   logger: this.logger,
   scope: 'DataProcessing',
@@ -148,13 +149,22 @@ if (!cached) {
 
 | Setting | Value | Why |
 |---------|-------|-----|
-| `NODE_ENV` | `production` | Enables library optimizations |
-| Process Manager | PM2, systemd, Docker | Auto-restart, cluster mode |
-| Cluster Mode | CPU cores | Utilize all CPUs |
+| `NODE_ENV` | `production` | Enables library optimizations; also gates error-detail leakage (unset is treated as production) |
+| `APP_ENV_LOGGER_LEVEL` | `info` or `warn` | Keep hot-path logging off the critical path |
+| Process Manager | systemd, Docker, Kubernetes | Auto-restart, supervision |
+| Horizontal Scaling | One process per CPU core | Utilize all CPUs |
+
+Bun has no PM2-style cluster mode, and `Bun.serve` is started without `reusePort` - two processes cannot share a port. Scale out with one process per port behind a reverse proxy, or with container replicas:
+
+```bash
+# Each replica binds its own port; nginx / a load balancer fans out across them
+APP_ENV_SERVER_PORT=3000 NODE_ENV=production bun run dist/index.js &
+APP_ENV_SERVER_PORT=3001 NODE_ENV=production bun run dist/index.js &
+```
 
-**PM2 Cluster Mode:**
 ```bash
-pm2 start dist/index.js -i max  # Use all CPU cores
+# Or let the orchestrator do it
+docker compose up -d --scale app=4
 ```
 
 ## 6. Transaction Support
@@ -208,12 +218,12 @@ Connection pooling significantly improves performance by reusing database connec
 ```typescript
 import { Pool } from 'pg';
 import { datasource } from '@venizia/ignis';
-import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { BaseRelationalDataSource } from '@venizia/ignis/postgres';
 import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
 
 // IDataSourceConfigs: your settings interface (host/port/user/password/database)
 @datasource({ driver: NodePostgresDriver })
-export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+export class PostgresDataSource extends BaseRelationalDataSource<IDataSourceConfigs> {
   override configure(): void {
     // Keep the pool on `this.client` - NodePostgresDriver above wires the driver and Drizzle
     // connector from it lazily, on first getConnector()/beginTransaction()
@@ -385,9 +395,9 @@ const logger = HfLogger.get('OrderEngine');
 const MSG_ORDER_SENT = HfLogger.encodeMessage('Order sent');
 const MSG_ORDER_FILLED = HfLogger.encodeMessage('Order filled');
 
-// Start background flusher
+// Start background flusher (writes to stdout by default; pass { filePath } or { sink })
 const flusher = new HfLogFlusher();
-flusher.start(100); // Flush every 100ms
+flusher.start(100); // Flush interval in ms - 100 is also the default
 
 // In hot path (~100-300ns, zero allocation):
 logger.log('info', MSG_ORDER_SENT);
@@ -395,11 +405,14 @@ logger.log('info', MSG_ORDER_FILLED);
 ```
 
 **Key points:**
+- `log(level, bytes)` is the zero-allocation path. Passing a string, or any `...args`, falls back to formatting
+- Levels are the same five as `ILogger`: `debug`, `info`, `warn`, `error`, `emerg`
 - Pre-encode messages at initialization, not in hot path
-- Use background flushing to avoid I/O blocking
-- HfLogger uses a lock-free ring buffer (64K entries, 16MB)
+- HfLogger uses a lock-free ring buffer (64K entries x 256 bytes = 16MB), allocated lazily on first use
+- Scope truncates at 32 UTF-8 bytes, message at 213 - silently
+- For the standard logger, narrow output with `APP_ENV_LOGGER_LEVEL` in production and keep debug lines behind the `DEBUG` gate (pre-computed at module load, near-zero cost when off)
 
-> **Deep Dive:** See [Logger Helper](../extensions/helpers/logger/) for complete HfLogger API.
+> **Deep Dive:** See [HfLogger](../extensions/helpers/logger/hf-logger.md) for the complete API.
 
 ## Performance Checklist
 
@@ -414,7 +427,7 @@ logger.log('info', MSG_ORDER_FILLED);
 | **Memory** | Large datasets processed in batches | High |
 | **Caching** | Expensive queries cached | High |
 | **Workers** | CPU-intensive tasks offloaded | High |
-| **Logging** | HfLogger for hot paths (HFT) | High |
+| **Logging** | HfLogger for hot paths (HFT); `APP_ENV_LOGGER_LEVEL` in production | High |
 | **Monitoring** | Performance logging enabled | Low |
 
 ## See Also

package/content/best-practices/security-guidelines.md

@@ -20,17 +20,17 @@ APP_ENV_POSTGRES_PASSWORD=database_password_here
 
 **Generate strong secrets:**
 ```bash
-node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+bun -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString('base64'))"
 ```
 
 ### Redaction at Log Time
 
-Never hard-coding a secret is not enough on its own -- an options object holding one still ends up in a log line the moment it is passed to `logger.info('...: %s', opts)`. `@venizia/ignis-helpers` provides two primitives for exactly this:
+Never hard-coding a secret is not enough on its own. An options object holding one still ends up in a log line the moment it is passed to `logger.info('...: %s', opts)`. `@venizia/ignis-helpers` provides two primitives for exactly this:
 
 | Function | Use For | Behavior |
 |----------|---------|----------|
-| `redactSecrets(value)` | Any object/array being logged | Recursively replaces every value whose key matches a secret-looking name (`password`, `token`, `apiKey`, `authorization`, HTTP header spellings like `x-api-key`/`cookie`/`proxy-authorization`, etc., case-insensitive) with `'[REDACTED]'` |
-| `redactUrlCredentials(url)` | A connection/broker URL string | Strips the password out of a URL's authority section (`mqtts://user:hunter2@broker:8883` becomes `mqtts://user:[REDACTED]@broker:8883`); a value that doesn't parse as a URL is returned unchanged |
+| `redactSecrets(value)` | Any object/array being logged | Recursively replaces every value whose key matches a secret-looking name with `'[REDACTED]'` |
+| `redactUrlCredentials(url)` | A connection/broker URL string | Strips the password out of a URL's authority section: `mqtts://user:hunter2@broker:8883` becomes `mqtts://user:[REDACTED]@broker:8883`. A value that doesn't parse as a URL, or one with no password, is returned unchanged |
 
 ```typescript
 import { redactSecrets, redactUrlCredentials } from '@venizia/ignis-helpers';
@@ -39,7 +39,19 @@ this.logger.info('[connect] Options: %s', redactSecrets(connectionOptions));
 this.logger.info('[connect] Broker: %s', redactUrlCredentials(brokerUrl));
 ```
 
-These are the primitives the framework itself uses -- outbound HTTP request configs (`NodeFetcher`/`AxiosFetcher`, see [Network Helper](/extensions/helpers/network/)) and MQTT broker URLs (`MQTTClientHelper`, see [Queue Helper](/extensions/helpers/queue/)) are both redacted this way before they reach a log line.
+`redactSecrets` matches on the **key name**, case-insensitively, at any depth:
+
+- Options-object spellings: `password`, `passphrase`, `secret`, `token`, `apiKey`, `privateKey`, `credentials`, `authorization`, `connectionString`, ...
+- Any `*_token` / `*Token` key: `access_token`, `refresh_token`, `vaultToken`, ...
+- Vault wire keys: `client_token`, `secret_id`, `role_id`
+- HTTP header spellings: `x-api-key`, `x-vault-token`, `cookie`, `set-cookie`, `proxy-authorization`, `www-authenticate`
+
+It also handles the shapes naive redaction breaks on. An `Error` is reprojected so its non-enumerable `message`/`stack` survive. Cycles become `'[Circular]'`, and buffers/typed arrays are summarized as `[Binary N bytes]` instead of serialized.
+
+These are the primitives the framework itself uses. Outbound HTTP request configs (`NodeFetcher`/`AxiosFetcher`, see [Network Helper](/extensions/helpers/network/)) and MQTT broker URLs (`MQTTClientHelper`, see [Queue Helper](/extensions/helpers/queue/)) are both redacted this way before they reach a log line.
+
+> [!WARNING]
+> `APP_ENV_LOGGER_DO_REDACT=false` turns both functions into the identity function. It is a local-debugging kill-switch and must never be set in production. The check is fail-closed - only the literal string `false` disables redaction - and is read per call, so it can be flipped at runtime.
 
 ## 2. Input Validation
 
@@ -110,7 +122,7 @@ Configure model properties that should **never be returned** through repository
     hiddenProperties: ['password', 'apiSecret', 'internalToken'],
   },
 })
-export class User extends BasePostgresEntity<typeof User.schema> {
+export class User extends BaseRelationalEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     email: text('email').notNull(),
@@ -131,7 +143,7 @@ export class User extends BasePostgresEntity<typeof User.schema> {
 
 ```typescript
 // For authentication - access password via connector
-const connector = userRepository.getConnector();
+const connector = userRepository.connector;
 const [user] = await connector
   .select({ id: User.schema.id, password: User.schema.password })
   .from(User.schema)
@@ -339,7 +351,7 @@ const redisHelper = new RedisSingleHelper({
   name: 'rate-limiter',
   host: process.env.APP_ENV_REDIS_HOST ?? 'localhost',
   port: process.env.APP_ENV_REDIS_PORT ?? '6379',
-  password: process.env.APP_ENV_REDIS_PASSWORD,
+  password: process.env.APP_ENV_REDIS_PASSWORD ?? '',
 });
 
 const distributedRateLimiter = async (opts: { key: string; max: number; windowSeconds: number }) => {
@@ -462,6 +474,18 @@ export class AuthService extends BaseService {
 }
 ```
 
+### Error Responses Are Hardened in Production
+
+The global error handler decides what a client sees by environment, and it is **fail-closed**: an unset or unrecognized `NODE_ENV` is treated as production. Only `NODE_ENV` values in the development set relax it.
+
+| In production | Behavior |
+|---|---|
+| Unexpected errors | Replaced with a generic `"Internal Server Error"` - raw text may carry SQL, schema names or connection details |
+| Database constraint errors (400) | Base message only; the driver's `Detail:` (which echoes row values like emails), `Table:` and `Constraint:` are stripped |
+| `details.stack` / `details.cause` | Omitted |
+
+Deliberate `getError` messages are always returned verbatim, in every environment - so never put internal detail in one. Use `requestId` plus the server log to diagnose what the response no longer shows. See [Error Handling](./error-handling#_5-error-response-format).
+
 **Events to Log:**
 - Failed login attempts
 - Successful logins
@@ -471,7 +495,7 @@ export class AuthService extends BaseService {
 - Admin actions
 
 > [!NOTE]
-> When logging a request or connection config that might carry credentials, wrap it in `redactSecrets()` (or `redactUrlCredentials()` for a URL) rather than logging it raw -- see [Redaction at Log Time](#redaction-at-log-time) above. This is what the framework's own outbound HTTP and MQTT logging already does automatically.
+> When logging a request or connection config that might carry credentials, wrap it in `redactSecrets()` (or `redactUrlCredentials()` for a URL) rather than logging it raw. See [Redaction at Log Time](#redaction-at-log-time) above. This is what the framework's own outbound HTTP and MQTT logging already does automatically.
 
 ## Security Checklist
 
@@ -489,6 +513,8 @@ Before deploying to production, verify:
 | **Dependencies** | No known vulnerabilities (`bun audit`) |
 | **HTTPS** | TLS configured for production |
 | **Hidden Data** | Sensitive fields use `hiddenProperties` |
+| **Redaction** | `APP_ENV_LOGGER_DO_REDACT` is unset (never `false`) |
+| **Error Leakage** | `NODE_ENV` set to a production value so responses are sanitized |
 
 ## See Also
 

package/content/best-practices/testing-strategies.md

@@ -102,8 +102,8 @@ bun test
 # Run specific test file
 bun test src/__tests__/user.service.test.ts
 
-# Run tests matching pattern
-bun test --grep "UserService"
+# Run tests whose name matches a pattern
+bun test -t "UserService"
 
 # Watch mode
 bun test --watch
@@ -410,6 +410,11 @@ describe('UserController E2E', () => {
       });
 
       expect(response.status).toBe(409);
+
+      // Error responses carry one message shape: { text, code, args }.
+      // There is no flat top-level messageCode - branch on normalized.code.
+      const body = await response.json();
+      expect(body.normalized.code).toBeDefined();
     });
   });
 

package/content/best-practices/troubleshooting-tips.md

@@ -50,11 +50,9 @@ This prints all registered routes on startup.
 
 **Debug bindings:**
 ```typescript
-// In postConfigure() method
-async postConfigure(): Promise<void> {
-  this.logger.info('Available bindings: %s',
-    Array.from(this.bindings.keys())
-  );
+// In your Application class - `bindings` is protected on the container it extends
+override async postConfigure(): Promise<void> {
+  this.logger.info('[postConfigure] Available bindings: %j', Array.from(this.bindings.keys()));
 }
 ```
 
@@ -77,16 +75,21 @@ curl -H "Authorization: Bearer YOUR_TOKEN" \
 
 **Enable detailed logging:**
 ```bash
-# Enable debug mode via environment variable
+# `debug` is the only gated level - it is dropped unless DEBUG is set
 DEBUG=true
+
+# File logging is OPT-IN. Without this, logs go to console/dgram only
+APP_ENV_LOGGER_FOLDER_PATH=./logs
 ```
 
 **Use method-scoped logging with `.for()`:**
 ```typescript
+import { ApplicationLogger, type ILogger } from '@venizia/ignis-helpers';
+
 class UserService {
-  private logger = Logger.get('UserService');
+  private logger: ILogger = ApplicationLogger.get('UserService');
 
-  async createUser(data: CreateUserDto) {
+  async createUser(data: TCreateUserRequest) {
     this.logger.for('createUser').info('Creating user: %j', data);
     // Output: [UserService-createUser] Creating user: {...}
 
@@ -102,16 +105,19 @@ class UserService {
 }
 ```
 
+Annotate against `ILogger`, never a concrete provider class. Acquire a logger via `BaseHelper.logger` (inside any helper, service, controller or repository), `ApplicationLogger.get('Scope')`, or `LoggerFactory.getLogger(['A', 'B'])`.
+
 **Common debugging commands:**
 ```bash
-# View application logs
-tail -f logs/app.log
+# View application logs - the rotating files are <APP_ENV_APPLICATION_NAME>-info-<date>.log
+# and -error-<date>.log inside APP_ENV_LOGGER_FOLDER_PATH
+tail -f "$APP_ENV_LOGGER_FOLDER_PATH"/*-info-*.log
 
-# Check TypeScript compilation errors
-bun run build
+# Check TypeScript compilation errors (from the repo root)
+make core
 
 # Validate environment variables
-cat .env | grep APP_ENV
+grep APP_ENV .env
 ```
 
 **Useful debugging patterns:**
@@ -144,10 +150,10 @@ async getUser(c: Context) {
 **Filtering logs by request:**
 ```bash
 # Find all logs for a specific request
-grep "abc123" logs/app.log
+grep "abc123" "$APP_ENV_LOGGER_FOLDER_PATH"/*-info-*.log
 
 # Extract request timing
-grep "\[abc123\]" logs/app.log | grep "Took:"
+grep "\[abc123\]" "$APP_ENV_LOGGER_FOLDER_PATH"/*-info-*.log | grep "Took:"
 ```
 
 **Why this matters:**
@@ -159,12 +165,16 @@ grep "\[abc123\]" logs/app.log | grep "Took:"
 
 When Zod validation fails, IGNIS returns a structured error response. Understanding this format helps debug client-side issues.
 
-**Error response structure** (top-level `message`/`messageCode` come from the first issue; the fallback message is `ValidationError`):
+**Error response structure** (`message`/`normalized.code` come from the first issue; the fallback message is `ValidationError`):
 ```json
 {
   "statusCode": 422,
   "message": "Invalid email address",
-  "messageCode": "invalid_format",
+  "normalized": {
+    "text": "Invalid email address",
+    "code": "invalid_format",
+    "args": {}
+  },
   "requestId": "abc123",
   "details": {
     "url": "http://localhost:3000/api/users",