@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/references/configuration/index.md

@@ -1,6 +1,6 @@
 # Configuration Reference
 
-Configuration options and environment variables for IGNIS applications.
+How IGNIS applications read configuration - the `APP_ENV_` variable convention, the `EnvironmentKeys` constants, and where to look up every value.
 
 ## Quick Reference
 
@@ -14,22 +14,20 @@ Configuration options and environment variables for IGNIS applications.
 | Storage | MinIO/S3 file storage (application-level convention) | `APP_ENV_MINIO_HOST`, `APP_ENV_MINIO_ACCESS_KEY` |
 | Mail | SMTP email sending (application-level convention) | `APP_ENV_MAIL_HOST`, `APP_ENV_MAIL_USER` |
 
-## Environment Variable Prefix
+**Full list:** [Environment Variables Reference](./environment-variables.md) - every `APP_ENV_*` variable, its default, and whether it's required.
 
-IGNIS uses the `APP_ENV_` prefix to avoid conflicts with system variables:
+## In one example
+
+IGNIS uses the `APP_ENV_` prefix to avoid conflicts with system variables. Create a `.env` file in your project root:
 
 ```bash
 # ✅ IGNIS variables
 APP_ENV_POSTGRES_HOST=localhost
 
-# ❌ Might conflict with system
+# ❌ Might conflict with system variables
 POSTGRES_HOST=localhost
 ```
 
-## Quick Start
-
-Create a `.env` file in your project root:
-
 ```bash
 # .env
 APP_ENV_APPLICATION_NAME=my-app
@@ -39,26 +37,38 @@ APP_ENV_POSTGRES_HOST=localhost
 APP_ENV_POSTGRES_DATABASE=my_database
 ```
 
-## What's in This Section
-
-- [Environment Variables](./environment-variables.md) - Complete reference of all `APP_ENV_*` variables
-
-## Configuration Patterns
-
-### 1. Accessing Variables
+Read a value either directly or through the `applicationEnvironment` helper:
 
 ```typescript
 // 1. Direct access
 const host = process.env.APP_ENV_POSTGRES_HOST;
 
-// 2. Using helper (recommended)
+// 2. Using the helper (recommended)
 import { applicationEnvironment } from '@venizia/ignis-helpers';
 import { EnvironmentKeys } from '@venizia/ignis';
 const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
 ```
 
-### 2. Environment Files
+## How it works
+
+- **One prefix, layered files.** Everything IGNIS reads is prefixed `APP_ENV_` (configurable - see the [Environment Variables Reference](./environment-variables.md#custom-environment-prefix)). Layer `.env`, `.env.local`, and `.env.{NODE_ENV}` the same way any dotenv-based tool does.
+- **`applicationEnvironment` snapshots `process.env` once at import.** It's built from whatever is in `process.env` when `@venizia/ignis-helpers` loads - values arriving after that (e.g., set programmatically at runtime) won't appear in `.keys()` unless merged in explicitly (secret hydration does this - see below).
+- **Startup validation is fail-closed on emptiness, not absence.** IGNIS iterates every `APP_ENV_*` key that IS set and throws if its value is empty; it does not require a variable to exist at all. Bypass with `ALLOW_EMPTY_ENV_VALUE=true`. Component-level checks (e.g., the authentication component's `jwtSecret` check) cover values that must be present.
+- **Secrets don't have to live in a file.** IGNIS can hydrate `APP_ENV_*` keys from a vault at boot, before datasources are configured - see [Secrets & Vault](./environment-variables.md#secrets-vault).
+
+## Common tasks
+
+### Access a variable in code
+Prefer `applicationEnvironment.get()` over `process.env` directly - it stays in sync when secrets are hydrated from a vault.
+
+```typescript
+import { applicationEnvironment } from '@venizia/ignis-helpers';
+import { EnvironmentKeys } from '@venizia/ignis';
 
+const dbHost = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
+```
+
+### Add a per-environment file
 ```
 project/
 ├── .env                 # Default (development)
@@ -67,14 +77,18 @@ project/
 └── .env.example         # Template (committed)
 ```
 
-### 3. Validation on Startup
-
-IGNIS validates every set `APP_ENV_*` variable on startup and fails with a clear error if any is empty (bypass with `ALLOW_EMPTY_ENV_VALUE=true`). Absent variables are not flagged - components validate their own required inputs.
+### Bypass startup validation during local prototyping
+```bash
+ALLOW_EMPTY_ENV_VALUE=true
+```
+Not recommended once real secrets are wired in - see [Validation](./environment-variables.md#validation).
 
-> **Related:** [Environment Variables Reference](./environment-variables.md) | [DataSources Guide](../../guides/core-concepts/persistent/datasources)
+### Look up every variable's default and requirement
+See the [Environment Variables Reference](./environment-variables.md) for the full table, grouped by Application, Server, Database, Authentication, Logging, Storage, Mail, and Secrets & Vault.
 
-## EnvironmentKeys Class
+## Reference
 
+### EnvironmentKeys class
 ```typescript
 import { EnvironmentKeys } from '@venizia/ignis';
 ```
@@ -82,7 +96,7 @@ import { EnvironmentKeys } from '@venizia/ignis';
 | Constant | Description |
 |----------|-------------|
 | `APP_ENV_APPLICATION_NAME` | Application display name |
-| `APP_ENV_APPLICATION_TIMEZONE` | Application timezone (e.g., 'Asia/Ho_Chi_Minh') |
+| `APP_ENV_APPLICATION_TIMEZONE` | Application timezone (e.g., `'Asia/Ho_Chi_Minh'`) |
 | `APP_ENV_APPLICATION_SECRET` | Application-wide secret key |
 | `APP_ENV_JWT_SECRET` | JWT signing secret |
 | `APP_ENV_JWT_EXPIRES_IN` | JWT token expiration |
@@ -92,8 +106,8 @@ import { EnvironmentKeys } from '@venizia/ignis';
 | `APP_ENV_APPLICATION_DS_AUTHORIZE` | DataSource name for authorization |
 | `APP_ENV_APPLICATION_DS_OAUTH2` | DataSource name for OAuth2 |
 | `APP_ENV_OAUTH2_VIEW_FOLDER` | OAuth2 view templates folder |
-| `APP_ENV_SERVER_HOST` | HTTP server host (e.g., '0.0.0.0') |
-| `APP_ENV_SERVER_PORT` | HTTP server port (e.g., 3000) |
+| `APP_ENV_SERVER_HOST` | HTTP server host (e.g., `'0.0.0.0'`) |
+| `APP_ENV_SERVER_PORT` | HTTP server port (e.g., `3000`) |
 | `APP_ENV_SERVER_BASE_PATH` | Base URL path prefix |
 | `APP_ENV_DATASOURCE_NAME` | Default datasource name |
 | `APP_ENV_POSTGRES_HOST` | PostgreSQL host |
@@ -102,11 +116,15 @@ import { EnvironmentKeys } from '@venizia/ignis';
 | `APP_ENV_POSTGRES_PASSWORD` | PostgreSQL password |
 | `APP_ENV_POSTGRES_DATABASE` | PostgreSQL database name |
 
-Usage:
+## See also
 
-```typescript
-import { applicationEnvironment } from '@venizia/ignis-helpers';
-import { EnvironmentKeys } from '@venizia/ignis';
+- [Environment Variables Reference](./environment-variables.md) - complete variable list, defaults, and the Secrets & Vault section
+- [Secrets & Vault Guide](/guides/core-concepts/secrets-vault) - setup walkthrough
+- [Secrets & Vault Reference](/references/base/secrets) - full provider API
+- [DataSources Guide](/guides/core-concepts/persistent/datasources) - wiring `APP_ENV_POSTGRES_*` into a DataSource
 
-const dbHost = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES_HOST);
-```
+**Files:**
+
+- [`packages/core/src/common/environments.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/common/environments.ts) - `EnvironmentKeys`
+- [`packages/helpers/src/modules/env/app-env.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/env/app-env.ts) - `applicationEnvironment`, `Environment`, `ApplicationEnvironment`
+- [`packages/core/src/base/applications/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/applications/abstract.ts) - `validateEnvs()`, host/port resolution

package/content/references/quick-reference.md

@@ -81,9 +81,8 @@ class GreeterController extends BaseGrpcController {
 ### BaseService
 
 ```typescript
-import { BaseService, injectable } from '@venizia/ignis';
+import { BaseService } from '@venizia/ignis';
 
-@injectable({})
 class UserService extends BaseService {
   constructor() {
     super({ scope: UserService.name });
@@ -308,17 +307,6 @@ const users = await userRepository.find({
 
 ## Dependency Injection
 
-### Injectable Decorator
-
-```typescript
-import { injectable } from '@venizia/ignis';
-
-@injectable({})
-class MyService extends BaseService {
-  // ...
-}
-```
-
 ### Inject Decorator
 
 ```typescript
@@ -368,7 +356,6 @@ import {
 
   // DI
   inject,
-  injectable,
 
   // Utilities
   jsonResponse,
@@ -513,7 +500,7 @@ if (Statuses.isCompleted(order.status)) {
 
 ```typescript
 import {
-  appErrorHandler,
+  AppErrorMiddleware,
   notFoundHandler,
   RequestSpyMiddleware,
   emojiFavicon,
@@ -529,7 +516,7 @@ app.use(requestSpy.value());
 app.use(emojiFavicon({ icon: '🚀' }));
 
 // Error handling (register last)
-app.onError(appErrorHandler({ logger: app.logger }));
+app.onError(new AppErrorMiddleware({ logger: app.logger }).value());
 
 // 404 handler
 app.notFound(notFoundHandler({ logger: app.logger }));

package/content/references/utilities/crypto.md

@@ -1,98 +1,57 @@
-# Crypto Utility
-
-The Crypto utility provides a single stateless `hash` function built on Node's built-in `node:crypto` module. It covers the two most common lightweight hashing needs - MD5 digests and HMAC-SHA256 signatures - without any external dependencies.
-
-::: tip Full AES / RSA / ECDH encryption
-This page covers only the utility-level `hash` function. For full symmetric/asymmetric encryption (AES-256-CBC, AES-256-GCM, RSA, ECDH key exchange) see the [Crypto helper](/extensions/helpers/crypto/).
-:::
-
-## `hash`
-
-Creates a hash or HMAC digest of a string and returns it as a text-encoded string.
-
-### Signature
-
-```typescript
-hash(
-  text: string,
-  options: {
-    algorithm: 'SHA256' | 'MD5';
-    secret?: string;
-    outputType: BinaryToTextEncoding; // 'hex' | 'base64' | 'base64url' | 'latin1'
-  },
-): string
-```
-
-**Parameters**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `text` | `string` | The input string to hash. |
-| `options.algorithm` | `'SHA256' \| 'MD5'` | Hashing algorithm. |
-| `options.secret` | `string` (optional) | Secret key for HMAC. Only used when `algorithm` is `'SHA256'`. |
-| `options.outputType` | `BinaryToTextEncoding` | Encoding of the output string - typically `'hex'` or `'base64'`. |
+---
+title: Crypto Utility
+description: Stateless MD5 and HMAC-SHA256 hashing built on node:crypto
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-### Behavior
-
-| Algorithm | `secret` provided | Result |
-|-----------|-------------------|--------|
-| `'MD5'` | ignored | MD5 digest of `text` |
-| `'SHA256'` | yes | HMAC-SHA256 of `text` signed with `secret` |
-| `'SHA256'` | no / `undefined` | `text` returned unchanged (no-op) |
-| any other | - | `text` returned unchanged (no-op) |
-
-The SHA256 pass-through is intentional: it lets callers skip hashing conditionally (for example, when a secret is not yet configured) without adding an extra `if` at the call site. If you need an unconditional SHA256 hash without a secret, use MD5 or the full [Crypto helper](/extensions/helpers/crypto/).
+# Crypto Utility
 
-### Examples
+A single stateless `hash` function for lightweight MD5 digests and HMAC-SHA256 signatures, with no external dependencies beyond Node's built-in `node:crypto`.
 
-**MD5 digest (hex)**
+## In one example
 
 ```typescript
 import { hash } from '@venizia/ignis-helpers';
 
 const digest = hash('user@example.com', { algorithm: 'MD5', outputType: 'hex' });
 // => 'b58996c504c5638798eb6b511e6f49af'
-```
-
-**MD5 digest (base64) - useful for HTTP ETags**
-
-```typescript
-const etag = hash(JSON.stringify(payload), { algorithm: 'MD5', outputType: 'base64' });
-// => 'tYlsUExWOHeY62a1EW9Jr...'
-```
-
-**HMAC-SHA256 - signing a webhook payload**
-
-```typescript
-import { hash } from '@venizia/ignis-helpers';
 
 const signature = hash(rawBody, {
   algorithm: 'SHA256',
   secret: process.env.WEBHOOK_SECRET,
   outputType: 'hex',
 });
-
-// Compare against the value in the X-Hub-Signature-256 header
-const expected = `sha256=${signature}`;
+// Compare against the X-Hub-Signature-256 header: `sha256=${signature}`
 ```
 
-**HMAC-SHA256 in base64 - API request signing**
+## Functions
 
-```typescript
-const hmac = hash(`${timestamp}.${body}`, {
-  algorithm: 'SHA256',
-  secret: apiKey,
-  outputType: 'base64',
-});
-```
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `hash` | `hash(text: string, options: { algorithm: 'SHA256' \| 'MD5'; secret?: string; outputType: BinaryToTextEncoding }): string` | Creates an MD5 digest or an HMAC-SHA256 signature of `text`, encoded via `outputType` (`'hex'`, `'base64'`, `'base64url'`, `'latin1'`). |
+
+## Behavior
+
+| Algorithm | `secret` provided | Result |
+|-----------|-------------------|--------|
+| `'MD5'` | ignored | MD5 digest of `text` |
+| `'SHA256'` | yes | HMAC-SHA256 of `text` signed with `secret` |
+| `'SHA256'` | no / `undefined` | `text` returned unchanged (no-op) |
+| any other value | - | `text` returned unchanged (no-op) |
+
+## Notes
+
+- **The SHA256 pass-through is intentional.** It lets callers skip hashing conditionally (for example, when a secret is not yet configured) without an extra `if` at the call site.
+- **Need an unconditional SHA256 hash with no secret?** Use `'MD5'`, or reach for the full [Crypto helper](/extensions/helpers/crypto/).
+- **Typical uses:** cache keys or ETags from response bodies (MD5), webhook signature verification (HMAC-SHA256), API request signing (HMAC-SHA256), anonymising PII before logging (MD5).
+- **Out of scope:** encryption, decryption, and asymmetric operations (AES, RSA, ECDH) - see the [Crypto helper](/extensions/helpers/crypto/) instead.
 
-## When to use
+## See also
 
-Use `hash` for lightweight, one-off hashing that does not require key management or IV handling:
+- [Crypto helper](/extensions/helpers/crypto/) - full AES / RSA / ECDH encryption
+- [Utilities Overview](/references/utilities/) - all utility functions
 
-- Building cache keys or ETags from response bodies (MD5)
-- Verifying webhook signatures (HMAC-SHA256)
-- Signing API requests with a shared secret (HMAC-SHA256)
-- Anonymising personally identifiable data before storing in logs (MD5)
+**Files:**
 
-For encryption, decryption, or asymmetric operations (AES, RSA, ECDH) use the [Crypto helper](/extensions/helpers/crypto/) instead.
+- [`packages/helpers/src/utilities/crypto.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/crypto.utility.ts)

package/content/references/utilities/date.md

@@ -1,90 +1,50 @@
-# Date Utility
-
-The Date utility provides a set of functions for date and time manipulation, built on top of the powerful `dayjs` library. It also configures `dayjs` with useful plugins and a default timezone.
+---
+title: Date Utility
+description: Pre-configured dayjs re-export plus sleep, weekday, timezone, and high-resolution timing helpers
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-## `dayjs`
+# Date Utility
 
-The `dayjs` object is re-exported, so you can use it directly for any date and time operations. It is pre-configured with the following plugins: `CustomParseFormat`, `UTC`, `Timezone`, `Weekday`, and `IsoWeek`.
+A pre-configured `dayjs` re-export, plus small standalone helpers for sleeping, weekday math, timezone conversion, and high-resolution timing.
 
-The default timezone is set to `Asia/Ho_Chi_Minh` and can be overridden via the `APP_ENV_APPLICATION_TIMEZONE` environment variable.
+## In one example
 
 ```typescript
-import { dayjs } from '@venizia/ignis-helpers';
-
-// Get the current date and time
-const now = dayjs();
-
-// Format a date
-const formatted = now.format('YYYY-MM-DD HH:mm:ss');
-```
+import { dayjs, sleep, getDateTz } from '@venizia/ignis-helpers';
 
-## `sleep`
+const now = dayjs().format('YYYY-MM-DD HH:mm:ss');
 
-The `sleep` function pauses execution for a specified number of milliseconds.
+await sleep(2000); // pause for 2 seconds
 
-```typescript
-import { sleep } from '@venizia/ignis-helpers';
-
-async function myAsyncFunction() {
-  console.log('Start');
-  await sleep(2000); // Wait for 2 seconds
-  console.log('End');
-}
+const tokyoTime = getDateTz({ date: '2023-10-27T10:00:00Z', timezone: 'Asia/Tokyo' });
 ```
 
-## Weekday Functions
-
--   **`isWeekday(date)`**: Checks if a given date is a weekday (Monday to Friday). Accepts a `string` or `dayjs.Dayjs` instance.
--   **`getPreviousWeekday(opts?)`**: Returns the previous weekday from a given date. If no date is provided, defaults to today.
--   **`getNextWeekday(opts?)`**: Returns the next weekday from a given date. If no date is provided, defaults to today.
+## Functions
 
-```typescript
-import { isWeekday, getPreviousWeekday, getNextWeekday } from '@venizia/ignis-helpers';
-
-const isTodayWeekday = isWeekday('2026-03-15');
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `dayjs` | re-exported `dayjs` object | The `dayjs` factory, pre-loaded with plugins - use it exactly like raw `dayjs`. |
+| `sleep` | `sleep(ms: number): Promise<void>` | Resolves after `ms` milliseconds (`setTimeout` wrapped in a Promise). |
+| `isWeekday` | `isWeekday(date: string \| dayjs.Dayjs): boolean` | `true` when `date` falls Monday through Friday (ISO weekday 1-5). |
+| `getPreviousWeekday` | `getPreviousWeekday(opts?: { date?: string \| dayjs.Dayjs }): dayjs.Dayjs` | Walks backward a day at a time from `date` (default: today) until it lands on a weekday. |
+| `getNextWeekday` | `getNextWeekday(opts?: { date?: string \| dayjs.Dayjs }): dayjs.Dayjs` | Walks forward a day at a time from `date` (default: today) until it lands on a weekday. |
+| `getDateTz` | `getDateTz(opts: { date: string; timezone: string; useClientTz?: boolean; timeOffset?: number }): dayjs.Dayjs` | Parses `date` and converts it to `timezone`, optionally shifting by `timeOffset` hours. |
+| `hrTime` | `hrTime(): number` | High-resolution seconds from `process.hrtime()`, rounded to 9 decimal places - for benchmarking. |
 
-const lastBusinessDay = getPreviousWeekday();
-const nextBusinessDay = getNextWeekday({ date: '2026-03-13' });
-```
+## Notes
 
-## `getDateTz`
+- **Plugins loaded once at module import:** `CustomParseFormat`, `UTC`, `Timezone`, `Weekday`, `IsoWeek`.
+- **Default timezone is `Asia/Ho_Chi_Minh`**, set via `dayjs.tz.setDefault()` at module load. Override with the `APP_ENV_APPLICATION_TIMEZONE` environment variable - it is read once, so changing it at runtime needs a restart.
+- **`getPreviousWeekday` / `getNextWeekday` are day-by-day loops**, not calendar lookups. They call `isWeekday()` after each step, so the worst case (stepping over a weekend) is only 2-3 iterations.
+- **`getDateTz`'s `useClientTz`** defaults to `false` and controls whether `dayjs().tz()` keeps the original wall-clock time or converts it - see the [Day.js Timezone plugin docs](https://day.js.org/docs/en/timezone/timezone) for the exact semantics.
 
-The `getDateTz` function allows you to get a `dayjs` object in a specific timezone, with an optional hour offset.
+## See also
 
-### `getDateTz(opts)`
+- [Utilities Overview](/references/utilities/) - all utility functions
+- [Day.js documentation](https://day.js.org/docs/en/installation/installation) - underlying date library
 
--   `opts` (object):
-    -   `date` (string): The date string to parse.
-    -   `timezone` (string): The IANA timezone name.
-    -   `useClientTz` (boolean, optional): Whether to keep the client's timezone. Defaults to `false`.
-    -   `timeOffset` (number, optional): Number of hours to add to the result. Defaults to `0`.
+**Files:**
 
-```typescript
-import { getDateTz } from '@venizia/ignis-helpers';
-
-const tokyoTime = getDateTz({
-  date: '2023-10-27T10:00:00Z',
-  timezone: 'Asia/Tokyo',
-});
-
-// With hour offset
-const offsetTime = getDateTz({
-  date: '2023-10-27T10:00:00Z',
-  timezone: 'Asia/Tokyo',
-  timeOffset: 2, // Add 2 hours
-});
-```
-
-## `hrTime`
-
-The `hrTime` function returns a high-resolution time measurement in seconds using `process.hrtime()`, useful for performance benchmarking. The result is rounded to 9 decimal places.
-
-```typescript
-import { hrTime } from '@venizia/ignis-helpers';
-
-const start = hrTime();
-// ... some long-running operation
-const end = hrTime();
-
-console.log(`Operation took ${end - start} seconds.`);
-```
+- [`packages/helpers/src/utilities/date.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/date.utility.ts)

package/content/references/utilities/index.md

@@ -22,7 +22,7 @@ Pure, standalone functions providing common, reusable logic for the IGNIS framew
 ### Data Processing
 
 - [**Crypto**](./crypto.md) - Simple, stateless cryptographic functions for hashing (SHA256 HMAC, MD5)
-- [**Parse**](./parse.md) - Functions for parsing and converting data types safely (integers, floats, booleans, camelCase, locale-aware numbers, array-to-map)
+- [**Parse**](./parse.md) - Functions for parsing and converting data types safely (integers, floats, booleans, camelCase, array-to-map)
 - [**Schema**](./schema.md) - Helpers for creating Zod schemas for OpenAPI request/response validation
 - [**Statuses**](./statuses.md) - Standardized status code constants for entity lifecycle management