@pikku/core 0.12.15 → 0.12.17

package/src/function/list.types.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Type-level tests for list-function primitives.
+ *
+ * No runtime assertions — the point is that valid shapes compile and
+ * invalid shapes fail with `@ts-expect-error`. The file is excluded
+ * from `yarn build` via tsconfig's `**∕*.test.ts` pattern.
+ */
+
+import type { ListInput, ListOutput, Filter } from './list.types.js'
+
+// -- ListInput ---------------------------------------------------------------
+
+type SessionFilter = {
+  status?: string[]
+  therapistId?: string
+  uploadedAt?: string
+}
+type SessionSort = 'user' | 'status' | 'uploaded_at'
+
+const _basic: ListInput<SessionFilter, SessionSort> = {
+  cursor: 'abc',
+  limit: 50,
+  sort: [
+    { column: 'uploaded_at', direction: 'desc' },
+    { column: 'status', direction: 'asc' },
+  ],
+  filter: { status: ['pending'] },
+  search: 'sarah',
+}
+void _basic
+
+const _empty: ListInput = {}
+void _empty
+
+// sort.column must be from the declared union
+// @ts-expect-error — 'created_at' is not in SessionSort
+const _badSort: ListInput<SessionFilter, SessionSort> = {
+  sort: [{ column: 'created_at', direction: 'asc' }],
+}
+void _badSort
+
+// sort.direction must be 'asc' or 'desc'
+// @ts-expect-error — 'descending' is not a valid direction
+const _badDirection: ListInput<SessionFilter, SessionSort> = {
+  sort: [{ column: 'user', direction: 'descending' }],
+}
+void _badDirection
+
+// -- ListOutput --------------------------------------------------------------
+
+interface Session {
+  id: string
+  user: string
+  status: string
+}
+
+const _output: ListOutput<Session> = {
+  rows: [{ id: '1', user: 'sarah', status: 'pending' }],
+  nextCursor: null,
+  totalCount: 42,
+}
+void _output
+
+// nextCursor is required (must be string or null, not undefined-only)
+// @ts-expect-error — missing nextCursor
+const _badOutput: ListOutput<Session> = {
+  rows: [],
+}
+void _badOutput
+
+// -- Filter: leaves ----------------------------------------------------------
+
+// Simple equality
+const _leafEq: Filter<SessionFilter> = { therapistId: 'kim' }
+void _leafEq
+
+// Array = IN shorthand
+const _leafIn: Filter<SessionFilter> = { status: ['pending', 'processed'] }
+void _leafIn
+
+// Operator object
+const _leafOp: Filter<SessionFilter> = {
+  uploadedAt: { gt: '2026-04-10', lte: '2026-04-17' },
+}
+void _leafOp
+
+// Null = IS NULL
+const _leafNull: Filter<SessionFilter> = { therapistId: null }
+void _leafNull
+
+// NOT on a value
+const _leafNot: Filter<SessionFilter> = { therapistId: { not: 'kim' } }
+void _leafNot
+
+// -- Filter: AND (array) -----------------------------------------------------
+
+const _and: Filter<SessionFilter> = [
+  { status: ['pending'] },
+  { therapistId: 'kim' },
+  { uploadedAt: { gt: '2026-04-10' } },
+]
+void _and
+
+// -- Filter: OR (object with arbitrary label keys) --------------------------
+
+const _or: Filter<SessionFilter> = {
+  viaKim: { therapistId: 'kim' },
+  viaPark: { therapistId: 'park' },
+}
+void _or
+
+// -- Filter: nested AND/OR ---------------------------------------------------
+
+const _nested: Filter<SessionFilter> = [
+  { status: ['pending'] },
+  {
+    kim: { therapistId: 'kim' },
+    park: { therapistId: 'park' },
+  },
+  { uploadedAt: { gt: '2026-04-10' } },
+]
+void _nested

package/src/function/list.types.ts

@@ -0,0 +1,121 @@
+/**
+ * List-function primitives.
+ *
+ * A "list function" is any Pikku function that returns a paginated
+ * collection. Adopting this shape unlocks a shared vocabulary across
+ * MCP tools, AI agents, typed RPC clients, and widget libraries — they
+ * all reason about cursor, filter, sort, and search uniformly.
+ *
+ * Under the hood, a list function is still a normal `pikkuFunc`. These
+ * types are purely structural constraints; no runtime behaviour change.
+ *
+ * @example
+ * ```ts
+ * import { pikkuFunc } from '#pikku'
+ * import type { ListInput, ListOutput } from '@pikku/core'
+ *
+ * export const listSessions = pikkuFunc<
+ *   ListInput<{ status?: SessionStatus[] }, 'user' | 'status' | 'uploaded_at'>,
+ *   ListOutput<Session>
+ * >({
+ *   func: async ({ kysely }, input) => {
+ *     // input.sort / input.filter / input.cursor / input.search are typed
+ *     return { rows, nextCursor, totalCount }
+ *   },
+ * })
+ * ```
+ */
+
+/**
+ * Shape every list function accepts as input.
+ *
+ * @template F - User-defined filter shape. Each key is a filterable field.
+ * @template S - String union of sortable column names.
+ */
+export interface ListInput<
+  F extends Record<string, unknown> = Record<string, never>,
+  S extends string = never,
+> {
+  /** Opaque cursor from the previous page's `nextCursor`. */
+  cursor?: string
+  /** Page size. Server may cap. */
+  limit?: number
+  /** Ordered sort criteria — first entry is primary. */
+  sort?: Array<{ column: S; direction: 'asc' | 'desc' }>
+  /** Structured filter tree. See {@link Filter}. */
+  filter?: Filter<F>
+  /** Unstructured text search across server-configured fields. */
+  search?: string
+}
+
+/**
+ * Shape every list function returns.
+ */
+export interface ListOutput<Row> {
+  rows: Row[]
+  /** Null when no more pages. */
+  nextCursor: string | null
+  /** Optional — backend may skip when expensive. */
+  totalCount?: number
+}
+
+/**
+ * Leaf predicate value on a single field.
+ *
+ * Operator keywords (`equals`, `not`, `in`, `notIn`, `gt`, `gte`, `lt`,
+ * `lte`, `contains`, `startsWith`, `endsWith`, `mode`) mirror Prisma's
+ * vocabulary for dev familiarity. These keys are reserved and cannot be
+ * used as user field names in a Filter's `F` type.
+ */
+export type LeafValue<T> =
+  | T
+  | null
+  | T[]
+  | {
+      equals?: T | null
+      not?: T | null | LeafValue<T>
+      in?: T[]
+      notIn?: T[]
+      gt?: T
+      gte?: T
+      lt?: T
+      lte?: T
+      contains?: string
+      startsWith?: string
+      endsWith?: string
+      mode?: 'sensitive' | 'insensitive'
+    }
+
+/**
+ * A single-key object keyed by a field name from F, value is a leaf
+ * predicate. Single-key so the runtime discriminator is unambiguous:
+ * multi-key objects are OR groups.
+ */
+export type LeafFilter<F extends Record<string, unknown>> = {
+  [K in keyof F]: { [Key in K]: LeafValue<F[K]> }
+}[keyof F]
+
+/**
+ * Recursive filter tree.
+ *
+ * - `Array<Filter<F>>` — AND of children.
+ * - `{ [label: string]: Filter<F> }` — OR of children. Keys are arbitrary
+ *   labels (unique strings), ignored at evaluation time.
+ * - `LeafFilter<F>` — single-key predicate on a declared field.
+ *
+ * @example "status = pending AND (therapist = kim OR therapist = park) AND uploaded_at > 2026-04-10"
+ * ```ts
+ * const filter: Filter<{ status: string; therapistId: string; uploadedAt: string }> = [
+ *   { status: 'pending' },
+ *   {
+ *     kim:  { therapistId: 'kim' },
+ *     park: { therapistId: 'park' },
+ *   },
+ *   { uploadedAt: { gt: '2026-04-10' } },
+ * ]
+ * ```
+ */
+export type Filter<F extends Record<string, unknown>> =
+  | LeafFilter<F>
+  | Filter<F>[]
+  | { [label: string]: Filter<F> }

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
   JSONValue,
   MakeRequired,
   MiddlewareMetadata,
+  MiddlewarePriority,
   PermissionMetadata,
   PickOptional,
   PickRequired,
@@ -58,6 +59,13 @@ export {
   pikkuApprovalDescription,
 } from './function/functions.types.js'
 export { addFunction, getAllFunctionNames } from './function/index.js'
+export type {
+  ListInput,
+  ListOutput,
+  Filter,
+  LeafFilter,
+  LeafValue,
+} from './function/list.types.js'
 export { PikkuRequest } from './pikku-request.js'
 export {
   getRelativeTimeOffsetFromNow,

package/src/middleware/index.ts

@@ -3,5 +3,6 @@ export { authCookie } from './auth-cookie.js'
 export { authBearer } from './auth-bearer.js'
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 export { cors } from './cors.js'
+export { telemetryOuter, telemetryInner } from './telemetry.js'
 export { addMiddleware, runMiddleware } from '../middleware-runner.js'
 export { addPermission } from '../permissions.js'

package/src/middleware/telemetry.ts

@@ -0,0 +1,110 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
+
+/**
+ * Outer telemetry middleware that captures total request duration and outcome.
+ * Runs at `highest` priority (outermost in the middleware chain).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Total duration (including all middleware)
+ * - Outcome (ok/error)
+ * - Wire metadata (wireType, wireId, traceId)
+ * - HTTP details (method, path, status) if applicable
+ *
+ * @example
+ * ```typescript
+ * import { telemetryOuter } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryOuter()])
+ * ```
+ */
+export const telemetryOuter = pikkuMiddlewareFactory<{
+  environmentId?: string
+  orgId?: string
+} | void>(({ environmentId, orgId } = {}) => {
+  return pikkuMiddleware({
+    name: 'telemetry-outer',
+    priority: 'highest',
+    func: async (services, wire, next) => {
+      const start = performance.now()
+      let outcome = 'ok'
+      let errorMessage: string | undefined
+      try {
+        await next()
+      } catch (e) {
+        outcome = 'error'
+        errorMessage = e instanceof Error ? e.message : String(e)
+        throw e
+      } finally {
+        services.logger.info({
+          __pikku_telemetry: 'end',
+          __pikku_layer: 'outer',
+          traceId: wire.traceId,
+          wireType: wire.wireType,
+          wireId: wire.wireId,
+          totalDuration: Math.round(performance.now() - start),
+          outcome,
+          ...(errorMessage ? { errorMessage } : {}),
+          ...(wire.http
+            ? {
+                httpStatus: wire.http.response?.statusCode,
+                httpMethod: wire.http.request?.method(),
+                httpPath: wire.http.request?.path(),
+              }
+            : {}),
+          ...(environmentId ? { environmentId } : {}),
+          ...(orgId ? { orgId } : {}),
+        })
+      }
+    },
+  })
+})
+
+/**
+ * Inner telemetry middleware that captures function execution duration and user context.
+ * Runs at `lowest` priority (innermost, closest to the function).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Function-only duration (excluding outer middleware like auth)
+ * - User identity (pikkuUserId) if authenticated
+ * - Wire metadata (wireType, wireId, traceId)
+ *
+ * @example
+ * ```typescript
+ * import { telemetryInner } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryInner()])
+ * ```
+ */
+export const telemetryInner = pikkuMiddlewareFactory<{
+  environmentId?: string
+  orgId?: string
+} | void>(({ environmentId, orgId } = {}) => {
+  return pikkuMiddleware({
+    name: 'telemetry-inner',
+    priority: 'lowest',
+    func: async (services, wire, next) => {
+      const start = performance.now()
+      let outcome = 'ok'
+      let errorMessage: string | undefined
+      try {
+        await next()
+      } catch (e) {
+        outcome = 'error'
+        errorMessage = e instanceof Error ? e.message : String(e)
+        throw e
+      } finally {
+        services.logger.info({
+          __pikku_telemetry: 'end',
+          __pikku_layer: 'inner',
+          traceId: wire.traceId,
+          wireType: wire.wireType,
+          wireId: wire.wireId,
+          functionDuration: Math.round(performance.now() - start),
+          outcome,
+          pikkuUserId: wire.pikkuUserId,
+          ...(errorMessage ? { errorMessage } : {}),
+          ...(environmentId ? { environmentId } : {}),
+          ...(orgId ? { orgId } : {}),
+        })
+      }
+    },
+  })
+})

package/src/middleware-runner.test.ts

@@ -6,7 +6,27 @@ import {
   runMiddleware,
 } from './middleware-runner.js'
 import { resetPikkuState } from './pikku-state.js'
-import type { CorePikkuMiddleware } from './types/core.types.js'
+import type {
+  CorePikkuMiddleware,
+  MiddlewarePriority,
+} from './types/core.types.js'
+import { pikkuMiddleware } from './types/core.types.js'
+
+const withPriority = (
+  name: string,
+  priority: MiddlewarePriority,
+  log: string[]
+): CorePikkuMiddleware => {
+  return pikkuMiddleware({
+    name,
+    priority,
+    func: async (_services, _wire, next) => {
+      log.push(`start:${name}`)
+      await next()
+      log.push(`end:${name}`)
+    },
+  })
+}
 
 beforeEach(() => {
   resetPikkuState()
@@ -329,6 +349,56 @@ describe('combineMiddleware', () => {
     assert.equal(result.length, 1)
     assert.equal(result[0], middleware)
   })
+
+  test('should sort middleware by priority', () => {
+    const log: string[] = []
+    const low = withPriority('low', 'low', log)
+    const highest = withPriority('highest', 'highest', log)
+    const medium = withPriority('medium', 'medium', log)
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [low, highest, medium],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], highest)
+    assert.equal(result[1], medium)
+    assert.equal(result[2], low)
+  })
+
+  test('should default unprioritized middleware to medium', () => {
+    const log: string[] = []
+    const highest = withPriority('highest', 'highest', log)
+    const lowest = withPriority('lowest', 'lowest', log)
+    const noPriority: CorePikkuMiddleware = async (_services, _wire, next) => {
+      await next()
+    }
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [lowest, noPriority, highest],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], highest)
+    assert.equal(result[1], noPriority) // defaults to medium
+    assert.equal(result[2], lowest)
+  })
+
+  test('should preserve registration order within same priority', () => {
+    const log: string[] = []
+    const first = withPriority('first', 'medium', log)
+    const second = withPriority('second', 'medium', log)
+    const third = withPriority('third', 'medium', log)
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [first, second, third],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], first)
+    assert.equal(result[1], second)
+    assert.equal(result[2], third)
+  })
 })
 
 describe('runMiddleware', () => {
@@ -415,4 +485,82 @@ describe('runMiddleware', () => {
 
     assert.deepEqual(executionOrder, ['middleware'])
   })
+
+  test('should execute middleware in priority order (highest first, lowest last)', async () => {
+    const log: string[] = []
+    const low = withPriority('low', 'low', log)
+    const highest = withPriority('highest', 'highest', log)
+    const medium = withPriority('medium', 'medium', log)
+
+    await runMiddleware(
+      {} as any,
+      {} as any,
+      [low, highest, medium],
+      async () => {
+        log.push('main')
+      }
+    )
+
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:medium',
+      'start:low',
+      'main',
+      'end:low',
+      'end:medium',
+      'end:highest',
+    ])
+  })
+
+  test('should sort unsorted middleware passed directly to runMiddleware', async () => {
+    const log: string[] = []
+    const lowest = withPriority('lowest', 'lowest', log)
+    const highest = withPriority('highest', 'highest', log)
+
+    await runMiddleware({} as any, {} as any, [lowest, highest], async () => {
+      log.push('main')
+    })
+
+    // highest should run first (outermost), lowest last (innermost)
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:lowest',
+      'main',
+      'end:lowest',
+      'end:highest',
+    ])
+  })
+
+  test('should handle all five priority levels in correct order', async () => {
+    const log: string[] = []
+    const lowest = withPriority('lowest', 'lowest', log)
+    const low = withPriority('low', 'low', log)
+    const medium = withPriority('medium', 'medium', log)
+    const high = withPriority('high', 'high', log)
+    const highest = withPriority('highest', 'highest', log)
+
+    // Pass in reverse order to verify sorting
+    await runMiddleware(
+      {} as any,
+      {} as any,
+      [lowest, low, medium, high, highest],
+      async () => {
+        log.push('main')
+      }
+    )
+
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:high',
+      'start:medium',
+      'start:low',
+      'start:lowest',
+      'main',
+      'end:lowest',
+      'end:low',
+      'end:medium',
+      'end:high',
+      'end:highest',
+    ])
+  })
 })

package/src/middleware-runner.ts

@@ -5,10 +5,34 @@ import type {
   CorePikkuMiddlewareGroup,
   PikkuWiringTypes,
   MiddlewareMetadata,
+  MiddlewarePriority,
 } from './types/core.types.js'
 import { pikkuState } from './pikku-state.js'
 import { freezeDedupe, getTagGroups } from './utils.js'
 
+const PRIORITY_ORDER: Record<MiddlewarePriority, number> = {
+  highest: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  lowest: 4,
+}
+
+const getMiddlewarePriority = (fn: CorePikkuMiddleware): number => {
+  const priority = (
+    fn as CorePikkuMiddleware & { __priority?: MiddlewarePriority }
+  ).__priority
+  return PRIORITY_ORDER[priority ?? 'medium']
+}
+
+const sortByPriority = (
+  middlewares: CorePikkuMiddleware[]
+): CorePikkuMiddleware[] => {
+  return middlewares.sort(
+    (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
+  )
+}
+
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *
@@ -32,11 +56,16 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   middlewares: readonly Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
-  // Deduplicate middleware using Set to avoid running the same middleware multiple times
+  // Sort by priority if not already sorted (cached middleware is pre-sorted)
+  const sorted = isSortedByPriority(middlewares)
+    ? middlewares
+    : ([...middlewares].sort(
+        (a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b)
+      ) as readonly Middleware[])
   let result: any
   const dispatch = async (index: number): Promise<any> => {
-    if (middlewares && index < middlewares.length) {
-      return await middlewares[index]!(services as any, wire, () =>
+    if (sorted && index < sorted.length) {
+      return await sorted[index]!(services as any, wire, () =>
         dispatch(index + 1)
       )
     } else if (main) {
@@ -47,6 +76,20 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   return result
 }
 
+const isSortedByPriority = (
+  middlewares: readonly CorePikkuMiddleware[]
+): boolean => {
+  for (let i = 1; i < middlewares.length; i++) {
+    if (
+      getMiddlewarePriority(middlewares[i]) <
+      getMiddlewarePriority(middlewares[i - 1])
+    ) {
+      return false
+    }
+  }
+  return true
+}
+
 /**
  * Registers global middleware for a specific tag.
  *
@@ -231,7 +274,8 @@ export const combineMiddleware = (
     resolved.push(...funcMiddleware)
   }
 
-  // Deduplicate and freeze
+  // Sort by priority, deduplicate, and freeze
+  sortByPriority(resolved)
   middlewareCache[wireType][uid] = freezeDedupe(
     resolved
   ) as readonly CorePikkuMiddleware[]

package/src/types/core.types.ts

@@ -305,6 +305,23 @@ export type CorePikkuMiddleware<
   next: () => Promise<void>
 ) => Promise<void>
 
+/**
+ * Priority levels for middleware execution order.
+ * Lower priority runs first (outermost in the onion model).
+ *
+ * - `highest` — Runs first (outermost). Use for telemetry, request tracing.
+ * - `high` — Runs early. Use for CORS, rate limiting.
+ * - `medium` — Default. Use for auth, most user middleware.
+ * - `low` — Runs late. Use for post-auth processing.
+ * - `lowest` — Runs last (innermost, closest to function). Use for inner telemetry.
+ */
+export type MiddlewarePriority =
+  | 'highest'
+  | 'high'
+  | 'medium'
+  | 'low'
+  | 'lowest'
+
 /**
  * Configuration object for creating middleware with metadata
  *
@@ -321,6 +338,8 @@ export type CorePikkuMiddlewareConfig<
   name?: string
   /** Optional description of what the middleware does */
   description?: string
+  /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
+  priority?: MiddlewarePriority
 }
 
 /**
@@ -378,7 +397,15 @@ export const pikkuMiddleware = <
     | CorePikkuMiddleware<SingletonServices, UserSession>
     | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
 ): CorePikkuMiddleware<SingletonServices, UserSession> => {
-  return typeof middleware === 'function' ? middleware : middleware.func
+  if (typeof middleware === 'function') return middleware
+  const func = middleware.func as CorePikkuMiddleware<
+    SingletonServices,
+    UserSession
+  > & { __priority?: MiddlewarePriority }
+  if (middleware.priority) {
+    func.__priority = middleware.priority
+  }
+  return func
 }
 
 /**

package/src/wirings/channel/local/local-channel-runner.test.ts

@@ -70,7 +70,11 @@ export class PikkuMockRequest implements PikkuHTTPRequest {
 }
 
 export class PikkuMockResponse implements PikkuHTTPResponse {
-  public _status: number | undefined
+  public _status: number = 200
+
+  public get statusCode(): number {
+    return this._status
+  }
 
   status(code: number): this {
     this._status = code