@venizia/ignis-docs 0.0.5 → 0.0.6-1

package/wiki/references/helpers/env/index.md

@@ -0,0 +1,214 @@
+# Environment
+
+Structured access to application environment variables with prefix filtering, type-safe retrieval, and stage detection.
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis-helpers` |
+| **Classes** | `ApplicationEnvironment`, `Environment` |
+| **Extends** | `IApplicationEnvironment` (interface) |
+| **Singleton** | `applicationEnvironment` -- auto-initialized at module load |
+| **Runtimes** | Both |
+
+#### Import Paths
+
+```typescript
+// Singleton instance (recommended)
+import { applicationEnvironment } from '@venizia/ignis-helpers';
+
+// Classes
+import { ApplicationEnvironment, Environment } from '@venizia/ignis-helpers';
+
+// Interface
+import type { IApplicationEnvironment } from '@venizia/ignis-helpers';
+```
+
+## Creating an Instance
+
+### Singleton (Recommended)
+
+A pre-configured `applicationEnvironment` singleton is auto-initialized at module load time. It reads `process.env` and filters keys matching the configured prefix (default: `APP_ENV`).
+
+```typescript
+import { applicationEnvironment } from '@venizia/ignis-helpers';
+
+const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
+```
+
+> [!TIP]
+> For most applications, the singleton is all you need. It is created once at module load and shares the same filtered environment across your entire app.
+
+### Custom Instance
+
+If you need a different prefix or a custom set of environment variables, construct your own instance.
+
+```typescript
+import { ApplicationEnvironment } from '@venizia/ignis-helpers';
+
+const customEnv = new ApplicationEnvironment({
+  prefix: 'MY_APP_ENV',
+  envs: process.env,
+});
+
+const host = customEnv.get<string>('MY_APP_ENV_SERVER_HOST');
+```
+
+#### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `prefix` | `string` | -- (required) | Only keys starting with this prefix are included |
+| `envs` | `Record<string, string \| number \| undefined>` | -- (required) | The environment object to filter (typically `process.env`) |
+
+The default singleton uses `process.env.APPLICATION_ENV_PREFIX ?? 'APP_ENV'` as the prefix and `process.env` as the environment source.
+
+## Usage
+
+### Reading Variables
+
+Use `get<ReturnType>(key)` to retrieve a typed environment variable. Only keys matching the configured prefix are available.
+
+```typescript
+import { applicationEnvironment } from '@venizia/ignis-helpers';
+
+const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
+const serverPort = applicationEnvironment.get<string>('APP_ENV_SERVER_PORT');
+```
+
+> [!WARNING]
+> `get<T>()` performs a TypeScript type cast, not a runtime conversion. All `process.env` values are strings. If the raw value is `"3000"`, `get<number>()` still returns the string at runtime. Parse it yourself if needed.
+
+### Setting Variables
+
+Use `set<ValueType>(key, value)` to add or override a variable at runtime.
+
+```typescript
+applicationEnvironment.set('APP_ENV_FEATURE_FLAG', 'enabled');
+```
+
+### Listing Keys
+
+Use `keys()` to retrieve all filtered environment variable keys.
+
+```typescript
+const allKeys = applicationEnvironment.keys();
+// e.g. ['APP_ENV_SERVER_HOST', 'APP_ENV_SERVER_PORT', 'APP_ENV_JWT_SECRET']
+```
+
+### Checking Development Mode
+
+Use `isDevelopment()` to check if `process.env.NODE_ENV` is `'development'`.
+
+```typescript
+if (applicationEnvironment.isDevelopment()) {
+  // Enable verbose logging, seed data, etc.
+}
+```
+
+### Environment Stage Detection
+
+The `Environment` class provides static helpers for checking the current `NODE_ENV`.
+
+```typescript
+import { Environment } from '@venizia/ignis-helpers';
+
+// Read the current stage (falls back to 'development' if NODE_ENV is unset)
+console.log(Environment.current);
+
+// Check a specific stage
+if (Environment.is({ name: 'staging' })) {
+  // Staging-only behavior
+}
+```
+
+#### Available Stages
+
+| Constant | Value |
+|----------|-------|
+| `Environment.LOCAL` | `'local'` |
+| `Environment.DEBUG` | `'debug'` |
+| `Environment.DEVELOPMENT` | `'development'` |
+| `Environment.ALPHA` | `'alpha'` |
+| `Environment.BETA` | `'beta'` |
+| `Environment.STAGING` | `'staging'` |
+| `Environment.PRODUCTION` | `'production'` |
+
+All stages are collected in `Environment.COMMON_ENVS` (a `Set<string>`), which is used internally by the Logger to determine whether debug logging should be active.
+
+### Configuring the Prefix
+
+The default singleton reads `APPLICATION_ENV_PREFIX` from `process.env` to determine its prefix. Set this variable **before** any import of `@venizia/ignis-helpers`.
+
+```
+APPLICATION_ENV_PREFIX=MY_APP_ENV
+
+MY_APP_ENV_SERVER_HOST=0.0.0.0
+MY_APP_ENV_SERVER_PORT=3000
+```
+
+### Integration with BaseApplication
+
+The `applicationEnvironment` singleton is used by the framework's `BaseApplication` during startup to validate that all prefixed environment variables have non-empty values. If any key has an empty value, the application throws an error unless `ALLOW_EMPTY_ENV_VALUE` is set to a truthy value.
+
+```typescript
+// This validation runs automatically during application initialization.
+// To allow empty values, set in your environment:
+ALLOW_EMPTY_ENV_VALUE=true
+```
+
+## Troubleshooting
+
+### `get()` returns `undefined`
+
+**Cause:** The key does not start with the configured prefix, so it was filtered out during construction.
+
+**Fix:** Ensure your `.env` keys use the correct prefix:
+
+```
+# Wrong -- missing prefix
+SERVER_PORT=3000
+
+# Correct -- matches default prefix
+APP_ENV_SERVER_PORT=3000
+```
+
+### Custom prefix not taking effect
+
+**Cause:** `APPLICATION_ENV_PREFIX` must be set **before** the module loads. If it is set after import, the singleton is already constructed with the default `APP_ENV`.
+
+**Fix:** Set the prefix in your `.env` file or at process start, before any import of `@venizia/ignis-helpers`:
+
+```
+APPLICATION_ENV_PREFIX=MY_APP_ENV
+```
+
+### `get<number>()` returns a string
+
+**Cause:** `get<T>()` performs a TypeScript type cast, not a runtime conversion. All `process.env` values are strings.
+
+**Fix:** Parse the value explicitly:
+
+```typescript
+const port = Number(applicationEnvironment.get<string>('APP_ENV_SERVER_PORT'));
+```
+
+### `[validateEnvs] Invalid Application Environment! Key: {key} | Value: {value}`
+
+**Cause:** During application startup, `BaseApplication.validateEnvs()` found a prefixed environment key with an empty or undefined value.
+
+**Fix:** Either provide a value for the key in your `.env` file, or allow empty values by setting:
+
+```
+ALLOW_EMPTY_ENV_VALUE=true
+```
+
+## See Also
+
+- **Guides:**
+  - [Application](/guides/core-concepts/application/) -- Environment validation during startup
+
+- **Other Helpers:**
+  - [Helpers Index](../index) -- All available helpers
+  - [Logger](/references/helpers/logger/) -- Uses `Environment.COMMON_ENVS` for debug log filtering

package/wiki/references/helpers/error/index.md

@@ -0,0 +1,232 @@
+# Error
+
+Standardized error class and factory for throwing HTTP-aware errors with machine-readable codes across the application.
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis-helpers` |
+| **Class** | `ApplicationError` |
+| **Extends** | `Error` (native) |
+| **Runtimes** | Both |
+
+#### Import Paths
+
+```typescript
+import { ApplicationError, getError } from '@venizia/ignis-helpers';
+import { ErrorSchema } from '@venizia/ignis-helpers';
+import type { TError } from '@venizia/ignis-helpers';
+```
+
+> [!NOTE]
+> `ApplicationError`, `getError`, `ErrorSchema`, and `TError` are also available from `@venizia/ignis-inversion` and re-exported through `@venizia/ignis`.
+
+## Creating an Instance
+
+`ApplicationError` extends the native `Error` class with an HTTP `statusCode` and an optional `messageCode` for machine-readable error identification.
+
+```typescript
+import { ApplicationError, HTTP } from '@venizia/ignis-helpers';
+
+const error = new ApplicationError({
+  message: 'User not found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+  messageCode: 'USER_NOT_FOUND',
+});
+```
+
+#### Constructor Options (`TError`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `message` | `string` | -- (required) | Human-readable error message |
+| `statusCode` | `number` | `400` | HTTP status code |
+| `messageCode` | `string` | `undefined` | Machine-readable error code for client-side handling |
+| `name` | `string` | `undefined` | Error name |
+
+> [!TIP]
+> The `TError` type is derived from `ErrorSchema` (a Zod schema) and uses `.catchall(z.any())`, so you can pass additional arbitrary properties beyond the four listed above.
+
+#### `getError()` Factory Function
+
+For convenience, use the standalone `getError()` function instead of calling `new ApplicationError()` directly. This is the preferred pattern throughout the Ignis codebase.
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis-helpers';
+
+throw getError({
+  message: 'Invalid credentials',
+  statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+  messageCode: 'INVALID_CREDENTIALS',
+});
+```
+
+#### `ApplicationError.getError()` Static Method
+
+An equivalent static factory method on the class itself:
+
+```typescript
+throw ApplicationError.getError({
+  message: 'Configuration missing',
+  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+});
+```
+
+## Usage
+
+### Throwing Errors in Services
+
+The most common pattern is throwing `ApplicationError` from service methods to signal HTTP-level failures. The framework's error handling middleware catches these and formats the response automatically.
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis-helpers';
+
+class AuthenticationService {
+  async signUp(opts: { username: string; credential: string }) {
+    const existingUser = await this.userRepository.findByUsername(opts.username);
+    if (existingUser) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Conflict,
+        message: 'Username already exists',
+      });
+    }
+    // ...
+  }
+}
+```
+
+### Using `messageCode` for Client-Side Handling
+
+The `messageCode` field allows frontend applications to map errors to localized messages or specific UI behaviors without parsing the human-readable `message` string.
+
+```typescript
+throw getError({
+  message: 'Email verification required before login',
+  statusCode: HTTP.ResultCodes.RS_4.Forbidden,
+  messageCode: 'auth.email_not_verified',
+});
+```
+
+### Error Response Format
+
+The built-in `appErrorHandler` middleware (from `@venizia/ignis`) catches `ApplicationError` instances and formats them into consistent JSON responses. The response shape differs by environment.
+
+#### Production Response
+
+```json
+{
+  "message": "User not found",
+  "statusCode": 404,
+  "requestId": "abc-123-def"
+}
+```
+
+#### Development Response
+
+In development (`NODE_ENV=development`), additional debugging fields are included:
+
+```json
+{
+  "message": "User not found",
+  "statusCode": 404,
+  "requestId": "abc-123-def",
+  "details": {
+    "url": "http://localhost:3000/api/users/123",
+    "path": "/api/users/123",
+    "stack": "Error: User not found\n    at ...",
+    "cause": "..."
+  }
+}
+```
+
+### ErrorSchema (Zod)
+
+`ErrorSchema` is a Zod object schema used for OpenAPI response documentation. It is typically referenced in route definitions to describe error responses.
+
+```typescript
+import { ErrorSchema, HTTP } from '@venizia/ignis-helpers';
+
+// In route definition responses
+const responses = {
+  [HTTP.ResultCodes.RS_4.NotFound]: {
+    description: 'Resource not found',
+    content: {
+      'application/json': { schema: ErrorSchema },
+    },
+  },
+};
+```
+
+The schema shape:
+
+```typescript
+const ErrorSchema = z
+  .object({
+    name: z.string().optional(),
+    statusCode: z.number().optional(),
+    messageCode: z.string().optional(),
+    message: z.string(),
+  })
+  .catchall(z.any());
+```
+
+### Common Status Code Patterns
+
+| Scenario | Status Code | `HTTP.ResultCodes` Path |
+|----------|-------------|-------------------------|
+| Invalid input / bad request | 400 | `RS_4.BadRequest` |
+| Missing or invalid auth | 401 | `RS_4.Unauthorized` |
+| Insufficient permissions | 403 | `RS_4.Forbidden` |
+| Resource not found | 404 | `RS_4.NotFound` |
+| Duplicate resource | 409 | `RS_4.Conflict` |
+| Validation error | 422 | `RS_4.UnprocessableEntity` |
+| Server failure | 500 | `RS_5.InternalServerError` |
+
+## Troubleshooting
+
+### `statusCode` defaults to 400
+
+**Cause:** `getError()` was called without specifying a `statusCode`. The `ApplicationError` constructor defaults to `400` (Bad Request).
+
+**Fix:** Always provide an explicit status code using `HTTP.ResultCodes`:
+
+```typescript
+throw getError({
+  message: 'Resource not found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+});
+```
+
+### Error response missing `stack` and `cause`
+
+**Cause:** The application is running in production mode. The `appErrorHandler` middleware strips `stack`, `cause`, `url`, and `path` from responses when `NODE_ENV` is not `development`.
+
+**Fix:** Set `NODE_ENV=development` to see full error details during debugging.
+
+### Errors returning 500 instead of expected status code
+
+**Cause:** A plain `Error` (not `ApplicationError`) was thrown. The `appErrorHandler` middleware only reads `statusCode` from errors that have that property. Native `Error` instances default to `500`.
+
+**Fix:** Use `getError()` or `new ApplicationError()` instead of `new Error()`:
+
+```typescript
+// Incorrect -- will return 500
+throw new Error('Not found');
+
+// Correct -- will return 404
+throw getError({
+  message: 'Not found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+});
+```
+
+## See Also
+
+- [Controllers](/references/base/controllers) -- Throwing errors in route handlers
+- [Services](/references/base/services) -- Error handling in business logic
+- [Middlewares](/references/base/middlewares) -- The `appErrorHandler` middleware
+- [Helpers Index](/references/helpers/) -- All available helpers
+- [Logger Helper](/references/helpers/logger/) -- Logging errors
+- [Error Handling Best Practices](/best-practices/error-handling) -- Patterns and anti-patterns
+- [Common Pitfalls](/best-practices/common-pitfalls) -- Frequent error handling mistakes

package/wiki/references/helpers/index.md

@@ -6,21 +6,22 @@ Reusable classes and functions providing common functionality - designed for eas
 
 | Helper | Purpose | Key Features |
 |--------|---------|--------------|
-| [Common Types](./types.md) | Utility types | Nullable, resolvers, class types |
-| [Cron](./cron.md) | Job scheduling | Cron expressions, task management |
-| [Crypto](./crypto.md) | Cryptographic operations | Hashing, AES/RSA encryption/decryption |
-| [Environment](./env.md) | Environment variables | Centralized config access |
-| [Error](./error.md) | Error handling | `ApplicationError`, consistent responses |
-| [Inversion](./inversion.md) | Dependency injection | DI container implementation |
-| [Logger](./logger.md) | Logging | Winston-based, multiple transports, scopes |
-| [Network](./network.md) | Network requests | HTTP, TCP, UDP helpers |
-| [Queue](./queue.md) | Message queues | BullMQ, MQTT support |
-| [Redis](./redis.md) | Redis operations | Single/cluster, key-value, hashes, JSON, pub/sub |
-| [Socket.IO](./socket-io.md) | Real-time communication | Socket.IO client/server helpers |
-| [Storage](./storage.md) | File storage | In-memory, Minio object storage |
-| [Testing](./testing.md) | Test utilities | Test plan runner, base test classes |
-| [UID](./uid.md) | Unique ID generation | Snowflake IDs, Base62 encoding |
-| [Worker Thread](./worker-thread.md) | Worker threads | Node.js worker management |
+| [Common Types](./types/) | Utility types | Nullable, resolvers, class types |
+| [Cron](./cron/) | Job scheduling | Cron expressions, task management |
+| [Crypto](./crypto/) | Cryptographic operations | AES/RSA/ECDH encryption, key exchange, hashing |
+| [Environment](./env/) | Environment variables | Centralized config access |
+| [Error](./error/) | Error handling | `ApplicationError`, consistent responses |
+| [Inversion](./inversion/) | Dependency injection | DI container implementation |
+| [Logger](./logger/) | Logging | Winston-based, multiple transports, scopes |
+| [Network](./network/) | Network requests | HTTP, TCP, UDP helpers |
+| [Queue](./queue/) | Message queues | BullMQ, MQTT support |
+| [Redis](./redis/) | Redis operations | Single/cluster, key-value, hashes, JSON, pub/sub |
+| [Socket.IO](./socket-io/) | Real-time communication | Socket.IO client/server helpers |
+| [WebSocket](./websocket/) | Real-time communication | Bun native WebSocket server/emitter, Redis scaling |
+| [Storage](./storage/) | File storage | In-memory, Minio object storage |
+| [Testing](./testing/) | Test utilities | Test plan runner, base test classes |
+| [UID](./uid/) | Unique ID generation | Snowflake IDs, Base62 encoding |
+| [Worker Thread](./worker-thread/) | Worker threads | Node.js worker management |
 
 ## See Also