spooder 4.6.2 → 5.0.1

package/README.md

@@ -17,66 +17,6 @@ It consists of two components, the `CLI` and the `API`.
 - The `CLI` is responsible for keeping the server process running, applying updates in response to source control changes, and automatically raising issues on GitHub via the canary feature.
 - The `API` provides a minimal building-block style API for developing servers, with a focus on simplicity and performance.
 
-# CLI
-
-The `CLI` component of `spooder` is a global command-line tool for running server processes.
-
-- [CLI > Usage](#cli-usage)
-- [CLI > Dev Mode](#cli-dev-mode)
-- [CLI > Auto Restart](#cli-auto-restart)
-- [CLI > Auto Update](#cli-auto-update)
-- [CLI > Canary](#cli-canary)
-	- [CLI > Canary > Crash](#cli-canary-crash)
-	- [CLI > Canary > Sanitization](#cli-canary-sanitization)
-	- [CLI > Canary > System Information](#cli-canary-system-information)
-
-# API
-
-`spooder` exposes a simple yet powerful API for developing servers. The API is designed to be minimal to leave control in the hands of the developer and not add overhead for features you may not need.
-
-- [API > Serving](#api-serving)
-	- [`serve(port: number, hostname?: string): Server`](#api-serving-serve)
-- [API > Routing](#api-routing)
-	- [`server.route(path: string, handler: RequestHandler, method: HTTP_METHODS)`](#api-routing-server-route)
-	- [`server.unroute(path: string)`](#api-routing-server-unroute)
-	- [HTTP Methods](#api-routing-methods)
-	- [Redirection Routes](#api-routing-redirection-routes)
-	- [Status Code Text](#api-routing-status-code-text)
-- [API > Routing > RequestHandler](#api-routing-request-handler)
-- [API > Routing > Fallback Handling](#api-routing-fallback-handlers)
-	- [`server.handle(status_code: number, handler: RequestHandler)`](#api-routing-server-handle)
-	- [`server.default(handler: DefaultHandler)`](#api-routing-server-default)
-	- [`server.error(handler: ErrorHandler)`](#api-routing-server-error)
-- [API > Routing > Slow Requests](#api-routing-slow-requests)
-	- [`server.on_slow_request(callback: SlowRequestCallback, threshold: number)`](#api-routing-server-on-slow-request)
-	- [`server.allow_slow_request(req: Request)`](#api-routing-server-allow-slow-request)
-- [API > Routing > Validation](#api-routing-validation)
-	- [`validate_req_json(handler: JSONRequestHandler)`](#api-routing-validate-req-json)
-- [API > Routing > Directory Serving](#api-routing-directory-serving)
-	- [`server.dir(path: string, dir: string, handler?: DirHandler, method: HTTP_METHODS)`](#api-routing-server-dir)
-- [API > Routing > Server-Sent Events](#api-routing-server-sent-events)
-	- [`server.sse(path: string, handler: ServerSentEventHandler)`](#api-routing-server-sse)
-- [API > Routing > Webhooks](#api-routing-webhooks)
-	- [`server.webhook(secret: string, path: string, handler: WebhookHandler)`](#api-routing-server-webhook)
-- [API > Routing > WebSockets](#api-routing-websockets)
-	- [`server.websocket(path: string, handlers: WebsocketHandlers)`](#api-routing-server-websocket)
-- [API > Server Control](#api-server-control)
-	- [`server.stop(immediate: boolean)`](#api-server-control-server-stop)
-- [API > Error Handling](#api-error-handling)
-	- [`ErrorWithMetadata(message: string, metadata: object)`](#api-error-handling-error-with-metadata)
-	- [`caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-caution)
-	- [`panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-panic)
-	- [`safe(fn: Callable): Promise<void>`](#api-error-handling-safe)
-- [API > Content](#api-content)
-	- [`parse_template(template: string, replacements: Record<string, string>, drop_missing: boolean): string`](#api-content-parse-template)
-	- [`generate_hash_subs(length: number, prefix: string, hashes?: Record<string, string>): Promise<Record<string, string>>`](#api-content-generate-hash-subs)
-	- [`get_git_hashes(length: number): Promise<Record<string, string>>`](#api-content-get-git-hashes)
-	- [`apply_range(file: BunFile, request: Request): HandlerReturnType`](#api-content-apply-range)
-- [API > State Management](#api-state-management)
-	- [`set_cookie(res: Response, name: string, value: string, options?: CookieOptions)`](#api-state-management-set-cookie)
-	- [`get_cookies(source: Request | Response): Record<string, string>`](#api-state-management-get-cookies)
-- [API > Database Schema](#api-database-schema)
-
 # Installation
 
 ```bash
@@ -91,14 +31,25 @@ bun add spooder
 
 Both the `CLI` and the API are configured in the same way by providing a `spooder` object in your `package.json` file.
 
-```json
+Below is a full map of the available configuration options in their default states. All configuration options are **optional**.
+
+```jsonc
 {
 	"spooder": {
-		"auto_restart": 5000,
+
+		// see CLI > Auto Restart
+		"auto_restart": true,
+		"auto_restart_max": 30000,
+		"auto_restart_attempts": 10,
+		"auto_restart_grace": 30000,
+
+		// see CLI > Auto Update
 		"update": [
 			"git pull",
 			"bun install"
 		],
+
+		// see CLI > Canary
 		"canary": {
 			"account": "",
 			"repository": "",
@@ -116,6 +67,44 @@ If there are any issues with the provided configuration, a warning will be print
 > [!NOTE]
 > Configuration warnings **do not** raise `caution` events with the `spooder` canary functionality.
 
+# CLI
+
+The `CLI` component of `spooder` is a global command-line tool for running server processes.
+
+- [CLI > Usage](#cli-usage)
+- [CLI > Dev Mode](#cli-dev-mode)
+- [CLI > Auto Restart](#cli-auto-restart)
+- [CLI > Auto Update](#cli-auto-update)
+- [CLI > Canary](#cli-canary)
+	- [CLI > Canary > Crash](#cli-canary-crash)
+	- [CLI > Canary > Sanitization](#cli-canary-sanitization)
+	- [CLI > Canary > System Information](#cli-canary-system-information)
+
+# API
+
+`spooder` exposes a simple yet powerful API for developing servers. The API is designed to be minimal to leave control in the hands of the developer and not add overhead for features you may not need.
+
+- [API > Cheatsheet](#api-cheatsheet)
+- [API > Logging](#api-logging)
+- [API > HTTP](#api-http)
+	- [API > HTTP > Directory Serving](#api-http-directory)
+	- [API > HTTP > Server-Sent Events (SSE)](#api-http-sse)
+	- [API > HTTP > Webhooks](#api-http-webhooks)
+	- [API > HTTP > Websocket Server](#api-http-websockets)
+	- [API > HTTP > Bootstrap](#api-http-bootstrap)
+- [API > Error Handling](#api-error-handling)
+- [API > Workers](#api-workers)
+- [API > Caching](#api-caching)
+- [API > Templating](#api-templating)
+- [API > Database](#api-database)
+	- [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
+
 <a id="cli-usage"></a>
 ## CLI > Usage
 
@@ -179,17 +168,27 @@ if (process.env.SPOODER_ENV === 'dev') {
 > [!NOTE]
 > This feature is not enabled by default.
 
-In the event that the server process exits, regardless of exit code, `spooder` can automatically restart it after a short delay. To enable this feature specify the restart delay in milliseconds as `auto_restart` in the configuration.
+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.
 
 ```json
 {
 	"spooder": {
-		"auto_restart": 5000
+		"auto_restart": true,
+		"auto_restart_max": 30000,
+		"auto_restart_attempts": 10,
+		"auto_restart_grace": 30000
 	}
 }
 ```
 
-If set to `0`, the server will be restarted immediately without delay. If set to `-1`, the server will not be restarted at all.
+### Configuration Options
+
+- **`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.
+
+If the server exits with a zero exit code (successful termination), auto-restart will not trigger.
 
 <a id="cli-auto-update"></a>
 ## CLI > Auto Update
@@ -227,7 +226,7 @@ server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
 		await server.stop(false);
 		process.exit();
 	});
-	return 200;
+	return HTTP_STATUS_CODE.OK_200;
 });
 ```
 
@@ -243,9 +242,10 @@ In addition to being skipped in [dev mode](#cli-dev-mode), updates can also be s
 
 `canary` is a feature in `spooder` which allows server problems to be raised as issues in your repository on GitHub.
 
-To enable this feature, you will need to create a GitHub App and configure it:
+To enable this feature, you will need a GitHub app which has access to your repository and a corresponding private key. If you do not already have those, instructions can be found below.
 
-### 1. Create a GitHub App
+<details>
+<summary>GitHub App Setup</summary>
 
 Create a new GitHub App either on your personal account or on an organization. The app will need the following permissions:
 
@@ -264,8 +264,9 @@ openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out
 ```
 
 Each server that intends to use the canary feature will need to have the private key installed somewhere the server process can access it.
+</details>
 
-### 2. Add package.json configuration
+### Configure Canary
 
 ```json
 "spooder": {
@@ -283,7 +284,7 @@ The repository name must in the full-name format `owner/repo` (e.g. `facebook/re
 
 The `labels` property can be used to provide a list of labels to automatically add to the issue. This property is optional and can be omitted.
 
-### 3. Setup environment variables
+### Setup Environment Variables
 
 The following two environment variables must be defined on the server.
 
@@ -299,7 +300,7 @@ SPOODER_CANARY_KEY=/home/bond/.ssh/id_007_pcks8.key
 > [!NOTE]
 > Since `spooder` uses the Bun runtime, you can use the `.env.local` file in the project root directory to set these environment variables per-project.
 
-### 4. Use canary
+### Using Canary
 
 Once configured, `spooder` will automatically raise an issue when the server exits with a non-zero exit code. 
 
@@ -464,19 +465,173 @@ In addition to the information provided by the developer, `spooder` also include
 }
 ```
 
-<a id="api-serving"></a>
-## API > Serving
+# API
+
+<a id="api-cheatsheet"></a>
+## API > Cheatsheet
+
+```ts
+// logging
+log(message: string);
+log_error(message: string);
+log_create_logger(prefix: string, color: ColorInput);
+log_list(input: any[], delimiter = ', ');
+
+// http
+http_serve(port: number, hostname?: string): Server;
+server.stop(immediate: boolean): Promise<void>;
+
+// routing
+server.route(path: string, handler: RequestHandler, method?: HTTP_METHODS);
+server.json(path: string, handler: JSONRequestHandler, method?: HTTP_METHODS);
+server.unroute(path: string);
+
+// fallback handlers
+server.handle(status_code: number, handler: RequestHandler);
+server.default(handler: DefaultHandler);
+server.error(handler: ErrorHandler);
+server.on_slow_request(callback: SlowRequestCallback, threshold?: number);
+server.allow_slow_request(req: Request);
+
+// http generics
+http_apply_range(file: BunFile, request: Request): HandlerReturnType;
+
+// directory serving
+server.dir(path: string, dir: string, options?: DirOptions | DirHandler, method?: HTTP_METHODS);
+
+// server-sent events
+server.sse(path: string, handler: ServerSentEventHandler);
+
+// webhooks
+server.webhook(secret: string, path: string, handler: WebhookHandler, branches?: string | string[]);
+
+// websockets
+server.websocket(path: string, handlers: WebsocketHandlers);
+
+// bootstrap
+server.bootstrap(options: BootstrapOptions): Promise<void>;
+
+// error handling
+ErrorWithMetadata(message: string, metadata: object);
+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;
+
+// templates
+parse_template(template: string, replacements: Record<string, string>, drop_missing?: boolean): Promise<string>;
+generate_hash_subs(length?: number, prefix?: string, hashes?: Record<string, string>): Promise<Record<string, string>>;
+get_git_hashes(length: number): Promise<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>;
+
+// 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>;
+
+// caching
+cache_http(options?: CacheOptions);
+cache.file(file_path: string): RequestHandler;
+cache.request(req: Request, cache_key: string, content_generator: () => string | Promise<string>): Promise<Response>;
+
+// utilities
+filesize(bytes: number): string;
+
+// constants
+HTTP_STATUS_TEXT: Record<number, string>;
+HTTP_STATUS_CODE: { OK_200: 200, NotFound_404: 404, ... };
+```
+
+<a id="api-logging"></a>
+## API > Logging
+
+### 🔧 `log(message: string)`
+Print a message to the console using the default logger. Wrapping text segments in curly braces will highlight those segments with colour.
+
+```ts
+log('Hello, {world}!');
+// > [info] Hello, world!
+```
+
+### 🔧 `log_error(message: string)`
+Print an error message to the console. Wrapping text segments in curly braces will highlight those segments. This works the same as `log()` except it's red, so you know it's bad.
+
+```ts
+log_error('Something went {really} wrong');
+// > [error] Something went really wrong
+```
+
+### 🔧 `log_create_logger(prefix: string, color: ColorInput)`
+Create a `log()` function with a custom prefix and highlight colour.
+
+```ts
+const db_log = log_create_logger('db', 'pink');
+db_log('Creating table {users}...');
+```
+
+> [!INFO]
+> For information about `ColorInput`, see the [Bun Color API](https://bun.sh/docs/api/color).
+
+
+### 🔧 `log_list(input: any[], delimiter = ', ')`
+Utility function that joins an array of items together with each element wrapped in highlighting syntax for logging.
+
+```ts
+const fruit = ['apple', 'orange', 'peach'];
+log(`Fruit must be one of ${fruit.map(e => `{${e}}`).join(', ')}`);
+log(`Fruit must be one of ${log_list(fruit)}`);
+```
 
-<a id="api-serving-serve"></a>
-### `serve(port: number, hostname?: string): Server`
+<a id="api-http"></a>
+## API > HTTP
 
+### `http_serve(port: number, hostname?: string): Server`
 Bootstrap a server on the specified port (and optional hostname).
 
 ```ts
 import { serve } from 'spooder';
 
-const server = serve(8080); // port only
-const server = serve(3000, '0.0.0.0'); // optional hostname
+const server = http_serve(8080); // port only
+const server = http_serve(3000, '0.0.0.0'); // optional hostname
 ```
 
 By default, the server responds with:
@@ -489,10 +644,28 @@ Content-Type: text/plain;charset=utf-8
 Not Found
 ```
 
-<a id="api-routing"></a>
-## API > Routing
+### 🔧 `server.stop(immediate: boolean)`
+
+Stop the server process immediately, terminating all in-flight requests.
+
+```ts
+server.stop(true);
+```
+
+Stop the server process gracefully, waiting for all in-flight requests to complete.
+
+```ts
+server.stop(false);
+```
+
+`server.stop()` returns a promise, which if awaited, resolves when all pending connections have been completed.
+```ts
+await server.stop(false);
+// do something now all connections are done
+```
+
+### Routing
 
-<a id="api-routing-server-route"></a>
 ### 🔧 `server.route(path: string, handler: RequestHandler)`
 
 Register a handler for a specific path.
@@ -503,7 +676,6 @@ server.route('/test/route', (req, url) => {
 });
 ```
 
-<a id="api-routing-server-unrouote"></a>
 ### 🔧 `server.unroute(path: string)`
 
 Unregister a specific route.
@@ -513,10 +685,37 @@ server.route('/test/route', () => {});
 server.unroute('/test/route');
 ```
 
-<a id="api-routing-methods"></a>
+### 🔧 `server.json(path: string, handler: JSONRequestHandler, method?: HTTP_METHODS)`
+
+Register a JSON endpoint with automatic content validation. This method automatically validates that the request has the correct `Content-Type: application/json` header and that the request body contains a valid JSON object.
+
+```ts
+server.json('/api/users', (req, url, json) => {
+	// json is automatically parsed and validated as a plain object
+	const name = json.name;
+	const email = json.email;
+	
+	// Process the JSON data
+	return { success: true, id: 123 };
+});
+```
+
+By default, JSON routes are registered as `POST` endpoints, but this can be customized:
+
+```ts
+server.json('/api/data', (req, url, json) => {
+	return { received: json };
+}, 'PUT');
+```
+
+The handler will automatically return `400 Bad Request` if:
+- The `Content-Type` header is not `application/json`
+- The request body is not valid JSON
+- The JSON is not a plain object (e.g., it's an array, null, or primitive value)
+
 ### HTTP Methods
 
-By default, `spooder` will register routes defined with `server.route()` and `server.dir()` as `GET` routes. Requests to these routes with other methods will return `405 Method Not Allowed`.
+By default, `spooder` will register routes defined with `server.route()` and `server.dir()` as `GET` routes, while `server.json()` routes default to `POST`. Requests to these routes with other methods will return `405 Method Not Allowed`.
 
 > [!NOTE]
 > spooder does not automatically handle HEAD requests natively.
@@ -539,32 +738,38 @@ server.route('/test/route', (req, url) => {
 > [!NOTE]
 > Routes defined with .sse() or .webhook() are always registered as 'GET' and 'POST' respectively and cannot be configured.
 
-<a id="api-routing-redirection-routes"></a>
 ### Redirection Routes
 
 `spooder` does not provide a built-in redirection handler since it's trivial to implement one using [`Response.redirect`](https://developer.mozilla.org/en-US/docs/Web/API/Response/redirect_static), part of the standard Web API.
 
 ```ts
-server.route('/redirect', () => Response.redirect('/redirected', 301));
+server.route('/redirect', () => Response.redirect('/redirected', HTTP_STATUS_CODE.MovedPermanently_301));
 ```
 
-<a id="api-routing-status-code-text"></a>
 ### Status Code Text
 
-`spooder` exposes `HTTP_STATUS_CODE` to convieniently access status code text.
+`spooder` exposes `HTTP_STATUS_TEXT` to conveniently access status code text, and `HTTP_STATUS_CODE` for named status code constants.
 
 ```ts
-import { HTTP_STATUS_CODE } from 'spooder';
+import { HTTP_STATUS_TEXT, HTTP_STATUS_CODE } from 'spooder';
 
 server.default((req, status_code) => {
 	// status_code: 404
 	// Body: Not Found
-	return new Response(HTTP_STATUS_CODE[status_code], { status: status_code });
+	return new Response(HTTP_STATUS_TEXT[status_code], { status: status_code });
+});
+
+// Using named constants for better readability
+server.route('/api/users', (req, url) => {
+	if (!isValidUser(req))
+		return HTTP_STATUS_CODE.Unauthorized_401;
+	
+	// Process user request
+	return HTTP_STATUS_CODE.OK_200;
 });
 ```
 
-<a id="api-routing-request-handler"></a>
-## API > Routing > RequestHandler
+### RequestHandler
 
 `RequestHandler` is a function that accepts a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object and a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object and returns a `HandlerReturnType`.
 
@@ -587,8 +792,7 @@ server.default((req, status_code) => {
 > [!NOTE]
 > Returning `Bun.file()` directly is the most efficient way to serve static files as it uses system calls to stream the file directly to the client without loading into user-space.
 
-<a id="api-routing-query-parameters"></a>
-## API > Routing > Query Parameters
+### Query Parameters
 
 Query parameters can be accessed from the `searchParams` property on the `URL` object.
 
@@ -618,8 +822,7 @@ server.route('/test/:param', (req, url) => {
 });
 ```
 
-<a id="api-routing-wildcards"></a>
-## API > Routing > Wildcards
+### Wildcards
 
 Wildcards can be used to match any path that starts with a given path.
 
@@ -628,7 +831,7 @@ Wildcards can be used to match any path that starts with a given path.
 
 ```ts
 server.route('/test/*', (req, url) => {
-	return new Response('Hello, world!', { status: 200 });
+	return new Response('Hello, world!', { status: HTTP_STATUS_CODE.OK_200 });
 });
 ```
 
@@ -636,25 +839,22 @@ server.route('/test/*', (req, url) => {
 > Routes are [FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) and wildcards are greedy. Wildcards should be registered last to ensure they do not consume more specific routes.
 
 ```ts
-server.route('/*', () => 301);
-server.route('/test', () => 200);
+server.route('/*', () => HTTP_STATUS_CODE.MovedPermanently_301);
+server.route('/test', () => HTTP_STATUS_CODE.OK_200);
 
 // Accessing /test returns 301 here, because /* matches /test first.
 ```
 
-<a id="api-routing-fallback-handlers"></a>
-## API > Routing > Fallback Handlers
+### Fallback Handlers
 
-<a id="api-routing-server-handle"></a>
 ### 🔧 `server.handle(status_code: number, handler: RequestHandler)`
 Register a custom handler for a specific status code.
 ```ts
-server.handle(500, (req) => {
-	return new Response('Custom Internal Server Error Message', { status: 500 });
+server.handle(HTTP_STATUS_CODE.InternalServerError_500, (req) => {
+	return new Response('Custom Internal Server Error Message', { status: HTTP_STATUS_CODE.InternalServerError_500 });
 });
 ```
 
-<a id="api-routing-server-default"></a>
 ### 🔧 `server.default(handler: DefaultHandler)`
 Register a handler for all unhandled response codes.
 > [!NOTE]
@@ -665,7 +865,6 @@ server.default((req, status_code) => {
 });
 ```
 
-<a id="api-routing-server-error"></a>
 ### 🔧 `server.error(handler: ErrorHandler)`
 Register a handler for uncaught errors.
 
@@ -673,7 +872,7 @@ Register a handler for uncaught errors.
 > Unlike other handlers, this should only return `Response` or `Promise<Response>`.
 ```ts
 server.error((err, req, url) => {
-	return new Response('Custom Internal Server Error Message', { status: 500 });
+	return new Response('Custom Internal Server Error Message', { status: HTTP_STATUS_CODE.InternalServerError_500 });
 });
 ```
 
@@ -686,14 +885,12 @@ server.error((err, req, url) => {
 	caution({ err, url });
 
 	// Return a response to the client.
-	return new Response('Custom Internal Server Error Message', { status: 500 });
+	return new Response('Custom Internal Server Error Message', { status: HTTP_STATUS_CODE.InternalServerError_500 });
 });
 ```
 
-<a id="api-routing-slow-requests"></a>
-## API > Routing > Slow Requests
+### Slow Requests
 
-<a id="api-routing-server-on-slow-request"></a>
 ### 🔧 `server.on_slow_request(callback: SlowRequestCallback, threshold: number)`
 
 `server.on_slow_request` can be used to register a callback for requests that take an undesirable amount of time to process.
@@ -714,7 +911,6 @@ server.on_slow_request(async (req, time, url) => {
 > [!NOTE]
 > The callback is not awaited internally, so you can use `async/await` freely without blocking the server/request.
 
-<a id="api-routing-server-allow-slow-request"></a>
 ### 🔧 `server.allow_slow_request(req: Request)`
 
 In some scenarios, mitigation throttling or heavy workloads may cause slow requests intentionally. To prevent these triggering a caution, requests can be marked as slow.
@@ -735,106 +931,77 @@ server.route('/test', async (req) => {
 > [!NOTE]
 > This will have no effect if a handler hasn't been registered with `on_slow_request`.
 
-<a id="api-routing-validation"></a>
-## API > Routing > Validation
+<a id="api-http-directory"></a>
+## API > HTTP > Directory Serving
 
-<a id="api-routing-validate-req-json"></a>
-### 🔧 `validate_req_json(handler: JSONRequestHandler)`
-
-In the scenario that you're expecting an endpoint to receive JSON data, you might set up a handler like this:
+### 🔧 `server.dir(path: string, dir: string, options?: DirOptions | DirHandler)`
+Serve files from a directory.
 
 ```ts
-server.route('/api/endpoint', async (req, url) => {
-	const json = await req.json();
-	// do something with json.
-	return 200;
-})
+server.dir('/content', './public/content');
 ```
 
-The problem with this is that if the request body is not valid JSON, the server will throw an error (potentially triggering canary reports) and return a `500` response.
-
-What should instead happen is something like this:
+> [!IMPORTANT]
+> `server.dir` registers a wildcard route. Routes are [FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) and wildcards are greedy. Directories should be registered last to ensure they do not consume more specific routes.
 
 ```ts
-server.route('/api/endpoint', async (req, url) => {
-	// check content-type header
-	if (req.headers.get('Content-Type') !== 'application/json')
-		return 400;
-
-	try {
-		const json = await req.json();
-		if (json === null || typeof json !== 'object' || Array.isArray(json))
-			return 400;
+server.dir('/', '/files');
+server.route('/test', () => 200);
 
-		// do something with json.
-		return 200;
-	} catch (err) {
-		return 400;
-	}
-})
+// Route / is equal to /* with server.dir()
+// Accessing /test returns 404 here because /files/test does not exist.
 ```
 
-As you can see this is quite verbose and adds a lot of boilerplate to your handlers. `validate_req_json` can be used to simplify this.
+#### Directory Options
+
+You can configure directory behavior using the `DirOptions` interface:
 
 ```ts
-server.route('/api/endpoint', validate_req_json(async (req, url, json) => {
-	// do something with json.
-	return 200;
-}));
+interface DirOptions {
+	ignore_hidden?: boolean;      // default: true
+	index_directories?: boolean;  // default: false  
+	support_ranges?: boolean;     // default: true
+}
 ```
 
-This behaves the same as the code above, where a `400` status code is returned if the `Content-Type` header is not `application/json` or if the request body is not valid JSON, and no error is thrown.
-
-> [!NOTE]
-> While arrays and other primitives are valid JSON, `validate_req_json` will only pass objects to the handler, since they are the most common use case for JSON request bodies and it removes the need to validate that in the handler. If you need to use arrays or other primitives, either box them in an object or provide your own validation.
+**Options-based configuration:**
+```ts
+// Enable directory browsing with HTML listings
+server.dir('/files', './public', { index_directories: true });
 
-<a id="api-routing-directory-serving"></a>
-## API > Routing > Directory Serving
+// Serve hidden files and disable range requests
+server.dir('/files', './public', { 
+	ignore_hidden: false, 
+	support_ranges: false 
+});
 
-<a id="api-routing-server-dir"></a>
-### 🔧 `server.dir(path: string, dir: string, handler?: DirHandler)`
-Serve files from a directory.
-```ts
-server.dir('/content', './public/content');
+// Full configuration
+server.dir('/files', './public', { 
+	ignore_hidden: true,
+	index_directories: true,
+	support_ranges: true 
+});
 ```
 
-> [!IMPORTANT]
-> `server.dir` registers a wildcard route. Routes are [FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)) and wildcards are greedy. Directories should be registered last to ensure they do not consume more specific routes.
-
-```ts
-server.dir('/', '/files');
-server.route('/test', () => 200);
+When `index_directories` is enabled, accessing a directory will return a styled HTML page listing the directory contents with file and folder icons.
 
-// Route / is equal to /* with server.dir()
-// Accessing /test returns 404 here because /files/test does not exist.
-```
+#### Custom Directory Handlers
 
-By default, spooder will use the following default handler for serving directories.
+For complete control, provide a custom handler function:
 
 ```ts
-function default_directory_handler(file_path: string, file: BunFile, stat: DirStat, request: Request): HandlerReturnType {
+server.dir('/static', '/static', (file_path, file, stat, request, url) => {
 	// ignore hidden files by default, return 404 to prevent file sniffing
 	if (path.basename(file_path).startsWith('.'))
-		return 404; // Not Found
+		return HTTP_STATUS_CODE.NotFound_404;
 
 	if (stat.isDirectory())
-		return 401; // Unauthorized
+		return HTTP_STATUS_CODE.Unauthorized_401;
 
-	return apply_range(file, request);
-}
+	return http_apply_range(file, request);
+});
 ```
 
-> [!NOTE]
-> Uncaught `ENOENT` errors thrown from the directory handler will return a `404` response, other errors will return a `500` response.
-
-> [!NOTE]
-> The call to `apply_range` in the default directory handler will automatically slice the file based on the [`Range`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) header. This function is also exposed as part of the `spooder` API for use in your own handlers.
-
-Provide your own directory handler for fine-grained control.
-
-> [!IMPORTANT]
-> Providing your own handler will override the default handler defined above. Be sure to implement the same logic if you want to retain the default behavior.
-
 | Parameter | Type | Reference |
 | --- | --- | --- |
 | `file_path` | `string` | The path to the file on disk. |
@@ -843,30 +1010,48 @@ Provide your own directory handler for fine-grained control.
 | `request` | `Request` | https://developer.mozilla.org/en-US/docs/Web/API/Request |
 | `url` | `URL` | https://developer.mozilla.org/en-US/docs/Web/API/URL |
 
+Asynchronous directory handlers are supported and will be awaited.
+
 ```ts
-server.dir('/static', '/static', (file_path, file, stat, request, url) => {
-	// Implement custom logic.
-	return file; // HandlerReturnType
+server.dir('/static', '/static', async (file_path, file) => {
+	let file_contents = await file.text();
+	// do something with file_contents
+	return file_contents;
 });
 ```
 
 > [!NOTE]
 > The directory handler function is only called for files that exist on disk - including directories.
 
-Asynchronous directory handlers are supported and will be awaited.
+> [!NOTE]
+> Uncaught `ENOENT` errors thrown from the directory handler will return a `404` response, other errors will return a `500` response.
 
-```js
-server.dir('/static', '/static', async (file_path, file) => {
-	let file_contents = await file.text();
-	// do something with file_contents
-	return file_contents;
+### 🔧 `http_apply_range(file: BunFile, request: Request): HandlerReturnType`
+
+`http_apply_range` parses the `Range` header for a request and slices the file accordingly. This is used internally by `server.dir()` and exposed for convenience.
+
+```ts
+server.route('/test', (req, url) => {
+	const file = Bun.file('./test.txt');
+	return http_apply_range(file, req);
 });
 ```
 
-<a id="api-routing-server-sse"></a>
-## API > Routing > Server-Sent Events
+```http
+GET /test HTTP/1.1
+Range: bytes=0-5
+
+HTTP/1.1 206 Partial Content
+Content-Length: 6
+Content-Range: bytes 0-5/6
+Content-Type: text/plain;charset=utf-8
+
+Hello,
+```
+
+<a id="api-http-sse"></a>
+## API > HTTP > Server-Sent Events (SSE)
 
-<a id="api-routing-server-sse"></a>
 ### 🔧 `server.sse(path: string, handler: ServerSentEventHandler)`
 
 Setup a [server-sent event](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream.
@@ -904,35 +1089,54 @@ server.sse('/sse', (req, url, client) => {
 });
 ```
 
-<a id="api-routing-webhooks"></a>
-## API > Routing > Webhooks
+<a id="api-http-webhooks"></a>
+## API > HTTP > Webhooks
 
-<a id="api-routing-server-webhook"></a>
-### 🔧 `server.webhook(secret: string, path: string, handler: WebhookHandler)`
+### 🔧 `server.webhook(secret: string, path: string, handler: WebhookHandler, branches?: string | string[])`
 
 Setup a webhook handler.
 
 ```ts
 server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
 	// React to the webhook.
-	return 200;
+	return HTTP_STATUS_CODE.OK_200;
 });
 ```
 
+#### Branch Filtering
+
+You can optionally filter webhooks by branch name using the `branches` parameter:
+
+```ts
+// Only trigger for main branch
+server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
+	// This will only fire for pushes to main branch
+	return HTTP_STATUS_CODE.OK_200;
+}, 'main');
+
+// Trigger for multiple branches
+server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
+	// This will fire for pushes to main or staging branches
+	return HTTP_STATUS_CODE.OK_200;
+}, ['main', 'staging']);
+```
+
+When branch filtering is enabled, the webhook handler will only be called for pushes to the specified branches. The branch name is extracted from the payload's `ref` field (e.g., `refs/heads/main` becomes `main`).
+
 A webhook callback will only be called if the following critera is met by a request:
 - Request method is `POST` (returns `405` otherwise)
 - Header `X-Hub-Signature-256` is present (returns `400` otherwise)
 - Header `Content-Type` is `application/json` (returns `401` otherwise)
 - Request body is a valid JSON object (returns `500` otherwise)
 - HMAC signature of the request body matches the `X-Hub-Signature-256` header (returns `401` otherwise)
+- If branch filtering is enabled, the push must be to one of the specified branches (returns `200` but ignores otherwise)
 
 > [!NOTE]
 > Constant-time comparison is used to prevent timing attacks when comparing the HMAC signature.
 
-<a id="api-routing-websockets"></a>
-## API > Routing > WebSockets
+<a id="api-http-websockets"></a>
+## API > HTTP > Websocket Server
 
-<a id="api-routing-server-websocket"></a>
 ### 🔧 `server.websocket(path: string, handlers: WebSocketHandlers)`
 
 Register a route which handles websocket connections.
@@ -985,34 +1189,161 @@ server.websocket('/path/to/websocket', {
 > [!IMPORTANT]
 > While it is possible to register multiple routes for websockets, the only handler which is unique per route is `accept()`. The last handlers provided to any route (with the exception of `accept()`) will apply to ALL websocket routes. This is a limitation in Bun.
 
-<a id="api-server-control"></a>
-## API > Server Control
+<a id="api-http-bootstrap"></a>
+## API > HTTP > Bootstrap
 
-<a id="api-server-control-stop"></a>
-### 🔧 `server.stop(immediate: boolean)`
+`spooder` provides a building-block style API with the intention of giving you the blocks to construct a server your way, rather than being shoe-horned into one over-engineered mega-solution which you don't need.
 
-Stop the server process immediately, terminating all in-flight requests.
+For simpler projects, the scaffolding can often look the same, potentially something similar to below.
 
 ```ts
-server.stop(true);
-```
+import { http_serve, cache_http, generate_hash_subs, parse_template, http_apply_range } from 'spooder';
+import path from 'node:path';
 
-Stop the server process gracefully, waiting for all in-flight requests to complete.
+const server = http_serve(80);
+const cache = cache_http({
+	ttl: 5 * 60 * 60 * 1000, // 5 minutes
+	max_size: 5 * 1024 * 1024, // 5 MB
+	use_canary_reporting: true,
+	use_etags: true
+});
 
-```ts
-server.stop(false);
+const base_file = await Bun.file('./html/base_template.html').text();
+const hash_table = await generate_hash_subs();
+
+async function default_handler(status_code: number): Promise<Response> {
+	const error_text = HTTP_STATUS_CODE[status_code] as string;
+	const error_page = await Bun.file('./html/error.html').text();
+
+	const content = await parse_template(error_page, {
+		title: error_text,
+		error_code: status_code.toString(),
+		error_text: error_text
+	}, true);
+
+	return new Response(content, { status: status_code });
+}
+
+server.error((err: Error) => {
+	caution(err?.message ?? err);
+	return default_handler(HTTP_STATUS_CODE.InternalServerError_500);
+});
+
+server.default((req, status_code) => default_handler(status_code));
+
+server.dir('/static', './static', async (file_path, file, stat, request) => {
+	// ignore hidden files by default, return 404 to prevent file sniffing
+	if (path.basename(file_path).startsWith('.'))
+		return HTTP_STATUS_CODE.NotFound_404;
+	
+	if (stat.isDirectory())
+		return HTTP_STATUS_CODE.Unauthorized_401;
+
+	// cache busting
+	const ext = path.extname(file_path);
+	if (ext === '.css' || ext === '.js') {
+		const content = await parse_template(await file.text(), hash_table, true);
+
+		return new Response(content, {
+			headers: {
+				'Content-Type': file.type
+			}
+		});
+	}
+	
+	return http_apply_range(file, request);
+});
+
+function add_route(route: string, file: string, title: string) {
+	server.route(route, async (req) => {
+		return cache.request(req, route, async () => {
+			const file_content = await Bun.file(file).text();
+			const template = await parse_template(base_file, {
+				title: title,
+				content: file_content,
+				...hash_table	
+			}, false);
+
+			return template;
+		});
+	});
+}
+
+add_route('/', './html/index.html', 'Homepage');
+add_route('/about', './html/about.html', 'About Us');
+add_route('/contact', './html/contact.html', 'Contact Us');
+add_route('/privacy', './html/privacy.html', 'Privacy Policy');
+add_route('/terms', './html/terms.html', 'Terms of Service');
 ```
 
-`server.stop()` returns a promise, which if awaited, resolves when all pending connections have been completed.
+For a project where you are looking for fine control, this may be acceptable, but for bootstrapping simple servers this can be a lot of boilerplate. This is where `server.bootstrap` comes in.
+
+### 🔧 `server.bootstrap(options: BootstrapOptions): Promise<void>`
+
+Bootstrap a server using `spooder` utilities with a straight-forward options API, cutting out the boilerplate.
+
 ```ts
-await server.stop(false);
-// do something now all connections are done
+const server = http_serve(80);
+
+server.bootstrap({
+	base: Bun.file('./html/base_template.html'),
+
+	cache: {
+		ttl: 5 * 60 * 60 * 1000, // 5 minutes
+		max_size: 5 * 1024 * 1024, // 5 MB
+		use_canary_reporting: true,
+		use_etags: true
+	},
+
+	error: {
+		use_canary_reporting: true,
+		error_page: Bun.file('./html/error.html')
+	},
+	
+	cache_bust: true,
+
+	static: {
+		directory: './static',
+		route: '/static',
+		sub_ext: ['.css']
+	},
+
+	global_subs: {
+		'project_name': 'Some Project'
+	},
+
+	routes: {
+		'/': {
+			content: Bun.file('./html/index.html'),
+			subs: { 'title': 'Homepage' }
+		},
+
+		'/about': {
+			content: Bun.file('./html/about.html'),
+			subs: { 'title': 'About Us' }
+		},
+
+		'/contact': {
+			content: Bun.file('./html/contact.html'),
+			subs: { 'title': 'Contact Us' }
+		},
+
+		'/privacy': {
+			content: Bun.file('./html/privacy.html'),
+			subs: { 'title': 'Privacy Policy' }
+		},
+
+		'/terms': {
+			content: Bun.file('./html/terms.html'),
+			subs: { 'title': 'Terms of Service' }
+		}
+	}
+});
 ```
 
 <a id="api-error-handling"></a>
 ## API > Error Handling
 
-<a id="api-error-handling-error-with-metadata"></a>
 ### 🔧 `ErrorWithMetadata(message: string, metadata: object)`
 
 The `ErrorWithMetadata` class allows you to attach metadata to errors, which can be used for debugging purposes when errors are dispatched to the canary.
@@ -1027,7 +1358,6 @@ Functions and promises contained in the metadata will be resolved and the return
 throw new ErrorWithMetadata('Something went wrong', { foo: () => 'bar' });
 ```
 
-<a id="api-error-handling-caution"></a>
 ### 🔧 `caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>`
 
 Raise a warning issue on GitHub. This is useful for non-fatal issues which you want to be notified about.
@@ -1086,7 +1416,6 @@ await caution('Error with number ' + some_important_value);
 await caution('Error with number', { some_important_value });
 ```
 
-<a id="api-error-handling-panic"></a>
 ### 🔧 `panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>`
 
 This behaves the same as `caution()` with the difference that once `panic()` has raised the issue, it will exit the process with a non-zero exit code.
@@ -1106,7 +1435,6 @@ try {
 }
 ```
 
-<a id="api-error-handling-safe"></a>
 ### 🔧 `safe(fn: Callable): Promise<void>`
 
 `safe()` is a utility function that wraps a "callable" and calls `caution()` if it throws an error.
@@ -1130,24 +1458,196 @@ await safe(() => {
 });
 ```
 
-<a id="api-content"></a>
-## API > Content
+<a id="api-workers"></a>
+## API > Workers
 
-<a id="api-content-parse-template"></a>
-### 🔧 `parse_template(template: string, replacements: Replacements, drop_missing: boolean): Promise<string>`
+### 🔧 `worker_event_pipe(worker: Worker, options?: WorkerEventPipeOptions): WorkerEventPipe`
 
-Replace placeholders in a template string with values from a replacement object.
+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.
 
 ```ts
-const template = `
-	<html>
-		<head>
-			<title>{$title}</title>
-		</head>
+// main thread
+const worker = new Worker('./some_file.ts');
+const pipe = worker_event_pipe(worker);
+
+pipe.on('bar', data => console.log('Received from worker:', data));
+pipe.send('foo', { x: 42 });
+
+// worker thread
+import { worker_event_pipe } from 'spooder';
+
+const pipe = worker_event_pipe(globalThis as unknown as Worker);
+
+pipe.on('foo', data => {
+	console.log('Received from main:', data); // { x: 42 }
+	pipe.send('bar', { response: 'success' });
+});
+```
+
+### WorkerEventPipeOptions
+
+The second parameter of `worker_event_pipe` accepts an object of options.
+
+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.
+
+### 🔧 `pipe.send(id: string, data?: object): void`
+
+Send a message to the other side of the worker pipe with the specified event ID and optional data payload.
+
+```ts
+pipe.send('user_update', { user_id: 123, name: 'John' });
+pipe.send('simple_event'); // data defaults to {}
+```
+
+### 🔧 `pipe.on(event: string, callback: (data: object) => 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);
+});
+```
+
+> [!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`
+
+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.
+
+```ts
+pipe.once('one_time_event', async (data) => {
+	// this will only fire once
+});
+```
+
+### 🔧 `pipe.off(event: string): void`
+
+Unregister an event handler for events with the specified event ID.
+
+```ts
+pipe.off('event_name');
+```
+
+> [!IMPORTANT]
+> Each worker pipe instance expects to be the sole handler for the worker's message events. Creating multiple pipes for the same worker may result in unexpected behavior.
+
+<a id="api-caching"></a>
+## API > Caching
+
+### 🔧 `cache_http(options?: CacheOptions)`
+
+Initialize a file caching system that stores file contents in memory with configurable TTL, size limits, and ETag support for efficient HTTP caching.
+
+```ts
+import { cache_http } from 'spooder';
+
+const cache = cache_http({
+	ttl: 5 * 60 * 1000 // 5 minutes
+});
+
+// Use with server routes for static files
+server.route('/', cache.file('./index.html'));
+
+// Use with server routes for dynamic content
+server.route('/dynamic', async (req) => cache.request(req, 'dynamic-page', () => 'Dynamic Content'));
+```
+
+The `cache_http()` function returns an object with two methods:
+
+### 🔧 `cache.file(file_path: string)`
+Caches static files from the filesystem. This method reads the file from disk and caches its contents with automatic content-type detection.
+
+```ts
+// Cache a static HTML file
+server.route('/', cache.file('./public/index.html'));
+
+// Cache CSS files
+server.route('/styles.css', cache.file('./public/styles.css'));
+```
+
+### 🔧 `cache.request(req: Request, cache_key: string, content_generator: () => string | Promise<string>): Promise<Response>`
+Caches dynamic content using a cache key and content generator function. The generator function is called only when the cache is cold (empty or expired). This method directly processes requests and returns responses, making it compatible with any request handler.
+
+```ts
+// Cache dynamic HTML content
+server.route('/user/:id', async (req) => {
+	return cache.request(req, '/user', async () => {
+		const userData = await fetchUserData();
+		return generateUserHTML(userData);
+	});
+});
+
+// Cache API responses
+server.route('/api/stats', async (req) => {
+	return cache.request(req, 'stats', () => {
+		return JSON.stringify({ users: getUserCount(), posts: getPostCount() });
+	});
+});
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ttl` | `number` | `18000000` (5 hours) | Time in milliseconds before cached entries expire |
+| `max_size` | `number` | `5242880` (5 MB) | Maximum total size of all cached files in bytes |
+| `use_etags` | `boolean` | `true` | Generate and use ETag headers for cache validation |
+| `headers` | `Record<string, string>` | `{}` | Additional HTTP headers to include in responses |
+| `use_canary_reporting` | `boolean` | `false` | Reports faults to canary (see below).
+
+#### Canary Reporting
+
+If `use_canary_reporting` is enabled, `spooder` will call `caution()` in two scenarios:
+
+1. The cache has exceeded it's maximum capacity and had to purge. If this happens frequently, it is an indication that the maximum capacity should be increased or the use of the cache should be evaluated.
+2. An item cannot enter the cache because it's size is larger than the total size of the cache. This is an indication that either something too large is being cached, or the maximum capacity is far too small.
+
+#### Cache Behavior
+
+- Files are cached for the specified TTL duration.
+- Individual files larger than `max_size` will not be cached
+- When total cache size exceeds `max_size`, expired entries are removed first
+- If still over limit, least recently used (LRU) entries are evicted
+
+**ETag Support:**
+- When `use_etags` is enabled, SHA-256 hashes are generated for file contents
+- ETags enable HTTP 304 Not Modified responses for unchanged files
+- Clients can send `If-None-Match` headers for efficient cache validation
+
+> [!IMPORTANT]
+> The cache uses memory storage and will be lost when the server restarts. It's designed for improving response times of frequently requested files rather than persistent storage.
+
+> [!NOTE]
+> Files are only cached after the first request. The cache performs lazy loading and does not pre-populate files on initialization.
+
+### Raw Cache Access
+
+The internal cache map can be accessed via `cache.entries`. This is exposed primarily for debugging and diagnostics you may wish to implement. It is not recommended that you directly manage this.
+
+<a id="api-templating"></a>
+## API > Templating
+
+### 🔧 `parse_template(template: string, replacements: Replacements, drop_missing: boolean): Promise<string>`
+
+Replace placeholders in a template string with values from a replacement object.
+
+```ts
+const template = `
+	<html>
+		<head>
+			<title>{{title}}</title>
+		</head>
 		<body>
-			<h1>{$title}</h1>
-			<p>{$content}</p>
-			<p>{$ignored}</p>
+			<h1>{{title}}</h1>
+			<p>{{content}}</p>
+			<p>{{ignored}}</p>
 		</body>
 	</html>
 `;
@@ -1168,7 +1668,7 @@ const html = await parse_template(template, replacements);
 	<body>
 		<h1>Hello, world!</h1>
 		<p>This is a test.</p>
-		<p>{$ignored}</p>
+		<p>{{ignored}}</p>
 	</body>
 </html>
 ```
@@ -1199,7 +1699,7 @@ const replacer = (placeholder: string) => {
 	return placeholder.toUpperCase();
 };
 
-await parse_template('Hello {$world}', replacer);
+await parse_template('Hello {{world}}', replacer);
 ```
 
 ```html
@@ -1215,30 +1715,41 @@ await parse_template('Hello {$world}', replacer);
 </html>
 ```
 
-`parse_template` supports optional scopes with the following syntax.
+`parse_template` supports conditional rendering with the following syntax.
 
 ```html
-{$if:foo}I love {$foo}{/if}
+<t-if test="foo">I love {{foo}}</t-if>
 ```
-Contents contained inside an `if` block will be rendered providing the given value, in this case `foo` is truthy in the substitution table.
+Contents contained inside a `t-if` block will be rendered providing the given value, in this case `foo` is truthy in the substitution table.
 
-An `if` block is only removed if `drop_missing` is `true`, allowing them to persist through multiple passes of a template.
+A `t-if` block is only removed if `drop_missing` is `true`, allowing them to persist through multiple passes of a template.
 
 
-`parse_template` supports looping arrays with the following syntax.
+`parse_template` supports looping arrays and objects using the `items` and `as` attributes.
+
+#### Object/Array Looping with `items` and `as` Attributes
 
 ```html
-{$for:foo}My colour is %s{/for}
+<t-for items="items" as="item"><div>{{item.name}}: {{item.value}}</div></t-for>
 ```
+
 ```ts
 const template = `
 	<ul>
-		{$for:foo}<li>%s</li>{/for}
+		<t-for items="colors" as="color">
+			<li class="{{color.type}}">
+				{{color.name}}
+			</li>
+		</t-for>
 	</ul>
 `;
 
 const replacements = {
-	foo: ['red', 'green', 'blue']
+	colors: [
+		{ name: 'red', type: 'warm' },
+		{ name: 'blue', type: 'cool' },
+		{ name: 'green', type: 'neutral' }
+	]
 };
 
 const html = await parse_template(template, replacements);
@@ -1246,19 +1757,37 @@ const html = await parse_template(template, replacements);
 
 ```html
 <ul>
-	<li>red</li>
-	<li>green</li>
-	<li>blue</li>
+	<li class="warm">red</li>
+	<li class="cool">blue</li>
+	<li class="neutral">green</li>
 </ul>
 ```
 
-All placeholders inside a `{$for:}` loop are substituted, but only if the loop variable exists.
+#### Dot Notation Property Access
+
+You can access nested object properties using dot notation:
+
+```ts
+const data = {
+	user: {
+		profile: { name: 'John', age: 30 },
+		settings: { theme: 'dark' }
+	}
+};
+
+await parse_template('Hello {{user.profile.name}}, you prefer {{user.settings.theme}} mode!', data);
+// Result: "Hello John, you prefer dark mode!"
+```
+
+All placeholders inside a `<t-for>` loop are substituted, but only if the loop variable exists.
 
 In the following example, `missing` does not exist, so `test` is not substituted inside the loop, but `test` is still substituted outside the loop.
 
 ```html
-<div>Hello {$test}!</div>
-{$for:missing}<div>Loop {$test}</div>{/for}
+<div>Hello {{test}}!</div>
+<t-for items="missing" as="item">
+	<div>Loop {{test}}</div>
+</t-for>
 ```
 
 ```ts
@@ -1269,10 +1798,11 @@ await parse_template(..., {
 
 ```html
 <div>Hello world!</div>
-{$for}Loop <div>{$test}</div>{/for}
+<t-for items="missing" as="item">
+	<div>Loop {{test}}</div>
+</t-for>
 ```
 
-<a id="api-content-generate-hash-subs"></a>
 ### 🔧 `generate_hash_subs(length: number, prefix: string, hashes?: Record<string, string>): Promise<Record<string, string>>`
 
 Generate a replacement table for mapping file paths to hashes in templates. This is useful for cache-busting static assets.
@@ -1286,7 +1816,7 @@ let hash_sub_table = {};
 generate_hash_subs().then(subs => hash_sub_table = subs).catch(caution);
 
 server.route('/test', (req, url) => {
-	return parse_template('Hello world {$hash=docs/project-logo.png}', hash_sub_table);
+	return parse_template('Hello world {{hash=docs/project-logo.png}}', hash_sub_table);
 });
 ```
 
@@ -1313,11 +1843,10 @@ Use a different prefix other than `hash=` by passing it as the first parameter.
 generate_hash_subs(7, '$#').then(subs => hash_sub_table = subs).catch(caution);
 
 server.route('/test', (req, url) => {
-	return parse_template('Hello world {$#docs/project-logo.png}', hash_sub_table);
+	return parse_template('Hello world {{$#docs/project-logo.png}}', hash_sub_table);
 });
 ```
 
-<a id="api-content-get-git-hashes"></a>
 ### 🔧 ``get_git_hashes(length: number): Promise<Record<string, string>>``
 
 Internally, `generate_hash_subs()` uses `get_git_hashes()` to retrieve the hash table from git. This function is exposed for convenience.
@@ -1340,113 +1869,367 @@ const subs = await generate_hash_subs(7, undefined, hashes);
 // subs[0] -> { 'hash=docs/project-logo.png': '754d9ea' }
 ```
 
-<a id="api-apply-range"></a>
-### 🔧 `apply_range(file: BunFile, request: Request): HandlerReturnType`
+<a id="api-database"></a>
+<a id="api-database-interface"></a>
+## API > Database
 
-`apply_range` parses the `Range` header for a request and slices the file accordingly. This is used internally by `server.dir()` and exposed for convenience.
+### 🔧 ``db_cast_set<T extends string>(set: string | null): Set<T>``
+
+Takes a database SET string and returns a `Set<T>` where `T` is a provided enum.
 
 ```ts
-server.route('/test', (req, url) => {
-	const file = Bun.file('./test.txt');
-	return apply_range(file, req);
-});
+enum ExampleRow {
+	OPT_A = 'OPT_A',
+	OPT_B = 'OPT_B',
+	OPT_C = 'OPT_C'
+};
+
+const set = db_cast_set<ExampleRow>('OPT_A,OPT_B');
+if (set.has(ExampleRow.OPT_B)) {
+	// ...
+}
 ```
 
-```http
-GET /test HTTP/1.1
-Range: bytes=0-5
+### 🔧 ``db_serialize_set<T extends string>(set: Set<T> | null): string``
 
-HTTP/1.1 206 Partial Content
-Content-Length: 6
-Content-Range: bytes 0-5/6
-Content-Type: text/plain;charset=utf-8
+Takes a `Set<T>` and returns a database SET string. If the set is empty or `null`, it returns an empty string.
 
-Hello,
+```ts
+enum ExampleRow {
+	OPT_A = 'OPT_A',
+	OPT_B = 'OPT_B',
+	OPT_C = 'OPT_C'
+};
+
+const set = new Set<ExampleRow>([ExampleRow.OPT_A, ExampleRow.OPT_B]);
+
+const serialized = db_serialize_set(set);
+// > 'OPT_A,OPT_B'
 ```
 
-<a id="api-state-management"></a>
-## API > State Management
+<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.
 
-<a id="api-state-management-set-cookie"></a>
-### 🔧 `set_cookie(res: Response, name: string, value: string, options?: CookieOptions)`
+```ts
+// see: https://bun.sh/docs/api/sqlite
+const db = db_sqlite(':memory:', { create: true });
+db.instance; // raw access to underlying sqlite instance.
+```
 
-Set a cookie onto a `Response` object.
+### 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.
 
 ```ts
-const res = new Response('Cookies!', { status: 200 });
-set_cookie(res, 'my_test_cookie', 'my_cookie_value');
+const result = await db.get_single('BROKEN QUERY');
+if (result !== null) {
+	// do more stuff with result
+}
 ```
 
-```http
-HTTP/1.1 200 OK
-Set-Cookie: my_test_cookie=my_cookie_value
-Content-Length: 8
+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.
 
-Cookies!
+See [API > Database > Schema](#api-database-schema) for information on how schema updating works.
+
+```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]
-> Spooder does not URL encode cookies by default. This can result in invalid cookies if they contain special characters. See `encode` option on `CookieOptions` below.
+> 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
-type CookieOptions = {
-	same_site?: 'Strict' | 'Lax' | 'None',
-	secure?: boolean,
-	http_only?: boolean,
-	path?: string,
-	expires?: number,
-	encode?: boolean,
-	max_age?: number
-};
+// see: https://github.com/mysqljs/mysql#connection-options
+const db = await db_mysql({
+	// ...
+});
+db.instance; // raw access to underlying mysql2 instance.
 ```
 
-Most of the options that can be provided as `CookieOptions` are part of the standard `Set-Cookie` header. See [HTTP Cookies - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies).
+### Error Reporting
 
-Passing `encode` as `true` will URL encode the cookie value.
+In the event of an error from MySQL, an applicable value will be returned from interface functions, rather than the error being thrown.
 
 ```ts
-set_cookie(res, 'my_test_cookie', 'my cookie value', { encode: true });
+const result = await db.get_single('BROKEN QUERY');
+if (result !== null) {
+	// do more stuff with result
+}
 ```
 
-```http
-Set-Cookie: my_test_cookie=my%20cookie%20value
+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);
 ```
 
-<a id="api-state-management-get-cookies"></a>
-### 🔧 `get_cookies(source: Request | Response, decode: boolean = false): Record<string, string>`
+### Pooling
 
-Get cookies from a `Request` or `Response` object.
+MySQL supports connection pooling. This can be configured by providing `true` to the `pool` parameter.
 
-```http
-GET /test HTTP/1.1
-Cookie: my_test_cookie=my_cookie_value
+```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
-const cookies = get_cookies(req);
-{ my_test_cookie: 'my_cookie_value' }
+// 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');
 ```
 
-Cookies are not URL decoded by default. This can be enabled by passing `true` as the second parameter.
+### 🔧 ``db_mysql.insert(sql: string, ...values: any): Promise<number>``
 
-```http
-GET /test HTTP/1.1
-Cookie: my_test_cookie=my%20cookie%20value
+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 cookies = get_cookies(req, true);
-{ my_test_cookie: 'my cookie value' }
+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);
+```
+
+### 🔧 ``db_mysql.count_table(table_name: string): Promise<number>``
+
+Returns the total count of rows from a table. Returns `0` if query fails.
+
+```ts
+const total_users = await db.count_table('users');
+```
+
+### 🔧 ``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');
+}
 ```
 
 <a id="api-database-schema"></a>
-## API > Database Schema
+## API > Database > Schema
 
 `spooder` provides a straightforward API to manage database schema in revisions through source control.
 
-Database schema is updated with `db_update_schema_DRIVER` where `DRIVER` corresponds to the database driver being used.
+```ts
+// sqlite
+db_update_schema_sqlite(db: Database, schema_dir: string, schema_table?: string): Promise<void>;
 
-> [!NOTE]
-> Currently, only SQLite and MySQL are supported. This may be expanded once Bun supports more database drivers.
+// mysql
+db_update_schema_mysql(db: Connection, schema_dir: string, schema_table?: string): Promise<void>;
+```
 
 ```ts
 // sqlite example
@@ -1465,41 +2248,20 @@ 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');
 ```
 
 > [!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.
 
-Database initiation and schema updating can be streamlined with the `db_init_DRIVER` functions. The following examples are equivalent to the above ones.
-
-```ts
-// sqlite example
-import { db_init_sqlite } from 'spooder';
-const db = await db_init_sqlite('./database.sqlite', './schema');
-```
-
-```ts
-// mysql example
-import { db_init_mysql } from 'spooder';
-const db = await db_init_mysql({
-	// connection options
-	// see https://github.com/mysqljs/mysql#connection-options
-}, './schema');
-```
-
-### Pooling
+### Interface API
 
-Providing `true` to the `pool` parameter of `db_init_mysql` will return a connection pool instead of a single connection.
+If you are already using the [database interface API](#api-database-interface) provided by `spooder`, you can call `update_schema()` directly on the interface.
 
 ```ts
-import { db_init_mysql } from 'spooder';
-const pool = await db_init_mysql({
-	// connection options
-	connectionLimit: 10
-}, './schema', true);
-
-const connection = await pool.getConnection();
+const db = await db_mysql({ ... });
+await db.update_schema('./schema');
 ```
 
 ### Schema Files
@@ -1550,7 +2312,7 @@ Each revision should be clearly marked with a comment containing the revision nu
 
 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.
 
-When calling `db_update_schema_sqlite`, unapplied revisions will be applied in ascending order (regardless of order within the file) until the schema is up-to-date.
+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.
 
 It is acceptable to omit keys. This can be useful to prevent repitition when managing stored procedures, views or functions.
 
@@ -1590,7 +2352,7 @@ await db_update_schema_sqlite(db, './schema', 'my_schema_table');
 > 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.
 
 >[!IMPORTANT]
-> `db_update_schema_sqlite` will throw an error if the revisions cannot be parsed or applied for any reason. It is important you catch and handle appropriately.
+> `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.
 
 ```ts
 try {
@@ -1616,6 +2378,21 @@ CREATE ...
 >[!IMPORTANT]
 > Cyclic or missing dependencies will throw an error.
 
+<a id="api-utilities"></a>
+## API > Utilities
+
+### 🔧 ``filesize(bytes: number): string``
+
+Returns a human-readable string representation of a file size in bytes.
+
+```ts
+filesize(512); // > "512 bytes"
+filesize(1024); // > "1 kb"
+filesize(1048576); // > "1 mb"
+filesize(1073741824); // > "1 gb"
+filesize(1099511627776); // > "1 tb"
+```
+
 ## 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.