spooder 5.1.12 → 6.0.0

package/README.md

@@ -38,14 +38,16 @@ Below is a full map of the available configuration options in their default stat
 	"spooder": {
 
 		// see CLI > Usage
-		"run": "bun run index.ts",
+		"run": "",
 		"run_dev": "",
 
 		// see CLI > Auto Restart
-		"auto_restart": true,
-		"auto_restart_max": 30000,
-		"auto_restart_attempts": 10,
-		"auto_restart_grace": 30000,
+		"auto_restart": {
+			"enabled": false,
+			"backoff_max": 300000,
+			"backoff_grace": 30000,
+			"max_attempts": -1
+		},
 
 		// see CLI > Auto Update
 		"update": [
@@ -55,6 +57,7 @@ Below is a full map of the available configuration options in their default stat
 
 		// see CLI > Canary
 		"canary": {
+			"enabled": false,
 			"account": "",
 			"repository": "",
 			"labels": [],
@@ -79,6 +82,7 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 - [CLI > Dev Mode](#cli-dev-mode)
 - [CLI > Auto Restart](#cli-auto-restart)
 - [CLI > Auto Update](#cli-auto-update)
+- [CLI > Instancing](#cli-instancing)
 - [CLI > Canary](#cli-canary)
 	- [CLI > Canary > Crash](#cli-canary-crash)
 	- [CLI > Canary > Sanitization](#cli-canary-sanitization)
@@ -90,6 +94,7 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 
 - [API > Cheatsheet](#api-cheatsheet)
 - [API > Logging](#api-logging)
+- [API > IPC](#api-ipc)
 - [API > HTTP](#api-http)
 	- [API > HTTP > Directory Serving](#api-http-directory)
 	- [API > HTTP > Server-Sent Events (SSE)](#api-http-sse)
@@ -122,7 +127,7 @@ cd /var/www/my-website-about-fish.net/
 spooder
 ```
 
-`spooder` will launch your server either by executing the `run` command provided in the configuration, or by executing `bun run index.ts` by default.
+`spooder` will launch your server either by executing the `run` command provided in the configuration. If this is not defined, an error will be thrown.
 
 ```json
 {
@@ -155,7 +160,7 @@ The following differences will be observed when running in development mode:
 
 - If `run_dev` is configured, it will be used instead of the default `run` command.
 - Update commands defined in `spooder.update` will not be executed when starting a server.
-- If the server crashes and `auto_restart` is enabled, the server will not be restarted, and spooder will exit with the same exit code as the server.
+- If the server crashes and `auto_restart` is configured, the server will not be restarted, and spooder will exit with the same exit code as the server.
 - If canary is configured, reports will not be dispatched to GitHub and instead be printed to the console; this includes crash reports.
 
 It is possible to detect in userland if a server is running in development mode by checking the `SPOODER_ENV` environment variable.
@@ -188,27 +193,35 @@ You can configure a different command to run when in development mode using the
 > [!NOTE]
 > This feature is not enabled by default.
 
-In the event that the server process exits with a non-zero exit code, `spooder` can automatically restart it using an exponential backoff strategy. To enable this feature set `auto_restart` to `true` in the configuration.
+In the event that the server process exits, `spooder` can automatically restart it.
+
+If the server exits with a non-zero exit code, this will be considered an **unexpected shutdown**. The process will be restarted using an [exponential backoff strategy](https://en.wikipedia.org/wiki/Exponential_backoff).
 
 ```json
 {
 	"spooder": {
-		"auto_restart": true,
-		"auto_restart_max": 30000,
-		"auto_restart_attempts": 10,
-		"auto_restart_grace": 30000
+		"auto_restart": {
+			"enabled": true,
+
+			// max restarts before giving up
+			"max_attempts": -1, // default (unlimited)
+
+			// max delay (ms) between restart attempts
+			"backoff_max": 300000, // default 5 min
+
+			// grace period after which the backoff protocol
+			"backoff_grace": 30000 // default 30s
+		}
 	}
 }
 ```
 
-### Configuration Options
+If the server exits with a `0` exit code, this will be considered an **intentional shutdown** and `spooder` will execute the update commands before restarting the server.
 
-- **`auto_restart`** (boolean, default: `false`): Enable or disable the auto-restart feature
-- **`auto_restart_max`** (number, default: `30000`): Maximum delay in milliseconds between restart attempts
-- **`auto_restart_attempts`** (number, default: `-1`): Maximum number of restart attempts before giving up. Set to `-1` for unlimited attempts
-- **`auto_restart_grace`** (number, default: `30000`): Period of time after which the backoff protocol disables if the server remains stable.
+> [!TIP]
+> An **intentional shutdown** can be useful for auto-updating in response to events, such as webhooks.
 
-If the server exits with a zero exit code (successful termination), auto-restart will not trigger.
+If the server exits with `42` (SPOODER_AUTO_RESTART), the update commands will **not** be executed before starting the server. [See Auto Update for information](#cli-auto-update).
 
 <a id="cli-auto-update"></a>
 ## CLI > Auto Update
@@ -238,22 +251,106 @@ Each command should be a separate entry in the array and will be executed in seq
 
 If a command in the sequence fails, the remaining commands will not be executed, however the server will still be started. This is preferred over entering a restart loop or failing to start the server at all.
 
-You can utilize this to automatically update your server in response to a webhook by exiting the process.
+You can combine this with [Auto Restart](#cli-auto-restart) to automatically update your server in response to a webhook by exiting the process.
 
 ```ts
 server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
 	setImmediate(async () => {
 		await server.stop(false);
-		process.exit();
+		process.exit(0);
 	});
 	return HTTP_STATUS_CODE.OK_200;
 });
 ```
 
+### Multi-Instance Auto Update
+
+See [Instancing](#cli-instancing) for instructions on how to use [Auto Update](#cli-auto-update) with multiple instances.
+
 ### Skip Updates
 
 In addition to being skipped in [dev mode](#cli-dev-mode), updates can also be skipped in production mode by passing the `--no-update` flag.
 
+<a id="cli-instancing"></a>
+## CLI > Instancing
+
+> [!NOTE]
+> This feature is not enabled by default.
+
+By default, `spooder` will start and manage a single process as defined by the `run` and `run_dev` configuration properties. In some scenarios, you may want multiple processes for a single codebase, such as variant sub-domains.
+
+This can be configured in `spooder` using the `instances` array, with each entry defining a unique instance.
+
+```json
+"spooder": {
+	"instances": [
+		{
+			"id": "dev01",
+			"run": "bun run --env-file=.env.a index.ts",
+			"run_dev": "bun run --env-file=.env.a.dev index.ts --inspect"
+		},
+		{
+			"id": "dev02",
+			"run": "bun run --env-file=.env.b index.ts",
+			"run_dev": "bun run --env-file=.env.b.dev index.ts --inspect"
+		}
+	]
+}
+```
+
+Instances will be managed individually in the same manner that a single process would be, including auto-restarting and other functionality.
+
+### Instance Stagger
+
+By default, instances are all launched instantly. This behavior can be configured with the `instance_stagger_interval` configuration property, which defines an interval between instance launches in milliseconds.
+
+This interval effects both server start-up, auto-restarting and crash recovery. No two instances will be launched within that interval regardless of the reason.
+
+### Canary
+
+The [canary](#cli-canary) feature functions the same for multiple instances as it would for a single instance with the caveat that the `instance` object as defined in the configuration is included in the crash report for diagnostics.
+
+This allows you to define custom properties on the instance which will be included as part of the crash report.
+
+```json
+{
+	"id": "dev01",
+	"run": "bun run --env-file=.env.a index.ts",
+	"sub_domain": "dev01.spooder.dev" // custom, for diagnostics
+}
+```
+
+> ![IMPORTANT]
+> You should not include sensitive or confidential credentials in your instance configuration for this reason. This should always be handled using environment variables or credential storage.
+
+### Multi-instance Auto Restart
+
+Combining [Auto Restart](#cli-auto-restart) and [Auto Update](#cli-auto-update), when a server process exits with a zero exit code, the update commands will be run as the server restarts. This is suitable for a single-instance setup.
+
+In the event of multiple instances, this does not work. One server instance would receive the webhook and exit, resulting in the update commands being run and that instance being restarted, leaving the other instances still running.
+
+A solution might be to send the web-hook to every instance, but now each instance is going to restart individually, running the update commands unnecessarily and, if at the same time, causing conflicts. In addition, the concept of multiple instances in spooder is that they operate from a single codebase, which makes sending multiple webhooks a challenge - so don't do this.
+
+The solution is to the use the [IPC](#api-ipc) to instruct the host process to handle this.
+
+```ts
+server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
+	setImmediate(async () => {
+		ipc_send(IPC_TARGET.SPOODER, IPC_OP.CMSG_TRIGGER_UPDATE);
+	});
+	return HTTP_STATUS_CODE.OK_200;
+});
+
+ipc_register(IPC_OP.SMSG_UPDATE_READY, async () => {
+	await server.stop(false);
+	process.exit(EXIT_CODE.SPOODER_AUTO_UPDATE);
+});
+```
+
+In this scenario, we instruct the host process from one instance receiving the webhook to apply the updates. Once the update commands have been run, all instances are send the `SMSG_UPDATE_READY` event, indicating they can restart.
+
+Exiting with the `SPOODER_AUTO_UPDATE` exit code instructs spooder that we're exiting as part of this process, and prevents auto-update from running on restart.
+
 <a id="cli-canary"></a>
 ## CLI > Canary
 
@@ -291,6 +388,7 @@ Each server that intends to use the canary feature will need to have the private
 ```json
 "spooder": {
 	"canary": {
+		"enabled": true,
 		"account": "<GITHUB_ACCOUNT_NAME>",
 		"repository": "<GITHUB_REPOSITORY>",
 		"labels": ["some-label"]
@@ -537,12 +635,30 @@ caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>;
 panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>;
 safe(fn: Callable): Promise<void>;
 
-// worker
-worker_event_pipe(worker: Worker, options?: WorkerEventPipeOptions): WorkerEventPipe;
-pipe.send(id: string, data?: object): void;
-pipe.on(event: string, callback: (data: object) => void | Promise<void>): void;
-pipe.once(event: string, callback: (data: object) => void | Promise<void>): void;
-pipe.off(event: string): void;
+// worker (main thread)
+worker_pool(options: WorkerPoolOptions): Promise<WorkerPool>;
+pool.id: string;
+pool.send: (peer: string, id: string, data?: WorkerMessageData) => void;
+pool.broadcast: (id: string, data?: WorkerMessageData) => void;
+pool.on: (event: string, callback: (message: WorkerMessage) => Promise<void> | void) => void;
+pool.once: (event: string, callback: (message: WorkerMessage) => Promise<void> | void) => void;
+pool.off: (event: string) => void;
+
+type WorkerPoolOptions = {
+	id?: string;
+	worker: string | string[];
+	size?: number;
+	auto_restart?: boolean | AutoRestartConfig;
+};
+
+type AutoRestartConfig = {
+	backoff_max?: number; // default: 5 * 60 * 1000 (5 min)
+	backoff_grace?: number; // default: 30000 (30 seconds)
+	max_attempts?: number; // default: 5, -1 for unlimited
+};
+
+// worker (worker thread)
+worker_connect(peer_id?: string): WorkerPool;
 
 // templates
 Replacements = Record<string, string | Array<string> | object | object[]> | ReplacerFn | AsyncReplaceFn;
@@ -604,10 +720,19 @@ cache.request(req: Request, cache_key: string, content_generator: () => string |
 
 // utilities
 filesize(bytes: number): string;
+BiMap: class BiMap<K, V>;
+
+// ipc
+ipc_register(op: number, callback: IPC_Callback);
+ipc_send(target: string, op: number, data?: object);
 
 // constants
 HTTP_STATUS_TEXT: Record<number, string>;
 HTTP_STATUS_CODE: { OK_200: 200, NotFound_404: 404, ... };
+EXIT_CODE: Record<string, number>;
+EXIT_CODE_NAMES: Record<number, string>;
+IPC_TARGET: Record<string, string>;
+IPC_OP: Record<string, number>;
 ```
 
 <a id="api-logging"></a>
@@ -667,6 +792,60 @@ log(`Fruit must be one of ${fruit.map(e => `{${e}}`).join(', ')}`);
 log(`Fruit must be one of ${log_list(fruit)}`);
 ```
 
+<a id="api-ipc"></a>
+## API > IPC
+
+`spooder` provides a way to send/receive messages between different instances via IPC. See [CLI > Instancing](#cli-instancing) for documentation on instances.
+
+```ts
+// listen for a message
+ipc_register(0x1, msg => {
+	// msg.peer, msg.op, msg.data
+	console.log(msg.data.foo); // 42
+});
+
+// send a message to dev02
+ipc_send('dev02', 0x1, { foo: 42 });
+
+// send a message to all other instances
+ipc_send(IPC_TARGET.BROADCAST, 0x1, { foo: 42 });
+```
+
+This can also be used to communicate with the host process for certain functionality, such as [auto-restarting](#cli-auto-restart).
+
+#### OpCodes
+
+When sending/receiving IPC messages, the message will include an opcode. When communicating with the host process, that will be one of the following:
+
+```ts
+IPC_OP.CMSG_TRIGGER_UPDATE = -1;
+IPC_OP.SMSG_UPDATE_READY = -2;
+IPC_OP.CMSG_REGISTER_LISTENER = -3; // used internally by ipc_register
+```
+
+When sending/receiving your own messages, you can define and use your own ID schema. To prevent conflict with internal opcodes, always use positive values; `spooder` internal opcodes will always be negative.
+
+### `ipc_register(op: number, callback: IPC_Callback)`
+
+Register a listener for IPC events. The callback will receive an object with this structure:
+
+```ts
+type IPC_Message = {
+	op: number; // opcode received
+	peer: string; // sender
+	data?: object // payload data (optional)
+};
+```
+
+### `ipc_send(peer: string, op: number, data?: object)`
+
+Send an IPC event. The target can either be the ID of another instance (such as the `peer` ID from an `IPC_Message`) or one of the following constants.
+
+```ts
+IPC_TARGET.SPOODER; // communicate with the host
+IPC_TARGET.BROADCAST; // broadcast to all other instances
+```
+
 <a id="api-http"></a>
 ## API > HTTP
 
@@ -1688,78 +1867,251 @@ await safe(() => {
 <a id="api-workers"></a>
 ## API > Workers
 
-### 🔧 `worker_event_pipe(worker: Worker, options?: WorkerEventPipeOptions): WorkerEventPipe`
+### 🔧 `worker_pool(options: WorkerPoolOptions): Promise<WorkerPool>` (Main Thread)
 
-Create an event-based communication pipe between host and worker processes. This function works both inside and outside of workers and provides a simple event system on top of the native `postMessage` API.
+Create a worker pool with an event-based communication system between the main thread and one or more workers. This provides a networked event system on top of the native `postMessage` API.
 
 ```ts
-// main thread
-const worker = new Worker('./some_file.ts');
-const pipe = worker_event_pipe(worker);
+// with a single worker (id defaults to 'main')
+const pool = await worker_pool({
+	worker: './worker.ts'
+});
+
+// with multiple workers and custom ID
+const pool = await worker_pool({
+	id: 'main',
+	worker: ['./worker_a.ts', './worker_b.ts']
+});
 
-pipe.on('bar', data => console.log('Received from worker:', data));
-pipe.send('foo', { x: 42 });
+// spawn multiple instances of the same worker
+const pool = await worker_pool({
+	worker: './worker.ts',
+	size: 5 // spawns 5 instances
+});
+
+// with custom response timeout
+const pool = await worker_pool({
+	worker: './worker.ts',
+	response_timeout: 10000 // 10 seconds (default: 5000ms, use -1 to disable)
+});
 
+// with auto-restart enabled (boolean)
+const pool = await worker_pool({
+	worker: './worker.ts',
+	auto_restart: true // uses default settings
+});
+
+// with custom auto-restart configuration
+const pool = await worker_pool({
+	worker: './worker.ts',
+	auto_restart: {
+		backoff_max: 5 * 60 * 1000, // 5 min (default)
+		backoff_grace: 30000, // 30 seconds (default)
+		max_attempts: 5 // -1 for unlimited (default: 5)
+	}
+});
+```
+
+### 🔧 `worker_connect(peer_id?: string, response_timeout?: number): WorkerPool` (Worker Thread)
+
+Connect a worker thread to the worker pool. This should be called from within a worker thread to establish communication with the main thread and other workers.
+
+**Parameters:**
+- `peer_id` - Optional worker ID (defaults to `worker-UUID`)
+- `response_timeout` - Optional timeout in milliseconds for request-response patterns (default: 5000ms, use -1 to disable)
+
+```ts
 // worker thread
-import { worker_event_pipe } from 'spooder';
+const pool = worker_connect('my_worker'); // defaults to worker-UUID, 5000ms timeout
+pool.on('test', msg => {
+	console.log(`Received ${msg.data.foo} from ${msg.peer}`);
+});
+
+// with custom timeout
+const pool = worker_connect('my_worker', 10000); // 10 second timeout
+const pool = worker_connect('my_worker', -1); // no timeout
+```
+
+### Basic Usage
+
+```ts
+// main thread
+const pool = await worker_pool({
+	id: 'main',
+	worker: './worker.ts'
+});
 
-const pipe = worker_event_pipe(globalThis as unknown as Worker);
+pool.send('my_worker', 'test', { foo: 42 });
 
-pipe.on('foo', data => {
-	console.log('Received from main:', data); // { x: 42 }
-	pipe.send('bar', { response: 'success' });
+// worker thread (worker.ts)
+const pool = worker_connect('my_worker');
+pool.on('test', msg => {
+	console.log(`Received ${msg.data.foo} from ${msg.peer}`);
+	// > Received 42 from main
 });
 ```
 
-### WorkerEventPipeOptions
+### Cross-Worker Communication
 
-The second parameter of `worker_event_pipe` accepts an object of options.
+```ts
+// main thread
+const pool = await worker_pool({
+	id: 'main',
+	worker: ['./worker_a.ts', './worker_b.ts']
+});
 
-Currently the only available option is `use_canary_reporting`. If enabled, the event pipe will call `caution()` when it encounters errors such as malformed payloads.
+pool.send('worker_a', 'test', { foo: 42 }); // send to just worker_a
+pool.broadcast('test', { foo: 50 } ); // send to all workers
 
-### 🔧 `pipe.send(id: string, data?: object): void`
+// worker_a.ts
+const pool = worker_connect('worker_a');
+// send from worker_a to worker_b
+pool.send('worker_b', 'test', { foo: 500 });
+```
+
+### 🔧 `pool.send(peer: string, id: string, data?: Record<string, any>, expect_response?: boolean): void | Promise<WorkerMessage>`
+
+Send a message to a specific peer in the pool, which can be the main host or another worker.
 
-Send a message to the other side of the worker pipe with the specified event ID and optional data payload.
+When `expect_response` is `false` (default), the function returns `void`. When `true`, it returns a `Promise<WorkerMessage>` that resolves when the peer responds using `pool.respond()`.
 
 ```ts
-pipe.send('user_update', { user_id: 123, name: 'John' });
-pipe.send('simple_event'); // data defaults to {}
+// Fire-and-forget (default behavior)
+pool.send('main', 'user_update', { user_id: 123, name: 'John' });
+pool.send('worker_b', 'simple_event');
+
+// Request-response pattern
+const response = await pool.send('worker_b', 'calculate', { value: 42 }, true);
+console.log('Result:', response.data);
 ```
 
-### 🔧 `pipe.on(event: string, callback: (data: object) => void | Promise<void>): void`
+> [!NOTE]
+> When using `expect_response: true`, the promise will reject with a timeout error if no response is received within the configured timeout (default: 5000ms). You can configure this timeout in `worker_pool()` options or `worker_connect()` parameters, or disable it entirely by setting it to `-1`.
 
-Register an event handler for messages with the specified event ID. The callback can be synchronous or asynchronous.
+### 🔧 `pool.broadcast(id: string, data?: Record<string, any>): void`
+
+Broadcast a message to all peers in the pool.
 
 ```ts
-pipe.on('process_data', async (data) => {
-	const result = await processData(data);
-	pipe.send('data_processed', { result });
-});
+pool.broadcast('test_event', { foo: 42 });
+```
+
+### 🔧 `pool.on(event: string, callback: (data: Record<string, any>) => void | Promise<void>): void`
 
-pipe.on('log_message', (data) => {
-	console.log(data.message);
+Register an event handler for messages with the specified event ID. The callback can be synchronous or asynchronous.
+
+```ts
+pool.on('process_data', async msg => {
+	// msg.peer
+	// msg.id
+	// msg.data
 });
 ```
 
 > [!NOTE]
 > There can only be one event handler for a specific event ID. Registering a new handler for an existing event ID will overwrite the previous handler.
 
-### 🔧 `pipe.once(event: string, callback: (data: object) => void | Promise<void>): void`
+### 🔧 `pool.once(event: string, callback: (data: Record<string, any>) => void | Promise<void>): void`
 
-Register an event handler for messages with the specified event ID. This is the same as `pipe.on`, except the handler is automatically removed once it is fired.
+Register an event handler for messages with the specified event ID. This is the same as `pool.on`, except the handler is automatically removed once it is fired.
 
 ```ts
-pipe.once('one_time_event', async (data) => {
+pool.once('one_time_event', async msg => {
 	// this will only fire once
 });
 ```
 
-### 🔧 `pipe.off(event: string): void`
+### 🔧 `pool.off(event: string): void`
 
 Unregister an event handler for events with the specified event ID.
 
 ```ts
-pipe.off('event_name');
+pool.off('event_name');
+```
+
+### 🔧 `pool.respond(message: WorkerMessage, data?: Record<string, any>): void`
+
+Respond to a message that was sent with `expect_response: true`. This allows implementing request-response patterns between peers.
+
+```ts
+pool.on('calculate', msg => {
+	const result = msg.data.value * 2;
+	pool.respond(msg, { result });
+});
+
+const response = await pool.send('worker_a', 'calculate', { value: 42 }, true);
+console.log(response.data.result); // 84
+```
+
+**Message Structure:**
+- `message.id` - The event ID
+- `message.peer` - The sender's peer ID
+- `message.data` - The message payload
+- `message.uuid` - Unique identifier for this message
+- `message.response_to` - UUID of the message being responded to (only present in responses)
+
+### Request-Response Example
+
+```ts
+// main.ts
+const pool = await worker_pool({
+	id: 'main',
+	worker: './worker.ts'
+});
+
+const response = await pool.send('worker_a', 'MSG_REQUEST', { value: 42 }, true);
+console.log(`Got response ${response.data.value} from ${response.peer}`);
+
+// worker.ts
+const pool = worker_connect('worker_a');
+
+pool.on('MSG_REQUEST', msg => {
+	console.log(`Received request with value: ${msg.data.value}`);
+	pool.respond(msg, { value: msg.data.value * 2 });
+});
+```
+
+### Auto-Restart
+
+The `worker_pool` function supports automatic worker restart when workers crash or close unexpectedly. This feature includes an exponential backoff protocol to prevent restart loops.
+
+#### Configuration:
+- `auto_restart`: `boolean | AutoRestartConfig` - Enable auto-restart (optional)
+  - If `true`, uses default settings
+  - If an object, allows customization of restart behavior
+
+#### AutoRestartConfig
+- `backoff_max`: `number` - Maximum delay between restart attempts in milliseconds (default: `5 * 60 * 1000` = 5 minutes)
+- `backoff_grace`: `number` - Time in milliseconds a worker must run successfully before restart attempts are reset (default: `30000` = 30 seconds)
+- `max_attempts`: `number` - Maximum number of restart attempts before giving up (default: `5`, use `-1` for unlimited)
+
+#### Backoff Protocol
+1. Initial restart delay starts at 100ms
+2. Each subsequent restart doubles the delay
+3. Delay is capped at `backoff_max`
+4. If a worker runs successfully for `backoff_grace` milliseconds, the delay and attempt counter reset
+5. After `max_attempts` failures, auto-restart stops for that worker
+
+**Example:**
+```ts
+const pool = await worker_pool({
+	worker: './worker.ts',
+	auto_restart: {
+		backoff_max: 5 * 60 * 1000, // cap at 5 minutes
+		backoff_grace: 30000, // reset after 30 seconds of successful operation
+		max_attempts: 5 // give up after 5 failed attempts
+	}
+});
+```
+
+#### Graceful Exit
+
+Workers can exit gracefully without triggering an auto-restart by using the `WORKER_EXIT_NO_RESTART` exit code (42):
+
+```ts
+// worker thread
+import { WORKER_EXIT_NO_RESTART } from 'spooder';
+process.exit(WORKER_EXIT_NO_RESTART); // exits without auto-restart
 ```
 
 > [!IMPORTANT]
@@ -2710,6 +3062,37 @@ filesize(1073741824); // > "1 gb"
 filesize(1099511627776); // > "1 tb"
 ```
 
+### 🔧 ``BiMap<K, V>``
+
+A bidirectional map that maintains a two-way relationship between keys and values, allowing efficient lookups in both directions.
+
+```ts
+const users = new BiMap<number, string>();
+
+// Set key-value pairs
+users.set(1, "Alice");
+users.set(2, "Bob");
+users.set(3, "Charlie");
+
+// Lookup by key
+users.getByKey(1); // > "Alice"
+
+// Lookup by value
+users.getByValue("Bob"); // > 2
+
+// Check existence
+users.hasKey(1); // > true
+users.hasValue("Charlie"); // > true
+
+// Delete by key or value
+users.deleteByKey(1); // > true
+users.deleteByValue("Bob"); // > true
+
+// Other operations
+users.size; // > 1
+users.clear();
+```
+
 ## Legal
 This software is provided as-is with no warranty or guarantee. The authors of this project are not responsible or liable for any problems caused by using this software or any part thereof. Use of this software does not entitle you to any support or assistance from the authors of this project.