@typokit/platform-bun 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import type { ServerHandle, TypoKitRequest, TypoKitResponse } from "@typokit/types";
+/** Subset of Bun's Server type we rely on */
+interface BunServer {
+    port: number;
+    hostname: string;
+    stop(closeActiveConnections?: boolean): void;
+}
+/** Runtime platform metadata for diagnostics and inspect commands */
+export interface PlatformInfo {
+    runtime: string;
+    version: string;
+}
+/** Returns Bun platform info */
+export declare function getPlatformInfo(): PlatformInfo;
+/**
+ * Normalize a Web API Request (used by Bun.serve) into a TypoKitRequest.
+ */
+export declare function normalizeRequest(req: Request): Promise<TypoKitRequest>;
+/**
+ * Convert a TypoKitResponse into a Web API Response for Bun.serve().
+ */
+export declare function buildResponse(response: TypoKitResponse): Response;
+/** Handler function that receives a normalized request and returns a response */
+export type BunRequestHandler = (req: TypoKitRequest) => Promise<TypoKitResponse>;
+export interface BunServerOptions {
+    /** Optional hostname to bind to (default: "0.0.0.0") */
+    hostname?: string;
+}
+/** Result of createServer — provides listen/close and access to the underlying Bun server */
+export interface BunServerInstance {
+    /** Start listening on the given port. Returns a handle for graceful shutdown. */
+    listen(port: number): Promise<ServerHandle>;
+    /** The underlying Bun server instance (available after listen()) */
+    server: BunServer | null;
+}
+/**
+ * Create a Bun HTTP server that dispatches to a TypoKit request handler.
+ *
+ * Usage:
+ * ```ts
+ * const srv = createServer(async (req) => ({
+ *   status: 200,
+ *   headers: {},
+ *   body: { ok: true },
+ * }));
+ * const handle = await srv.listen(3000);
+ * // ... later
+ * await handle.close();
+ * ```
+ */
+export declare function createServer(handler: BunRequestHandler, options?: BunServerOptions): BunServerInstance;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,YAAY,EACZ,cAAc,EACd,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAMxB,6CAA6C;AAC7C,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,sBAAsB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAiBD,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gCAAgC;AAChC,wBAAgB,eAAe,IAAI,YAAY,CAM9C;AAiCD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CA4B5E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,CA8BjE;AAID,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,eAAe,CAAC,CAAC;AAI9B,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5C,oEAAoE;IACpE,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,gBAAqB,GAC7B,iBAAiB,CAoDnB"}

package/dist/index.js

@@ -0,0 +1,166 @@
+// @typokit/platform-bun — Bun Platform Adapter
+/** Returns Bun platform info */
+export function getPlatformInfo() {
+    const bun = globalThis.Bun;
+    return {
+        runtime: "bun",
+        version: bun?.version ?? "unknown",
+    };
+}
+// ─── Request / Response Helpers ──────────────────────────────
+/** Parse query string from a URL into a Record */
+function parseQuery(searchParams) {
+    const result = {};
+    for (const [key, value] of searchParams.entries()) {
+        const existing = result[key];
+        if (existing === undefined) {
+            result[key] = value;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            result[key] = [existing, value];
+        }
+    }
+    return result;
+}
+/** Normalize Web API headers into a flat Record */
+function normalizeHeaders(headers) {
+    const result = {};
+    headers.forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+/**
+ * Normalize a Web API Request (used by Bun.serve) into a TypoKitRequest.
+ */
+export async function normalizeRequest(req) {
+    const url = new URL(req.url);
+    let body = undefined;
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        const contentType = req.headers.get("content-type") ?? "";
+        const raw = await req.text();
+        if (raw) {
+            if (contentType.includes("application/json")) {
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    body = raw;
+                }
+            }
+            else {
+                body = raw;
+            }
+        }
+    }
+    return {
+        method: req.method.toUpperCase(),
+        path: url.pathname,
+        headers: normalizeHeaders(req.headers),
+        body,
+        query: parseQuery(url.searchParams),
+        params: {},
+    };
+}
+/**
+ * Convert a TypoKitResponse into a Web API Response for Bun.serve().
+ */
+export function buildResponse(response) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(response.headers)) {
+        if (value !== undefined) {
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    headers.append(key, v);
+                }
+            }
+            else {
+                headers.set(key, value);
+            }
+        }
+    }
+    let bodyContent = null;
+    if (response.body === null || response.body === undefined) {
+        bodyContent = null;
+    }
+    else if (typeof response.body === "string") {
+        bodyContent = response.body;
+    }
+    else {
+        if (!headers.has("content-type")) {
+            headers.set("content-type", "application/json");
+        }
+        bodyContent = JSON.stringify(response.body);
+    }
+    return new Response(bodyContent, {
+        status: response.status,
+        headers,
+    });
+}
+/**
+ * Create a Bun HTTP server that dispatches to a TypoKit request handler.
+ *
+ * Usage:
+ * ```ts
+ * const srv = createServer(async (req) => ({
+ *   status: 200,
+ *   headers: {},
+ *   body: { ok: true },
+ * }));
+ * const handle = await srv.listen(3000);
+ * // ... later
+ * await handle.close();
+ * ```
+ */
+export function createServer(handler, options = {}) {
+    const hostname = options.hostname ?? "0.0.0.0";
+    let bunServer = null;
+    const instance = {
+        get server() {
+            return bunServer;
+        },
+        listen(port) {
+            return new Promise((resolve, reject) => {
+                try {
+                    const bun = globalThis.Bun;
+                    bunServer = bun.serve({
+                        port,
+                        hostname,
+                        async fetch(req) {
+                            try {
+                                const normalized = await normalizeRequest(req);
+                                const response = await handler(normalized);
+                                return buildResponse(response);
+                            }
+                            catch (err) {
+                                return new Response(JSON.stringify({
+                                    error: "Internal Server Error",
+                                    message: err instanceof Error ? err.message : "Unknown error",
+                                }), {
+                                    status: 500,
+                                    headers: { "content-type": "application/json" },
+                                });
+                            }
+                        },
+                    });
+                    resolve({
+                        async close() {
+                            if (bunServer) {
+                                bunServer.stop(true);
+                                bunServer = null;
+                            }
+                        },
+                    });
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        },
+    };
+    return instance;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@typokit/platform-bun",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "version": "0.1.4",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@typokit/types": "0.1.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KyleBastien/typokit",
+    "directory": "packages/platform-bun"
+  },
+  "scripts": {
+    "test": "rstest run --passWithNoTests"
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,50 @@
+// Minimal Web API type declarations for Bun platform adapter.
+// These types are available in Bun natively, but we declare them here
+// so the package compiles under Node16 moduleResolution without DOM lib.
+
+declare class URL {
+  constructor(url: string, base?: string);
+  readonly pathname: string;
+  readonly searchParams: URLSearchParams;
+}
+
+declare class URLSearchParams {
+  entries(): IterableIterator<[string, string]>;
+}
+
+declare class Headers {
+  constructor();
+  get(name: string): string | null;
+  has(name: string): boolean;
+  set(name: string, value: string): void;
+  append(name: string, value: string): void;
+  forEach(callback: (value: string, key: string) => void): void;
+}
+
+declare class Request {
+  constructor(input: string, init?: RequestInit);
+  readonly url: string;
+  readonly method: string;
+  readonly headers: Headers;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}
+
+interface RequestInit {
+  method?: string;
+  headers?: Record<string, string> | Headers;
+  body?: string | null;
+}
+
+declare class Response {
+  constructor(body?: string | null, init?: ResponseInit);
+  readonly status: number;
+  readonly headers: Headers;
+  text(): Promise<string>;
+  json(): Promise<unknown>;
+}
+
+interface ResponseInit {
+  status?: number;
+  headers?: Record<string, string> | Headers;
+}

package/src/index.test.ts

@@ -0,0 +1,289 @@
+// @typokit/platform-bun — Tests
+
+import { describe, it, expect } from "@rstest/core";
+import {
+  normalizeRequest,
+  buildResponse,
+  getPlatformInfo,
+  createServer,
+} from "./index.js";
+import type { TypoKitResponse } from "@typokit/types";
+
+// ─── getPlatformInfo ─────────────────────────────────────────
+
+describe("getPlatformInfo", () => {
+  it("returns bun runtime", () => {
+    // Mock Bun global for testing in Node environment
+    const g = globalThis as unknown as Record<string, unknown>;
+    g["Bun"] = { version: "1.0.0" };
+    try {
+      const info = getPlatformInfo();
+      expect(info.runtime).toBe("bun");
+      expect(info.version).toBe("1.0.0");
+    } finally {
+      delete g["Bun"];
+    }
+  });
+
+  it("returns unknown version when Bun global is missing", () => {
+    const info = getPlatformInfo();
+    expect(info.runtime).toBe("bun");
+    expect(info.version).toBe("unknown");
+  });
+});
+
+// ─── normalizeRequest ────────────────────────────────────────
+
+describe("normalizeRequest", () => {
+  it("parses method, path, headers, and query from Request", async () => {
+    const req = new Request("http://localhost:3000/hello?foo=bar", {
+      method: "GET",
+      headers: { "x-test": "yes" },
+    });
+
+    const normalized = await normalizeRequest(req);
+
+    expect(normalized.method).toBe("GET");
+    expect(normalized.path).toBe("/hello");
+    expect(normalized.query["foo"]).toBe("bar");
+    expect(normalized.headers["x-test"]).toBe("yes");
+    expect(normalized.params).toEqual({});
+  });
+
+  it("collects JSON body when content-type is application/json", async () => {
+    const req = new Request("http://localhost:3000/data", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "test" }),
+    });
+
+    const normalized = await normalizeRequest(req);
+
+    expect(normalized.method).toBe("POST");
+    expect(normalized.body).toEqual({ name: "test" });
+  });
+
+  it("returns raw string body when content-type is not JSON", async () => {
+    const req = new Request("http://localhost:3000/text", {
+      method: "POST",
+      headers: { "content-type": "text/plain" },
+      body: "hello world",
+    });
+
+    const normalized = await normalizeRequest(req);
+    expect(normalized.body).toBe("hello world");
+  });
+
+  it("returns undefined body for GET requests", async () => {
+    const req = new Request("http://localhost:3000/empty", {
+      method: "GET",
+    });
+
+    const normalized = await normalizeRequest(req);
+    expect(normalized.body).toBeUndefined();
+  });
+
+  it("handles multiple query params with the same key", async () => {
+    const req = new Request("http://localhost:3000/multi?tag=a&tag=b", {
+      method: "GET",
+    });
+
+    const normalized = await normalizeRequest(req);
+    expect(normalized.query["tag"]).toEqual(["a", "b"]);
+  });
+});
+
+// ─── buildResponse ───────────────────────────────────────────
+
+describe("buildResponse", () => {
+  it("builds a Response with status, headers, and JSON body", () => {
+    const typoResponse: TypoKitResponse = {
+      status: 201,
+      headers: { "x-custom": "value" },
+      body: { created: true },
+    };
+
+    const response = buildResponse(typoResponse);
+
+    expect(response.status).toBe(201);
+    expect(response.headers.get("x-custom")).toBe("value");
+    expect(response.headers.get("content-type")).toBe("application/json");
+  });
+
+  it("builds a Response with string body", async () => {
+    const typoResponse: TypoKitResponse = {
+      status: 200,
+      headers: { "content-type": "text/plain" },
+      body: "hello",
+    };
+
+    const response = buildResponse(typoResponse);
+    const text = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(text).toBe("hello");
+  });
+
+  it("builds a Response with null body", () => {
+    const typoResponse: TypoKitResponse = {
+      status: 204,
+      headers: {},
+      body: null,
+    };
+
+    const response = buildResponse(typoResponse);
+    expect(response.status).toBe(204);
+  });
+
+  it("handles array header values", () => {
+    const typoResponse: TypoKitResponse = {
+      status: 200,
+      headers: { "set-cookie": ["a=1", "b=2"] },
+      body: null,
+    };
+
+    const response = buildResponse(typoResponse);
+    expect(response.headers.get("set-cookie")).toContain("a=1");
+  });
+});
+
+// ─── createServer ────────────────────────────────────────────
+
+describe("createServer", () => {
+  it("creates a server instance with listen method", () => {
+    const srv = createServer(async () => ({
+      status: 200,
+      headers: {},
+      body: null,
+    }));
+
+    expect(typeof srv.listen).toBe("function");
+    expect(srv.server).toBeNull();
+  });
+
+  it("calls Bun.serve when listen is invoked", async () => {
+    const mockServer = {
+      port: 3000,
+      hostname: "0.0.0.0",
+      stop: () => {},
+    };
+
+    const g = globalThis as unknown as Record<string, unknown>;
+    g["Bun"] = {
+      version: "1.0.0",
+      serve: () => mockServer,
+    };
+
+    try {
+      const srv = createServer(async () => ({
+        status: 200,
+        headers: {},
+        body: { ok: true },
+      }));
+
+      const handle = await srv.listen(3000);
+      expect(srv.server).not.toBeNull();
+
+      await handle.close();
+      expect(srv.server).toBeNull();
+    } finally {
+      delete g["Bun"];
+    }
+  });
+
+  it("rejects when Bun global is not available", async () => {
+    const srv = createServer(async () => ({
+      status: 200,
+      headers: {},
+      body: null,
+    }));
+
+    let error: Error | null = null;
+    try {
+      await srv.listen(3000);
+    } catch (err) {
+      error = err as Error;
+    }
+    expect(error).not.toBeNull();
+  });
+
+  it("fetch handler converts request and returns response", async () => {
+    let capturedFetch: ((req: Request) => Promise<Response>) | null = null;
+    const mockServer = {
+      port: 3001,
+      hostname: "0.0.0.0",
+      stop: () => {},
+    };
+
+    const g = globalThis as unknown as Record<string, unknown>;
+    g["Bun"] = {
+      version: "1.0.0",
+      serve: (opts: { fetch: (req: Request) => Promise<Response> }) => {
+        capturedFetch = opts.fetch;
+        return mockServer;
+      },
+    };
+
+    try {
+      const srv = createServer(async (req) => ({
+        status: 200,
+        headers: { "content-type": "application/json" },
+        body: { echo: req.path },
+      }));
+
+      await srv.listen(3001);
+
+      // Simulate a request through the captured fetch handler
+      const webReq = new Request("http://localhost:3001/test-path");
+      const webResp = await capturedFetch!(webReq);
+
+      expect(webResp.status).toBe(200);
+      const body = await webResp.json();
+      expect(body).toEqual({ echo: "/test-path" });
+
+      const handle = await srv.listen(3001);
+      await handle.close();
+    } finally {
+      delete g["Bun"];
+    }
+  });
+
+  it("fetch handler returns 500 when handler throws", async () => {
+    let capturedFetch: ((req: Request) => Promise<Response>) | null = null;
+    const mockServer = {
+      port: 3002,
+      hostname: "0.0.0.0",
+      stop: () => {},
+    };
+
+    const g = globalThis as unknown as Record<string, unknown>;
+    g["Bun"] = {
+      version: "1.0.0",
+      serve: (opts: { fetch: (req: Request) => Promise<Response> }) => {
+        capturedFetch = opts.fetch;
+        return mockServer;
+      },
+    };
+
+    try {
+      const srv = createServer(async () => {
+        throw new Error("boom");
+      });
+
+      await srv.listen(3002);
+
+      const webReq = new Request("http://localhost:3002/fail");
+      const webResp = await capturedFetch!(webReq);
+
+      expect(webResp.status).toBe(500);
+      const body = (await webResp.json()) as { error: string; message: string };
+      expect(body.error).toBe("Internal Server Error");
+      expect(body.message).toBe("boom");
+
+      const handle = await srv.listen(3002);
+      await handle.close();
+    } finally {
+      delete g["Bun"];
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,244 @@
+// @typokit/platform-bun — Bun Platform Adapter
+
+import type {
+  HttpMethod,
+  ServerHandle,
+  TypoKitRequest,
+  TypoKitResponse,
+} from "@typokit/types";
+
+// ─── Bun Type Declarations ──────────────────────────────────
+// Minimal type declarations for Bun APIs so this package compiles
+// without bun-types installed (they're only available in Bun runtimes).
+
+/** Subset of Bun's Server type we rely on */
+interface BunServer {
+  port: number;
+  hostname: string;
+  stop(closeActiveConnections?: boolean): void;
+}
+
+/** Options passed to Bun.serve() */
+interface BunServeOptions {
+  port: number;
+  hostname: string;
+  fetch(req: Request): Promise<Response> | Response;
+}
+
+/** Minimal shape of the global Bun object */
+interface BunGlobal {
+  version: string;
+  serve(options: BunServeOptions): BunServer;
+}
+
+// ─── Platform Info ───────────────────────────────────────────
+
+/** Runtime platform metadata for diagnostics and inspect commands */
+export interface PlatformInfo {
+  runtime: string;
+  version: string;
+}
+
+/** Returns Bun platform info */
+export function getPlatformInfo(): PlatformInfo {
+  const bun = (globalThis as unknown as { Bun: BunGlobal }).Bun;
+  return {
+    runtime: "bun",
+    version: bun?.version ?? "unknown",
+  };
+}
+
+// ─── Request / Response Helpers ──────────────────────────────
+
+/** Parse query string from a URL into a Record */
+function parseQuery(
+  searchParams: URLSearchParams,
+): Record<string, string | string[] | undefined> {
+  const result: Record<string, string | string[] | undefined> = {};
+  for (const [key, value] of searchParams.entries()) {
+    const existing = result[key];
+    if (existing === undefined) {
+      result[key] = value;
+    } else if (Array.isArray(existing)) {
+      existing.push(value);
+    } else {
+      result[key] = [existing, value];
+    }
+  }
+  return result;
+}
+
+/** Normalize Web API headers into a flat Record */
+function normalizeHeaders(
+  headers: Headers,
+): Record<string, string | string[] | undefined> {
+  const result: Record<string, string | string[] | undefined> = {};
+  headers.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
+
+/**
+ * Normalize a Web API Request (used by Bun.serve) into a TypoKitRequest.
+ */
+export async function normalizeRequest(req: Request): Promise<TypoKitRequest> {
+  const url = new URL(req.url);
+
+  let body: unknown = undefined;
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    const contentType = req.headers.get("content-type") ?? "";
+    const raw = await req.text();
+    if (raw) {
+      if (contentType.includes("application/json")) {
+        try {
+          body = JSON.parse(raw);
+        } catch {
+          body = raw;
+        }
+      } else {
+        body = raw;
+      }
+    }
+  }
+
+  return {
+    method: req.method.toUpperCase() as HttpMethod,
+    path: url.pathname,
+    headers: normalizeHeaders(req.headers),
+    body,
+    query: parseQuery(url.searchParams),
+    params: {},
+  };
+}
+
+/**
+ * Convert a TypoKitResponse into a Web API Response for Bun.serve().
+ */
+export function buildResponse(response: TypoKitResponse): Response {
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(response.headers)) {
+    if (value !== undefined) {
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          headers.append(key, v);
+        }
+      } else {
+        headers.set(key, value);
+      }
+    }
+  }
+
+  let bodyContent: string | null = null;
+  if (response.body === null || response.body === undefined) {
+    bodyContent = null;
+  } else if (typeof response.body === "string") {
+    bodyContent = response.body;
+  } else {
+    if (!headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+    bodyContent = JSON.stringify(response.body);
+  }
+
+  return new Response(bodyContent, {
+    status: response.status,
+    headers,
+  });
+}
+
+// ─── Request Handler Type ────────────────────────────────────
+
+/** Handler function that receives a normalized request and returns a response */
+export type BunRequestHandler = (
+  req: TypoKitRequest,
+) => Promise<TypoKitResponse>;
+
+// ─── Bun Server Options ─────────────────────────────────────
+
+export interface BunServerOptions {
+  /** Optional hostname to bind to (default: "0.0.0.0") */
+  hostname?: string;
+}
+
+// ─── Bun Server ─────────────────────────────────────────────
+
+/** Result of createServer — provides listen/close and access to the underlying Bun server */
+export interface BunServerInstance {
+  /** Start listening on the given port. Returns a handle for graceful shutdown. */
+  listen(port: number): Promise<ServerHandle>;
+  /** The underlying Bun server instance (available after listen()) */
+  server: BunServer | null;
+}
+
+/**
+ * Create a Bun HTTP server that dispatches to a TypoKit request handler.
+ *
+ * Usage:
+ * ```ts
+ * const srv = createServer(async (req) => ({
+ *   status: 200,
+ *   headers: {},
+ *   body: { ok: true },
+ * }));
+ * const handle = await srv.listen(3000);
+ * // ... later
+ * await handle.close();
+ * ```
+ */
+export function createServer(
+  handler: BunRequestHandler,
+  options: BunServerOptions = {},
+): BunServerInstance {
+  const hostname = options.hostname ?? "0.0.0.0";
+  let bunServer: BunServer | null = null;
+
+  const instance: BunServerInstance = {
+    get server(): BunServer | null {
+      return bunServer;
+    },
+    listen(port: number): Promise<ServerHandle> {
+      return new Promise((resolve, reject) => {
+        try {
+          const bun = (globalThis as unknown as { Bun: BunGlobal }).Bun;
+          bunServer = bun.serve({
+            port,
+            hostname,
+            async fetch(req: Request): Promise<Response> {
+              try {
+                const normalized = await normalizeRequest(req);
+                const response = await handler(normalized);
+                return buildResponse(response);
+              } catch (err: unknown) {
+                return new Response(
+                  JSON.stringify({
+                    error: "Internal Server Error",
+                    message:
+                      err instanceof Error ? err.message : "Unknown error",
+                  }),
+                  {
+                    status: 500,
+                    headers: { "content-type": "application/json" },
+                  },
+                );
+              }
+            },
+          });
+
+          resolve({
+            async close(): Promise<void> {
+              if (bunServer) {
+                bunServer.stop(true);
+                bunServer = null;
+              }
+            },
+          });
+        } catch (err) {
+          reject(err);
+        }
+      });
+    },
+  };
+
+  return instance;
+}