@pikku/core 0.11.2 → 0.12.0

package/src/wirings/channel/index.ts

@@ -1,8 +1,23 @@
-export * from './channel-runner.js'
-export * from './channel.types.js'
-export * from './log-channels.js'
-export * from './pikku-abstract-channel-handler.js'
-export * from './eventhub-service.js'
-export * from './eventhub-service.js'
-export * from './channel-store.js'
-export * from './eventhub-store.js'
+export { wireChannel, openChannel } from './channel-runner.js'
+export {
+  addChannelMiddleware,
+  combineChannelMiddleware,
+  wrapChannelWithMiddleware,
+} from './channel-middleware-runner.js'
+export { logChannels } from './log-channels.js'
+export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
+export type { EventHubService } from './eventhub-service.js'
+export { ChannelStore } from './channel-store.js'
+export type { Channel } from './channel-store.js'
+export { EventHubStore } from './eventhub-store.js'
+export type {
+  ChannelsMeta,
+  CoreChannel,
+  CorePikkuChannelMiddleware,
+  CorePikkuChannelMiddlewareFactory,
+  ChannelMessageMeta,
+  ChannelMeta,
+  PikkuChannel,
+  PikkuChannelHandlerFactory,
+} from './channel.types.js'
+export { defineChannelRoutes } from './define-channel-routes.js'

package/src/wirings/channel/local/index.ts

@@ -1,3 +1,3 @@
-export * from './local-channel-handler.js'
-export * from './local-channel-runner.js'
-export * from './local-eventhub-service.js'
+export { PikkuLocalChannelHandler } from './local-channel-handler.js'
+export { runLocalChannel } from './local-channel-runner.js'
+export { LocalEventHubService } from './local-eventhub-service.js'

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

@@ -160,6 +160,49 @@ test('runChannel should return a channel handler if channel matches and no auth
 
   // Simulate opening the channel
   result.open()
+})
+
+test('runChannel should close wire services once when channel closes', async () => {
+  resetPikkuState()
+  let closeCount = 0
+
+  pikkuState(null, 'channel', 'meta', {
+    test: {
+      name: 'test',
+      route: '/test-channel',
+    },
+  } as any)
+  wireChannel({
+    name: 'test',
+    route: '/test-channel',
+    auth: false,
+  })
+
+  httpRouter.initialize()
+
+  const result = await runLocalChannel({
+    singletonServices: mockSingletonServices,
+    channelId: 'test-channel-id',
+    request: new PikkuMockRequest('/test-channel', 'get'),
+    response: new PikkuMockResponse(),
+    route: '/test-channel',
+    createWireServices: async () => ({
+      tracked: {
+        close: async () => {
+          closeCount += 1
+        },
+      },
+    }),
+  })
+
+  assert.ok(result)
+  assert.equal(closeCount, 0)
+
+  result.close()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  assert.equal(closeCount, 1)
 
-  // TODO: Test that the opened channel works
+  result.close()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  assert.equal(closeCount, 1)
 })

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

@@ -10,7 +10,10 @@ import {
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
 import { PikkuWire, WireServices } from '../../../types/core.types.js'
 import { handleHTTPError } from '../../../handle-error.js'
-import { PikkuSessionService } from '../../../services/user-session-service.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../../services/user-session-service.js'
 import { PikkuHTTP } from '../../http/http.types.js'
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
 
@@ -30,6 +33,7 @@ export const runLocalChannel = async ({
   RunChannelOptions &
   RunChannelParams<unknown>): Promise<PikkuLocalChannelHandler | void> => {
   let wireServices: WireServices<typeof singletonServices> | undefined
+  let closedWireServices = false
 
   let channelHandler: PikkuLocalChannelHandler | undefined
   const userSession = new PikkuSessionService()
@@ -75,12 +79,23 @@ export const runLocalChannel = async ({
         openingData
       )
       const channel = channelHandler.getChannel()
-      const wire: PikkuWire = { channel, session: userSession }
+      const wire: PikkuWire = {
+        channel,
+        ...createMiddlewareSessionWireProps(userSession),
+      }
 
       if (createWireServices) {
         wireServices = await createWireServices(singletonServices, wire)
       }
 
+      const closeServices = async () => {
+        if (!wireServices || closedWireServices) {
+          return
+        }
+        closedWireServices = true
+        await closeWireServices(singletonServices.logger, wireServices)
+      }
+
       const services = { ...singletonServices, ...wireServices }
 
       channelHandler.registerOnOpen(async () => {
@@ -94,6 +109,7 @@ export const runLocalChannel = async ({
               services,
               channel,
               data: openingData,
+              channelMiddlewareMeta: meta.channelMiddleware,
             })
             if (result !== undefined) {
               await channel.send(result)
@@ -115,6 +131,7 @@ export const runLocalChannel = async ({
               lifecycleType: 'disconnect',
               services,
               channel,
+              channelMiddlewareMeta: meta.channelMiddleware,
             })
           } catch (e) {
             singletonServices.logger.error(`Error handling onDisconnect: ${e}`)
@@ -122,9 +139,7 @@ export const runLocalChannel = async ({
           }
         }
 
-        if (wireServices) {
-          await closeWireServices(singletonServices.logger, wireServices)
-        }
+        await closeServices()
       })
 
       const onMessage = processMessageHandlers(
@@ -153,7 +168,8 @@ export const runLocalChannel = async ({
         bubbleErrors
       )
     } finally {
-      if (wireServices) {
+      if (!channelHandler && wireServices && !closedWireServices) {
+        closedWireServices = true
         await closeWireServices(singletonServices.logger, wireServices)
       }
     }

package/src/wirings/channel/serverless/index.ts

@@ -1 +1,5 @@
-export * from './serverless-channel-runner.js'
+export {
+  runChannelConnect,
+  runChannelDisconnect,
+  runChannelMessage,
+} from './serverless-channel-runner.js'

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -11,7 +11,10 @@ import type {
 import { createHTTPWire } from '../../http/http-runner.js'
 import { ChannelStore } from '../channel-store.js'
 import { handleHTTPError } from '../../../handle-error.js'
-import { PikkuSessionService } from '../../../services/user-session-service.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../../services/user-session-service.js'
 import { pikkuState } from '../../../pikku-state.js'
 import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js'
 import { PikkuHTTP } from '../../http/http.types.js'
@@ -107,7 +110,10 @@ export const runChannelConnect = async ({
       channelName: channelConfig.name,
     })
 
-    const wire: PikkuWire = { channel, session: userSession }
+    const wire: PikkuWire = {
+      channel,
+      ...createMiddlewareSessionWireProps(userSession),
+    }
 
     if (createWireServices) {
       wireServices = await createWireServices(singletonServices, wire)
@@ -127,6 +133,7 @@ export const runChannelConnect = async ({
         services,
         channel,
         data: openingData,
+        channelMiddlewareMeta: meta.channelMiddleware,
       })
     }
     http?.response?.status(101)
@@ -175,12 +182,16 @@ export const runChannelDisconnect = async ({
     openingData,
     channelName,
   })
+
   const userSession = new PikkuSessionService(
     params.channelStore,
     params.channelId
   )
   userSession.setInitial(session)
-  const wire: PikkuWire = { channel, session: userSession }
+  const wire: PikkuWire = {
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
+  }
 
   if (!wireServices && params.createWireServices) {
     wireServices = await params.createWireServices(singletonServices, wire)
@@ -200,6 +211,7 @@ export const runChannelDisconnect = async ({
         lifecycleType: 'disconnect',
         services,
         channel,
+        channelMiddlewareMeta: meta.channelMiddleware,
       })
     } catch (e: any) {
       singletonServices.logger.error(
@@ -226,12 +238,16 @@ export const runChannelMessage = async (
     openingData,
     channelName,
   })
+
   const userSession = new PikkuSessionService(
     params.channelStore,
     params.channelId
   )
   userSession.setInitial(session)
-  const wire: PikkuWire = { channel, session: userSession }
+  const wire: PikkuWire = {
+    channel,
+    ...createMiddlewareSessionWireProps(userSession),
+  }
 
   if (params.createWireServices) {
     wireServices = await params.createWireServices(singletonServices, wire)

package/src/wirings/cli/channel/index.ts

@@ -1 +1 @@
-export * from './cli-channel-runner.js'
+export { executeCLIViaChannel } from './cli-channel-runner.js'

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

@@ -91,7 +91,7 @@ describe('CLI Runner', () => {
             commands: {
               greet: {
                 command: 'greet <name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 positionals: [{ name: 'name', required: true }],
                 options: {},
               },
@@ -112,7 +112,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         greetFunc: {
-          pikkuFuncName: 'greetFunc',
+          pikkuFuncId: 'greetFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -155,7 +155,7 @@ describe('CLI Runner', () => {
             commands: {
               test: {
                 command: 'test',
-                pikkuFuncName: 'testFunc',
+                pikkuFuncId: 'testFunc',
                 positionals: [],
                 options: {},
               },
@@ -176,7 +176,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         testFunc: {
-          pikkuFuncName: 'testFunc',
+          pikkuFuncId: 'testFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -215,7 +215,7 @@ describe('CLI Runner', () => {
             commands: {
               greet: {
                 command: 'greet <name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 positionals: [{ name: 'name', required: true }],
                 options: {},
               },
@@ -236,7 +236,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         greetFunc: {
-          pikkuFuncName: 'greetFunc',
+          pikkuFuncId: 'greetFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -267,7 +267,7 @@ describe('CLI Runner', () => {
             commands: {
               secure: {
                 command: 'secure',
-                pikkuFuncName: 'secureFunc',
+                pikkuFuncId: 'secureFunc',
                 positionals: [],
                 options: {},
               },
@@ -280,7 +280,7 @@ describe('CLI Runner', () => {
 
       pikkuState(null, 'function', 'meta', {
         secureFunc: {
-          pikkuFuncName: 'secureFunc',
+          pikkuFuncId: 'secureFunc',
           inputSchemaName: null,
           outputSchemaName: null,
         },
@@ -313,7 +313,7 @@ describe('CLI Runner', () => {
             commands: {
               greet: {
                 command: 'greet <name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 positionals: [{ name: 'name', required: true }],
                 options: {
                   loud: {

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

@@ -1,4 +1,4 @@
-import { NotFoundError } from '../../errors/errors.js'
+import { NotFoundError, PikkuMissingMetaError } from '../../errors/errors.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
 import { CorePikkuMiddleware, CoreUserSession } from '../../types/core.types.js'
@@ -20,7 +20,10 @@ import type {
   CreateSingletonServices,
 } from '../../types/core.types.js'
 import { PikkuChannel } from '../channel/channel.types.js'
-import { PikkuSessionService } from '../../services/user-session-service.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../services/user-session-service.js'
 import { LocalVariablesService } from '../../services/local-variables.js'
 import { generateCommandHelp, parseCLIArguments } from './command-parser.js'
 
@@ -60,8 +63,8 @@ export const wireCLI = <
   const cliMeta = pikkuState(null, 'cli', 'meta') || {}
 
   if (!cliMeta.programs?.[cli.program]) {
-    throw new Error(
-      `CLI metadata not found for program '${cli.program}'. Did you run 'pikku all'?`
+    throw new PikkuMissingMetaError(
+      `CLI metadata not found for program '${cli.program}'`
     )
   }
 
@@ -141,7 +144,7 @@ function registerCLICommands(
     for (let i = 1; i < fullPath.length; i++) {
       currentMeta = currentMeta?.subcommands?.[fullPath[i]]
     }
-    const funcName = currentMeta?.pikkuFuncName
+    const funcName = currentMeta?.pikkuFuncId
 
     // Skip if no function name (could be a command group)
     if (!funcName) {
@@ -272,7 +275,7 @@ export async function runCLICommand({
     currentCommand = currentCommand.subcommands[commandPath[i]]
   }
 
-  const funcName = currentCommand.pikkuFuncName
+  const funcName = currentCommand.pikkuFuncId
 
   // Get program-specific data
   const programs: Record<string, CLIProgramState> =
@@ -332,7 +335,7 @@ export async function runCLICommand({
       data: pluckedData,
       channel,
     },
-    session: userSession,
+    ...createMiddlewareSessionWireProps(userSession),
   }
 
   try {
@@ -347,10 +350,12 @@ export async function runCLICommand({
       wirePermissions: undefined,
       tags: programData?.tags,
       wire,
+      sessionService: userSession,
     })
 
     // Apply renderer one final time with the final output (if renderer exists)
-    if (renderer) {
+    // Skip if result is undefined (void functions handle their own output)
+    if (renderer && result !== undefined) {
       await Promise.resolve(
         renderer(singletonServices, result, userSession.get())
       )
@@ -395,7 +400,7 @@ export async function executeCLI({
 }: {
   programName: string
   args?: string[]
-  createConfig: CreateConfig<any, any>
+  createConfig?: CreateConfig<any, any>
   createSingletonServices: CreateSingletonServices<any, any>
   createWireServices?: CreateWireServices<any, any, any>
 }): Promise<void> {
@@ -470,7 +475,9 @@ export async function executeCLI({
     const data = { ...parsed.positionals, ...parsed.options }
 
     // Create config (pass data in case it needs to use any parsed options)
-    const config = await createConfig(new LocalVariablesService(), data)
+    const config = createConfig
+      ? await createConfig(new LocalVariablesService(), data)
+      : ({} as any)
 
     // Create services with config
     const singletonServices = await createSingletonServices(config)

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

@@ -69,7 +69,7 @@ export interface CLIProgramState {
  */
 export interface CLICommandMeta {
   parameters?: string
-  pikkuFuncName: string
+  pikkuFuncId: string
   positionals: CLIPositional[]
   options: Record<string, CLIOption>
   renderName?: string
@@ -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>
-        | CorePikkuFunctionSessionless<infer Input, any, any, any>
+        | CorePikkuFunction<infer Input, any, any, any, any>
+        | CorePikkuFunctionSessionless<infer Input, any, 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>
-        | CorePikkuFunctionSessionless<any, infer Output, any, any>
+        | CorePikkuFunction<any, infer Output, any, any, any>
+        | CorePikkuFunctionSessionless<any, infer Output, any, any, any>
       ? Output
       : never
     : never
@@ -249,8 +249,8 @@ export interface CoreCLICommand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any>
+    | CorePikkuFunction<In, Out, any, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,
@@ -282,8 +282,8 @@ export type CLICommandShorthand<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any>
+    | CorePikkuFunction<In, Out, any, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
 > = PikkuFunctionConfig
 
@@ -294,8 +294,8 @@ export type CLICommandDefinition<
   In,
   Out,
   PikkuFunctionConfig extends CorePikkuFunctionConfig<
-    | CorePikkuFunction<In, Out, any, any>
-    | CorePikkuFunctionSessionless<In, Out, any, any>
+    | CorePikkuFunction<In, Out, any, any, any>
+    | CorePikkuFunctionSessionless<In, Out, any, any, any>
   >,
   PikkuPermission extends CorePikkuPermission<any, any, any>,
   PikkuMiddleware extends CorePikkuMiddleware,

package/src/wirings/cli/command-parser.test.ts

@@ -17,7 +17,7 @@ const testMeta: CLIMeta = {
       commands: {
         greet: {
           parameters: '<name>',
-          pikkuFuncName: 'greetFunc',
+          pikkuFuncId: 'greetFunc',
           positionals: [{ name: 'name', required: true }],
           options: {
             loud: {
@@ -28,13 +28,13 @@ const testMeta: CLIMeta = {
           },
         },
         user: {
-          pikkuFuncName: '',
+          pikkuFuncId: '',
           positionals: [],
           options: {},
           subcommands: {
             create: {
               parameters: '<name> <email>',
-              pikkuFuncName: 'createUserFunc',
+              pikkuFuncId: 'createUserFunc',
               positionals: [
                 { name: 'name', required: true },
                 { name: 'email', required: true },
@@ -50,7 +50,7 @@ const testMeta: CLIMeta = {
             },
             delete: {
               parameters: '<id>',
-              pikkuFuncName: 'deleteUserFunc',
+              pikkuFuncId: 'deleteUserFunc',
               positionals: [{ name: 'id', required: true }],
               options: {
                 force: {
@@ -64,13 +64,13 @@ const testMeta: CLIMeta = {
         },
         files: {
           parameters: '<paths...>',
-          pikkuFuncName: 'filesFunc',
+          pikkuFuncId: 'filesFunc',
           positionals: [{ name: 'paths', required: true, variadic: true }],
           options: {},
         },
         optional: {
           parameters: '[name]',
-          pikkuFuncName: 'optionalFunc',
+          pikkuFuncId: 'optionalFunc',
           positionals: [{ name: 'name', required: false }],
           options: {},
         },
@@ -299,7 +299,7 @@ describe('Command Parser', () => {
             options: {},
             commands: {
               test: {
-                pikkuFuncName: 'testFunc',
+                pikkuFuncId: 'testFunc',
                 positionals: [],
                 options: {
                   port: {
@@ -380,7 +380,7 @@ describe('Command Parser', () => {
             commands: {
               greet: {
                 parameters: '<name>',
-                pikkuFuncName: 'greetFunc',
+                pikkuFuncId: 'greetFunc',
                 description: 'Greet a user',
                 positionals: [{ name: 'name', required: true }],
                 options: {},

package/src/wirings/cli/define-cli-commands.ts

@@ -0,0 +1,24 @@
+import type { CoreCLICommandConfig } from './cli.types.js'
+
+/**
+ * Type-safe helper for defining CLI commands that can be composed.
+ * Returns the commands record as-is (identity function) for use with `wireCLI`.
+ *
+ * @example
+ * ```typescript
+ * export const chatCommands = defineCLICommands({
+ *   chat: pikkuCLICommand({ func: chatFunc }),
+ *   'chat:history': pikkuCLICommand({ func: historyFunc }),
+ * })
+ *
+ * wireCLI({
+ *   program: 'my-app',
+ *   commands: { ...chatCommands, other: pikkuCLICommand({ func: otherFunc }) }
+ * })
+ * ```
+ */
+export function defineCLICommands<
+  T extends Record<string, CoreCLICommandConfig<any, any, any, any>>,
+>(commands: T): T {
+  return commands
+}

package/src/wirings/cli/index.ts

@@ -1,7 +1,3 @@
-export * from './cli.types.js'
-export * from './cli-runner.js'
-export * from './command-parser.js'
-
 export {
   wireCLI,
   runCLICommand,
@@ -11,3 +7,13 @@ export {
 } from './cli-runner.js'
 
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js'
+
+export { defineCLICommands } from './define-cli-commands.js'
+export type {
+  CLIMeta,
+  CLICommandMeta,
+  CLIProgramMeta,
+  CoreCLI,
+  CoreCLICommandConfig,
+  CorePikkuCLIRender,
+} from './cli.types.js'