spooder 5.1.12 → 6.1.0

package/README.md

@@ -10,6 +10,9 @@
 
 The design goal behind `spooder` is not to provide a full-featured web server, but to expand the Bun runtime with a set of APIs and utilities that make it easy to develop servers with minimal overhead.
 
+### spooderverse
+In addition to the core API provided here, you can also find [spooderverse](https://github.com/Kruithne/spooderverse) which is a collection of drop-in modules designed for spooder with minimal overhead and zero dependencies.
+
 > [!NOTE]
 > If you think a is missing a feature, consider opening an issue with your use-case. The goal behind `spooder` is to provide APIs that are useful for a wide range of use-cases, not to provide bespoke features better suited for userland.
 
@@ -38,14 +41,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 +60,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 +85,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 +97,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)
@@ -103,10 +111,8 @@ The `CLI` component of `spooder` is a global command-line tool for running serve
 - [API > Cache Busting](#api-cache-busting)
 - [API > Git](#api-git)
 - [API > Database](#api-database)
+	- [API > Database > Utilities](#api-database-utilities)
 	- [API > Database > Schema](#api-database-schema)
-	- [API > Database > Interface](#api-database-interface)
-		- [API > Database > Interface > SQLite](#api-database-interface-sqlite)
-		- [API > Database > Interface > MySQL](#api-database-interface-mysql)
 - [API > Utilities](#api-utilities)
 
 # CLI
@@ -122,7 +128,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 +161,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 +194,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 +252,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 +389,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 +636,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;
@@ -556,46 +673,20 @@ cache_bust_get_hash_table(): Record<string, string>;
 
 // git
 git_get_hashes(length: number): Promise<Record<string, string>>;
-git_get_hashes_sync(length: number): Record<string, string>
-
-// database interface
-db_sqlite(filename: string, options: number|object): db_sqlite;
-db_mysql(options: ConnectionOptions, pool: boolean): Promise<MySQLDatabaseInterface>;
-db_cast_set<T extends string>(set: string | null): Set<T>;
-db_serialize_set<T extends string>(set: Set<T> | null): string;
-
-// db_sqlite
-update_schema(db_dir: string, schema_table?: string): Promise<void>
-insert(sql: string, ...values: any): number;
-insert_object(table: string, obj: Record<string, any>): number;
-execute(sql: string, ...values: any): number;
-get_all<T>(sql: string, ...values: any): T[];
-get_single<T>(sql: string, ...values: any): T | null;
-get_column<T>(sql: string, column: string, ...values: any): T[];
-get_paged<T>(sql: string, values?: any[], page_size?: number): AsyncGenerator<T[]>;
-count(sql: string, ...values: any): number;
-count_table(table_name: string): number;
-exists(sql: string, ...values: any): boolean;
-transaction(scope: (transaction: SQLiteDatabaseInterface) => void | Promise<void>): boolean;
-
-// db_mysql
-update_schema(db_dir: string, schema_table?: string): Promise<void>
-insert(sql: string, ...values: any): Promise<number>;
-insert_object(table: string, obj: Record<string, any>): Promise<number>;
-execute(sql: string, ...values: any): Promise<number>;
-get_all<T>(sql: string, ...values: any): Promise<T[]>;
-get_single<T>(sql: string, ...values: any): Promise<T | null>;
-get_column<T>(sql: string, column: string, ...values: any): Promise<T[]>;
-call<T>(func_name: string, ...args: any): Promise<T[]>;
-get_paged<T>(sql: string, values?: any[], page_size?: number): AsyncGenerator<T[]>;
-count(sql: string, ...values: any): Promise<number>;
-count_table(table_name: string): Promise<number>;
-exists(sql: string, ...values: any): Promise<boolean>;
-transaction(scope: (transaction: MySQLDatabaseInterface) => void | Promise<void>): Promise<boolean>;
+git_get_hashes_sync(length: number): Record<string, string>;
+
+// database utilities
+db_set_cast<T extends string>(set: string | null): Set<T>;
+db_set_serialize<T extends string>(set: Iterable<T> | null): string;
 
 // database schema
-db_update_schema_sqlite(db: Database, schema_dir: string, schema_table?: string): Promise<void>;
-db_update_schema_mysql(db: Connection, schema_dir: string, schema_table?: string): Promise<void>;
+type SchemaOptions = {
+	schema_table: string;
+	recursive: boolean;
+};
+
+db_get_schema_revision(db: SQL): Promise<number|null>;
+db_schema(db: SQL, schema_path: string, options?: SchemaOptions): Promise<boolean>;
 
 // caching
 cache_http(options?: CacheOptions);
@@ -604,10 +695,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>
@@ -621,6 +721,13 @@ log('Hello, {world}!');
 // > [info] Hello, world!
 ```
 
+Tagged template literals are also supported and automatically highlights values without the brace syntax.
+
+```ts
+const user = 'Fred';
+log`Hello ${user}!`;
+```
+
 Formatting parameters are supported using standard console logging formatters.
 
 ```ts
@@ -667,6 +774,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 +1849,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']
+});
+
+// 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)
+});
 
-pipe.on('bar', data => console.log('Received from worker:', data));
-pipe.send('foo', { x: 42 });
+// 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}`);
+});
 
-const pipe = worker_event_pipe(globalThis as unknown as Worker);
+// with custom timeout
+const pool = worker_connect('my_worker', 10000); // 10 second timeout
+const pool = worker_connect('my_worker', -1); // no timeout
+```
+
+### Basic Usage
 
-pipe.on('foo', data => {
-	console.log('Received from main:', data); // { x: 42 }
-	pipe.send('bar', { response: 'success' });
+```ts
+// main thread
+const pool = await worker_pool({
+	id: 'main',
+	worker: './worker.ts'
+});
+
+pool.send('my_worker', 'test', { foo: 42 });
+
+// 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
+});
+```
+
+### Cross-Worker Communication
+
+```ts
+// main thread
+const pool = await worker_pool({
+	id: 'main',
+	worker: ['./worker_a.ts', './worker_b.ts']
 });
+
+pool.send('worker_a', 'test', { foo: 42 }); // send to just worker_a
+pool.broadcast('test', { foo: 50 } ); // send to all workers
+
+// worker_a.ts
+const pool = worker_connect('worker_a');
+// send from worker_a to worker_b
+pool.send('worker_b', 'test', { foo: 500 });
 ```
 
-### WorkerEventPipeOptions
+### 🔧 `pool.send(peer: string, id: string, data?: Record<string, any>, expect_response?: boolean): void | Promise<WorkerMessage>`
 
-The second parameter of `worker_event_pipe` accepts an object of options.
+Send a message to a specific peer in the pool, which can be the main host or another worker.
 
-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.
+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()`.
 
-### 🔧 `pipe.send(id: string, data?: object): void`
+```ts
+// 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);
+```
 
-Send a message to the other side of the worker pipe with the specified event ID and optional data payload.
+> [!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`.
+
+### 🔧 `pool.broadcast(id: string, data?: Record<string, any>): void`
+
+Broadcast a message to all peers in the pool.
 
 ```ts
-pipe.send('user_update', { user_id: 123, name: 'John' });
-pipe.send('simple_event'); // data defaults to {}
+pool.broadcast('test_event', { foo: 42 });
 ```
 
-### 🔧 `pipe.on(event: string, callback: (data: object) => void | Promise<void>): void`
+### 🔧 `pool.on(event: string, callback: (data: Record<string, any>) => void | Promise<void>): void`
 
 Register an event handler for messages with the specified event ID. The callback can be synchronous or asynchronous.
 
 ```ts
-pipe.on('process_data', async (data) => {
-	const result = await processData(data);
-	pipe.send('data_processed', { result });
-});
-
-pipe.on('log_message', (data) => {
-	console.log(data.message);
+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]
@@ -2176,538 +2510,160 @@ const full_hashes = await git_get_hashes(40);
 
 
 <a id="api-database"></a>
-<a id="api-database-interface"></a>
 ## API > Database
 
-### 🔧 ``db_cast_set<T extends string>(set: string | null): Set<T>``
+Before `v6.0.0`, spooder provided a database API for `sqlite` and `mysql` while they were not available natively in `bun`.
 
-Takes a database SET string and returns a `Set<T>` where `T` is a provided enum.
+Now that `bun` provides a native API for these, we've dropped our API in favor of those as it aligns with the mission of minimalism.
 
-```ts
-enum ExampleRow {
-	OPT_A = 'OPT_A',
-	OPT_B = 'OPT_B',
-	OPT_C = 'OPT_C'
-};
+You can see the documentation for the [Bun SQL API here.](https://bun.com/docs/runtime/sql)
 
-const set = db_cast_set<ExampleRow>('OPT_A,OPT_B');
-if (set.has(ExampleRow.OPT_B)) {
-	// ...
-}
-```
+<a id="api-database-utilities"></a>
+## API > Database > Utilities
 
-### 🔧 ``db_serialize_set<T extends string>(set: Set<T> | null): string``
+### 🔧 ``db_set_cast<T extends string>(set: string | null): Set<T>``
 
-Takes a `Set<T>` and returns a database SET string. If the set is empty or `null`, it returns an empty string.
+Takes a database SET string and returns a `Set<T>` where `T` is a provided enum.
 
 ```ts
-enum ExampleRow {
-	OPT_A = 'OPT_A',
-	OPT_B = 'OPT_B',
-	OPT_C = 'OPT_C'
+enum Fruits {
+	Apple = 'Apple',
+	Banana = 'Banana',
+	Lemon = 'Lemon'
 };
 
-const set = new Set<ExampleRow>([ExampleRow.OPT_A, ExampleRow.OPT_B]);
-
-const serialized = db_serialize_set(set);
-// > 'OPT_A,OPT_B'
-```
-
-<a id="api-database-interface-sqlite"></a>
-## API > Database > Interface > SQLite
-
-`spooder` provides a simple **SQLite** interface that acts as a wrapper around the Bun SQLite API. The construction parameters match the underlying API.
-
-```ts
-// see: https://bun.sh/docs/api/sqlite
-const db = db_sqlite(':memory:', { create: true });
-db.instance; // raw access to underlying sqlite instance.
-```
-
-### Error Reporting
-
-In the event of an error from SQLite, an applicable value will be returned from interface functions, rather than the error being thrown.
+const [row] = await sql`SELECT * FROM some_table`;
+const set = db_set_cast<Fruits>(row.fruits);
 
-```ts
-const result = await db.get_single('BROKEN QUERY');
-if (result !== null) {
-	// do more stuff with result
+if (set.has(Fruits.Apple)) {
+	// we have an apple in the set
 }
 ```
 
-If you have configured the canary reporting feature in spooder, you can instruct the database interface to report errors using this feature with the `use_canary_reporting` parameter.
-
-```ts
-const db = db_sqlite(':memory', { ... }, true);
-```
-
-### 🔧 ``db_sqlite.update_schema(schema_dir: string, schema_table: string): Promise<void>``
-
-`spooder` offers a database schema management system. The `update_schema()` function is a shortcut to call this on the underlying database.
+### 🔧 ``db_set_serialize<T extends string>(set: Iterable<T> | null): string``
 
-See [API > Database > Schema](#api-database-schema) for information on how schema updating works.
+Takes an `Iterable<T>` and returns a database SET string. If the set is empty or `null`, it returns an empty string.
 
 ```ts
-// without interface
-import { db_sqlite, db_update_schema_sqlite } from 'spooder';
-const db = db_sqlite('./my_database.sqlite');
-await db_update_schema_sqlite(db.instance, './schema');
-
-// with interface
-import { db_sqlite } from 'spooder';
-const db = db_sqlite('./my_database.sqlite');
-await db.update_schema('./schema');
-```
-
-### 🔧 ``db_sqlite.insert(sql: string, ...values: any): number``
-
-Executes a query and returns the `lastInsertRowid`. Returns `-1` in the event of an error or if `lastInsertRowid` is not provided.
-
-```ts
-const id = db.insert('INSERT INTO users (name) VALUES(?)', 'test');
-```
-
-### 🔧 ``db_sqlite.insert_object(table: string, obj: Record<string, any>): number``
-
-Executes an insert query using object key/value mapping and returns the `lastInsertRowid`. Returns `-1` in the event of an error.
-
-```ts
-const id = db.insert_object('users', { name: 'John', email: 'john@example.com' });
-```
-
-### 🔧 ``db_sqlite.execute(sql: string, ...values: any): number``
-
-Executes a query and returns the number of affected rows. Returns `-1` in the event of an error.
-
-```ts
-const affected = db.execute('UPDATE users SET name = ? WHERE id = ?', 'Jane', 1);
-```
-
-### 🔧 ``db_sqlite.get_all<T>(sql: string, ...values: any): T[]``
-
-Returns the complete query result set as an array. Returns empty array if no rows found or if query fails.
-
-```ts
-const users = db.get_all<User>('SELECT * FROM users WHERE active = ?', true);
-```
-
-### 🔧 ``db_sqlite.get_single<T>(sql: string, ...values: any): T | null``
-
-Returns the first row from a query result set. Returns `null` if no rows found or if query fails.
-
-```ts
-const user = db.get_single<User>('SELECT * FROM users WHERE id = ?', 1);
-```
-
-### 🔧 ``db_sqlite.get_column<T>(sql: string, column: string, ...values: any): T[]``
-
-Returns the query result as a single column array. Returns empty array if no rows found or if query fails.
-
-```ts
-const names = db.get_column<string>('SELECT name FROM users', 'name');
-```
-
-### 🔧 ``db_sqlite.get_paged<T>(sql: string, values?: any[], page_size?: number): AsyncGenerator<T[]>``
-
-Returns an async iterator that yields pages of database rows. Each page contains at most `page_size` rows (default 1000).
-
-```ts
-for await (const page of db.get_paged<User>('SELECT * FROM users', [], 100)) {
-	console.log(`Processing ${page.length} users`);
-}
-```
-
-### 🔧 ``db_sqlite.count(sql: string, ...values: any): number``
-
-Returns the value of `count` from a query. Returns `0` if query fails.
-
-```ts
-const user_count = db.count('SELECT COUNT(*) AS count FROM users WHERE active = ?', true);
-```
-
-### 🔧 ``db_sqlite.count_table(table_name: string): number``
-
-Returns the total count of rows from a table. Returns `0` if query fails.
-
-```ts
-const total_users = db.count_table('users');
-```
-
-### 🔧 ``db_sqlite.exists(sql: string, ...values: any): boolean``
-
-Returns `true` if the query returns any results. Returns `false` if no results found or if query fails.
-
-```ts
-const has_active_users = db.exists('SELECT 1 FROM users WHERE active = ? LIMIT 1', true);
-```
-
-### 🔧 ``db_sqlite.transaction(scope: (transaction: SQLiteDatabaseInterface) => void | Promise<void>): boolean``
-
-Executes a callback function within a database transaction. The callback receives a transaction object with all the same database methods available. Returns `true` if the transaction was committed successfully, `false` if it was rolled back due to an error.
-
-```ts
-const success = db.transaction(async (tx) => {
-	const user_id = tx.insert('INSERT INTO users (name) VALUES (?)', 'John');
-	tx.insert('INSERT INTO user_profiles (user_id, bio) VALUES (?, ?)', user_id, 'Hello world');
-});
-
-if (success) {
-	console.log('Transaction completed successfully');
-} else {
-	console.log('Transaction was rolled back');
-}
-```
-
-<a id="api-database-interface-mysql"></a>
-## API > Database > Interface > MySQL
-
-`spooder` provides a simple **MySQL** interface that acts as a wrapper around the `mysql2` API. The connection options match the underlying API.
-
-> [!IMPORTANT]
-> MySQL requires the optional dependency `mysql2` to be installed - this is not automatically installed with spooder. This will be replaced when bun:sql supports MySQL natively.
-
-```ts
-// see: https://github.com/mysqljs/mysql#connection-options
-const db = await db_mysql({
-	// ...
-});
-db.instance; // raw access to underlying mysql2 instance.
-```
-
-### Error Reporting
-
-In the event of an error from MySQL, an applicable value will be returned from interface functions, rather than the error being thrown.
-
-```ts
-const result = await db.get_single('BROKEN QUERY');
-if (result !== null) {
-	// do more stuff with result
-}
-```
-
-If you have configured the canary reporting feature in spooder, you can instruct the database interface to report errors using this feature with the `use_canary_reporting` parameter.
-
-```ts
-const db = await db_mysql({ ... }, false, true);
-```
-
-### Pooling
-
-MySQL supports connection pooling. This can be configured by providing `true` to the `pool` parameter.
-
-```ts
-const pool = await db_mysql({ ... }, true);
-```
-
-### 🔧 ``db_mysql.update_schema(schema_dir: string, schema_table: string): Promise<void>``
-
-`spooder` offers a database schema management system. The `update_schema()` function is a shortcut to call this on the underlying database.
-
-See [API > Database > Schema](#api-database-schema) for information on how schema updating works.
-
-```ts
-// without interface
-import { db_mysql, db_update_schema_mysql } from 'spooder';
-const db = await db_mysql({ ... });
-await db_update_schema_mysql(db.instance, './schema');
-
-// with interface
-import { db_mysql } from 'spooder';
-const db = await db_mysql({ ... });
-await db.update_schema('./schema');
-```
-
-### 🔧 ``db_mysql.insert(sql: string, ...values: any): Promise<number>``
-
-Executes a query and returns the `LAST_INSERT_ID`. Returns `-1` in the event of an error or if `LAST_INSERT_ID` is not provided.
-
-```ts
-const id = await db.insert('INSERT INTO tbl (name) VALUES(?)', 'test');
-```
-
-### 🔧 ``db_mysql.insert_object(table: string, obj: Record<string, any>): Promise<number>``
-
-Executes an insert query using object key/value mapping and returns the `LAST_INSERT_ID`. Returns `-1` in the event of an error.
-
-```ts
-const id = await db.insert_object('users', { name: 'John', email: 'john@example.com' });
-```
-
-### 🔧 ``db_mysql.execute(sql: string, ...values: any): Promise<number>``
-
-Executes a query and returns the number of affected rows. Returns `-1` in the event of an error.
-
-```ts
-const affected = await db.execute('UPDATE users SET name = ? WHERE id = ?', 'Jane', 1);
-```
-
-### 🔧 ``db_mysql.get_all<T>(sql: string, ...values: any): Promise<T[]>``
-
-Returns the complete query result set as an array. Returns empty array if no rows found or if query fails.
-
-```ts
-const users = await db.get_all<User>('SELECT * FROM users WHERE active = ?', true);
-```
-
-### 🔧 ``db_mysql.get_single<T>(sql: string, ...values: any): Promise<T | null>``
-
-Returns the first row from a query result set. Returns `null` if no rows found or if query fails.
-
-```ts
-const user = await db.get_single<User>('SELECT * FROM users WHERE id = ?', 1);
-```
-
-### 🔧 ``db_mysql.get_column<T>(sql: string, column: string, ...values: any): Promise<T[]>``
-
-Returns the query result as a single column array. Returns empty array if no rows found or if query fails.
-
-```ts
-const names = await db.get_column<string>('SELECT name FROM users', 'name');
-```
-
-### 🔧 ``db_mysql.call<T>(func_name: string, ...args: any): Promise<T[]>``
-
-Calls a stored procedure and returns the result set as an array. Returns empty array if no rows found or if query fails.
-
-```ts
-const results = await db.call<User>('get_active_users', true, 10);
-```
-
-### 🔧 ``db_mysql.get_paged<T>(sql: string, values?: any[], page_size?: number): AsyncGenerator<T[]>``
-
-Returns an async iterator that yields pages of database rows. Each page contains at most `page_size` rows (default 1000).
-
-```ts
-for await (const page of db.get_paged<User>('SELECT * FROM users', [], 100)) {
-	console.log(`Processing ${page.length} users`);
-}
-```
-
-### 🔧 ``db_mysql.count(sql: string, ...values: any): Promise<number>``
-
-Returns the value of `count` from a query. Returns `0` if query fails.
-
-```ts
-const user_count = await db.count('SELECT COUNT(*) AS count FROM users WHERE active = ?', true);
-```
+enum Fruits {
+	Apple = 'Apple',
+	Banana = 'Banana',
+	Lemon = 'Lemon'
+};
 
-### 🔧 ``db_mysql.count_table(table_name: string): Promise<number>``
+// edit existing set
+const [row] = await sql`SELECT * FROM some_table`;
+const fruits = db_set_cast<Fruits>(row.fruits);
 
-Returns the total count of rows from a table. Returns `0` if query fails.
+if (!fruits.has(Fruits.Lemon))
+	fruits.add(Fruits.Lemon);
 
-```ts
-const total_users = await db.count_table('users');
-```
+await sql`UPDATE some_table SET fruits = ${sql(db_set_serialize(fruits))} WHERE id = ${row.id}`;
 
-### 🔧 ``db_mysql.exists(sql: string, ...values: any): Promise<boolean>``
-
-Returns `true` if the query returns any results. Returns `false` if no results found or if query fails.
-
-```ts
-const has_active_users = await db.exists('SELECT 1 FROM users WHERE active = ? LIMIT 1', true);
-```
-
-### 🔧 ``db_mysql.transaction(scope: (transaction: MySQLDatabaseInterface) => void | Promise<void>): Promise<boolean>``
-
-Executes a callback function within a database transaction. The callback receives a transaction object with all the same database methods available. Returns `true` if the transaction was committed successfully, `false` if it was rolled back due to an error.
-
-```ts
-const success = await db.transaction(async (tx) => {
-	const user_id = await tx.insert('INSERT INTO users (name) VALUES (?)', 'John');
-	await tx.insert('INSERT INTO user_profiles (user_id, bio) VALUES (?, ?)', user_id, 'Hello world');
-});
-
-if (success) {
-	console.log('Transaction completed successfully');
-} else {
-	console.log('Transaction was rolled back');
-}
+// new set from iterable
+await sql`UPDATE some_table SET fruits = ${sql(db_set_serialize([Fruits.Apple, Fruits.Lemon]))}`;
 ```
 
 <a id="api-database-schema"></a>
 ## API > Database > Schema
 
-`spooder` provides a straightforward API to manage database schema in revisions through source control.
-
-```ts
-// sqlite
-db_update_schema_sqlite(db: Database, schema_dir: string, schema_table?: string): Promise<void>;
-
-// mysql
-db_update_schema_mysql(db: Connection, schema_dir: string, schema_table?: string): Promise<void>;
-```
-
-```ts
-// sqlite example
-import { db_update_schema_sqlite } from 'spooder';
-import { Database } from 'bun:sqlite';
+### 🔧 ``db_schema(db: SQL, schema_path: string, options?: SchemaOptions): Promise<boolean>``
 
-const db = new Database('./database.sqlite');
-await db_update_schema_sqlite(db, './schema');
-```
+`db_schema` executes all revisioned `.sql` files in a given directory, applying them to the database incrementally.
 
 ```ts
-// mysql example
-import { db_update_schema_mysql } from 'spooder';
-import mysql from 'mysql2';
-
-const db = await mysql.createConnection({
-	// connection options
-	// see https://github.com/mysqljs/mysql#connection-options
-});
-await db_update_schema_mysql(db, './schema');
+const db = new SQL('db:pw@localhost:3306/test');
+await db_schema(db, './db/revisions');
 ```
 
-> [!IMPORTANT]
-> MySQL requires the optional dependency `mysql2` to be installed - this is not automatically installed with spooder. This will be replaced when bun:sql supports MySQL natively.
-
-### Interface API
-
-If you are already using the [database interface API](#api-database-interface) provided by `spooder`, you can call `update_schema()` directly on the interface.
+The above example will **recursively** search the `./db/revisions` directory for all `.sql` files that begin with a positive numeric identifier.
 
 ```ts
-const db = await db_mysql({ ... });
-await db.update_schema('./schema');
+db/revisions/000_invalid.sql // no: 0 is not valid
+db/revisions/001_valid.sql // yes: revision 1
+db/revisions/25-valid.sql // yes: revision 25
+db/revisions/005_not.txt // no: .sql extension missing
+db/revisions/invalid_500.sql // no: must begin with rev
 ```
 
-### Schema Files
+Revisions are applied in **numerical order**, rather than the file sorting order from the operating system. Invalid files are **skipped** without throwing an error.
 
-The schema directory is expected to contain an SQL file for each table in the database with the file name matching the name of the table.
-
-> [!NOTE]
-> The schema directory is searched recursively and files without the `.sql` extension (case-insensitive) will be ignored.
-
-```
-- database.sqlite
-- schema/
-	- users.sql
-	- posts.sql
-	- comments.sql
-```
+By default, schema revision is tracked in a table called `db_schema`. The name of this table can be customized by providing a different `.schema_table` option.
 
 ```ts
-import { db_update_schema_sqlite } from 'spooder';
-import { Database } from 'bun:sqlite';
-
-const db = new Database('./database.sqlite');
-await db_update_schema_sqlite(db, './schema');
+await db_schema(db, './db/revisions', { schema_table: 'alt_table_name' });
 ```
 
-Each of the SQL files should contain all of the revisions for the table, with the first revision being table creation and subsequent revisions being table modifications.
-
-```sql
--- [1] Table creation.
-CREATE TABLE users (
-	id INTEGER PRIMARY KEY,
-	username TEXT NOT NULL,
-	password TEXT NOT NULL
-);
-
--- [2] Add email column.
-ALTER TABLE users ADD COLUMN email TEXT;
+The revision folder is enumerated recursively by default. This can be disabled by passing `false` to `.recursive`, which will only scan the top level of the specified directory.
 
--- [3] Cleanup invalid usernames.
-DELETE FROM users WHERE username = 'admin';
-DELETE FROM users WHERE username = 'root';
+```ts
+await db_schema(db, './db/revisions', { recursive: false });
 ```
 
-Each revision should be clearly marked with a comment containing the revision number in square brackets. Anything proceeding the revision number is treated as a comment and ignored.
-
->[!NOTE]
-> The exact revision header syntax is `^--\s*\[(\d+)\]`.
-
-Everything following a revision header is considered part of that revision until the next revision header or the end of the file, allowing for multiple SQL statements to be included in a single revision.
+Each revision file is executed within a transaction. In the event of an error, the transaction will be rolled back. Successful revision files executed **before** the error will not be rolled back. Subsequent revision files will **not** be executed after an error.
 
-When calling `db_update_schema_*`, unapplied revisions will be applied in ascending order (regardless of order within the file) until the schema is up-to-date.
+> [!CAUTION]
+> Implicit commits, such as those that modify DDL, cannot be rolled back inside a transaction.
+>
+> It is recommended to only feature one implicit commit query per revision file. In the event of multiple, an error will not rollback previous implicitly committed queries within the revision, leaving your database in a partial state.
+>
+> See [MySQL 8.4 Reference Manual // 15.3.3 Statements That Cause an Implicit Commit](https://dev.mysql.com/doc/refman/8.4/en/implicit-commit.html) for more information.
 
-It is acceptable to omit keys. This can be useful to prevent repitition when managing stored procedures, views or functions.
 
-```sql
--- example of repetitive declaration
-
--- [1] create view
-CREATE VIEW `view_test` AS SELECT * FROM `table_a` WHERE col = 'foo';
+```ts
+type SchemaOptions = {
+	schema_table: string;
+	recursive: boolean;
+};
 
--- [2] change view
-DROP VIEW IF EXISTS `view_test`;
-CREATE VIEW `view_test` AS SELECT * FROM `table_b` WHERE col = 'foo';
+db_get_schema_revision(db: SQL): Promise<number|null>;
+db_schema(db: SQL, schema_path: string, options?: SchemaOptions): Promise<boolean>;
 ```
-Instead of unnecessarily including each full revision of a procedure, view or function in the schema file, simply store the most up-to-date one and increment the version.
-```sql
--- [2] create view
-CREATE OR REPLACE VIEW `view_test` AS SELECT * FROM `table_b` WHERE col = 'foo';
-```
-
 
-Schema revisions are tracked in a table called `db_schema` which is created automatically if it does not exist with the following schema.
+<a id="api-utilities"></a>
+## API > Utilities
 
-```sql
-CREATE TABLE db_schema (
-	db_schema_table_name TEXT PRIMARY KEY,
-	db_schema_version INTEGER
-);
-```
+### 🔧 ``filesize(bytes: number): string``
 
-The table used for schema tracking can be changed if necessary by providing an alternative table name as the third paramater.
+Returns a human-readable string representation of a file size in bytes.
 
 ```ts
-await db_update_schema_sqlite(db, './schema', 'my_schema_table');
+filesize(512); // > "512 bytes"
+filesize(1024); // > "1 kb"
+filesize(1048576); // > "1 mb"
+filesize(1073741824); // > "1 gb"
+filesize(1099511627776); // > "1 tb"
 ```
 
->[!IMPORTANT]
-> The entire process is transactional. If an error occurs during the application of **any** revision for **any** table, the entire process will be rolled back and the database will be left in the state it was before the update was attempted.
+### 🔧 ``BiMap<K, V>``
 
->[!IMPORTANT]
-> `db_update_schema_*` will throw an error if the revisions cannot be parsed or applied for any reason. It is important you catch and handle appropriately.
+A bidirectional map that maintains a two-way relationship between keys and values, allowing efficient lookups in both directions.
 
 ```ts
-try {
-	const db = new Database('./database.sqlite');
-	await db_update_schema_sqlite(db, './schema');
-} catch (e) {
-	// panic (crash) or gracefully continue, etc.
-	await panic(e);
-}
-```
-
-### Schema Dependencies
-By default, schema files are executed in the order they are provided by the operating system (generally alphabetically). Individual revisions within files are always executed in ascending order.
-
-If a specific revision depends on one or more other schema files to be executed before it (for example, when adding foreign keys), you can specify dependencies at the revision level.
-
-```sql
--- [1] create table_a (no dependencies)
-CREATE TABLE table_a (
-    id INTEGER PRIMARY KEY,
-    name TEXT NOT NULL
-);
-
--- [2] add foreign key to table_b
--- [deps] table_b_schema.sql
-ALTER TABLE table_a ADD COLUMN table_b_id INTEGER REFERENCES table_b(id);
-```
-
-When a revision specifies dependencies, all revisions of the dependent schema files will be executed before that specific revision runs. This allows you to create tables independently and then add dependencies in later revisions.
+const users = new BiMap<number, string>();
 
->[!IMPORTANT]
-> Dependencies are specified per-revision, not per-file. A `-- [deps]` line applies only to the revision it appears in.
+// Set key-value pairs
+users.set(1, "Alice");
+users.set(2, "Bob");
+users.set(3, "Charlie");
 
->[!IMPORTANT]
-> Cyclic or missing dependencies will throw an error.
+// Lookup by key
+users.getByKey(1); // > "Alice"
 
-<a id="api-utilities"></a>
-## API > Utilities
+// Lookup by value
+users.getByValue("Bob"); // > 2
 
-### 🔧 ``filesize(bytes: number): string``
+// Check existence
+users.hasKey(1); // > true
+users.hasValue("Charlie"); // > true
 
-Returns a human-readable string representation of a file size in bytes.
+// Delete by key or value
+users.deleteByKey(1); // > true
+users.deleteByValue("Bob"); // > true
 
-```ts
-filesize(512); // > "512 bytes"
-filesize(1024); // > "1 kb"
-filesize(1048576); // > "1 mb"
-filesize(1073741824); // > "1 gb"
-filesize(1099511627776); // > "1 tb"
+// Other operations
+users.size; // > 1
+users.clear();
 ```
 
 ## Legal