@pikku/core 0.9.11 → 0.10.0

package/src/middleware-runner.ts

@@ -3,7 +3,9 @@ import {
   CoreSingletonServices,
   PikkuInteraction,
   CorePikkuMiddleware,
+  CorePikkuMiddlewareGroup,
   PikkuWiringTypes,
+  MiddlewareMetadata,
 } from './types/core.types.js'
 import { pikkuState } from './pikku-state.js'
 import { freezeDedupe } from './utils.js'
@@ -49,79 +51,64 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
 }
 
 /**
- * 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])
+ * // Recommended: tree-shakeable
+ * export const adminMiddleware = () => addMiddleware('admin', [
+ *   authMiddleware,
+ *   loggingMiddleware({ level: 'info' })
+ * ])
  *
- * // Add authentication middleware for auth endpoints
- * addMiddleware('auth', [authMiddleware])
- *
- * // Add logging middleware for all API endpoints
- * addMiddleware('api', [loggingMiddleware])
+ * // Also works: no tree-shaking
+ * export const apiMiddleware = addMiddleware('api', [
+ *   rateLimitMiddleware
+ * ])
  * ```
  */
 export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   tag: string,
-  middleware: PikkuMiddleware[]
-) => {
-  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 as CorePikkuMiddleware[]
+  middleware: CorePikkuMiddlewareGroup
+): CorePikkuMiddlewareGroup => {
+  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?: string[]
-): CorePikkuMiddleware[] => {
-  if (!tags || tags.length === 0) {
-    return []
-  }
-
+export const getMiddlewareByName = (
+  name: string
+): CorePikkuMiddleware | undefined => {
   const middlewareStore = pikkuState('misc', 'middleware')
-  const applicableMiddleware: CorePikkuMiddleware[] = []
-
-  // 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: Record<
@@ -134,28 +121,28 @@ const middlewareCache: Record<
   [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
  * })
  * ```
  */
@@ -163,38 +150,79 @@ export const combineMiddleware = (
   wireType: PikkuWiringTypes,
   uid: string,
   {
-    httpMiddleware,
-    wiringMiddleware,
-    wiringTags,
+    wireInheritedMiddleware,
+    wireMiddleware,
+    funcInheritedMiddleware,
     funcMiddleware,
-    funcTags,
   }: {
-    httpMiddleware?: CorePikkuMiddleware[]
-    wiringMiddleware?: CorePikkuMiddleware[]
-    wiringTags?: string[]
+    wireInheritedMiddleware?: MiddlewareMetadata[]
+    wireMiddleware?: CorePikkuMiddleware[]
+    funcInheritedMiddleware?: MiddlewareMetadata[]
     funcMiddleware?: CorePikkuMiddleware[]
-    funcTags?: string[]
   } = {}
 ): readonly CorePikkuMiddleware[] => {
   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)
+  const resolved: CorePikkuMiddleware[] = []
+
+  // 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 as CorePikkuMiddleware[]))
+        }
+      } 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 as CorePikkuMiddleware[]))
+        }
+      } 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 as CorePikkuMiddleware[]))
+        }
+      }
+      // Note: wire middleware is already handled in wireInheritedMiddleware
+    }
+  }
+
+  // 4. Add inline function middleware
+  if (funcMiddleware) {
+    resolved.push(...funcMiddleware)
+  }
 
-  middlewareCache[wireType][uid] = freezeDedupe([
-    ...(httpMiddleware || []),
-    ...wiringTaggedMiddleware,
-    ...(wiringMiddleware || []),
-    ...(funcMiddleware || []),
-    ...funcTaggedMiddleware,
-  ]) as readonly CorePikkuMiddleware[]
+  // Deduplicate and freeze
+  middlewareCache[wireType][uid] = freezeDedupe(
+    resolved
+  ) as readonly CorePikkuMiddleware[]
 
   return middlewareCache[wireType][uid]
 }

package/src/permissions.test.ts

@@ -181,7 +181,7 @@ describe('runPermissions', () => {
     addPermission('wiringTag', [wiringTagPermission])
 
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['wiringTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'wiringTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -205,7 +205,7 @@ describe('runPermissions', () => {
     addPermission('wiringTag', [wiringTagPermission])
     addPermission('funcTag', [funcTagPermission])
 
-    const wiringPermissions: CorePermissionGroup = {
+    const wirePermissions: CorePermissionGroup = {
       permissions: [
         async () => {
           executionOrder.push('wiringPermission')
@@ -224,16 +224,16 @@ describe('runPermissions', () => {
     }
 
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['wiringTag'],
-      wiringPermissions,
-      funcTags: ['funcTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'wiringTag' }],
+      wirePermissions,
+      funcInheritedPermissions: [{ type: 'tag', tag: 'funcTag' }],
       funcPermissions,
       allServices: mockServices,
       data: {},
       session: mockSession,
     })
 
-    // Order: wiringTags → wiringPermissions → funcTags → funcPermissions
+    // Order: wireInheritedPermissions (wiringTag) → wirePermissions → funcInheritedPermissions (funcTag) → funcPermissions
     assert.deepEqual(executionOrder, [
       'wiringTag',
       'wiringPermission',
@@ -250,7 +250,7 @@ describe('runPermissions', () => {
 
     // Should not throw because at least one permission passes
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['atLeastOneTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'atLeastOneTestTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -265,7 +265,7 @@ describe('runPermissions', () => {
 
     await assert.rejects(
       runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        wiringTags: ['allFailTestTag'],
+        wireInheritedPermissions: [{ type: 'tag', tag: 'allFailTestTag' }],
         allServices: mockServices,
         data: {},
         session: mockSession,
@@ -277,13 +277,13 @@ describe('runPermissions', () => {
   })
 
   test('should throw error when wiring permissions fail', async () => {
-    const wiringPermissions: CorePermissionGroup = {
+    const wirePermissions: CorePermissionGroup = {
       permissions: [async () => false],
     }
 
     await assert.rejects(
       runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        wiringPermissions,
+        wirePermissions,
         allServices: mockServices,
         data: {},
         session: mockSession,
@@ -301,7 +301,7 @@ describe('runPermissions', () => {
 
     await assert.rejects(
       runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        funcTags: ['funcTag'],
+        funcInheritedPermissions: [{ type: 'tag', tag: 'funcTag' }],
         allServices: mockServices,
         data: {},
         session: mockSession,
@@ -330,7 +330,7 @@ describe('runPermissions', () => {
     )
   })
 
-  test('should stop execution at first failing level', async () => {
+  test('should evaluate all permissions and pass if at least one succeeds', async () => {
     const executionOrder: string[] = []
 
     const failingWiringTagPermission = async () => {
@@ -340,7 +340,7 @@ describe('runPermissions', () => {
 
     addPermission('failingWiringTag', [failingWiringTagPermission])
 
-    const wiringPermissions: CorePermissionGroup = {
+    const wirePermissions: CorePermissionGroup = {
       permissions: [
         async () => {
           executionOrder.push('wiringPermission')
@@ -349,18 +349,17 @@ describe('runPermissions', () => {
       ],
     }
 
-    await assert.rejects(
-      runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-        wiringTags: ['failingWiringTag'],
-        wiringPermissions,
-        allServices: mockServices,
-        data: {},
-        session: mockSession,
-      })
-    )
+    // Should NOT throw because at least one permission (wirePermissions) passes
+    await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
+      wireInheritedPermissions: [{ type: 'tag', tag: 'failingWiringTag' }],
+      wirePermissions,
+      allServices: mockServices,
+      data: {},
+      session: mockSession,
+    })
 
-    // Should only execute wiring tag permissions, not wiring permissions
-    assert.deepEqual(executionOrder, ['wiringTag'])
+    // Both permissions should be evaluated
+    assert.deepEqual(executionOrder, ['wiringTag', 'wiringPermission'])
   })
 
   test('should handle array permissions in tag-based permissions', async () => {
@@ -370,7 +369,7 @@ describe('runPermissions', () => {
 
     // Should not throw because verifyPermissions handles array properly
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['arrayTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'arrayTestTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -386,7 +385,7 @@ describe('runPermissions', () => {
 
     // Should not throw because verifyPermissions handles objects properly
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['objectTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'objectTestTag' }],
       allServices: mockServices,
       data: {},
       session: mockSession,
@@ -410,7 +409,7 @@ describe('runPermissions', () => {
     addPermission('paramTestTag', [testPermission])
 
     await runPermissions(PikkuWiringTypes.rpc, Math.random().toString(), {
-      wiringTags: ['paramTestTag'],
+      wireInheritedPermissions: [{ type: 'tag', tag: 'paramTestTag' }],
       allServices: mockServices,
       data: testData,
       session: mockSession,