@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/references/utilities/module.md

@@ -1,46 +1,15 @@
-# Module Utility
-
-The Module utility provides a pre-flight check for optional peer dependencies. IGNIS helpers and components often depend on packages that are not bundled with the framework (for example, `@connectrpc/connect` for gRPC, `@hono/swagger-ui` for the Swagger component). Calling `validateModule` at the start of a lazy-loaded code path ensures a clear, actionable error is thrown before any import is attempted, rather than a cryptic "Cannot find module" crash.
-
-Resolution is rooted at `process.cwd()/node_modules` via Node's `createRequire`, so peer dependencies installed in the consuming application are found correctly even though this utility lives inside `packages/helpers/dist/`.
-
-## `validateModule`
-
-Resolves each module name in sequence using `require.resolve`. If any module cannot be found it logs the failure and throws an `ApplicationError` with an install instruction. Returns a `Promise<void>` - it is async to support consistent `await` usage at call sites, though resolution itself is synchronous.
-
-### Signature
-
-```typescript
-validateModule(opts: {
-  scope?: string;
-  modules: Array<string>;
-}): Promise<void>
-```
-
-**Options**
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `modules` | `Array<string>` | `[]` | Module names to check. Evaluated in order - the first missing module stops the loop and throws. |
-| `scope` | `string` | `''` | Human-readable label for the calling feature (e.g. the component or helper class name). Included in the error message to tell the developer which feature needs the package. |
+---
+title: Module Utility
+description: Pre-flight check that fails fast with an install instruction when an optional peer dependency is missing
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-### Error message format
-
-When a module is missing the thrown error reads:
-
-```
-[validateModule] <module> is required for <scope>. Please install '<module>'
-```
-
-If `scope` is omitted:
-
-```
-[validateModule] <module> is required. Please install '<module>'
-```
+# Module Utility
 
-### Example - gRPC controller (optional dep guard)
+A pre-flight check for optional peer dependencies. IGNIS helpers and components often depend on packages that are not bundled with the framework (`@connectrpc/connect` for gRPC, `@hono/swagger-ui` for the Swagger component, and so on). Calling `validateModule` before a lazy `import()` throws a clear, actionable error instead of a cryptic "Cannot find module" crash.
 
-The `GrpcRequestAdapter` uses `validateModule` to gate the ConnectRPC import. The check runs once before the adapter is wired up, so the error surfaces at startup rather than on the first request.
+## In one example
 
 ```typescript
 import { validateModule } from '@venizia/ignis-helpers';
@@ -58,33 +27,31 @@ export class MyGrpcController extends BaseGrpcController {
 }
 ```
 
-### Example - custom helper with multiple optional deps
+## Functions
 
-When a feature requires several packages, list them all. The first missing one stops the check.
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `validateModule` | `validateModule(opts: { scope?: string; modules: Array<string> }): Promise<void>` | Resolves each module in `modules`, in order, via `require.resolve`. Throws an `ApplicationError` on the first one that cannot be found. |
 
-```typescript
-import { validateModule } from '@venizia/ignis-helpers';
-import { BaseHelper } from '@venizia/ignis-helpers';
+## Error message format
 
-export class KafkaQueueHelper extends BaseHelper {
-  async configure() {
-    await validateModule({
-      scope: KafkaQueueHelper.name,
-      modules: ['kafkajs', 'kafkajs-snappy'],
-    });
+| `scope` | Message |
+|---------|---------|
+| provided | `[validateModule] <module> is required for <scope>. Please install '<module>'` |
+| omitted | `[validateModule] <module> is required. Please install '<module>'` |
 
-    const { Kafka } = await import('kafkajs');
-    // ... initialise Kafka client
-  }
-}
-```
+## Notes
+
+- **Resolution is rooted at `process.cwd()/node_modules`** via Node's `createRequire`, so peer dependencies installed in the consuming application resolve correctly even though this utility ships inside `packages/helpers/dist/`.
+- **Evaluated in order - first miss wins.** With multiple `modules`, the loop stops at the first unresolved one and throws; later entries are never checked.
+- **`async` for call-site consistency only.** Resolution itself is synchronous (`require.resolve`); the function returns a `Promise<void>` so every call site can `await` it uniformly.
+- **Call it once, at startup - not per request.** Place it in an initialisation hook (`configure`, `binding`, `boot`), before the guarded `import()`.
+- **Recommended pattern:** declare the dependency as `peerDependenciesMeta` with `optional: true` in `package.json`, call `validateModule` at the top of the method that needs it, and pass the feature or class name as `scope` so the thrown message pinpoints the caller.
 
-## When to use
+## See also
 
-Use `validateModule` whenever your code does a dynamic `import()` of a package that is listed as an optional peer dependency in `package.json`. The recommended pattern is:
+- [Utilities Overview](/references/utilities/) - all utility functions
 
-1. Declare the dep as `peerDependenciesMeta` with `optional: true` in `package.json`.
-2. Call `validateModule` at the top of the method that needs the package - before any `import()`.
-3. Pass the feature or class name as `scope` so the error message pinpoints which feature triggered the check.
+**Files:**
 
-Avoid calling `validateModule` on every request. Place it in an initialisation hook (`configure`, `binding`, `boot`) that runs once at startup.
+- [`packages/helpers/src/utilities/module.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/module.utility.ts)

package/content/references/utilities/parse.md

@@ -1,85 +1,55 @@
-# Parse Utility
-
-The Parse utility provides a collection of functions for data type checking, conversion, and transformation.
+---
+title: Parse Utility
+description: Type checking, safe numeric and boolean conversion, camelCase transforms, and array-to-map helpers
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-## Type Checking
-
--   **`isInt(n)`**: Checks if a value is an integer.
--   **`isFloat(n)`**: Checks if a value is a float.
+# Parse Utility
 
-## Type Conversion
+A collection of standalone functions for type checking, safe type conversion, and string/object/array transformation - the small helpers repositories and controllers reach for when normalizing loosely typed input.
 
--   **`int(input)`**: Parses a value to an integer. Handles strings with commas and defaults to `0` if the input is invalid.
--   **`float(input, digit = 2)`**: Parses a value to a float, rounding to a specified number of digits. Handles strings with commas and defaults to `0` if the input is invalid.
--   **`toBoolean(input)`**: Converts a value to a boolean. Returns `false` for empty string, `'false'`, `'0'`, `false`, `0`, `null`, and `undefined`. Returns `true` for everything else.
+## In one example
 
 ```typescript
-import { int, float, toBoolean } from '@venizia/ignis-helpers';
+import { int, float, toBoolean, toCamel, keysToCamel } from '@venizia/ignis-helpers';
 
 const myInt = int('1,000'); // => 1000
 const myFloat = float('1,234.567', 2); // => 1234.57
 const myBool = toBoolean('true'); // => true
-```
-
-## String and Object Transformation
-
--   **`toCamel(s)`**: Converts a string from snake_case or kebab-case to camelCase.
--   **`keysToCamel(object)`**: Recursively converts all keys in an object (and nested objects) to camelCase.
-
-```typescript
-import { toCamel, keysToCamel } from '@venizia/ignis-helpers';
-
-const camelString = toCamel('my-snake_case-string');
-// => 'mySnakeCaseString'
 
 const camelObject = keysToCamel({ 'first-name': 'John', 'last_name': 'Doe' });
 // => { firstName: 'John', lastName: 'Doe' }
 ```
 
-## Number Parsing
+## Functions
 
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `isInt` | `isInt(n: any): boolean` | `true` when `n` is (or coerces to) an integer. |
+| `isFloat` | `isFloat(input: any): boolean` | `true` when `input` is (or coerces to) a non-integer number. |
+| `int` | `int(input: any): number` | Parses `input` to an integer. Strips commas first; returns `0` for empty/invalid input. |
+| `float` | `float(input: any, digit = 2): number` | Parses `input` to a float, rounded to `digit` places (via lodash `round`). Strips commas first; returns `0` for empty/invalid input. |
+| `toBoolean` | `toBoolean(input: any): boolean` | `false` for `''`, `'false'`, `'0'`, `false`, `0`, `null`, `undefined`; `true` for everything else. |
+| `toCamel` | `toCamel(s: string): string` | Converts a `snake_case` or `kebab-case` string to `camelCase`. |
+| `keysToCamel` | `keysToCamel(object: object): any` | Recursively camelizes every key in `object`. Arrays stay arrays (their object elements are still camelized); `Date` values pass through untouched. |
+| `parseArrayToMapWithKey` | `parseArrayToMapWithKey<T, K>(arr: T[], keyMap: K): Map<T[K], T>` | Turns an array of objects into a `Map` keyed by `keyMap`. Positional arguments, not an options object. Throws if `keyMap` is missing from an element; last element wins on duplicate keys. |
+| `toDelimitedArray` | `toDelimitedArray(input: unknown, separator = ','): string[]` | Splits `input` on `separator` into trimmed, non-empty entries. `null`/`undefined` input returns `[]`. |
+| `toTrimmed` | `toTrimmed(input: unknown): string` | Stringifies and trims `input`; `null`/`undefined` returns `''`. |
+| `getUID` | `getUID(): string` | Generates a short, uppercase, `Math.random()`-based ID - not cryptographically unique. |
 
-```typescript
-
-// US format (default) - comma is thousands separator
+## Notes
 
-// EU format - dot is thousands separator, comma is decimal
-```
+- **`int`/`float` are comma-tolerant.** Both strip `,` before parsing, so `'1,000'` and `1000` behave the same - useful for user-typed numeric input.
+- **`parseArrayToMapWithKey` breaks the options-object convention on purpose** - it takes `(arr, keyMap)` positionally, unlike every other function on this page.
+- **`toDelimitedArray` and `toTrimmed` are the transform functions for list-shaped and string env values** - typical use is `applicationEnvironment.get(KEY, { transform: toDelimitedArray })`.
+- **`getUID` is for short, human-glanceable identifiers**, not for anything that needs global uniqueness guarantees - use the [UID helper](/extensions/helpers/) (Snowflake-based) for that.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `method` | `'int' \| 'float'` | `'int'` | Parse as integer or float |
-| `locale` | `'us' \| 'eu'` | `'us'` | Number format locale |
+## See also
 
-## Array Transformation
+- [Utilities Overview](/references/utilities/) - all utility functions
+- [Schema Utility](/references/utilities/schema) - `snakeToCamel` for Zod schemas built on `toCamel`/`keysToCamel`
 
--   **`parseArrayToMapWithKey(arr, keyMap)`**: Transforms an array of objects into a `Map`, using a specified property of the objects as keys. Takes positional arguments (not an options object). Throws an error if `keyMap` is not found in an element. Last element wins on duplicate keys.
+**Files:**
 
-```typescript
-import { parseArrayToMapWithKey } from '@venizia/ignis-helpers';
-
-const users = [
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' },
-];
-
-// Record (options object pattern)
-// => { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } }
-
-// Map (positional arguments)
-const usersMap = parseArrayToMapWithKey(users, 'id');
-// => Map { 1 => { id: 1, name: 'Alice' }, 2 => { id: 2, name: 'Bob' } }
-
-const user = usersMap.get(1);
-// => { id: 1, name: 'Alice' }
-```
-
-## Unique ID
-
--   **`getUID()`**: Generates a simple, short unique ID string based on `Math.random()`, returned in uppercase.
-
-```typescript
-import { getUID } from '@venizia/ignis-helpers';
-
-const uniqueId = getUID(); // => e.g., 'A1B2C3D4'
-```
+- [`packages/helpers/src/utilities/parse.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/parse.utility.ts)

package/content/references/utilities/performance.md

@@ -1,79 +1,54 @@
-# Performance Utility
-
-The Performance utility provides functions for measuring and logging the execution time of code blocks, which is useful for identifying bottlenecks and optimizing your application. All timing uses `performance.now()` (milliseconds).
-
-## `executeWithPerformanceMeasure`
-
-This is a higher-order function that wraps a task (a function), automatically logging its start time, end time, and total execution duration. Returns a Promise that resolves to the task's return value.
+---
+title: Performance Utility
+description: Checkpoint-based timing and a logging wrapper for measuring execution duration
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-### `executeWithPerformanceMeasure(opts)`
-
--   `opts` (object):
-    -   `logger` (Logger, optional): A logger instance to use for logging. Defaults to `console`.
-    -   `level` (string, optional): The log level to use (e.g., `'debug'`, `'info'`). Defaults to `'debug'`.
-    -   `description` (string, optional): A description of the task being measured. Defaults to `'Executing'`.
-    -   `scope` (string): A scope to identify the context of the measurement.
-    -   `task` (Function): The function to be executed and measured. Can be sync or async (wrapped with `Promise.resolve()`).
-    -   `args` (any, optional): Arguments to include in the log output for debugging purposes. When provided, they are logged as JSON (`%j` format).
+# Performance Utility
 
-### Example
+Functions for measuring and logging how long a code block takes to run, built on `performance.now()` (millisecond resolution). `BaseApplication` uses `executeWithPerformanceMeasure` internally to time component, controller, and datasource registration during startup.
 
-The `BaseApplication` uses this utility to measure the time taken to register components, controllers, and data sources during the startup process.
+## In one example
 
 ```typescript
-// Inside BaseApplication class
 import { executeWithPerformanceMeasure } from '@venizia/ignis-helpers';
 
-// ...
-
-  async registerComponents() {
-    await executeWithPerformanceMeasure({
-      logger: this.logger,
-      scope: this.registerComponents.name,
-      description: 'Register application components',
-      task: async () => {
-        // ... logic to register components
-      },
-    });
-  }
+await executeWithPerformanceMeasure({
+  logger: this.logger,
+  scope: this.registerComponents.name,
+  description: 'Register application components',
+  task: async () => {
+    // ... logic to register components
+  },
+});
 ```
 
-When `registerComponents` is called, it will produce log output similar to this:
-
 ```
 [RegisterComponents] START | Register application components ...
 [RegisterComponents] DONE | Register application components | Took: 12.3456 (ms)
 ```
 
-With `args` provided:
+## Functions
 
-```
-[RegisterComponents] START | Register application components... | Args: {"name":"auth"}
-[RegisterComponents] DONE | Register application components | Args: {"name":"auth"} | Took: 12.3456 (ms)
-```
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `executeWithPerformanceMeasure` | `executeWithPerformanceMeasure<R>(opts: { logger?: ILogger; level?: string; description?: string; args?: any; scope: string; task: Function }): Promise<R>` | Runs `task` (sync or async), logging a `START` line before and a `DONE` line after with the elapsed time. Resolves to whatever `task` returns. |
+| `getPerformanceCheckpoint` | `getPerformanceCheckpoint(): number` | Returns `performance.now()` - a starting timestamp to pass to `getExecutedPerformance`. |
+| `getExecutedPerformance` | `getExecutedPerformance(opts: { from: number; digit?: number }): number` | Elapsed milliseconds since `from`, rounded to `digit` places (default `6`). |
 
-## Low-Level Utilities
+## Notes
 
-For more granular measurements, you can use the lower-level functions:
+- **Defaults:** `logger` falls back to `console`, `level` to `'debug'`, `description` to `'Executing'`.
+- **`args`, when provided, are logged as JSON (`%j`)** on both the `START` and `DONE` lines - handy for correlating a specific call's timing.
+- **`task` is wrapped in `Promise.resolve()`**, so a plain synchronous function works exactly like an `async` one.
+- **Prefer the checkpoint pair for granular, multi-point measurements** inside a single function, where wrapping the whole thing in `executeWithPerformanceMeasure` would not isolate the segment you care about.
 
--   **`getPerformanceCheckpoint()`**: Returns a high-resolution timestamp from `performance.now()`, which you can use as a starting point.
--   **`getExecutedPerformance(opts)`**: Calculates the elapsed time in milliseconds since a given checkpoint. Rounds to 6 decimal places by default.
-    -   `opts.from` (number): The starting checkpoint from `getPerformanceCheckpoint()`.
-    -   `opts.digit` (number, optional): Number of decimal places for rounding. Defaults to `6`.
+## See also
 
-### Example
-
-```typescript
-import { getPerformanceCheckpoint, getExecutedPerformance } from '@venizia/ignis-helpers';
+- [Utilities Overview](/references/utilities/) - all utility functions
+- [Logger](/extensions/helpers/logger/) - the `ILogger` type accepted by `executeWithPerformanceMeasure`
 
-const start = getPerformanceCheckpoint();
+**Files:**
 
-// ... perform some work
-
-const duration = getExecutedPerformance({ from: start });
-console.log(`The work took ${duration} ms.`);
-
-// With custom precision
-const preciseDuration = getExecutedPerformance({ from: start, digit: 2 });
-console.log(`The work took ${preciseDuration} ms.`);
-```
+- [`packages/helpers/src/utilities/performance.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/performance.utility.ts)

package/content/references/utilities/promise.md

@@ -1,19 +1,15 @@
-# Promise Utility
-
-The Promise utility provides helper functions for working with Promises, particularly for managing concurrency and transforming values.
-
-## `executePromiseWithLimit`
+---
+title: Promise Utility
+description: Concurrency-limited task execution plus small Promise and object-path helpers
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-This function executes an array of asynchronous tasks concurrently, but with a specified limit on the number of promises running at any given time. This is useful for throttling asynchronous operations to avoid overwhelming a system (e.g., making a large number of concurrent API calls).
-
-### `executePromiseWithLimit(opts)`
+# Promise Utility
 
--   `opts` (object):
-    -   `tasks` (Array<() => Promise<T>>): An array of functions that each return a Promise.
-    -   `limit` (number): The maximum number of promises to execute in parallel.
-    -   `onTaskDone` (<R>(opts: { result: R }) => ValueOrPromise<void>, optional): A callback function that is executed whenever a task is completed (specifically, when the concurrency limit is reached and a task finishes to make room).
+Helper functions for working with Promises - bounding concurrency, normalizing thrown values, type-guarding thenables, reading nested object paths, and firing-and-forgetting async work safely.
 
-### Example
+## In one example
 
 ```typescript
 import { executePromiseWithLimit, sleep } from '@venizia/ignis-helpers';
@@ -22,67 +18,37 @@ const tasks = [
   () => sleep(1000).then(() => 'Task 1 done'),
   () => sleep(500).then(() => 'Task 2 done'),
   () => sleep(1200).then(() => 'Task 3 done'),
-  () => sleep(800).then(() => 'Task 4 done'),
 ];
 
-console.log('Starting tasks with a limit of 2...');
-
 const results = await executePromiseWithLimit({
   tasks,
   limit: 2,
-  onTaskDone: ({ result }) => {
-    console.log('A task finished:', result);
-  },
+  onTaskDone: ({ result }) => console.log('A task finished:', result),
 });
-
-console.log('All tasks finished:', results);
 ```
 
-## `toError`
+## Functions
 
-Normalizes an unknown thrown value into an `Error` instance. Useful in `catch` blocks where the caught value is typed `unknown` and isn't guaranteed to already be an `Error`.
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `executePromiseWithLimit` | `executePromiseWithLimit<T>(opts: { tasks: Array<() => Promise<T>>; limit: number; onTaskDone?: <R>(opts: { result: R }) => ValueOrPromise<void> }): Promise<T[]>` | Runs `tasks` with at most `limit` running concurrently. Calls `onTaskDone` each time the limit is hit and a slot frees up. Throws if `limit` is not a positive integer. |
+| `toError` | `toError(error: unknown): Error` | Normalizes a `catch`-block value into an `Error` - passes an existing `Error` through, wraps anything else with `new Error(String(error))`. |
+| `isPromiseLike` | `isPromiseLike<T>(value: T \| PromiseLike<T>): value is PromiseLike<T>` | Type guard: `true` when `value` is non-null and has a callable `.then`. |
+| `getDeepProperty` | `getDeepProperty<T, V>(obj: T, path: string): V` | Reads a dot-separated `path` off `obj`. Throws if any intermediate segment is `null`/`undefined`. |
+| `voidExecution` | `voidExecution(opts: { logger?: ILogger; scope: string; execution: ValueOrPromise<unknown> }): void` | Fire-and-forget: if `execution` is a Promise, routes a rejection to `logger.for(scope).error(...)` (or `console.error` without a logger) instead of an unhandled rejection. Synchronous values pass through untouched. |
 
-```typescript
-import { toError } from '@venizia/ignis-helpers';
+## Notes
 
-try {
-  await riskyOperation();
-} catch (caught) {
-  const error = toError(caught);
-  console.error(error.message);
-}
-```
+- **`executePromiseWithLimit` validates `limit` eagerly** - a non-integer or a value below `1` throws immediately, before any task runs.
+- **`onTaskDone` only fires under backpressure.** It runs when the number of in-flight tasks reaches `limit` and `Promise.race` resolves one of them - not after every task.
+- **`voidExecution` exists because `BaseHelper` cannot carry `protected` members** on classes the container instantiates anonymously (TS4094) - it is a standalone function, not a helper method, precisely so factory-built controllers can still use it.
+- **`getDeepProperty` throws, it does not return `undefined`**, on a missing intermediate segment - wrap the call if you need optional-path semantics instead.
 
-## `isPromiseLike`
+## See also
 
-A type guard function to check if a given value is a Promise-like object (i.e., it has a `then` method). Checks that the value is non-null, is an object or function, and has a `then` property that is a function.
-
-```typescript
-import { isPromiseLike } from '@venizia/ignis-helpers';
+- [Utilities Overview](/references/utilities/) - all utility functions
+- [Date Utility](/references/utilities/date) - `sleep()`, used to build the tasks in the example above
 
-const a = Promise.resolve(1);
-const b = 2;
+**Files:**
 
-if (isPromiseLike(a)) {
-  // This will run
-}
-
-if (isPromiseLike(b)) {
-  // This will not run
-}
-```
-
-## `getDeepProperty`
-
-Traverses a dot-separated property path on an object and returns the value. It throws an error if any intermediate part of the path is null or undefined.
-
-```typescript
-import { getDeepProperty } from '@venizia/ignis-helpers';
-
-const obj = { a: { b: { c: 'hello' } } };
-
-const value = getDeepProperty(obj, 'a.b.c'); // => 'hello'
-
-// Throws: Cannot read property 'x' of undefined
-getDeepProperty(obj, 'a.x.y');
-```
+- [`packages/helpers/src/utilities/promise.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/promise.utility.ts)