ingenium 0.0.1

package/src/openapi/generate.ts

@@ -0,0 +1,251 @@
+import type { IngeniumApp } from '../app.ts'
+import { isStandardSchema } from '../schema/standard.ts'
+import { Router, flattenRouter } from '../router/router.ts'
+import type { HttpMethod } from '../router/types.ts'
+import { descriptorKey, mergeDescriptor, type RouteDescriptor } from './describe.ts'
+import { extractPathParams } from './extract-params.ts'
+import type {
+  Components,
+  Info,
+  MediaType,
+  OpenApiSpec,
+  Operation,
+  PathItem,
+  RequestBody,
+  Response,
+  Schema,
+  SecurityRequirement,
+  SecurityScheme,
+  Server,
+  Tag,
+} from './types.ts'
+
+/** Public options for `generateOpenApi(app, opts)`. */
+export interface GenerateOpenApiOptions {
+  info: Info
+  servers?: Server[]
+  tags?: Tag[]
+  security?: SecurityRequirement[]
+  /**
+   * Auto-tag generated operations by path prefix. The longest matching
+   * prefix wins. Routes that already have `tags` in their descriptor are
+   * left alone.
+   *
+   * @example { '/users': 'users', '/auth': 'auth' }
+   */
+  tagsByPrefix?: Record<string, string>
+  /**
+   * Hide routes whose path matches any entry. Strings match exactly,
+   * RegExps are tested against the full path.
+   */
+  excludePaths?: (string | RegExp)[]
+  /** Pass-through `components.securitySchemes`. */
+  securitySchemes?: Record<string, SecurityScheme>
+  /**
+   * Optional additional schemas to merge into `components.schemas`. Useful
+   * when you reference shared models via `$ref: '#/components/schemas/X'`.
+   */
+  componentSchemas?: Record<string, Schema>
+}
+
+/**
+ * Generate an OpenAPI 3.1 spec from a composed (or uncomposed) IngeniumApp.
+ * Walks the registration journal — does not require `compose()` to have run.
+ *
+ * Schema-conversion strategy (in priority order):
+ *   1. If a request/response schema has a `toJsonSchema()` method (Zod 3.24+,
+ *      ArkType, Effect Schema, etc.), call it.
+ *   2. If it looks like a Standard Schema (has `~standard`), emit `{}` plus
+ *      `x-schema-source: '<vendor>-untranslated'` as a TODO marker.
+ *   3. Otherwise, pass the value through unchanged (assumed JSON Schema).
+ */
+export function generateOpenApi(
+  app: IngeniumApp,
+  opts: GenerateOpenApiOptions,
+): OpenApiSpec {
+  const router = getRouter(app)
+  const descriptors = getDescriptors(app)
+  const flat = flattenRouter(router)
+
+  const paths: Record<string, PathItem> = {}
+  const tagsByPrefix = sortedTagsByPrefix(opts.tagsByPrefix)
+  const exclude = opts.excludePaths ?? []
+
+  for (const route of flat.routes) {
+    if (isExcluded(route.path, exclude)) continue
+
+    const desc = descriptors.get(descriptorKey(route.method, route.path))
+    if (desc?.hidden) continue
+
+    const oasPath = toOpenApiPath(route.path)
+    const item: PathItem = paths[oasPath] ?? (paths[oasPath] = {})
+
+    const op: Operation = {
+      parameters: extractPathParams(route.path),
+      responses: { default: { description: 'Default response' } },
+    }
+
+    // Auto-tag by prefix if no descriptor tags were provided.
+    if (!desc?.tags) {
+      const tag = matchTag(route.path, tagsByPrefix)
+      if (tag) op.tags = [tag]
+    }
+
+    mergeDescriptor(op, desc)
+
+    // Convert any Standard/Zod-style schemas inside requestBody.content.
+    if (op.requestBody) {
+      op.requestBody = convertRequestBodySchemas(op.requestBody)
+    }
+    if (op.responses) {
+      const r: Record<string, Response> = {}
+      for (const k of Object.keys(op.responses)) {
+        r[k] = convertResponseSchemas(op.responses[k]!)
+      }
+      op.responses = r
+    }
+
+    // PathItem's method keys are typed as Operation but `keyof PathItem` widens
+    // to include `parameters` / `summary` / `description`. Cast the slot.
+    ;(item as Record<string, Operation>)[methodKey(route.method)] = op
+  }
+
+  const components: Components = {}
+  if (opts.securitySchemes) components.securitySchemes = opts.securitySchemes
+  if (opts.componentSchemas) components.schemas = opts.componentSchemas
+
+  const spec: OpenApiSpec = {
+    openapi: '3.1.0',
+    info: opts.info,
+    paths,
+  }
+  if (opts.servers) spec.servers = opts.servers
+  if (opts.tags) spec.tags = opts.tags
+  if (opts.security) spec.security = opts.security
+  if (Object.keys(components).length > 0) spec.components = components
+
+  return spec
+}
+
+// ───── helpers ──────────────────────────────────────────────────────────────
+
+/** Reach into the app's private `router` field — public surface intentionally narrow. */
+function getRouter(app: IngeniumApp): Router {
+  const r = (app as unknown as { router?: Router })['router']
+  if (!(r instanceof Router)) {
+    throw new TypeError(
+      'generateOpenApi: app.router is not a Router instance — pass the value returned by `ingenium()`.',
+    )
+  }
+  return r
+}
+
+/** Reach into the descriptor map (set up by the integration in app.ts). */
+function getDescriptors(app: IngeniumApp): Map<string, RouteDescriptor> {
+  const m = (app as unknown as { _routeDescriptors?: Map<string, RouteDescriptor> })['_routeDescriptors']
+  return m instanceof Map ? m : new Map()
+}
+
+/** Convert Ingenium path syntax to OpenAPI: `:id` → `{id}`, `*path` → `{path}`. */
+function toOpenApiPath(path: string): string {
+  if (!path) return '/'
+  const out = path
+    .split('/')
+    .map((seg) => {
+      if (!seg) return seg
+      if (seg[0] === ':') {
+        const isOpt = seg.endsWith('?')
+        const name = isOpt ? seg.slice(1, -1) : seg.slice(1)
+        return `{${name}}`
+      }
+      if (seg[0] === '*') {
+        const name = seg.slice(1) || 'wildcard'
+        return `{${name}}`
+      }
+      return seg
+    })
+    .join('/')
+  return out || '/'
+}
+
+function methodKey(m: HttpMethod): keyof PathItem {
+  return m.toLowerCase() as keyof PathItem
+}
+
+function isExcluded(path: string, excludes: (string | RegExp)[]): boolean {
+  for (const ex of excludes) {
+    if (typeof ex === 'string') {
+      if (ex === path) return true
+    } else if (ex.test(path)) {
+      return true
+    }
+  }
+  return false
+}
+
+function sortedTagsByPrefix(map: Record<string, string> | undefined): [string, string][] {
+  if (!map) return []
+  return Object.entries(map).sort((a, b) => b[0].length - a[0].length)
+}
+
+function matchTag(path: string, tagsByPrefix: [string, string][]): string | undefined {
+  for (const [prefix, tag] of tagsByPrefix) {
+    if (path === prefix || path.startsWith(prefix + '/') || path.startsWith(prefix)) {
+      return tag
+    }
+  }
+  return undefined
+}
+
+function convertRequestBodySchemas(rb: RequestBody): RequestBody {
+  const out: RequestBody = { ...rb, content: {} }
+  for (const [type, media] of Object.entries(rb.content)) {
+    out.content[type] = convertMediaSchema(media)
+  }
+  return out
+}
+
+function convertResponseSchemas(res: Response): Response {
+  if (!res.content) return res
+  const next: Response = { ...res, content: {} }
+  for (const [type, media] of Object.entries(res.content)) {
+    next.content![type] = convertMediaSchema(media)
+  }
+  return next
+}
+
+function convertMediaSchema(media: MediaType): MediaType {
+  if (!media.schema) return media
+  const converted = toJsonSchema(media.schema)
+  if (converted === media.schema) return media
+  return { ...media, schema: converted }
+}
+
+/**
+ * Best-effort schema conversion. Returns the input unchanged if it's already
+ * a plain JSON Schema; otherwise tries known conversion paths.
+ */
+function toJsonSchema(schema: unknown): Schema {
+  if (schema === null || typeof schema !== 'object') return schema as Schema
+
+  // 1. Native `toJsonSchema()` (Zod 3.24+, ArkType, Effect Schema, etc.)
+  const maybe = schema as { toJsonSchema?: () => unknown }
+  if (typeof maybe.toJsonSchema === 'function') {
+    try {
+      const out = maybe.toJsonSchema()
+      if (out && typeof out === 'object') return out as Schema
+    } catch {
+      // fall through to placeholder
+    }
+  }
+
+  // 2. Standard Schema fallback — emit a marker so users know to add a
+  //    converter. We can't introspect the validator without running it.
+  if (isStandardSchema(schema)) {
+    const vendor = schema['~standard'].vendor || 'unknown'
+    return { 'x-schema-source': `${vendor}-untranslated` }
+  }
+
+  // 3. Pass through (assumed JSON Schema literal).
+  return schema as Schema
+}

package/src/openapi/handler.ts

@@ -0,0 +1,73 @@
+import type { IngeniumApp } from '../app.ts'
+import type { IngeniumContext } from '../context/context.ts'
+import type { IngeniumHandler } from '../middleware/types.ts'
+import { generateOpenApi, type GenerateOpenApiOptions } from './generate.ts'
+import type { OpenApiSpec } from './types.ts'
+
+/**
+ * Build a route handler that serves the generated OpenAPI spec as JSON.
+ *
+ * The spec is generated lazily on the first request that hits this handler
+ * and cached on the app under a private symbol. The cache invalidates when
+ * the registration journal length changes — i.e. when new routes are added —
+ * so live-registered routes are reflected on the next request.
+ *
+ * @example
+ * app.get('/openapi.json', ingenium.openapiHandler({
+ *   info: { title: 'My API', version: '1.0.0' },
+ * }))
+ */
+export function openapiHandler(opts: GenerateOpenApiOptions): IngeniumHandler {
+  type Cache = { journalLen: number; descriptorVer: number; spec: OpenApiSpec }
+  let cache: Cache | null = null
+
+  return (ctx: IngeniumContext): void => {
+    const app = resolveApp(ctx)
+    if (!app) {
+      // The integration shim stamps `ctx.state._ingeniumApp` for us; if it's
+      // missing the user is on an older app build that hasn't applied the
+      // shim. Surface a clear error rather than silently emitting an empty
+      // spec.
+      ctx.json(
+        {
+          error: 'openapiHandler: ctx.state._ingeniumApp is missing — apply the integration shim from src/_pending-context-additions/openapi.ts',
+        },
+        500,
+      )
+      return
+    }
+
+    const journalLen = readJournalLen(app)
+    const descriptorVer = readDescriptorVersion(app)
+
+    if (
+      cache === null
+      || cache.journalLen !== journalLen
+      || cache.descriptorVer !== descriptorVer
+    ) {
+      cache = { journalLen, descriptorVer, spec: generateOpenApi(app, opts) }
+    }
+    ctx.json(cache.spec)
+  }
+}
+
+/**
+ * Pull the owning IngeniumApp off the context. We stash a reference under
+ * `ctx.state._ingeniumApp` from the integration shim in app.ts; if it's
+ * missing (older app, no integration), fall back to `ctx.state.app`.
+ */
+function resolveApp(ctx: IngeniumContext): IngeniumApp | null {
+  const fromState = (ctx.state as Record<string, unknown>)._ingeniumApp
+    ?? (ctx.state as Record<string, unknown>).app
+  return (fromState as IngeniumApp | undefined) ?? null
+}
+
+function readJournalLen(app: IngeniumApp): number {
+  const router = (app as unknown as { router?: { journal: unknown[] } }).router
+  return router?.journal?.length ?? 0
+}
+
+function readDescriptorVersion(app: IngeniumApp): number {
+  // Bumped by `app.describe()` so descriptor edits invalidate the cache too.
+  return (app as unknown as { _routeDescriptorVersion?: number })._routeDescriptorVersion ?? 0
+}

package/src/openapi/types.ts

@@ -0,0 +1,145 @@
+/**
+ * Minimal OpenAPI 3.1 type surface — just enough for what Ingenium
+ * generates today. Not a full mirror of the spec; we keep it intentionally
+ * narrow so the generator's outputs typecheck without dragging in a
+ * 4000-line ambient module.
+ *
+ * Spec reference: https://spec.openapis.org/oas/v3.1.0
+ *
+ * Intentional gaps (out of scope for v0.0.1, document-as-TODO):
+ * - `callbacks`, `links`, `webhooks` — none of these have a registration
+ *   surface in Ingenium yet.
+ * - `discriminator` / `xml` — schema is passed through verbatim, so callers
+ *   can include these themselves if they want to.
+ * - `pathItems` under `components` — we only emit operations under `paths`.
+ */
+
+/** Permissive `$ref`-or-inline union used in many slots. */
+export type Ref<T> = T | { $ref: string }
+
+/** A JSON Schema fragment (per OpenAPI 3.1 = full JSON Schema 2020-12). */
+export type Schema = Record<string, unknown>
+
+/** Where a parameter lives. Ingenium only emits `path` from route syntax. */
+export type ParameterLocation = 'query' | 'header' | 'path' | 'cookie'
+
+export interface Parameter {
+  name: string
+  in: ParameterLocation
+  description?: string
+  required?: boolean
+  deprecated?: boolean
+  schema?: Schema
+  example?: unknown
+  examples?: Record<string, Example>
+  /** Free-form passthrough so callers can stamp `x-*` extensions. */
+  [extension: `x-${string}`]: unknown
+}
+
+export interface Example {
+  summary?: string
+  description?: string
+  value?: unknown
+  externalValue?: string
+}
+
+export interface MediaType {
+  schema?: Schema
+  example?: unknown
+  examples?: Record<string, Example>
+}
+
+export interface RequestBody {
+  description?: string
+  required?: boolean
+  content: Record<string, MediaType>
+}
+
+export interface Response {
+  description: string
+  headers?: Record<string, Ref<Header>>
+  content?: Record<string, MediaType>
+}
+
+export interface Header {
+  description?: string
+  required?: boolean
+  deprecated?: boolean
+  schema?: Schema
+}
+
+export interface SecurityRequirement {
+  [name: string]: string[]
+}
+
+export interface Operation {
+  tags?: string[]
+  summary?: string
+  description?: string
+  operationId?: string
+  parameters?: Parameter[]
+  requestBody?: RequestBody
+  responses?: Record<string, Response>
+  deprecated?: boolean
+  security?: SecurityRequirement[]
+  /** Free-form passthrough so callers can stamp `x-*` extensions. */
+  [extension: `x-${string}`]: unknown
+}
+
+export type PathItem = Partial<Record<
+  'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options' | 'trace',
+  Operation
+>> & {
+  summary?: string
+  description?: string
+  parameters?: Parameter[]
+}
+
+export interface Server {
+  url: string
+  description?: string
+  variables?: Record<string, { default: string; enum?: string[]; description?: string }>
+}
+
+export interface Tag {
+  name: string
+  description?: string
+}
+
+export interface Info {
+  title: string
+  version: string
+  description?: string
+  termsOfService?: string
+  contact?: { name?: string; url?: string; email?: string }
+  license?: { name: string; url?: string; identifier?: string }
+  summary?: string
+}
+
+export interface Components {
+  schemas?: Record<string, Schema>
+  responses?: Record<string, Response>
+  parameters?: Record<string, Parameter>
+  examples?: Record<string, Example>
+  requestBodies?: Record<string, RequestBody>
+  headers?: Record<string, Header>
+  securitySchemes?: Record<string, SecurityScheme>
+}
+
+/**
+ * Loose security-scheme type — we do not interpret this, we pass it through
+ * verbatim to `components.securitySchemes`. Use the OpenAPI spec's full
+ * shape (apiKey / http / oauth2 / openIdConnect / mutualTLS).
+ */
+export type SecurityScheme = Record<string, unknown>
+
+export interface OpenApiSpec {
+  openapi: '3.1.0'
+  info: Info
+  servers?: Server[]
+  paths: Record<string, PathItem>
+  components?: Components
+  security?: SecurityRequirement[]
+  tags?: Tag[]
+  externalDocs?: { url: string; description?: string }
+}

package/src/plugin/decorators.ts

@@ -0,0 +1,100 @@
+import type { IngeniumContext } from '../context/context.ts'
+import type { Decorator, EagerDecorator, LazyDecorator } from './types.ts'
+
+interface LazyEntry {
+  name: string
+  factory: LazyDecorator
+}
+
+interface EagerEntry {
+  name: string
+  factory: EagerDecorator
+}
+
+/**
+ * Per-app registry of decorators. Decorators are NOT installed onto
+ * `IngeniumContext.prototype` — that would mutate a shared class and leak across
+ * apps in the same process. Instead, `applyTo(ctx)` writes them onto each
+ * pooled context instance at request start.
+ *
+ * # Lazy vs eager — perf trade-off
+ *
+ * - **Lazy** (`decorate`): installed via `Object.defineProperty` with a
+ *   getter. The getter computes on first access, then redefines itself as
+ *   a plain data property holding the resolved value (define-self pattern).
+ *   Subsequent reads cost a normal property access — no getter call. Use
+ *   this for values that may not be needed (e.g. `ctx.user` on public
+ *   routes), and for values whose computation is non-trivial (DB lookups,
+ *   token decoding).
+ *
+ * - **Eager** (`decorateRequest`): factory is invoked at request start,
+ *   value assigned directly. Use this for cheap values that virtually every
+ *   handler will read (e.g. `ctx.startedAt = Date.now()`). Avoids the
+ *   per-property getter-redefinition overhead.
+ *
+ * # Pool reuse
+ *
+ * Pooled contexts are reset between requests; the `IngeniumContext.reset()`
+ * method does not know about decorator names, so each request re-applies
+ * via `applyTo(ctx)`. Lazy `defineProperty` overwrites the previous slot
+ * configuration cleanly; eager assignment overwrites the previous value.
+ * No leakage between requests.
+ */
+export class DecoratorRegistry {
+  private readonly lazy: LazyEntry[] = []
+  private readonly eager: EagerEntry[] = []
+
+  /** Register a lazy decorator. Computed on first access; cached thereafter. */
+  decorate<T>(name: string, factory: LazyDecorator<T>): void {
+    this.lazy.push({ name, factory: factory as Decorator })
+  }
+
+  /** Register an eager decorator. Factory runs at the start of every request. */
+  decorateRequest<T>(name: string, factory: EagerDecorator<T>): void {
+    this.eager.push({ name, factory: factory as Decorator })
+  }
+
+  /** True when any decorator is registered (lets the hot path skip work). */
+  hasAny(): boolean {
+    return this.lazy.length > 0 || this.eager.length > 0
+  }
+
+  /**
+   * Install all registered decorators onto a single context instance.
+   * Called by `app.handle` after `onRequest` hooks and before dispatch.
+   */
+  applyTo(ctx: IngeniumContext): void {
+    // Eager: simple assignment.
+    for (let i = 0; i < this.eager.length; i++) {
+      const entry = this.eager[i]!
+      ;(ctx as unknown as Record<string, unknown>)[entry.name] = entry.factory(ctx)
+    }
+    // Lazy: define-self getter.
+    for (let i = 0; i < this.lazy.length; i++) {
+      const entry = this.lazy[i]!
+      defineLazy(ctx, entry.name, entry.factory)
+    }
+  }
+}
+
+/**
+ * Install a getter that computes once, then replaces itself with a plain
+ * data property holding the resolved value. After first access, reads are
+ * free of any getter overhead.
+ */
+function defineLazy(ctx: IngeniumContext, name: string, factory: LazyDecorator): void {
+  Object.defineProperty(ctx, name, {
+    configurable: true,
+    enumerable: true,
+    get() {
+      const value = factory(ctx)
+      Object.defineProperty(ctx, name, {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value,
+      })
+      return value
+    },
+  })
+}

package/src/plugin/hooks.ts

@@ -0,0 +1,114 @@
+import type { IngeniumContext } from '../context/context.ts'
+import type {
+  Hooks,
+  OnComposeHook,
+  OnErrorHook,
+  OnRequestHook,
+  OnResponseHook,
+  OnRouteHook,
+  RegistrationEvent,
+} from './types.ts'
+
+/**
+ * Registry for the framework's lifecycle hooks. Implements the `Hooks`
+ * interface that plugins call into via `app.hooks`.
+ *
+ * # Execution model
+ *
+ * `runOn*` methods invoke listeners **sequentially** in registration order,
+ * awaiting each one before invoking the next. This is intentional:
+ *
+ *   - Predictable ordering: a hook registered first ALWAYS observes state
+ *     before a hook registered later. Plugins can rely on this.
+ *   - Backpressure: an async hook (e.g. fetching a session) blocks
+ *     subsequent hooks, ensuring downstream hooks see decorated state.
+ *   - Errors short-circuit `runOnRequest`/`runOnResponse`/`runOnCompose` —
+ *     they propagate to the caller (the request enters the error boundary).
+ *
+ * `runOnError` is the exception: it wraps each listener in a try/catch and
+ * swallows throws, because observers must not mask the original error.
+ *
+ * # Reading order
+ *
+ * Within a single `run*` call, listeners run in the order they were added.
+ * Across hook types within one request, the order is fixed by `app.handle`:
+ *
+ *   onRequest -> (decorators applied) -> dispatch -> onResponse
+ *                                                 \-> onError (on throw)
+ *
+ * # Hot-path note
+ *
+ * Each `runOn*` returns immediately if no listeners are registered. Callers
+ * should additionally check `hasAny()` (or the per-hook `has*()` helpers) to
+ * skip the `await` entirely on the zero-plugin path.
+ */
+export class HooksRegistry implements Hooks {
+  private readonly _onRoute: OnRouteHook[] = []
+  private readonly _onCompose: OnComposeHook[] = []
+  private readonly _onRequest: OnRequestHook[] = []
+  private readonly _onResponse: OnResponseHook[] = []
+  private readonly _onError: OnErrorHook[] = []
+
+  // ───── Registration (Hooks interface) ──────────────────────────────────
+
+  onRoute(fn: OnRouteHook): void { this._onRoute.push(fn) }
+  onCompose(fn: OnComposeHook): void { this._onCompose.push(fn) }
+  onRequest(fn: OnRequestHook): void { this._onRequest.push(fn) }
+  onResponse(fn: OnResponseHook): void { this._onResponse.push(fn) }
+  onError(fn: OnErrorHook): void { this._onError.push(fn) }
+
+  // ───── Hot-path checks ─────────────────────────────────────────────────
+
+  /** True when any request-time hook is registered. */
+  hasAny(): boolean {
+    return (
+      this._onRequest.length > 0 ||
+      this._onResponse.length > 0 ||
+      this._onError.length > 0
+    )
+  }
+
+  hasOnRequest(): boolean { return this._onRequest.length > 0 }
+  hasOnResponse(): boolean { return this._onResponse.length > 0 }
+  hasOnError(): boolean { return this._onError.length > 0 }
+  hasOnRoute(): boolean { return this._onRoute.length > 0 }
+  hasOnCompose(): boolean { return this._onCompose.length > 0 }
+
+  // ───── Run (sequential, registration order) ────────────────────────────
+
+  /** Synchronous — `onRoute` is invoked during composition for each route. */
+  runOnRoute(event: RegistrationEvent): void {
+    for (let i = 0; i < this._onRoute.length; i++) {
+      this._onRoute[i]!(event)
+    }
+  }
+
+  async runOnCompose(): Promise<void> {
+    for (let i = 0; i < this._onCompose.length; i++) {
+      await this._onCompose[i]!()
+    }
+  }
+
+  async runOnRequest(ctx: IngeniumContext): Promise<void> {
+    for (let i = 0; i < this._onRequest.length; i++) {
+      await this._onRequest[i]!(ctx)
+    }
+  }
+
+  async runOnResponse(ctx: IngeniumContext): Promise<void> {
+    for (let i = 0; i < this._onResponse.length; i++) {
+      await this._onResponse[i]!(ctx)
+    }
+  }
+
+  /** Observation only. Throws inside listeners are swallowed. */
+  async runOnError(err: unknown, ctx: IngeniumContext): Promise<void> {
+    for (let i = 0; i < this._onError.length; i++) {
+      try {
+        await this._onError[i]!(err, ctx)
+      } catch {
+        // Swallow — observers must not mask the original error.
+      }
+    }
+  }
+}