@pikku/core 0.9.1 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -34,16 +34,16 @@
     "./types": "./dist/types/index.d.ts"
   },
   "dependencies": {
-    "@types/cookie": "^0.6.0",
+    "@types/cookie": "^1.0.0",
     "@types/uuid": "^10.0.0",
-    "cookie": "^1.0.1",
+    "cookie": "^1.0.2",
     "path-to-regexp": "^8.2.0",
-    "picoquery": "^2.4.0"
+    "picoquery": "^2.5.0"
   },
   "devDependencies": {
-    "@types/node": "^22.7.8",
-    "tsx": "^4.19.2",
-    "typescript": "^5.6"
+    "@types/node": "^24.2.1",
+    "tsx": "^4.20.4",
+    "typescript": "^5.9"
   },
   "engines": {
     "node": ">=18"

package/src/function/function-runner.ts

@@ -6,17 +6,25 @@ import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
 import {
   CoreServices,
   CoreUserSession,
-  PikkuFunctionMiddleware,
+  CorePikkuMiddleware,
 } from '../types/core.types.js'
 import {
   CorePermissionGroup,
+  CorePikkuFunction,
   CorePikkuFunctionConfig,
+  CorePikkuFunctionSessionless,
 } from './functions.types.js'
 
 export const addFunction = (
   funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>
+  funcConfig:
+    | CorePikkuFunctionConfig<any, any>
+    | CorePikkuFunctionSessionless<any, any>
+    | CorePikkuFunction<any, any>
 ) => {
+  if (funcConfig instanceof Function) {
+    funcConfig = { func: funcConfig }
+  }
   pikkuState('function', 'functions').set(funcName, funcConfig)
 }
 
@@ -47,7 +55,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     data: In
     session?: CoreUserSession
     permissions?: CorePermissionGroup
-    middleware?: PikkuFunctionMiddleware[]
+    middleware?: CorePikkuMiddleware[]
     coerceDataFromSchema?: boolean
   }
 ): Promise<Out> => {
@@ -68,18 +76,18 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   const allServices = await getAllServices()
 
-  const schemaName = funcMeta.schemaName
-  if (schemaName) {
+  const inputSchemaName = funcMeta.inputSchemaName
+  if (inputSchemaName) {
     // Validate request data against the defined schema, if any
     await validateSchema(
       allServices.logger,
       allServices.schema,
-      schemaName,
+      inputSchemaName,
       data
     )
     // Coerce (top level) query string parameters or date objects if specified by the schema
     if (coerceDataFromSchema) {
-      coerceTopLevelDataFromSchema(schemaName, data)
+      coerceTopLevelDataFromSchema(inputSchemaName, data)
     }
   }
 
@@ -106,7 +114,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
   }
 
   if (transportMiddleware || funcConfig.middleware) {
-    return (await runMiddleware<PikkuFunctionMiddleware>(
+    return (await runMiddleware<CorePikkuMiddleware>(
       allServices,
       {
         http: allServices.http,

package/src/function/functions.types.ts

@@ -3,7 +3,8 @@ import type {
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuFunctionMiddleware,
+  PikkuDocs,
+  CorePikkuMiddleware,
 } from '../types/core.types.js'
 
 /**
@@ -79,12 +80,19 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
 
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
-    | CorePikkuFunction<any, any>
-    | CorePikkuFunctionSessionless<any, any>,
-  PikkuPermission extends CorePikkuPermission<any> = CorePikkuPermission<any>,
+    | CorePikkuFunction<any, any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any, any>,
+  PikkuPermission extends CorePikkuPermission<
+    any,
+    any,
+    any
+  > = CorePikkuPermission<any>,
 > = {
+  name?: string
+  expose?: boolean
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
-  middleware?: PikkuFunctionMiddleware[]
+  middleware?: CorePikkuMiddleware[]
+  docs?: PikkuDocs
 }

package/src/index.ts

@@ -22,7 +22,7 @@ export * from './time-utils.js'
 export * from './utils.js'
 export { pikkuState } from './pikku-state.js'
 export { runMiddleware } from './middleware-runner.js'
-export { wireHTTP, addMiddleware } from './wirings/http/http-runner.js'
+export { wireHTTP, addHTTPMiddleware } from './wirings/http/http-runner.js'
 export { wireChannel } from './wirings/channel/channel-runner.js'
 export { wireScheduler } from './wirings/scheduler/scheduler-runner.js'
 export { wireQueueWorker } from './wirings/queue/queue-runner.js'

package/src/middleware/auth-apikey.ts

@@ -2,7 +2,7 @@ import {
   CoreConfig,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuMiddleware,
+  CorePikkuMiddleware,
 } from '../types/core.types.js'
 
 /**
@@ -32,7 +32,7 @@ export const authAPIKey = <
       jwt?: false
     }
 )) => {
-  const middleware: PikkuMiddleware = async (services, { http }, next) => {
+  const middleware: CorePikkuMiddleware = async (services, { http }, next) => {
     const { userSession: userSessionService, jwt: jwtService } = services as any
     if (!http?.request || userSessionService.get()) {
       return next()

package/src/middleware/auth-bearer.ts

@@ -3,7 +3,7 @@ import {
   CoreConfig,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuMiddleware,
+  CorePikkuMiddleware,
 } from '../types/core.types.js'
 
 /**
@@ -26,8 +26,8 @@ export const authBearer = <
     services: SingletonServices,
     token: string
   ) => Promise<UserSession> | UserSession
-} = {}): PikkuMiddleware => {
-  const middleware: PikkuMiddleware = async (services, { http }, next) => {
+} = {}): CorePikkuMiddleware => {
+  const middleware: CorePikkuMiddleware = async (services, { http }, next) => {
     const { userSession: userSessionService, jwt: jwtService } = services as any
     // Skip if session already exists.
     if (!http?.request || userSessionService.get()) {

package/src/middleware/auth-cookie.ts

@@ -3,7 +3,7 @@ import {
   CoreConfig,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuMiddleware,
+  CorePikkuMiddleware,
 } from '../types/core.types.js'
 import {
   getRelativeTimeOffsetFromNow,
@@ -42,8 +42,8 @@ export const authCookie = <
       getSessionForCookieValue?: undefined
       jwt: true
     }
-)): PikkuMiddleware => {
-  const middleware: PikkuMiddleware = async (services, { http }, next) => {
+)): CorePikkuMiddleware => {
+  const middleware: CorePikkuMiddleware = async (services, { http }, next) => {
     const {
       userSession: userSessionService,
       jwt: jwtService,

package/src/middleware/timeout.ts

@@ -1,8 +1,12 @@
 import { RequestTimeoutError } from '../errors/errors.js'
-import { PikkuMiddleware } from '../types/core.types.js'
+import { CorePikkuMiddleware } from '../types/core.types.js'
 
 export const timeout = (timeout: number) => {
-  const middleware: PikkuMiddleware = async (_services, _interaction, next) => {
+  const middleware: CorePikkuMiddleware = async (
+    _services,
+    _interaction,
+    next
+  ) => {
     setTimeout(() => {
       throw new RequestTimeoutError()
     }, timeout)

package/src/middleware-runner.ts

@@ -1,9 +1,8 @@
 import { UserSessionService } from './services/user-session-service.js'
 import {
   CoreSingletonServices,
-  PikkuFunctionMiddleware,
   PikkuInteraction,
-  PikkuMiddleware,
+  CorePikkuMiddleware,
 } from './types/core.types.js'
 
 /**
@@ -23,11 +22,7 @@ import {
  *   async () => { return await runMain(); }
  * );
  */
-export const runMiddleware = async <
-  Middleware extends
-    | PikkuMiddleware
-    | PikkuFunctionMiddleware = PikkuMiddleware,
->(
+export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   services: CoreSingletonServices & {
     userSession?: UserSessionService<any>
   },

package/src/pikku-state.ts

@@ -4,14 +4,13 @@ import {
   HTTPMethod,
   HTTPWiringsMeta,
 } from './wirings/http/http.types.js'
-import { FunctionsMeta, PikkuMiddleware } from './types/core.types.js'
+import { FunctionsMeta, CorePikkuMiddleware } from './types/core.types.js'
 import {
   CoreScheduledTask,
   ScheduledTasksMeta,
 } from './wirings/scheduler/scheduler.types.js'
 import { ErrorDetails, PikkuError } from './errors/error-handler.js'
 import { CorePikkuFunctionConfig } from './function/functions.types.js'
-import { RPCMeta } from './wirings/rpc/rpc-types.js'
 import {
   queueWorkersMeta,
   CoreQueueWorker,
@@ -31,7 +30,7 @@ interface PikkuState {
     functions: Map<string, CorePikkuFunctionConfig<any, any>>
   }
   rpc: {
-    meta: Record<string, RPCMeta>
+    meta: Record<string, string>
     files: Map<
       string,
       {
@@ -41,7 +40,7 @@ interface PikkuState {
     >
   }
   http: {
-    middleware: Array<{ route: string; middleware: PikkuMiddleware[] }>
+    middleware: Array<{ route: string; middleware: CorePikkuMiddleware[] }>
     routes: Map<HTTPMethod, Map<string, CoreHTTPFunctionWiring<any, any, any>>>
     meta: HTTPWiringsMeta
   }

package/src/types/core.types.ts

@@ -21,17 +21,28 @@ export interface FunctionServicesMeta {
   services: string[]
 }
 
-export type FunctionsMeta = Record<
-  string,
-  {
-    pikkuFuncName: string
-    name?: string
+export type FunctionRuntimeMeta = {
+  pikkuFuncName: string
+  inputSchemaName: string | null
+  outputSchemaName: string | null
+  expose?: boolean
+}
+
+export type FunctionMeta = FunctionRuntimeMeta &
+  Partial<{
+    name: string
     services: FunctionServicesMeta
-    schemaName: string | null
     inputs: string[] | null
     outputs: string[] | null
-  }
->
+    tags: string[]
+    docs: PikkuDocs
+    isDirectFunction: boolean // true if it's pikkuFunc(fn), false if it's pikkuFunc({ func: fn })
+  }>
+
+export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
+export type FunctionsMeta = Record<string, FunctionMeta>
+
+// Optimized runtime metadata with only essential fields
 
 export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
   Required<Pick<T, K>>
@@ -110,21 +121,7 @@ export interface PikkuInteraction {
 /**
  * A function that can wrap an interaction and be called before or after
  */
-export type PikkuFunctionMiddleware<
-  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
-  UserSession extends CoreUserSession = CoreUserSession,
-> = (
-  services: SingletonServices & {
-    userSession?: UserSessionService<UserSession>
-  },
-  interactions: PikkuInteraction,
-  next: () => Promise<void>
-) => Promise<void>
-
-/**
- * A function that can wrap an interaction and be called before or after
- */
-export type PikkuMiddleware<
+export type CorePikkuMiddleware<
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   UserSession extends CoreUserSession = CoreUserSession,
 > = (
@@ -190,7 +187,7 @@ export type CreateConfig<Config extends CoreConfig> = (
 /**
  * Represents the documentation for a route, including summary, description, tags, and errors.
  */
-export type APIDocs = {
+export type PikkuDocs = {
   summary?: string
   description?: string
   tags?: string[]

package/src/wirings/channel/channel.types.ts

@@ -5,10 +5,10 @@ import {
   PikkuHTTPResponse,
 } from '../http/http.types.js'
 import {
-  APIDocs,
+  PikkuDocs,
   CoreSingletonServices,
   CreateSessionServices,
-  PikkuMiddleware,
+  CorePikkuMiddleware,
 } from '../../types/core.types.js'
 import {
   CorePikkuFunction,
@@ -34,7 +34,7 @@ export type RunChannelParams<ChannelData> = {
 
 export interface ChannelMessageMeta {
   pikkuFuncName: string
-  docs?: APIDocs
+  docs?: PikkuDocs
 }
 
 export interface ChannelMeta {
@@ -48,7 +48,7 @@ export interface ChannelMeta {
   disconnect: ChannelMessageMeta | null
   message: ChannelMessageMeta | null
   messageWirings: Record<string, Record<string, ChannelMessageMeta>>
-  docs?: APIDocs
+  docs?: PikkuDocs
   tags?: string[]
 }
 
@@ -91,7 +91,7 @@ export type CoreChannel<
         }
     >
   >
-  middleware?: PikkuMiddleware[]
+  middleware?: CorePikkuMiddleware[]
   permissions?: Record<string, PikkuPermission[] | PikkuPermission>
   auth?: boolean
   docs?: Partial<{

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

@@ -1,7 +1,7 @@
 import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
 import { NotFoundError } from '../../errors/errors.js'
-import { JSONValue, PikkuMiddleware } from '../../types/core.types.js'
+import { JSONValue, CorePikkuMiddleware } from '../../types/core.types.js'
 import { fetch, wireHTTP } from './http-runner.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import {
@@ -10,7 +10,7 @@ import {
 } from '../channel/local/local-channel-runner.test.js'
 import { addFunction } from '../../function/function-runner.js'
 
-const sessionMiddleware: PikkuMiddleware = async (services, _, next) => {
+const sessionMiddleware: CorePikkuMiddleware = async (services, _, next) => {
   services.userSession.set({ userId: 'test' } as any)
   await next()
 }

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

@@ -10,7 +10,7 @@ import {
 } from './http.types.js'
 import {
   CoreUserSession,
-  PikkuMiddleware,
+  CorePikkuMiddleware,
   SessionServices,
 } from '../../types/core.types.js'
 import { match } from 'path-to-regexp'
@@ -40,13 +40,13 @@ import { rpcService } from '../rpc/rpc-runner.js'
  * is applied only to that route. Otherwise, if an array is provided, it is treated
  * as global middleware (applied to all routes).
  *
- * @template APIMiddleware The middleware type.
- * @param {APIMiddleware[] | string} routeOrMiddleware - Either a global middleware array or a route pattern string.
- * @param {APIMiddleware[]} [middleware] - The middleware array to apply when a route pattern is specified.
+ * @template PikkuMiddleware The middleware type.
+ * @param {PikkuMiddleware[] | string} routeOrMiddleware - Either a global middleware array or a route pattern string.
+ * @param {PikkuMiddleware[]} [middleware] - The middleware array to apply when a route pattern is specified.
  */
-export const addMiddleware = <APIMiddleware extends PikkuMiddleware>(
-  routeOrMiddleware: APIMiddleware[] | string,
-  middleware?: APIMiddleware[]
+export const addHTTPMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
+  routeOrMiddleware: PikkuMiddleware[] | string,
+  middleware?: PikkuMiddleware[]
 ) => {
   const middlewareStore = pikkuState('http', 'middleware')
 
@@ -90,8 +90,8 @@ export const addMiddleware = <APIMiddleware extends PikkuMiddleware>(
  * @template PikkuFunction Type for the route handler function.
  * @template PikkuFunctionSessionless Type for a sessionless handler.
  * @template PikkuPermissionGroup Type representing required permissions.
- * @template APIMiddleware Middleware type to be used with the route.
- * @param {CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, APIMiddleware>} httpWiring - The HTTP wiring configuration object.
+ * @template PikkuMiddleware Middleware type to be used with the route.
+ * @param {CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>} httpWiring - The HTTP wiring configuration object.
  */
 export const wireHTTP = <
   In,
@@ -100,7 +100,7 @@ export const wireHTTP = <
   PikkuFunction,
   PikkuFunctionSessionless,
   PikkuPermissionGroup,
-  APIMiddleware,
+  PikkuMiddleware,
 >(
   httpWiring: CoreHTTPFunctionWiring<
     In,
@@ -109,7 +109,7 @@ export const wireHTTP = <
     PikkuFunction,
     PikkuFunctionSessionless,
     PikkuPermissionGroup,
-    APIMiddleware
+    PikkuMiddleware
   >
 ) => {
   const httpMeta = pikkuState('http', 'meta')
@@ -120,9 +120,7 @@ export const wireHTTP = <
   if (!routeMeta) {
     throw new Error('Route metadata not found')
   }
-  addFunction(routeMeta.pikkuFuncName, {
-    func: httpWiring.func,
-  })
+  addFunction(routeMeta.pikkuFuncName, httpWiring.func as any)
   const routes = pikkuState('http', 'routes')
   if (!routes.has(httpWiring.method)) {
     routes.set(httpWiring.method, new Map())

package/src/wirings/http/http.types.ts

@@ -1,12 +1,12 @@
 import type { SerializeOptions } from 'cookie'
 import type { PikkuError } from '../../errors/error-handler.js'
 import type {
-  APIDocs,
+  PikkuDocs,
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
   CreateSessionServices,
-  PikkuMiddleware,
+  CorePikkuMiddleware,
 } from '../../types/core.types.js'
 import type {
   CorePikkuFunction,
@@ -119,7 +119,7 @@ export type CoreHTTPFunctionWiring<
   PikkuFunction = CorePikkuFunction<In, Out>,
   PikkuFunctionSessionless = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission = CorePikkuPermission<In>,
-  APIMiddleware = PikkuMiddleware,
+  PikkuMiddleware = CorePikkuMiddleware,
 > =
   | (CoreHTTPFunction & {
       route: R
@@ -128,7 +128,7 @@ export type CoreHTTPFunctionWiring<
       permissions?: CorePermissionGroup<PikkuPermission>
       auth?: true
       tags?: string[]
-      middleware?: APIMiddleware[]
+      middleware?: PikkuMiddleware[]
       sse?: undefined
     })
   | (CoreHTTPFunction & {
@@ -138,7 +138,7 @@ export type CoreHTTPFunctionWiring<
       permissions?: undefined
       auth?: false
       tags?: string[]
-      middleware?: APIMiddleware[]
+      middleware?: PikkuMiddleware[]
       sse?: undefined
     })
   | (CoreHTTPFunction & {
@@ -149,7 +149,7 @@ export type CoreHTTPFunctionWiring<
       auth?: true
       sse?: boolean
       tags?: string[]
-      middleware?: APIMiddleware[]
+      middleware?: PikkuMiddleware[]
     })
   | (CoreHTTPFunction & {
       route: R
@@ -159,7 +159,7 @@ export type CoreHTTPFunctionWiring<
       auth?: false
       sse?: boolean
       tags?: string[]
-      middleware?: APIMiddleware[]
+      middleware?: PikkuMiddleware[]
     })
   | (CoreHTTPFunction & {
       route: R
@@ -169,7 +169,7 @@ export type CoreHTTPFunctionWiring<
       auth?: true
       query?: Array<keyof In>
       tags?: string[]
-      middleware?: APIMiddleware[]
+      middleware?: PikkuMiddleware[]
       sse?: undefined
     })
   | (CoreHTTPFunction & {
@@ -180,7 +180,7 @@ export type CoreHTTPFunctionWiring<
       auth?: false
       query?: Array<keyof In>
       tags?: string[]
-      middleware?: APIMiddleware[]
+      middleware?: PikkuMiddleware[]
       sse?: undefined
     })
 
@@ -203,7 +203,7 @@ export type HTTPWiringMeta = {
   params?: string[]
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
-  docs?: APIDocs
+  docs?: PikkuDocs
   tags?: string[]
   sse?: true
 }
@@ -217,7 +217,7 @@ export type HTTPFunctionsMeta = Array<{
 
 export type HTTPWiringMiddleware = {
   route: string
-  middleware: PikkuMiddleware[]
+  middleware: CorePikkuMiddleware[]
 }
 
 export interface PikkuHTTPRequest<In = unknown> {

package/src/wirings/mcp/mcp-runner.ts

@@ -56,9 +56,7 @@ export const wireMCPResource = <
   if (!mcpResourceMeta) {
     throw new Error(`MCP resource metadata not found for '${mcpResource.uri}'`)
   }
-  addFunction(mcpResourceMeta.pikkuFuncName, {
-    func: mcpResource.func,
-  })
+  addFunction(mcpResourceMeta.pikkuFuncName, mcpResource.func)
   const resources = pikkuState('mcp', 'resources')
   if (resources.has(mcpResource.uri)) {
     throw new Error(`MCP resource already exists: ${mcpResource.uri}`)
@@ -76,9 +74,7 @@ export const wireMCPTool = <
   if (!mcpToolMeta) {
     throw new Error(`MCP tool metadata not found for '${mcpTool.name}'`)
   }
-  addFunction(mcpToolMeta.pikkuFuncName, {
-    func: mcpTool.func,
-  })
+  addFunction(mcpToolMeta.pikkuFuncName, mcpTool.func as any)
   const tools = pikkuState('mcp', 'tools')
   if (tools.has(mcpTool.name)) {
     throw new Error(`MCP tool already exists: ${mcpTool.name}`)
@@ -96,9 +92,7 @@ export const wireMCPPrompt = <
   if (!mcpPromptMeta) {
     throw new Error(`MCP prompt metadata not found for '${mcpPrompt.name}'`)
   }
-  addFunction(mcpPromptMeta.pikkuFuncName, {
-    func: mcpPrompt.func,
-  })
+  addFunction(mcpPromptMeta.pikkuFuncName, mcpPrompt.func as any)
   const prompts = pikkuState('mcp', 'prompts')
   if (prompts.has(mcpPrompt.name)) {
     throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`)

package/src/wirings/queue/queue-runner.ts

@@ -37,9 +37,7 @@ export const wireQueueWorker = <
   }
 
   // Register the function with pikku
-  addFunction(processorMeta.pikkuFuncName, {
-    func: queueWorker.func,
-  })
+  addFunction(processorMeta.pikkuFuncName, queueWorker.func)
 
   // Store processor definition in state - runtime adapters will pick this up
   const registrations = pikkuState('queue', 'registrations')

package/src/wirings/queue/queue.types.ts

@@ -1,4 +1,4 @@
-import { APIDocs } from '../../types/core.types.js'
+import { PikkuDocs } from '../../types/core.types.js'
 import { CorePikkuFunctionSessionless } from '../../function/functions.types.js'
 import { QueueConfigMapping } from './validate-worker-config.js'
 
@@ -155,7 +155,7 @@ export type queueWorkersMeta = Record<
     schemaName?: string
     queueName: string
     session?: undefined
-    docs?: APIDocs
+    docs?: PikkuDocs
     tags?: string[]
     config?: PikkuWorkerConfig
   }
@@ -170,7 +170,7 @@ export type CoreQueueWorker<
   queueName: string
   func: PikkuFunction
   config?: PikkuWorkerConfig
-  docs?: APIDocs
+  docs?: PikkuDocs
   session?: undefined
   tags?: string[]
 }