@pikku/core 0.12.3 → 0.12.4

package/src/middleware-runner.test.ts

@@ -1,418 +0,0 @@
-import { describe, test, beforeEach } from 'node:test'
-import assert from 'node:assert'
-import {
-  combineMiddleware,
-  addMiddleware,
-  runMiddleware,
-} from './middleware-runner.js'
-import { resetPikkuState } from './pikku-state.js'
-import type { CorePikkuMiddleware } from './types/core.types.js'
-
-beforeEach(() => {
-  resetPikkuState()
-})
-
-describe('combineMiddleware', () => {
-  test('should return empty array when no parameters provided', () => {
-    const result = combineMiddleware('http', Math.random().toString())
-    assert.deepEqual(result, [])
-  })
-
-  test('should return empty array when all parameters are undefined', () => {
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wiringMiddleware: undefined,
-      wiringTags: undefined,
-      funcMiddleware: undefined,
-      funcTags: undefined,
-    })
-    assert.deepEqual(result, [])
-  })
-
-  test('should combine wiring middleware only', () => {
-    const mockMiddleware1: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-    const mockMiddleware2: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireMiddleware: [mockMiddleware1, mockMiddleware2],
-    })
-
-    assert.equal(result.length, 2)
-    assert.equal(result[0], mockMiddleware1)
-    assert.equal(result[1], mockMiddleware2)
-  })
-
-  test('should combine function middleware only', () => {
-    const mockMiddleware1: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-    const mockMiddleware2: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      funcMiddleware: [mockMiddleware1, mockMiddleware2],
-    })
-
-    assert.equal(result.length, 2)
-    assert.equal(result[0], mockMiddleware1)
-    assert.equal(result[1], mockMiddleware2)
-  })
-
-  test('should execute middleware in correct order: wireInheritedMiddleware (tags) → wireMiddleware → funcInheritedMiddleware (tags) → funcMiddleware', () => {
-    // Setup tagged middleware
-    const wiringTagMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-    const funcTagMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('wiringTag', [wiringTagMiddleware])
-    addMiddleware('funcTag', [funcTagMiddleware])
-
-    const wiringMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-    const funcMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [{ type: 'tag', tag: 'wiringTag' }],
-      wireMiddleware: [wiringMiddleware],
-      funcInheritedMiddleware: [{ type: 'tag', tag: 'funcTag' }],
-      funcMiddleware: [funcMiddleware],
-    })
-
-    assert.equal(result.length, 4)
-    // Order: wireInheritedMiddleware (tags), wireMiddleware, funcInheritedMiddleware (tags), funcMiddleware
-    assert.equal(result[0], wiringTagMiddleware) // wireInheritedMiddleware tags first
-    assert.equal(result[1], wiringMiddleware) // wireMiddleware second
-    assert.equal(result[2], funcTagMiddleware) // funcInheritedMiddleware tags third
-    assert.equal(result[3], funcMiddleware) // funcMiddleware last
-  })
-
-  test('should handle wiring tags only', () => {
-    const taggedMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('testTag', [taggedMiddleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [{ type: 'tag', tag: 'testTag' }],
-    })
-
-    assert.equal(result.length, 1)
-    assert.equal(result[0], taggedMiddleware)
-  })
-
-  test('should handle function tags only', () => {
-    const taggedMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('funcTestTag', [taggedMiddleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      funcInheritedMiddleware: [{ type: 'tag', tag: 'funcTestTag' }],
-    })
-
-    assert.equal(result.length, 1)
-    assert.equal(result[0], taggedMiddleware)
-  })
-
-  test('should handle multiple tags', () => {
-    const middleware1: CorePikkuMiddleware = async (services, wire, next) => {
-      await next()
-    }
-    const middleware2: CorePikkuMiddleware = async (services, wire, next) => {
-      await next()
-    }
-
-    addMiddleware('tag1', [middleware1])
-    addMiddleware('tag2', [middleware2])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [
-        { type: 'tag', tag: 'tag1' },
-        { type: 'tag', tag: 'tag2' },
-      ],
-    })
-
-    assert.equal(result.length, 2)
-    assert.equal(result[0], middleware1)
-    assert.equal(result[1], middleware2)
-  })
-
-  test('should apply parent tag middleware to namespaced tag', () => {
-    const billingMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('billing', [billingMiddleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing:read' }],
-    })
-
-    assert.equal(result.length, 1)
-    assert.equal(result[0], billingMiddleware)
-  })
-
-  test('should apply exact tag middleware for non-namespaced tag', () => {
-    const billingMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('billing', [billingMiddleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing' }],
-    })
-
-    assert.equal(result.length, 1)
-    assert.equal(result[0], billingMiddleware)
-  })
-
-  test('should apply both exact and parent tag middleware (specific first)', () => {
-    const billingMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-    const billingReadMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('billing', [billingMiddleware])
-    addMiddleware('billing:read', [billingReadMiddleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing:read' }],
-    })
-
-    assert.equal(result.length, 2)
-    assert.equal(result[0], billingReadMiddleware)
-    assert.equal(result[1], billingMiddleware)
-  })
-
-  test('should resolve multi-level namespace tags', () => {
-    const billingMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-    const billingReadMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-    const billingReadAdminMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('billing', [billingMiddleware])
-    addMiddleware('billing:read', [billingReadMiddleware])
-    addMiddleware('billing:read:admin', [billingReadAdminMiddleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [{ type: 'tag', tag: 'billing:read:admin' }],
-    })
-
-    assert.equal(result.length, 3)
-    assert.equal(result[0], billingReadAdminMiddleware)
-    assert.equal(result[1], billingReadMiddleware)
-    assert.equal(result[2], billingMiddleware)
-  })
-
-  test('should apply parent tag middleware via funcInheritedMiddleware', () => {
-    const billingMiddleware: CorePikkuMiddleware = async (
-      services,
-      wire,
-      next
-    ) => {
-      await next()
-    }
-
-    addMiddleware('billing', [billingMiddleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      funcInheritedMiddleware: [{ type: 'tag', tag: 'billing:write' }],
-    })
-
-    assert.equal(result.length, 1)
-    assert.equal(result[0], billingMiddleware)
-  })
-
-  test('should ignore non-existent tags', () => {
-    const middleware: CorePikkuMiddleware = async (services, wire, next) => {
-      await next()
-    }
-
-    addMiddleware('existingTag', [middleware])
-
-    const result = combineMiddleware('http', Math.random().toString(), {
-      wireInheritedMiddleware: [
-        { type: 'tag', tag: 'existingTag' },
-        { type: 'tag', tag: 'nonExistentTag' },
-      ],
-      funcInheritedMiddleware: [{ type: 'tag', tag: 'anotherNonExistentTag' }],
-    })
-
-    assert.equal(result.length, 1)
-    assert.equal(result[0], middleware)
-  })
-})
-
-describe('runMiddleware', () => {
-  test('should deduplicate middleware using Set', async () => {
-    const executionOrder: string[] = []
-
-    const middleware1: CorePikkuMiddleware = async (services, wire, next) => {
-      executionOrder.push('middleware1')
-      await next()
-    }
-
-    const middleware2: CorePikkuMiddleware = async (services, wire, next) => {
-      executionOrder.push('middleware2')
-      await next()
-    }
-
-    await runMiddleware(
-      {} as any,
-      {} as any,
-      combineMiddleware('rpc', Math.random().toString(), {
-        wireMiddleware: [middleware1, middleware2, middleware1, middleware2],
-      }),
-      async () => {
-        executionOrder.push('main')
-      }
-    )
-
-    // Should only execute each middleware once
-    assert.deepEqual(executionOrder, ['middleware1', 'middleware2', 'main'])
-  })
-
-  test('should execute middleware in correct order', async () => {
-    const executionOrder: string[] = []
-
-    const middleware1: CorePikkuMiddleware = async (services, wire, next) => {
-      executionOrder.push('start1')
-      await next()
-      executionOrder.push('end1')
-    }
-
-    const middleware2: CorePikkuMiddleware = async (services, wire, next) => {
-      executionOrder.push('start2')
-      await next()
-      executionOrder.push('end2')
-    }
-
-    await runMiddleware(
-      {} as any,
-      {} as any,
-      [middleware1, middleware2],
-      async () => {
-        executionOrder.push('main')
-      }
-    )
-
-    assert.deepEqual(executionOrder, [
-      'start1',
-      'start2',
-      'main',
-      'end2',
-      'end1',
-    ])
-  })
-
-  test('should work with empty middleware array', async () => {
-    let mainExecuted = false
-
-    await runMiddleware({} as any, {} as any, [], async () => {
-      mainExecuted = true
-    })
-
-    assert.equal(mainExecuted, true)
-  })
-
-  test('should work without main function', async () => {
-    const executionOrder: string[] = []
-
-    const middleware: CorePikkuMiddleware = async (services, wire, next) => {
-      executionOrder.push('middleware')
-      await next()
-    }
-
-    await runMiddleware({} as any, {} as any, [middleware])
-
-    assert.deepEqual(executionOrder, ['middleware'])
-  })
-})

package/src/middleware-runner.ts

@@ -1,234 +0,0 @@
-import type {
-  CoreSingletonServices,
-  PikkuWire,
-  CorePikkuMiddleware,
-  CorePikkuMiddlewareGroup,
-  PikkuWiringTypes,
-  MiddlewareMetadata,
-} from './types/core.types.js'
-import { pikkuState } from './pikku-state.js'
-import { freezeDedupe, getTagGroups } from './utils.js'
-
-/**
- * Runs a chain of middleware functions in sequence before executing the main function.
- *
- * @param services - An object containing services (e.g., singletonServices, userSession, etc.)
- * @param wire - The wire context, e.g., { http }.
- * @param middlewares - An array of middleware functions to run.
- * @param main - The main function to execute after all middleware have run.
- * @returns A promise resolving to the result of the main function.
- *
- * @example
- * runMiddleware(
- *   { ...services, userSession },
- *   { http },
- *   [middleware1, middleware2, middleware3],
- *   async () => { return await runMain(); }
- * );
- */
-export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
-  services: CoreSingletonServices,
-  wire: PikkuWire,
-  middlewares: readonly Middleware[],
-  main?: () => Promise<unknown>
-): Promise<unknown> => {
-  // Deduplicate middleware using Set to avoid running the same middleware multiple times
-  let result: any
-  const dispatch = async (index: number): Promise<any> => {
-    if (middlewares && index < middlewares.length) {
-      return await middlewares[index]!(services as any, wire, () =>
-        dispatch(index + 1)
-      )
-    } else if (main) {
-      result = await main()
-    }
-  }
-  await dispatch(0)
-  return result
-}
-
-/**
- * Registers global middleware for a specific 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 {CorePikkuMiddlewareGroup} middleware - Array of middleware for this tag.
- *
- * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
- *
- * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const adminMiddleware = () => addMiddleware('admin', [
- *   authMiddleware,
- *   loggingMiddleware({ level: 'info' })
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiMiddleware = addMiddleware('api', [
- *   rateLimitMiddleware
- * ])
- * ```
- */
-export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
-  tag: string,
-  middleware: CorePikkuMiddlewareGroup,
-  packageName: string | null = null
-): CorePikkuMiddlewareGroup => {
-  const tagGroups = pikkuState(packageName, 'middleware', 'tagGroup')
-  tagGroups[tag] = middleware
-  return middleware
-}
-
-/**
- * Retrieves a registered middleware function by its name.
- *
- * 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} name - The unique name (pikkuFuncId) of the middleware function.
- * @returns {CorePikkuMiddleware | undefined} The middleware function, or undefined if not found.
- *
- * @internal
- */
-const getMiddlewareByName = (name: string): CorePikkuMiddleware | undefined => {
-  const middlewareStore = pikkuState(null, 'misc', 'middleware')
-  const middleware = middlewareStore[name]
-  return middleware?.[0]
-}
-
-const middlewareCache: Record<
-  PikkuWiringTypes,
-  Record<string, readonly CorePikkuMiddleware[]>
-> = {
-  http: {},
-  rpc: {},
-  channel: {},
-  queue: {},
-  scheduler: {},
-  trigger: {},
-  mcp: {},
-  agent: {},
-  cli: {},
-  workflow: {},
-  gateway: {},
-}
-
-/**
- * Combines wiring-specific middleware with function-level middleware.
- *
- * 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 {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(wireType, wireId, {
- *   inheritedMiddleware: meta.middleware,
- *   wireMiddleware: [inlineMiddleware],
- *   funcMiddleware: funcMeta.middleware
- * })
- * ```
- */
-export const combineMiddleware = (
-  wireType: PikkuWiringTypes,
-  uid: string,
-  {
-    wireInheritedMiddleware,
-    wireMiddleware,
-    funcInheritedMiddleware,
-    funcMiddleware,
-    packageName = null,
-  }: {
-    wireInheritedMiddleware?: MiddlewareMetadata[]
-    wireMiddleware?: CorePikkuMiddleware[]
-    funcInheritedMiddleware?: MiddlewareMetadata[]
-    funcMiddleware?: CorePikkuMiddleware[]
-    packageName?: string | null
-  } = {}
-): readonly CorePikkuMiddleware[] => {
-  if (middlewareCache[wireType][uid]) {
-    return middlewareCache[wireType][uid]
-  }
-
-  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(packageName, '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') {
-        const groups = getTagGroups(
-          pikkuState(packageName, 'middleware', 'tagGroup'),
-          meta.tag
-        )
-        for (const group of groups) {
-          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') {
-        const groups = getTagGroups(
-          pikkuState(packageName, 'middleware', 'tagGroup'),
-          meta.tag
-        )
-        for (const group of groups) {
-          resolved.push(...(group as CorePikkuMiddleware[]))
-        }
-      }
-      // 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
-  ) as readonly CorePikkuMiddleware[]
-
-  return middlewareCache[wireType][uid]
-}