@di-framework/di-framework-http 0.0.0-prerelease.302 → 0.0.0-prerelease.305

package/dist/index.js

@@ -1,54 +1,3 @@
-import { createRequire } from "node:module";
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/registry.ts
-var exports_registry = {};
-__export(exports_registry, {
-  default: () => registry_default,
-  Registry: () => Registry
-});
-
-class Registry {
-  targets = new Set;
-  addTarget(target) {
-    this.targets.add(target);
-  }
-  getTargets() {
-    return this.targets;
-  }
-}
-var registry, registry_default;
-var init_registry = __esm(() => {
-  registry = new Registry;
-  registry_default = registry;
-});
-
 // src/typed-router.ts
 import {
   Router,
@@ -120,8 +69,19 @@ function TypedRouter(opts) {
   });
   return wrapper;
 }
-// src/decorators.ts
-init_registry();
+// src/registry.ts
+class Registry {
+  targets = new Set;
+  addTarget(target) {
+    this.targets.add(target);
+  }
+  getTargets() {
+    return this.targets;
+  }
+}
+var GLOBAL_KEY = Symbol.for("@di-framework/http-registry");
+var registry = globalThis[GLOBAL_KEY] ?? (globalThis[GLOBAL_KEY] = new Registry);
+var registry_default = registry;
 
 // ../di-framework/dist/container.js
 var INJECT_METADATA_KEY = "di:inject";
@@ -530,7 +490,6 @@ function Endpoint(metadata) {
   };
 }
 // src/openapi.ts
-init_registry();
 function generateOpenAPI(options = {}, registryToUse = registry_default) {
   const spec = {
     openapi: "3.1.0",
@@ -570,10 +529,6 @@ function generateOpenAPI(options = {}, registryToUse = registry_default) {
   }
   return spec;
 }
-
-// index.ts
-init_registry();
-init_registry();
 export {
   registry_default as registry,
   json,

package/dist/src/cli.js

@@ -1,40 +1,10 @@
 #!/usr/bin/env bun
-import { createRequire } from "node:module";
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
-// src/registry.ts
-var exports_registry = {};
-__export(exports_registry, {
-  default: () => registry_default,
-  Registry: () => Registry
-});
+// src/cli.ts
+import fs from "fs";
+import path from "path";
 
+// src/registry.ts
 class Registry {
   targets = new Set;
   addTarget(target) {
@@ -44,18 +14,11 @@ class Registry {
     return this.targets;
   }
 }
-var registry, registry_default;
-var init_registry = __esm(() => {
-  registry = new Registry;
-  registry_default = registry;
-});
-
-// src/cli.ts
-import fs from "fs";
-import path from "path";
+var GLOBAL_KEY = Symbol.for("@di-framework/http-registry");
+var registry = globalThis[GLOBAL_KEY] ?? (globalThis[GLOBAL_KEY] = new Registry);
+var registry_default = registry;
 
 // src/openapi.ts
-init_registry();
 function generateOpenAPI(options = {}, registryToUse = registry_default) {
   const spec = {
     openapi: "3.1.0",
@@ -107,24 +70,13 @@ if (command === "generate") {
     console.error("Error: --controllers path is required");
     process.exit(1);
   }
-  const controllersPath = path.resolve(process.cwd(), args[controllersArg + 1]);
   async function run() {
     try {
       const controllersPathResolved = path.resolve(process.cwd(), args[controllersArg + 1]);
-      const imported = await import(controllersPathResolved);
-      let registryToUse = imported.default || imported.registry;
-      if (!registryToUse || typeof registryToUse.getTargets !== "function") {
-        try {
-          const dfHttp = await import("@di-framework/di-framework-http");
-          registryToUse = dfHttp.default || dfHttp.registry;
-        } catch {
-          const regModule = await Promise.resolve().then(() => (init_registry(), exports_registry));
-          registryToUse = regModule.default;
-        }
-      }
+      await import(controllersPathResolved);
       const spec = generateOpenAPI({
         title: "API Documentation"
-      }, registryToUse);
+      }, registry_default);
       fs.writeFileSync(outputPath, JSON.stringify(spec, null, 2));
       console.log(`Successfully generated OpenAPI spec at ${outputPath}`);
     } catch (error) {

package/index.ts

@@ -0,0 +1,5 @@
+export * from "./src/typed-router.ts";
+export * from "./src/decorators.ts";
+export * from "./src/openapi.ts";
+export * from "./src/registry.ts";
+export { default as registry } from "./src/registry.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@di-framework/di-framework-http",
-  "version": "0.0.0-prerelease.302",
+  "version": "0.0.0-prerelease.305",
   "description": "Extends di-framework with HTTP features",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,7 +22,9 @@
   "type": "module",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "index.ts",
+    "src"
   ],
   "scripts": {
     "build": "rm -rf dist && bun build ./index.ts ./src/cli.ts --outdir ./dist --target node --external itty-router && tsc --emitDeclarationOnly --declaration --outDir dist",
@@ -38,7 +40,7 @@
     "typescript": "^5"
   },
   "peerDependencies": {
-    "@di-framework/di-framework": "0.0.0-prerelease.301",
+    "@di-framework/di-framework": "^0.0.0-prerelease.305",
     "typescript": "^5"
   }
 }

package/src/cli.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, afterEach } from "bun:test";
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+const CLI_PATH = path.resolve(import.meta.dir, "cli.ts");
+const TEST_OUTPUT = "test.openapi.json";
+
+describe("CLI", () => {
+  afterEach(() => {
+    if (fs.existsSync(TEST_OUTPUT)) {
+      fs.unlinkSync(TEST_OUTPUT);
+    }
+  });
+
+  it("should show help when no command is provided", () => {
+    const { stdout } = spawnSync("bun", [CLI_PATH]);
+    expect(stdout.toString()).toContain("Usage: di-framework-http generate");
+  });
+
+  it("should error when --controllers is missing", () => {
+    const { stderr, status } = spawnSync("bun", [CLI_PATH, "generate"]);
+    expect(status).toBe(1);
+    expect(stderr.toString()).toContain(
+      "Error: --controllers path is required",
+    );
+  });
+
+  it("should generate OpenAPI spec with --controllers and --output", () => {
+    const controllersPath = path.resolve(
+      import.meta.dir,
+      "../../examples/http-router/index.ts",
+    );
+    const { stdout, status } = spawnSync("bun", [
+      CLI_PATH,
+      "generate",
+      "--controllers",
+      controllersPath,
+      "--output",
+      TEST_OUTPUT,
+    ]);
+
+    expect(status).toBe(0);
+    expect(stdout.toString()).toContain(
+      "Successfully generated OpenAPI spec at test.openapi.json",
+    );
+    expect(fs.existsSync(TEST_OUTPUT)).toBe(true);
+
+    const spec = JSON.parse(fs.readFileSync(TEST_OUTPUT, "utf8"));
+    expect(spec.openapi).toBe("3.1.0");
+    expect(spec.paths["/echo"]).toBeDefined();
+    expect(spec.paths["/echo"].post).toBeDefined();
+  });
+
+  it("should use default output path (openapi.json) if --output is missing", () => {
+    const DEFAULT_OUTPUT = "openapi.json";
+    if (fs.existsSync(DEFAULT_OUTPUT)) fs.unlinkSync(DEFAULT_OUTPUT);
+
+    const controllersPath = path.resolve(
+      import.meta.dir,
+      "../../examples/http-router/index.ts",
+    );
+    const { status } = spawnSync("bun", [
+      CLI_PATH,
+      "generate",
+      "--controllers",
+      controllersPath,
+    ]);
+
+    expect(status).toBe(0);
+    expect(fs.existsSync(DEFAULT_OUTPUT)).toBe(true);
+    fs.unlinkSync(DEFAULT_OUTPUT);
+  });
+
+  it("should error with invalid controllers path", () => {
+    const { stderr, status } = spawnSync("bun", [
+      CLI_PATH,
+      "generate",
+      "--controllers",
+      "./non-existent-file.ts",
+    ]);
+    expect(status).toBe(1);
+    expect(stderr.toString()).toContain("Error generating OpenAPI spec");
+  });
+});

package/src/cli.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env bun
+import fs from "fs";
+import path from "path";
+import { generateOpenAPI } from "./openapi.ts";
+import registry from "./registry.ts";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "generate") {
+  const outputArg = args.indexOf("--output");
+  const outputPath = outputArg !== -1 ? args[outputArg + 1] : "openapi.json";
+
+  const controllersArg = args.indexOf("--controllers");
+  if (controllersArg === -1) {
+    console.error("Error: --controllers path is required");
+    process.exit(1);
+  }
+
+  async function run() {
+    try {
+      // Import the user's controllers to trigger decorator registration
+      const controllersPathResolved = path.resolve(
+        process.cwd(),
+        args[controllersArg + 1]!,
+      );
+      await import(controllersPathResolved);
+
+      const spec = generateOpenAPI(
+        {
+          title: "API Documentation",
+        },
+        registry,
+      );
+
+      fs.writeFileSync(outputPath!, JSON.stringify(spec, null, 2));
+      console.log(`Successfully generated OpenAPI spec at ${outputPath}`);
+    } catch (error: any) {
+      console.error(`Error generating OpenAPI spec: ${error.message}`);
+      process.exit(1);
+    }
+  }
+
+  run();
+} else {
+  console.log(`
+Usage: di-framework-http generate --controllers <path-to-controllers> [options]
+
+Options:
+  --controllers <path>  Path to a file that imports all your decorated controllers
+  --output <path>       Path to save the generated JSON (default: openapi.json)
+    `);
+}

package/src/decorators.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "bun:test";
+import { Controller, Endpoint } from "./decorators.ts";
+import registry from "./registry.ts";
+
+describe("Decorators", () => {
+  it("should register a controller and its endpoints", () => {
+    const initialSize = registry.getTargets().size;
+
+    @Controller()
+    class TestController {
+      @Endpoint({ summary: "Test endpoint" })
+      static test = { isEndpoint: true, path: "/test", method: "get" };
+    }
+
+    expect(registry.getTargets().has(TestController)).toBe(true);
+    // @ts-ignore
+    expect(TestController.isController).toBe(true);
+    // @ts-ignore
+    expect(TestController.test.isEndpoint).toBe(true);
+    // @ts-ignore
+    expect(TestController.test.metadata.summary).toBe("Test endpoint");
+
+    expect(registry.getTargets().size).toBeGreaterThan(initialSize);
+  });
+
+  it("should work as a class decorator for Endpoint", () => {
+    @Endpoint({ summary: "Class level" })
+    class ClassEndpoint {}
+
+    expect(registry.getTargets().has(ClassEndpoint)).toBe(true);
+    // @ts-ignore
+    expect(ClassEndpoint.isEndpoint).toBe(true);
+    // @ts-ignore
+    expect(ClassEndpoint.metadata.summary).toBe("Class level");
+  });
+
+  it("should work on instance methods (via prototype)", () => {
+    class InstanceController {
+      @Endpoint({ summary: "Instance method" })
+      method() {}
+    }
+
+    expect(registry.getTargets().has(InstanceController)).toBe(true);
+    // @ts-ignore
+    expect(InstanceController.prototype.method.isEndpoint).toBe(true);
+  });
+});

package/src/decorators.ts

@@ -0,0 +1,51 @@
+import registry from "./registry.ts";
+import { Container as ContainerDecorator } from "@di-framework/di-framework/decorators";
+
+export function Controller(
+  options: { singleton?: boolean; container?: any } = {},
+) {
+  // Compose DI registration with OpenAPI registry marking
+  const container = ContainerDecorator(options);
+  return function (target: any) {
+    // Mark for HTTP/OpenAPI purposes
+    target.isController = true;
+    registry.addTarget(target);
+
+    // Also register with the DI container (same instance as core framework)
+    container(target);
+  };
+}
+
+export function Endpoint(metadata?: {
+  summary?: string;
+  description?: string;
+  requestBody?: any;
+  responses?: Record<string, any>;
+}) {
+  return function (target: any, propertyKey?: string) {
+    if (propertyKey) {
+      const property = target[propertyKey];
+
+      // For static methods on a class, target is the constructor.
+      // If it's a static method, target itself is the constructor.
+      const constructor =
+        typeof target === "function" ? target : target.constructor;
+      registry.addTarget(constructor);
+
+      // We'll let the generator discover the details from the property for now,
+      // or we could register it explicitly here if we had path/method info.
+      // Since TypedRouter adds path/method to the handler, we keep it as is
+      // but we can ensure the metadata is attached.
+      property.isEndpoint = true;
+      if (metadata) {
+        property.metadata = metadata;
+      }
+    } else {
+      target.isEndpoint = true;
+      if (metadata) {
+        target.metadata = metadata;
+      }
+      registry.addTarget(target);
+    }
+  };
+}

package/src/openapi.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from "bun:test";
+import { generateOpenAPI } from "./openapi.ts";
+
+describe("generateOpenAPI", () => {
+  it("should generate a default OpenAPI spec with default options", () => {
+    const spec = generateOpenAPI({}, { getTargets: () => new Set() } as any);
+
+    expect(spec.openapi).toBe("3.1.0");
+    expect(spec.info.title).toBe("Generated API");
+    expect(spec.info.version).toBe("1.0.0");
+    expect(spec.info.description).toBe(
+      "API documentation generated by @di-framework/di-framework-http.",
+    );
+    expect(spec.paths).toEqual({});
+    expect(spec.components.schemas).toEqual({});
+  });
+
+  it("should use provided options in the OpenAPI spec", () => {
+    const options = {
+      title: "Custom API",
+      version: "2.0.0",
+      description: "Custom description",
+    };
+    const spec = generateOpenAPI(options, {
+      getTargets: () => new Set(),
+    } as any);
+
+    expect(spec.info.title).toBe("Custom API");
+    expect(spec.info.version).toBe("2.0.0");
+    expect(spec.info.description).toBe("Custom description");
+  });
+
+  it("should correctly map a registry with controllers and endpoints", () => {
+    // Mocking the structure that decorators create
+    const mockController = class TestController {};
+    // @ts-ignore
+    mockController.post = () => {};
+    // @ts-ignore
+    mockController.post.isEndpoint = true;
+    // @ts-ignore
+    mockController.post.path = "/test";
+    // @ts-ignore
+    mockController.post.method = "post";
+    // @ts-ignore
+    mockController.post.metadata = {
+      summary: "Test Summary",
+      description: "Test Description",
+      requestBody: { content: { "application/json": {} } },
+      responses: { "201": { description: "Created" } },
+    };
+
+    const registry = { getTargets: () => new Set([mockController]) } as any;
+    const spec = generateOpenAPI({}, registry);
+
+    expect(spec.paths["/test"]).toBeDefined();
+    expect(spec.paths["/test"].post).toBeDefined();
+    const operation = spec.paths["/test"].post;
+    expect(operation.summary).toBe("Test Summary");
+    expect(operation.description).toBe("Test Description");
+    expect(operation.operationId).toBe("TestController.post");
+    expect(operation.requestBody).toBeDefined();
+    expect(operation.responses["201"]).toBeDefined();
+  });
+
+  it("should handle endpoints without metadata", () => {
+    const mockController = class SimpleController {};
+    // @ts-ignore
+    mockController.get = () => {};
+    // @ts-ignore
+    mockController.get.isEndpoint = true;
+    // @ts-ignore
+    mockController.get.path = "/simple";
+    // @ts-ignore
+    mockController.get.method = "get";
+
+    const registry = { getTargets: () => new Set([mockController]) } as any;
+    const spec = generateOpenAPI({}, registry);
+
+    const operation = spec.paths["/simple"].get;
+    expect(operation.summary).toBe("get"); // defaults to property key
+    expect(operation.responses["200"]).toBeDefined(); // default response
+    expect(operation.responses["200"].description).toBe("OK");
+  });
+
+  it("should handle multiple endpoints on the same path", () => {
+    const mockController = class MultiController {};
+    // @ts-ignore
+    mockController.get = () => {};
+    // @ts-ignore
+    mockController.get.isEndpoint = true;
+    // @ts-ignore
+    mockController.get.path = "/resource";
+    // @ts-ignore
+    mockController.get.method = "get";
+
+    // @ts-ignore
+    mockController.post = () => {};
+    // @ts-ignore
+    mockController.post.isEndpoint = true;
+    // @ts-ignore
+    mockController.post.path = "/resource";
+    // @ts-ignore
+    mockController.post.method = "post";
+
+    const registry = { getTargets: () => new Set([mockController]) } as any;
+    const spec = generateOpenAPI({}, registry);
+
+    expect(spec.paths["/resource"].get).toBeDefined();
+    expect(spec.paths["/resource"].post).toBeDefined();
+  });
+
+  it("should handle unknown path and method defaults", () => {
+    const mockController = class WeirdController {};
+    // @ts-ignore
+    mockController.weird = () => {};
+    // @ts-ignore
+    mockController.weird.isEndpoint = true;
+    // Note: missing path and method
+
+    const registry = { getTargets: () => new Set([mockController]) } as any;
+    const spec = generateOpenAPI({}, registry);
+
+    expect(spec.paths["/unknown"]).toBeDefined();
+    expect(spec.paths["/unknown"].get).toBeDefined();
+  });
+});

package/src/openapi.ts

@@ -0,0 +1,59 @@
+import registry from "./registry.ts";
+
+export type OpenAPIOptions = {
+  title?: string;
+  version?: string;
+  description?: string;
+  outputPath?: string;
+};
+
+export function generateOpenAPI(
+  options: OpenAPIOptions = {},
+  registryToUse = registry,
+) {
+  const spec: any = {
+    openapi: "3.1.0",
+    info: {
+      title: options.title || "Generated API",
+      version: options.version || "1.0.0",
+      description:
+        options.description ||
+        "API documentation generated by @di-framework/di-framework-http.",
+    },
+    paths: {},
+    components: {
+      schemas: {},
+    },
+  };
+
+  const targets = registryToUse.getTargets();
+
+  for (const target of targets) {
+    // Look for endpoints on the target (static properties)
+    for (const key of Object.getOwnPropertyNames(target)) {
+      const property = target[key];
+      if (property && property.isEndpoint) {
+        const path = property.path || "/unknown";
+        const method = property.method || "get";
+
+        if (!spec.paths[path]) {
+          spec.paths[path] = {};
+        }
+
+        spec.paths[path][method] = {
+          summary: property.metadata?.summary || key,
+          description: property.metadata?.description,
+          operationId: `${target.name}.${key}`,
+          requestBody: property.metadata?.requestBody,
+          responses: property.metadata?.responses || {
+            "200": {
+              description: "OK",
+            },
+          },
+        };
+      }
+    }
+  }
+
+  return spec;
+}

package/src/registry.ts

@@ -0,0 +1,34 @@
+export interface EndpointMetadata {
+  summary?: string;
+  description?: string;
+  requestBody?: any;
+  responses?: Record<string, any>;
+  [key: string]: any;
+}
+
+export interface RegisteredEndpoint {
+  target: any;
+  propertyKey: string;
+  path: string;
+  method: string;
+  metadata: EndpointMetadata;
+}
+
+export class Registry {
+  private targets = new Set<any>();
+
+  addTarget(target: any) {
+    this.targets.add(target);
+  }
+
+  getTargets() {
+    return this.targets;
+  }
+}
+
+const GLOBAL_KEY = Symbol.for("@di-framework/http-registry");
+
+const registry: Registry =
+  (globalThis as any)[GLOBAL_KEY] ?? ((globalThis as any)[GLOBAL_KEY] = new Registry());
+
+export default registry;

package/src/typed-router.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect } from "bun:test";
+import {
+  TypedRouter,
+  json,
+  type Multipart,
+  type RequestSpec,
+  type ResponseSpec,
+} from "./typed-router.ts";
+
+describe("TypedRouter", () => {
+  it("should handle GET requests", async () => {
+    const router = TypedRouter();
+    router.get("/test", () => json({ ok: true }));
+
+    const req = new Request("http://localhost/test");
+    const res = await router.fetch(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ ok: true });
+  });
+
+  it("should handle POST requests with JSON content-type", async () => {
+    const router = TypedRouter();
+    router.post("/test", (req) => json({ received: req.content }));
+
+    const req = new Request("http://localhost/test", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ hello: "world" }),
+    });
+    const res = await router.fetch(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ received: { hello: "world" } });
+  });
+
+  it("should reject POST requests without application/json", async () => {
+    const router = TypedRouter();
+    router.post("/test", () => json({ ok: true }));
+
+    const req = new Request("http://localhost/test", {
+      method: "POST",
+      headers: { "Content-Type": "text/plain" },
+      body: "hello",
+    });
+    const res = await router.fetch(req);
+    expect(res.status).toBe(415);
+    const body = (await res.json()) as any;
+    expect(body.error).toBe("Content-Type must be application/json");
+  });
+
+  it("should attach path and method to the handler", () => {
+    const router = TypedRouter();
+    const handler = router.get("/metadata", () => json({}));
+
+    expect(handler.path).toBe("/metadata");
+    expect(handler.method).toBe("get");
+  });
+
+  it("should support extra arguments in fetch", async () => {
+    type Env = { BINDING: string };
+    const router = TypedRouter<[Env]>();
+    router.get("/env", (req, env) => json({ binding: env.BINDING }));
+
+    const req = new Request("http://localhost/env");
+    const res = await router.fetch(req, { BINDING: "value" });
+    const body = await res.json();
+    expect(body).toEqual({ binding: "value" });
+  });
+
+  it("should support other HTTP methods", async () => {
+    const router = TypedRouter();
+    router.put("/put", () => json({ method: "PUT" }));
+    router.delete("/delete", () => json({ method: "DELETE" }));
+    router.patch("/patch", () => json({ method: "PATCH" }));
+
+    expect(
+      (
+        (await (
+          await router.fetch(
+            new Request("http://localhost/put", {
+              method: "PUT",
+              headers: { "Content-Type": "application/json" },
+              body: "{}",
+            }),
+          )
+        ).json()) as any
+      ).method,
+    ).toBe("PUT");
+    expect(
+      (
+        (await (
+          await router.fetch(
+            new Request("http://localhost/delete", { method: "DELETE" }),
+          )
+        ).json()) as any
+      ).method,
+    ).toBe("DELETE");
+    expect(
+      (
+        (await (
+          await router.fetch(
+            new Request("http://localhost/patch", {
+              method: "PATCH",
+              headers: { "Content-Type": "application/json" },
+              body: "{}",
+            }),
+          )
+        ).json()) as any
+      ).method,
+    ).toBe("PATCH");
+  });
+
+  it("should handle multipart POST requests with { multipart: true }", async () => {
+    const router = TypedRouter();
+    router.post<
+      RequestSpec<Multipart<{ file: File }>>,
+      ResponseSpec<{ ok: boolean }>
+    >(
+      "/upload",
+      (req) => {
+        return json({ ok: req.content instanceof FormData });
+      },
+      { multipart: true },
+    );
+
+    const formData = new FormData();
+    formData.append("file", new Blob(["hello"]), "test.txt");
+
+    const req = new Request("http://localhost/upload", {
+      method: "POST",
+      body: formData,
+    });
+    const res = await router.fetch(req);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any;
+    expect(body.ok).toBe(true);
+  });
+
+  it("should parse FormData as req.content in multipart handlers", async () => {
+    const router = TypedRouter();
+    router.post(
+      "/upload",
+      (req) => {
+        const content = req.content as FormData;
+        const name = content.get("name");
+        return json({ name });
+      },
+      { multipart: true },
+    );
+
+    const formData = new FormData();
+    formData.append("name", "test-file");
+
+    const req = new Request("http://localhost/upload", {
+      method: "POST",
+      body: formData,
+    });
+    const res = await router.fetch(req);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any;
+    expect(body.name).toBe("test-file");
+  });
+
+  it("should not enforce JSON content-type on multipart routes", async () => {
+    const router = TypedRouter();
+    router.post("/upload", () => json({ ok: true }), { multipart: true });
+
+    const formData = new FormData();
+    formData.append("field", "value");
+
+    const req = new Request("http://localhost/upload", {
+      method: "POST",
+      body: formData,
+    });
+    const res = await router.fetch(req);
+    // Should NOT return 415
+    expect(res.status).toBe(200);
+  });
+
+  it("should still reject non-JSON on non-multipart POST routes (backward compat)", async () => {
+    const router = TypedRouter();
+    router.post("/json-only", () => json({ ok: true }));
+
+    const formData = new FormData();
+    formData.append("field", "value");
+
+    const req = new Request("http://localhost/json-only", {
+      method: "POST",
+      body: formData,
+    });
+    const res = await router.fetch(req);
+    expect(res.status).toBe(415);
+  });
+});

package/src/typed-router.ts

@@ -0,0 +1,162 @@
+import {
+  Router,
+  withContent,
+  json as ittyJson,
+  type IRequest,
+} from "itty-router";
+
+/** Marker for body "shape + content-type" */
+export type Json<T> = { readonly __kind: "json"; readonly __type?: T };
+export type Multipart<T> = {
+  readonly __kind: "multipart";
+  readonly __type?: T;
+};
+
+/** Spec types you’ll use in generics */
+export type RequestSpec<BodySpec = unknown> = { readonly __req?: BodySpec };
+export type ResponseSpec<Body = unknown> = { readonly __res?: Body };
+
+/** Map a BodySpec to the actual req.content type */
+type ContentOf<BodySpec> =
+  BodySpec extends Json<infer T>
+    ? T
+    : BodySpec extends Multipart<infer _T>
+      ? FormData
+      : unknown;
+
+/** The actual request type your handlers receive */
+export type TypedRequest<ReqSpec> = IRequest & {
+  content: ContentOf<ReqSpec extends RequestSpec<infer B> ? B : never>;
+};
+
+/** Typed response helper (phantom only) */
+export type TypedResponse<ResSpec> = globalThis.Response & {
+  readonly __typedRes?: ResSpec;
+};
+
+/** HandlerController type derived from the Request/Response specs */
+export type HandlerController<ReqSpec, ResSpec, Args extends any[] = any[]> = (
+  req: TypedRequest<ReqSpec>,
+  ...args: Args
+) => TypedResponse<ResSpec> | Promise<TypedResponse<ResSpec>>;
+
+/** A typed json() that returns a Response annotated with Response<T> */
+export function json<T>(
+  data: T,
+  init?: ResponseInit,
+): TypedResponse<ResponseSpec<T>> {
+  return ittyJson(data as any, init) as any;
+}
+
+export type RouteOptions = { multipart?: boolean };
+
+export type TypedRoute<Args extends any[] = any[]> = <
+  ReqSpec = RequestSpec<unknown>,
+  ResSpec = ResponseSpec<unknown>,
+>(
+  path: string,
+  controller: HandlerController<ReqSpec, ResSpec, Args>,
+  options?: RouteOptions,
+) => TypedRouterType<Args> & {
+  path: string;
+  method: string;
+  reqSpec: ReqSpec;
+  resSpec: ResSpec;
+};
+
+export type TypedRouterType<Args extends any[] = any[]> = {
+  get: TypedRoute<Args>;
+  post: TypedRoute<Args>;
+  put: TypedRoute<Args>;
+  delete: TypedRoute<Args>;
+  patch: TypedRoute<Args>;
+  head: TypedRoute<Args>;
+  options: TypedRoute<Args>;
+  // Add other methods as needed, or use a more generic approach
+  fetch: (request: Request, ...args: Args) => Promise<Response>;
+  [key: string]: any;
+};
+
+export function TypedRouter<Args extends any[] = any[]>(
+  opts?: Parameters<typeof Router>[0],
+): TypedRouterType<Args> {
+  const r = Router(opts);
+
+  function enforceJson(req: globalThis.Request) {
+    const ct = (req.headers.get("content-type") ?? "").toLowerCase();
+    if (!ct.includes("application/json") && !ct.includes("+json")) {
+      return ittyJson(
+        { error: "Content-Type must be application/json" },
+        { status: 415 },
+      );
+    }
+    return null;
+  }
+
+  async function withFormData(req: IRequest) {
+    try {
+      (req as any).content = await (req as globalThis.Request).formData();
+    } catch {
+      // leave content undefined if parsing fails
+    }
+  }
+
+  const methodsToProxy = [
+    "get",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "head",
+    "options",
+  ];
+
+  const wrapper: any = new Proxy(r, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && methodsToProxy.includes(prop)) {
+        return (
+          path: string,
+          controller: HandlerController<any, any, Args>,
+          options?: RouteOptions,
+        ) => {
+          const handler = (...args: any[]) => {
+            const req = args[0] as IRequest & { content?: unknown };
+            const extraArgs = args.slice(1) as Args;
+            if (prop === "post" || prop === "put" || prop === "patch") {
+              if (!options?.multipart) {
+                const ctErr = enforceJson(req);
+                if (ctErr) return ctErr;
+              }
+            }
+            return controller(req as any, ...extraArgs);
+          };
+
+          const middleware = options?.multipart ? withFormData : withContent;
+          target[prop](path, middleware, handler);
+
+          const routeInfo = {
+            path,
+            method: prop,
+            handler,
+            // These are just markers for the generator to know they are there
+            // We can't easily pass the actual type at runtime but we can pass names if we had them
+          };
+
+          Object.assign(handler, routeInfo);
+
+          return handler;
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        return (...args: any[]) => {
+          const result = value.apply(target, args);
+          return result === target ? wrapper : result;
+        };
+      }
+      return value;
+    },
+  });
+
+  return wrapper;
+}