@pikku/core 0.12.4 → 0.12.6

package/src/wirings/http/http-routes.test.ts

@@ -0,0 +1,322 @@
+import { test, describe, beforeEach, afterEach } from 'node:test'
+import * as assert from 'assert'
+import { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { addFunction } from '../../function/function-runner.js'
+import { httpRouter } from './routers/http-router.js'
+import type { CorePikkuMiddleware } from '../../types/core.types.js'
+
+// Mock function for testing
+const mockFunc = async () => ({ success: true })
+
+// Mock middleware
+const mockMiddleware: CorePikkuMiddleware = async (_services, _wire, next) => {
+  await next()
+}
+
+// Helper to set up function metadata for routes
+const setupFunctionMeta = (
+  routes: Array<{ method: string; route: string }>
+) => {
+  const meta: Record<string, Record<string, any>> = {
+    get: {},
+    post: {},
+    delete: {},
+    patch: {},
+    head: {},
+    put: {},
+    options: {},
+  }
+
+  for (const { method, route } of routes) {
+    meta[method][route] = {
+      pikkuFuncId: `func_${route.replace(/[^a-z0-9]/gi, '_')}`,
+      route,
+      method,
+    }
+  }
+
+  pikkuState(null, 'http', 'meta', meta)
+
+  for (const { method, route } of routes) {
+    const funcName = `func_${route.replace(/[^a-z0-9]/gi, '_')}`
+    pikkuState(null, 'function', 'meta', {
+      [funcName]: {
+        pikkuFuncId: funcName,
+        services: [],
+      },
+    } as any)
+    addFunction(funcName, { func: mockFunc })
+  }
+}
+
+describe('defineHTTPRoutes', () => {
+  test('should accept routes directly', () => {
+    const routes = defineHTTPRoutes({
+      list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      get: { method: 'get', route: '/todos/:id', func: { func: mockFunc } },
+    })
+
+    assert.ok(routes.routes.list)
+    assert.ok(routes.routes.get)
+    assert.strictEqual(routes.routes.list.method, 'get')
+    assert.strictEqual(routes.routes.list.route, '/todos')
+  })
+
+  test('should accept config with routes', () => {
+    const routes = defineHTTPRoutes({
+      auth: true,
+      tags: ['todos'],
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    assert.strictEqual(routes.auth, true)
+    assert.deepStrictEqual(routes.tags, ['todos'])
+    assert.ok(routes.routes.list)
+  })
+
+  test('should handle basePath in config', () => {
+    const routes = defineHTTPRoutes({
+      basePath: '/api',
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    assert.strictEqual(routes.basePath, '/api')
+  })
+})
+
+describe('wireHTTPRoutes', () => {
+  beforeEach(() => {
+    resetPikkuState()
+    httpRouter.reset()
+  })
+
+  afterEach(() => {
+    resetPikkuState()
+    httpRouter.reset()
+  })
+
+  test('should wire flat array of routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'post', route: '/todos' },
+    ])
+
+    wireHTTPRoutes({
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        { method: 'post', route: '/todos', func: { func: mockFunc } },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('post')?.has('/todos'))
+  })
+
+  test('should wire nested object routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'get', route: '/todos/:id' },
+      { method: 'post', route: '/auth/login' },
+    ])
+
+    wireHTTPRoutes({
+      routes: {
+        todos: {
+          list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+          get: {
+            method: 'get',
+            route: '/todos/:id',
+            func: { func: mockFunc },
+          },
+        },
+        auth: {
+          login: {
+            method: 'post',
+            route: '/auth/login',
+            func: { func: mockFunc },
+          },
+        },
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('get')?.has('/todos/:id'))
+    assert.ok(routes.get('post')?.has('/auth/login'))
+  })
+
+  test('should apply basePath to all routes', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/api/v1/todos' },
+      { method: 'post', route: '/api/v1/todos' },
+    ])
+
+    wireHTTPRoutes({
+      basePath: '/api/v1',
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        { method: 'post', route: '/todos', func: { func: mockFunc } },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/api/v1/todos'))
+    assert.ok(routes.get('post')?.has('/api/v1/todos'))
+  })
+
+  test('should merge tags from group config and route config', () => {
+    setupFunctionMeta([{ method: 'get', route: '/todos' }])
+
+    wireHTTPRoutes({
+      tags: ['api'],
+      routes: [
+        {
+          method: 'get',
+          route: '/todos',
+          func: { func: mockFunc },
+          tags: ['todos'],
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/todos')
+    assert.deepStrictEqual(route?.tags, ['api', 'todos'])
+  })
+
+  test('should merge middleware from group config and route config', () => {
+    setupFunctionMeta([{ method: 'get', route: '/todos' }])
+
+    const groupMiddleware: CorePikkuMiddleware = async (_s, _w, next) => {
+      await next()
+    }
+    const routeMiddleware: CorePikkuMiddleware = async (_s, _w, next) => {
+      await next()
+    }
+
+    wireHTTPRoutes({
+      middleware: [groupMiddleware],
+      routes: [
+        {
+          method: 'get',
+          route: '/todos',
+          func: { func: mockFunc },
+          middleware: [routeMiddleware],
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/todos')
+    assert.strictEqual(route?.middleware?.length, 2)
+  })
+
+  test('should allow route auth to override group auth', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'post', route: '/auth/login' },
+    ])
+
+    wireHTTPRoutes({
+      auth: true,
+      routes: [
+        { method: 'get', route: '/todos', func: { func: mockFunc } },
+        {
+          method: 'post',
+          route: '/auth/login',
+          func: { func: mockFunc },
+          auth: false,
+        },
+      ],
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const todosRoute = routes.get('get')?.get('/todos')
+    const loginRoute = routes.get('post')?.get('/auth/login')
+
+    assert.strictEqual(todosRoute?.auth, true)
+    assert.strictEqual(loginRoute?.auth, false)
+  })
+
+  test('should wire routes from defineHTTPRoutes contracts', () => {
+    const todosRoutes = defineHTTPRoutes({
+      tags: ['todos'],
+      routes: {
+        list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+      },
+    })
+
+    setupFunctionMeta([{ method: 'get', route: '/api/todos' }])
+
+    wireHTTPRoutes({
+      basePath: '/api',
+      tags: ['api'],
+      routes: {
+        todos: todosRoutes,
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    const route = routes.get('get')?.get('/api/todos')
+    assert.ok(route)
+    assert.deepStrictEqual(route?.tags, ['api', 'todos'])
+  })
+
+  test('should cascade basePath from multiple levels', () => {
+    const todosRoutes = defineHTTPRoutes({
+      basePath: '/todos',
+      routes: {
+        list: { method: 'get', route: '', func: { func: mockFunc } },
+        get: { method: 'get', route: '/:id', func: { func: mockFunc } },
+      },
+    })
+
+    setupFunctionMeta([
+      { method: 'get', route: '/api/v1/todos' },
+      { method: 'get', route: '/api/v1/todos/:id' },
+    ])
+
+    wireHTTPRoutes({
+      basePath: '/api/v1',
+      routes: {
+        todos: todosRoutes,
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/api/v1/todos'))
+    assert.ok(routes.get('get')?.has('/api/v1/todos/:id'))
+  })
+
+  test('should handle deeply nested route maps', () => {
+    setupFunctionMeta([
+      { method: 'get', route: '/todos' },
+      { method: 'get', route: '/todos/:id' },
+    ])
+
+    wireHTTPRoutes({
+      routes: {
+        level1: {
+          level2: {
+            list: { method: 'get', route: '/todos', func: { func: mockFunc } },
+            get: {
+              method: 'get',
+              route: '/todos/:id',
+              func: { func: mockFunc },
+            },
+          },
+        },
+      },
+    })
+
+    const routes = pikkuState(null, 'http', 'routes')
+    assert.ok(routes.get('get')?.has('/todos'))
+    assert.ok(routes.get('get')?.has('/todos/:id'))
+  })
+})

package/src/wirings/http/http-routes.ts

@@ -0,0 +1,197 @@
+import type {
+  HTTPRouteConfig,
+  HTTPRouteMap,
+  HTTPRouteContract,
+  HTTPRoutesGroupConfig,
+  WireHTTPRoutesConfig,
+} from './http.types.js'
+import { wireHTTP } from './http-runner.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 function defineHTTPRoutes<T extends HTTPRouteMap>(
+  routes: T
+): HTTPRouteContract<T>
+export function defineHTTPRoutes<T extends HTTPRouteMap>(
+  config: HTTPRoutesGroupConfig & { routes: T }
+): HTTPRouteContract<T>
+export function defineHTTPRoutes<T extends HTTPRouteMap>(
+  configOrRoutes: T | (HTTPRoutesGroupConfig & { routes: T })
+): HTTPRouteContract<T> {
+  // 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 as HTTPRouteContract<T>
+  }
+  // Otherwise it's just routes
+  return { routes: configOrRoutes as 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 const wireHTTPRoutes = (config: WireHTTPRoutesConfig): void => {
+  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: HTTPRouteMap,
+  parentConfig: HTTPRoutesGroupConfig
+): void {
+  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 as HTTPRouteMap, 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: HTTPRoutesGroupConfig,
+  child: HTTPRoutesGroupConfig
+): HTTPRoutesGroupConfig {
+  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: HTTPRouteConfig,
+  groupConfig: HTTPRoutesGroupConfig
+): void {
+  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,
+    sse: route.sse,
+  } as any)
+}
+
+/**
+ * Type guard to check if a value is an individual route config
+ */
+function isRouteConfig(value: unknown): value is HTTPRouteConfig {
+  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: unknown): value is HTTPRouteContract {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'routes' in value &&
+    !('method' in value) &&
+    !('func' in value)
+  )
+}

package/src/wirings/http/http-runner.test.ts

@@ -0,0 +1,144 @@
+import { test, describe, beforeEach, afterEach } from 'node:test'
+import * as assert from 'assert'
+import { NotFoundError } from '../../errors/errors.js'
+import type { JSONValue, CorePikkuMiddleware } from '../../types/core.types.js'
+import { fetch, wireHTTP } from './http-runner.js'
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import {
+  PikkuMockRequest,
+  PikkuMockResponse,
+} from '../channel/local/local-channel-runner.test.js'
+import { addFunction } from '../../function/function-runner.js'
+import { httpRouter } from './routers/http-router.js'
+
+const sessionMiddleware: CorePikkuMiddleware = async (services, wire, next) => {
+  wire.setSession?.({ userId: 'test' } as any)
+  await next()
+}
+
+const setHTTPFunctionMap = (func: any) => {
+  pikkuState(null, 'function', 'meta', {
+    pikku_func_name: {
+      pikkuFuncId: 'pikku_func_name',
+      services: ['userSession'],
+    },
+  } as any)
+  pikkuState(null, 'http', 'meta', {
+    get: {
+      test: {
+        pikkuFuncId: 'pikku_func_name',
+        route: 'test',
+        method: 'get',
+      },
+    },
+    post: {},
+    delete: {},
+    patch: {},
+    head: {},
+    put: {},
+    options: {},
+  })
+  addFunction('pikku_func_name', { func })
+}
+
+describe('fetch', () => {
+  let request: any
+  let response: any
+
+  beforeEach(() => {
+    resetPikkuState()
+    httpRouter.reset()
+
+    const singletonServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      },
+    }
+
+    const createWireServices = async () => ({})
+
+    pikkuState(null, 'package', 'singletonServices', singletonServices as any)
+    pikkuState(null, 'package', 'factories', { createWireServices } as any)
+
+    request = new PikkuMockRequest('/test', 'get')
+    response = new PikkuMockResponse()
+
+    request.getData = async () => ({})
+    request.getHeader = (name: string) =>
+      name === 'content-type' ? 'application/json' : undefined
+    response.setStatus = (status: number) => {}
+    response.setJson = (json: JSONValue) => {}
+  })
+
+  afterEach(() => {})
+
+  test('should throw RouteNotFoundError when no matching route is found', async () => {
+    await assert.rejects(
+      async () =>
+        fetch(request, {
+          bubbleErrors: true,
+        }),
+      NotFoundError
+    )
+  })
+
+  test('should call the route function and return its result when a matching route is found', async () => {
+    const routeFunc = async () => ({ success: true })
+    setHTTPFunctionMap(routeFunc)
+
+    wireHTTP({
+      route: 'test',
+      method: 'get',
+      func: { func: routeFunc, middleware: [sessionMiddleware] },
+    })
+
+    // Initialize router after adding route (for tests)
+    httpRouter.initialize()
+
+    const result = await fetch(request)
+
+    assert.deepStrictEqual(await result.json(), { success: true })
+  })
+
+  test('should verify permissions if provided', async () => {
+    const permissions = { test: async () => true }
+    const routeFunc = async () => ({ success: true })
+    setHTTPFunctionMap(routeFunc)
+
+    wireHTTP({
+      route: 'test',
+      method: 'get',
+      func: {
+        func: routeFunc,
+        permissions,
+        middleware: [sessionMiddleware],
+      },
+    })
+
+    await fetch(request)
+
+    assert.strictEqual(await permissions.test(), true)
+  })
+
+  test('should handle errors and set appropriate response', async () => {
+    const error = new Error('Test error')
+    const routeFunc = async () => {
+      throw error
+    }
+    setHTTPFunctionMap(routeFunc)
+    wireHTTP({
+      route: 'test',
+      method: 'get',
+      func: { func: routeFunc, middleware: [sessionMiddleware] },
+    })
+    await assert.rejects(
+      async () =>
+        fetch(request, {
+          bubbleErrors: true,
+        }),
+      error
+    )
+  })
+})