@typokit/core 0.1.4

package/dist/middleware.js

@@ -0,0 +1,54 @@
+// @typokit/core — Middleware System
+import { createAppError } from "@typokit/errors";
+/**
+ * Define a typed middleware that receives request properties and returns
+ * additional context properties. Supports context type narrowing.
+ */
+export function defineMiddleware(handler) {
+    return { handler };
+}
+/** Create a no-op placeholder logger (actual implementation in observability phase) */
+export function createPlaceholderLogger() {
+    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) {
+    return {
+        log: createPlaceholderLogger(),
+        fail(status, code, message, details) {
+            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, ctx, entries) {
+    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 };
+    }
+    return currentCtx;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,oCAAoC;AAGpC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAyBjD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAoD;IAEpD,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,uBAAuB;IACrC,MAAM,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACtB,OAAO;QACL,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,IAAI;QACX,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,IAAI;KACZ,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,oBAAoB,CAClC,SAAmC;IAEnC,OAAO;QACL,GAAG,EAAE,uBAAuB,EAAE;QAC9B,IAAI,CACF,MAAc,EACd,IAAY,EACZ,OAAe,EACf,OAAiC;YAEjC,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACvD,CAAC;QACD,QAAQ,EAAE,EAAE;QACZ,SAAS,EACP,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3E,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAmB,EACnB,GAAmB,EACnB,OAA0B;IAE1B,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAC9B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAChD,CAAC;IAEF,IAAI,UAAU,GAAG,GAAG,CAAC;IACrB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;YAC3C,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,GAAG,EAAE,UAAU;SAChB,CAAC,CAAC;QACH,UAAU,GAAG,EAAE,GAAG,UAAU,EAAE,GAAG,KAAK,EAAoB,CAAC;IAC7D,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,74 @@
+import type { BuildContext, BuildResult, CompiledRouteTable, GeneratedOutput, RequestContext, SchemaChange, SchemaTypeMap } from "@typokit/types";
+import type { AppError } from "@typokit/errors";
+/** 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>;
+}
+/** 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]>;
+    };
+}
+/** 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>;
+}
+/** 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 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[];
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -0,0 +1,3 @@
+// @typokit/core — Plugin Interface & Build Pipeline
+export {};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,oDAAoD"}

package/package.json

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

package/src/adapters/database.ts

@@ -0,0 +1,37 @@
+import type {
+  GeneratedOutput,
+  MigrationDraft,
+  SchemaTypeMap,
+} from "@typokit/types";
+
+/**
+ * Represents the current state of a database schema,
+ * used by adapters to compute diffs against TypoKit types.
+ */
+export interface DatabaseState {
+  tables: Record<string, TableState>;
+}
+
+export interface TableState {
+  columns: Record<string, ColumnState>;
+}
+
+export interface ColumnState {
+  type: string;
+  nullable: boolean;
+}
+
+/**
+ * Every database adapter implements this interface.
+ * See typokit-arch.md Section 7.3.
+ */
+export interface DatabaseAdapter {
+  /** Generate DB schema artifacts from TypoKit types */
+  generate(types: SchemaTypeMap): GeneratedOutput[];
+
+  /** Diff current DB state against types, produce migration draft */
+  diff(types: SchemaTypeMap, currentState: DatabaseState): MigrationDraft;
+
+  /** Generate typed repository helpers (optional — adapters can skip this) */
+  generateRepositories?(types: SchemaTypeMap): GeneratedOutput[];
+}

package/src/adapters/server.ts

@@ -0,0 +1,55 @@
+import type {
+  CompiledRouteTable,
+  HandlerMap,
+  MiddlewareChain,
+  SerializerMap,
+  ServerHandle,
+  TypoKitRequest,
+  TypoKitResponse,
+  ValidatorMap,
+} from "@typokit/types";
+
+export interface ServerAdapter {
+  /** Adapter name for logging and diagnostics */
+  name: string;
+
+  /**
+   * Register TypoKit's compiled routes into the server framework.
+   * The adapter translates the route table into framework-native registrations.
+   * Each route handler receives a normalized TypoKitRequest and must return
+   * a TypoKitResponse.
+   */
+  registerRoutes(
+    routeTable: CompiledRouteTable,
+    handlerMap: HandlerMap,
+    middlewareChain: MiddlewareChain,
+    validatorMap?: ValidatorMap,
+    serializerMap?: SerializerMap,
+  ): void;
+
+  /**
+   * Start the server. Returns a handle for shutdown.
+   */
+  listen(port: number): Promise<ServerHandle>;
+
+  /**
+   * Normalize the framework's native request into TypoKit's standard format.
+   * This is where Fastify's `req`, Hono's `c`, or raw `http.IncomingMessage`
+   * get normalized into a consistent shape for TypoKit's validation/handler
+   * pipeline.
+   */
+  normalizeRequest(raw: unknown): TypoKitRequest;
+
+  /**
+   * Write TypoKit's response back through the framework's native response
+   * mechanism.
+   */
+  writeResponse(raw: unknown, response: TypoKitResponse): void;
+
+  /**
+   * Optional: expose the underlying framework instance for escape hatches.
+   * e.g., the raw Fastify instance so users can register Fastify-native plugins.
+   * Returns `unknown` — consumers cast to the specific framework type.
+   */
+  getNativeServer?(): unknown;
+}