@ripple-ts/adapter-bun 0.2.208

package/README.md

@@ -0,0 +1,78 @@
+# @ripple-ts/adapter-bun
+
+Bun adapter for Ripple metaframework apps.
+
+It exposes the same `serve(fetch_handler, options?)` contract as
+`@ripple-ts/adapter-node`, backed by `Bun.serve`.
+
+## Installation
+
+```bash
+pnpm add @ripple-ts/adapter-bun
+# or
+npm install @ripple-ts/adapter-bun
+# or
+yarn add @ripple-ts/adapter-bun
+```
+
+## Usage
+
+```js
+import { serve } from '@ripple-ts/adapter-bun';
+
+const app = serve(async (request) => {
+  const url = new URL(request.url);
+
+  if (url.pathname === '/health') {
+    return new Response('ok');
+  }
+
+  return new Response('Hello from Ripple adapter-bun!', {
+    headers: { 'content-type': 'text/plain; charset=utf-8' },
+  });
+});
+
+app.listen(3000);
+```
+
+## API
+
+### `serve(fetch_handler, options?)`
+
+- `fetch_handler`:
+  `(request: Request, platform?: any) => Response | Promise<Response>`
+- `options.port` (default: `3000`)
+- `options.hostname` (default: `localhost`)
+- `options.static` (default: `{ dir: 'public' }`): serves static files before
+  middleware/handler
+  - `options.static.dir` (default: `public`, resolved from `process.cwd()`)
+  - `options.static.prefix` (default: `/`)
+  - `options.static.maxAge` (default: `86400`)
+  - `options.static.immutable` (default: `false`)
+  - set `options.static = false` to disable automatic static serving
+- `options.middleware` (optional):
+  `(request, server, next) => Response | Promise<Response> | void`
+
+Returns:
+
+- `listen(port?)`: starts Bun server and returns the Bun server instance
+- `close()`: stops the current Bun server instance
+
+### `serveStatic(dir, options?)`
+
+Creates a Bun middleware that serves static assets from `dir`.
+
+- `options.prefix` (default: `/`)
+- `options.maxAge` (default: `86400`)
+- `options.immutable` (default: `false`)
+
+## Notes
+
+- Requires Bun runtime (`Bun.serve`).
+- Static file logic and MIME type mappings are shared from `@ripple-ts/adapter`.
+- `platform` passed to `fetch_handler` contains `{ bun_server }`.
+- Unhandled errors return `500 Internal Server Error`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ripple-ts/adapter-bun",
+  "description": "Bun adapter for Ripple metaframework (Web Request/Response bridge)",
+  "license": "MIT",
+  "author": "Dominic Gannaway",
+  "version": "0.2.208",
+  "type": "module",
+  "module": "src/index.js",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "pnpm -w test --project adapter-bun"
+  },
+  "dependencies": {
+    "@ripple-ts/adapter": "workspace:*"
+  },
+  "homepage": "https://ripplejs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ripple-TS/ripple.git",
+    "directory": "packages/adapter-bun"
+  },
+  "peerDependencies": {
+    "bun": "^1.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/Ripple-TS/ripple/issues"
+  }
+}

package/src/index.js

@@ -0,0 +1,119 @@
+/** @typedef {typeof import('bun')} Bun */
+/** @typedef {Bun.Server<undefined>} Server */
+
+import {
+	DEFAULT_HOSTNAME,
+	DEFAULT_PORT,
+	internal_server_error_response,
+	run_next_middleware,
+	serveStatic as create_static_handler,
+} from '@ripple-ts/adapter';
+
+/** @typedef {import('@ripple-ts/adapter').ServeStaticDirectoryOptions} StaticServeOptions */
+
+/**
+ * @typedef {{
+ * 	port?: number,
+ * 	hostname?: string,
+ * 	middleware?: ((
+ * 		request: Request,
+ * 		server: Server,
+ * 		next: () => Promise<Response>
+ * 	) => Response | Promise<Response> | void) | null,
+ * 	static?: StaticServeOptions | false,
+ * }} ServeOptions
+ */
+
+/**
+ * @param {(request: Request, platform?: any) => Response | Promise<Response>} fetch_handler
+ * @param {ServeOptions} [options]
+ * @returns {{ listen: (port?: number) => Server, close: () => void }}
+ */
+export function serve(fetch_handler, options = {}) {
+	const {
+		port = DEFAULT_PORT,
+		hostname = DEFAULT_HOSTNAME,
+		middleware = null,
+		static: static_options = {},
+	} = options;
+
+	/** @type {ReturnType<typeof serveStatic> | null} */
+	let static_middleware = null;
+	if (static_options !== false) {
+		const { dir = 'public', ...static_handler_options } = static_options;
+		static_middleware = serveStatic(dir, static_handler_options);
+	}
+
+	/** @type {Server | null} */
+	let bun_server = null;
+
+	return {
+		listen(listen_port = port) {
+			/** @type {typeof import('bun')} */
+			const bun = globalThis.Bun;
+			if (bun == null || typeof bun.serve !== 'function') {
+				throw new Error('@ripple-ts/adapter-bun requires Bun runtime');
+			}
+
+			bun_server = bun.serve({
+				port: listen_port,
+				hostname,
+				async fetch(request, server) {
+					const platform = { bun_server: server };
+					try {
+						const run_fetch_handler = async () => {
+							return await fetch_handler(request, platform);
+						};
+
+						const run_app_middleware = async () => {
+							if (middleware !== null) {
+								return await run_next_middleware(middleware, request, server, run_fetch_handler);
+							}
+
+							return await run_fetch_handler();
+						};
+
+						if (static_middleware !== null) {
+							return await run_next_middleware(static_middleware, request, server, async () => {
+								return await run_app_middleware();
+							});
+						}
+
+						return await run_app_middleware();
+					} catch {
+						return internal_server_error_response();
+					}
+				},
+			});
+
+			return bun_server;
+		},
+		close() {
+			if (bun_server && typeof bun_server.stop === 'function') {
+				bun_server.stop();
+			}
+		},
+	};
+}
+
+/**
+ * Create a Bun middleware that serves static files from a directory
+ *
+ * @param {string} dir - Directory to serve files from (relative to cwd or absolute)
+ * @param {import('@ripple-ts/adapter').ServeStaticOptions} [options]
+ * @returns {(request: Request, server: Server, next: () => Promise<Response>) => Promise<Response>}
+ */
+export function serveStatic(dir, options = {}) {
+	const serve_static_request = create_static_handler(dir, options);
+
+	return async function static_middleware(request, server, next) {
+		void server;
+
+		const response = serve_static_request(request);
+		if (response !== null) {
+			return response;
+		}
+
+		return await next();
+	};
+}

package/tests/serve.test.js

@@ -0,0 +1,272 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { serve, serveStatic } from '../src/index.js';
+
+/** @type {any} */
+const original_bun = globalThis.Bun;
+
+afterEach(() => {
+	if (original_bun === undefined) {
+		Reflect.deleteProperty(globalThis, 'Bun');
+	} else {
+		globalThis.Bun = original_bun;
+	}
+	vi.restoreAllMocks();
+});
+
+/**
+ * @returns {{
+ * 	serve_spy: import('vitest').Mock,
+ * 	server: { stop: import('vitest').Mock },
+ * 	get_fetch: () => (request: Request, server: any) => Promise<Response>
+ * }}
+ */
+function create_bun_mock() {
+	/** @type {(request: Request, server: any) => Promise<Response>} */
+	let fetch_handler = async () => new Response('not-configured', { status: 500 });
+
+	const server = { stop: vi.fn() };
+	const serve_spy = vi.fn((options) => {
+		fetch_handler = options.fetch;
+		return server;
+	});
+
+	globalThis.Bun = {
+		serve: serve_spy,
+	};
+
+	return {
+		serve_spy,
+		server,
+		get_fetch() {
+			return fetch_handler;
+		},
+	};
+}
+
+/**
+ * @param {string} cwd
+ * @param {() => Promise<void>} run
+ * @returns {Promise<void>}
+ */
+async function with_cwd(cwd, run) {
+	const previous_cwd = process.cwd();
+	process.chdir(cwd);
+	try {
+		await run();
+	} finally {
+		process.chdir(previous_cwd);
+	}
+}
+
+describe('@ripple-ts/adapter-bun serve()', () => {
+	it('throws when Bun runtime is unavailable', () => {
+		Reflect.deleteProperty(globalThis, 'Bun');
+
+		const app = serve(() => new Response('ok'));
+		expect(() => app.listen()).toThrow('@ripple-ts/adapter-bun requires Bun runtime');
+	});
+
+	it('starts bun server and forwards request to fetch handler', async () => {
+		const { serve_spy, server, get_fetch } = create_bun_mock();
+		const fetch_handler = vi.fn(() => new Response('ok'));
+
+		const app = serve(fetch_handler);
+		const returned_server = app.listen();
+
+		expect(returned_server).toBe(server);
+		expect(serve_spy).toHaveBeenCalledTimes(1);
+		expect(serve_spy).toHaveBeenCalledWith(expect.objectContaining({ port: 3000 }));
+		expect(serve_spy).toHaveBeenCalledWith(expect.objectContaining({ hostname: 'localhost' }));
+
+		const request = new Request('http://localhost/users');
+		const response = await get_fetch()(request, server);
+
+		expect(fetch_handler).toHaveBeenCalledTimes(1);
+		expect(fetch_handler).toHaveBeenCalledWith(request, { bun_server: server });
+		expect(await response.text()).toBe('ok');
+	});
+
+	it('uses explicit listen port over default option port', () => {
+		const { serve_spy } = create_bun_mock();
+
+		const app = serve(() => new Response('ok'), { port: 8080, hostname: '0.0.0.0' });
+		app.listen(9090);
+
+		expect(serve_spy).toHaveBeenCalledWith(expect.objectContaining({ port: 9090 }));
+		expect(serve_spy).toHaveBeenCalledWith(expect.objectContaining({ hostname: '0.0.0.0' }));
+	});
+
+	it('supports middleware short-circuit responses', async () => {
+		const { server, get_fetch } = create_bun_mock();
+		const fetch_handler = vi.fn(() => new Response('handler'));
+		const middleware = vi.fn(() => new Response('middleware', { status: 202 }));
+
+		const app = serve(fetch_handler, { middleware });
+		app.listen();
+
+		const response = await get_fetch()(new Request('http://localhost/'), server);
+		expect(middleware).toHaveBeenCalledTimes(1);
+		expect(fetch_handler).not.toHaveBeenCalled();
+		expect(response.status).toBe(202);
+		expect(await response.text()).toBe('middleware');
+	});
+
+	it('supports middleware next() flow', async () => {
+		const { server, get_fetch } = create_bun_mock();
+		const fetch_handler = vi.fn(() => new Response('handler'));
+		const middleware = vi.fn(async (request, bun_server, next) => {
+			void request;
+			void bun_server;
+			return await next();
+		});
+
+		const app = serve(fetch_handler, { middleware });
+		app.listen();
+
+		const response = await get_fetch()(new Request('http://localhost/'), server);
+		expect(middleware).toHaveBeenCalledTimes(1);
+		expect(fetch_handler).toHaveBeenCalledTimes(1);
+		expect(await response.text()).toBe('handler');
+	});
+
+	it('returns 500 response when fetch handler throws', async () => {
+		const { server, get_fetch } = create_bun_mock();
+		const app = serve(() => {
+			throw new Error('boom');
+		});
+		app.listen();
+
+		const response = await get_fetch()(new Request('http://localhost/'), server);
+		expect(response.status).toBe(500);
+		expect(response.headers.get('content-type')).toBe('text/plain; charset=utf-8');
+		expect(await response.text()).toBe('Internal Server Error');
+	});
+
+	it('stops server on close()', () => {
+		const { server } = create_bun_mock();
+
+		const app = serve(() => new Response('ok'));
+		app.listen();
+		app.close();
+
+		expect(server.stop).toHaveBeenCalledTimes(1);
+	});
+
+	it('serveStatic middleware serves matching files', async () => {
+		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-bun-static-'));
+		try {
+			writeFileSync(join(temp_dir, 'app.js'), 'console.log("bun");');
+
+			const static_middleware = serveStatic(temp_dir, { prefix: '/assets' });
+			const next = vi.fn(async () => new Response('next'));
+
+			const response = await static_middleware(
+				new Request('http://localhost/assets/app.js'),
+				/** @type {any} */ ({}),
+				next,
+			);
+
+			expect(next).not.toHaveBeenCalled();
+			expect(response.status).toBe(200);
+			expect(response.headers.get('content-type')).toBe('text/javascript; charset=utf-8');
+			expect(await response.text()).toContain('console.log');
+		} finally {
+			rmSync(temp_dir, { recursive: true, force: true });
+		}
+	});
+
+	it('serveStatic middleware falls through when no file is found', async () => {
+		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-bun-static-fallthrough-'));
+		try {
+			const static_middleware = serveStatic(temp_dir, { prefix: '/assets' });
+			const next = vi.fn(async () => new Response('next'));
+
+			const response = await static_middleware(
+				new Request('http://localhost/assets/missing.js'),
+				/** @type {any} */ ({}),
+				next,
+			);
+
+			expect(next).toHaveBeenCalledTimes(1);
+			expect(await response.text()).toBe('next');
+		} finally {
+			rmSync(temp_dir, { recursive: true, force: true });
+		}
+	});
+
+	it('serves files from ./public by default', async () => {
+		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-bun-default-static-'));
+		try {
+			const public_dir = join(temp_dir, 'public');
+			mkdirSync(public_dir);
+			writeFileSync(join(public_dir, 'llms.txt'), 'hello llms');
+
+			await with_cwd(temp_dir, async () => {
+				const { server, get_fetch } = create_bun_mock();
+				const fetch_handler = vi.fn(() => new Response('fallback', { status: 404 }));
+				const app = serve(fetch_handler);
+				app.listen();
+
+				const response = await get_fetch()(new Request('http://localhost/llms.txt'), server);
+				expect(response.status).toBe(200);
+				expect(await response.text()).toBe('hello llms');
+				expect(fetch_handler).not.toHaveBeenCalled();
+			});
+		} finally {
+			rmSync(temp_dir, { recursive: true, force: true });
+		}
+	});
+
+	it('can disable default static serving via options.static = false', async () => {
+		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-bun-default-static-disabled-'));
+		try {
+			const public_dir = join(temp_dir, 'public');
+			mkdirSync(public_dir);
+			writeFileSync(join(public_dir, 'llms.txt'), 'hello llms');
+
+			await with_cwd(temp_dir, async () => {
+				const { server, get_fetch } = create_bun_mock();
+				const fetch_handler = vi.fn(() => new Response('fallback', { status: 404 }));
+				const app = serve(fetch_handler, { static: false });
+				app.listen();
+
+				const response = await get_fetch()(new Request('http://localhost/llms.txt'), server);
+				expect(response.status).toBe(404);
+				expect(await response.text()).toBe('fallback');
+				expect(fetch_handler).toHaveBeenCalledTimes(1);
+			});
+		} finally {
+			rmSync(temp_dir, { recursive: true, force: true });
+		}
+	});
+
+	it('serves static files via options.static with custom prefix and cache settings', async () => {
+		const temp_dir = mkdtempSync(join(tmpdir(), 'adapter-bun-static-options-'));
+		try {
+			writeFileSync(join(temp_dir, 'asset.txt'), 'asset-data');
+
+			const { server, get_fetch } = create_bun_mock();
+			const fetch_handler = vi.fn(() => new Response('fallback', { status: 404 }));
+			const app = serve(fetch_handler, {
+				static: {
+					dir: temp_dir,
+					prefix: '/public',
+					maxAge: 60,
+					immutable: true,
+				},
+			});
+			app.listen();
+
+			const response = await get_fetch()(new Request('http://localhost/public/asset.txt'), server);
+			expect(response.status).toBe(200);
+			expect(response.headers.get('cache-control')).toBe('public, max-age=31536000, immutable');
+			expect(await response.text()).toBe('asset-data');
+			expect(fetch_handler).not.toHaveBeenCalled();
+		} finally {
+			rmSync(temp_dir, { recursive: true, force: true });
+		}
+	});
+});

package/tests/types.test.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const types_source = readFileSync(new URL('../types/index.d.ts', import.meta.url), 'utf8');
+
+describe('@ripple-ts/adapter-bun types', () => {
+	it('uses shared ServeStaticDirectoryOptions alias from @ripple-ts/adapter', () => {
+		expect(types_source).toContain(
+			'ServeStaticDirectoryOptions as BaseServeStaticDirectoryOptions',
+		);
+		expect(types_source).toContain('static?: BaseServeStaticDirectoryOptions | false;');
+		expect(types_source).toContain('export type ServeStaticOptions = BaseServeStaticOptions;');
+	});
+
+	it('does not inline static dir type shape locally', () => {
+		expect(types_source).not.toMatch(/BaseServeStaticOptions\s*&\s*\{\s*dir\?: string;\s*\}/);
+	});
+});

package/types/index.d.ts

@@ -0,0 +1,25 @@
+import type {
+	AdapterCoreOptions,
+	FetchHandler,
+	NextMiddleware,
+	ServeStaticOptions as BaseServeStaticOptions,
+	ServeStaticDirectoryOptions as BaseServeStaticDirectoryOptions,
+	ServeResult,
+} from '@ripple-ts/adapter';
+
+export type ServeOptions = AdapterCoreOptions & {
+	middleware?: NextMiddleware<Request, any> | null;
+	static?: BaseServeStaticDirectoryOptions | false;
+};
+
+export type ServeStaticOptions = BaseServeStaticOptions;
+
+export function serve(
+	fetch_handler: FetchHandler<{ bun_server: any }>,
+	options?: ServeOptions,
+): ServeResult<any>;
+
+export function serveStatic(
+	dir: string,
+	options?: ServeStaticOptions,
+): NextMiddleware<Request, any, Response>;