{"id":18638558,"url":"https://github.com/kruithne/spooder","last_synced_at":"2026-02-03T12:15:03.853Z","repository":{"id":75672394,"uuid":"598627674","full_name":"Kruithne/spooder","owner":"Kruithne","description":"Modular server API for Bun","archived":false,"fork":false,"pushed_at":"2026-01-14T16:26:55.000Z","size":798,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-16T20:12:09.907Z","etag":null,"topics":["bun","http","http-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kruithne.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-07T13:54:58.000Z","updated_at":"2026-01-14T16:26:54.000Z","dependencies_parsed_at":"2026-01-16T08:12:44.925Z","dependency_job_id":null,"html_url":"https://github.com/Kruithne/spooder","commit_stats":null,"previous_names":[],"tags_count":243,"template":false,"template_full_name":null,"purl":"pkg:github/Kruithne/spooder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kruithne%2Fspooder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kruithne%2Fspooder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kruithne%2Fspooder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kruithne%2Fspooder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kruithne","download_url":"https://codeload.github.com/Kruithne/spooder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kruithne%2Fspooder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29045561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","http","http-server"],"created_at":"2024-11-07T05:42:25.398Z","updated_at":"2026-02-03T12:15:03.824Z","avatar_url":"https://github.com/Kruithne.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"docs/project-logo.png\"/\u003e\u003c/p\u003e\n\n# spooder \u0026middot; ![typescript](https://img.shields.io/badge/language-typescript-blue) [![license badge](https://img.shields.io/github/license/Kruithne/spooder?color=yellow)](LICENSE) ![npm version](https://img.shields.io/npm/v/spooder?color=c53635) ![bun](https://img.shields.io/badge/runtime-bun-f9f1e1)\n\n`spooder` is a purpose-built server solution that shifts away from the dependency hell of the Node.js ecosystem, with a focus on stability and performance, which is why:\n- It is built using the [Bun](https://bun.sh/) runtime and not designed to be compatible with Node.js or other runtimes.\n- It uses zero dependencies and only relies on code written explicitly for `spooder` or APIs provided by the Bun runtime, often implemented in native code.\n- It provides streamlined APIs for common server tasks in a minimalistic way, without the overhead of a full-featured web framework.\n- It is opinionated in its design to reduce complexity and overhead.\n\nThe 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.\n\n### spooderverse\nIn 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.\n\n\u003e [!NOTE]\n\u003e 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.\n\nIt consists of two components, the `CLI` and the `API`. \n- 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.\n- The `API` provides a minimal building-block style API for developing servers, with a focus on simplicity and performance.\n\n# Installation\n\n```bash\n# Installing globally for CLI runner usage.\nbun add spooder --global\n\n# Install into local package for API usage.\nbun add spooder\n```\n\n# Configuration\n\nBoth the `CLI` and the API are configured in the same way by providing a `spooder` object in your `package.json` file.\n\nBelow is a full map of the available configuration options in their default states. All configuration options are **optional**.\n\n```jsonc\n{\n\t\"spooder\": {\n\n\t\t// see CLI \u003e Usage\n\t\t\"run\": \"\",\n\t\t\"run_dev\": \"\",\n\n\t\t// see CLI \u003e Auto Restart\n\t\t\"auto_restart\": {\n\t\t\t\"enabled\": false,\n\t\t\t\"backoff_max\": 300000,\n\t\t\t\"backoff_grace\": 30000,\n\t\t\t\"max_attempts\": -1\n\t\t},\n\n\t\t// see CLI \u003e Auto Update\n\t\t\"update\": [\n\t\t\t\"git pull\",\n\t\t\t\"bun install\"\n\t\t],\n\n\t\t// see CLI \u003e Canary\n\t\t\"canary\": {\n\t\t\t\"enabled\": false,\n\t\t\t\"account\": \"\",\n\t\t\t\"repository\": \"\",\n\t\t\t\"labels\": [],\n\t\t\t\"crash_console_history\": 64,\n\t\t\t\"throttle\": 86400,\n\t\t\t\"sanitize\": true\n\t\t}\n\t}\n}\n```\n\nIf there are any issues with the provided configuration, a warning will be printed to the console but will not halt execution. `spooder` will always fall back to default values where invalid configuration is provided.\n\n\u003e [!NOTE]\n\u003e Configuration warnings **do not** raise `caution` events with the `spooder` canary functionality.\n\n# CLI\n\nThe `CLI` component of `spooder` is a global command-line tool for running server processes.\n\n- [CLI \u003e Usage](#cli-usage)\n- [CLI \u003e Dev Mode](#cli-dev-mode)\n- [CLI \u003e Auto Restart](#cli-auto-restart)\n- [CLI \u003e Auto Update](#cli-auto-update)\n- [CLI \u003e Instancing](#cli-instancing)\n- [CLI \u003e Canary](#cli-canary)\n\t- [CLI \u003e Canary \u003e Crash](#cli-canary-crash)\n\t- [CLI \u003e Canary \u003e Sanitization](#cli-canary-sanitization)\n\t- [CLI \u003e Canary \u003e System Information](#cli-canary-system-information)\n\n# API\n\n`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.\n\n- [API \u003e Cheatsheet](#api-cheatsheet)\n- [API \u003e Logging](#api-logging)\n- [API \u003e IPC](#api-ipc)\n- [API \u003e HTTP](#api-http)\n\t- [API \u003e HTTP \u003e Directory Serving](#api-http-directory)\n\t- [API \u003e HTTP \u003e Server-Sent Events (SSE)](#api-http-sse)\n\t- [API \u003e HTTP \u003e Webhooks](#api-http-webhooks)\n\t- [API \u003e HTTP \u003e Websocket Server](#api-http-websockets)\n\t- [API \u003e HTTP \u003e Bootstrap](#api-http-bootstrap)\n\t- [API \u003e HTTP \u003e Cookies](#api-http-cookies)\n- [API \u003e Error Handling](#api-error-handling)\n- [API \u003e Workers](#api-workers)\n- [API \u003e Caching](#api-caching)\n- [API \u003e Templating](#api-templating)\n- [API \u003e Cache Busting](#api-cache-busting)\n- [API \u003e Git](#api-git)\n- [API \u003e Database](#api-database)\n\t- [API \u003e Database \u003e Utilities](#api-database-utilities)\n\t- [API \u003e Database \u003e Schema](#api-database-schema)\n- [API \u003e Utilities](#api-utilities)\n\n# CLI\n\n\u003ca id=\"cli-usage\"\u003e\u003c/a\u003e\n## CLI \u003e Usage\n\nFor convenience, it is recommended that you run this in a `screen` session.\n\n```bash\nscreen -S my-website-about-fish.net\ncd /var/www/my-website-about-fish.net/\nspooder\n```\n\n`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.\n\n```json\n{\n\t\"spooder\": {\n\t\t\"run\": \"bun run my_server.ts\"\n\t}\n}\n```\n\nWhile `spooder` uses a `bun run` command by default, it is possible to use any command string. For example if you wanted to launch a server using `node` instead of `bun`, you could do the following.\n\n```json\n{\n\t\"spooder\": {\n\t\t\"run\": \"node my_server.js\"\n\t}\n}\n```\n\n\u003ca id=\"cli-dev-mode\"\u003e\u003c/a\u003e\n## CLI \u003e Dev Mode\n\n`spooder` can be started in development mode by providing the `--dev` flag when starting the server.\n\n```bash\nspooder --dev\n```\n\nThe following differences will be observed when running in development mode:\n\n- If `run_dev` is configured, it will be used instead of the default `run` command.\n- Update commands defined in `spooder.update` will not be executed when starting a server.\n- 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.\n- If canary is configured, reports will not be dispatched to GitHub and instead be printed to the console; this includes crash reports.\n\nIt is possible to detect in userland if a server is running in development mode by checking the `SPOODER_ENV` environment variable.\n\n```ts\nif (process.env.SPOODER_ENV === 'dev') {\n\t// Server is running in development mode.\n}\n```\n\n### Development Command Override\n\nYou can configure a different command to run when in development mode using the `run_dev` option:\n\n```json\n{\n\t\"spooder\": {\n\t\t\"run\": \"bun run server.ts\",\n\t\t\"run_dev\": \"bun run server.ts --inspect\"\n\t}\n}\n```\n\n\u003e [!NOTE]\n\u003e `SPOODER_ENV` should be either `dev` or `prod`. If the variable is not defined, the server was not started by the `spooder` CLI.\n\n\u003ca id=\"cli-auto-restart\"\u003e\u003c/a\u003e\n## CLI \u003e Auto Restart\n\n\u003e [!NOTE]\n\u003e This feature is not enabled by default.\n\nIn the event that the server process exits, `spooder` can automatically restart it.\n\nIf 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).\n\n```json\n{\n\t\"spooder\": {\n\t\t\"auto_restart\": {\n\t\t\t\"enabled\": true,\n\n\t\t\t// max restarts before giving up\n\t\t\t\"max_attempts\": -1, // default (unlimited)\n\n\t\t\t// max delay (ms) between restart attempts\n\t\t\t\"backoff_max\": 300000, // default 5 min\n\n\t\t\t// grace period after which the backoff protocol\n\t\t\t\"backoff_grace\": 30000 // default 30s\n\t\t}\n\t}\n}\n```\n\nIf 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.\n\n\u003e [!TIP]\n\u003e An **intentional shutdown** can be useful for auto-updating in response to events, such as webhooks.\n\nIf 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).\n\n\u003ca id=\"cli-auto-update\"\u003e\u003c/a\u003e\n## CLI \u003e Auto Update\n\n\u003e [!NOTE]\n\u003e This feature is not enabled by default.\n\nWhen starting or restarting a server process, `spooder` can automatically update the source code in the working directory. To enable this feature, the necessary update commands can be provided in the configuration as an array of strings.\n\n```json\n{\n\t\"spooder\": {\n\t\t\"update\": [\n\t\t\t\"git reset --hard\",\n\t\t\t\"git clean -fd\",\n\t\t\t\"git pull origin main\",\n\t\t\t\"bun install\"\n\t\t]\n\t}\n}\n```\n\nEach command should be a separate entry in the array and will be executed in sequence. The server process will be started once all commands have resolved.\n\n\u003e [!IMPORTANT]\n\u003e Chaining commands using `\u0026\u0026` or `||` operators does not work.\n\nIf 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.\n\nYou can combine this with [Auto Restart](#cli-auto-restart) to automatically update your server in response to a webhook by exiting the process.\n\n```ts\nserver.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload =\u003e {\n\tsetImmediate(async () =\u003e {\n\t\tawait server.stop(false);\n\t\tprocess.exit(0);\n\t});\n\treturn HTTP_STATUS_CODE.OK_200;\n});\n```\n\n### Multi-Instance Auto Update\n\nSee [Instancing](#cli-instancing) for instructions on how to use [Auto Update](#cli-auto-update) with multiple instances.\n\n### Skip Updates\n\nIn addition to being skipped in [dev mode](#cli-dev-mode), updates can also be skipped in production mode by passing the `--no-update` flag.\n\n\u003ca id=\"cli-instancing\"\u003e\u003c/a\u003e\n## CLI \u003e Instancing\n\n\u003e [!NOTE]\n\u003e This feature is not enabled by default.\n\nBy 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.\n\nThis can be configured in `spooder` using the `instances` array, with each entry defining a unique instance.\n\n```json\n\"spooder\": {\n\t\"instances\": [\n\t\t{\n\t\t\t\"id\": \"dev01\",\n\t\t\t\"run\": \"bun run --env-file=.env.a index.ts\",\n\t\t\t\"run_dev\": \"bun run --env-file=.env.a.dev index.ts --inspect\"\n\t\t},\n\t\t{\n\t\t\t\"id\": \"dev02\",\n\t\t\t\"run\": \"bun run --env-file=.env.b index.ts\",\n\t\t\t\"run_dev\": \"bun run --env-file=.env.b.dev index.ts --inspect\"\n\t\t}\n\t]\n}\n```\n\nInstances will be managed individually in the same manner that a single process would be, including auto-restarting and other functionality.\n\n### Instance Environment\n\nEach instance can define custom environment variables using the `env` property. These variables are merged with the parent process environment and passed to the spawned instance.\n\n```json\n\"spooder\": {\n\t\"instances\": [\n\t\t{\n\t\t\t\"id\": \"foo\",\n\t\t\t\"run\": \"bun run server.ts\",\n\t\t\t\"env\": { \"ENVTEST\": \"foo\" }\n\t\t},\n\t\t{\n\t\t\t\"id\": \"bar\",\n\t\t\t\"run\": \"bun run server.ts\",\n\t\t\t\"env\": { \"ENVTEST\": \"bar\" }\n\t\t}\n\t]\n}\n```\n\nEnvironment variable precedence (highest to lowest):\n1. `SPOODER_ENV` - always set by spooder (`dev` or `prod`)\n2. Instance `env` - overrides parent environment\n3. Parent process environment - inherited from spooder\n\n### Instance Stagger\n\nBy 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.\n\nThis interval effects both server start-up, auto-restarting and crash recovery. No two instances will be launched within that interval regardless of the reason.\n\n### Canary\n\nThe [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.\n\nThis allows you to define custom properties on the instance which will be included as part of the crash report.\n\n```json\n{\n\t\"id\": \"dev01\",\n\t\"run\": \"bun run --env-file=.env.a index.ts\",\n\t\"sub_domain\": \"dev01.spooder.dev\" // custom, for diagnostics\n}\n```\n\n\u003e ![IMPORTANT]\n\u003e 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.\n\n### Multi-instance Auto Restart\n\nCombining [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.\n\nIn 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.\n\nA 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.\n\nThe solution is to the use the [IPC](#api-ipc) to instruct the host process to handle this.\n\n```ts\nserver.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload =\u003e {\n\tsetImmediate(async () =\u003e {\n\t\tipc_send(IPC_TARGET.SPOODER, IPC_OP.CMSG_TRIGGER_UPDATE);\n\t});\n\treturn HTTP_STATUS_CODE.OK_200;\n});\n\nipc_register(IPC_OP.SMSG_UPDATE_READY, async () =\u003e {\n\tawait server.stop(false);\n\tprocess.exit(EXIT_CODE.SPOODER_AUTO_UPDATE);\n});\n```\n\nIn 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.\n\nExiting 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.\n\n\u003ca id=\"cli-canary\"\u003e\u003c/a\u003e\n## CLI \u003e Canary\n\n\u003e [!NOTE]\n\u003e This feature is not enabled by default.\n\n`canary` is a feature in `spooder` which allows server problems to be raised as issues in your repository on GitHub.\n\nTo 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.\n\n\u003cdetails\u003e\n\u003csummary\u003eGitHub App Setup\u003c/summary\u003e\n\nCreate a new GitHub App either on your personal account or on an organization. The app will need the following permissions:\n\n- **Issues** - Read \u0026 Write\n- **Metadata** - Read-only\n\nOnce created, install the GitHub App to your account. The app will need to be given access to the repositories you want to use the canary feature with.\n\nIn addition to the **App ID** that is assigned automatically, you will also need to generate a **Private Key** for the app. This can be done by clicking the **Generate a private key** button on the app page.\n\n\u003e [!NOTE]\n\u003e The private keys provided by GitHub are in PKCS#1 format, but only PKCS#8 is supported. You can convert the key file with the following command.\n\n```bash\nopenssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private-key.pem -out private-key-pkcs8.key\n```\n\nEach server that intends to use the canary feature will need to have the private key installed somewhere the server process can access it.\n\u003c/details\u003e\n\n### Configure Canary\n\n```json\n\"spooder\": {\n\t\"canary\": {\n\t\t\"enabled\": true,\n\t\t\"account\": \"\u003cGITHUB_ACCOUNT_NAME\u003e\",\n\t\t\"repository\": \"\u003cGITHUB_REPOSITORY\u003e\",\n\t\t\"labels\": [\"some-label\"]\n\t}\n}\n```\n\nReplace `\u003cGITHUB_ACCOUNT_NAME\u003e` with the account name you have installed the GitHub App to, and `\u003cGITHUB_REPOSITORY\u003e` with the repository name you want to use for issues.\n\nThe repository name must in the full-name format `owner/repo` (e.g. `facebook/react`).\n\nThe `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.\n\n### Setup Environment Variables\n\nThe following two environment variables must be defined on the server.\n\n```\nSPOODER_CANARY_APP_ID=1234\nSPOODER_CANARY_KEY=/home/bond/.ssh/id_007_pcks8.key\n```\n\n`SPOODER_CANARY_APP_ID` is the **App ID** as shown on the GitHub App page.\n\n`SPOODER_CANARY_KEY` is the path to the private key file in PKCS#8 format.\n\n\u003e [!NOTE]\n\u003e 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.\n\n### Using Canary\n\nOnce configured, `spooder` will automatically raise an issue when the server exits with a non-zero exit code. \n\nIn addition, you can manually raise issues using the `spooder` API by calling `caution()` or `panic()`. More information about these functions can be found in the `API` section.\n\nIf `canary` has not been configured correctly, `spooder` will only print warnings to the console when it attempts to raise an issue.\n\n\u003e [!WARNING]\n\u003e Consider testing the canary feature with the `caution()` function before relying on it for critical issues.\n\n\u003ca id=\"cli-canary-crash\"\u003e\u003c/a\u003e\n## CLI \u003e Canary \u003e Crash\n\nIt is recommended that you harden your server code against unexpected exceptions and use `panic()` and `caution()` to raise issues with selected diagnostic information.\n\nIn the event that the server does encounter an unexpected exception which causes it to exit with a non-zero exit code, `spooder` will provide some diagnostic information in the canary report.\n\nSince this issue has been caught externally, `spooder` has no context of the exception which was raised. Instead, the canary report will contain the output from both `stdout` and `stderr`.\n\n```json\n{\n\t\"proc_exit_code\": 1,\n\t\"console_output\": [\n\t\t\"[2.48ms] \\\".env.local\\\"\",\n\t\t\"Test output\",\n\t\t\"Test output\",\n\t\t\"4 | console.warn('Test output');\",\n\t\t\"5 | \",\n\t\t\"6 | // Create custom error class.\",\n\t\t\"7 | class TestError extends Error {\",\n\t\t\"8 | \tconstructor(message: string) {\",\n\t\t\"9 | \t\tsuper(message);\",\n\t\t\"     ^\",\n\t\t\"TestError: Home is [IPv4 address]\",\n\t\t\"      at new TestError (/mnt/i/spooder/test.ts:9:2)\",\n\t\t\"      at /mnt/i/spooder/test.ts:13:6\",\n\t\t\"\"\n\t]\n}\n```\n\nThe `proc_exit_code` property contains the exit code that the server exited with.\n\nThe `console_output` will contain the last `64` lines of output from `stdout` and `stderr` combined. This can be configured by setting the `spooder.canary.crash_console_history` property to a length of your choice.\n\n```json\n{\n\t\"spooder\": {\n\t\t\"canary\": {\n\t\t\t\"crash_console_history\": 128\n\t\t}\n\t}\n}\n```\n\nThis information is subject to sanitization, as described in the `CLI \u003e Canary \u003e Sanitization` section, however you should be aware that stack traces may contain sensitive information.\n\nSetting `spooder.canary.crash_console_history` to `0` will omit the `console_output` property from the report entirely, which may make it harder to diagnose the problem but will ensure that no sensitive information is leaked.\n\n\u003ca id=\"cli-canary-sanitization\"\u003e\u003c/a\u003e\n## CLI \u003e Canary \u003e Sanitization\n\nAll reports sent via the canary feature are sanitized to prevent sensitive information from being leaked. This includes:\n\n- Environment variables from `.env.local`\n- IPv4 / IPv6 addresses.\n- E-mail addresses.\n\n```bash\n# .env.local\nDB_PASSWORD=secret\n```\n\n```ts\nawait panic({\n\ta: 'foo',\n\tb: process.env.DB_PASSWORD,\n\tc: 'Hello person@place.net',\n\td: 'Client: 192.168.1.1'\n});\n```\n\n```json\n[\n\t{\n\t\t\"a\": \"foo\",\n\t\t\"b\": \"[redacted]\",\n\t\t\"c\": \"Hello [e-mail address]\",\n\t\t\"d\": \"Client: [IPv4 address]\"\n\t}\n]\n```\n\nThe sanitization behavior can be disabled by setting `spooder.canary.sanitize` to `false` in the configuration. This is not recommended as it may leak sensitive information.\n\n```json\n{\n\t\"spooder\": {\n\t\t\"canary\": {\n\t\t\t\"sanitize\": false\n\t\t}\n\t}\n}\n```\n\n\u003e [!WARNING]\n\u003e While this sanitization adds a layer of protection against information leaking, it does not catch everything. You should pay special attention to messages and objects provided to the canary to not unintentionally leak sensitive information.\n\n\u003ca id=\"cli-canary-system-information\"\u003e\u003c/a\u003e\n## CLI \u003e Canary \u003e System Information\n\nIn addition to the information provided by the developer, `spooder` also includes some system information in the canary reports.\n\n```json\n{\n\t\"loadavg\": [\n\t\t0,\n\t\t0,\n\t\t0\n\t],\n\t\"memory\": {\n\t\t\"free\": 7620907008,\n\t\t\"total\": 8261840896\n\t},\n\t\"platform\": \"linux\",\n\t\"uptime\": 7123,\n\t\"versions\": {\n\t\t\"node\": \"18.15.0\",\n\t\t\"bun\": \"0.6.5\",\n\t\t\"webkit\": \"60d11703a533fd694cd1d6ddda04813eecb5d69f\",\n\t\t\"boringssl\": \"b275c5ce1c88bc06f5a967026d3c0ce1df2be815\",\n\t\t\"libarchive\": \"dc321febde83dd0f31158e1be61a7aedda65e7a2\",\n\t\t\"mimalloc\": \"3c7079967a269027e438a2aac83197076d9fe09d\",\n\t\t\"picohttpparser\": \"066d2b1e9ab820703db0837a7255d92d30f0c9f5\",\n\t\t\"uwebsockets\": \"70b1b9fc1341e8b791b42c5447f90505c2abe156\",\n\t\t\"zig\": \"0.11.0-dev.2571+31738de28\",\n\t\t\"zlib\": \"885674026394870b7e7a05b7bf1ec5eb7bd8a9c0\",\n\t\t\"tinycc\": \"2d3ad9e0d32194ad7fd867b66ebe218dcc8cb5cd\",\n\t\t\"lolhtml\": \"2eed349dcdfa4ff5c19fe7c6e501cfd687601033\",\n\t\t\"ares\": \"0e7a5dee0fbb04080750cf6eabbe89d8bae87faa\",\n\t\t\"usockets\": \"fafc241e8664243fc0c51d69684d5d02b9805134\",\n\t\t\"v8\": \"10.8.168.20-node.8\",\n\t\t\"uv\": \"1.44.2\",\n\t\t\"napi\": \"8\",\n\t\t\"modules\": \"108\"\n\t},\n\t\"bun\": {\n\t\t\"version\": \"0.6.5\",\n\t\t\"rev\": \"f02561530fda1ee9396f51c8bc99b38716e38296\",\n\t\t\"memory_usage\": {\n\t\t\t\"rss\": 99672064,\n\t\t\t\"heapTotal\": 3039232,\n\t\t\t\"heapUsed\": 2332783,\n\t\t\t\"external\": 0,\n\t\t\t\"arrayBuffers\": 0\n\t\t},\n\t\t\"cpu_usage\": {\n\t\t\t\"user\": 50469,\n\t\t\t\"system\": 0\n\t\t}\n\t}\n}\n```\n\n# API\n\n\u003ca id=\"api-cheatsheet\"\u003e\u003c/a\u003e\n## API \u003e Cheatsheet\n\n```ts\n// logging\nlog(message: string, ...params: any[]);\nlog_error(message: string, ...params: any[]);\nlog_create_logger(prefix: string, color: ColorInput);\nlog_list(input: any[], delimiter = ', ');\n\n// http\nhttp_serve(port: number, hostname?: string): Server;\nserver.port: number;\nserver.stop(immediate: boolean): Promise\u003cvoid\u003e;\n\n// cookies\ncookies_get(req: Request): Bun.CookieMap\n\n// routing\nserver.route(path: string, handler: RequestHandler, method?: HTTP_METHODS);\nserver.json(path: string, handler: JSONRequestHandler, method?: HTTP_METHODS);\nserver.throttle(delta: number, handler: JSONRequestHandler|RequestHandler);\nserver.unroute(path: string);\n\n// fallback handlers\nserver.handle(status_code: number, handler: RequestHandler);\nserver.default(handler: DefaultHandler);\nserver.error(handler: ErrorHandler);\nserver.on_slow_request(callback: SlowRequestCallback, threshold?: number);\nserver.allow_slow_request(req: Request);\n\n// http generics\nhttp_apply_range(file: BunFile, request: Request): HandlerReturnType;\n\n// directory serving\nserver.dir(path: string, dir: string, options?: DirOptions | DirHandler, method?: HTTP_METHODS);\n\n// server-sent events\nserver.sse(path: string, handler: ServerSentEventHandler);\n\n// webhooks\nserver.webhook(secret: string, path: string, handler: WebhookHandler, branches?: string | string[]);\n\n// websockets\nserver.websocket(path: string, handlers: WebsocketHandlers);\n\n// bootstrap\nserver.bootstrap(options: BootstrapOptions): Promise\u003cvoid\u003e;\n\n// error handling\nErrorWithMetadata(message: string, metadata: object);\ncaution(err_message_or_obj: string | object, ...err: object[]): Promise\u003cvoid\u003e;\npanic(err_message_or_obj: string | object, ...err: object[]): Promise\u003cvoid\u003e;\nsafe(fn: Callable): Promise\u003cvoid\u003e;\n\n// worker (main thread)\nworker_pool(options: WorkerPoolOptions): Promise\u003cWorkerPool\u003e;\npool.id: string;\npool.send: (peer: string, id: string, data?: WorkerMessageData) =\u003e void;\npool.broadcast: (id: string, data?: WorkerMessageData) =\u003e void;\npool.on: (event: string, callback: (message: WorkerMessage) =\u003e Promise\u003cvoid\u003e | void) =\u003e void;\npool.once: (event: string, callback: (message: WorkerMessage) =\u003e Promise\u003cvoid\u003e | void) =\u003e void;\npool.off: (event: string) =\u003e void;\n\ntype WorkerPoolOptions = {\n\tid?: string;\n\tworker: string | string[];\n\tsize?: number;\n\tauto_restart?: boolean | AutoRestartConfig;\n\tonWorkerStart?: (pool: WorkerPool, worker_id: string) =\u003e void;\n\tonWorkerStop?: (pool: WorkerPool, worker_id: string, exit_code: number) =\u003e void;\n};\n\ntype AutoRestartConfig = {\n\tbackoff_max?: number; // default: 5 * 60 * 1000 (5 min)\n\tbackoff_grace?: number; // default: 30000 (30 seconds)\n\tmax_attempts?: number; // default: 5, -1 for unlimited\n};\n\n// worker (worker thread)\nworker_connect(peer_id?: string): WorkerPool;\n\n// templates\nReplacements = Record\u003cstring, string | Array\u003cstring\u003e | object | object[]\u003e | ReplacerFn | AsyncReplaceFn;\nparse_template(template: string, replacements: Replacements, drop_missing?: boolean): Promise\u003cstring\u003e;\n\n// cache busting\ncache_bust(string|string[]: path, format: string): string|string[]\ncache_bust_set_hash_length(length: number): void;\ncache_bust_set_format(format: string): void;\ncache_bust_get_hash_table(): Record\u003cstring, string\u003e;\n\n// git\ngit_get_hashes(length: number): Promise\u003cRecord\u003cstring, string\u003e\u003e;\ngit_get_hashes_sync(length: number): Record\u003cstring, string\u003e;\n\n// database utilities\ndb_set_cast\u003cT extends string\u003e(set: string | null): Set\u003cT\u003e;\ndb_set_serialize\u003cT extends string\u003e(set: Iterable\u003cT\u003e | null): string;\ndb_exists(db: SQL, table_name: string, value: string|number, column_name = 'id'): Promise\u003cboolean\u003e;\n\n// database schema\ntype SchemaOptions = {\n\tschema_table?: string;\n\trecursive?: boolean;\n};\n\ndb_get_schema_revision(db: SQL): Promise\u003cnumber|null\u003e;\ndb_schema(db: SQL, schema_path: string, options?: SchemaOptions): Promise\u003cboolean\u003e;\n\n// caching\ncache_http(options?: CacheOptions);\ncache.file(file_path: string): RequestHandler;\ncache.request(req: Request, cache_key: string, content_generator: () =\u003e string | Promise\u003cstring\u003e): Promise\u003cResponse\u003e;\n\n// utilities\nfilesize(bytes: number): string;\nBiMap: class BiMap\u003cK, V\u003e;\n\n// ipc\nipc_register(op: number, callback: IPC_Callback);\nipc_send(target: string, op: number, data?: object);\n\n// constants\nHTTP_STATUS_TEXT: Record\u003cnumber, string\u003e;\nHTTP_STATUS_CODE: { OK_200: 200, NotFound_404: 404, ... };\nEXIT_CODE: Record\u003cstring, number\u003e;\nEXIT_CODE_NAMES: Record\u003cnumber, string\u003e;\nIPC_TARGET: Record\u003cstring, string\u003e;\nIPC_OP: Record\u003cstring, number\u003e;\n```\n\n\u003ca id=\"api-logging\"\u003e\u003c/a\u003e\n## API \u003e Logging\n\n### 🔧 `log(message: string, ...params: any[])`\nPrint a message to the console using the default logger. Wrapping text segments in curly braces will highlight those segments with colour.\n\n```ts\nlog('Hello, {world}!');\n// \u003e [info] Hello, world!\n```\n\nTagged template literals are also supported and automatically highlights values without the brace syntax.\n\n```ts\nconst user = 'Fred';\nlog`Hello ${user}!`;\n```\n\nFormatting parameters are supported using standard console logging formatters.\n\n```ts\nlog('My object: %o', { foo: 'bar' });\n// \u003e [info] My object: { foo: 'bar' }\n```\n\n| Specifier | Description |\n|-----------|-------------|\n| `%s` | String |\n| `%d` | Integer |\n| `%i` | Integer (same as %d) |\n| `%f` | Floating point |\n| `%o` | Object (pretty-printed) |\n| `%O` | Object (expanded/detailed) |\n| `%j` | JSON string |\n\n### 🔧 `log_error(message: string, ...params: any[])`\nPrint 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.\n\n```ts\nlog_error('Something went {really} wrong');\n// \u003e [error] Something went really wrong\n```\n\n### 🔧 `log_create_logger(prefix: string, color: ColorInput)`\nCreate a `log()` function with a custom prefix and highlight colour.\n\n```ts\nconst db_log = log_create_logger('db', 'pink');\ndb_log('Creating table {users}...');\n```\n\n\u003e [!INFO]\n\u003e For information about `ColorInput`, see the [Bun Color API](https://bun.sh/docs/api/color).\n\n\n### 🔧 `log_list(input: any[], delimiter = ', ')`\nUtility function that joins an array of items together with each element wrapped in highlighting syntax for logging.\n\n```ts\nconst fruit = ['apple', 'orange', 'peach'];\nlog(`Fruit must be one of ${fruit.map(e =\u003e `{${e}}`).join(', ')}`);\nlog(`Fruit must be one of ${log_list(fruit)}`);\n```\n\n\u003ca id=\"api-ipc\"\u003e\u003c/a\u003e\n## API \u003e IPC\n\n`spooder` provides a way to send/receive messages between different instances via IPC. See [CLI \u003e Instancing](#cli-instancing) for documentation on instances.\n\n```ts\n// listen for a message\nipc_register(0x1, msg =\u003e {\n\t// msg.peer, msg.op, msg.data\n\tconsole.log(msg.data.foo); // 42\n});\n\n// send a message to dev02\nipc_send('dev02', 0x1, { foo: 42 });\n\n// send a message to all other instances\nipc_send(IPC_TARGET.BROADCAST, 0x1, { foo: 42 });\n```\n\nThis can also be used to communicate with the host process for certain functionality, such as [auto-restarting](#cli-auto-restart).\n\n#### OpCodes\n\nWhen sending/receiving IPC messages, the message will include an opcode. When communicating with the host process, that will be one of the following:\n\n```ts\nIPC_OP.CMSG_TRIGGER_UPDATE = -1;\nIPC_OP.SMSG_UPDATE_READY = -2;\nIPC_OP.CMSG_REGISTER_LISTENER = -3; // used internally by ipc_register\n```\n\nWhen 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.\n\n### `ipc_register(op: number, callback: IPC_Callback)`\n\nRegister a listener for IPC events. The callback will receive an object with this structure:\n\n```ts\ntype IPC_Message = {\n\top: number; // opcode received\n\tpeer: string; // sender\n\tdata?: object // payload data (optional)\n};\n```\n\n### `ipc_send(peer: string, op: number, data?: object)`\n\nSend 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.\n\n```ts\nIPC_TARGET.SPOODER; // communicate with the host\nIPC_TARGET.BROADCAST; // broadcast to all other instances\n```\n\n\u003ca id=\"api-http\"\u003e\u003c/a\u003e\n## API \u003e HTTP\n\n### `http_serve(port: number, hostname?: string): Server`\nBootstrap a server on the specified port (and optional hostname). Pass `0` for the port to assign a random available port, which can then be retrieved via `server.port`.\n\n```ts\nimport { serve } from 'spooder';\n\nconst server = http_serve(8080); // port only\nconst server = http_serve(3000, '0.0.0.0'); // optional hostname\nconst server = http_serve(0); // random port, retrieve via server.port\n```\n\nBy default, the server responds with:\n\n```http\nHTTP/1.1 404 Not Found\nContent-Length: 9\nContent-Type: text/plain;charset=utf-8\n\nNot Found\n```\n\n### 🔧 `server.stop(immediate: boolean)`\n\nStop the server process immediately, terminating all in-flight requests.\n\n```ts\nserver.stop(true);\n```\n\nStop the server process gracefully, waiting for all in-flight requests to complete.\n\n```ts\nserver.stop(false);\n```\n\n`server.stop()` returns a promise, which if awaited, resolves when all pending connections have been completed.\n```ts\nawait server.stop(false);\n// do something now all connections are done\n```\n\n### 📖 `server.port`\n\nReturns the port the server is listening on. Useful when `0` is passed to `http_serve()` for a random port assignment.\n\n```ts\nconst server = http_serve(0);\nconsole.log(`Server listening on port ${server.port}`);\n```\n\n### Routing\n\n### 🔧 `server.route(path: string, handler: RequestHandler)`\n\nRegister a handler for a specific path.\n\n```ts\nserver.route('/test/route', (req, url) =\u003e {\n\treturn new Response('Hello, world!', { status: 200 });\n});\n```\n\n### 🔧 `server.unroute(path: string)`\n\nUnregister a specific route.\n\n```ts\nserver.route('/test/route', () =\u003e {});\nserver.unroute('/test/route');\n```\n\n### 🔧 `server.throttle(delta: number, handler: JSONRequestHandler|RequestHandler)`\n\nThrottles requests going through the provided handler so that they take a **minimum** of `delta` milliseconds. Useful for preventing brute-force of sensitive endpoints.\n\n\u003e [!IMPORTANT]\n\u003e This is a rudimentary countermeasure for brute-force attacks, **not** a defence against timing-attacks. Always use constant-time/timing-safe comparison functions in sensitive endpoints.\n\n```ts\nserver.json('/api/login', server.throttle(1000, (req, url, json) =\u003e {\n\t// this endpoint will always take at least 1000ms to execute\n}));\n\n// works with regular routes\nserver.route('/reset-password', server.throttle(1000, (req, url) =\u003e {\n\t// this route will also take at least 1000ms to execute\n}));\n```\n\n### 🔧 `server.json(path: string, handler: JSONRequestHandler, method?: HTTP_METHODS)`\n\nRegister 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.\n\n```ts\nserver.json('/api/users', (req, url, json) =\u003e {\n\t// json is automatically parsed and validated as a plain object\n\tconst name = json.name;\n\tconst email = json.email;\n\t\n\t// Process the JSON data\n\treturn { success: true, id: 123 };\n});\n```\n\nBy default, JSON routes are registered as `POST` endpoints, but this can be customized:\n\n```ts\nserver.json('/api/data', (req, url, json) =\u003e {\n\treturn { received: json };\n}, 'PUT');\n```\n\nThe handler will automatically return `400 Bad Request` if:\n- The `Content-Type` header is not `application/json`\n- The request body is not valid JSON\n- The JSON is not a plain object (e.g., it's an array, null, or primitive value)\n\n### HTTP Methods\n\nBy 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`.\n\n\u003e [!NOTE]\n\u003e spooder does not automatically handle HEAD requests natively.\n\nThis can be controlled by providing the `method` parameter with a string or array defining one or more of the following methods.\n\n```\nGET | HEAD | POST | PUT | DELETE | CONNECT | OPTIONS | TRACE | PATCH\n```\n\n```ts\nserver.route('/test/route', (req, url) =\u003e {\n\tif (req.method === 'GET')\n\t\t// Handle GET request.\n\telse if (req.method === 'POST')\n\t\t// Handle POST request.\n}, ['GET', 'POST']);\n```\n\n\u003e [!NOTE]\n\u003e Routes defined with .sse() or .webhook() are always registered as 'GET' and 'POST' respectively and cannot be configured.\n\n### Redirection Routes\n\n`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.\n\n```ts\nserver.route('/redirect', () =\u003e Response.redirect('/redirected', HTTP_STATUS_CODE.MovedPermanently_301));\n```\n\n### Status Code Text\n\n`spooder` exposes `HTTP_STATUS_TEXT` to conveniently access status code text, and `HTTP_STATUS_CODE` for named status code constants.\n\n```ts\nimport { HTTP_STATUS_TEXT, HTTP_STATUS_CODE } from 'spooder';\n\nserver.default((req, status_code) =\u003e {\n\t// status_code: 404\n\t// Body: Not Found\n\treturn new Response(HTTP_STATUS_TEXT[status_code], { status: status_code });\n});\n\n// Using named constants for better readability\nserver.route('/api/users', (req, url) =\u003e {\n\tif (!isValidUser(req))\n\t\treturn HTTP_STATUS_CODE.Unauthorized_401;\n\t\n\t// Process user request\n\treturn HTTP_STATUS_CODE.OK_200;\n});\n```\n\n### RequestHandler\n\n`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`.\n\n`HandlerReturnType` must be one of the following.\n\n| Type | Description |\n| --- | --- |\n| `Response` | https://developer.mozilla.org/en-US/docs/Web/API/Response |\n| `Blob` | https://developer.mozilla.org/en-US/docs/Web/API/Blob |\n| `BunFile` | https://bun.sh/docs/api/file-io |\n| `object` | Will be serialized to JSON. |\n| `string` | Will be sent as `text/html``. |\n| `number` | Sets status code and sends status message as plain text. |\n\n\u003e [!NOTE]\n\u003e For custom JSON serialization on an object/class, implement the [`toJSON()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) method.\n\n`HandleReturnType` can also be a promise resolving to any of the above types, which will be awaited before sending the response.\n\n\u003e [!NOTE]\n\u003e 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.\n\n### Query Parameters\n\nQuery parameters can be accessed from the `searchParams` property on the `URL` object.\n\n```ts\nserver.route('/test', (req, url) =\u003e {\n\treturn new Response(url.searchParams.get('foo'), { status: 200 });\n});\n```\n\n```http\nGET /test?foo=bar HTTP/1.1\n\nHTTP/1.1 200 OK\nContent-Length: 3\n\nbar\n```\n\nNamed parameters can be used in paths by prefixing a path segment with a colon.\n\n\u003e [!IMPORTANT]\n\u003e Named parameters will overwrite existing query parameters with the same name.\n\n```ts\nserver.route('/test/:param', (req, url) =\u003e {\n\treturn new Response(url.searchParams.get('param'), { status: 200 });\n});\n```\n\n### Wildcards\n\nWildcards can be used to match any path that starts with a given path.\n\n\u003e [!NOTE]\n\u003e If you intend to use this for directory serving, you may be better suited looking at the `server.dir()` function.\n\n```ts\nserver.route('/test/*', (req, url) =\u003e {\n\treturn new Response('Hello, world!', { status: HTTP_STATUS_CODE.OK_200 });\n});\n```\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n```ts\nserver.route('/*', () =\u003e HTTP_STATUS_CODE.MovedPermanently_301);\nserver.route('/test', () =\u003e HTTP_STATUS_CODE.OK_200);\n\n// Accessing /test returns 301 here, because /* matches /test first.\n```\n\n### Fallback Handlers\n\n### 🔧 `server.handle(status_code: number, handler: RequestHandler)`\nRegister a custom handler for a specific status code.\n```ts\nserver.handle(HTTP_STATUS_CODE.InternalServerError_500, (req) =\u003e {\n\treturn new Response('Custom Internal Server Error Message', { status: HTTP_STATUS_CODE.InternalServerError_500 });\n});\n```\n\n### 🔧 `server.default(handler: DefaultHandler)`\nRegister a handler for all unhandled response codes.\n\u003e [!NOTE]\n\u003e If you return a `Response` object from here, you must explicitly set the status code.\n```ts\nserver.default((req, status_code) =\u003e {\n\treturn new Response(`Custom handler for: ${status_code}`, { status: status_code });\n});\n```\n\n### 🔧 `server.error(handler: ErrorHandler)`\nRegister a handler for uncaught errors.\n\n\u003e [!NOTE]\n\u003e Unlike other handlers, this should only return `Response` or `Promise\u003cResponse\u003e`.\n```ts\nserver.error((err, req, url) =\u003e {\n\treturn new Response('Custom Internal Server Error Message', { status: HTTP_STATUS_CODE.InternalServerError_500 });\n});\n```\n\n\u003e [!IMPORTANT]\n\u003e It is highly recommended to use `caution()` or some form of reporting to notify you when this handler is called, as it means an error went entirely uncaught.\n\n```ts\nserver.error((err, req, url) =\u003e {\n\t// Notify yourself of the error.\n\tcaution({ err, url });\n\n\t// Return a response to the client.\n\treturn new Response('Custom Internal Server Error Message', { status: HTTP_STATUS_CODE.InternalServerError_500 });\n});\n```\n\n### Slow Requests\n\n### 🔧 `server.on_slow_request(callback: SlowRequestCallback, threshold: number)`\n\n`server.on_slow_request` can be used to register a callback for requests that take an undesirable amount of time to process.\n\nBy default requests that take longer than `1000ms` to process will trigger the callback, but this can be adjusted by providing a custom threshold.\n\n\u003e [!IMPORTANT]\n\u003e If your canary reports to a public repository, be cautious about directly including the `req` object in the callback. This can lead to sensitive information being leaked.\n\n```ts\nserver.on_slow_request(async (req, time, url) =\u003e {\n\t// avoid `time` in the title to avoid canary spam\n\t// see caution() API for information\n\tawait caution('Slow request warning', { req, time });\n}, 500);\n```\n\n\u003e [!NOTE]\n\u003e The callback is not awaited internally, so you can use `async/await` freely without blocking the server/request.\n\n### 🔧 `server.allow_slow_request(req: Request)`\n\nIn some scenarios, mitigation throttling or heavy workloads may cause slow requests intentionally. To prevent these triggering a caution, requests can be marked as slow.\n\n```ts\nserver.on_slow_request(async (req, time, url) =\u003e {\n\tawait caution('Slow request warning', { req, time });\n}, 500);\n\nserver.route('/test', async (req) =\u003e {\n\t// this request is marked as slow, therefore won't\n\t// trigger on_slow_request despite taking 5000ms+\n\tserver.allow_slow_request(req);\n\tawait new Promise(res =\u003e setTimeout(res, 5000));\n});\n```\n\n\u003e [!NOTE]\n\u003e This will have no effect if a handler hasn't been registered with `on_slow_request`.\n\n\u003ca id=\"api-http-directory\"\u003e\u003c/a\u003e\n## API \u003e HTTP \u003e Directory Serving\n\n### 🔧 `server.dir(path: string, dir: string, options?: DirOptions | DirHandler)`\nServe files from a directory.\n\n```ts\nserver.dir('/content', './public/content');\n```\n\n\u003e [!IMPORTANT]\n\u003e `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.\n\n```ts\nserver.dir('/', '/files');\nserver.route('/test', () =\u003e 200);\n\n// Route / is equal to /* with server.dir()\n// Accessing /test returns 404 here because /files/test does not exist.\n```\n\n#### Directory Options\n\nYou can configure directory behavior using the `DirOptions` interface:\n\n```ts\ninterface DirOptions {\n\tignore_hidden?: boolean;      // default: true\n\tindex_directories?: boolean;  // default: false  \n\tsupport_ranges?: boolean;     // default: true\n}\n```\n\n**Options-based configuration:**\n```ts\n// Enable directory browsing with HTML listings\nserver.dir('/files', './public', { index_directories: true });\n\n// Serve hidden files and disable range requests\nserver.dir('/files', './public', { \n\tignore_hidden: false, \n\tsupport_ranges: false \n});\n\n// Full configuration\nserver.dir('/files', './public', { \n\tignore_hidden: true,\n\tindex_directories: true,\n\tsupport_ranges: true \n});\n```\n\nWhen `index_directories` is enabled, accessing a directory will return a styled HTML page listing the directory contents with file and folder icons.\n\n#### Custom Directory Handlers\n\nFor complete control, provide a custom handler function:\n\n```ts\nserver.dir('/static', '/static', (file_path, file, stat, request, url) =\u003e {\n\t// ignore hidden files by default, return 404 to prevent file sniffing\n\tif (path.basename(file_path).startsWith('.'))\n\t\treturn HTTP_STATUS_CODE.NotFound_404;\n\n\tif (stat.isDirectory())\n\t\treturn HTTP_STATUS_CODE.Unauthorized_401;\n\n\treturn http_apply_range(file, request);\n});\n```\n\n| Parameter | Type | Reference |\n| --- | --- | --- |\n| `file_path` | `string` | The path to the file on disk. |\n| `file` | `BunFile` | https://bun.sh/docs/api/file-io |\n| `stat` | `fs.Stats` | https://nodejs.org/api/fs.html#class-fsstats |\n| `request` | `Request` | https://developer.mozilla.org/en-US/docs/Web/API/Request |\n| `url` | `URL` | https://developer.mozilla.org/en-US/docs/Web/API/URL |\n\nAsynchronous directory handlers are supported and will be awaited.\n\n```ts\nserver.dir('/static', '/static', async (file_path, file) =\u003e {\n\tlet file_contents = await file.text();\n\t// do something with file_contents\n\treturn file_contents;\n});\n```\n\n\u003e [!NOTE]\n\u003e The directory handler function is only called for files that exist on disk - including directories.\n\n\u003e [!NOTE]\n\u003e Uncaught `ENOENT` errors thrown from the directory handler will return a `404` response, other errors will return a `500` response.\n\n### 🔧 `http_apply_range(file: BunFile, request: Request): HandlerReturnType`\n\n`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.\n\n```ts\nserver.route('/test', (req, url) =\u003e {\n\tconst file = Bun.file('./test.txt');\n\treturn http_apply_range(file, req);\n});\n```\n\n```http\nGET /test HTTP/1.1\nRange: bytes=0-5\n\nHTTP/1.1 206 Partial Content\nContent-Length: 6\nContent-Range: bytes 0-5/6\nContent-Type: text/plain;charset=utf-8\n\nHello,\n```\n\n\u003ca id=\"api-http-sse\"\u003e\u003c/a\u003e\n## API \u003e HTTP \u003e Server-Sent Events (SSE)\n\n### 🔧 `server.sse(path: string, handler: ServerSentEventHandler)`\n\nSetup a [server-sent event](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream.\n\n```ts\nserver.sse('/sse', (req, url, client) =\u003e {\n\tclient.message('Hello, client!'); // Unnamed event.\n\tclient.event('named_event', 'Hello, client!'); // Named event.\n\n\tclient.message(JSON.stringify({ foo: 'bar' })); // JSON message.\n});\n```\n\n`client.closed` is a promise that resolves when the client closes the connection.\n\n```ts\nconst clients = new Set();\n\nserver.sse('/sse', (req, url, client) =\u003e {\n\tclients.add(client);\n\tclient.closed.then(() =\u003e clients.delete(client));\n});\n```\n\nConnections can be manually closed with `client.close()`. This will also trigger the `client.closed` promise to resolve.\n\n```ts\nserver.sse('/sse', (req, url, client) =\u003e {\n\tclient.message('Hello, client!');\n\n\tsetTimeout(() =\u003e {\n\t\tclient.message('Goodbye, client!');\n\t\tclient.close();\n\t}, 5000);\n});\n```\n\n\u003ca id=\"api-http-webhooks\"\u003e\u003c/a\u003e\n## API \u003e HTTP \u003e Webhooks\n\n### 🔧 `server.webhook(secret: string, path: string, handler: WebhookHandler, branches?: string | string[])`\n\nSetup a webhook handler.\n\n```ts\nserver.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload =\u003e {\n\t// React to the webhook.\n\treturn HTTP_STATUS_CODE.OK_200;\n});\n```\n\n#### Branch Filtering\n\nYou can optionally filter webhooks by branch name using the `branches` parameter:\n\n```ts\n// Only trigger for main branch\nserver.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload =\u003e {\n\t// This will only fire for pushes to main branch\n\treturn HTTP_STATUS_CODE.OK_200;\n}, 'main');\n\n// Trigger for multiple branches\nserver.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload =\u003e {\n\t// This will fire for pushes to main or staging branches\n\treturn HTTP_STATUS_CODE.OK_200;\n}, ['main', 'staging']);\n```\n\nWhen 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`).\n\nA webhook callback will only be called if the following critera is met by a request:\n- Request method is `POST` (returns `405` otherwise)\n- Header `X-Hub-Signature-256` is present (returns `400` otherwise)\n- Header `Content-Type` is `application/json` (returns `401` otherwise)\n- Request body is a valid JSON object (returns `500` otherwise)\n- HMAC signature of the request body matches the `X-Hub-Signature-256` header (returns `401` otherwise)\n- If branch filtering is enabled, the push must be to one of the specified branches (returns `200` but ignores otherwise)\n\n\u003e [!NOTE]\n\u003e Constant-time comparison is used to prevent timing attacks when comparing the HMAC signature.\n\n\u003ca id=\"api-http-websockets\"\u003e\u003c/a\u003e\n## API \u003e HTTP \u003e Websocket Server\n\n### 🔧 `server.websocket(path: string, handlers: WebSocketHandlers)`\n\nRegister a route which handles websocket connections.\n\n```ts\nserver.websocket('/path/to/websocket', {\n\t// all of these handlers are OPTIONAL\n\n\taccept: (req, url) =\u003e {\n\t\t// validates a request before it is upgraded\n\t\t// returns HTTP 401 if FALSE is returned\n\t\t// allows you to check headers/authentication\n\t\t// url parameter contains query parameters from route\n\n\t\t// if an OBJECT is returned, the object will\n\t\t// be accessible on the websocket as ws.data.*\n\n\t\treturn true;\n\t},\n\n\topen: (ws) =\u003e {\n\t\t// called when a websocket client connects\n\t},\n\n\tclose: (ws, code, reason) =\u003e {\n\t\t// called when a websocket client disconnects\n\t},\n\n\tmessage: (ws, message) =\u003e {\n\t\t// called when a websocket message is received\n\t\t// message is a string or buffer\n\t},\n\n\tmessage_json: (ws, data) =\u003e {\n\t\t// called when a websocket message is received\n\t\t// payload is parsed as JSON\n\n\t\t// if payload cannot be parsed, socket will be\n\t\t// closed with error 1003: Unsupported Data\n\n\t\t// messages are only internally parsed if this\n\t\t// handler is present\n\t},\n\n\tdrain: (ws) =\u003e {\n\t\t// called when a websocket with backpressure drains\n\t}\n});\n```\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n\u003ca id=\"api-http-bootstrap\"\u003e\u003c/a\u003e\n## API \u003e HTTP \u003e Bootstrap\n\n`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.\n\nFor simpler projects, the scaffolding can often look the same, potentially something similar to below.\n\n```ts\nimport { http_serve, cache_http, parse_template, http_apply_range, git_get_hashes } from 'spooder';\nimport path from 'node:path';\n\nconst server = http_serve(80);\nconst cache = cache_http({\n\tttl: 5 * 60 * 60 * 1000, // 5 minutes\n\tmax_size: 5 * 1024 * 1024, // 5 MB\n\tuse_canary_reporting: true,\n\tuse_etags: true\n});\n\nconst base_file = await Bun.file('./html/base_template.html').text();\nconst git_hash_table = await git_get_hashes();\n\nasync function default_handler(status_code: number): Promise\u003cResponse\u003e {\n\tconst error_text = HTTP_STATUS_CODE[status_code] as string;\n\tconst error_page = await Bun.file('./html/error.html').text();\n\n\tconst content = await parse_template(error_page, {\n\t\ttitle: error_text,\n\t\terror_code: status_code.toString(),\n\t\terror_text: error_text\n\t}, true);\n\n\treturn new Response(content, { status: status_code });\n}\n\nserver.error((err: Error) =\u003e {\n\tcaution(err?.message ?? err);\n\treturn default_handler(HTTP_STATUS_CODE.InternalServerError_500);\n});\n\nserver.default((req, status_code) =\u003e default_handler(status_code));\n\nserver.dir('/static', './static', async (file_path, file, stat, request) =\u003e {\n\t// ignore hidden files by default, return 404 to prevent file sniffing\n\tif (path.basename(file_path).startsWith('.'))\n\t\treturn HTTP_STATUS_CODE.NotFound_404;\n\t\n\tif (stat.isDirectory())\n\t\treturn HTTP_STATUS_CODE.Unauthorized_401;\n\n\t// serve css/js files directly\n\tconst ext = path.extname(file_path);\n\tif (ext === '.css' || ext === '.js') {\n\t\tconst content = await parse_template(await file.text(), {\n\t\t\tcache_bust: (file) =\u003e `${file}?v=${git_hash_table[file]}`\n\t\t}, true);\n\n\t\treturn new Response(content, {\n\t\t\theaders: {\n\t\t\t\t'Content-Type': file.type\n\t\t\t}\n\t\t});\n\t}\n\t\n\treturn http_apply_range(file, request);\n});\n\nfunction add_route(route: string, file: string, title: string) {\n\tserver.route(route, async (req) =\u003e {\n\t\treturn cache.request(req, route, async () =\u003e {\n\t\t\tconst file_content = await Bun.file(file).text();\n\t\t\tconst template = await parse_template(base_file, {\n\t\t\t\ttitle: title,\n\t\t\t\tcontent: file_content,\n\t\t\t\tasset: (file) =\u003e git_hash_table[file]\n\t\t\t}, true);\n\n\t\t\treturn template;\n\t\t});\n\t});\n}\n\nadd_route('/', './html/index.html', 'Homepage');\nadd_route('/about', './html/about.html', 'About Us');\nadd_route('/contact', './html/contact.html', 'Contact Us');\nadd_route('/privacy', './html/privacy.html', 'Privacy Policy');\nadd_route('/terms', './html/terms.html', 'Terms of Service');\n```\n\nFor 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.\n\n### 🔧 `server.bootstrap(options: BootstrapOptions): Promise\u003cvoid\u003e`\n\nBootstrap a server using `spooder` utilities with a straight-forward options API, cutting out the boilerplate.\n\n```ts\nconst server = http_serve(80);\n\nserver.bootstrap({\n\tbase: Bun.file('./html/base_template.html'),\n\tdrop_missing_subs: false,\n\n\tcache: {\n\t\tttl: 5 * 60 * 60 * 1000, // 5 minutes\n\t\tmax_size: 5 * 1024 * 1024, // 5 MB\n\t\tuse_canary_reporting: true,\n\t\tuse_etags: true\n\t},\n\n\terror: {\n\t\tuse_canary_reporting: true,\n\t\terror_page: Bun.file('./html/error.html')\n\t},\n\t\n\tcache_bust: { // true or options\n\t\tformat: '$file#$hash', // default: $file?v=$hash\n\t\thash_length: 20, // default: 7\n\t\tprefix: 'bust' // default: cache_bust\n\t},\n\n\tstatic: {\n\t\tdirectory: './static',\n\t\troute: '/static',\n\t\tsub_ext: ['.css']\n\t},\n\n\tglobal_subs: {\n\t\t'project_name': 'Some Project'\n\t},\n\n\troutes: {\n\t\t'/': {\n\t\t\tcontent: Bun.file('./html/index.html'),\n\t\t\tsubs: { 'title': 'Homepage' }\n\t\t},\n\n\t\t'/about': {\n\t\t\tcontent: Bun.file('./html/about.html'),\n\t\t\tsubs: { 'title': 'About Us' }\n\t\t},\n\n\t\t'/contact': {\n\t\t\tcontent: Bun.file('./html/contact.html'),\n\t\t\tsubs: { 'title': 'Contact Us' }\n\t\t},\n\n\t\t'/privacy': {\n\t\t\tcontent: Bun.file('./html/privacy.html'),\n\t\t\tsubs: { 'title': 'Privacy Policy' }\n\t\t},\n\n\t\t'/terms': {\n\t\t\tcontent: Bun.file('./html/terms.html'),\n\t\t\tsubs: { 'title': 'Terms of Service' }\n\t\t}\n\t}\n});\n```\n\n#### Bootstrap Options\n\nThe `BootstrapOptions` object accepts the following properties:\n\n##### `base?: string | BunFile`\nOptional base template that wraps all route content. The base template should include `{{content}}` where the route content will be inserted.\n\n```ts\n// Base template: base.html\n\u003chtml\u003e\n\u003chead\u003e\u003ctitle\u003e{{title}}\u003c/title\u003e\u003c/head\u003e\n\u003cbody\u003e{{content}}\u003c/body\u003e\n\u003c/html\u003e\n\n// Usage\nserver.bootstrap({\n\tbase: Bun.file('./templates/base.html'),\n\troutes: {\n\t\t'/': {\n\t\t\tcontent: '\u003ch1\u003eWelcome\u003c/h1\u003e',\n\t\t\tsubs: { title: 'Home' }\n\t\t}\n\t}\n});\n```\n\n##### `drop_missing_subs: boolean`\n\n**Optional**. Defaults to true. If explicitly disabled, templating parsing will not drop unknown substitutions.\n\n\u003e ![NOTE]\n\u003e If you are using a client-side framework that uses the double-brace syntax ``{{foo}}`` such as Vue, you should set this to `false` to ensure compatibility.\n\n##### `routes: Record\u003cstring, BootstrapRoute\u003e`\n**Required.** Defines the routes and their content. Each route can have:\n- `content`: The page content (string or BunFile)\n- `subs?`: Template substitutions specific to this route\n\n```ts\nroutes: {\n\t'/about': {\n\t\tcontent: Bun.file('./pages/about.html'),\n\t\tsubs: { \n\t\t\ttitle: 'About Us',\n\t\t\tdescription: 'Learn more about our company'\n\t\t}\n\t}\n}\n```\n\n##### `cache?: CacheOptions | ReturnType\u003ctypeof cache_http\u003e`\nOptional HTTP caching configuration. Can be:\n- A `CacheOptions` object (creates new cache instance)\n- An existing cache instance from `cache_http()`\n- Omitted to disable caching\n\n```ts\ncache: {\n\tttl: 5 * 60 * 1000,     // 5 minutes\n\tmax_size: 10 * 1024 * 1024, // 10 MB\n\tuse_etags: true,\n\tuse_canary_reporting: true\n}\n```\n\n##### `cache_bust?: CacheBustOptions | boolean`\nEnables the use of the [`cache_bust()`](#api-cache-busting) API inside templates using the ``{{cache_bust=file}}`` directive.\n\n```html\n\u003clink href=\"{{cache_bust=static/css/style.css}}\"\u003e\n\u003cscript src=\"{{cache_bust=static/js/app.js}}\"\u003e\u003c/script\u003e\n\u003cimg src=\"{{cache_bust=static/images/logo.png}}\"\u003e\n```\n\nSince this uses the [`cache_bust()`](#api-cache-busting) API internally, it is effected by the `cache_bust_set_hash_length` and `cache_bust_set_format` global functions.\n\nSetting `cache_bust` to `true` assumes the normal defaults, however this can be customized by providing an options object.\n\n```ts\ncache_bust: { // true or options\n\tformat: '$file#$hash', // default: $file?v=$hash\n\thash_length: 20, // default: 7\n\tprefix: 'bust' // default: cache_bust\n},\n```\n\n\u003e ![IMPORTANT]\n\u003e `format` and `hash_length` internally call `cache_bust_set_format` and `cache_bust_set_hash_length` respectively, so these values will effect `cache_bust()` globally.\n\n##### `error?: object`\nOptional error page configuration:\n- `error_page`: Template for error pages (string or BunFile)\n- `use_canary_reporting?`: Whether to report errors via canary\n\nError templates receive `{{error_code}}` and `{{error_text}}` substitutions.\n\n```ts\nerror: {\n\terror_page: Bun.file('./templates/error.html'),\n\tuse_canary_reporting: true\n}\n```\n\n##### `static?: object`\nOptional static file serving configuration:\n- `route`: URL path prefix for static files\n- `directory`: Local directory containing static files\n- `sub_ext?`: Array of file extensions that should have template substitution applied\n\n```ts\nstatic: {\n\troute: '/assets',\n\tdirectory: './public',\n\tsub_ext: ['.css', '.js']  // These files get template processing\n}\n```\n\nFiles with extensions in `sub_ext` will have template substitutions applied before serving. This includes support for functions to generate dynamic content:\n\n```ts\n// Dynamic CSS with function-based substitutions\nstatic: {\n\troute: '/assets',\n\tdirectory: './public',\n\tsub_ext: ['.css']\n},\n\nglobal_subs: {\n\ttheme_color: () =\u003e {\n\t\tconst hour = new Date().getHours();\n\t\treturn hour \u003c 6 || hour \u003e 18 ? '#2d3748' : '#4a5568';\n\t}\n}\n```\n\nThis allows CSS files to use dynamic substitutions: `color: {{theme_color}};`\n\n##### `global_subs?: Record\u003cstring, BootstrapSub\u003e`\nOptional global template substitutions available to all routes, error pages, and static files with `sub_ext`.\n\n```ts\nglobal_subs: {\n\tsite_name: 'My Website',\n\tversion: '1.0.0',\n\tapi_url: 'https://api.example.com',\n\t\n\t// Function-based substitutions for dynamic content\n\tcurrent_year: () =\u003e new Date().getFullYear().toString(),\n\t\n\tbuild_time: async () =\u003e {\n\t\t// Example: fetch build timestamp from git\n\t\tconst process = Bun.spawn(['git', 'log', '-1', '--format=%ct']);\n\t\tconst output = await new Response(process.stdout).text();\n\t\treturn new Date(parseInt(output.trim()) * 1000).toISOString();\n\t},\n\t\n\tuser_count: async () =\u003e {\n\t\t// Example: dynamic user count from database\n\t\tconst count = await db.count('SELECT COUNT(*) as count FROM users');\n\t\treturn count.toLocaleString();\n\t}\n}\n```\n\nFunctions in `global_subs` and route-specific `subs` are called during template processing, allowing for dynamic content generation. Both synchronous and asynchronous functions are supported.\n\n#### Template Processing Order\n\n1. Route content is loaded\n2. If `base` is defined, content is wrapped using `{{content}}` substitution\n3. Route-specific `subs` and `global_subs` are applied\n4. Hash substitutions (if enabled) are applied\n\n\u003ca id=\"api-http-cookies\"\u003e\u003c/a\u003e\n## API \u003e HTTP \u003e Cookies\n\n### 🔧 `cookies_get(req: Request): Bun.CookieMap`\n\nWhen called on a request, the `cookies_get` function will return a `Bun.CookieMap` contains all of the cookies parsed from the `Cookie` header on the request.\n\n```ts\nserver.route('/', (req, url) =\u003e {\n\tconst cookies = cookies_get(req);\n\treturn `Hello ${cookies.get('person') ?? 'unknown'}`;\n});\n```\n\nThe return `Bun.CookieMap` is an iterable map with a custom API for reading/setting cookies. The full API [can be seen here](https://bun.com/docs/runtime/cookies).\n\nAny changes made to the cookie map (adding, deletion, editing, etc) will be sent as `Set-Cookie` headers on the response automatically. Unchanged cookies are not sent.\n\n```ts\nserver.route('/', (req, url) =\u003e {\n\tconst cookies = cookies_get(req);\n\tcookies.set('test', 'foobar');\n\treturn 'Hello, world!';\n\n\t// the response automatically gets:\n\t// Set-Cookie test=foobar; Path=/; SameSite=Lax\n});\n```\n\n\u003ca id=\"api-error-handling\"\u003e\u003c/a\u003e\n## API \u003e Error Handling\n\n### 🔧 `ErrorWithMetadata(message: string, metadata: object)`\n\nThe `ErrorWithMetadata` class allows you to attach metadata to errors, which can be used for debugging purposes when errors are dispatched to the canary.\n\n```ts\nthrow new ErrorWithMetadata('Something went wrong', { foo: 'bar' });\n```\n\nFunctions and promises contained in the metadata will be resolved and the return value will be used instead.\n\n```ts\nthrow new ErrorWithMetadata('Something went wrong', { foo: () =\u003e 'bar' });\n```\n\n### 🔧 `caution(err_message_or_obj: string | object, ...err: object[]): Promise\u003cvoid\u003e`\n\nRaise a warning issue on GitHub. This is useful for non-fatal issues which you want to be notified about.\n\n\u003e [!NOTE]\n\u003e This function is only available if the canary feature is enabled.\n\n```ts\ntry {\n\t// Perform a non-critical action, such as analytics.\n\t// ...\n} catch (e) {\n\t// `caution` is async, you can use it without awaiting.\n\tcaution(e);\n}\n```\n\nAdditional data can be provided as objects which will be serialized to JSON and included in the report.\n\n```ts\ncaution(e, { foo: 42 });\n```\n\nA custom error message can be provided as the first parameter\n\n\u003e [!NOTE]\n\u003e Avoid including dynamic information in the title that would prevent the issue from being unique.\n\n```ts\ncaution('Custom error', e, { foo: 42 });\n```\n\nIssues raised with `caution()` are rate-limited. By default, the rate limit is `86400` seconds (24 hours), however this can be configured in the `spooder.canary.throttle` property.\n\n```json\n{\n\t\"spooder\": {\n\t\t\"canary\": {\n\t\t\t\"throttle\": 86400\n\t\t}\n\t}\n}\n```\n\nIssues are considered unique by the `err_message` parameter, so avoid using dynamic information that would prevent this from being unique.\n\nIf you need to provide unique information, you can use the `err` parameter to provide an object which will be serialized to JSON and included in the issue body.\n\n```ts\nconst some_important_value = Math.random();\n\n// Bad: Do not use dynamic information in err_message.\nawait caution('Error with number ' + some_important_value);\n\n// Good: Use err parameter to provide dynamic information.\nawait caution('Error with number', { some_important_value });\n```\n\n### 🔧 `panic(err_message_or_obj: string | object, ...err: object[]): Promise\u003cvoid\u003e`\n\nThis 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.\n\n\u003e [!NOTE]\n\u003e This function is only available if the canary feature is enabled.\n\nThis should only be used as an absolute last resort when the server cannot continue to run and will be unable to respond to requests.\n\n```ts\ntry {\n\t// Perform a critical action.\n\t// ...\n} catch (e) {\n\t// You should await `panic` since the process will exit.\n\tawait panic(e);\n}\n```\n\n### 🔧 `safe(fn: Callable): Promise\u003cvoid\u003e`\n\n`safe()` is a utility function that wraps a \"callable\" and calls `caution()` if it throws an error.\n\n\u003e [!NOTE]\n\u003e This utility is primarily intended to be used to reduce boilerplate for fire-and-forget functions that you want to be notified about if they fail. \n\n```ts\nsafe(async (() =\u003e {\n\t// This code will run async and any errors will invoke caution().\n});\n```\n\n`safe()` supports both async and sync callables, as well as Promise objects. `safe()` can also used with `await`.\n\n```ts\nawait safe(() =\u003e {\n\treturn new Promise((resolve, reject) =\u003e {\n\t\t// Do stuff.\n\t});\n});\n```\n\n\u003ca id=\"api-workers\"\u003e\u003c/a\u003e\n## API \u003e Workers\n\n### 🔧 `worker_pool(options: WorkerPoolOptions): Promise\u003cWorkerPool\u003e` (Main Thread)\n\nCreate 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.\n\n```ts\n// with a single worker (id defaults to 'main')\nconst pool = await worker_pool({\n\tworker: './worker.ts'\n});\n\n// with multiple workers and custom ID\nconst pool = await worker_pool({\n\tid: 'main',\n\tworker: ['./worker_a.ts', './worker_b.ts']\n});\n\n// spawn multiple instances of the same worker\nconst pool = await worker_pool({\n\tworker: './worker.ts',\n\tsize: 5 // spawns 5 instances\n});\n\n// with custom response timeout\nconst pool = await worker_pool({\n\tworker: './worker.ts',\n\tresponse_timeout: 10000 // 10 seconds (default: 5000ms, use -1 to disable)\n});\n\n// with auto-restart enabled (boolean)\nconst pool = await worker_pool({\n\tworker: './worker.ts',\n\tauto_restart: true // uses default settings\n});\n\n// with custom auto-restart configuration\nconst pool = await worker_pool({\n\tworker: './worker.ts',\n\tauto_restart: {\n\t\tbackoff_max: 5 * 60 * 1000, // 5 min (default)\n\t\tbackoff_grace: 30000, // 30 seconds (default)\n\t\tmax_attempts: 5 // -1 for unlimited (default: 5)\n\t}\n});\n```\n\n### 🔧 `worker_connect(peer_id?: string, response_timeout?: number): WorkerPool` (Worker Thread)\n\nConnect 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.\n\n**Parameters:**\n- `peer_id` - Optional worker ID (defaults to `worker-UUID`)\n- `response_timeout` - Optional timeout in milliseconds for request-response patterns (default: 5000ms, use -1 to disable)\n\n```ts\n// worker thread\nconst pool = worker_connect('my_worker'); // defaults to worker-UUID, 5000ms timeout\npool.on('test', msg =\u003e {\n\tconsole.log(`Received ${msg.data.foo} from ${msg.peer}`);\n});\n\n// with custom timeout\nconst pool = worker_connect('my_worker', 10000); // 10 second timeout\nconst pool = worker_connect('my_worker', -1); // no timeout\n```\n\n### Basic Usage\n\n```ts\n// main thread\nconst pool = await worker_pool({\n\tid: 'main',\n\tworker: './worker.ts'\n});\n\npool.send('my_worker', 'test', { foo: 42 });\n\n// worker thread (worker.ts)\nconst pool = worker_connect('my_worker');\npool.on('test', msg =\u003e {\n\tconsole.log(`Received ${msg.data.foo} from ${msg.peer}`);\n\t// \u003e Received 42 from main\n});\n```\n\n### Cross-Worker Communication\n\n```ts\n// main thread\nconst pool = await worker_pool({\n\tid: 'main',\n\tworker: ['./worker_a.ts', './worker_b.ts']\n});\n\npool.send('worker_a', 'test', { foo: 42 }); // send to just worker_a\npool.broadcast('test', { foo: 50 } ); // send to all workers\n\n// worker_a.ts\nconst pool = worker_connect('worker_a');\n// send from worker_a to worker_b\npool.send('worker_b', 'test', { foo: 500 });\n```\n\n### 🔧 `pool.send(peer: string, id: string, data?: Record\u003cstring, any\u003e, expect_response?: boolean): void | Promise\u003cWorkerMessage\u003e`\n\nSend a message to a specific peer in the pool, which can be the main host or another worker.\n\nWhen `expect_response` is `false` (default), the function returns `void`. When `true`, it returns a `Promise\u003cWorkerMessage\u003e` that resolves when the peer responds using `pool.respond()`.\n\n```ts\n// Fire-and-forget (default behavior)\npool.send('main', 'user_update', { user_id: 123, name: 'John' });\npool.send('worker_b', 'simple_event');\n\n// Request-response pattern\nconst response = await pool.send('worker_b', 'calculate', { value: 42 }, true);\nconsole.log('Result:', response.data);\n```\n\n\u003e [!NOTE]\n\u003e 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`.\n\n### 🔧 `pool.broadcast(id: string, data?: Record\u003cstring, any\u003e): void`\n\nBroadcast a message to all peers in the pool.\n\n```ts\npool.broadcast('test_event', { foo: 42 });\n```\n\n### 🔧 `pool.on(event: string, callback: (data: Record\u003cstring, any\u003e) =\u003e void | Promise\u003cvoid\u003e): void`\n\nRegister an event handler for messages with the specified event ID. The callback can be synchronous or asynchronous.\n\n```ts\npool.on('process_data', async msg =\u003e {\n\t// msg.peer\n\t// msg.id\n\t// msg.data\n});\n```\n\n\u003e [!NOTE]\n\u003e 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.\n\n### 🔧 `pool.once(event: string, callback: (data: Record\u003cstring, any\u003e) =\u003e void | Promise\u003cvoid\u003e): void`\n\nRegister 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.\n\n```ts\npool.once('one_time_event', async msg =\u003e {\n\t// this will only fire once\n});\n```\n\n### 🔧 `pool.off(event: string): void`\n\nUnregister an event handler for events with the specified event ID.\n\n```ts\npool.off('event_name');\n```\n\n### 🔧 `pool.respond(message: WorkerMessage, data?: Record\u003cstring, any\u003e): void`\n\nRespond to a message that was sent with `expect_response: true`. This allows implementing request-response patterns between peers.\n\n```ts\npool.on('calculate', msg =\u003e {\n\tconst result = msg.data.value * 2;\n\tpool.respond(msg, { result });\n});\n\nconst response = await pool.send('worker_a', 'calculate', { value: 42 }, true);\nconsole.log(response.data.result); // 84\n```\n\n**Message Structure:**\n- `message.id` - The event ID\n- `message.peer` - The sender's peer ID\n- `message.data` - The message payload\n- `message.uuid` - Unique identifier for this message\n- `message.response_to` - UUID of the message being responded to (only present in responses)\n\n### Request-Response Example\n\n```ts\n// main.ts\nconst pool = await worker_pool({\n\tid: 'main',\n\tworker: './worker.ts'\n});\n\nconst response = await pool.send('worker_a', 'MSG_REQUEST', { value: 42 }, true);\nconsole.log(`Got response ${response.data.value} from ${response.peer}`);\n\n// worker.ts\nconst pool = worker_connect('worker_a');\n\npool.on('MSG_REQUEST', msg =\u003e {\n\tconsole.log(`Received request with value: ${msg.data.value}`);\n\tpool.respond(msg, { value: msg.data.value * 2 });\n});\n```\n\n### Lifecycle Callbacks\n\nWorker pools support lifecycle callbacks to monitor when workers start and stop. Callbacks receive the pool instance, allowing you to communicate with workers immediately.\n\n```ts\nconst pool = await worker_pool({\n\tworker: './worker.ts',\n\tauto_restart: true,\n\tonWorkerStart: async (pool, worker_id) =\u003e {\n\t\tconsole.log(`Worker ${worker_id} started`);\n\t\tawait pool.send(worker_id, 'init', { config: 'value' }, true);\n\t},\n\tonWorkerStop: (pool, worker_id, exit_code) =\u003e {\n\t\tconsole.log(`Worker ${worker_id} stopped with exit code ${exit_code}`);\n\t\tif (exit_code !== 0 \u0026\u0026 exit_code !== 42) {\n\t\t\tconsole.log(`Worker ${worker_id} crashed`);\n\t\t}\n\t}\n});\n```\n\n#### Callback Signatures\n\n- `onWorkerStart: (pool: WorkerPool, worker_id: string) =\u003e void` - Fires when a worker registers with the pool\n- `onWorkerStop: (pool: WorkerPool, worker_id: string, exit_code: number) =\u003e void` - Fires when a worker stops\n\n### Auto-Restart\n\nThe `worker_pool` function supports automatic worker restart when workers crash or close unexpectedly. This feature includes an exponential backoff protocol to prevent restart loops.\n\n#### Configuration:\n- `auto_restart`: `boolean | AutoRestartConfig` - Enable auto-restart (optional)\n  - If `true`, uses default settings\n  - If an object, allows customization of restart behavior\n\n#### AutoRestartConfig\n- `backoff_max`: `number` - Maximum delay between restart attempts in milliseconds (default: `5 * 60 * 1000` = 5 minutes)\n- `backoff_grace`: `number` - Time in milliseconds a worker must run successfully before restart attempts are reset (default: `30000` = 30 seconds)\n- `max_attempts`: `number` - Maximum number of restart attempts before giving up (default: `5`, use `-1` for unlimited)\n\n#### Backoff Protocol\n1. Initial restart delay starts at 100ms\n2. Each subsequent restart doubles the delay\n3. Delay is capped at `backoff_max`\n4. If a worker runs successfully for `backoff_grace` milliseconds, the delay and attempt counter reset\n5. After `max_attempts` failures, auto-restart stops for that worker\n\n**Example:**\n```ts\nconst pool = await worker_pool({\n\tworker: './worker.ts',\n\tauto_restart: {\n\t\tbackoff_max: 5 * 60 * 1000, // cap at 5 minutes\n\t\tbackoff_grace: 30000, // reset after 30 seconds of successful operation\n\t\tmax_attempts: 5 // give up after 5 failed attempts\n\t}\n});\n```\n\n#### Graceful Exit\n\nWorkers can exit gracefully without triggering an auto-restart by using the `WORKER_EXIT_NO_RESTART` exit code (42):\n\n```ts\n// worker thread\nimport { WORKER_EXIT_NO_RESTART } from 'spooder';\nprocess.exit(WORKER_EXIT_NO_RESTART); // exits without auto-restart\n```\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n\u003ca id=\"api-caching\"\u003e\u003c/a\u003e\n## API \u003e Caching\n\n### 🔧 `cache_http(options?: CacheOptions)`\n\nInitialize a file caching system that stores file contents in memory with configurable TTL, size limits, and ETag support for efficient HTTP caching.\n\n```ts\nimport { cache_http } from 'spooder';\n\nconst cache = cache_http({\n\tttl: 5 * 60 * 1000 // 5 minutes\n});\n\n// Use with server routes for static files\nserver.route('/', cache.file('./index.html'));\n\n// Use with server routes for dynamic content\nserver.route('/dynamic', async (req) =\u003e cache.request(req, 'dynamic-page', () =\u003e 'Dynamic Content'));\n\n// Disable caching (useful for development mode)\nconst devCache = cache_http({ enabled: process.env.SPOODER_ENV !== 'dev' });\nserver.route('/no-cache', devCache.file('./index.html')); // Always reads from disk\n```\n\nThe `cache_http()` function returns an object with two methods:\n\n### 🔧 `cache.file(file_path: string)`\nCaches static files from the filesystem. This method reads the file from disk and caches its contents with automatic content-type detection.\n\n```ts\n// Cache a static HTML file\nserver.route('/', cache.file('./public/index.html'));\n\n// Cache CSS files\nserver.route('/styles.css', cache.file('./public/styles.css'));\n```\n\n### 🔧 `cache.request(req: Request, cache_key: string, content_generator: () =\u003e string | Promise\u003cstring\u003e): Promise\u003cResponse\u003e`\nCaches 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.\n\n```ts\n// Cache dynamic HTML content\nserver.route('/user/:id', async (req) =\u003e {\n\treturn cache.request(req, '/user', async () =\u003e {\n\t\tconst userData = await fetchUserData();\n\t\treturn generateUserHTML(userData);\n\t});\n});\n\n// Cache API responses\nserver.route('/api/stats', async (req) =\u003e {\n\treturn cache.request(req, 'stats', () =\u003e {\n\t\treturn JSON.stringify({ users: getUserCount(), posts: getPostCount() });\n\t});\n});\n```\n\n## Configuration Options\n\n| Option | Type | Default | Description |\n| --- | --- | --- | --- |\n| `ttl` | `number` | `18000000` (5 hours) | Time in milliseconds before cached entries expire |\n| `max_size` | `number` | `5242880` (5 MB) | Maximum total size of all cached files in bytes |\n| `use_etags` | `boolean` | `true` | Generate and use ETag headers for cache validation |\n| `headers` | `Record\u003cstring, string\u003e` | `{}` | Additional HTTP headers to include in responses |\n| `use_canary_reporting` | `boolean` | `false` | Reports faults to canary (see below) |\n| `enabled` | `boolean` | `true` | When false, content is generated but not stored\n\n#### Canary Reporting\n\nIf `use_canary_reporting` is enabled, `spooder` will call `caution()` in two scenarios:\n\n1. 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.\n2. 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.\n\n#### Cache Behavior\n\n- Files are cached for the specified TTL duration.\n- Individual files larger than `max_size` will not be cached\n- When total cache size exceeds `max_size`, expired entries are removed first\n- If still over limit, least recently used (LRU) entries are evicted\n\n**ETag Support:**\n- When `use_etags` is enabled, SHA-256 hashes are generated for file contents\n- ETags enable HTTP 304 Not Modified responses for unchanged files\n- Clients can send `If-None-Match` headers for efficient cache validation\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n\u003e [!NOTE]\n\u003e Files are only cached after the first request. The cache performs lazy loading and does not pre-populate files on initialization.\n\n### Raw Cache Access\n\nThe 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.\n\n\u003ca id=\"api-templating\"\u003e\u003c/a\u003e\n## API \u003e Templating\n\n### 🔧 `parse_template(template: string, replacements: Replacements, drop_missing: boolean): Promise\u003cstring\u003e`\n\nReplace placeholders in a template string with values from a replacement object.\n\n```ts\nconst template = `\n\t\u003chtml\u003e\n\t\t\u003chead\u003e\n\t\t\t\u003ctitle\u003e{{title}}\u003c/title\u003e\n\t\t\u003c/head\u003e\n\t\t\u003cbody\u003e\n\t\t\t\u003ch1\u003e{{title}}\u003c/h1\u003e\n\t\t\t\u003cp\u003e{{content}}\u003c/p\u003e\n\t\t\t\u003cp\u003e{{ignored}}\u003c/p\u003e\n\t\t\u003c/body\u003e\n\t\u003c/html\u003e\n`;\n\nconst replacements = {\n\ttitle: 'Hello, world!',\n\tcontent: 'This is a test.'\n};\n\nconst html = await parse_template(template, replacements);\n```\n\n```html\n\u003chtml\u003e\n\t\u003chead\u003e\n\t\t\u003ctitle\u003eHello, world!\u003c/title\u003e\n\t\u003c/head\u003e\n\t\u003cbody\u003e\n\t\t\u003ch1\u003eHello, world!\u003c/h1\u003e\n\t\t\u003cp\u003eThis is a test.\u003c/p\u003e\n\t\t\u003cp\u003e{{ignored}}\u003c/p\u003e\n\t\u003c/body\u003e\n\u003c/html\u003e\n```\n\nBy default, placeholders that do not appear in the replacement object will be left as-is. Set `drop_missing` to `true` to remove them.\n\n```ts\nawait parse_template(template, replacements, true);\n```\n\n```html\n\u003chtml\u003e\n\t\u003chead\u003e\n\t\t\u003ctitle\u003eHello, world!\u003c/title\u003e\n\t\u003c/head\u003e\n\t\u003cbody\u003e\n\t\t\u003ch1\u003eHello, world!\u003c/h1\u003e\n\t\t\u003cp\u003eThis is a test.\u003c/p\u003e\n\t\t\u003cp\u003e\u003c/p\u003e\n\t\u003c/body\u003e\n\u003c/html\u003e\n```\n\n#### Custom Replacer Function\n\n`parse_template` supports passing a function instead of a replacement object. This function will be called for each placeholder and the return value will be used as the replacement. Both synchronous and asynchronous functions are supported.\n\n```ts\nconst replacer = (key: string) =\u003e {\n\tswitch (key) {\n\t\tcase 'timestamp': return Date.now().toString();\n\t\tcase 'random': return Math.random().toString(36).substring(7);\n\t\tcase 'greeting': return 'Hello, World!';\n\t\tdefault: return undefined;\n\t}\n};\n\nawait parse_template('Generated at {{timestamp}}: {{greeting}} (ID: {{random}})', replacer);\n// Result: \"Generated at 1635789123456: Hello, World! (ID: x7k2p9m)\"\n```\n\nCustom replacer functions are supported on a per-key basis, mixing with static string replacement.\n\n```ts\nawait parse_template('Hello {{foo}}, it is {{now}}', {\n\tfoo: 'world',\n\tnow: () =\u003e Date.now()\n});\n```\n\n#### Key/Value Based Substitutions\n\n`parse_template` supports key/value based substitutions using the `{{key=value}}` syntax. When a function replacer is provided for the key, the value is passed as a parameter to the function.\n\n```ts\nawait parse_template('Color: {{hex=blue}}', {\n\thex: (color) =\u003e {\n\t\tconst colors = { blue: '#0000ff', red: '#ff0000', green: '#00ff00' };\n\t\treturn colors[color] || color;\n\t}\n});\n// Result: \"Color: #0000ff\"\n```\n\nGlobal replacer functions also support the value parameter:\n\n```ts\nawait parse_template('Transform: {{upper=hello}} and {{lower=WORLD}}', (key, value) =\u003e {\n\tif (key === 'upper' \u0026\u0026 value) return value.toUpperCase();\n\tif (key === 'lower' \u0026\u0026 value) return value.toLowerCase();\n\treturn 'unknown';\n});\n// Result: \"Transform: HELLO and world\"\n```\n\n#### Conditional Rendering\n\n`parse_template` supports conditional rendering with the following syntax.\n\n```html\n\u003ct-if test=\"foo\"\u003eI love {{foo}}\u003c/t-if\u003e\n```\nContents contained inside a `t-if` block will be rendered providing the given value, in this case `foo` is truthy in the substitution table.\n\nA `t-if` block is only removed if `drop_missing` is `true`, allowing them to persist through multiple passes of a template.\n\n\n`parse_template` supports looping arrays and objects using the `items` and `as` attributes.\n\n#### Object/Array Looping with `items` and `as` Attributes\n\n```html\n\u003ct-for items=\"items\" as=\"item\"\u003e\u003cdiv\u003e{{item.name}}: {{item.value}}\u003c/div\u003e\u003c/t-for\u003e\n```\n\n```ts\nconst template = `\n\t\u003cul\u003e\n\t\t\u003ct-for items=\"colors\" as=\"color\"\u003e\n\t\t\t\u003cli class=\"{{color.type}}\"\u003e\n\t\t\t\t{{color.name}}\n\t\t\t\u003c/li\u003e\n\t\t\u003c/t-for\u003e\n\t\u003c/ul\u003e\n`;\n\nconst replacements = {\n\tcolors: [\n\t\t{ name: 'red', type: 'warm' },\n\t\t{ name: 'blue', type: 'cool' },\n\t\t{ name: 'green', type: 'neutral' }\n\t]\n};\n\nconst html = await parse_template(template, replacements);\n```\n\n```html\n\u003cul\u003e\n\t\u003cli class=\"warm\"\u003ered\u003c/li\u003e\n\t\u003cli class=\"cool\"\u003eblue\u003c/li\u003e\n\t\u003cli class=\"neutral\"\u003egreen\u003c/li\u003e\n\u003c/ul\u003e\n```\n\n#### Simple Array Iteration\n\nFor simple arrays containing strings, you can iterate directly over the array items:\n\n```ts\nconst template = `\n\t\u003cul\u003e\n\t\t\u003ct-for items=\"fruits\" as=\"fruit\"\u003e\n\t\t\t\u003cli\u003e{{fruit}}\u003c/li\u003e\n\t\t\u003c/t-for\u003e\n\t\u003c/ul\u003e\n`;\n\nconst replacements = {\n\tfruits: ['apple', 'banana', 'orange']\n};\n\nconst html = await parse_template(template, replacements);\n```\n\n```html\n\u003cul\u003e\n\t\u003cli\u003eapple\u003c/li\u003e\n\t\u003cli\u003ebanana\u003c/li\u003e\n\t\u003cli\u003eorange\u003c/li\u003e\n\u003c/ul\u003e\n```\n\n#### Dot Notation Property Access\n\nYou can access nested object properties using dot notation:\n\n```ts\nconst data = {\n\tuser: {\n\t\tprofile: { name: 'John', age: 30 },\n\t\tsettings: { theme: 'dark' }\n\t}\n};\n\nawait parse_template('Hello {{user.profile.name}}, you prefer {{user.settings.theme}} mode!', data);\n// Result: \"Hello John, you prefer dark mode!\"\n```\n\nAll placeholders inside a `\u003ct-for\u003e` loop are substituted, but only if the loop variable exists.\n\nIn the following example, `missing` does not exist, so `test` is not substituted inside the loop, but `test` is still substituted outside the loop.\n\n```html\n\u003cdiv\u003eHello {{test}}!\u003c/div\u003e\n\u003ct-for items=\"missing\" as=\"item\"\u003e\n\t\u003cdiv\u003eLoop {{test}}\u003c/div\u003e\n\u003c/t-for\u003e\n```\n\n```ts\nawait parse_template(..., {\n\ttest: 'world'\n});\n```\n\n```html\n\u003cdiv\u003eHello world!\u003c/div\u003e\n\u003ct-for items=\"missing\" as=\"item\"\u003e\n\t\u003cdiv\u003eLoop {{test}}\u003c/div\u003e\n\u003c/t-for\u003e\n```\n\n#### Object Serialization\n\nWhen a replacement value is an object or array, it is automatically serialized to JSON. This allows server-side data to be embedded directly into client-side scripts.\n\n```ts\nconst config = {\n\tdebug: true,\n\tapi_url: '/api/v1',\n\tfeatures: ['auth', 'logging']\n};\n\nawait parse_template('\u003cscript\u003econst CONFIG = {{config}};\u003c/script\u003e', { config });\n// Result: \"\u003cscript\u003econst CONFIG = {\"debug\":true,\"api_url\":\"/api/v1\",\"features\":[\"auth\",\"logging\"]};\u003c/script\u003e\"\n```\n\nThis also works with nested objects accessed via dot notation:\n\n```ts\nconst data = {\n\tapp: {\n\t\tsettings: { theme: 'dark', lang: 'en' }\n\t}\n};\n\nawait parse_template('\u003cscript\u003econst SETTINGS = {{app.settings}};\u003c/script\u003e', data);\n// Result: \"\u003cscript\u003econst SETTINGS = {\"theme\":\"dark\",\"lang\":\"en\"};\u003c/script\u003e\"\n```\n\n\u003ca id=\"api-cache-busting\"\u003e\u003c/a\u003e\n## API \u003e Cache Busting\n\n### 🔧 ``cache_bust(string|string[]: path, format: string): string|string[]``\n\nAppends a hash-suffix to the provided string, formatted by default as a query parameter, for cache-busting purposes.\n\n```ts\ncache_bust('static/my_image.png'); // \u003e static/my_image.png?v=123fea\n```\n\nThis works on an array of paths as well.\n\n```ts\ncache_bust([\n\t'static/js/script1.js',\n\t'static/js/script2.js'\n]);\n\n// [\n//    'static/js/script1.js?v=fffffff',\n//    'static/js/script2.js?v=fffffff'\n// ]\n```\n\n\u003e ![NOTE]\n\u003e Internally `cache_bust()` uses `git_get_hashes()` to hash paths, requiring the input `path` to be a valid git path. If the path cannot be resolved in git, an empty hash is substituted.\n\n### 🔧 ``cache_bust_set_format(format: string): void``\n\nThe default format for used for `cache_bust()` is `$file?v=$hash`, this can be customized per-call with the `format` parameter, or globally using `cache_bust_set_format()`\n\n```ts\ncache_bust('dogs.txt'); // \u003e dogs.txt?v=fff\ncache_bust('dogs.txt', '$file?hash=$hash'); // \u003e dogs.txt?hash=fff\n\ncache_bust_set_format('$file#$hash');\ncache_bust('dogs.txt'); // \u003e dogs#fff\n```\n\n### 🔧 ``cache_bust_set_hash_length(length: number): void``\n\nThe default hash-length used by `cache_bust()` is 7. This can be changed with `cache_bust_set_hash_length()`.\n\n\u003e ![NOTE]\n\u003e Hashes are cached once at the specified length, therefore `cache_bust_set_hash_length()` must be called before calling `cache_bust()` and has no effect calling it after.\n\n```ts\ncache_bust_set_hash_length(10);\ncache_bust('dogs.txt'); // \u003e dogs.txt?v=ffffffffff\n```\n\n### 🔧 ``cache_bust_get_hash_table(): Record\u003cstring, string\u003e``\n\nThis function returns the internal hash table used by `cache_bust()`. This is exposed to userland in the event that you which to use the hashes for other purposes, avoiding the need to call and store `git_get_hashes()` twice.\n\n\u003ca id=\"api-templating\"\u003e\u003c/a\u003e\n## API \u003e Git\n\n### 🔧 ``git_get_hashes(length: number): Promise\u003cRecord\u003cstring, string\u003e\u003e``\n\n### 🔧 ``git_get_hashes_sync(length: number): Record\u003cstring, string\u003e``\n\nRetrieve git hashes for all files in the repository. This is useful for implementing cache-busting functionality or creating file integrity checks.\n\n\u003e [!IMPORTANT]\n\u003e Internally `git_get_hashes()` uses `git ls-tree -r HEAD`, so the working directory must be a git repository.\n\n```ts\nconst hashes = await git_get_hashes(7);\n// { 'docs/project-logo.png': '754d9ea' }\n```\n\nYou can specify the hash length (default is 7 characters for short hashes):\n\n```ts\nconst full_hashes = await git_get_hashes(40);\n// { 'docs/project-logo.png': 'd65c52a41a75db43e184d2268c6ea9f9741de63e' }\n```\n\n\n\u003ca id=\"api-database\"\u003e\u003c/a\u003e\n## API \u003e Database\n\nBefore `v6.0.0`, spooder provided a database API for `sqlite` and `mysql` while they were not available natively in `bun`.\n\nNow 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.\n\nYou can see the documentation for the [Bun SQL API here.](https://bun.com/docs/runtime/sql)\n\n\u003ca id=\"api-database-utilities\"\u003e\u003c/a\u003e\n## API \u003e Database \u003e Utilities\n\n### 🔧 ``db_set_cast\u003cT extends string\u003e(set: string | null): Set\u003cT\u003e``\n\nTakes a database SET string and returns a `Set\u003cT\u003e` where `T` is a provided enum.\n\n```ts\nenum Fruits {\n\tApple = 'Apple',\n\tBanana = 'Banana',\n\tLemon = 'Lemon'\n};\n\nconst [row] = await sql`SELECT * FROM some_table`;\nconst set = db_set_cast\u003cFruits\u003e(row.fruits);\n\nif (set.has(Fruits.Apple)) {\n\t// we have an apple in the set\n}\n```\n\n### ``db_set_serialize\u003cT extends string\u003e(set: Iterable\u003cT\u003e | null): string``\n\nTakes an `Iterable\u003cT\u003e` and returns a database SET string. If the set is empty or `null`, it returns an empty string.\n\n```ts\nenum Fruits {\n\tApple = 'Apple',\n\tBanana = 'Banana',\n\tLemon = 'Lemon'\n};\n\n// edit existing set\nconst [row] = await sql`SELECT * FROM some_table`;\nconst fruits = db_set_cast\u003cFruits\u003e(row.fruits);\n\nif (!fruits.has(Fruits.Lemon))\n\tfruits.add(Fruits.Lemon);\n\nawait sql`UPDATE some_table SET fruits = ${sql(db_set_serialize(fruits))} WHERE id = ${row.id}`;\n\n// new set from iterable\nawait sql`UPDATE some_table SET fruits = ${sql(db_set_serialize([Fruits.Apple, Fruits.Lemon]))}`;\n```\n\n### 🔧 ``db_exists(db: SQL, table_name: string, value: string|number, column_name = 'id'): Promise\u003cboolean\u003e``\n\nReturns true if a database row exists in the table.\n\n```ts\n// checks if row exists with id 1 in 'table'\nconst exists = await db_exists(db, 'table', 1);\n\n// checks if row exists with column 'foo' = 'bar' in 'table'\nconst exists = await db_exists(db, 'table', 'bar', 'foo');\n```\n\n\u003ca id=\"api-database-schema\"\u003e\u003c/a\u003e\n## API \u003e Database \u003e Schema\n\n### 🔧 ``db_schema(db: SQL, schema_path: string, options?: SchemaOptions): Promise\u003cboolean\u003e``\n\n`db_schema` executes all revisioned `.sql` files in a given directory, applying them to the database incrementally.\n\n```ts\nconst db = new SQL('db:pw@localhost:3306/test');\nawait db_schema(db, './db/revisions');\n```\n\nThe above example will **recursively** search the `./db/revisions` directory for all `.sql` files that begin with a positive numeric identifier.\n\n```ts\ndb/revisions/000_invalid.sql // no: 0 is not valid\ndb/revisions/001_valid.sql // yes: revision 1\ndb/revisions/25-valid.sql // yes: revision 25\ndb/revisions/005_not.txt // no: .sql extension missing\ndb/revisions/invalid_500.sql // no: must begin with rev\n```\n\nRevisions are applied in **numerical order**, rather than the file sorting order from the operating system. Invalid files are **skipped** without throwing an error.\n\nBy 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.\n\n```ts\nawait db_schema(db, './db/revisions', { schema_table: 'alt_table_name' });\n```\n\nThe 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.\n\n```ts\nawait db_schema(db, './db/revisions', { recursive: false });\n```\n\nEach 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.\n\n\u003e [!CAUTION]\n\u003e Implicit commits, such as those that modify DDL, cannot be rolled back inside a transaction.\n\u003e\n\u003e 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.\n\u003e\n\u003e 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.\n\n\n```ts\ntype SchemaOptions = {\n\tschema_table: string;\n\trecursive: boolean;\n};\n\ndb_get_schema_revision(db: SQL): Promise\u003cnumber|null\u003e;\ndb_schema(db: SQL, schema_path: string, options?: SchemaOptions): Promise\u003cboolean\u003e;\n```\n\n\u003ca id=\"api-utilities\"\u003e\u003c/a\u003e\n## API \u003e Utilities\n\n### 🔧 ``filesize(bytes: number): string``\n\nReturns a human-readable string representation of a file size in bytes.\n\n```ts\nfilesize(512); // \u003e \"512 bytes\"\nfilesize(1024); // \u003e \"1 kb\"\nfilesize(1048576); // \u003e \"1 mb\"\nfilesize(1073741824); // \u003e \"1 gb\"\nfilesize(1099511627776); // \u003e \"1 tb\"\n```\n\n### 🔧 ``BiMap\u003cK, V\u003e``\n\nA bidirectional map that maintains a two-way relationship between keys and values, allowing efficient lookups in both directions.\n\n```ts\nconst users = new BiMap\u003cnumber, string\u003e();\n\n// Set key-value pairs\nusers.set(1, \"Alice\");\nusers.set(2, \"Bob\");\nusers.set(3, \"Charlie\");\n\n// Lookup by key\nusers.getByKey(1); // \u003e \"Alice\"\n\n// Lookup by value\nusers.getByValue(\"Bob\"); // \u003e 2\n\n// Check existence\nusers.hasKey(1); // \u003e true\nusers.hasValue(\"Charlie\"); // \u003e true\n\n// Delete by key or value\nusers.deleteByKey(1); // \u003e true\nusers.deleteByValue(\"Bob\"); // \u003e true\n\n// Other operations\nusers.size; // \u003e 1\nusers.clear();\n```\n\n## Legal\nThis 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.\n\nThe code in this repository is licensed under the ISC license. See the [LICENSE](LICENSE) file for more information.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkruithne%2Fspooder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkruithne%2Fspooder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkruithne%2Fspooder/lists"}