spooder 4.2.7 → 4.2.9

package/README.md

@@ -8,10 +8,68 @@
 - It provides streamlined APIs for common server tasks in a minimalistic way, without the overhead of a full-featured web framework.
 - It is opinionated in its design to reduce complexity and overhead.
 
+The design goal behind `spooder` is not to provide a full-featured web server, but to expand the Bun runtime with a set of APIs and utilities that make it easy to develop servers with minimal overhead.
+
+> [!NOTE]
+> If you think a is missing a feature, consider opening an issue with your use-case. The goal behind `spooder` is to provide APIs that are useful for a wide range of use-cases, not to provide bespoke features better suited for userland.
+
 It consists of two components, the `CLI` and the `API`. 
 - The `CLI` is responsible for keeping the server process running, applying updates in response to source control changes, and automatically raising issues on GitHub via the canary feature.
 - The `API` provides a minimal building-block style API for developing servers, with a focus on simplicity and performance.
 
+> [!WARNING]
+> `spooder` is stable but still in active development. Backwards compatibility between versions is not guaranteed and breaking changes may be introduced. Consider pinning a specific version in your `package.json`.
+
+# CLI
+
+The `CLI` component of `spooder` is a global command-line tool for running server processes.
+
+- [CLI > Usage](#cli-usage)
+- [CLI > Dev Mode](#cli-dev-mode)
+- [CLI > Auto Restart](#cli-auto-restart)
+- [CLI > Auto Update](#cli-auto-update)
+- [CLI > Canary](#cli-canary)
+	- [CLI > Canary > Crash](#cli-canary-crash)
+	- [CLI > Canary > Sanitization](#cli-canary-sanitization)
+	- [CLI > Canary > System Information](#cli-canary-system-information)
+
+# API
+
+`spooder` exposes a simple yet powerful API for developing servers. The API is designed to be minimal to leave control in the hands of the developer and not add overhead for features you may not need.
+
+- [API > Serving](#api-serving)
+	- [`serve(port: number): Server`](#api-serving-serve)
+- [API > Routing](#api-routing)
+	- [`server.route(path: string, handler: RequestHandler, method: HTTP_METHODS)`](#api-routing-server-route)
+	- [HTTP Methods](#api-routing-methods)
+	- [Redirection Routes](#api-routing-redirection-routes)
+	- [Status Code Text](#api-routing-status-code-text)
+- [API > Routing > RequestHandler](#api-routing-request-handler)
+- [API > Routing > Fallback Handling](#api-routing-fallback-handlers)
+	- [`server.handle(status_code: number, handler: RequestHandler)`](#api-routing-server-handle)
+	- [`server.default(handler: DefaultHandler)`](#api-routing-server-default)
+	- [`server.error(handler: ErrorHandler)`](#api-routing-server-error)
+- [API > Routing > Directory Serving](#api-routing-directory-serving)
+	- [`server.dir(path: string, dir: string, handler?: DirHandler, method: HTTP_METHODS)`](#api-routing-server-dir)
+- [API > Routing > Server-Sent Events](#api-routing-server-sent-events)
+	- [`server.sse(path: string, handler: ServerSentEventHandler)`](#api-routing-server-sse)
+- [API > Routing > Webhooks](#api-routing-webhooks)
+	- [`server.webhook(secret: string, path: string, handler: WebhookHandler)`](#api-routing-server-webhook)
+- [API > Server Control](#api-server-control)
+	- [`server.stop(immediate: boolean)`](#api-server-control-server-stop)
+- [API > Error Handling](#api-error-handling)
+	- [`ErrorWithMetadata(message: string, metadata: object)`](#api-error-handling-error-with-metadata)
+	- [`caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-caution)
+	- [`panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-panic)
+	- [`safe(fn: Callable): Promise<void>`](#api-error-handling-safe)
+- [API > Content](#api-content)
+	- [`parse_template(template: string, replacements: Record<string, string>, drop_missing: boolean): string`](#api-content-parse-template)
+	- [`generate_hash_subs(length: number, prefix: string): Promise<Record<string, string>>`](#api-content-generate-hash-subs)
+	- [`apply_range(file: BunFile, request: Request): HandlerReturnType`](#api-content-apply-range)
+- [API > State Management](#api-state-management)
+	- [`set_cookie(res: Response, name: string, value: string, options?: CookieOptions)`](#api-state-management-set-cookie)
+	- [`get_cookies(source: Request | Response): Record<string, string>`](#api-state-management-get-cookies)
+
 # Installation
 
 ```bash
@@ -51,20 +109,6 @@ If there are any issues with the provided configuration, a warning will be print
 > [!NOTE]
 > Configuration warnings **do not** raise `caution` events with the `spooder` canary functionality.
 
-# CLI
-
-The `CLI` component of `spooder` is a global command-line tool for running server processes.
-
-- [CLI > Usage](#cli-usage)
-- [CLI > Dev Mode](#cli-dev-mode)
-- [CLI > Auto Restart](#cli-auto-restart)
-- [CLI > Auto Update](#cli-auto-update)
-- [CLI > Canary](#cli-canary)
-	- [CLI > Canary > Crash](#cli-canary-crash)
-	- [CLI > Canary > Sanitization](#cli-canary-sanitization)
-	- [CLI > Canary > System Information](#cli-canary-system-information)
-
-
 <a id="cli-usage"></a>
 ## CLI > Usage
 
@@ -114,7 +158,7 @@ The following differences will be observed when running in development mode:
 It is possible to detect in userland if a server is running in development mode by checking the `SPOODER_ENV` environment variable.
 
 ```ts
-if (process.env.SPOODER_DEV === 'dev') {
+if (process.env.SPOODER_ENV === 'dev') {
 	// Server is running in development mode.
 }
 ```
@@ -183,7 +227,7 @@ server.webhook(process.env.WEBHOOK_SECRET, '/webhook', payload => {
 
 `canary` is a feature in `spooder` which allows server problems to be raised as issues in your repository on GitHub.
 
-To enable this feature, you will need to configure a GitHub App and configure it:
+To enable this feature, you will need to create a GitHub App and configure it:
 
 ### 1. Create a GitHub App
 
@@ -404,41 +448,6 @@ In addition to the information provided by the developer, `spooder` also include
 }
 ```
 
-# API
-
-`spooder` exposes a simple yet powerful API for developing servers. The API is designed to be minimal to leave control in the hands of the developer and not add overhead for features you may not need.
-
-- [API > Serving](#api-serving)
-	- [`serve(port: number): Server`](#api-serving-serve)
-- [API > Routing](#api-routing)
-	- [`server.route(path: string, handler: RequestHandler)`](#api-routing-server-route)
-	- [Redirection Routes](#api-routing-redirection-routes)
-- [API > Routing > RequestHandler](#api-routing-request-handler)
-- [API > Routing > Fallback Handling](#api-routing-fallback-handlers)
-	- [`server.handle(status_code: number, handler: RequestHandler)`](#api-routing-server-handle)
-	- [`server.default(handler: DefaultHandler)`](#api-routing-server-default)
-	- [`server.error(handler: ErrorHandler)`](#api-routing-server-error)
-- [API > Routing > Directory Serving](#api-routing-directory-serving)
-	- [`server.dir(path: string, dir: string, handler?: DirHandler)`](#api-routing-server-dir)
-- [API > Routing > Server-Sent Events](#api-routing-server-sent-events)
-	- [`server.sse(path: string, handler: ServerSentEventHandler)`](#api-routing-server-sse)
-- [API > Routing > Webhooks](#api-routing-webhooks)
-	- [`server.webhook(secret: string, path: string, handler: WebhookHandler)`](#api-routing-server-webhook)
-- [API > Server Control](#api-server-control)
-	- [`server.stop(immediate: boolean)`](#api-server-control-server-stop)
-- [API > Error Handling](#api-error-handling)
-	- [`ErrorWithMetadata(message: string, metadata: object)`](#api-error-handling-error-with-metadata)
-	- [`caution(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-caution)
-	- [`panic(err_message_or_obj: string | object, ...err: object[]): Promise<void>`](#api-error-handling-panic)
-	- [`safe(fn: Callable): Promise<void>`](#api-error-handling-safe)
-- [API > Content](#api-content)
-	- [`parse_template(template: string, replacements: Record<string, string>, drop_missing: boolean): string`](#api-content-parse-template)
-	- [`generate_hash_subs(length: number, prefix: string): Promise<Record<string, string>>`](#api-content-generate-hash-subs)
-	- [`apply_range(file: BunFile, request: Request): HandlerReturnType`](#api-content-apply-range)
-- [API > State Management](#api-state-management)
-	- [`set_cookie(res: Response, name: string, value: string, options?: CookieOptions)`](#api-state-management-set-cookie)
-	- [`get_cookies(source: Request | Response): Record<string, string>`](#api-state-management-get-cookies)
-
 <a id="api-serving"></a>
 ## API > Serving
 
@@ -477,6 +486,32 @@ server.route('/test/route', (req, url) => {
 });
 ```
 
+<a id="api-routing-methods"></a>
+### HTTP Methods
+
+By default, `spooder` will register routes defined with `server.route()` and `server.dir()` as `GET` routes. Requests to these routes with other methods will return `405 Method Not Allowed`.
+
+> [!NOTE]
+> spooder does not automatically handle HEAD requests natively.
+
+This can be controlled by providing the `method` parameter with a string or array defining one or more of the following methods.
+
+```
+GET | HEAD | POST | PUT | DELETE | CONNECT | OPTIONS | TRACE | PATCH
+```
+
+```ts
+server.route('/test/route', (req, url) => {
+	if (req.method === 'GET')
+		// Handle GET request.
+	else if (req.method === 'POST')
+		// Handle POST request.
+}, ['GET', 'POST']);
+```
+
+> [!NOTE]
+> Routes defined with .sse() or .webhook() are always registered as 'GET' and 'POST' respectively and cannot be configured.
+
 <a id="api-routing-redirection-routes"></a>
 ### Redirection Routes
 
@@ -486,6 +521,7 @@ server.route('/test/route', (req, url) => {
 server.route('/redirect', () => Response.redirect('/redirected', 301));
 ```
 
+<a id="api-routing-status-code-text"></a>
 ### Status Code Text
 
 `spooder` exposes `HTTP_STATUS_CODE` to convieniently access status code text.
@@ -546,7 +582,7 @@ bar
 
 Named parameters can be used in paths by prefixing a path segment with a colon.
 
-> [!NOTE]
+> [!IMPORTANT]
 > Named parameters will overwrite existing query parameters with the same name.
 
 ```ts
@@ -878,7 +914,7 @@ try {
 
 `safe()` is a utility function that wraps a "callable" and calls `caution()` if it throws an error.
 
-> ![NOTE]
+> [!NOTE]
 > 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. 
 
 ```ts
@@ -901,7 +937,7 @@ await safe(() => {
 ## API > Content
 
 <a id="api-content-parse-template"></a>
-### 🔧 `parse_template(template: string, replacements: Record<string, string>, drop_missing: boolean): string`
+### 🔧 `parse_template(template: string, replacements: Replacements, drop_missing: boolean): string`
 
 Replace placeholders in a template string with values from a replacement object.
 
@@ -959,6 +995,29 @@ parse_template(template, replacements, true);
 </html>
 ```
 
+`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.
+
+```ts
+const replacer = (placeholder: string) => {
+	return placeholder.toUpperCase();
+};
+
+parse_template('Hello {$world}', replacer);
+```
+
+```html
+<html>
+	<head>
+		<title>TITLE</title>
+	</head>
+	<body>
+		<h1>TITLE</h1>
+		<p>CONTENT</p>
+		<p>IGNORED</p>
+	</body>
+</html>
+```
+
 `parse_template` supports looping arrays with the following syntax.
 
 ```html

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "spooder",
 	"type": "module",
-	"version": "4.2.7",
+	"version": "4.2.9",
 	"exports": {
 		".": {
 			"bun": "./src/api.ts",

package/src/api.d.ts

@@ -8,6 +8,8 @@ export declare const HTTP_STATUS_CODE: {
     [errorCode: number]: string | undefined;
     [errorCode: string]: string | undefined;
 };
+type HTTP_METHOD = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';
+type HTTP_METHODS = HTTP_METHOD | HTTP_METHOD[];
 export declare class ErrorWithMetadata extends Error {
     metadata: Record<string, unknown>;
     constructor(message: string, metadata: Record<string, unknown>);
@@ -18,7 +20,9 @@ export declare function caution(err_message_or_obj: string | object, ...err: obj
 type CallableFunction = (...args: any[]) => any;
 type Callable = Promise<any> | CallableFunction;
 export declare function safe(target_fn: Callable): Promise<void>;
-export declare function parse_template(template: string, replacements: Record<string, string | Array<string>>, drop_missing?: boolean): string;
+type ReplacerFn = (key: string) => string | Array<string>;
+type Replacements = Record<string, string | Array<string>> | ReplacerFn;
+export declare function parse_template(template: string, replacements: Replacements, drop_missing?: boolean): string;
 export declare function generate_hash_subs(length?: number, prefix?: string): Promise<Record<string, string>>;
 type CookieOptions = {
     same_site?: 'Strict' | 'Lax' | 'None';
@@ -60,9 +64,9 @@ type DirStat = PromiseType<ReturnType<typeof fs.stat>>;
 type DirHandler = (file_path: string, file: BunFile, stat: DirStat, request: Request, url: URL) => HandlerReturnType;
 export declare function serve(port: number): {
     /** Register a handler for a specific route. */
-    route: (path: string, handler: RequestHandler) => void;
+    route: (path: string, handler: RequestHandler, method?: HTTP_METHODS) => void;
     /** Serve a directory for a specific route. */
-    dir: (path: string, dir: string, handler?: DirHandler) => void;
+    dir: (path: string, dir: string, handler?: DirHandler, method?: HTTP_METHODS) => void;
     webhook: (secret: string, path: string, handler: WebhookHandler) => void;
     /** Register a default handler for all status codes. */
     default: (handler: DefaultHandler) => void;

package/src/api.ts

@@ -8,6 +8,10 @@ import { Blob } from 'node:buffer';
 
 export const HTTP_STATUS_CODE = http.STATUS_CODES;
 
+// Create enum containing HTTP methods
+type HTTP_METHOD = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'CONNECT' | 'TRACE';
+type HTTP_METHODS = HTTP_METHOD|HTTP_METHOD[];
+
 export class ErrorWithMetadata extends Error {
 	constructor(message: string, public metadata: Record<string, unknown>) {
 		super(message);
@@ -24,7 +28,7 @@ export class ErrorWithMetadata extends Error {
 			if (value instanceof Promise)
 				resolved_value = await value;
 			else if (typeof value === 'function')
-				resolved_value = value();
+				resolved_value = await value();
 			else if (value instanceof ReadableStream)
 				resolved_value = await Bun.readableStreamToText(value);
 
@@ -103,11 +107,16 @@ export async function safe(target_fn: Callable) {
 	}
 }
 
-export function parse_template(template: string, replacements: Record<string, string | Array<string>>, drop_missing = false): string {
+type ReplacerFn = (key: string) => string | Array<string>;
+type Replacements = Record<string, string | Array<string>> | ReplacerFn;
+
+export function parse_template(template: string, replacements: Replacements, drop_missing = false): string {
 	let result = '';
 	let buffer = '';
 	let buffer_active = false;
 
+	const is_replacer_fn = typeof replacements === 'function';
+
 	const template_length = template.length;
 	for (let i = 0; i < template_length; i++) {
 		const char = template[i];
@@ -122,7 +131,7 @@ export function parse_template(template: string, replacements: Record<string, st
 			if (buffer.startsWith('for:')) {
 				const loop_key = buffer.substring(4);
 
-				const loop_entries = replacements[loop_key];
+				const loop_entries = is_replacer_fn ? replacements(loop_key) : replacements[loop_key];
 				const loop_content_start_index = i + 1;
 				const loop_close_index = template.indexOf('{/for}', loop_content_start_index);
 				
@@ -143,7 +152,7 @@ export function parse_template(template: string, replacements: Record<string, st
 					i += loop_content.length + 6;
 				}
 			} else {
-				const replacement = replacements[buffer];
+				const replacement = is_replacer_fn ? replacements(buffer) : replacements[buffer];
 				if (replacement !== undefined)
 					result += replacement;
 				else if (!drop_missing)
@@ -349,8 +358,15 @@ function print_request_info(req: Request, res: Response, url: URL, request_start
 	return res;
 }
 
+function is_valid_method(method: HTTP_METHODS, req: Request): boolean {
+	if (Array.isArray(method))
+		return method.includes(req.method as HTTP_METHOD);
+
+	return req.method === method;
+}
+
 export function serve(port: number) {
-	const routes = new Array<[string[], RequestHandler]>();
+	const routes = new Array<[string[], RequestHandler, HTTP_METHODS]>();
 	const handlers = new Map<number, StatusCodeHandler>();
 	
 	let error_handler: ErrorHandler | undefined;
@@ -388,8 +404,9 @@ export function serve(port: number) {
 		try {
 			const route_array = url.pathname.split('/').filter(e => !(e === '..' || e === '.'));
 			let handler: RequestHandler | undefined;
+			let methods: HTTP_METHODS | undefined;
 
-			for (const [path, route_handler] of routes) {
+			for (const [path, route_handler, route_methods] of routes) {
 				const is_trailing_wildcard = path[path.length - 1] === '*';
 				if (!is_trailing_wildcard && path.length !== route_array.length)
 					continue;
@@ -414,20 +431,25 @@ export function serve(port: number) {
 
 				if (match) {
 					handler = route_handler;
+					methods = route_methods;
 					break;
 				}
 			}
 
 			// Check for a handler for the route.
 			if (handler !== undefined) {
-				const response = await resolve_handler(handler(req, url), status_code, true);
-				if (response instanceof Response)
-					return response;
+				if (is_valid_method(methods!, req)) {
+					const response = await resolve_handler(handler(req, url), status_code, true);
+					if (response instanceof Response)
+						return response;
 
-				// If the handler returned a status code, use that instead.
-				status_code = response;
+					// If the handler returned a status code, use that instead.
+					status_code = response;
+				} else {
+					status_code = 405; // Method Not Allowed
+				}
 			} else {
-				status_code = 404;
+				status_code = 404; // Not Found
 			}
 
 			// Fallback to checking for a handler for the status code.
@@ -472,23 +494,20 @@ export function serve(port: number) {
 
 	return {
 		/** Register a handler for a specific route. */
-		route: (path: string, handler: RequestHandler): void => {
-			routes.push([path.split('/'), handler]);
+		route: (path: string, handler: RequestHandler, method: HTTP_METHODS = 'GET'): void => {
+			routes.push([path.split('/'), handler, method]);
 		},
 
 		/** Serve a directory for a specific route. */
-		dir: (path: string, dir: string, handler?: DirHandler): void => {
+		dir: (path: string, dir: string, handler?: DirHandler, method: HTTP_METHODS = 'GET'): void => {
 			if (path.endsWith('/'))
 				path = path.slice(0, -1);
 
-			routes.push([[...path.split('/'), '*'], route_directory(path, dir, handler ?? default_directory_handler)]);
+			routes.push([[...path.split('/'), '*'], route_directory(path, dir, handler ?? default_directory_handler), method]);
 		},
 
 		webhook: (secret: string, path: string, handler: WebhookHandler): void => {
 			routes.push([path.split('/'), async (req: Request, url: URL) => {
-				if (req.method !== 'POST')
-					return 405; // Method Not Allowed
-
 				if (req.headers.get('Content-Type') !== 'application/json')
 					return 400; // Bad Request
 
@@ -504,7 +523,7 @@ export function serve(port: number) {
 					return 401; // Unauthorized
 
 				return handler(body);
-			}]);
+			}, 'POST']);
 		},
 
 		/** Register a default handler for all status codes. */
@@ -576,7 +595,7 @@ export function serve(port: number) {
 					'Cache-Control': 'no-cache',
 					'Connection': 'keep-alive'
 				}});
-			}]);
+			}, 'GET']);
 		}
 	}
 }