@di-framework/di-framework-http 0.0.0-prerelease.100

package/README.md

@@ -0,0 +1,209 @@
+# @di-framework/di-framework-http
+
+Lightweight TypeScript decorators and a type-safe router for [itty-router](https://github.com/kwhitley/itty-router). Includes a build-time OpenAPI 3.1 generator. Ported from `itty-decorators`.
+
+## Features
+
+- **Type-Safe Routing**: `TypedRouter` provides full TypeScript support for request bodies, response types, and context.
+- **Auto JSON Enforcement**: Automatically validates `Content-Type: application/json` for mutation methods (POST, PUT, PATCH).
+- **Multipart Support**: Opt into `multipart/form-data` handling with `Multipart<T>` and `{ multipart: true }`.
+- **Declarative Metadata**: Use `@Controller` and `@Endpoint` decorators to document your API logic directly in code.
+- **DI Integration**: `@Controller` composes the core DI `@Container` decorator, so controllers are auto-registered and can use `@Component` injection and `useContainer().resolve(...)`.
+- **OpenAPI 3.1 Support**: Generate a complete OpenAPI specification from your code at build time.
+- **Minimal Footprint**: Built on top of the ultra-light `itty-router`.
+
+## Installation
+
+```bash
+# Install the HTTP package and the core DI framework (peer dependency)
+bun add @di-framework/di-framework-http @di-framework/di-framework
+# or
+npm install @di-framework/di-framework-http @di-framework/di-framework
+```
+
+## Quick Start
+
+### 1. Create a Controller (DI-aware)
+
+Annotate your API logic using decorators and the `TypedRouter`. Controllers are automatically registered with the DI container, so you can inject services and resolve the controller instance.
+
+```typescript
+import {
+  TypedRouter,
+  json,
+  type RequestSpec,
+  type ResponseSpec,
+  type Json,
+  Controller,
+  Endpoint,
+} from "@di-framework/di-framework-http";
+import { Component, Container } from "@di-framework/di-framework/decorators";
+import { useContainer } from "@di-framework/di-framework/container";
+
+const router = TypedRouter();
+
+type EchoPayload = { message: string };
+type EchoResponse = { echoed: string; timestamp: string };
+
+// Example DI-managed service
+@Container()
+export class LoggerService {
+  log(msg: string) {
+    console.log(msg);
+  }
+}
+
+@Controller()
+export class EchoController {
+  // Because @Controller composes the core @Container decorator, this class is
+  // automatically registered with the DI container. We can inject services.
+  @Component(LoggerService)
+  private logger!: LoggerService;
+
+  echoMessage(message: string): EchoResponse {
+    this.logger.log(`Echoing: ${message}`);
+    return { echoed: message, timestamp: new Date().toISOString() };
+  }
+
+  @Endpoint({
+    summary: "Echo a message",
+    description: "Returns the provided message with a server timestamp.",
+    responses: {
+      "200": { description: "Successful echo" },
+    },
+  })
+  static post = router.post<
+    RequestSpec<Json<EchoPayload>>,
+    ResponseSpec<EchoResponse>
+  >("/echo", (req) => {
+    // Demonstrate auto DI registration: resolve the controller instance from
+    // the global container without any manual registration.
+    const controller = useContainer().resolve(EchoController);
+    return json(controller.echoMessage(req.content.message));
+  });
+}
+
+// Add a simple GET route
+router.get("/", () => json({ message: "API is healthy" }));
+
+export default {
+  fetch: (request: Request, env: any, ctx: any) =>
+    router.fetch(request, env, ctx),
+};
+```
+
+### 2. Multipart File Uploads
+
+Use `Multipart<T>` and `{ multipart: true }` to accept `multipart/form-data` instead of JSON. The handler receives `req.content` typed as `FormData`.
+
+```typescript
+import {
+  TypedRouter,
+  json,
+  type RequestSpec,
+  type ResponseSpec,
+  type Multipart,
+} from "@di-framework/di-framework-http";
+
+const router = TypedRouter();
+
+type UploadPayload = { files: File[] };
+type UploadResult = { filenames: string[] };
+
+router.post<RequestSpec<Multipart<UploadPayload>>, ResponseSpec<UploadResult>>(
+  "/upload",
+  (req) => {
+    // req.content is typed as FormData
+    const files = req.content.getAll("files") as File[];
+    return json({ filenames: files.map((f) => f.name) });
+  },
+  { multipart: true },
+);
+```
+
+### OpenAPI Generation
+
+`@di-framework/di-framework-http` provides a built-in CLI and a registry to generate OpenAPI specs from your controllers.
+
+#### Using the CLI
+
+The easiest way to generate a spec is using the provided CLI tool.
+
+```bash
+# Generate openapi.json from your controllers
+bun x di-framework-http generate --controllers ./src/index.ts
+```
+
+**Options:**
+
+- `--controllers <path>`: (Required) Path to the file that imports all your decorated controllers.
+- `--output <path>`: (Optional) Path to save the generated JSON (default: `openapi.json`).
+
+#### Manual Generation
+
+You can also generate the spec programmatically using the `generateOpenAPI` function and the default `registry`:
+
+```typescript
+import registry, { generateOpenAPI } from "@di-framework/di-framework-http";
+import "./controllers/MyController"; // Import to trigger registration
+
+const spec = generateOpenAPI(
+  {
+    title: "My API",
+    version: "1.0.0",
+  },
+  registry,
+);
+
+console.log(JSON.stringify(spec, null, 2));
+```
+
+If you need full control, you can iterate the `registry` manually:
+
+```typescript
+import registry from "@di-framework/di-framework-http";
+
+for (const target of registry.getTargets()) {
+  // target is the decorated class
+  // target[methodName].isEndpoint will be true
+  // target[methodName].metadata contains your @Endpoint info
+}
+```
+
+## API Reference
+
+### `TypedRouter<Args[]>()`
+
+A proxy for `itty-router` that enables type-safe method definitions.
+
+- `Args`: An array of types representing additional arguments passed to `fetch` (e.g., `[Env, ExecutionContext]`).
+
+### `json<T>(data: T, init?: ResponseInit)`
+
+A typed wrapper around itty-router's `json` helper.
+
+### `Json<T>` / `Multipart<T>`
+
+Body spec markers used with `RequestSpec<>` to declare the expected content type. `Json<T>` types `req.content` as `T`; `Multipart<T>` types it as `FormData`. Multipart routes require passing `{ multipart: true }` as the third argument to the route method.
+
+### `@Controller(options?)`
+
+Composed decorator that:
+
+- Marks a class for inclusion in the OpenAPI registry; and
+- Registers the class with the core DI container (same instance as `@di-framework/di-framework`).
+
+**Options:** `{ singleton?: boolean; container?: DIContainer }`
+
+### `@Endpoint(metadata)`
+
+Method or property decorator that attaches OpenAPI metadata.
+
+- `summary`: Short summary of the operation.
+- `description`: Verbose explanation.
+- `requestBody`: OpenAPI Request Body object.
+- `responses`: OpenAPI Responses object.
+
+## License
+
+MIT

package/dist/index.d.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/dist/index.js

@@ -0,0 +1,585 @@
+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,
+  withContent,
+  json as ittyJson
+} from "itty-router";
+function json(data, init) {
+  return ittyJson(data, init);
+}
+function TypedRouter(opts) {
+  const r = Router(opts);
+  function enforceJson(req) {
+    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) {
+    try {
+      req.content = await req.formData();
+    } catch {}
+  }
+  const methodsToProxy = [
+    "get",
+    "post",
+    "put",
+    "delete",
+    "patch",
+    "head",
+    "options"
+  ];
+  const wrapper = new Proxy(r, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && methodsToProxy.includes(prop)) {
+        return (path, controller, options) => {
+          const handler = (...args) => {
+            const req = args[0];
+            const extraArgs = args.slice(1);
+            if (prop === "post" || prop === "put" || prop === "patch") {
+              if (!options?.multipart) {
+                const ctErr = enforceJson(req);
+                if (ctErr)
+                  return ctErr;
+              }
+            }
+            return controller(req, ...extraArgs);
+          };
+          const middleware = options?.multipart ? withFormData : withContent;
+          target[prop](path, middleware, handler);
+          const routeInfo = {
+            path,
+            method: prop,
+            handler
+          };
+          Object.assign(handler, routeInfo);
+          return handler;
+        };
+      }
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        return (...args) => {
+          const result = value.apply(target, args);
+          return result === target ? wrapper : result;
+        };
+      }
+      return value;
+    }
+  });
+  return wrapper;
+}
+// src/decorators.ts
+init_registry();
+
+// ../di-framework/dist/container.js
+var INJECT_METADATA_KEY = "di:inject";
+var DESIGN_PARAM_TYPES_KEY = "design:paramtypes";
+var TELEMETRY_METADATA_KEY = "di:telemetry";
+var TELEMETRY_LISTENER_METADATA_KEY = "di:telemetry-listener";
+var PUBLISHER_METADATA_KEY = "di:publisher";
+var SUBSCRIBER_METADATA_KEY = "di:subscriber";
+var metadataStore = new Map;
+function defineMetadata(key, value, target) {
+  if (!metadataStore.has(target)) {
+    metadataStore.set(target, new Map);
+  }
+  metadataStore.get(target).set(key, value);
+}
+function getMetadata(key, target) {
+  return metadataStore.get(target)?.get(key);
+}
+function getOwnMetadata(key, target) {
+  return getMetadata(key, target);
+}
+
+class Container {
+  services = new Map;
+  resolutionStack = new Set;
+  listeners = new Map;
+  register(serviceClass, options = { singleton: true }) {
+    const name = serviceClass.name;
+    this.services.set(name, {
+      type: serviceClass,
+      singleton: options.singleton ?? true
+    });
+    this.services.set(serviceClass, {
+      type: serviceClass,
+      singleton: options.singleton ?? true
+    });
+    this.emit("registered", {
+      key: serviceClass,
+      singleton: options.singleton ?? true,
+      kind: "class"
+    });
+    return this;
+  }
+  registerFactory(name, factory, options = { singleton: true }) {
+    this.services.set(name, {
+      type: factory,
+      singleton: options.singleton ?? true
+    });
+    this.emit("registered", {
+      key: name,
+      singleton: options.singleton ?? true,
+      kind: "factory"
+    });
+    return this;
+  }
+  resolve(serviceClass) {
+    const key = typeof serviceClass === "string" ? serviceClass : serviceClass;
+    const keyStr = typeof serviceClass === "string" ? serviceClass : serviceClass.name;
+    if (this.resolutionStack.has(key)) {
+      throw new Error(`Circular dependency detected while resolving ${keyStr}. Stack: ${Array.from(this.resolutionStack).join(" -> ")} -> ${keyStr}`);
+    }
+    const definition = this.services.get(key);
+    if (!definition) {
+      throw new Error(`Service '${keyStr}' is not registered in the DI container`);
+    }
+    const wasCached = definition.singleton && !!definition.instance;
+    if (definition.singleton && definition.instance) {
+      this.emit("resolved", {
+        key,
+        instance: definition.instance,
+        singleton: true,
+        fromCache: true
+      });
+      return definition.instance;
+    }
+    this.resolutionStack.add(key);
+    try {
+      const instance = this.instantiate(definition.type);
+      if (definition.singleton) {
+        definition.instance = instance;
+      }
+      this.emit("resolved", {
+        key,
+        instance,
+        singleton: definition.singleton,
+        fromCache: wasCached
+      });
+      return instance;
+    } finally {
+      this.resolutionStack.delete(key);
+    }
+  }
+  construct(serviceClass, overrides = {}) {
+    const keyStr = serviceClass.name;
+    if (this.resolutionStack.has(serviceClass)) {
+      throw new Error(`Circular dependency detected while constructing ${keyStr}. Stack: ${Array.from(this.resolutionStack).join(" -> ")} -> ${keyStr}`);
+    }
+    this.resolutionStack.add(serviceClass);
+    try {
+      const instance = this.instantiate(serviceClass, overrides);
+      this.emit("constructed", { key: serviceClass, instance, overrides });
+      return instance;
+    } finally {
+      this.resolutionStack.delete(serviceClass);
+    }
+  }
+  has(serviceClass) {
+    return this.services.has(serviceClass);
+  }
+  clear() {
+    const count = this.services.size;
+    this.services.clear();
+    this.emit("cleared", { count });
+  }
+  getServiceNames() {
+    const names = new Set;
+    this.services.forEach((_, key) => {
+      if (typeof key === "string") {
+        names.add(key);
+      }
+    });
+    return Array.from(names);
+  }
+  fork(options = {}) {
+    const clone = new Container;
+    this.services.forEach((def, key) => {
+      clone.services.set(key, {
+        ...def,
+        instance: options.carrySingletons ? def.instance : undefined
+      });
+    });
+    return clone;
+  }
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set);
+    }
+    this.listeners.get(event).add(listener);
+    return () => this.off(event, listener);
+  }
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+  }
+  emit(event, payload) {
+    const listeners = this.listeners.get(event);
+    if (!listeners || listeners.size === 0)
+      return;
+    listeners.forEach((listener) => {
+      try {
+        listener(payload);
+      } catch (err) {
+        console.error(`[Container] listener for '${String(event)}' threw`, err);
+      }
+    });
+  }
+  applyEvents(instance, constructor) {
+    const className = constructor.name;
+    const subscriberMap = getMetadata(SUBSCRIBER_METADATA_KEY, constructor.prototype) || {};
+    Object.entries(subscriberMap).forEach(([event, methods]) => {
+      methods.forEach((methodName) => {
+        const method = instance[methodName];
+        if (typeof method === "function") {
+          this.on(event, (payload) => {
+            try {
+              method.call(instance, payload);
+            } catch (err) {
+              console.error(`[Container] Subscriber '${className}.${methodName}' for event '${event}' threw`, err);
+            }
+          });
+        }
+      });
+    });
+    const publisherMethods = getMetadata(PUBLISHER_METADATA_KEY, constructor.prototype) || {};
+    Object.entries(publisherMethods).forEach(([methodName, options]) => {
+      const originalMethod = instance[methodName];
+      if (typeof originalMethod === "function") {
+        const self = this;
+        const phase = options.phase ?? "after";
+        instance[methodName] = function(...args) {
+          const startTime = Date.now();
+          const emit = (result, error) => {
+            const payload = {
+              className,
+              methodName,
+              args,
+              startTime,
+              endTime: Date.now(),
+              result,
+              error
+            };
+            if (options.logging) {
+              const duration = payload.endTime - payload.startTime;
+              const status = error ? `ERROR: ${error && error.message ? error.message : String(error)}` : "SUCCESS";
+              console.log(`[Publisher] ${className}.${methodName} -> '${options.event}' - ${status} (${duration}ms)`);
+            }
+            self.emit(options.event, payload);
+          };
+          try {
+            if (phase === "before" || phase === "both") {
+              emit(undefined, undefined);
+            }
+            const result = originalMethod.apply(this, args);
+            if (result instanceof Promise) {
+              return result.then((val) => {
+                if (phase === "after" || phase === "both") {
+                  emit(val, undefined);
+                }
+                return val;
+              }).catch((err) => {
+                emit(undefined, err);
+                throw err;
+              });
+            }
+            if (phase === "after" || phase === "both") {
+              emit(result, undefined);
+            }
+            return result;
+          } catch (err) {
+            emit(undefined, err);
+            throw err;
+          }
+        };
+      }
+    });
+  }
+  instantiate(type, overrides = {}) {
+    if (typeof type !== "function") {
+      throw new Error("Service type must be a constructor or factory function");
+    }
+    if (!this.isClass(type)) {
+      return type();
+    }
+    const paramTypes = getMetadata(DESIGN_PARAM_TYPES_KEY, type) || [];
+    const paramNames = this.getConstructorParamNames(type);
+    const dependencies = [];
+    const injectMetadata = getOwnMetadata(INJECT_METADATA_KEY, type) || {};
+    const paramCount = Math.max(paramTypes.length, paramNames.length);
+    for (let i = 0;i < paramCount; i++) {
+      if (Object.prototype.hasOwnProperty.call(overrides, i)) {
+        dependencies.push(overrides[i]);
+        continue;
+      }
+      const paramType = paramTypes[i];
+      const paramName = paramNames[i];
+      const paramInjectTarget = injectMetadata[`param_${i}`];
+      if (paramInjectTarget) {
+        dependencies.push(this.resolve(paramInjectTarget));
+      } else if (paramType && paramType !== Object) {
+        if (this.has(paramType)) {
+          dependencies.push(this.resolve(paramType));
+        } else if (this.has(paramType.name)) {
+          dependencies.push(this.resolve(paramType.name));
+        } else {
+          throw new Error(`Cannot resolve dependency of type ${paramType.name} for parameter '${paramName}' in ${type.name}`);
+        }
+      } else {}
+    }
+    const instance = new type(...dependencies);
+    this.applyTelemetry(instance, type);
+    this.applyEvents(instance, type);
+    const injectProperties = getMetadata(INJECT_METADATA_KEY, type) || {};
+    const protoInjectProperties = getMetadata(INJECT_METADATA_KEY, type.prototype) || {};
+    const allInjectProperties = {
+      ...injectProperties,
+      ...protoInjectProperties
+    };
+    Object.entries(allInjectProperties).forEach(([propName, targetType]) => {
+      if (!propName.startsWith("param_") && targetType) {
+        try {
+          instance[propName] = this.resolve(targetType);
+        } catch (error) {
+          console.warn(`Failed to inject property '${propName}' on ${type.name}:`, error);
+        }
+      }
+    });
+    return instance;
+  }
+  applyTelemetry(instance, constructor) {
+    const className = constructor.name;
+    const listenerMethods = getMetadata(TELEMETRY_LISTENER_METADATA_KEY, constructor.prototype) || [];
+    listenerMethods.forEach((methodName) => {
+      const method = instance[methodName];
+      if (typeof method === "function") {
+        this.on("telemetry", (payload) => {
+          try {
+            method.call(instance, payload);
+          } catch (err) {
+            console.error(`[Container] TelemetryListener '${className}.${methodName}' threw`, err);
+          }
+        });
+      }
+    });
+    const telemetryMethods = getMetadata(TELEMETRY_METADATA_KEY, constructor.prototype) || {};
+    Object.entries(telemetryMethods).forEach(([methodName, options]) => {
+      const originalMethod = instance[methodName];
+      if (typeof originalMethod === "function") {
+        const self = this;
+        instance[methodName] = function(...args) {
+          const startTime = Date.now();
+          const emit = (result, error) => {
+            const payload = {
+              className,
+              methodName,
+              args,
+              startTime,
+              endTime: Date.now(),
+              result,
+              error
+            };
+            if (options.logging) {
+              const duration = payload.endTime - payload.startTime;
+              const status = error ? `ERROR: ${error.message || error}` : "SUCCESS";
+              console.log(`[Telemetry] ${className}.${methodName} - ${status} (${duration}ms)`);
+            }
+            self.emit("telemetry", payload);
+          };
+          try {
+            const result = originalMethod.apply(this, args);
+            if (result instanceof Promise) {
+              return result.then((val) => {
+                emit(val);
+                return val;
+              }).catch((err) => {
+                emit(undefined, err);
+                throw err;
+              });
+            }
+            emit(result);
+            return result;
+          } catch (err) {
+            emit(undefined, err);
+            throw err;
+          }
+        };
+      }
+    });
+  }
+  isClass(func) {
+    return typeof func === "function" && func.prototype && func.prototype.constructor === func;
+  }
+  getConstructorParamNames(target) {
+    const funcStr = target.toString();
+    const match = funcStr.match(/constructor\s*\(([^)]*)\)/);
+    if (!match || !match[1])
+      return [];
+    const paramsStr = match[1];
+    return paramsStr.split(",").map((param) => {
+      const trimmed = param.trim();
+      const withoutDefault = trimmed.split("=")[0] || "";
+      const withoutType = withoutDefault.split(":")[0] || "";
+      return withoutType.trim();
+    }).filter((param) => param);
+  }
+  extractParamTypesFromSource(target) {
+    const funcStr = target.toString();
+    const decoratorMatch = funcStr.match(/__decorate\(\[\s*(?:\w+\s*\([^)]*\),?\s*)*__param\((\d+),\s*(\w+)\([^)]*\)\)/g);
+    if (decoratorMatch) {
+      return [];
+    }
+    return [];
+  }
+}
+var container = new Container;
+function useContainer() {
+  return container;
+}
+
+// ../di-framework/dist/decorators.js
+var INJECTABLE_METADATA_KEY = "di:injectable";
+function Container2(options = {}) {
+  return function(constructor) {
+    const container2 = options.container ?? useContainer();
+    const singleton = options.singleton ?? true;
+    defineMetadata(INJECTABLE_METADATA_KEY, true, constructor);
+    container2.register(constructor, { singleton });
+    return constructor;
+  };
+}
+
+// src/decorators.ts
+function Controller(options = {}) {
+  const container2 = Container2(options);
+  return function(target) {
+    target.isController = true;
+    registry_default.addTarget(target);
+    container2(target);
+  };
+}
+function Endpoint(metadata) {
+  return function(target, propertyKey) {
+    if (propertyKey) {
+      const property = target[propertyKey];
+      const constructor = typeof target === "function" ? target : target.constructor;
+      registry_default.addTarget(constructor);
+      property.isEndpoint = true;
+      if (metadata) {
+        property.metadata = metadata;
+      }
+    } else {
+      target.isEndpoint = true;
+      if (metadata) {
+        target.metadata = metadata;
+      }
+      registry_default.addTarget(target);
+    }
+  };
+}
+// src/openapi.ts
+init_registry();
+function generateOpenAPI(options = {}, registryToUse = registry_default) {
+  const spec = {
+    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) {
+    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;
+}
+
+// index.ts
+init_registry();
+init_registry();
+export {
+  registry_default as registry,
+  json,
+  generateOpenAPI,
+  TypedRouter,
+  Registry,
+  Endpoint,
+  Controller
+};

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/src/cli.js

@@ -0,0 +1,144 @@
+#!/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
+});
+
+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/cli.ts
+import fs from "fs";
+import path from "path";
+
+// src/openapi.ts
+init_registry();
+function generateOpenAPI(options = {}, registryToUse = registry_default) {
+  const spec = {
+    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) {
+    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;
+}
+
+// src/cli.ts
+var args = process.argv.slice(2);
+var 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);
+  }
+  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;
+        }
+      }
+      const spec = generateOpenAPI({
+        title: "API Documentation"
+      }, registryToUse);
+      fs.writeFileSync(outputPath, JSON.stringify(spec, null, 2));
+      console.log(`Successfully generated OpenAPI spec at ${outputPath}`);
+    } catch (error) {
+      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/dist/src/decorators.d.ts

@@ -0,0 +1,10 @@
+export declare function Controller(options?: {
+    singleton?: boolean;
+    container?: any;
+}): (target: any) => void;
+export declare function Endpoint(metadata?: {
+    summary?: string;
+    description?: string;
+    requestBody?: any;
+    responses?: Record<string, any>;
+}): (target: any, propertyKey?: string) => void;

package/dist/src/openapi.d.ts

@@ -0,0 +1,7 @@
+export type OpenAPIOptions = {
+    title?: string;
+    version?: string;
+    description?: string;
+    outputPath?: string;
+};
+export declare function generateOpenAPI(options?: OpenAPIOptions, registryToUse?: import("./registry.ts").Registry): any;

package/dist/src/registry.d.ts

@@ -0,0 +1,21 @@
+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 declare class Registry {
+    private targets;
+    addTarget(target: any): void;
+    getTargets(): Set<any>;
+}
+declare const registry: Registry;
+export default registry;

package/dist/src/typed-router.d.ts

@@ -0,0 +1,53 @@
+import { Router, 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 declare function json<T>(data: T, init?: ResponseInit): TypedResponse<ResponseSpec<T>>;
+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>;
+    fetch: (request: Request, ...args: Args) => Promise<Response>;
+    [key: string]: any;
+};
+export declare function TypedRouter<Args extends any[] = any[]>(opts?: Parameters<typeof Router>[0]): TypedRouterType<Args>;
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@di-framework/di-framework-http",
+  "version": "0.0.0-prerelease.100",
+  "description": "Extends di-framework with HTTP features",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "private": false,
+  "exports": {
+    ".": {
+      "bun": "./index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "author": "github.com/geoffsee",
+  "license": "MIT",
+  "repository": "https://github.com/geoffsee/di-framework",
+  "bin": {
+    "di-framework-http": "./dist/src/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build ./index.ts ./src/cli.ts --outdir ./dist --target node --external itty-router && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "prepublishOnly": "npm run build",
+    "dev": "bun ../examples/http-router/index.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "itty-router": "^5.0.22"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "@di-framework/di-framework": "0.0.0-prerelease-0",
+    "typescript": "^5"
+  }
+}