@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/helpers/uid/index.md

@@ -1,12 +1,21 @@
 ---
 title: UID
-description: Snowflake ID generator with Base62 encoding for unique, time-sortable distributed identifiers
+description: Two ID generators - time-sortable Snowflake IDs, and short random IDs a human can read back
 difficulty: beginner
 ---
 
 # UID
 
-`SnowflakeUidHelper` generates 70-bit, time-sortable Snowflake IDs and encodes them as compact Base62 strings, suitable as database primary keys.
+Two generators, and they answer different questions.
+
+| Helper | Reads back as | Pick it when |
+|---|---|---|
+| `SnowflakeUidHelper` | Timestamp, worker ID, sequence | The ID is a primary key and you want insert order for free |
+| `OpaqueUidHelper` | Nothing | The ID leaves your system - a human reads it, or a stranger sees it |
+
+A Snowflake ID is transparent by design. `parseId()` gives back the exact millisecond it was minted and the worker that minted it. That is what you want in a log, and what you do not want printed on an invoice a customer keeps.
+
+An opaque ID gives nothing back. You trade the ordering for that, and for a short ID a human can read out loud.
 
 ## In one example
 
@@ -18,15 +27,19 @@ const id = generator.nextId();
 // => e.g. "9du1sJXO88"
 ```
 
-Use one `SnowflakeUidHelper` instance per worker process - `nextId()` returns a URL-safe Base62 string that sorts the same order as the IDs were generated.
+Use one `SnowflakeUidHelper` instance per worker process. `nextId()` returns a URL-safe Base62 string, and it sorts in the same order the IDs were generated.
 
 ## How it works
 
-- **The ID packs three fields into 70 bits.** A 48-bit timestamp (offset from a custom epoch), a 10-bit worker ID (0-1023), and a 12-bit sequence (0-4095) - shifted and OR'd together in `nextSnowflake()`. Sorting the raw bigints, or the Base62 strings, sorts by generation time.
-- **The sequence resets every millisecond, per worker.** Within the same millisecond it increments and wraps at 4096; a wrap forces the generator to busy-wait for the next millisecond, capping throughput at 4,096,000 IDs/second/worker.
-- **Backward clock drift is handled, up to a point.** A drift up to 100ms (`MAX_CLOCK_BACKWARD_MS`) busy-waits until the clock catches up, logging a warning. A larger drift throws instead of risking a duplicate ID.
-- **`encodeBase62` / `decodeBase62` are just a bigint <-> string codec.** They do not know about the Snowflake layout - `parseId()` is `decodeBase62()` followed by the three `extract*` calls, all built on the same instance's `epoch` and bit-shift constants.
-- **An expiry warning logs once the epoch nears its 48-bit limit.** ~8,919 years after the configured epoch the timestamp field overflows; a warning starts logging 10 years before that.
+- **The ID packs three fields into 70 bits.** `nextSnowflake()` shifts and OR's together a timestamp, a worker ID, and a sequence - see the bit layout below.
+- **Sorting the ID sorts by generation time.** This holds for the raw `bigint`, and for the Base62 string.
+- **The sequence resets every millisecond, per worker.** It increments within the millisecond and wraps at 4096.
+- **A wrap forces a busy-wait for the next millisecond.** That caps throughput at 4,096,000 IDs per second per worker.
+- **A small backward clock drift busy-waits.** Up to 100ms (`MAX_CLOCK_BACKWARD_MS`), the generator waits for the clock to catch up, and logs a warning.
+- **A larger drift throws instead.** IGNIS refuses to risk generating a duplicate ID.
+- **`encodeBase62` / `decodeBase62` are a bigint <-> string codec.** They don't know about the Snowflake layout.
+- **`parseId()` layers on top of the codec.** It calls `decodeBase62()`, then the three `extract*` calls, using the same instance's `epoch` and bit-shift constants.
+- **An expiry warning logs once the epoch nears its 48-bit limit.** The timestamp field overflows about 8,919 years after the configured epoch. A warning starts logging 10 years before that.
 
 **Snowflake layout (70 bits)**
 
@@ -47,7 +60,7 @@ Use one `SnowflakeUidHelper` instance per worker process - `nextId()` returns a
 
 ### Generate an ID
 
-`nextId()` is the common case - a Base62 string, 10-12 characters. `nextSnowflake()` returns the raw `bigint` when you need arithmetic or bit-level access.
+`nextId()` is the common case - a Base62 string, 10-12 characters. `nextSnowflake()` returns the raw `bigint`, for arithmetic or bit-level access.
 
 ```typescript
 const id = generator.nextId();               // "9du1sJXO88"
@@ -71,7 +84,7 @@ const sequence = generator.extractSequence(raw);
 
 ### Run one generator per worker in a distributed deployment
 
-Give each process a unique `workerId`; keep `epoch` identical across all of them so ID ordering stays meaningful.
+Give each process a unique `workerId`. Keep `epoch` identical across every process, so ID ordering stays meaningful.
 
 ```typescript
 const generator = new SnowflakeUidHelper({ workerId: Number(process.env.WORKER_ID) });
@@ -89,6 +102,147 @@ try {
 }
 ```
 
+## OpaqueUidHelper
+
+```typescript
+import { OpaqueUidHelper } from '@venizia/ignis-helpers';
+
+const generator = new OpaqueUidHelper({
+  prefix: { enable: true, value: 'INV' },
+  delimiter: { enable: true, value: '-' },
+  length: 6,
+});
+
+generator.nextId();
+// => e.g. "INV-7K2MQ9"
+```
+
+`length` counts the body only. The prefix and the delimiter sit in front of it, so that ID is 10 characters.
+
+### Options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `prefix` | `{ enable, value? }` | disabled | Leads the ID. `value` survives being disabled, so you can toggle it back on |
+| `delimiter` | `{ enable, value? }` | disabled, `_` | Separates prefix from body. Requires a prefix |
+| `length` | `number` | `6` | Characters in the body |
+| `caseForm` | `'upper' \| 'lower' \| 'mixed'` | `'upper'` | Folds the alphabet before sampling |
+| `alphabet` | `string` | `UidAlphabets.CROCKFORD` | The characters to draw from |
+| `exclude` | `string` | `''` | Removed from `alphabet` |
+
+Four alphabets ship with it:
+
+| Alphabet | Size | Drops | Use for |
+|---|---|---|---|
+| `CROCKFORD` | 32 | Lowercase, `I` `L` `O` `U` | IDs a human reads, types, or says aloud |
+| `BASE58` | 58 | `0` `O` `I` `l` | IDs in a URL or a log |
+| `NO_VOWEL` | 50 | `BASE58` plus every vowel | Customer-facing IDs - no word can form |
+| `BASE62` | 62 | Nothing | Machines only |
+
+`getAlphabet()` returns the set actually in use, after the case fold and every exclusion. That is what `length` is measured against, so read it before calculating how many IDs a length affords you.
+
+### Six characters needs a unique index
+
+Six Crockford characters is 2^30 combinations, the size of an airline record locator. That works for airlines because of three things, not because 2^30 is large:
+
+1. **Scoped.** A record locator is unique per carrier, not worldwide.
+2. **Recycled.** The airline reuses it once the trip is over.
+3. **Retried.** The reservation system regenerates on conflict.
+
+> [!WARNING]
+> At the default length, a 1% chance of at least one collision arrives at roughly 4,600 IDs in one space, and 50% at roughly 38,000.
+
+A `prefix` PARTITIONS the space. `INV-7K2MQ9` can never collide with `CUS-7K2MQ9`, so ten entity types get ten separate spaces instead of sharing one. It does not make an ID unique inside its own space - within `INV`, the numbers above still hold.
+
+So do both. Give each entity type its own `prefix`, and put the column behind a unique index.
+
+### Reject an ID you already hold
+
+`nextId()` takes a callback. Return `true` to accept the ID, `false` to draw another.
+
+```typescript
+const issued = new Set<string>();
+const generator = new OpaqueUidHelper({ length: 8 });
+
+const id = generator.nextId({
+  isAvailable: candidate => !issued.has(candidate),
+});
+issued.add(id);
+```
+
+Every argument is optional, including the options object itself - `nextId()` alone is the common case.
+
+**`nextId()` options**
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `prefix` | `string` | The configured prefix | Replaces it for this call |
+| `isAvailable` | `(id: string) => ValueOrPromise<boolean>` | none | `true` accepts, `false` draws again |
+| `maxAttempts` | `number` | `10` | Draws before it throws. Requires `isAvailable` |
+
+The callback sees the finished ID, prefix and delimiter included - the string the column stores.
+
+**The callback's return type decides `nextId`'s.** A synchronous check keeps the call synchronous, so no promise is allocated. An asynchronous one makes it a promise:
+
+```typescript
+const id = generator.nextId({ isAvailable: candidate => !issued.has(candidate) });
+// string
+
+const id = await generator.nextId({
+  isAvailable: async candidate => !(await invoiceRepository.exists(candidate)),
+});
+// Promise<string>
+```
+
+> [!WARNING]
+> An asynchronous check does not make an ID safe. Against a database it is a read and then a write with a gap between them, and another request can take the ID inside that gap. `isAvailable` lowers the collision rate; the unique index is what removes it.
+
+`maxAttempts` bounds the redraws. Repeated rejection means the space is full, and the helper throws with the length and alphabet size rather than looping.
+
+### Regenerate on conflict, never check first
+
+Insert and catch the violation. Checking whether an ID exists and then inserting it leaves a window where another request takes the same ID between the two statements.
+
+```typescript
+import { executeWithRetry, OpaqueUidHelper } from '@venizia/ignis-helpers';
+
+const generator = new OpaqueUidHelper({
+  prefix: { enable: true, value: 'INV' },
+  delimiter: { enable: true, value: '-' },
+});
+
+const invoice = await executeWithRetry({
+  operation: 'createInvoice',
+  maxAttempts: 5,
+  // A fresh ID per attempt - retrying with the same one would collide forever.
+  execution: () => invoiceRepository.create({ data: { id: generator.nextId(), total } }),
+  shouldRetry: context => isUniqueViolation(context.error),
+});
+```
+
+Five attempts is generous. At the default length a second collision on the same insert has a probability in the millionths.
+
+Or raise `length` - every extra character multiplies the space by 32.
+
+### What the constructor refuses
+
+Each of these fails loudly at construction, because each one fails silently at runtime:
+
+| Configuration | Why it is refused |
+|---|---|
+| `delimiter` enabled, `prefix` disabled | The delimiter would lead the ID and separate nothing |
+| A delimiter character that is in the alphabet | The ID could not be split back into prefix and body |
+| A `prefix` that disagrees with `caseForm` | A lowercase prefix on an uppercase ID defeats the reason for choosing one case |
+| `caseForm` folding a two-case alphabet | Uppercasing `BASE58` brings `I` and `O` back - the pair it drops so `1` and `0` stay readable |
+| An alphabet under 16 characters | `exclude` has eaten it |
+| `maxAttempts` passed without `isAvailable` | Nothing rejects a draw, so the retry it configures cannot happen |
+
+### Randomness
+
+`OpaqueUidHelper` draws from `crypto.getRandomValues`, and rejects samples that fall outside the alphabet rather than wrapping them. A `byte % 58` would favour the first 24 characters by about 1.5%, forever, and no caller could see it.
+
+Unlike `crypto.randomUUID`, `getRandomValues` works outside a secure context. The generator runs on a plain-http origin and inside a browser Worker.
+
 ## See also
 
 - [Models](/guides/core-concepts/persistent/models) - using UIDs as primary keys
@@ -100,4 +254,6 @@ try {
 **Files:**
 
 - [`packages/helpers/src/modules/uid/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/uid/helper.ts) - `SnowflakeUidHelper`, `SnowflakeConfig`
+- [`packages/helpers/src/modules/uid/opaque.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/uid/opaque.ts) - `OpaqueUidHelper`
+- [`packages/helpers/src/modules/uid/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/uid/common/constants.ts) - `UidAlphabets`, `UidCaseForms`
 - [`packages/helpers/src/modules/uid/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/uid/index.ts) - module barrel

package/content/extensions/helpers/websocket/api.md

@@ -15,6 +15,19 @@ Exhaustive reference for `WebSocketServerHelper` and `WebSocketEmitter`. For a r
 - [`packages/helpers/src/modules/socket/websocket/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/websocket/common/types.ts) - option, callback, and wire types
 - [`packages/helpers/src/modules/socket/websocket/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/websocket/common/constants.ts) - `WebSocketEvents`, `WebSocketChannels`, `WebSocketDefaults`, `WebSocketMessageTypes`, `WebSocketClientStates`
 
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See every class and its role at a glance | [Quick Reference](#quick-reference) |
+| Follow a connection from upgrade to disconnect | [Client connection lifecycle](#client-connection-lifecycle) |
+| Look up every server constructor option | [`IWebSocketServerOptions`](#iwebsocketserveroptions) |
+| Send to one client, a user, a room, or everyone (same process) | [Server API](#server-api) |
+| Send to clients on any server instance, or publish from a process with no server of its own | [Server API](#server-api) / [Emitter API](#emitter-api) |
+| Look up a wire type, option type, or callback signature | [Types Reference](#types-reference) |
+| Look up an event name, channel, default, or close code | [Constants](#constants) |
+| Debug a stuck, rejected, or cross-instance delivery problem | [Troubleshooting](#troubleshooting) |
+
 ## Quick Reference
 
 | Class | Extends | Role |
@@ -157,7 +170,7 @@ Server A                      Redis                     Server B
 
 - **Duplication.** `WebSocketServerHelper` duplicates its `redisConnection` twice (`redisPub`, `redisSub`); `WebSocketEmitter` duplicates it once (`redisPub` only).
 - **Connection types.** Both single-instance `Redis` and `Cluster` connections from ioredis are supported - the parent helper connection stays independent and unconsumed.
-- **Dedup on receipt.** Every server instance generates a unique `serverId` (UUID) at construction; messages carrying the same `serverId` on receipt are skipped to prevent double delivery to the originating instance.
+- **Dedup on receipt.** Every server instance generates a unique `serverId` (UUID) at construction. A message carrying that same `serverId` on receipt is skipped, so the originating instance never delivers to itself twice.
 
 ## Server API
 
@@ -169,11 +182,20 @@ Server A                      Redis                     Server B
 constructor(opts: IWebSocketServerOptions<AuthDataType, MetadataType>)
 ```
 
-Generates a unique `serverId` (UUID), stores all options with defaults applied, and initializes two duplicated Redis clients (`redisPub`, `redisSub`). Throws `getError({ statusCode: 500, message: '[WebSocketServerHelper] Invalid redis connection!' })` if `redisConnection` is falsy.
+On construction:
+
+- Generates a unique `serverId` (UUID).
+- Stores all options, with defaults applied.
+- Initializes two duplicated Redis clients (`redisPub`, `redisSub`).
+
+Throws `getError({ statusCode: 500, message: '[WebSocketServerHelper] Invalid redis connection!' })` if `redisConnection` is falsy.
 
 #### Generic type parameters
 
-`AuthDataType` types the payload passed to `authenticateFn`/`handshakeFn`; `MetadataType` types the value returned as `metadata` and stored on `IWebSocketClient`. Both default to `Record<string, unknown>`.
+| Type parameter | Types | Default |
+|---|---|---|
+| `AuthDataType` | The payload passed to `authenticateFn`/`handshakeFn` | `Record<string, unknown>` |
+| `MetadataType` | The value returned as `metadata` and stored on `IWebSocketClient` | `Record<string, unknown>` |
 
 ```typescript
 interface AuthPayload { type: string; token: string; publicKey?: string }
@@ -219,7 +241,7 @@ const helper = new WebSocketServerHelper<AuthPayload, UserMetadata>({
 | `handshakeFn` | `TWebSocketHandshakeFn` | No | - | Required when `requireEncryption` is `true`. Returns `{ serverPublicKey, salt }` to accept, `null`/`false` to reject |
 
 - **All callbacks run through `invokeHook()`.** Applies to `authenticateFn`, `validateRoomFn`, `clientConnectedFn`, `clientDisconnectedFn`, `messageHandler`, and `handshakeFn`.
-- **Failures do not crash the process.** A synchronous throw inside a Bun socket handler is caught and logged; rejected promises are logged the same way via `voidExecution`.
+- **Failures do not crash the process.** A synchronous throw inside a Bun socket handler is caught and logged. A rejected promise is logged the same way, via `voidExecution`.
 
 ### `configure()`
 
@@ -253,7 +275,7 @@ Returns the Bun WebSocket handler object. Pass it to `server.reload({ websocket
 #### Bun native configuration
 
 - **`serverOptions` is spread into the returned handler.** `WebSocketServerHelper` only applies its own default for `sendPings`, `idleTimeout`, and `maxPayloadLength`.
-- **Everything else falls through to Bun.** The remaining fields are `undefined` unless you set them, and Bun applies its own runtime default in that case.
+- **Everything else falls through to Bun.** The remaining fields are `undefined` unless you set them. Bun applies its own runtime default in that case.
 
 | Option | Type | Helper default | Description |
 |--------|------|-----------------|--------------|
@@ -306,7 +328,13 @@ Returns every client in `room`; `[]` if the room does not exist or is empty.
 onClientConnect(opts: { clientId: string; socket: IWebSocket }): void
 ```
 
-Handles a new WebSocket connection: creates an `IWebSocketClient` entry with state `UNAUTHORIZED`, subscribes the socket to its own `clientId` topic (Bun native pub/sub), and starts the authentication timeout. Returns early - and logs `'Client already existed'` - if the client ID already exists.
+Handles a new WebSocket connection:
+
+- Creates an `IWebSocketClient` entry with state `UNAUTHORIZED`.
+- Subscribes the socket to its own `clientId` topic (Bun native pub/sub).
+- Starts the authentication timeout.
+
+If the client ID already exists, it returns early and logs `'Client already existed'`.
 
 ### `onClientMessage()`
 
@@ -316,7 +344,8 @@ onClientMessage(opts: { clientId: string; raw: string }): void
 
 Routes an incoming message:
 
-- Parses `raw` as JSON. On failure, sends `{ event: 'error', data: { message: 'Invalid message format' } }` and returns. A message with no `event` field is logged and dropped.
+- Parses `raw` as JSON. On failure, sends `{ event: 'error', data: { message: 'Invalid message format' } }` and returns.
+- A parsed message with no `event` field is logged and dropped.
 - `heartbeat`: consumed silently (`lastActivity` is already updated by the `message` callback before this runs).
 - `authenticate`: delegates to `handleAuthenticate()`.
 - Any other event, when the client is not `AUTHENTICATED`: sends `{ event: 'error', data: { message: 'Not authenticated' } }`.
@@ -329,7 +358,14 @@ Routes an incoming message:
 onClientDisconnect(opts: { clientId: string }): void
 ```
 
-Cleans up a disconnected client: clears the pending auth timer, removes the client from its user's index, removes it from every joined room, removes it from the clients map, then invokes `clientDisconnectedFn`.
+Cleans up a disconnected client:
+
+- Clears the pending auth timer.
+- Removes the client from its user's index.
+- Removes it from every joined room.
+- Removes it from the clients map.
+
+It then invokes `clientDisconnectedFn`.
 
 ### `joinRoom()`
 
@@ -337,7 +373,7 @@ Cleans up a disconnected client: clears the pending auth timer, removes the clie
 joinRoom(opts: { clientId: string; room: string }): void
 ```
 
-Adds `clientId` to the room index and to `client.rooms`, and subscribes the socket to the room's Bun native pub/sub topic - unless the client is encrypted, in which case the subscribe step is skipped (delivery goes through the transformer instead). No-op if the client does not exist.
+Adds `clientId` to the room index and to `client.rooms`, and subscribes the socket to the room's Bun native pub/sub topic. An encrypted client skips the subscribe step - delivery goes through the transformer instead. No-op if the client does not exist.
 
 ### `leaveRoom()`
 
@@ -355,7 +391,10 @@ Removes `clientId` from the room index and from `client.rooms`, and unsubscribes
 - Maximum 256 characters.
 - Cannot start with `ws:` (reserved for the internal Redis channel prefix).
 
-- **Rejection is silent.** If every requested room is filtered out, `validateRoomFn` is not configured, or it resolves to an empty array, the join is rejected and logged - no error is sent back to the client.
+- **Rejection is silent.** No error goes back to the client - the join is only rejected and logged. That happens when:
+  - every requested room is filtered out,
+  - `validateRoomFn` is not configured, or
+  - it resolves to an empty array.
 - **`leave` does not re-filter.** `{ event: 'leave' }` only processes rooms the client is actually a member of (`client.rooms.has(room)`).
 - **Programmatic calls bypass validation.** `joinRoom()`/`leaveRoom()` called directly skip all of the above.
 
@@ -365,7 +404,7 @@ Removes `clientId` from the room index and from `client.rooms`, and unsubscribes
 enableClientEncryption(opts: { clientId: string }): void
 ```
 
-Unsubscribes the client from every Bun native pub/sub topic (the broadcast topic plus all joined rooms) so `server.publish()` no longer reaches it; messages are instead delivered individually through `outboundTransformer`. No-op if the client is already encrypted or does not exist.
+Unsubscribes the client from every Bun native pub/sub topic (the broadcast topic plus all joined rooms), so `server.publish()` no longer reaches it. Messages are instead delivered individually through `outboundTransformer`. No-op if the client is already encrypted or does not exist.
 
 > [!WARNING]
 > Irreversible for the lifetime of the connection. Once a client is encrypted it cannot be switched back to Bun native pub/sub delivery.
@@ -377,7 +416,7 @@ sendToClient(opts: { clientId: string; event: string; data: unknown; doLog?: boo
 ```
 
 - **Local delivery only.**
-- **Encrypted client, `outboundTransformer` configured.** The transformer runs (async) before `socket.send()`; a transformer error is logged and the message is dropped.
+- **Encrypted client, `outboundTransformer` configured.** The transformer runs (async) before `socket.send()`. A transformer error is logged, and the message is dropped.
 - **Otherwise.** Sends `JSON.stringify({ event, data })` directly.
 - **`doLog: true`** emits an info log after delivery.
 
@@ -450,7 +489,7 @@ shutdown(): Promise<void>
 `Source ->` [`emitter/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/websocket/emitter/helper.ts)
 
 - **Role.** A Redis-only publisher for processes with no WebSocket server of their own - background workers, other microservices, cron jobs.
-- **No self-skip.** It always publishes with `serverId: 'emitter'`, so every server instance processes the message; there is no dedup skip on the sending side.
+- **No self-skip.** It always publishes with `serverId: 'emitter'`, so every server instance processes the message. There is no dedup skip on the sending side.
 
 ### Constructor
 

package/content/extensions/helpers/websocket/index.md

@@ -6,7 +6,9 @@ difficulty: intermediate
 
 # WebSocket
 
-A Bun-native WebSocket server with post-connection authentication, rooms, heartbeat, and Redis Pub/Sub for horizontal scaling, plus a Redis-only emitter for publishing to it from other processes.
+A Bun-native WebSocket server with post-connection authentication, rooms, heartbeat, and Redis Pub/Sub for horizontal scaling. A Redis-only emitter sends to it from other processes that run no server of their own.
+
+This helper is the raw class: construct it and wire it into your own server yourself. Need it inside an IGNIS app instead? [`WebSocketComponent`](/extensions/components/websocket/) does that wiring for you. It creates and binds the helper through DI once your app's Bun server is listening.
 
 > [!IMPORTANT]
 > **Bun only.** `WebSocketServerHelper` uses Bun's native WebSocket API and will not run on Node.js. For Node.js, use the [Socket.IO Helper](../socket-io/) instead.
@@ -46,7 +48,7 @@ ws.onopen = () => ws.send(JSON.stringify({ event: 'authenticate', data: { token:
 
 ## How it works
 
-- **Every connection starts unauthenticated.** The WebSocket upgrade always succeeds; the client starts as `UNAUTHORIZED` and must send `{ event: 'authenticate' }` within `authTimeout` (5s default) or get closed with code `4001`.
+- **Every connection starts unauthenticated.** The WebSocket upgrade always succeeds, and the client starts as `UNAUTHORIZED`. It must send `{ event: 'authenticate' }` within `authTimeout` (5s default) or get closed with code `4001`.
 - **`authenticateFn` decides accept or reject.** On success the client is indexed by `userId`, joins `defaultRooms`, and moves to `AUTHENTICATED`.
 - **Delivery has two tiers** - local-only fan-out on this process, or a Redis Pub/Sub layer that also reaches other server instances:
 
@@ -56,7 +58,8 @@ ws.onopen = () => ws.send(JSON.stringify({ event: 'authenticate', data: { token:
 | Cross-instance | `send()`, `WebSocketEmitter` | Clients on any server instance | Redis Pub/Sub, via the server's duplicated `redisPub`/`redisSub` connections |
 
 - **Liveness is passive.** The server never pings clients - they must periodically send `{ event: 'heartbeat' }`. A sweep every `heartbeatInterval` (30s) closes anyone silent for longer than `heartbeatTimeout` (90s) with code `4002`.
-- **Encryption is opt-in per client.** An `outboundTransformer` callback intercepts every outbound message before `socket.send()`. Once a client is encrypted, Bun native pub/sub is bypassed for it - `sendToRoom`/`broadcast` fall back to iterating encrypted clients individually.
+- **Encryption is opt-in per client.** An `outboundTransformer` callback intercepts every outbound message before `socket.send()`.
+- **Once encrypted, delivery changes.** Bun native pub/sub is bypassed for that client. `sendToRoom`/`broadcast` then fall back to iterating encrypted clients individually.
 
 ## Common tasks
 
@@ -96,7 +99,7 @@ helper.broadcast({ event: 'system:announcement', data: { text: 'Maintenance in 5
 
 ### Let clients join rooms
 
-Clients can only join custom rooms when you supply `validateRoomFn` - without it, every join request is rejected by default:
+Clients can only join custom rooms when you supply `validateRoomFn`. Without it, every join request is rejected by default:
 
 ```typescript
 const helper = new WebSocketServerHelper({

package/content/extensions/helpers/worker-thread/index.md

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Worker Thread
 
-The worker-thread helper wraps Node's `worker_threads` with a pooled registry, lifecycle-event helpers, and a `MessagePort` bus for two-way communication between the main thread and a worker.
+The worker-thread helper wraps Node's `worker_threads`. It adds a pooled registry, lifecycle-event helpers, and a `MessagePort` bus for two-way communication between the main thread and a worker.
 
 ## In one example
 
@@ -30,16 +30,20 @@ pool.register({ key: 'image-resizer', worker });
 
 ## How it works
 
-- **Main thread vs worker thread.** Two class families split by side: `BaseWorkerHelper` runs on the main thread and wraps a `Worker` instance; `BaseWorkerThreadHelper` runs inside the spawned worker script and throws `[BaseWorker] Cannot start worker in MAIN_THREAD` if constructed there instead.
+- **Main thread vs worker thread.** Two class families split by side.
+  - `BaseWorkerHelper` runs on the main thread and wraps a `Worker` instance.
+  - `BaseWorkerThreadHelper` runs inside the spawned worker script. It throws `[BaseWorker] Cannot start worker in MAIN_THREAD` if you construct it on the main thread instead.
 - **Pool caps concurrency.** `WorkerPoolHelper` is a lazy singleton (`getInstance()`) that limits registrations to `os.cpus().length`. Past the limit, `register()` returns `false` and logs a warning - it never throws.
-- **Lifecycle hooks, not raw events.** `BaseWorkerHelper` binds `online`, `exit`, `error`, `message`, and `messageerror` once in its constructor. Each has a default logging behavior, overridable per instance via `eventHandlers`. A synchronous throw inside a handler is caught and logged, not left to crash the process.
-- **Two-way messaging via buses.** Inside a worker script, `BaseWorkerThreadHelper` manages named `BaseWorkerBusHelper` instances - each wraps one `MessagePort` - so a single worker can multiplex several independent channels by key.
+- **Lifecycle hooks, not raw events.**
+  - `BaseWorkerHelper` binds `online`, `exit`, `error`, `message`, and `messageerror` once in its constructor. Each has a default logging behavior, overridable per instance via `eventHandlers`.
+  - A synchronous throw inside a handler is caught and logged, not left to crash the process.
+- **Two-way messaging via buses.** Inside a worker script, `BaseWorkerThreadHelper` manages named `BaseWorkerBusHelper` instances, each wrapping one `MessagePort`. A single worker can multiplex several independent channels this way, one per key.
 
 ## Common tasks
 
 ### Look up and message a registered worker
 
-`get()` and `has()` read the pool by key; `size()` reports how many workers are registered.
+`get()` and `has()` read the pool by key. `size()` reports how many workers are registered.
 
 ```typescript
 const worker = pool.get<string>({ key: 'image-resizer' });

package/content/extensions/helpers/worker-thread/reference.md

@@ -18,13 +18,13 @@ Exhaustive reference for the worker-thread classes, every constructor option, ev
 
 ## Quick Reference
 
-| Class | Extends | Use Case |
+| Class | Extends | Use case |
 |-------|---------|----------|
-| `WorkerPoolHelper` | `BaseHelper` | Singleton registry that tracks and limits active worker instances |
-| `BaseWorkerHelper<MessageType>` | `AbstractWorkerHelper<MessageType>` | Wraps a `Worker` with event lifecycle hooks (online, exit, error, message) |
-| `BaseWorkerThreadHelper` | `AbstractWorkerThreadHelper` | Runs inside a worker thread; manages named `WorkerBus` channels |
-| `BaseWorkerBusHelper<IC, IP>` | `AbstractWorkerBusHelper<IC, IP>` | Bidirectional `MessagePort` communication with pre/post hooks |
-| `BaseWorkerMessageBusHandlerHelper<IC>` | `AbstractWorkerMessageBusHandlerHelper<IC>` | Defines event handlers for a worker bus (message, close, error, exit) |
+| [`WorkerPoolHelper`](#workerpoolhelper) | `BaseHelper` | Singleton registry that tracks and limits active worker instances |
+| [`BaseWorkerHelper<MessageType>`](#baseworkerhelper-main-thread-worker-wrapper) | `AbstractWorkerHelper<MessageType>` | Wraps a `Worker` with event lifecycle hooks - online, exit, error, message |
+| [`BaseWorkerThreadHelper`](#baseworkerthreadhelper-inside-a-worker-thread) | `AbstractWorkerThreadHelper` | Runs inside a worker thread. Manages named `WorkerBus` channels |
+| [`BaseWorkerBusHelper<IConsumePayload, IPublishPayload>`](#baseworkerbushelper-messageport-communication) | `AbstractWorkerBusHelper<IConsumePayload, IPublishPayload>` | Bidirectional `MessagePort` communication with pre/post hooks |
+| [`BaseWorkerMessageBusHandlerHelper<IConsumePayload>`](#baseworkermessagebushandlerhelper) | `AbstractWorkerMessageBusHandlerHelper<IConsumePayload>` | Defines event handlers for a worker bus - message, close, error, exit |
 
 | Item | Value |
 |------|-------|
@@ -72,7 +72,7 @@ const customPool = new WorkerPoolHelper({ ignoreMaxWarning: true });
 ```
 
 > [!NOTE]
-> `WorkerPoolHelper.getInstance()` always creates the singleton with `ignoreMaxWarning: false`. To override this behavior, construct a new instance manually - the singleton and a manually-constructed instance are independent registries.
+> `WorkerPoolHelper.getInstance()` always creates the singleton with `ignoreMaxWarning: false`. To override this, construct a new instance manually. The singleton and a manually-constructed instance are independent registries.
 
 ### Constructor options
 
@@ -85,7 +85,7 @@ const customPool = new WorkerPoolHelper({ ignoreMaxWarning: true });
 | Method | Signature | Description |
 |--------|-----------|-------------|
 | `getInstance` | `static getInstance(): WorkerPoolHelper` | Returns the singleton pool instance (creates one with `ignoreMaxWarning: false` if needed) |
-| `register` | `register<MessageType>(opts: { key: string; worker: IWorker<MessageType> }): boolean` | Adds a worker to the pool. Returns `false` and logs instead of registering if the key already exists or the pool is at the CPU limit |
+| `register` | `register<MessageType>(opts: { key: string; worker: IWorker<MessageType> }): boolean` | Adds a worker to the pool. Returns `false` and logs, without registering, if the key exists or the pool is full |
 | `unregister` | `async unregister(opts: { key: string }): Promise<void>` | Terminates the worker (`worker.terminate()`) and removes it from the pool. The registry entry is deleted even if termination throws |
 | `get` | `get<MessageType>(opts: { key: string }): IWorker<MessageType> \| undefined` | Retrieves a registered worker by key |
 | `has` | `has(opts: { key: string }): boolean` | Checks if a worker is registered under the given key |
@@ -138,9 +138,9 @@ const worker = new BaseWorkerHelper<MyMessageType>({
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `binding` | `binding(): void` | Binds all five event handlers (`online`, `exit`, `error`, `message`, `messageerror`) to the internal `Worker` instance. Called automatically by the constructor. Throws `[binding] Invalid worker instance to bind event handlers` if `this.worker` is falsy |
+| `binding` | `binding(): void` | Binds all five event handlers to the internal `Worker` instance. Called automatically by the constructor. Throws `[binding] Invalid worker instance to bind event handlers` if `this.worker` is falsy |
 
-Every handler runs through `invokeHook`, which wraps the call in a `try/catch`: a synchronous throw inside a user handler is caught and logged (`"Hook execution FAILED | Error: %s"`) rather than crashing the process. Async rejections are settled the same way via `voidExecution`.
+Every handler runs through `invokeHook`, which wraps the call in a `try/catch`. A synchronous throw inside a user handler is caught and logged as `"Hook execution FAILED | Error: %s"`, rather than crashing the process. Async rejections are settled the same way, via `voidExecution`.
 
 ### AbstractWorkerHelper (subclassing)
 
@@ -155,7 +155,7 @@ class CustomWorker extends AbstractWorkerHelper<MyMessage> {
   }
 
   onExit(opts: { code: string | number }) {
-    // Custom exit handling, e.g., restart logic
+    // Custom exit handling - for example, restart logic
   }
 
   onError(opts: { error: Error }) {
@@ -172,13 +172,13 @@ class CustomWorker extends AbstractWorkerHelper<MyMessage> {
 }
 ```
 
-`AbstractWorkerHelper<MessageType>` declares `worker: Worker`, `options: WorkerOptions`, and the five abstract lifecycle methods above; it does not implement `binding()` itself.
+`AbstractWorkerHelper<MessageType>` declares `worker: Worker`, `options: WorkerOptions`, and the five abstract lifecycle methods above. It does not implement `binding()` itself.
 
 ## BaseWorkerThreadHelper (inside a worker thread)
 
 `Source ->` [`base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/worker-thread/base.ts)
 
-Used inside a worker script to manage named communication buses. Must be instantiated from within a worker thread - constructing it on the main thread throws.
+Used inside a worker script to manage named communication buses. Must be instantiated from within a worker thread. Constructing it on the main thread throws.
 
 ```typescript
 // Inside worker-script.js
@@ -203,7 +203,7 @@ The constructor checks `isMainThread` (from `node:worker_threads`) and throws `[
 | `unbindWorkerBus` | `unbindWorkerBus(opts: { key: string }): void` | Calls `port.removeAllListeners()` on the bus's port, then deletes it from the registry. Logs a warning if the key is not found |
 | `getWorkerBus` | `getWorkerBus<IC, IP>(opts: { key: string }): IWorkerBus<IC, IP>` | Returns the bus for the given key. Throws `[getWorkerBus] Not found worker bus | key: {key}` if not found |
 
-`unbindWorkerBus` is defined only on `BaseWorkerThreadHelper`, not on the `AbstractWorkerThreadHelper` interface - `AbstractWorkerThreadHelper` declares `buses`, `bindWorkerBus`, and `getWorkerBus` as abstract.
+`unbindWorkerBus` is defined only on `BaseWorkerThreadHelper`, not on the `AbstractWorkerThreadHelper` interface. `AbstractWorkerThreadHelper` declares `buses`, `bindWorkerBus`, and `getWorkerBus` as abstract members only.
 
 ## BaseWorkerMessageBusHandlerHelper
 
@@ -259,17 +259,17 @@ const bus = new BaseWorkerBusHelper<IncomingMessage, OutgoingMessage>({
 | `port` | `MessagePort` | - | The `MessagePort` to bind for communication. Required. |
 | `busHandler` | `IWorkerMessageBusHandler<IConsumePayload>` | - | Handler that receives incoming messages and lifecycle events. Required. |
 
-The constructor binds `message`, `error`, `messageerror`, `exit`, and `close` listeners on `port`, each routed through the handler's matching callback (`error` and `messageerror` both call `handler.onError`).
+The constructor binds `message`, `error`, `messageerror`, `exit`, and `close` listeners on `port`. Each routes to the handler's matching callback. `error` and `messageerror` both route to `handler.onError`.
 
 ### Methods
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `postMessage` | `postMessage(opts: { message: IPublishPayload; transferList: readonly Transferable[] \| undefined }): ValueOrPromise<void>` | Sends a message through the port. If `transferList` is provided, calls `port.postMessage(message, [...transferList])`; otherwise `port.postMessage(message)`. Logs and returns (does not throw) if `port` is falsy |
+| `postMessage` | `postMessage(opts: { message: IPublishPayload; transferList: readonly Transferable[] \| undefined }): ValueOrPromise<void>` | Sends a message through the port. Calls `port.postMessage(message, [...transferList])` if `transferList` is set, otherwise `port.postMessage(message)`. Logs and returns, without throwing, if `port` is falsy |
 
 ### Pre/post message hooks
 
-`onBeforePostMessage` and `onAfterPostMessage` are optional properties declared on the class but left `undefined` by the constructor - assign them after construction:
+`onBeforePostMessage` and `onAfterPostMessage` are optional properties declared on the class. The constructor leaves them `undefined`. Assign them yourself, after construction:
 
 ```typescript
 bus.onBeforePostMessage = opts => {
@@ -281,7 +281,7 @@ bus.onAfterPostMessage = opts => {
 };
 ```
 
-`postMessage` invokes `onBeforePostMessage` (if set) before the port write and `onAfterPostMessage` (if set) after, both through the same `try/catch`-wrapped `invokeHook` used for the port event listeners.
+`postMessage` invokes `onBeforePostMessage` before the port write, if set. It invokes `onAfterPostMessage` after the write, if set. Both hooks run through the same `try/catch`-wrapped `invokeHook` used for the port event listeners.
 
 ### Sending transferable objects
 
@@ -390,9 +390,9 @@ const bus = thread.getWorkerBus({ key: 'my-bus' });
 
 ### "Failed to post message to main | Invalid parentPort!"
 
-**Cause:** `BaseWorkerBusHelper.postMessage()` was called but the `port` property is falsy. This typically means the bus was constructed with an invalid `MessagePort`. This is logged at error level, not thrown - the message is silently dropped.
+**Cause:** `BaseWorkerBusHelper.postMessage()` was called but the `port` property is falsy. This typically means the bus was constructed with an invalid `MessagePort`. This is logged at error level, not thrown. The message is silently dropped.
 
-**Fix:** Ensure a valid `MessagePort` (e.g., `parentPort` from `node:worker_threads` or a port from `new MessageChannel()`) is passed to the constructor:
+**Fix:** Ensure a valid `MessagePort` is passed to the constructor - for example `parentPort` from `node:worker_threads`, or a port from `new MessageChannel()`:
 
 ```typescript
 import { parentPort } from 'node:worker_threads';