@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/{wiki → content}/references/quick-reference.md

@@ -30,8 +30,6 @@ await app.start();
 - `initialize()` - Bootstrap the application
 - `start()` - Start HTTP server
 - `stop()` - Stop server gracefully
-- `get<T>(key)` - Resolve from DI container
-- `mountControllers()` - Register controllers
 
 ### BaseRestController
 
@@ -85,7 +83,7 @@ class GreeterController extends BaseGrpcController {
 ```typescript
 import { BaseService, injectable } from '@venizia/ignis';
 
-@injectable()
+@injectable({})
 class UserService extends BaseService {
   constructor() {
     super({ scope: UserService.name });
@@ -93,7 +91,7 @@ class UserService extends BaseService {
 
   async getUser(id: string) {
     this.logger.info('Getting user', id);
-    return this.userRepo.findById(id);
+    return this.userRepository.findById({ id });
   }
 }
 ```
@@ -104,27 +102,25 @@ class UserService extends BaseService {
 ### DefaultCRUDRepository
 
 ```typescript
-import { DefaultCRUDRepository } from '@venizia/ignis';
+import { DefaultCRUDRepository, repository } from '@venizia/ignis';
 import { User } from '../models';
+import { PostgresDataSource } from '../datasources';
 
-class UserRepository extends DefaultCRUDRepository<User> {
-  constructor() {
-    super(User);
-  }
+@repository({ model: User, dataSource: PostgresDataSource })
+class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // No constructor needed - dataSource auto-injected from @repository decorator
 }
 ```
 
 **Key Methods:**
-- `create(data)` - Create single entity
-- `createMany(data[])` - Create multiple entities
-- `find(filter?)` - Find many with filter
-- `findById(id)` - Find by ID
-- `findOne(filter)` - Find single entity
-- `count(filter?)` - Count entities
-- `update(id, data)` - Update by ID
-- `updateMany(filter, data)` - Update multiple
-- `delete(id)` - Delete by ID (soft/hard based on config)
-- `deleteMany(filter)` - Delete multiple
+- `find({ filter })` - Find many with filter, returns `T[]`
+- `findById({ id })` - Find by ID
+- `findOne({ filter })` - Find single entity
+- `count({ where? })` - Count entities
+- `create({ data })` - Create single entity, returns `{ count, data }`
+- `createAll({ data: [] })` - Create multiple entities, returns `{ count, data[] }`
+- `updateById({ id, data })` - Update by ID
+- `deleteById({ id })` - Delete by ID
 
 ### BaseEntity
 
@@ -132,10 +128,10 @@ class UserRepository extends DefaultCRUDRepository<User> {
 import { BaseEntity, model } from '@venizia/ignis';
 import { integer, text, pgTable } from 'drizzle-orm/pg-core';
 
-@model()
+@model({ type: 'entity' })
 class User extends BaseEntity {
-  static readonly tableName = 'users';
-  static readonly schema = pgTable(User.tableName, {
+  static readonly TABLE_NAME = 'users';
+  static readonly schema = pgTable(User.TABLE_NAME, {
     id: integer('id').primaryKey(),
     name: text('name').notNull(),
     email: text('email').notNull().unique(),
@@ -144,7 +140,7 @@ class User extends BaseEntity {
 ```
 
 **Key Properties:**
-- `static tableName` - Database table name
+- `static TABLE_NAME` - Database table name
 - `static schema` - Drizzle schema definition
 - `static AUTHORIZATION_SUBJECT` - Authorization principal (auto-set from `@model` settings `authorize.principal`)
 
@@ -226,7 +222,7 @@ class UserController extends BaseRestController {
 | Operator | SQL | Example |
 |----------|-----|---------|
 | `in` | `IN` | `{ status: { in: ['active', 'pending'] } }` |
-| `notIn` | `NOT IN` | `{ status: { notIn: ['deleted'] } }` |
+| `nin` | `NOT IN` | `{ status: { nin: ['deleted'] } }` |
 
 ### Pattern Matching
 
@@ -234,17 +230,8 @@ class UserController extends BaseRestController {
 |----------|-----|---------|
 | `like` | `LIKE` | `{ name: { like: '%john%' } }` |
 | `ilike` | `ILIKE` | `{ email: { ilike: '%@gmail.com' } }` |
-| `notLike` | `NOT LIKE` | `{ name: { notLike: '%test%' } }` |
-| `notILike` | `NOT ILIKE` | `{ email: { notILike: '%spam%' } }` |
-| `startsWith` | `LIKE 'value%'` | `{ name: { startsWith: 'John' } }` |
-| `endsWith` | `LIKE '%value'` | `{ email: { endsWith: '@example.com' } }` |
-
-### Null Operators
-
-| Operator | SQL | Example |
-|----------|-----|---------|
-| `isNull` | `IS NULL` | `{ deletedAt: { isNull: true } }` |
-| `isNotNull` | `IS NOT NULL` | `{ email: { isNotNull: true } }` |
+| `nlike` | `NOT LIKE` | `{ name: { nlike: '%test%' } }` |
+| `nilike` | `NOT ILIKE` | `{ email: { nilike: '%spam%' } }` |
 
 ### Logical Operators
 
@@ -262,61 +249,59 @@ class UserController extends BaseRestController {
 | `containedBy` | `<@` | `{ tags: { containedBy: ['ts', 'js', 'go'] } }` |
 | `overlaps` | `&&` | `{ tags: { overlaps: ['react', 'vue'] } }` |
 
-### JSON Operators (PostgreSQL)
-
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `jsonPath` | Query JSON field | `{ metadata: { jsonPath: '$.user.name', eq: 'John' } }` |
-
-
 ## Common Filters
 
 ### Basic Find
 
 ```typescript
-const users = await userRepo.find({
-  where: { isActive: true },
-  orderBy: { createdAt: 'desc' },
-  limit: 10,
-  offset: 0,
+const users = await userRepository.find({
+  filter: {
+    where: { isActive: true },
+    order: ['createdAt DESC'],
+    limit: 10,
+    offset: 0,
+  },
 });
 ```
 
 ### With Multiple Conditions
 
 ```typescript
-const users = await userRepo.find({
-  where: {
-    and: [
-      { age: { gte: 18 } },
-      { status: { in: ['active', 'pending'] } },
-      { email: { endsWith: '@company.com' } }
-    ]
-  }
+const users = await userRepository.find({
+  filter: {
+    where: {
+      and: [
+        { age: { gte: 18 } },
+        { status: { in: ['active', 'pending'] } },
+        { email: { ilike: '%@company.com' } },
+      ],
+    },
+  },
 });
 ```
 
 ### With Relations
 
 ```typescript
-const posts = await postRepo.find({
-  where: { published: true },
-  include: {
-    author: true,
-    comments: {
-      where: { approved: true },
-      limit: 5
-    }
-  }
+const posts = await postRepository.find({
+  filter: {
+    where: { published: true },
+    include: [
+      { relation: 'author' },
+      { relation: 'comments', scope: { where: { approved: true }, limit: 5 } },
+    ],
+  },
 });
 ```
 
 ### Selecting Fields
 
 ```typescript
-const users = await userRepo.find({
-  where: { isActive: true },
-  fields: ['id', 'name', 'email'], // Only these fields
+const users = await userRepository.find({
+  filter: {
+    where: { isActive: true },
+    fields: ['id', 'name', 'email'],
+  },
 });
 ```
 
@@ -328,7 +313,7 @@ const users = await userRepo.find({
 ```typescript
 import { injectable } from '@venizia/ignis';
 
-@injectable()
+@injectable({})
 class MyService extends BaseService {
   // ...
 }
@@ -348,13 +333,6 @@ class UserController extends BaseRestController {
   }
 ```
 
-### Manual Resolution
-
-```typescript
-const userService = app.get<UserService>('services.UserService');
-```
-
-
 ## Common Imports
 
 ### Core Framework
@@ -408,21 +386,20 @@ import {
   ApplicationLogger,
 
   // Caching
-  RedisHelper,
+  RedisSingleHelper,
 
   // Queues
   QueueHelper,
 
   // Crypto
   hash,
-  compare,
 
   // HTTP
   HTTP,
 } from '@venizia/ignis-helpers';
 import { BullMQHelper } from '@venizia/ignis-helpers/bullmq';
 import { CronHelper } from '@venizia/ignis-helpers/cron';
-import { MinIOHelper } from '@venizia/ignis-helpers/minio';
+import { MinioHelper } from '@venizia/ignis-helpers/minio';
 ```
 
 ### Dependency Injection
@@ -487,14 +464,17 @@ getDashboard(c: Context) {
 import { Statuses } from '@venizia/ignis';
 
 // Create with status
-const order = await orderRepo.create({
-  items: [...],
-  status: Statuses.PENDING,
+const { data: order } = await orderRepository.create({
+  data: {
+    items: [...],
+    status: Statuses.PENDING,
+  },
 });
 
 // Update status
-await orderRepo.update(orderId, {
-  status: Statuses.COMPLETED,
+await orderRepository.updateById({
+  id: orderId,
+  data: { status: Statuses.COMPLETED },
 });
 
 // Check status
@@ -556,27 +536,6 @@ app.notFound(notFoundHandler({ logger: app.logger }));
 ```
 
 
-## Environment Variables
-
-### Loading Environment
-
-```typescript
-import { EnvHelper } from '@venizia/ignis-helpers';
-
-// Load from .env file
-EnvHelper.load();
-
-// Get variable
-const dbUrl = EnvHelper.get('DATABASE_URL');
-
-// Get with default
-const port = EnvHelper.get('PORT', '3000');
-
-// Get required (throws if missing)
-const apiKey = EnvHelper.getRequired('API_KEY');
-```
-
-
 ## Common Patterns
 
 ### Controller → Service → Repository
@@ -605,7 +564,7 @@ class UserController extends BaseRestController {
 class UserService extends BaseService {
   constructor(
     @inject({ key: 'repositories.UserRepository' })
-    private userRepo: UserRepository,
+    private userRepository: UserRepository,
   ) {
     super({ scope: UserService.name });
   }
@@ -614,7 +573,7 @@ class UserService extends BaseService {
     // Business logic
     const hashedPassword = await hash({ value: data.password });
 
-    return this.userRepo.create({
+    return this.userRepository.create({
       data: {
         ...data,
         password: hashedPassword,

package/content/references/utilities/crypto.md

@@ -0,0 +1,98 @@
+# 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'`. |
+
+### 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/).
+
+### Examples
+
+**MD5 digest (hex)**
+
+```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}`;
+```
+
+**HMAC-SHA256 in base64 - API request signing**
+
+```typescript
+const hmac = hash(`${timestamp}.${body}`, {
+  algorithm: 'SHA256',
+  secret: apiKey,
+  outputType: 'base64',
+});
+```
+
+## When to use
+
+Use `hash` for lightweight, one-off hashing that does not require key management or IV handling:
+
+- 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)
+
+For encryption, decryption, or asymmetric operations (AES, RSA, ECDH) use the [Crypto helper](/extensions/helpers/crypto/) instead.

package/{wiki → content}/references/utilities/index.md

@@ -1,6 +1,6 @@
 # Utilities
 
-Pure, standalone functions providing common, reusable logic for the Ignis framework. All utilities are stateless and easy to use.
+Pure, standalone functions providing common, reusable logic for the IGNIS framework. All utilities are stateless and easy to use.
 
 ## Quick Reference
 
@@ -10,7 +10,7 @@ Pure, standalone functions providing common, reusable logic for the Ignis framew
 | **Date** | `ignis-helpers` | Date/time manipulation | `dayjs`, `sleep()`, `isWeekday()`, `getDateTz()`, `hrTime()` |
 | **JSX** | `ignis` | HTML/JSX responses | `htmlContent()`, `htmlResponse()` |
 | **Module** | `ignis-helpers` | Module validation | `validateModule()` |
-| **Parse** | `ignis-helpers` | Data type conversion | `int()`, `float()`, `toBoolean()`, `toCamel()`, `getNumberValue()` |
+| **Parse** | `ignis-helpers` | Data type conversion | `int()`, `float()`, `toBoolean()`, `toCamel()` |
 | **Performance** | `ignis-helpers` | Execution timing | `executeWithPerformanceMeasure()`, `getPerformanceCheckpoint()` |
 | **Promise** | `ignis-helpers` | Promise helpers | `executePromiseWithLimit()`, `isPromiseLike()`, `getDeepProperty()` |
 | **Request** | `ignis-helpers` | HTTP utilities | `parseMultipartBody()`, `sanitizeFilename()`, `createContentDispositionHeader()` |
@@ -47,7 +47,7 @@ Utilities are imported from `@venizia/ignis` (schema, JSX, and status helpers) o
 
 ```typescript
 import { jsonContent, jsonResponse, htmlResponse, requiredString, Statuses } from '@venizia/ignis';
-import { hash, dayjs, sleep, int, float, toBoolean, getNumberValue } from '@venizia/ignis-helpers';
+import { hash, dayjs, sleep, int, float, toBoolean } from '@venizia/ignis-helpers';
 
 // Crypto
 const md5Hash = hash('some text', { algorithm: 'MD5', outputType: 'hex' });

package/{wiki → content}/references/utilities/jsx.md

@@ -186,7 +186,8 @@ export class PageController extends BaseRestController {
 ### HTML Email Preview
 
 ```typescript
-import { BaseRestController, get, htmlResponse, TRouteContext, z } from '@venizia/ignis';
+import { BaseRestController, get, htmlResponse, TRouteContext } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
 import { HTTP } from '@venizia/ignis-helpers';
 
 const EmailRoutes = {
@@ -225,7 +226,8 @@ export class EmailController extends BaseRestController {
 ### Documentation Page
 
 ```typescript
-import { BaseRestController, get, htmlResponse, TRouteContext, z } from '@venizia/ignis';
+import { BaseRestController, get, htmlResponse, TRouteContext } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
 import { HTTP } from '@venizia/ignis-helpers';
 
 const DocsRoutes = {
@@ -355,7 +357,7 @@ async getUserProfile(c: TRouteContext) {
   return c.html(<UserProfile user={user} />);
 }
 
-// Bad: Don't use htmlResponse for API endpoints — use jsonResponse instead
+// Bad: Don't use htmlResponse for API endpoints - use jsonResponse instead
 ```
 
 ### 2. Combine with Authentication
@@ -564,7 +566,7 @@ async getUsers() {
 - **Related References:**
   - [Schema Utility](./schema.md) - JSON content and response helpers
   - [Controllers](../base/controllers.md) - Defining routes and handlers
-  - [OpenAPI Component](/extensions/components/swagger) - API documentation
+  - [OpenAPI Component](/extensions/components/api-reference) - API documentation
 
 - **External Resources:**
   - [Hono JSX Documentation](https://hono.dev/guides/jsx)

package/content/references/utilities/module.md

@@ -0,0 +1,90 @@
+# 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. |
+
+### 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>'
+```
+
+### Example - gRPC controller (optional dep guard)
+
+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.
+
+```typescript
+import { validateModule } from '@venizia/ignis-helpers';
+
+const GRPC_MODULES = ['@connectrpc/connect'];
+
+export class MyGrpcController extends BaseGrpcController {
+  async configure() {
+    // Fails fast with a clear install instruction if the peer dep is absent
+    await validateModule({ scope: MyGrpcController.name, modules: GRPC_MODULES });
+
+    const { ConnectRouter } = await import('@connectrpc/connect');
+    // ... register routes
+  }
+}
+```
+
+### Example - custom helper with multiple optional deps
+
+When a feature requires several packages, list them all. The first missing one stops the check.
+
+```typescript
+import { validateModule } from '@venizia/ignis-helpers';
+import { BaseHelper } from '@venizia/ignis-helpers';
+
+export class KafkaQueueHelper extends BaseHelper {
+  async configure() {
+    await validateModule({
+      scope: KafkaQueueHelper.name,
+      modules: ['kafkajs', 'kafkajs-snappy'],
+    });
+
+    const { Kafka } = await import('kafkajs');
+    // ... initialise Kafka client
+  }
+}
+```
+
+## When to use
+
+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:
+
+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.
+
+Avoid calling `validateModule` on every request. Place it in an initialisation hook (`configure`, `binding`, `boot`) that runs once at startup.

package/{wiki → content}/references/utilities/parse.md

@@ -12,16 +12,13 @@ The Parse utility provides a collection of functions for data type checking, con
 -   **`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.
--   **`toStringDecimal(input, digit = 2, options?)`**: Formats a number to a string with a specified number of decimal places. By default uses locale-specific formatting (`useLocaleFormat: true`). When `useLocaleFormat` is `false`, uses `toFixed()` instead.
 
 ```typescript
-import { int, float, toBoolean, toStringDecimal } from '@venizia/ignis-helpers';
+import { int, float, toBoolean } from '@venizia/ignis-helpers';
 
 const myInt = int('1,000'); // => 1000
 const myFloat = float('1,234.567', 2); // => 1234.57
 const myBool = toBoolean('true'); // => true
-const formatted = toStringDecimal(1234.5, 2); // => '1,234.50'
-const fixed = toStringDecimal(1234.5, 2, { useLocaleFormat: false }); // => '1234.50'
 ```
 
 ## String and Object Transformation
@@ -41,17 +38,12 @@ const camelObject = keysToCamel({ 'first-name': 'John', 'last_name': 'Doe' });
 
 ## Number Parsing
 
--   **`getNumberValue(input, opts?)`**: Parses a string to a number with locale support (US or EU format).
 
 ```typescript
-import { getNumberValue } from '@venizia/ignis-helpers';
 
-// US format (default) — comma is thousands separator
-getNumberValue('1,234.56', { method: 'float' }); // => 1234.56
-getNumberValue('1,234', { method: 'int' });       // => 1234
+// US format (default) - comma is thousands separator
 
-// EU format — dot is thousands separator, comma is decimal
-getNumberValue('1.234,56', { method: 'float', locale: 'eu' }); // => 1234.56
+// EU format - dot is thousands separator, comma is decimal
 ```
 
 | Option | Type | Default | Description |
@@ -61,11 +53,10 @@ getNumberValue('1.234,56', { method: 'float', locale: 'eu' }); // => 1234.56
 
 ## Array Transformation
 
--   **`parseArrayToRecordWithKey(opts)`**: Transforms an array of objects into a record (plain object), using a specified property of the objects as keys. Takes an options object with `arr` and `keyMap` properties. Throws an error if `keyMap` is not found in an element. Last element wins on duplicate keys.
 -   **`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.
 
 ```typescript
-import { parseArrayToRecordWithKey, parseArrayToMapWithKey } from '@venizia/ignis-helpers';
+import { parseArrayToMapWithKey } from '@venizia/ignis-helpers';
 
 const users = [
   { id: 1, name: 'Alice' },
@@ -73,7 +64,6 @@ const users = [
 ];
 
 // Record (options object pattern)
-const usersRecord = parseArrayToRecordWithKey({ arr: users, keyMap: 'id' });
 // => { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } }
 
 // Map (positional arguments)

package/{wiki → content}/references/utilities/promise.md

@@ -38,17 +38,19 @@ const results = await executePromiseWithLimit({
 console.log('All tasks finished:', results);
 ```
 
-## `transformValueOrPromise`
+## `toError`
 
-This async function applies a transformation function to a value that might be a direct value or a Promise. It always returns a Promise.
+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`.
 
 ```typescript
-import { transformValueOrPromise } from '@venizia/ignis-helpers';
+import { toError } from '@venizia/ignis-helpers';
 
-const double = (n: number) => n * 2;
-
-const result1 = await transformValueOrPromise(5, double); // => 10
-const result2 = await transformValueOrPromise(Promise.resolve(5), double); // => 10
+try {
+  await riskyOperation();
+} catch (caught) {
+  const error = toError(caught);
+  console.error(error.message);
+}
 ```
 
 ## `isPromiseLike`