@pikku/core 0.10.2 → 0.11.1

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

@@ -1,13 +1,7 @@
 import { NotFoundError } from '../../errors/errors.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
-import {
-  CorePikkuMiddleware,
-  CoreUserSession,
-  SessionServices,
-  PikkuWiringTypes,
-} from '../../types/core.types.js'
-import { closeSessionServices } from '../../utils.js'
+import { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js'
 import {
   CoreCLI,
   CLICommandMeta,
@@ -20,14 +14,13 @@ import {
 import type {
   CoreSingletonServices,
   CoreServices,
-  CreateSessionServices,
-  PikkuInteraction,
+  CreateWireServices,
+  PikkuWire,
   CreateConfig,
   CreateSingletonServices,
 } from '../../types/core.types.js'
 import { PikkuChannel } from '../channel/channel.types.js'
-import { rpcService } from '../rpc/rpc-runner.js'
-import { PikkuUserSessionService } from '../../services/user-session-service.js'
+import { PikkuSessionService } from '../../services/user-session-service.js'
 import { LocalVariablesService } from '../../services/local-variables.js'
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js'
 
@@ -247,13 +240,13 @@ export async function runCLICommand({
   commandPath,
   data,
   singletonServices,
-  createSessionServices,
+  createWireServices,
 }: {
   program: string
   commandPath: string[]
   data: Record<string, any>
   singletonServices: CoreSingletonServices
-  createSessionServices?: CreateSessionServices
+  createWireServices?: CreateWireServices
 }): Promise<any> {
   // Get the command metadata to find the function name
   const cliMeta = pikkuState('cli', 'meta')
@@ -329,57 +322,31 @@ export async function runCLICommand({
     state: 'open',
   }
 
-  const userSession = new PikkuUserSessionService<CoreUserSession>()
-  let sessionServices: SessionServices | undefined
+  const userSession = new PikkuSessionService<CoreUserSession>()
 
-  const interaction: PikkuInteraction = {
+  const wire: PikkuWire = {
     cli: {
       program,
       command: commandPath,
       data: pluckedData,
       channel,
     },
-  }
-
-  const getAllServices = async (session?: CoreUserSession) => {
-    // Create session-specific services for handling the command
-    sessionServices = await createSessionServices?.(
-      singletonServices,
-      interaction,
-      session
-    )
-
-    return rpcService.injectRPCService(
-      {
-        ...singletonServices,
-        ...sessionServices,
-        userSession,
-        channel,
-      },
-      interaction,
-      false
-    )
+    session: userSession,
   }
 
   try {
-    const result = await runPikkuFunc(
-      PikkuWiringTypes.cli,
-      commandId,
-      funcName,
-      {
-        singletonServices,
-        getAllServices,
-        data: pluckedData,
-        auth: false,
-        userSession,
-        inheritedMiddleware: currentCommand.middleware,
-        wireMiddleware: allWireMiddleware,
-        inheritedPermissions: currentCommand.permissions,
-        wirePermissions: undefined,
-        tags: programData?.tags,
-        interaction,
-      }
-    )
+    const result = await runPikkuFunc('cli', commandId, funcName, {
+      singletonServices,
+      createWireServices,
+      data: pluckedData,
+      auth: false,
+      inheritedMiddleware: currentCommand.middleware,
+      wireMiddleware: allWireMiddleware,
+      inheritedPermissions: currentCommand.permissions,
+      wirePermissions: undefined,
+      tags: programData?.tags,
+      wire,
+    })
 
     // Apply renderer one final time with the final output (if renderer exists)
     if (renderer) {
@@ -392,11 +359,6 @@ export async function runCLICommand({
   } finally {
     // Close the channel
     channel.close()
-
-    // Clean up session services
-    if (sessionServices) {
-      await closeSessionServices(singletonServices.logger, sessionServices)
-    }
   }
 }
 
@@ -428,13 +390,13 @@ export async function executeCLI({
   args,
   createConfig,
   createSingletonServices,
-  createSessionServices,
+  createWireServices,
 }: {
   programName: string
   args?: string[]
   createConfig: CreateConfig<any, any>
   createSingletonServices: CreateSingletonServices<any, any>
-  createSessionServices?: CreateSessionServices<any, any, any>
+  createWireServices?: CreateWireServices<any, any, any>
 }): Promise<void> {
   if (!args) {
     throw new Error(
@@ -449,7 +411,7 @@ export async function executeCLI({
       | undefined
     if (!allCLIMeta) {
       throw new Error(
-        '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/errors/pku342 for more information.'
+        '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.'
       )
     }
     const programMeta = allCLIMeta.programs[programName]
@@ -518,7 +480,7 @@ export async function executeCLI({
       commandPath: parsed.commandPath,
       data,
       singletonServices,
-      createSessionServices,
+      createWireServices,
     })
   } catch (error: any) {
     // Re-throw CLIError as-is

package/src/wirings/cli/cli.types.ts

@@ -2,7 +2,6 @@ import {
   CorePikkuMiddleware,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuDocs,
   CoreServices,
   MiddlewareMetadata,
   PermissionMetadata,
@@ -44,7 +43,7 @@ export interface CLIPositional {
 }
 
 /**
- * CLI interaction context
+ * CLI wire context
  */
 export type PikkuCLI = {
   program: string
@@ -74,8 +73,9 @@ export interface CLICommandMeta {
   positionals: CLIPositional[]
   options: Record<string, CLIOption>
   renderName?: string
+  summary?: string
   description?: string
-  docs?: PikkuDocs
+  errors?: string[]
   tags?: string[]
   subcommands?: Record<string, CLICommandMeta>
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
@@ -131,8 +131,8 @@ export type CorePikkuCLIRender<
 export type ExtractFunctionInput<Func> =
   Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
-        | CorePikkuFunction<infer Input, any, any, any, any>
-        | CorePikkuFunctionSessionless<infer Input, any, any, any, any>
+        | CorePikkuFunction<infer Input, any, any, any>
+        | CorePikkuFunctionSessionless<infer Input, any, any, any>
       ? Input
       : never
     : never
@@ -198,8 +198,8 @@ export type ValidateParameters<Params extends string, Input> =
 export type ExtractFunctionOutput<Func> =
   Func extends CorePikkuFunctionConfig<infer FuncType, any, any>
     ? FuncType extends
-        | CorePikkuFunction<any, infer Output, any, any, any>
-        | CorePikkuFunctionSessionless<any, infer Output, any, any, any>
+        | CorePikkuFunction<any, infer Output, any, any>
+        | CorePikkuFunctionSessionless<any, infer Output, any, any>
       ? Output
       : never
     : never
@@ -210,7 +210,10 @@ export type ExtractFunctionOutput<Func> =
  */
 export type CoreCLICommandConfig<
   FuncConfig,
-  PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
   PikkuCLIRender extends CorePikkuCLIRender<any, any, any> = CorePikkuCLIRender<
     any,
     any
@@ -245,8 +248,8 @@ export interface CoreCLICommand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
+    | CorePikkuFunction<In, Out, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -264,7 +267,9 @@ export interface CoreCLICommand<
   middleware?: PikkuMiddleware[]
   permissions?: Record<string, PikkuPermission | PikkuPermission[]>
   auth?: boolean
-  docs?: PikkuDocs
+  summary?: string
+  errors?: string[]
+  tags?: string[]
   subcommands?: Subcommands
   isDefault?: boolean
 }
@@ -276,8 +281,8 @@ export type CLICommandShorthand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
+    | CorePikkuFunction<In, Out, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any>
   >,
 > = PikkuFunctionConfig
 
@@ -288,8 +293,8 @@ export type CLICommandDefinition<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any, any>
+    | CorePikkuFunction<In, Out, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -325,7 +330,8 @@ export interface CoreCLI<
   options?: CLIOptions<Options>
   middleware?: PikkuMiddleware[]
   render?: PikkuCLIRender
-  docs?: PikkuDocs
+  summary?: string
+  errors?: string[]
   tags?: string[]
 }
 

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

@@ -11,8 +11,8 @@ import {
 import { addFunction } from '../../function/function-runner.js'
 import { httpRouter } from './routers/http-router.js'
 
-const sessionMiddleware: CorePikkuMiddleware = async (services, _, next) => {
-  services.userSession.set({ userId: 'test' } as any)
+const sessionMiddleware: CorePikkuMiddleware = async (services, wire, next) => {
+  wire.session?.set({ userId: 'test' } as any)
   await next()
 }
 
@@ -43,7 +43,7 @@ const setHTTPFunctionMap = (func: any) => {
 
 describe('fetch', () => {
   let singletonServices: any
-  let createSessionServices: any
+  let createWireServices: any
   let request: any
   let response: any
 
@@ -59,7 +59,7 @@ describe('fetch', () => {
       },
     }
 
-    createSessionServices = async () => ({})
+    createWireServices = async () => ({})
     request = new PikkuMockRequest('/test', 'get')
     response = new PikkuMockResponse()
 
@@ -77,7 +77,7 @@ describe('fetch', () => {
       async () =>
         fetch(request, {
           singletonServices,
-          createSessionServices,
+          createWireServices,
           bubbleErrors: true,
         }),
       NotFoundError
@@ -99,7 +99,7 @@ describe('fetch', () => {
 
     const result = await fetch(request, {
       singletonServices,
-      createSessionServices,
+      createWireServices,
     })
 
     assert.deepStrictEqual(await result.json(), { success: true })
@@ -122,7 +122,7 @@ describe('fetch', () => {
 
     await fetch(request, {
       singletonServices,
-      createSessionServices,
+      createWireServices,
     })
 
     assert.strictEqual(await permissions.test(), true)
@@ -143,7 +143,7 @@ describe('fetch', () => {
       async () =>
         fetch(request, {
           singletonServices,
-          createSessionServices,
+          createWireServices,
           bubbleErrors: true,
         }),
       error

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

@@ -18,24 +18,23 @@ import {
   CoreUserSession,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
-  SessionServices,
+  WireServices,
+  PikkuWire,
   PikkuWiringTypes,
-  PikkuInteraction,
 } from '../../types/core.types.js'
 import { NotFoundError } from '../../errors/errors.js'
 import {
-  closeSessionServices,
+  closeWireServices,
   createWeakUID,
   isSerializable,
 } from '../../utils.js'
-import { PikkuUserSessionService } from '../../services/user-session-service.js'
+import { PikkuSessionService } from '../../services/user-session-service.js'
 import { handleHTTPError } from '../../handle-error.js'
 import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import { PikkuChannel } from '../channel/channel.types.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
-import { rpcService } from '../rpc/rpc-runner.js'
 import { httpRouter } from './routers/http-router.js'
 
 /**
@@ -203,16 +202,16 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
 }
 
 /**
- * Combines the request and response objects into a single HTTP interaction object.
+ * Combines the request and response objects into a single HTTP wire object.
  *
  * This utility function creates an object that holds both the HTTP request and response,
  * which simplifies passing these around through middleware and route execution.
  *
  * @param {PikkuHTTPRequest | undefined} request - The HTTP request object.
  * @param {PikkuHTTPResponse | undefined} response - The HTTP response object.
- * @returns {PikkuHTTP | undefined} The combined HTTP interaction object or undefined if none provided.
+ * @returns {PikkuHTTP | undefined} The combined HTTP wire object or undefined if none provided.
  */
-export const createHTTPInteraction = (
+export const createHTTPWire = (
   request: PikkuHTTPRequest | undefined,
   response: PikkuHTTPResponse | undefined
 ): PikkuHTTP | undefined => {
@@ -246,15 +245,15 @@ export const createHTTPInteraction = (
  *
  * @param {Object} services - A collection of shared services and utilities.
  * @param {Object} matchedRoute - Contains route details, URL parameters, and optional schema.
- * @param {PikkuHTTP | undefined} http - The HTTP interaction object.
+ * @param {PikkuHTTP | undefined} http - The HTTP wire object.
  * @param {Object} options - Options for route execution (e.g., whether to coerce query strings to arrays).
- * @returns {Promise<any>} An object containing the route handler result and session services (if any).
+ * @returns {Promise<any>} An object containing the route handler result and wire services (if any).
  * @throws Throws errors like MissingSessionError or ForbiddenError on validation failures.
  */
 const executeRoute = async (
   services: {
     singletonServices: any
-    createSessionServices: Function
+    createWireServices?: any
     skipUserSession: boolean
     requestId: string
   },
@@ -269,17 +268,13 @@ const executeRoute = async (
     coerceDataFromSchema: boolean
   }
 ) => {
-  const userSession = new PikkuUserSessionService<CoreUserSession>()
+  const userSession = new PikkuSessionService<CoreUserSession>()
   const { params, route, meta } = matchedRoute
-  const {
-    singletonServices,
-    createSessionServices,
-    skipUserSession,
-    requestId,
-  } = services
+  const { singletonServices, createWireServices, skipUserSession, requestId } =
+    services
 
   const requiresSession = route.auth !== false
-  let sessionServices: any
+  let wireServices: any
   let result: any
 
   // Attach URL parameters to the request object
@@ -324,38 +319,16 @@ const executeRoute = async (
     }
   }
 
-  const interaction: PikkuInteraction = { http, channel }
-
-  const getAllServices = async (session?: CoreUserSession) => {
-    // Create session-specific services for handling the request
-    sessionServices = await createSessionServices(
-      { ...singletonServices, userSession, channel },
-      { http },
-      session
-    )
-
-    return rpcService.injectRPCService(
-      {
-        ...singletonServices,
-        ...sessionServices,
-        http,
-        userSession,
-        channel,
-      },
-      interaction,
-      route.auth
-    )
-  }
+  const wire: PikkuWire = { http, channel, session: userSession }
 
   result = await runPikkuFunc(
-    PikkuWiringTypes.http,
+    'http',
     `${meta.method}:${meta.route}`,
     meta.pikkuFuncName,
     {
       singletonServices,
-      getAllServices,
+      createWireServices,
       auth: route.auth !== false,
-      userSession,
       data,
       inheritedMiddleware: meta.middleware,
       wireMiddleware: route.middleware,
@@ -363,7 +336,7 @@ const executeRoute = async (
       wirePermissions: route.permissions,
       coerceDataFromSchema: options.coerceDataFromSchema,
       tags: route.tags,
-      interaction,
+      wire,
     }
   )
 
@@ -378,7 +351,7 @@ const executeRoute = async (
   // TODO: Evaluate if the response stream should be explicitly ended.
   // http?.response?.end()
 
-  return sessionServices ? { result, sessionServices } : { result }
+  return wireServices ? { result, wireServices } : { result }
 }
 
 /**
@@ -431,11 +404,11 @@ export const pikkuFetch = async <In, Out>(
  * middleware execution, error handling, and session service cleanup.
  *
  * This function does the following:
- *  - Wraps the incoming request and response into an HTTP interaction object.
+ *  - Wraps the incoming request and response into an HTTP wire object.
  *  - Determines the correct route based on HTTP method and path.
  *  - Executes middleware and the route handler.
  *  - Catches and handles errors, optionally bubbling them if configured.
- *  - Cleans up any session services created during processing.
+ *  - Cleans up any wire services created during processing.
  *
  * @template In Expected input data type.
  * @template Out Expected output data type.
@@ -449,7 +422,7 @@ export const fetchData = async <In, Out>(
   response: PikkuHTTPResponse,
   {
     singletonServices,
-    createSessionServices,
+    createWireServices,
     skipUserSession = false,
     respondWith404 = true,
     logWarningsForStatusCodes = [],
@@ -462,11 +435,11 @@ export const fetchData = async <In, Out>(
     (request as any).getHeader?.('x-request-id') ||
     generateRequestId?.() ||
     createWeakUID()
-  let sessionServices: SessionServices<typeof singletonServices> | undefined
+  let wireServices: WireServices<typeof singletonServices> | undefined
   let result: Out
 
-  // Combine the request and response into one interaction object
-  const http = createHTTPInteraction(
+  // Combine the request and response into one wire object
+  const http = createHTTPWire(
     request instanceof Request ? new PikkuFetchHTTPRequest(request) : request,
     response
   )
@@ -487,10 +460,10 @@ export const fetchData = async <In, Out>(
     }
 
     // Execute the matched route along with its middleware and session management
-    ;({ result, sessionServices } = await executeRoute(
+    ;({ result, wireServices } = await executeRoute(
       {
         singletonServices,
-        createSessionServices,
+        createWireServices,
         skipUserSession,
         requestId,
       },
@@ -513,8 +486,8 @@ export const fetchData = async <In, Out>(
     )
   } finally {
     // Clean up any session-specific services created during processing
-    if (sessionServices) {
-      await closeSessionServices(singletonServices.logger, sessionServices)
+    if (wireServices) {
+      await closeWireServices(singletonServices.logger, wireServices)
     }
   }
 }

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

@@ -1,14 +1,12 @@
 import type { SerializeOptions } from 'cookie'
 import type { PikkuError } from '../../errors/error-handler.js'
 import type {
-  PikkuDocs,
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
-  CreateSessionServices,
+  CreateWireServices,
   CorePikkuMiddleware,
-  MiddlewareMetadata,
-  PermissionMetadata,
+  CommonWireMeta,
 } from '../../types/core.types.js'
 import type {
   CorePikkuFunction,
@@ -46,7 +44,7 @@ export type RunHTTPWiringOptions = Partial<{
 
 export type RunHTTPWiringParams = {
   singletonServices: CoreSingletonServices
-  createSessionServices: CreateSessionServices<
+  createWireServices: CreateWireServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
     CoreUserSession
@@ -83,7 +81,7 @@ export type CoreHTTPFunction = {
   }>
 }
 /**
- * Represents a http interaction within Pikku, including a request and response.
+ * Represents a http wire within Pikku, including a request and response.
  */
 export interface PikkuHTTP<In = unknown> {
   request?: PikkuHTTPRequest<In>
@@ -123,14 +121,12 @@ export type CoreHTTPFunctionWiring<
     In,
     Out,
     any,
-    any,
     any
   > = CorePikkuFunction<In, Out>,
   PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
     In,
     Out,
     any,
-    any,
     any
   > = CorePikkuFunctionSessionless<In, Out>,
   PikkuPermission extends CorePikkuPermission<
@@ -242,18 +238,13 @@ export type HTTPFunctionMetaInputTypes = {
 /**
  * Represents metadata for a set of HTTP wirings, including HTTP wiring details, methods, input/output types, and documentation.
  */
-export type HTTPWiringMeta = {
-  pikkuFuncName: string
+export type HTTPWiringMeta = CommonWireMeta & {
   route: string
   method: HTTPMethod
   params?: string[]
   query?: string[]
   inputTypes?: HTTPFunctionMetaInputTypes
-  docs?: PikkuDocs
-  tags?: string[]
   sse?: true
-  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (global + route + tag + explicit)
-  permissions?: PermissionMetadata[] // Pre-resolved permission chain (global + route + tag + explicit)
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>