@typokit/core 0.1.4

package/src/middleware.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect } from "@rstest/core";
+import {
+  defineMiddleware,
+  executeMiddlewareChain,
+  createRequestContext,
+} from "./middleware.js";
+import type { TypoKitRequest } from "@typokit/types";
+import type { AppError } from "@typokit/errors";
+import {
+  NotFoundError,
+  ValidationError,
+  ForbiddenError,
+} from "@typokit/errors";
+
+function createTestRequest(
+  overrides?: Partial<TypoKitRequest>,
+): TypoKitRequest {
+  return {
+    method: "GET",
+    path: "/test",
+    headers: {},
+    body: undefined,
+    query: {},
+    params: {},
+    ...overrides,
+  };
+}
+
+describe("defineMiddleware", () => {
+  it("creates a middleware with the given handler", async () => {
+    const mw = defineMiddleware(async () => ({ foo: "bar" }));
+    expect(mw.handler).toBeDefined();
+    const result = await mw.handler({
+      headers: {},
+      body: undefined,
+      query: {},
+      params: {},
+      ctx: createRequestContext(),
+    });
+    expect(result).toEqual({ foo: "bar" });
+  });
+
+  it("receives request properties", async () => {
+    const mw = defineMiddleware(async ({ headers, params }) => {
+      return {
+        token: headers["authorization"] as string,
+        userId: params["id"],
+      };
+    });
+    const result = await mw.handler({
+      headers: { authorization: "Bearer abc" },
+      body: undefined,
+      query: {},
+      params: { id: "42" },
+      ctx: createRequestContext(),
+    });
+    expect(result).toEqual({ token: "Bearer abc", userId: "42" });
+  });
+});
+
+describe("executeMiddlewareChain", () => {
+  it("runs middleware in order and accumulates context", async () => {
+    const order: number[] = [];
+
+    const mw1 = defineMiddleware(async () => {
+      order.push(1);
+      return { step1: true };
+    });
+
+    const mw2 = defineMiddleware(async ({ ctx }) => {
+      order.push(2);
+      expect((ctx as unknown as Record<string, unknown>)["step1"]).toBe(true);
+      return { step2: true };
+    });
+
+    const req = createTestRequest();
+    const ctx = createRequestContext();
+
+    const result = await executeMiddlewareChain(req, ctx, [
+      { name: "mw1", middleware: mw1 },
+      { name: "mw2", middleware: mw2 },
+    ]);
+
+    expect(order).toEqual([1, 2]);
+    expect((result as unknown as Record<string, unknown>)["step1"]).toBe(true);
+    expect((result as unknown as Record<string, unknown>)["step2"]).toBe(true);
+  });
+
+  it("respects priority ordering (lower runs first)", async () => {
+    const order: string[] = [];
+
+    const mwA = defineMiddleware(async () => {
+      order.push("A");
+      return {};
+    });
+    const mwB = defineMiddleware(async () => {
+      order.push("B");
+      return {};
+    });
+    const mwC = defineMiddleware(async () => {
+      order.push("C");
+      return {};
+    });
+
+    const req = createTestRequest();
+    const ctx = createRequestContext();
+
+    await executeMiddlewareChain(req, ctx, [
+      { name: "A", middleware: mwA, priority: 30 },
+      { name: "B", middleware: mwB, priority: 10 },
+      { name: "C", middleware: mwC, priority: 20 },
+    ]);
+
+    expect(order).toEqual(["B", "C", "A"]);
+  });
+
+  it("default priority is 0", async () => {
+    const order: string[] = [];
+
+    const mwA = defineMiddleware(async () => {
+      order.push("A");
+      return {};
+    });
+    const mwB = defineMiddleware(async () => {
+      order.push("B");
+      return {};
+    });
+
+    const req = createTestRequest();
+    const ctx = createRequestContext();
+
+    await executeMiddlewareChain(req, ctx, [
+      { name: "A", middleware: mwA, priority: 10 },
+      { name: "B", middleware: mwB },
+    ]);
+
+    expect(order).toEqual(["B", "A"]);
+  });
+
+  it("short-circuits when middleware throws", async () => {
+    const order: number[] = [];
+
+    const mw1 = defineMiddleware(async () => {
+      order.push(1);
+      return {};
+    });
+    const mw2 = defineMiddleware(
+      async ({ ctx }): Promise<Record<string, unknown>> => {
+        order.push(2);
+        ctx.fail(403, "FORBIDDEN", "Not allowed");
+        return {};
+      },
+    );
+    const mw3 = defineMiddleware(async () => {
+      order.push(3);
+      return {};
+    });
+
+    const req = createTestRequest();
+    const ctx = createRequestContext();
+
+    let caught: unknown;
+    try {
+      await executeMiddlewareChain(req, ctx, [
+        { name: "mw1", middleware: mw1 },
+        { name: "mw2", middleware: mw2 },
+        { name: "mw3", middleware: mw3 },
+      ]);
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(ForbiddenError);
+    expect((caught as AppError).status).toBe(403);
+    expect((caught as AppError).code).toBe("FORBIDDEN");
+    expect(order).toEqual([1, 2]);
+  });
+
+  it("handles empty middleware chain", async () => {
+    const req = createTestRequest();
+    const ctx = createRequestContext();
+    const result = await executeMiddlewareChain(req, ctx, []);
+    expect(result).toBeDefined();
+    expect(result.requestId).toBe(ctx.requestId);
+  });
+});
+
+describe("createRequestContext", () => {
+  it("ctx.fail() throws NotFoundError for 404", () => {
+    const ctx = createRequestContext();
+    let caught: unknown;
+    try {
+      ctx.fail(404, "NOT_FOUND", "Resource not found");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(NotFoundError);
+    expect((caught as AppError).status).toBe(404);
+    expect((caught as AppError).code).toBe("NOT_FOUND");
+    expect((caught as AppError).message).toBe("Resource not found");
+  });
+
+  it("ctx.fail() throws ValidationError for 400 with details", () => {
+    const ctx = createRequestContext();
+    let caught: unknown;
+    try {
+      ctx.fail(400, "VALIDATION", "Invalid input", { field: "email" });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(ValidationError);
+    expect((caught as AppError).details).toEqual({ field: "email" });
+  });
+
+  it("ctx.log is defined with all log levels", () => {
+    const ctx = createRequestContext();
+    expect(ctx.log).toBeDefined();
+    expect(typeof ctx.log.trace).toBe("function");
+    expect(typeof ctx.log.debug).toBe("function");
+    expect(typeof ctx.log.info).toBe("function");
+    expect(typeof ctx.log.warn).toBe("function");
+    expect(typeof ctx.log.error).toBe("function");
+    expect(typeof ctx.log.fatal).toBe("function");
+  });
+
+  it("ctx.log methods are no-ops (placeholder)", () => {
+    const ctx = createRequestContext();
+    // Should not throw
+    ctx.log.trace("test");
+    ctx.log.debug("test", { key: "value" });
+    ctx.log.info("test");
+    ctx.log.warn("test");
+    ctx.log.error("test");
+    ctx.log.fatal("test");
+  });
+
+  it("has a requestId", () => {
+    const ctx = createRequestContext();
+    expect(typeof ctx.requestId).toBe("string");
+    expect(ctx.requestId.length).toBeGreaterThan(0);
+  });
+
+  it("has services object", () => {
+    const ctx = createRequestContext();
+    expect(ctx.services).toBeDefined();
+    expect(typeof ctx.services).toBe("object");
+  });
+
+  it("accepts overrides", () => {
+    const ctx = createRequestContext({ requestId: "test-123" });
+    expect(ctx.requestId).toBe("test-123");
+  });
+});

package/src/middleware.ts

@@ -0,0 +1,100 @@
+// @typokit/core — Middleware System
+
+import type { TypoKitRequest, RequestContext, Logger } from "@typokit/types";
+import { createAppError } from "@typokit/errors";
+
+/** Input received by a defineMiddleware handler */
+export interface MiddlewareInput {
+  headers: TypoKitRequest["headers"];
+  body: TypoKitRequest["body"];
+  query: TypoKitRequest["query"];
+  params: TypoKitRequest["params"];
+  ctx: RequestContext;
+}
+
+/** A typed middleware created by defineMiddleware */
+export interface Middleware<
+  TAdded extends Record<string, unknown> = Record<string, unknown>,
+> {
+  handler: (input: MiddlewareInput) => Promise<TAdded>;
+}
+
+/** An entry in the middleware chain with name and optional priority */
+export interface MiddlewareEntry {
+  name: string;
+  middleware: Middleware;
+  priority?: number;
+}
+
+/**
+ * Define a typed middleware that receives request properties and returns
+ * additional context properties. Supports context type narrowing.
+ */
+export function defineMiddleware<TAdded extends Record<string, unknown>>(
+  handler: (input: MiddlewareInput) => Promise<TAdded>,
+): Middleware<TAdded> {
+  return { handler };
+}
+
+/** Create a no-op placeholder logger (actual implementation in observability phase) */
+export function createPlaceholderLogger(): Logger {
+  const noop = () => {};
+  return {
+    trace: noop,
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    fatal: noop,
+  };
+}
+
+/** Create a RequestContext with ctx.fail() and ctx.log placeholder */
+export function createRequestContext(
+  overrides?: Partial<RequestContext>,
+): RequestContext {
+  return {
+    log: createPlaceholderLogger(),
+    fail(
+      status: number,
+      code: string,
+      message: string,
+      details?: Record<string, unknown>,
+    ): never {
+      throw createAppError(status, code, message, details);
+    },
+    services: {},
+    requestId:
+      Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2),
+    ...overrides,
+  };
+}
+
+/**
+ * Execute a middleware chain in priority order (lower priority runs first).
+ * Each middleware's returned properties are accumulated onto the context.
+ * Middleware can short-circuit by throwing an error.
+ */
+export async function executeMiddlewareChain(
+  req: TypoKitRequest,
+  ctx: RequestContext,
+  entries: MiddlewareEntry[],
+): Promise<RequestContext> {
+  const sorted = [...entries].sort(
+    (a, b) => (a.priority ?? 0) - (b.priority ?? 0),
+  );
+
+  let currentCtx = ctx;
+  for (const entry of sorted) {
+    const added = await entry.middleware.handler({
+      headers: req.headers,
+      body: req.body,
+      query: req.query,
+      params: req.params,
+      ctx: currentCtx,
+    });
+    currentCtx = { ...currentCtx, ...added } as RequestContext;
+  }
+
+  return currentCtx;
+}

package/src/plugin.ts

@@ -0,0 +1,108 @@
+// @typokit/core — Plugin Interface & Build Pipeline
+
+import type {
+  BuildContext,
+  BuildResult,
+  CompiledRouteTable,
+  GeneratedOutput,
+  RequestContext,
+  SchemaChange,
+  SchemaTypeMap,
+} from "@typokit/types";
+import type { AppError } from "@typokit/errors";
+
+// ─── Hook System ─────────────────────────────────────────────
+
+/** Tapable-style async series hook — plugins tap in, calls run in series */
+export interface AsyncSeriesHook<T extends unknown[]> {
+  tap(name: string, fn: (...args: T) => void | Promise<void>): void;
+  call(...args: T): Promise<void>;
+}
+
+// ─── Build Pipeline ──────────────────────────────────────────
+
+/** Tapable build pipeline — plugins hook into build phases via onBuild() */
+export interface BuildPipeline {
+  hooks: {
+    /** Runs before any transforms — plugins can register additional type sources */
+    beforeTransform: AsyncSeriesHook<[BuildContext]>;
+
+    /** Runs after types are parsed — plugins can inspect/modify the type map */
+    afterTypeParse: AsyncSeriesHook<[SchemaTypeMap, BuildContext]>;
+
+    /** Runs after validators are generated — plugins can add custom validators */
+    afterValidators: AsyncSeriesHook<[GeneratedOutput[], BuildContext]>;
+
+    /** Runs after the route table is compiled */
+    afterRouteTable: AsyncSeriesHook<[CompiledRouteTable, BuildContext]>;
+
+    /** Runs after all generation — plugins emit their own artifacts */
+    emit: AsyncSeriesHook<[GeneratedOutput[], BuildContext]>;
+
+    /** Runs after build completes — cleanup, reporting */
+    done: AsyncSeriesHook<[BuildResult]>;
+  };
+}
+
+// ─── CLI & Introspection Types ───────────────────────────────
+
+/** A CLI subcommand exposed by a plugin */
+export interface CliCommand {
+  name: string;
+  description: string;
+  options?: Array<{ name: string; description: string; required?: boolean }>;
+  run(args: Record<string, unknown>): Promise<void>;
+}
+
+/** An introspection endpoint exposed by a plugin for the debug sidecar */
+export interface InspectEndpoint {
+  path: string;
+  description: string;
+  handler(): Promise<unknown>;
+}
+
+// ─── App Instance ────────────────────────────────────────────
+
+/** Represents the running application instance passed to plugin lifecycle hooks */
+export interface AppInstance {
+  /** Application name */
+  name: string;
+  /** Registered plugins */
+  plugins: TypoKitPlugin[];
+  /** Service container for dependency injection */
+  services: Record<string, unknown>;
+}
+
+// ─── Plugin Interface ────────────────────────────────────────
+
+/** Plugin contract — hooks into both build-time and runtime lifecycle events */
+export interface TypoKitPlugin {
+  name: string;
+
+  /** Hook into the build pipeline — tap into specific build phases */
+  onBuild?(pipeline: BuildPipeline): void;
+
+  /** Hook into server startup — register middleware, services, resources */
+  onStart?(app: AppInstance): Promise<void>;
+
+  /** Fires after all routes are registered and the server is listening.
+   *  Use for service discovery, health check readiness, warmup. */
+  onReady?(app: AppInstance): Promise<void>;
+
+  /** Observe unhandled errors — reporting, transformation (e.g. Sentry).
+   *  Called after the framework's error middleware serializes the response. */
+  onError?(error: AppError, ctx: RequestContext): void;
+
+  /** Hook into server shutdown — cleanup connections, flush buffers */
+  onStop?(app: AppInstance): Promise<void>;
+
+  /** Dev mode only — fires when schema types change and the build regenerates.
+   *  Use to refresh cached state (e.g. debug sidecar route map). */
+  onSchemaChange?(changes: SchemaChange[]): void;
+
+  /** Expose CLI subcommands */
+  commands?(): CliCommand[];
+
+  /** Expose introspection endpoints for the debug sidecar */
+  inspect?(): InspectEndpoint[];
+}