@mokup/runtime 1.0.2 → 1.0.4

package/dist/index.d.mts

@@ -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>;
 };