@pikku/core 0.11.2 → 0.12.1

package/dist/wirings/cli/define-cli-commands.js

@@ -0,0 +1,20 @@
+/**
+ * Type-safe helper for defining CLI commands that can be composed.
+ * Returns the commands record as-is (identity function) for use with `wireCLI`.
+ *
+ * @example
+ * ```typescript
+ * export const chatCommands = defineCLICommands({
+ *   chat: pikkuCLICommand({ func: chatFunc }),
+ *   'chat:history': pikkuCLICommand({ func: historyFunc }),
+ * })
+ *
+ * wireCLI({
+ *   program: 'my-app',
+ *   commands: { ...chatCommands, other: pikkuCLICommand({ func: otherFunc }) }
+ * })
+ * ```
+ */
+export function defineCLICommands(commands) {
+    return commands;
+}

package/dist/wirings/cli/index.d.ts

@@ -1,5 +1,4 @@
-export * from './cli.types.js';
-export * from './cli-runner.js';
-export * from './command-parser.js';
 export { wireCLI, runCLICommand, pikkuCLIRender, executeCLI, CLIError, } from './cli-runner.js';
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js';
+export { defineCLICommands } from './define-cli-commands.js';
+export type { CLIMeta, CLICommandMeta, CLIProgramMeta, CoreCLI, CoreCLICommandConfig, CorePikkuCLIRender, } from './cli.types.js';

package/dist/wirings/cli/index.js

@@ -1,5 +1,3 @@
-export * from './cli.types.js';
-export * from './cli-runner.js';
-export * from './command-parser.js';
 export { wireCLI, runCLICommand, pikkuCLIRender, executeCLI, CLIError, } from './cli-runner.js';
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js';
+export { defineCLICommands } from './define-cli-commands.js';

package/dist/wirings/http/http-routes.d.ts

@@ -0,0 +1,69 @@
+import type { HTTPRouteMap, HTTPRouteContract, HTTPRoutesGroupConfig, WireHTTPRoutesConfig } from './http.types.js';
+/**
+ * Type-safe helper for defining route contracts that can be composed.
+ * Supports optional group-level config that cascades to all routes.
+ *
+ * @example
+ * ```typescript
+ * // Simple routes without group config
+ * export const todosRoutes = defineHTTPRoutes({
+ *   list: { method: 'get', route: '/todos', func: listTodos },
+ *   get: { method: 'get', route: '/todos/:id', func: getTodo },
+ * })
+ *
+ * // Routes with group-level config
+ * export const todosRoutes = defineHTTPRoutes({
+ *   auth: true,
+ *   tags: ['todos'],
+ *   routes: {
+ *     list: { method: 'get', route: '/todos', func: listTodos },
+ *     get: { method: 'get', route: '/todos/:id', func: getTodo },
+ *   }
+ * })
+ * ```
+ */
+export declare function defineHTTPRoutes<T extends HTTPRouteMap>(routes: T): HTTPRouteContract<T>;
+export declare function defineHTTPRoutes<T extends HTTPRouteMap>(config: HTTPRoutesGroupConfig & {
+    routes: T;
+}): HTTPRouteContract<T>;
+/**
+ * Wires multiple HTTP routes from a nested map or array configuration.
+ * Inspired by ts-rest's contract pattern, provides a single place to wire an entire API.
+ *
+ * @example
+ * ```typescript
+ * // Nested object format
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   tags: ['api'],
+ *   routes: {
+ *     todos: {
+ *       list: { method: 'get', route: '/todos', func: listTodos },
+ *       get: { method: 'get', route: '/todos/:id', func: getTodo },
+ *     },
+ *     auth: {
+ *       login: { method: 'post', route: '/auth/login', func: login, auth: false },
+ *     },
+ *   },
+ * })
+ *
+ * // Flat array format
+ * wireHTTPRoutes({
+ *   basePath: '/api',
+ *   routes: [
+ *     { method: 'get', route: '/todos', func: listTodos },
+ *     { method: 'post', route: '/todos', func: createTodo },
+ *   ],
+ * })
+ *
+ * // Composing route contracts
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   routes: {
+ *     todos: todosRoutes,  // from defineHTTPRoutes()
+ *     auth: authRoutes,    // from defineHTTPRoutes()
+ *   },
+ * })
+ * ```
+ */
+export declare const wireHTTPRoutes: (config: WireHTTPRoutesConfig) => void;

package/dist/wirings/http/http-routes.js

@@ -0,0 +1,139 @@
+import { wireHTTP } from './http-runner.js';
+export function defineHTTPRoutes(configOrRoutes) {
+    // If it has a 'routes' property and contains a map (not a route config), it's config + routes
+    if ('routes' in configOrRoutes &&
+        typeof configOrRoutes.routes === 'object' &&
+        !isRouteConfig(configOrRoutes.routes)) {
+        return configOrRoutes;
+    }
+    // Otherwise it's just routes
+    return { routes: configOrRoutes };
+}
+/**
+ * Wires multiple HTTP routes from a nested map or array configuration.
+ * Inspired by ts-rest's contract pattern, provides a single place to wire an entire API.
+ *
+ * @example
+ * ```typescript
+ * // Nested object format
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   tags: ['api'],
+ *   routes: {
+ *     todos: {
+ *       list: { method: 'get', route: '/todos', func: listTodos },
+ *       get: { method: 'get', route: '/todos/:id', func: getTodo },
+ *     },
+ *     auth: {
+ *       login: { method: 'post', route: '/auth/login', func: login, auth: false },
+ *     },
+ *   },
+ * })
+ *
+ * // Flat array format
+ * wireHTTPRoutes({
+ *   basePath: '/api',
+ *   routes: [
+ *     { method: 'get', route: '/todos', func: listTodos },
+ *     { method: 'post', route: '/todos', func: createTodo },
+ *   ],
+ * })
+ *
+ * // Composing route contracts
+ * wireHTTPRoutes({
+ *   basePath: '/api/v1',
+ *   routes: {
+ *     todos: todosRoutes,  // from defineHTTPRoutes()
+ *     auth: authRoutes,    // from defineHTTPRoutes()
+ *   },
+ * })
+ * ```
+ */
+export const wireHTTPRoutes = (config) => {
+    const { routes, ...groupConfig } = config;
+    if (Array.isArray(routes)) {
+        routes.forEach((route) => registerRoute(route, groupConfig));
+    }
+    else {
+        processRouteMap(routes, groupConfig);
+    }
+};
+/**
+ * Recursively processes a route map, handling nested maps and contracts
+ */
+function processRouteMap(map, parentConfig) {
+    for (const [_key, value] of Object.entries(map)) {
+        if (isRouteConfig(value)) {
+            registerRoute(value, parentConfig);
+        }
+        else if (isRouteContract(value)) {
+            // Merge parent config with contract config, then process routes
+            const mergedConfig = mergeGroupConfig(parentConfig, value);
+            processRouteMap(value.routes, mergedConfig);
+        }
+        else {
+            // Nested map without config
+            processRouteMap(value, parentConfig);
+        }
+    }
+}
+/**
+ * Merge group configs with proper cascading behavior:
+ * - basePath: Concatenates
+ * - tags: Merges (parent + child)
+ * - middleware: Merges (parent runs first)
+ * - auth: Inner overrides outer
+ * - permissions: Inner overrides outer
+ */
+function mergeGroupConfig(parent, child) {
+    return {
+        basePath: (parent.basePath || '') + (child.basePath || ''),
+        tags: [...(parent.tags || []), ...(child.tags || [])],
+        middleware: [...(parent.middleware || []), ...(child.middleware || [])],
+        auth: child.auth ?? parent.auth,
+        permissions: child.permissions ?? parent.permissions,
+    };
+}
+/**
+ * Registers a single route by calling wireHTTP with merged configuration
+ */
+function registerRoute(route, groupConfig) {
+    const fullRoute = (groupConfig.basePath || '') + route.route;
+    wireHTTP({
+        method: route.method,
+        route: fullRoute,
+        func: route.func,
+        auth: route.auth ?? groupConfig.auth,
+        tags: [...(groupConfig.tags || []), ...(route.tags || [])],
+        middleware: [
+            ...(groupConfig.middleware || []),
+            ...(route.middleware || []),
+        ],
+        permissions: route.permissions ?? groupConfig.permissions,
+        contentType: route.contentType,
+        timeout: route.timeout,
+        headers: route.headers,
+        docs: route.docs,
+        sse: route.sse,
+    });
+}
+/**
+ * Type guard to check if a value is an individual route config
+ */
+function isRouteConfig(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'method' in value &&
+        'func' in value &&
+        'route' in value);
+}
+/**
+ * Type guard to check if a value is a route contract (has routes property but is not a route config)
+ */
+function isRouteContract(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'routes' in value &&
+        !('method' in value) &&
+        !('func' in value));
+}

package/dist/wirings/http/http-runner.d.ts

@@ -1,6 +1,6 @@
-import { CoreHTTPFunctionWiring, RunHTTPWiringOptions, RunHTTPWiringParams, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse } from './http.types.js';
-import { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePermissionGroup } from '../../function/functions.types.js';
-import { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
+import type { CoreHTTPFunctionWiring, RunHTTPWiringOptions, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse } from './http.types.js';
+import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePermissionGroup } from '../../function/functions.types.js';
+import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 /**
  * Registers HTTP middleware for a specific route pattern.
@@ -101,10 +101,10 @@ export declare const createHTTPWire: (request: PikkuHTTPRequest | undefined, res
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request} request - The native Fetch API Request object.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Additional options including services and session management.
+ * @param {RunHTTPWiringOptions} params - Additional options including services and session management.
  * @returns {Promise<Response>} A promise that resolves to a Fetch API Response object.
  */
-export declare const fetch: <In, Out>(request: Request, params: RunHTTPWiringOptions & RunHTTPWiringParams) => Promise<Response>;
+export declare const fetch: <In, Out>(request: Request, params?: RunHTTPWiringOptions) => Promise<Response>;
 /**
  * Executes an HTTP route using a Pikku-specific request wrapper.
  *
@@ -114,10 +114,10 @@ export declare const fetch: <In, Out>(request: Request, params: RunHTTPWiringOpt
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The request object.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Execution options including services and session configuration.
+ * @param {RunHTTPWiringOptions} params - Execution options including services and session configuration.
  * @returns {Promise<PikkuFetchHTTPResponse>} A promise that resolves to a PikkuFetchHTTPResponse object.
  */
-export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest, params: RunHTTPWiringOptions & RunHTTPWiringParams) => Promise<PikkuFetchHTTPResponse>;
+export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest, params?: RunHTTPWiringOptions) => Promise<PikkuFetchHTTPResponse>;
 /**
  * Core function to process an HTTP request through route matching, validation,
  * middleware execution, error handling, and session service cleanup.
@@ -133,7 +133,7 @@ export declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest,
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The incoming HTTP request.
  * @param {PikkuHTTPResponse} response - The response object to be populated.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} options - Options such as singleton services, session handling, and error configuration.
+ * @param {RunHTTPWiringOptions} options - Options such as singleton services, session handling, and error configuration.
  * @returns {Promise<Out | void>} The output from the route handler or void if an error occurred.
  */
-export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { singletonServices, createWireServices, skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, generateRequestId, }: RunHTTPWiringOptions & RunHTTPWiringParams) => Promise<Out | void>;
+export declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, generateRequestId, }?: RunHTTPWiringOptions) => Promise<Out | void>;

package/dist/wirings/http/http-runner.js

@@ -1,5 +1,6 @@
-import { NotFoundError } from '../../errors/errors.js';
+import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js';
 import { closeWireServices, createWeakUID, isSerializable, } from '../../utils.js';
+import { getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { PikkuSessionService } from '../../services/user-session-service.js';
 import { handleHTTPError } from '../../handle-error.js';
 import { pikkuState } from '../../pikku-state.js';
@@ -7,7 +8,21 @@ import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { httpRouter } from './routers/http-router.js';
-import { startWorkflowByHttpWire } from '../workflow/workflow-utils.js';
+import { validateSchema } from '../../schema.js';
+import { runMiddleware } from '../../middleware-runner.js';
+/**
+ * Extract headers from a PikkuHTTPRequest based on the schema keys
+ */
+function extractHeadersFromRequest(request, headerKeys) {
+    const headers = {};
+    for (const headerName of headerKeys) {
+        const value = request.header(headerName);
+        if (value !== null) {
+            headers[headerName] = value;
+        }
+    }
+    return headers;
+}
 /**
  * Registers HTTP middleware for a specific route pattern.
  *
@@ -95,10 +110,10 @@ export const wireHTTP = (httpWiring) => {
     const httpMeta = pikkuState(null, 'http', 'meta');
     const routeMeta = httpMeta[httpWiring.method][httpWiring.route];
     if (!routeMeta) {
-        throw new Error('Route metadata not found');
+        throw new PikkuMissingMetaError(`Missing generated metadata for HTTP route '${httpWiring.method.toUpperCase()} ${httpWiring.route}'`);
     }
     if (httpWiring.func) {
-        addFunction(routeMeta.pikkuFuncName, httpWiring.func);
+        addFunction(routeMeta.pikkuFuncId, httpWiring.func);
     }
     const routes = pikkuState(null, 'http', 'routes');
     if (!routes.has(httpWiring.method)) {
@@ -184,6 +199,12 @@ const executeRoute = async (services, matchedRoute, http, options) => {
     const { singletonServices, createWireServices, skipUserSession, requestId } = services;
     // Attach URL parameters to the request object
     http?.request?.setParams(params);
+    // Validate request headers if schema is defined
+    if (meta.headersSchemaName && http.request && singletonServices.schema) {
+        const headerKeys = singletonServices.schema.getSchemaKeys(meta.headersSchemaName);
+        const rawHeaders = extractHeadersFromRequest(http.request, headerKeys);
+        await validateSchema(singletonServices.logger, singletonServices.schema, meta.headersSchemaName, rawHeaders);
+    }
     const requiresSession = route.auth !== false;
     let wireServices;
     let result;
@@ -192,7 +213,13 @@ const executeRoute = async (services, matchedRoute, http, options) => {
     if (skipUserSession && requiresSession) {
         throw new Error("Can't skip trying to get user session if auth is required");
     }
-    const data = () => http.request.data();
+    let cachedData;
+    const data = async () => {
+        if (cachedData === undefined) {
+            cachedData = await http.request.data();
+        }
+        return cachedData;
+    };
     let channel;
     if (matchedRoute.route.sse) {
         const response = http?.response;
@@ -220,14 +247,15 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             state: 'open',
         };
     }
-    const wire = { http, channel, session: userSession };
-    if (matchedRoute.meta.workflow === true) {
-        await startWorkflowByHttpWire(singletonServices, createWireServices, matchedRoute, wire);
-        return wireServices
-            ? { wireServices, result: http.response }
-            : { result: http.response };
-    }
-    result = await runPikkuFunc('http', `${meta.method}:${meta.route}`, meta.pikkuFuncName, {
+    const wire = {
+        http,
+        channel,
+        session: userSession.get(),
+        setSession: (s) => userSession.setInitial(s),
+        getSession: () => userSession.get(),
+        hasSessionChanged: () => userSession.sessionChanged,
+    };
+    result = await runPikkuFunc('http', `${meta.method}:${meta.route}`, meta.pikkuFuncId, {
         singletonServices,
         createWireServices,
         auth: route.auth !== false,
@@ -239,17 +267,20 @@ const executeRoute = async (services, matchedRoute, http, options) => {
         coerceDataFromSchema: options.coerceDataFromSchema,
         tags: route.tags,
         wire,
+        sessionService: userSession,
     });
-    // Respond with either a binary or JSON response based on configuration
-    if (route.returnsJSON === false) {
-        http?.response?.arrayBuffer(result);
-    }
-    else {
-        http?.response?.json(result);
+    if (!matchedRoute.route.sse) {
+        if (result === undefined || result === null) {
+            http?.response?.status(204);
+        }
+        else if (route.returnsJSON === false) {
+            http?.response?.arrayBuffer(result);
+        }
+        else {
+            http?.response?.status(200);
+            http?.response?.json(result);
+        }
     }
-    http?.response?.status(200);
-    // TODO: Evaluate if the response stream should be explicitly ended.
-    // http?.response?.end()
     return wireServices ? { result, wireServices } : { result };
 };
 /**
@@ -264,10 +295,10 @@ const executeRoute = async (services, matchedRoute, http, options) => {
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request} request - The native Fetch API Request object.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Additional options including services and session management.
+ * @param {RunHTTPWiringOptions} params - Additional options including services and session management.
  * @returns {Promise<Response>} A promise that resolves to a Fetch API Response object.
  */
-export const fetch = async (request, params) => {
+export const fetch = async (request, params = {}) => {
     const pikkuResponse = new PikkuFetchHTTPResponse();
     await fetchData(request, pikkuResponse, params);
     return pikkuResponse.toResponse();
@@ -281,10 +312,10 @@ export const fetch = async (request, params) => {
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The request object.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Execution options including services and session configuration.
+ * @param {RunHTTPWiringOptions} params - Execution options including services and session configuration.
  * @returns {Promise<PikkuFetchHTTPResponse>} A promise that resolves to a PikkuFetchHTTPResponse object.
  */
-export const pikkuFetch = async (request, params) => {
+export const pikkuFetch = async (request, params = {}) => {
     const pikkuResponse = new PikkuFetchHTTPResponse();
     await fetchData(request, pikkuResponse, params);
     return pikkuResponse;
@@ -304,24 +335,39 @@ export const pikkuFetch = async (request, params) => {
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The incoming HTTP request.
  * @param {PikkuHTTPResponse} response - The response object to be populated.
- * @param {RunHTTPWiringOptions & RunHTTPWiringParams} options - Options such as singleton services, session handling, and error configuration.
+ * @param {RunHTTPWiringOptions} options - Options such as singleton services, session handling, and error configuration.
  * @returns {Promise<Out | void>} The output from the route handler or void if an error occurred.
  */
-export const fetchData = async (request, response, { singletonServices, createWireServices, skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, generateRequestId, }) => {
-    const requestId = request.getHeader?.('x-request-id') ||
-        generateRequestId?.() ||
-        createWeakUID();
+export const fetchData = async (request, response, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, generateRequestId, } = {}) => {
+    const singletonServices = getSingletonServices();
+    const createWireServices = getCreateWireServices();
     let wireServices;
     let result;
     // Combine the request and response into one wire object
-    const http = createHTTPWire(request instanceof Request ? new PikkuFetchHTTPRequest(request) : request, response);
+    const pikkuRequest = request instanceof Request ? new PikkuFetchHTTPRequest(request) : request;
+    let requestId = null;
+    try {
+        requestId = pikkuRequest.header('x-request-id');
+    }
+    catch { }
+    requestId = requestId || generateRequestId?.() || createWeakUID();
+    const http = createHTTPWire(pikkuRequest, response);
     const apiType = http.request.method();
     const apiRoute = http.request.path();
     // Locate the matching route based on the HTTP method and path
     const matchedRoute = getMatchingRoute(apiType, apiRoute);
     try {
-        // If no route matches, log the occurrence and throw a NotFoundError
         if (!matchedRoute) {
+            if (apiType.toLowerCase() === 'options') {
+                const httpGroups = pikkuState(null, 'middleware', 'httpGroup');
+                const globalMiddleware = httpGroups['*'];
+                const wire = { http: http };
+                if (globalMiddleware) {
+                    await runMiddleware(singletonServices, wire, globalMiddleware);
+                }
+                response.status(204).json(undefined);
+                return;
+            }
             singletonServices.logger.info({
                 message: 'Route not found',
                 apiRoute,
@@ -340,7 +386,6 @@ export const fetchData = async (request, response, { singletonServices, createWi
         return result;
     }
     catch (e) {
-        // Handle errors and, depending on configuration, bubble them up or respond with an error
         handleHTTPError(e, http, requestId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
     }
     finally {