@mokup/runtime 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 import { Context, Hono } from '@mokup/shared/hono';
 export { Context, MiddlewareHandler, handle } from '@mokup/shared/hono';
 
+/**
+ * Tokenized route segment for matching.
+ *
+ * @example
+ * import type { RouteToken } from '@mokup/runtime'
+ *
+ * const token: RouteToken = { type: 'param', name: 'id' }
+ */
 type RouteToken = {
     type: 'static';
     value: string;
@@ -14,6 +22,20 @@ type RouteToken = {
     type: 'optional-catchall';
     name: string;
 };
+/**
+ * Parsed route template with tokens and score.
+ *
+ * @example
+ * import type { ParsedRouteTemplate } from '@mokup/runtime'
+ *
+ * const parsed: ParsedRouteTemplate = {
+ *   template: '/users/[id]',
+ *   tokens: [{ type: 'param', name: 'id' }],
+ *   score: [3],
+ *   errors: [],
+ *   warnings: [],
+ * }
+ */
 interface ParsedRouteTemplate {
     template: string;
     tokens: RouteToken[];
@@ -21,36 +43,196 @@ interface ParsedRouteTemplate {
     errors: string[];
     warnings: string[];
 }
+/**
+ * Compute a score array for route tokens.
+ *
+ * @param tokens - Parsed route tokens.
+ * @returns A numeric score array used for sorting.
+ *
+ * @example
+ * import { scoreRouteTokens } from '@mokup/runtime'
+ *
+ * const score = scoreRouteTokens([{ type: 'static', value: 'users' }])
+ */
 declare function scoreRouteTokens(tokens: RouteToken[]): (4 | 3 | 2 | 1 | 0)[];
+/**
+ * Compare two route scores (higher wins).
+ *
+ * @param a - Score array for route A.
+ * @param b - Score array for route B.
+ * @returns Negative when A is higher priority.
+ *
+ * @example
+ * import { compareRouteScore } from '@mokup/runtime'
+ *
+ * const order = compareRouteScore([4], [3])
+ */
 declare function compareRouteScore(a: number[], b: number[]): number;
+/**
+ * Normalize a URL path by stripping query/hash and trailing slash.
+ *
+ * @param value - Raw path or URL.
+ * @returns Normalized pathname.
+ *
+ * @example
+ * import { normalizePathname } from '@mokup/runtime'
+ *
+ * const pathname = normalizePathname('/users/?q=1')
+ */
 declare function normalizePathname(value: string): string;
+/**
+ * Parse a route template into tokens, score, and diagnostics.
+ *
+ * @param template - Route template string.
+ * @returns Parsed template details.
+ *
+ * @example
+ * import { parseRouteTemplate } from '@mokup/runtime'
+ *
+ * const parsed = parseRouteTemplate('/users/[id]')
+ */
 declare function parseRouteTemplate(template: string): ParsedRouteTemplate;
+/**
+ * Match route tokens against a pathname and extract params.
+ *
+ * @param tokens - Tokens for the template.
+ * @param pathname - Request pathname.
+ * @returns Params object or null if no match.
+ *
+ * @example
+ * import { matchRouteTokens } from '@mokup/runtime'
+ *
+ * const match = matchRouteTokens(
+ *   [{ type: 'param', name: 'id' }],
+ *   '/123',
+ * )
+ */
 declare function matchRouteTokens(tokens: RouteToken[], pathname: string): {
     params: Record<string, string | string[]>;
 } | null;
 
+/**
+ * Supported HTTP methods for mock routes.
+ *
+ * @example
+ * import type { HttpMethod } from '@mokup/runtime'
+ *
+ * const method: HttpMethod = 'GET'
+ */
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+/**
+ * Serialized manifest describing all mock routes.
+ *
+ * @example
+ * import type { Manifest } from '@mokup/runtime'
+ *
+ * const manifest: Manifest = {
+ *   version: 1,
+ *   routes: [],
+ * }
+ */
 interface Manifest {
+    /**
+     * Manifest schema version.
+     *
+     * @default 1
+     */
     version: 1;
+    /**
+     * Route entries in this manifest.
+     *
+     * @default []
+     */
     routes: ManifestRoute[];
 }
+/**
+ * One route entry inside the manifest.
+ *
+ * @example
+ * import type { ManifestRoute } from '@mokup/runtime'
+ *
+ * const route: ManifestRoute = {
+ *   method: 'GET',
+ *   url: '/api/ping',
+ *   response: { type: 'json', body: { ok: true } },
+ * }
+ */
 interface ManifestRoute {
+    /** HTTP method of the route. */
     method: HttpMethod;
+    /** URL template for the route. */
     url: string;
+    /** Pre-parsed route tokens (optional optimization). */
     tokens?: RouteToken[];
+    /** Route score used for sorting and matching. */
     score?: number[];
+    /** Source file path for the route handler. */
     source?: string;
+    /**
+     * Override response status code.
+     *
+     * @default 200
+     */
     status?: number;
+    /**
+     * Additional headers to apply to the response.
+     *
+     * @default {}
+     */
     headers?: Record<string, string>;
+    /**
+     * Delay in milliseconds before responding.
+     *
+     * @default 0
+     */
     delay?: number;
+    /**
+     * Middleware module references to apply before the handler.
+     *
+     * @default []
+     */
     middleware?: ManifestModuleRef[];
+    /** Response definition for this route. */
     response: ManifestResponse;
 }
+/**
+ * Reference to a module export produced by mokup build.
+ *
+ * @example
+ * import type { ManifestModuleRef } from '@mokup/runtime'
+ *
+ * const ref: ManifestModuleRef = {
+ *   module: './mokup-handlers/mock/ping.get.mjs',
+ *   exportName: 'default',
+ * }
+ */
 interface ManifestModuleRef {
+    /** Module path (absolute or relative to moduleBase). */
     module: string;
+    /**
+     * Named export to load from the module.
+     *
+     * @default "default"
+     */
     exportName?: string;
+    /**
+     * Optional rule index when multiple rules exist in one module.
+     *
+     * @default 0
+     */
     ruleIndex?: number;
 }
+/**
+ * Response descriptor stored in the manifest.
+ *
+ * @example
+ * import type { ManifestResponse } from '@mokup/runtime'
+ *
+ * const response: ManifestResponse = {
+ *   type: 'text',
+ *   body: 'ok',
+ * }
+ */
 type ManifestResponse = {
     type: 'json';
     body: unknown;
@@ -64,33 +246,170 @@ type ManifestResponse = {
 } | ({
     type: 'module';
 } & ManifestModuleRef);
+/**
+ * Normalized request input for runtime execution.
+ *
+ * @example
+ * import type { RuntimeRequest } from '@mokup/runtime'
+ *
+ * const request: RuntimeRequest = {
+ *   method: 'GET',
+ *   path: '/api/ping',
+ *   query: {},
+ *   headers: {},
+ *   body: null,
+ * }
+ */
 interface RuntimeRequest {
+    /** HTTP method. */
     method: string;
+    /** Request path (no origin). */
     path: string;
+    /** Parsed query parameters. */
     query: Record<string, string | string[]>;
+    /** Normalized request headers. */
     headers: Record<string, string>;
+    /** Parsed request body. */
     body: unknown;
+    /** Raw body text (if available). */
     rawBody?: string;
+    /** Path params captured during matching. */
     params?: Record<string, string | string[]>;
 }
+/**
+ * Normalized runtime response output.
+ *
+ * @example
+ * import type { RuntimeResult } from '@mokup/runtime'
+ *
+ * const result: RuntimeResult = {
+ *   status: 200,
+ *   headers: { 'content-type': 'application/json' },
+ *   body: '{"ok":true}',
+ * }
+ */
 interface RuntimeResult {
+    /**
+     * HTTP status code.
+     *
+     * @default 200
+     */
     status: number;
+    /**
+     * Response headers.
+     *
+     * @default {}
+     */
     headers: Record<string, string>;
+    /** Response body as text or binary. */
     body: string | Uint8Array | null;
 }
+/**
+ * Static response values supported by route handlers.
+ *
+ * @example
+ * import type { RouteStaticResponse } from '@mokup/runtime'
+ *
+ * const value: RouteStaticResponse = { ok: true }
+ */
 type RouteStaticResponse = string | number | boolean | bigint | symbol | null | undefined | object;
+/**
+ * Allowed return values from a route handler.
+ *
+ * @example
+ * import type { RouteHandlerResult } from '@mokup/runtime'
+ *
+ * const result: RouteHandlerResult = 'ok'
+ */
 type RouteHandlerResult = RouteStaticResponse | Response;
+/**
+ * Function signature for request handlers.
+ *
+ * @example
+ * import type { RequestHandler } from '@mokup/runtime'
+ *
+ * const handler: RequestHandler = (c) => {
+ *   return { ok: true }
+ * }
+ */
 type RequestHandler = (context: Context) => RouteHandlerResult | Promise<RouteHandlerResult>;
+/**
+ * Route response as a static value or handler function.
+ *
+ * @example
+ * import type { RouteResponse } from '@mokup/runtime'
+ *
+ * const response: RouteResponse = (c) => c.text('ok')
+ */
 type RouteResponse = RouteStaticResponse | RequestHandler;
 
+/**
+ * Runtime configuration options.
+ *
+ * @example
+ * import type { RuntimeOptions } from '@mokup/runtime'
+ *
+ * const options: RuntimeOptions = {
+ *   manifest: { version: 1, routes: [] },
+ * }
+ */
 interface RuntimeOptions {
+    /**
+     * Manifest object or async loader.
+     */
     manifest: Manifest | (() => Promise<Manifest>);
+    /**
+     * Base directory for resolving module paths.
+     *
+     * @default undefined
+     */
     moduleBase?: string | URL;
+    /**
+     * Map of module exports for in-memory execution.
+     *
+     * @default undefined
+     */
     moduleMap?: ModuleMap;
 }
+/**
+ * Map of module path to exported members.
+ *
+ * @example
+ * import type { ModuleMap } from '@mokup/runtime'
+ *
+ * const moduleMap: ModuleMap = {
+ *   './handlers/ping.mjs': { default: () => ({ ok: true }) },
+ * }
+ */
 type ModuleMap = Record<string, Record<string, unknown>>;
 
+/**
+ * Build a Hono app from a manifest, loading module handlers as needed.
+ *
+ * @param options - Runtime options including the manifest.
+ * @returns A Hono app with routes registered.
+ *
+ * @example
+ * import { createRuntimeApp } from '@mokup/runtime'
+ *
+ * const app = await createRuntimeApp({
+ *   manifest: { version: 1, routes: [] },
+ * })
+ */
 declare function createRuntimeApp(options: RuntimeOptions): Promise<Hono>;
+/**
+ * Create a cached runtime handler for fetching and request simulation.
+ *
+ * @param options - Runtime options including the manifest.
+ * @returns Runtime helper with fetch and match helpers.
+ *
+ * @example
+ * import { createRuntime } from '@mokup/runtime'
+ *
+ * const runtime = createRuntime({
+ *   manifest: { version: 1, routes: [] },
+ * })
+ */
 declare function createRuntime(options: RuntimeOptions): {
     handle: (req: RuntimeRequest) => Promise<RuntimeResult | null>;
 };

package/dist/index.mjs

@@ -190,6 +190,29 @@ function matchRouteTokens(tokens, pathname) {
   return { params };
 }
 
+const methodSet = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+  "HEAD"
+]);
+function normalizeMethod(method) {
+  if (!method) {
+    return void 0;
+  }
+  const normalized = method.toUpperCase();
+  if (methodSet.has(normalized)) {
+    return normalized;
+  }
+  return void 0;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 function resolveModuleUrl(modulePath, moduleBase) {
   if (/^(?:data|http|https|file):/.test(modulePath)) {
     return modulePath;
@@ -325,29 +348,6 @@ async function loadModuleMiddleware(middleware, middlewareCache, moduleBase, mod
   return handlers[0];
 }
 
-const methodSet = /* @__PURE__ */ new Set([
-  "GET",
-  "POST",
-  "PUT",
-  "PATCH",
-  "DELETE",
-  "OPTIONS",
-  "HEAD"
-]);
-function normalizeMethod(method) {
-  if (!method) {
-    return void 0;
-  }
-  const normalized = method.toUpperCase();
-  if (methodSet.has(normalized)) {
-    return normalized;
-  }
-  return void 0;
-}
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 function decodeBase64(value) {
   if (typeof atob === "function") {
     const binary = atob(value);
@@ -360,50 +360,6 @@ function decodeBase64(value) {
   throw new Error("Base64 decoding is not supported in this runtime.");
 }
 
-function toHonoPath(tokens) {
-  if (!tokens || tokens.length === 0) {
-    return "/";
-  }
-  const segments = tokens.map((token) => {
-    if (token.type === "static") {
-      return token.value;
-    }
-    if (token.type === "param") {
-      return `:${token.name}`;
-    }
-    if (token.type === "catchall") {
-      return `:${token.name}{.+}`;
-    }
-    return `:${token.name}{.+}?`;
-  });
-  return `/${segments.join("/")}`;
-}
-function compileRoutes(manifest) {
-  const compiled = [];
-  for (const route of manifest.routes) {
-    const method = normalizeMethod(route.method) ?? "GET";
-    const parsed = route.tokens ? {
-      tokens: route.tokens,
-      score: route.score ?? scoreRouteTokens(route.tokens),
-      errors: []
-    } : parseRouteTemplate(route.url);
-    if (parsed.errors.length > 0) {
-      continue;
-    }
-    compiled.push({
-      route,
-      method,
-      tokens: route.tokens ?? parsed.tokens,
-      score: route.score ?? parsed.score
-    });
-  }
-  return compiled.sort((a, b) => {
-    if (a.method !== b.method) {
-      return a.method.localeCompare(b.method);
-    }
-    return compareRouteScore(a.score, b.score);
-  });
-}
 function shouldTreatAsText(contentType) {
   const normalized = contentType.toLowerCase();
   if (!normalized) {
@@ -485,6 +441,52 @@ function resolveResponse(value, fallback) {
   }
   return fallback;
 }
+
+function toHonoPath(tokens) {
+  if (!tokens || tokens.length === 0) {
+    return "/";
+  }
+  const segments = tokens.map((token) => {
+    if (token.type === "static") {
+      return token.value;
+    }
+    if (token.type === "param") {
+      return `:${token.name}`;
+    }
+    if (token.type === "catchall") {
+      return `:${token.name}{.+}`;
+    }
+    return `:${token.name}{.+}?`;
+  });
+  return `/${segments.join("/")}`;
+}
+function compileRoutes(manifest) {
+  const compiled = [];
+  for (const route of manifest.routes) {
+    const method = normalizeMethod(route.method) ?? "GET";
+    const parsed = route.tokens ? {
+      tokens: route.tokens,
+      score: route.score ?? scoreRouteTokens(route.tokens),
+      errors: []
+    } : parseRouteTemplate(route.url);
+    if (parsed.errors.length > 0) {
+      continue;
+    }
+    compiled.push({
+      route,
+      method,
+      tokens: route.tokens ?? parsed.tokens,
+      score: route.score ?? parsed.score
+    });
+  }
+  return compiled.sort((a, b) => {
+    if (a.method !== b.method) {
+      return a.method.localeCompare(b.method);
+    }
+    return compareRouteScore(a.score, b.score);
+  });
+}
+
 function normalizeHandlerValue(c, value) {
   if (value instanceof Response) {
     return value;
@@ -551,7 +553,7 @@ function createFinalizeMiddleware(route) {
   };
 }
 async function buildApp(params) {
-  const { manifest, moduleCache, middlewareCache, moduleBase, moduleMap } = params;
+  const manifest = typeof params.manifest === "function" ? await params.manifest() : params.manifest;
   const app = new Hono({ router: new PatternRouter(), strict: false });
   const compiled = compileRoutes(manifest);
   for (const entry of compiled) {
@@ -559,9 +561,9 @@ async function buildApp(params) {
     for (const middleware of entry.route.middleware ?? []) {
       const handler2 = await loadModuleMiddleware(
         middleware,
-        middlewareCache,
-        moduleBase,
-        moduleMap
+        params.middlewareCache,
+        params.moduleBase,
+        params.moduleMap
       );
       if (handler2) {
         middlewares.push(handler2);
@@ -569,9 +571,9 @@ async function buildApp(params) {
     }
     const handler = createRouteHandler({
       route: entry.route,
-      moduleCache,
-      ...typeof moduleBase !== "undefined" ? { moduleBase } : {},
-      ...typeof moduleMap !== "undefined" ? { moduleMap } : {}
+      moduleCache: params.moduleCache,
+      ...typeof params.moduleBase !== "undefined" ? { moduleBase: params.moduleBase } : {},
+      ...typeof params.moduleMap !== "undefined" ? { moduleMap: params.moduleMap } : {}
     });
     app.on(
       entry.method,
@@ -583,18 +585,7 @@ async function buildApp(params) {
   }
   return app;
 }
-async function createRuntimeApp(options) {
-  const manifest = typeof options.manifest === "function" ? await options.manifest() : options.manifest;
-  const moduleCache = /* @__PURE__ */ new Map();
-  const middlewareCache = /* @__PURE__ */ new Map();
-  return await buildApp({
-    manifest,
-    moduleCache,
-    middlewareCache,
-    ...typeof options.moduleBase !== "undefined" ? { moduleBase: options.moduleBase } : {},
-    ...typeof options.moduleMap !== "undefined" ? { moduleMap: options.moduleMap } : {}
-  });
-}
+
 function appendQueryParams(url, query) {
   for (const [key, value] of Object.entries(query)) {
     if (Array.isArray(value)) {
@@ -670,6 +661,18 @@ function routeNeedsModuleBase(route, moduleMap) {
   }
   return false;
 }
+
+async function createRuntimeApp(options) {
+  const moduleCache = /* @__PURE__ */ new Map();
+  const middlewareCache = /* @__PURE__ */ new Map();
+  return await buildApp({
+    manifest: options.manifest,
+    moduleCache,
+    middlewareCache,
+    ...typeof options.moduleBase !== "undefined" ? { moduleBase: options.moduleBase } : {},
+    ...typeof options.moduleMap !== "undefined" ? { moduleMap: options.moduleMap } : {}
+  });
+}
 function createRuntime(options) {
   let manifestCache = null;
   let appPromise = null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mokup/runtime",
   "type": "module",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Cross-runtime mock matching and response handling for mokup.",
   "license": "MIT",
   "homepage": "https://mokup.icebreaker.top",
@@ -27,7 +27,7 @@
     "dist"
   ],
   "dependencies": {
-    "@mokup/shared": "1.0.1"
+    "@mokup/shared": "1.0.2"
   },
   "devDependencies": {
     "typescript": "^5.9.3",