@pikku/core 0.8.2 → 0.9.1

package/src/{events → wirings}/channel/channel-handler.ts

@@ -5,7 +5,7 @@ import {
 } from '../../types/core.types.js'
 import {
   ChannelMessageMeta,
-  CoreAPIChannel,
+  CoreChannel,
   PikkuChannelHandler,
 } from './channel.types.js'
 import { pikkuState } from '../../pikku-state.js'
@@ -31,7 +31,7 @@ const getRouteMeta = (
       `Channel ${channelName} requires a router value for ${routingProperty}`
     )
   }
-  const route = channelMeta.messageRoutes[routingProperty]?.[routerValue]
+  const route = channelMeta.messageWirings[routingProperty]?.[routerValue]
   if (!route) {
     throw new Error(
       `Channel ${channelName} has no route for ${routingProperty}:${routerValue}`
@@ -61,7 +61,7 @@ const validateAuth = (
 export const processMessageHandlers = (
   services: CoreServices,
   session: CoreUserSession | undefined,
-  channelConfig: CoreAPIChannel<any, any>,
+  channelConfig: CoreChannel<any, any>,
   channelHandler: PikkuChannelHandler
 ) => {
   const logger = services.logger
@@ -115,10 +115,10 @@ export const processMessageHandlers = (
     let processed = false
 
     // Route-specific handling
-    if (typeof rawData === 'string' && channelConfig.onMessageRoute) {
+    if (typeof rawData === 'string' && channelConfig.onMessageWiring) {
       try {
         const messageData = JSON.parse(rawData)
-        const entries = Object.entries(channelConfig.onMessageRoute)
+        const entries = Object.entries(channelConfig.onMessageWiring)
         for (const [routingProperty, routes] of entries) {
           const routerValue = messageData[routingProperty]
           if (routerValue && routes[routerValue]) {

package/src/{events → wirings}/channel/channel-runner.ts

@@ -5,7 +5,7 @@ import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
 import { UserSessionService } from '../../services/user-session-service.js'
 import {
   ChannelMeta,
-  CoreAPIChannel,
+  CoreChannel,
   RunChannelOptions,
   RunChannelParams,
 } from './channel.types.js'
@@ -15,14 +15,14 @@ import { match } from 'path-to-regexp'
  * Adds a channel and registers all functions referenced in it using the
  * function names already stored in the channel metadata
  */
-export const addChannel = <
+export const wireChannel = <
   In,
   Channel extends string,
   ChannelFunction,
   ChannelFunctionSessionless,
-  APIPermission,
+  PikkuPermission,
 >(
-  channel: CoreAPIChannel<In, Channel, ChannelFunction, APIPermission>
+  channel: CoreChannel<In, Channel, ChannelFunction, PikkuPermission>
 ) => {
   // Get the channel metadata
   const channelsMeta = pikkuState('channel', 'meta')
@@ -58,20 +58,20 @@ export const addChannel = <
     })
   }
 
-  // Register functions in onMessageRoute
-  if (channel.onMessageRoute && channelMeta.messageRoutes) {
-    // Iterate through each channel in onMessageRoute
-    Object.entries(channel.onMessageRoute).forEach(([channelKey, routes]) => {
-      const channelRoutes = channelMeta.messageRoutes[channelKey]
-      if (!channelRoutes) return
+  // Register functions in onMessageWiring
+  if (channel.onMessageWiring && channelMeta.messageWirings) {
+    // Iterate through each channel in onMessageWiring
+    Object.entries(channel.onMessageWiring).forEach(([channelKey, wirings]) => {
+      const channelWirings = channelMeta.messageWirings[channelKey]
+      if (!channelWirings) return
 
-      // Iterate through each route in the channel
-      Object.entries(routes).forEach(([routeKey, handler]) => {
-        const routeMeta = channelRoutes[routeKey]
-        if (!routeMeta) return
+      // Iterate through each wiring in the channel
+      Object.entries(wirings).forEach(([wiringKey, handler]) => {
+        const wiringMeta = channelWirings[wiringKey]
+        if (!wiringMeta) return
 
         // Extract the function from the handler
-        const routeFunc =
+        const wiringFunc =
           typeof handler === 'function'
             ? { func: handler }
             : {
@@ -81,7 +81,7 @@ export const addChannel = <
               }
 
         // Register the function using the pikku name from metadata
-        addFunction(routeMeta.pikkuFuncName, routeFunc)
+        addFunction(wiringMeta.pikkuFuncName, wiringFunc)
       })
     })
   }
@@ -122,12 +122,12 @@ export const openChannel = async ({
   singletonServices,
   coerceDataFromSchema = true,
   request,
-}: Pick<CoreAPIChannel<unknown, string>, 'route'> &
+}: Pick<CoreChannel<unknown, string>, 'route'> &
   RunChannelParams<unknown> & {
     userSession: UserSessionService<any>
   } & RunChannelOptions): Promise<{
   openingData: unknown
-  channelConfig: CoreAPIChannel<unknown, any>
+  channelConfig: CoreChannel<unknown, any>
   meta: ChannelMeta
 }> => {
   const matchingChannel = getMatchingChannelConfig(route)

package/src/{events → wirings}/channel/channel.types.ts

@@ -11,9 +11,9 @@ import {
   PikkuMiddleware,
 } from '../../types/core.types.js'
 import {
-  CoreAPIFunction,
-  CoreAPIFunctionSessionless,
-  CoreAPIPermission,
+  CorePikkuFunction,
+  CorePikkuFunctionSessionless,
+  CorePikkuPermission,
 } from '../../function/functions.types.js'
 
 export type RunChannelOptions = Partial<{
@@ -47,26 +47,26 @@ export interface ChannelMeta {
   connect: ChannelMessageMeta | null
   disconnect: ChannelMessageMeta | null
   message: ChannelMessageMeta | null
-  messageRoutes: Record<string, Record<string, ChannelMessageMeta>>
+  messageWirings: Record<string, Record<string, ChannelMessageMeta>>
   docs?: APIDocs
   tags?: string[]
 }
 
 export type ChannelsMeta = Record<string, ChannelMeta>
 
-export type CoreAPIChannel<
+export type CoreChannel<
   ChannelData,
   Channel extends string,
   ChannelConnect =
-    | CoreAPIFunction<void, unknown, ChannelData>
-    | CoreAPIFunctionSessionless<void, unknown, ChannelData>,
+    | CorePikkuFunction<void, unknown, ChannelData>
+    | CorePikkuFunctionSessionless<void, unknown, ChannelData>,
   ChannelDisconnect =
-    | CoreAPIFunction<void, void, ChannelData>
-    | CoreAPIFunctionSessionless<void, void, ChannelData>,
+    | CorePikkuFunction<void, void, ChannelData>
+    | CorePikkuFunctionSessionless<void, void, ChannelData>,
   ChannelFunctionMessage =
-    | CoreAPIFunction<unknown, unknown, ChannelData>
-    | CoreAPIFunctionSessionless<unknown, unknown, ChannelData>,
-  APIPermission = CoreAPIPermission<ChannelData>,
+    | CorePikkuFunction<unknown, unknown, ChannelData>
+    | CorePikkuFunctionSessionless<unknown, unknown, ChannelData>,
+  PikkuPermission = CorePikkuPermission<ChannelData>,
 > = {
   name: string
   route: Channel
@@ -75,24 +75,24 @@ export type CoreAPIChannel<
   onMessage?:
     | {
         func: ChannelFunctionMessage
-        permissions?: Record<string, APIPermission[] | APIPermission>
+        permissions?: Record<string, PikkuPermission[] | PikkuPermission>
         auth?: boolean
       }
     | ChannelFunctionMessage
-  onMessageRoute?: Record<
+  onMessageWiring?: Record<
     string,
     Record<
       string,
       | ChannelFunctionMessage
       | {
           func: ChannelFunctionMessage
-          permissions?: Record<string, APIPermission[] | APIPermission>
+          permissions?: Record<string, PikkuPermission[] | PikkuPermission>
           auth?: boolean
         }
     >
   >
   middleware?: PikkuMiddleware[]
-  permissions?: Record<string, APIPermission[] | APIPermission>
+  permissions?: Record<string, PikkuPermission[] | PikkuPermission>
   auth?: boolean
   docs?: Partial<{
     description: string

package/src/{events → wirings}/channel/eventhub-service.ts

@@ -1,30 +1,34 @@
 /**
  * Interface defining the methods of a EventHub Service.
  */
-export interface EventHubService<Out = unknown> {
+export interface EventHubService<Topics extends Record<string, any>> {
   /**
    * Subscribes a connection to a specific topic.
    * @param topic - The topic to subscribe to.
    * @param channelId - The unique ID of the connection to subscribe.
    */
-  subscribe(topic: string, channelId: string): Promise<void> | void
-
+  subscribe<T extends keyof Topics>(
+    topic: T,
+    channelId: string
+  ): Promise<void> | void
   /**
    * Unsubscribes a connection from a specific topic.
    * @param topic - The topic to unsubscribe from.
    * @param channelId - The unique ID of the connection to unsubscribe.
    */
-  unsubscribe(topic: string, channelId: string): Promise<void> | void
-
+  unsubscribe<T extends keyof Topics>(
+    topic: T,
+    channelId: string
+  ): Promise<void> | void
   /**
    * Sends data to all connections subscribed to a topic.
    * @param topic - The topic to send data to.
    * @param data - The data to send to the subscribers.
    */
-  publish(
-    topic: string,
+  publish<T extends keyof Topics>(
+    topic: T,
     channelId: string | null,
-    data: Out,
+    data: Topics[T],
     isBinary?: boolean
   ): Promise<void> | void
 }

package/src/wirings/channel/eventhub-store.ts

@@ -0,0 +1,13 @@
+export abstract class EventHubStore<
+  EventTopics extends Record<string, any> = {},
+> {
+  public abstract getChannelIdsForTopic(topic: string): Promise<string[]>
+  public abstract subscribe<T extends keyof EventTopics>(
+    topic: T,
+    channelId: string
+  ): Promise<boolean>
+  public abstract unsubscribe<T extends keyof EventTopics>(
+    topic: T,
+    channelId: string
+  ): Promise<boolean>
+}

package/src/{events → wirings}/channel/local/local-channel-runner.test.ts

@@ -2,7 +2,7 @@ import { test, beforeEach, afterEach } from 'node:test'
 import * as assert from 'node:assert/strict'
 import { runLocalChannel } from './local-channel-runner.js'
 import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
-import { addChannel } from '../channel-runner.js'
+import { wireChannel } from '../channel-runner.js'
 import {
   HTTPMethod,
   PikkuHTTPRequest,
@@ -133,7 +133,7 @@ test('runChannel should return a channel handler if channel matches and no auth
       route: '/test-channel',
     },
   } as any)
-  addChannel({
+  wireChannel({
     name: 'test',
     route: '/test-channel',
     auth: false,

package/src/{events → wirings}/channel/local/local-channel-runner.ts

@@ -3,7 +3,7 @@ import { createHTTPInteraction } from '../../http/http-runner.js'
 import { closeSessionServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import {
-  CoreAPIChannel,
+  CoreChannel,
   RunChannelOptions,
   RunChannelParams,
 } from '../channel.types.js'
@@ -28,7 +28,7 @@ export const runLocalChannel = async ({
   coerceDataFromSchema = true,
   logWarningsForStatusCodes = [],
   bubbleErrors = false,
-}: Partial<Pick<CoreAPIChannel<unknown, any>, 'route'>> &
+}: Partial<Pick<CoreChannel<unknown, any>, 'route'>> &
   RunChannelOptions &
   RunChannelParams<unknown>): Promise<PikkuLocalChannelHandler | void> => {
   let sessionServices: SessionServices<typeof singletonServices> | undefined

package/src/{events → wirings}/channel/local/local-eventhub-service.ts

@@ -5,7 +5,7 @@ import { EventHubService } from '../eventhub-service.js'
  * Implementation of the SubscriptionService interface.
  * Manages subscriptions and publishes messages to subscribers.
  */
-export class LocalEventHubService<Data = unknown>
+export class LocalEventHubService<Data extends Record<string, any> = {}>
   implements EventHubService<Data>
 {
   private channels = new Map<string, PikkuChannelHandler>()
@@ -13,7 +13,7 @@ export class LocalEventHubService<Data = unknown>
   /**
    * A map storing topics and their associated connection IDs.
    */
-  private subscriptions: Map<string, Set<string>> = new Map()
+  private subscriptions: Map<keyof Data, Set<string>> = new Map()
 
   /**
    * Subscribes a connection to a specific topic.
@@ -21,7 +21,10 @@ export class LocalEventHubService<Data = unknown>
    * @param topic - The topic to subscribe to.
    * @param channelId - The unique ID of the connection to subscribe.
    */
-  public subscribe(topic: string, channelId: string): void {
+  public subscribe<T extends keyof Data>(
+    topic: T,
+    channelId: string
+  ): void | Promise<void> {
     if (!this.subscriptions.has(topic)) {
       this.subscriptions.set(topic, new Set())
     }
@@ -34,12 +37,15 @@ export class LocalEventHubService<Data = unknown>
    * @param topic - The topic to unsubscribe from.
    * @param channelId - The unique ID of the connection to unsubscribe.
    */
-  public unsubscribe(topic: string, channelId: string): void {
+  public unsubscribe<T extends keyof Data>(
+    topic: T,
+    channelId: string
+  ): void | Promise<void> {
     const topicSubscriptions = this.subscriptions.get(topic)
     if (topicSubscriptions) {
       topicSubscriptions.delete(channelId)
       if (topicSubscriptions.size === 0) {
-        this.subscriptions.delete(topic) // Cleanup empty subscriptions
+        this.subscriptions.delete(topic)
       }
     }
   }
@@ -49,12 +55,12 @@ export class LocalEventHubService<Data = unknown>
    * @param topic - The topic to send data to.
    * @param data - The data to send to the subscribers.
    */
-  public publish(
-    topic: string,
-    channelId: string,
-    data: Data,
+  public publish<T extends keyof Data>(
+    topic: T,
+    channelId: string | null,
+    data: Data[T],
     isBinary?: boolean
-  ): void {
+  ): void | Promise<void> {
     const subscribedChannelIds = this.subscriptions.get(topic)
     if (!subscribedChannelIds) {
       return

package/src/{events → wirings}/channel/serverless/serverless-channel-runner.ts

@@ -3,7 +3,7 @@ import { closeSessionServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import { openChannel } from '../channel-runner.js'
 import type {
-  CoreAPIChannel,
+  CoreChannel,
   RunChannelOptions,
   RunChannelParams,
   PikkuChannelHandlerFactory,
@@ -73,7 +73,7 @@ export const runChannelConnect = async ({
   logWarningsForStatusCodes = [],
   respondWith404 = true,
   bubbleErrors = false,
-}: Pick<CoreAPIChannel<unknown, any>, 'route'> &
+}: Pick<CoreChannel<unknown, any>, 'route'> &
   RunChannelOptions &
   RunServerlessChannelParams<unknown>) => {
   let sessionServices: SessionServices | undefined

package/src/{events → wirings}/http/http-runner.test.ts

@@ -2,7 +2,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 { fetch, addHTTPRoute } from './http-runner.js'
+import { fetch, wireHTTP } from './http-runner.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import {
   PikkuMockRequest,
@@ -78,7 +78,7 @@ describe('fetch', () => {
     const routeFunc = async () => ({ success: true })
     setHTTPFunctionMap(routeFunc)
 
-    addHTTPRoute({
+    wireHTTP({
       route: 'test',
       method: 'get',
       func: routeFunc,
@@ -98,7 +98,7 @@ describe('fetch', () => {
     const routeFunc = async () => ({ success: true })
     setHTTPFunctionMap(routeFunc)
 
-    addHTTPRoute({
+    wireHTTP({
       route: 'test',
       method: 'get',
       func: routeFunc,
@@ -120,7 +120,7 @@ describe('fetch', () => {
       throw error
     }
     setHTTPFunctionMap(routeFunc)
-    addHTTPRoute({
+    wireHTTP({
       route: 'test',
       method: 'get',
       func: routeFunc,

package/src/{events → wirings}/http/http-runner.ts

@@ -1,11 +1,11 @@
 import {
-  CoreHTTPFunctionRoute,
-  RunRouteOptions,
-  RunRouteParams,
+  CoreHTTPFunctionWiring,
+  RunHTTPWiringOptions,
+  RunHTTPWiringParams,
   PikkuHTTP,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
-  HTTPRouteMeta,
+  HTTPWiringMeta,
   HTTPMethod,
 } from './http.types.js'
 import {
@@ -87,48 +87,49 @@ export const addMiddleware = <APIMiddleware extends PikkuMiddleware>(
  * @template In Expected input type.
  * @template Out Expected output type.
  * @template Route Route pattern as a string.
- * @template APIFunction Type for the route handler function.
- * @template APIFunctionSessionless Type for a sessionless handler.
- * @template APIPermissionGroup Type representing required permissions.
+ * @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 {CoreHTTPFunctionRoute<In, Out, Route, APIFunction, APIFunctionSessionless, APIPermission, APIMiddleware>} route - The route configuration object.
+ * @param {CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, APIMiddleware>} httpWiring - The HTTP wiring configuration object.
  */
-export const addHTTPRoute = <
+export const wireHTTP = <
   In,
   Out,
   Route extends string,
-  APIFunction,
-  APIFunctionSessionless,
-  APIPermissionGroup,
+  PikkuFunction,
+  PikkuFunctionSessionless,
+  PikkuPermissionGroup,
   APIMiddleware,
 >(
-  httpRoute: CoreHTTPFunctionRoute<
+  httpWiring: CoreHTTPFunctionWiring<
     In,
     Out,
     Route,
-    APIFunction,
-    APIFunctionSessionless,
-    APIPermissionGroup,
+    PikkuFunction,
+    PikkuFunctionSessionless,
+    PikkuPermissionGroup,
     APIMiddleware
   >
 ) => {
   const httpMeta = pikkuState('http', 'meta')
   const routeMeta = httpMeta.find(
-    (meta) => meta.route === httpRoute.route && meta.method === httpRoute.method
+    (meta) =>
+      meta.route === httpWiring.route && meta.method === httpWiring.method
   )
   if (!routeMeta) {
     throw new Error('Route metadata not found')
   }
   addFunction(routeMeta.pikkuFuncName, {
-    func: httpRoute.func,
+    func: httpWiring.func,
   })
   const routes = pikkuState('http', 'routes')
-  if (!routes.has(httpRoute.method)) {
-    routes.set(httpRoute.method, new Map())
+  if (!routes.has(httpWiring.method)) {
+    routes.set(httpWiring.method, new Map())
   }
   pikkuState('http', 'routes')
-    .get(httpRoute.method)
-    ?.set(httpRoute.route, httpRoute as any)
+    .get(httpWiring.method)
+    ?.set(httpWiring.route, httpWiring as any)
 }
 
 /**
@@ -242,9 +243,9 @@ const executeRouteWithMiddleware = async (
   matchedRoute: {
     matchedPath: any
     params: any
-    route: CoreHTTPFunctionRoute<any, any, any>
+    route: CoreHTTPFunctionWiring<any, any, any>
     middleware: any[]
-    meta: HTTPRouteMeta
+    meta: HTTPWiringMeta
   },
   http: PikkuHTTP,
   options: {
@@ -290,7 +291,7 @@ const executeRouteWithMiddleware = async (
       throw new MissingSessionError()
     }
 
-    const data = http.request!.data()
+    const data = await http.request!.data()
 
     const getAllServices = async () => {
       let channel: PikkuChannel<unknown, unknown> | undefined
@@ -382,12 +383,12 @@ const executeRouteWithMiddleware = async (
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request} request - The native Fetch API Request object.
- * @param {RunRouteOptions & RunRouteParams} params - Additional options including services and session management.
+ * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Additional options including services and session management.
  * @returns {Promise<Response>} A promise that resolves to a Fetch API Response object.
  */
 export const fetch = async <In, Out>(
   request: Request,
-  params: RunRouteOptions & RunRouteParams
+  params: RunHTTPWiringOptions & RunHTTPWiringParams
 ): Promise<Response> => {
   const pikkuResponse = new PikkuFetchHTTPResponse()
   await fetchData<In, Out>(request, pikkuResponse, params)
@@ -403,12 +404,12 @@ export const fetch = async <In, Out>(
  * @template In Expected input data type.
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The request object.
- * @param {RunRouteOptions & RunRouteParams} params - Execution options including services and session configuration.
+ * @param {RunHTTPWiringOptions & RunHTTPWiringParams} params - Execution options including services and session configuration.
  * @returns {Promise<PikkuFetchHTTPResponse>} A promise that resolves to a PikkuFetchHTTPResponse object.
  */
 export const pikkuFetch = async <In, Out>(
   request: Request | PikkuHTTPRequest,
-  params: RunRouteOptions & RunRouteParams
+  params: RunHTTPWiringOptions & RunHTTPWiringParams
 ): Promise<PikkuFetchHTTPResponse> => {
   const pikkuResponse = new PikkuFetchHTTPResponse()
   await fetchData<In, Out>(request, pikkuResponse, params)
@@ -430,7 +431,7 @@ export const pikkuFetch = async <In, Out>(
  * @template Out Expected output data type.
  * @param {Request | PikkuHTTPRequest} request - The incoming HTTP request.
  * @param {PikkuHTTPResponse} response - The response object to be populated.
- * @param {RunRouteOptions & RunRouteParams} options - Options such as singleton services, session handling, and error configuration.
+ * @param {RunHTTPWiringOptions & RunHTTPWiringParams} options - Options such as singleton services, session handling, and error configuration.
  * @returns {Promise<Out | void>} The output from the route handler or void if an error occurred.
  */
 export const fetchData = async <In, Out>(
@@ -446,7 +447,7 @@ export const fetchData = async <In, Out>(
     bubbleErrors = false,
     generateRequestId,
     ignoreMiddleware = false,
-  }: RunRouteOptions & RunRouteParams
+  }: RunHTTPWiringOptions & RunHTTPWiringParams
 ): Promise<Out | void> => {
   const requestId =
     (request as any).getHeader?.('x-request-id') ||