@pikku/core 0.9.11 → 0.10.0

package/dist/middleware/auth-cookie.d.ts

@@ -1,20 +1,38 @@
 import { SerializeOptions } from 'cookie';
-import { CoreConfig, CoreSingletonServices, CoreUserSession, CorePikkuMiddleware } from '../types/core.types.js';
 import { RelativeTimeInput } from '../time-utils.js';
 /**
- * Cookie middleware that extracts a session from cookies.
+ * Cookie-based session middleware that uses JWT for encoding/decoding session data.
  *
- * @param options.name - List of cookie names to check.
- * @param options.getSessionForCookieValue - Function to retrieve a session using a cookie value.
+ * Reads session from a cookie on incoming requests and automatically updates the cookie
+ * when the session changes (e.g., after login).
+ *
+ * @param options.name - Cookie name
+ * @param options.expiresIn - Cookie expiration time (e.g., { value: 30, unit: 'day' })
+ * @param options.options - Cookie serialization options (httpOnly, secure, sameSite, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { authCookie } from '@pikku/core/middleware'
+ *
+ * addHTTPMiddleware([
+ *   authCookie({
+ *     name: 'session',
+ *     expiresIn: { value: 30, unit: 'day' },
+ *     options: {
+ *       httpOnly: true,
+ *       secure: true,
+ *       sameSite: 'strict',
+ *       path: '/'
+ *     }
+ *   })
+ * ])
+ * ```
  */
-export declare const authCookie: <SingletonServices extends CoreSingletonServices<CoreConfig>, UserSession extends CoreUserSession>({ name, getSessionForCookieValue, jwt, options, expiresIn, }: {
+export declare const authCookie: import("../types/core.types.js").CorePikkuMiddlewareFactory<{
     name: string;
     options: SerializeOptions;
     expiresIn: RelativeTimeInput;
-} & ({
-    getSessionForCookieValue: (services: SingletonServices, cookieValue: string, cookieName: string) => Promise<UserSession>;
-    jwt?: false;
-} | {
-    getSessionForCookieValue?: undefined;
-    jwt: true;
-})) => CorePikkuMiddleware;
+}, import("../types/core.types.js").CoreSingletonServices<{
+    logLevel?: import("../index.js").LogLevel;
+    secrets?: {};
+}>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/auth-cookie.js

@@ -1,52 +1,60 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js';
 import { getRelativeTimeOffsetFromNow, } from '../time-utils.js';
 /**
- * Cookie middleware that extracts a session from cookies.
+ * Cookie-based session middleware that uses JWT for encoding/decoding session data.
  *
- * @param options.name - List of cookie names to check.
- * @param options.getSessionForCookieValue - Function to retrieve a session using a cookie value.
+ * Reads session from a cookie on incoming requests and automatically updates the cookie
+ * when the session changes (e.g., after login).
+ *
+ * @param options.name - Cookie name
+ * @param options.expiresIn - Cookie expiration time (e.g., { value: 30, unit: 'day' })
+ * @param options.options - Cookie serialization options (httpOnly, secure, sameSite, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { authCookie } from '@pikku/core/middleware'
+ *
+ * addHTTPMiddleware([
+ *   authCookie({
+ *     name: 'session',
+ *     expiresIn: { value: 30, unit: 'day' },
+ *     options: {
+ *       httpOnly: true,
+ *       secure: true,
+ *       sameSite: 'strict',
+ *       path: '/'
+ *     }
+ *   })
+ * ])
+ * ```
  */
-export const authCookie = ({ name, getSessionForCookieValue, jwt, options, expiresIn, }) => {
-    const middleware = async (services, { http }, next) => {
-        const { userSession: userSessionService, jwt: jwtService, logger, } = services;
-        if (!http?.request || userSessionService.get()) {
-            return next();
-        }
-        let userSession = null;
-        const cookieValue = http.request.cookie(name);
-        if (cookieValue) {
-            if (jwt) {
-                if (!jwtService) {
-                    throw new Error('JWT service is required for JWT decoding.');
-                }
-                userSession = await jwtService.decode(cookieValue);
-            }
-            else if (getSessionForCookieValue) {
-                userSession = await getSessionForCookieValue(services, cookieValue, name);
-            }
-        }
+export const authCookie = pikkuMiddlewareFactory(({ name, options, expiresIn }) => pikkuMiddleware(async ({ userSession: userSessionService, jwt: jwtService, logger }, { http }, next) => {
+    if (!http?.request || userSessionService.get()) {
+        return next();
+    }
+    // Try to decode session from cookie
+    const cookieValue = http.request.cookie(name);
+    if (cookieValue && jwtService) {
+        const userSession = await jwtService.decode(cookieValue);
         if (userSession) {
             userSessionService.setInitial(userSession);
         }
-        await next();
-        // Set the cookie in the response if the session has changed
-        if (!http?.response) {
-            return;
+    }
+    await next();
+    // Set the cookie in the response if the session has changed
+    if (!http?.response) {
+        return;
+    }
+    if (userSessionService.sessionChanged) {
+        const session = userSessionService.get();
+        if (jwtService) {
+            http.response.cookie(name, await jwtService.encode(expiresIn, session), {
+                ...options,
+                expires: getRelativeTimeOffsetFromNow(expiresIn),
+            });
         }
-        if (userSessionService.sessionChanged) {
-            const session = userSessionService.get();
-            if (jwt) {
-                if (!jwtService) {
-                    throw new Error('JWT service is required for JWT encoding.');
-                }
-                http.response.cookie(name, await jwtService.encode(expiresIn, session), {
-                    ...options,
-                    expires: getRelativeTimeOffsetFromNow(expiresIn),
-                });
-            }
-            else {
-                logger.warn('No JWT service available, unable to set cookie');
-            }
+        else {
+            logger.warn('No JWT service available, unable to set cookie');
         }
-    };
-    return middleware;
-};
+    }
+}));

package/dist/middleware/timeout.d.ts

@@ -1,2 +1,6 @@
-import { CorePikkuMiddleware } from '../types/core.types.js';
-export declare const timeout: (timeout: number) => CorePikkuMiddleware;
+export declare const timeout: () => import("../types/core.types.js").CorePikkuMiddlewareFactory<{
+    timeout: number;
+}, import("../types/core.types.js").CoreSingletonServices<{
+    logLevel?: import("../index.js").LogLevel;
+    secrets?: {};
+}>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/timeout.js

@@ -1,10 +1,8 @@
 import { RequestTimeoutError } from '../errors/errors.js';
-export const timeout = (timeout) => {
-    const middleware = async (_services, _interaction, next) => {
-        setTimeout(() => {
-            throw new RequestTimeoutError();
-        }, timeout);
-        await next();
-    };
-    return middleware;
-};
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js';
+export const timeout = () => pikkuMiddlewareFactory(({ timeout }) => pikkuMiddleware(async (_services, _interaction, next) => {
+    setTimeout(() => {
+        throw new RequestTimeoutError();
+    }, timeout);
+    await next();
+}));

package/dist/middleware-runner.d.ts

@@ -1,5 +1,5 @@
 import { UserSessionService } from './services/user-session-service.js';
-import { CoreSingletonServices, PikkuInteraction, CorePikkuMiddleware, PikkuWiringTypes } from './types/core.types.js';
+import { CoreSingletonServices, PikkuInteraction, CorePikkuMiddleware, CorePikkuMiddlewareGroup, PikkuWiringTypes, MiddlewareMetadata } from './types/core.types.js';
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *
@@ -21,73 +21,76 @@ export declare const runMiddleware: <Middleware extends CorePikkuMiddleware>(ser
     userSession?: UserSessionService<any>;
 }, interaction: PikkuInteraction, middlewares: readonly Middleware[], main?: () => Promise<unknown>) => Promise<unknown>;
 /**
- * Adds global middleware for a specific tag.
+ * Registers global middleware for a specific tag.
  *
- * This function allows you to register middleware that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ * This function registers middleware at runtime that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP, CLI) that includes the matching tag.
+ *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addMiddleware('tag', [...])`
+ *
+ * Accepts an array that can contain:
+ * - Direct middleware functions (CorePikkuMiddleware)
+ * - Factory middleware functions (CorePikkuMiddlewareFactory)
  *
  * @template PikkuMiddleware The middleware type.
  * @param {string} tag - The tag that the middleware should apply to.
- * @param {PikkuMiddleware[]} middleware - The middleware array to apply for the specified tag.
+ * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this tag.
  *
- * @throws {Error} If middleware for the tag already exists.
+ * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
  *
  * @example
  * ```typescript
- * // Add admin middleware for admin endpoints
- * addMiddleware('admin', [adminMiddleware])
- *
- * // Add authentication middleware for auth endpoints
- * addMiddleware('auth', [authMiddleware])
+ * // Recommended: tree-shakeable
+ * export const adminMiddleware = () => addMiddleware('admin', [
+ *   authMiddleware,
+ *   loggingMiddleware({ level: 'info' })
+ * ])
  *
- * // Add logging middleware for all API endpoints
- * addMiddleware('api', [loggingMiddleware])
+ * // Also works: no tree-shaking
+ * export const apiMiddleware = addMiddleware('api', [
+ *   rateLimitMiddleware
+ * ])
  * ```
  */
-export declare const addMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(tag: string, middleware: PikkuMiddleware[]) => void;
+export declare const addMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(tag: string, middleware: CorePikkuMiddlewareGroup) => CorePikkuMiddlewareGroup;
 /**
- * Retrieves middleware for a given set of tags.
+ * Retrieves a registered middleware function by its name.
  *
- * This function looks up all middleware registered for any of the provided tags
- * and returns them as a flattened array.
+ * This function looks up middleware that was registered with registerMiddleware.
+ * It's used internally by the framework to resolve middleware references in metadata.
  *
- * @param {string[]} tags - Array of tags to look up middleware for.
- * @returns {CorePikkuMiddleware[]} Array of middleware functions that apply to the given tags.
+ * @param {string} name - The unique name (pikkuFuncName) of the middleware function.
+ * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
  *
- * @example
- * ```typescript
- * // Get all middleware for tags 'api' and 'auth'
- * const middleware = getMiddlewareForTags(['api', 'auth'])
- * ```
+ * @internal
  */
-export declare const getMiddlewareForTags: (tags?: string[]) => CorePikkuMiddleware[];
+export declare const getMiddlewareByName: (name: string) => CorePikkuMiddleware | undefined;
 /**
- * Combines tag-based middleware with wiring-specific middleware and function-level middleware.
+ * Combines wiring-specific middleware with function-level middleware.
  *
- * This helper function gets middleware for tags and combines it with any
- * wiring-specific middleware and function-level middleware, avoiding the need for manual spreading.
+ * This function resolves middleware metadata into actual middleware functions and combines them.
+ * It filters out wire middleware without tags from inheritedMiddleware to avoid duplication
+ * (those are passed separately as wireMiddleware).
  *
  * @param {object} options - Configuration object for combining middleware.
- * @param {CorePikkuMiddleware[] | undefined} options.wiringMiddleware - Wiring-specific middleware.
- * @param {string[] | undefined} options.wiringTags - Array of wiring-level tags to look up middleware for.
- * @param {CorePikkuMiddleware[] | undefined} options.funcMiddleware - Function-level middleware.
- * @param {string[] | undefined} options.funcTags - Array of function-level tags to look up middleware for.
- * @returns {CorePikkuMiddleware[]} Combined array of tag-based and wiring-specific middleware.
+ * @param {MiddlewareMetadata[] | undefined} options.inheritedMiddleware - Metadata from wiring (HTTP + tags + wire with tags).
+ * @param {CorePikkuMiddleware[] | undefined} options.wireMiddleware - Inline wire middleware.
+ * @param {MiddlewareMetadata[] | undefined} options.funcMiddleware - Function middleware metadata.
+ * @returns {CorePikkuMiddleware[]} Combined array of resolved middleware.
  *
  * @example
  * ```typescript
- * const combined = combineMiddleware({
- *   wiringMiddleware: httpRoute.middleware,
- *   wiringTags: httpRoute.tags,
- *   funcMiddleware: funcConfig.middleware,
- *   funcTags: funcConfig.tags
+ * const combined = combineMiddleware(wireType, wireId, {
+ *   inheritedMiddleware: meta.middleware,
+ *   wireMiddleware: [inlineMiddleware],
+ *   funcMiddleware: funcMeta.middleware
  * })
  * ```
  */
-export declare const combineMiddleware: (wireType: PikkuWiringTypes, uid: string, { httpMiddleware, wiringMiddleware, wiringTags, funcMiddleware, funcTags, }?: {
-    httpMiddleware?: CorePikkuMiddleware[];
-    wiringMiddleware?: CorePikkuMiddleware[];
-    wiringTags?: string[];
+export declare const combineMiddleware: (wireType: PikkuWiringTypes, uid: string, { wireInheritedMiddleware, wireMiddleware, funcInheritedMiddleware, funcMiddleware, }?: {
+    wireInheritedMiddleware?: MiddlewareMetadata[];
+    wireMiddleware?: CorePikkuMiddleware[];
+    funcInheritedMiddleware?: MiddlewareMetadata[];
     funcMiddleware?: CorePikkuMiddleware[];
-    funcTags?: string[];
 }) => readonly CorePikkuMiddleware[];

package/dist/middleware-runner.js

@@ -33,66 +33,58 @@ export const runMiddleware = async (services, interaction, middlewares, main) =>
     return result;
 };
 /**
- * Adds global middleware for a specific tag.
+ * Registers global middleware for a specific tag.
  *
- * This function allows you to register middleware that will be applied to
- * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ * This function registers middleware at runtime that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP, CLI) that includes the matching tag.
+ *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addMiddleware('tag', [...])`
+ *
+ * Accepts an array that can contain:
+ * - Direct middleware functions (CorePikkuMiddleware)
+ * - Factory middleware functions (CorePikkuMiddlewareFactory)
  *
  * @template PikkuMiddleware The middleware type.
  * @param {string} tag - The tag that the middleware should apply to.
- * @param {PikkuMiddleware[]} middleware - The middleware array to apply for the specified tag.
+ * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this tag.
  *
- * @throws {Error} If middleware for the tag already exists.
+ * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
  *
  * @example
  * ```typescript
- * // Add admin middleware for admin endpoints
- * addMiddleware('admin', [adminMiddleware])
- *
- * // Add authentication middleware for auth endpoints
- * addMiddleware('auth', [authMiddleware])
+ * // Recommended: tree-shakeable
+ * export const adminMiddleware = () => addMiddleware('admin', [
+ *   authMiddleware,
+ *   loggingMiddleware({ level: 'info' })
+ * ])
  *
- * // Add logging middleware for all API endpoints
- * addMiddleware('api', [loggingMiddleware])
+ * // Also works: no tree-shaking
+ * export const apiMiddleware = addMiddleware('api', [
+ *   rateLimitMiddleware
+ * ])
  * ```
  */
 export const addMiddleware = (tag, middleware) => {
-    const middlewareStore = pikkuState('misc', 'middleware');
-    // Check if tag already exists
-    if (middlewareStore[tag]) {
-        throw new Error(`Middleware for tag '${tag}' already exists. Use a different tag or remove the existing middleware first.`);
-    }
-    middlewareStore[tag] = middleware;
+    const tagGroups = pikkuState('middleware', 'tagGroup');
+    tagGroups[tag] = middleware;
+    return middleware;
 };
 /**
- * Retrieves middleware for a given set of tags.
+ * Retrieves a registered middleware function by its name.
  *
- * This function looks up all middleware registered for any of the provided tags
- * and returns them as a flattened array.
+ * This function looks up middleware that was registered with registerMiddleware.
+ * It's used internally by the framework to resolve middleware references in metadata.
  *
- * @param {string[]} tags - Array of tags to look up middleware for.
- * @returns {CorePikkuMiddleware[]} Array of middleware functions that apply to the given tags.
+ * @param {string} name - The unique name (pikkuFuncName) of the middleware function.
+ * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
  *
- * @example
- * ```typescript
- * // Get all middleware for tags 'api' and 'auth'
- * const middleware = getMiddlewareForTags(['api', 'auth'])
- * ```
+ * @internal
  */
-export const getMiddlewareForTags = (tags) => {
-    if (!tags || tags.length === 0) {
-        return [];
-    }
+export const getMiddlewareByName = (name) => {
     const middlewareStore = pikkuState('misc', 'middleware');
-    const applicableMiddleware = [];
-    // Collect middleware for all matching tags
-    for (const tag of tags) {
-        const tagMiddleware = middlewareStore[tag];
-        if (tagMiddleware) {
-            applicableMiddleware.push(...tagMiddleware);
-        }
-    }
-    return applicableMiddleware;
+    const middleware = middlewareStore[name];
+    return middleware?.[0];
 };
 const middlewareCache = {
     [PikkuWiringTypes.http]: {},
@@ -101,47 +93,86 @@ const middlewareCache = {
     [PikkuWiringTypes.queue]: {},
     [PikkuWiringTypes.scheduler]: {},
     [PikkuWiringTypes.mcp]: {},
+    [PikkuWiringTypes.cli]: {},
 };
 /**
- * Combines tag-based middleware with wiring-specific middleware and function-level middleware.
+ * Combines wiring-specific middleware with function-level middleware.
  *
- * This helper function gets middleware for tags and combines it with any
- * wiring-specific middleware and function-level middleware, avoiding the need for manual spreading.
+ * This function resolves middleware metadata into actual middleware functions and combines them.
+ * It filters out wire middleware without tags from inheritedMiddleware to avoid duplication
+ * (those are passed separately as wireMiddleware).
  *
  * @param {object} options - Configuration object for combining middleware.
- * @param {CorePikkuMiddleware[] | undefined} options.wiringMiddleware - Wiring-specific middleware.
- * @param {string[] | undefined} options.wiringTags - Array of wiring-level tags to look up middleware for.
- * @param {CorePikkuMiddleware[] | undefined} options.funcMiddleware - Function-level middleware.
- * @param {string[] | undefined} options.funcTags - Array of function-level tags to look up middleware for.
- * @returns {CorePikkuMiddleware[]} Combined array of tag-based and wiring-specific middleware.
+ * @param {MiddlewareMetadata[] | undefined} options.inheritedMiddleware - Metadata from wiring (HTTP + tags + wire with tags).
+ * @param {CorePikkuMiddleware[] | undefined} options.wireMiddleware - Inline wire middleware.
+ * @param {MiddlewareMetadata[] | undefined} options.funcMiddleware - Function middleware metadata.
+ * @returns {CorePikkuMiddleware[]} Combined array of resolved middleware.
  *
  * @example
  * ```typescript
- * const combined = combineMiddleware({
- *   wiringMiddleware: httpRoute.middleware,
- *   wiringTags: httpRoute.tags,
- *   funcMiddleware: funcConfig.middleware,
- *   funcTags: funcConfig.tags
+ * const combined = combineMiddleware(wireType, wireId, {
+ *   inheritedMiddleware: meta.middleware,
+ *   wireMiddleware: [inlineMiddleware],
+ *   funcMiddleware: funcMeta.middleware
  * })
  * ```
  */
-export const combineMiddleware = (wireType, uid, { httpMiddleware, wiringMiddleware, wiringTags, funcMiddleware, funcTags, } = {}) => {
+export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wireMiddleware, funcInheritedMiddleware, funcMiddleware, } = {}) => {
     if (middlewareCache[wireType][uid]) {
         return middlewareCache[wireType][uid];
     }
-    // Run middleware in specific order:
-    // 1) wiringTags middleware
-    // 2) wiringMiddleware
-    // 3) funcMiddleware
-    // 4) funcTags middleware
-    const wiringTaggedMiddleware = getMiddlewareForTags(wiringTags);
-    const funcTaggedMiddleware = getMiddlewareForTags(funcTags);
-    middlewareCache[wireType][uid] = freezeDedupe([
-        ...(httpMiddleware || []),
-        ...wiringTaggedMiddleware,
-        ...(wiringMiddleware || []),
-        ...(funcMiddleware || []),
-        ...funcTaggedMiddleware,
-    ]);
+    const resolved = [];
+    // 1. Resolve wire inherited middleware (HTTP + tag groups + individual wire middleware)
+    if (wireInheritedMiddleware) {
+        for (const meta of wireInheritedMiddleware) {
+            if (meta.type === 'http') {
+                // Look up HTTP middleware group from pikkuState
+                const group = pikkuState('middleware', 'httpGroup')[meta.route];
+                if (group) {
+                    // At runtime, all factories should be resolved to middleware
+                    resolved.push(...group);
+                }
+            }
+            else if (meta.type === 'tag') {
+                // Look up tag middleware group from pikkuState
+                const group = pikkuState('middleware', 'tagGroup')[meta.tag];
+                if (group) {
+                    // At runtime, all factories should be resolved to middleware
+                    resolved.push(...group);
+                }
+            }
+            else if (meta.type === 'wire') {
+                // Individual wire middleware (exported, not inline)
+                const middleware = getMiddlewareByName(meta.name);
+                if (middleware) {
+                    resolved.push(middleware);
+                }
+            }
+        }
+    }
+    // 2. Add inline wire middleware
+    if (wireMiddleware) {
+        resolved.push(...wireMiddleware);
+    }
+    // 3. Resolve function inherited middleware (only tags, wire middleware already handled)
+    if (funcInheritedMiddleware) {
+        for (const meta of funcInheritedMiddleware) {
+            if (meta.type === 'tag') {
+                // Look up tag middleware group from pikkuState
+                const group = pikkuState('middleware', 'tagGroup')[meta.tag];
+                if (group) {
+                    // At runtime, all factories should be resolved to middleware
+                    resolved.push(...group);
+                }
+            }
+            // Note: wire middleware is already handled in wireInheritedMiddleware
+        }
+    }
+    // 4. Add inline function middleware
+    if (funcMiddleware) {
+        resolved.push(...funcMiddleware);
+    }
+    // Deduplicate and freeze
+    middlewareCache[wireType][uid] = freezeDedupe(resolved);
     return middlewareCache[wireType][uid];
 };