@pikku/core 0.9.3 → 0.9.5

package/src/middleware-runner.test.ts

@@ -0,0 +1,329 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import {
+  combineMiddleware,
+  addMiddleware,
+  getMiddlewareForTags,
+  runMiddleware,
+} from './middleware-runner.js'
+import { resetPikkuState } from './pikku-state.js'
+import { CorePikkuMiddleware } from './types/core.types.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+describe('combineMiddleware', () => {
+  test('should return empty array when no parameters provided', () => {
+    const result = combineMiddleware()
+    assert.deepEqual(result, [])
+  })
+
+  test('should return empty array when all parameters are undefined', () => {
+    const result = combineMiddleware({
+      wiringMiddleware: undefined,
+      wiringTags: undefined,
+      funcMiddleware: undefined,
+      funcTags: undefined,
+    })
+    assert.deepEqual(result, [])
+  })
+
+  test('should combine wiring middleware only', () => {
+    const mockMiddleware1: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+    const mockMiddleware2: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    const result = combineMiddleware({
+      wiringMiddleware: [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,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+    const mockMiddleware2: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    const result = combineMiddleware({
+      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: wiringTags → wiringMiddleware → funcMiddleware → funcTags', () => {
+    // Setup tagged middleware
+    const wiringTagMiddleware: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+    const funcTagMiddleware: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('wiringTag', [wiringTagMiddleware])
+    addMiddleware('funcTag', [funcTagMiddleware])
+
+    const wiringMiddleware: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+    const funcMiddleware: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    const result = combineMiddleware({
+      wiringMiddleware: [wiringMiddleware],
+      wiringTags: ['wiringTag'],
+      funcMiddleware: [funcMiddleware],
+      funcTags: ['funcTag'],
+    })
+
+    assert.equal(result.length, 4)
+    // Order: wiringTags, wiringMiddleware, funcMiddleware, funcTags
+    assert.equal(result[0], wiringTagMiddleware) // wiringTags first
+    assert.equal(result[1], wiringMiddleware) // wiringMiddleware second
+    assert.equal(result[2], funcMiddleware) // funcMiddleware third
+    assert.equal(result[3], funcTagMiddleware) // funcTags last
+  })
+
+  test('should handle wiring tags only', () => {
+    const taggedMiddleware: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('testTag', [taggedMiddleware])
+
+    const result = combineMiddleware({
+      wiringTags: ['testTag'],
+    })
+
+    assert.equal(result.length, 1)
+    assert.equal(result[0], taggedMiddleware)
+  })
+
+  test('should handle function tags only', () => {
+    const taggedMiddleware: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('funcTestTag', [taggedMiddleware])
+
+    const result = combineMiddleware({
+      funcTags: ['funcTestTag'],
+    })
+
+    assert.equal(result.length, 1)
+    assert.equal(result[0], taggedMiddleware)
+  })
+
+  test('should handle multiple tags', () => {
+    const middleware1: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+    const middleware2: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('tag1', [middleware1])
+    addMiddleware('tag2', [middleware2])
+
+    const result = combineMiddleware({
+      wiringTags: ['tag1', 'tag2'],
+    })
+
+    assert.equal(result.length, 2)
+    assert.equal(result[0], middleware1)
+    assert.equal(result[1], middleware2)
+  })
+
+  test('should ignore non-existent tags', () => {
+    const middleware: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      await next()
+    }
+
+    addMiddleware('existingTag', [middleware])
+
+    const result = combineMiddleware({
+      wiringTags: ['existingTag', 'nonExistentTag'],
+      funcTags: ['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,
+      interaction,
+      next
+    ) => {
+      executionOrder.push('middleware1')
+      await next()
+    }
+
+    const middleware2: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      next
+    ) => {
+      executionOrder.push('middleware2')
+      await next()
+    }
+
+    // Pass same middleware multiple times
+    const duplicatedMiddleware = [
+      middleware1,
+      middleware2,
+      middleware1,
+      middleware2,
+    ]
+
+    await runMiddleware(
+      {} as any,
+      {} as any,
+      duplicatedMiddleware,
+      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,
+      interaction,
+      next
+    ) => {
+      executionOrder.push('start1')
+      await next()
+      executionOrder.push('end1')
+    }
+
+    const middleware2: CorePikkuMiddleware = async (
+      services,
+      interaction,
+      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,
+      interaction,
+      next
+    ) => {
+      executionOrder.push('middleware')
+      await next()
+    }
+
+    await runMiddleware({} as any, {} as any, [middleware])
+
+    assert.deepEqual(executionOrder, ['middleware'])
+  })
+})

package/src/middleware-runner.ts

@@ -4,6 +4,7 @@ import {
   PikkuInteraction,
   CorePikkuMiddleware,
 } from './types/core.types.js'
+import { pikkuState } from './pikku-state.js'
 
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
@@ -30,10 +31,12 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   middlewares: Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
+  // Deduplicate middleware using Set to avoid running the same middleware multiple times
+  const uniqueMiddleware = Array.from(new Set(middlewares))
   let result: any
   const dispatch = async (index: number): Promise<any> => {
-    if (middlewares && index < middlewares.length) {
-      return await middlewares[index]!(services as any, interaction, () =>
+    if (uniqueMiddleware && index < uniqueMiddleware.length) {
+      return await uniqueMiddleware[index]!(services as any, interaction, () =>
         dispatch(index + 1)
       )
     } else if (main) {
@@ -43,3 +46,129 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   await dispatch(0)
   return result
 }
+
+/**
+ * Adds 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.
+ *
+ * @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.
+ *
+ * @throws {Error} If middleware for the tag already exists.
+ *
+ * @example
+ * ```typescript
+ * // Add admin middleware for admin endpoints
+ * addMiddleware('admin', [adminMiddleware])
+ *
+ * // Add authentication middleware for auth endpoints
+ * addMiddleware('auth', [authMiddleware])
+ *
+ * // Add logging middleware for all API endpoints
+ * addMiddleware('api', [loggingMiddleware])
+ * ```
+ */
+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[]
+}
+
+/**
+ * Retrieves middleware for a given set of tags.
+ *
+ * This function looks up all middleware registered for any of the provided tags
+ * and returns them as a flattened array.
+ *
+ * @param {string[]} tags - Array of tags to look up middleware for.
+ * @returns {CorePikkuMiddleware[]} Array of middleware functions that apply to the given tags.
+ *
+ * @example
+ * ```typescript
+ * // Get all middleware for tags 'api' and 'auth'
+ * const middleware = getMiddlewareForTags(['api', 'auth'])
+ * ```
+ */
+export const getMiddlewareForTags = (
+  tags?: string[]
+): CorePikkuMiddleware[] => {
+  if (!tags || tags.length === 0) {
+    return []
+  }
+
+  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
+}
+
+/**
+ * Combines tag-based middleware with wiring-specific middleware and 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.
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * const combined = combineMiddleware({
+ *   wiringMiddleware: httpRoute.middleware,
+ *   wiringTags: httpRoute.tags,
+ *   funcMiddleware: funcConfig.middleware,
+ *   funcTags: funcConfig.tags
+ * })
+ * ```
+ */
+export const combineMiddleware = ({
+  wiringMiddleware,
+  wiringTags,
+  funcMiddleware,
+  funcTags,
+}: {
+  wiringMiddleware?: CorePikkuMiddleware[]
+  wiringTags?: string[]
+  funcMiddleware?: CorePikkuMiddleware[]
+  funcTags?: string[]
+} = {}): CorePikkuMiddleware[] => {
+  // Run middleware in specific order:
+  // 1) wiringTags middleware
+  // 2) wiringMiddleware
+  // 3) funcMiddleware
+  // 4) funcTags middleware
+  const wiringTaggedMiddleware = getMiddlewareForTags(wiringTags)
+  const funcTaggedMiddleware = getMiddlewareForTags(funcTags)
+
+  return [
+    ...wiringTaggedMiddleware,
+    ...(wiringMiddleware || []),
+    ...(funcMiddleware || []),
+    ...funcTaggedMiddleware,
+  ]
+}