@pikku/core 0.11.0 → 0.11.2

package/src/function/functions.types.ts

@@ -1,67 +1,58 @@
-import { PikkuChannel } from '../wirings/channel/channel.types.js'
 import type {
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
-  PikkuDocs,
   CorePikkuMiddleware,
+  PikkuWire,
+  PickRequired,
 } from '../types/core.types.js'
+import { Session } from 'inspector'
 
 /**
  * Represents a core API function that performs an operation using core services and a user session.
  *
  * @template In - The input type.
  * @template Out - The output type.
- * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
+ * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
  */
 export type CorePikkuFunction<
   In,
   Out,
-  ChannelData extends unknown | null = null,
-  Services extends CoreSingletonServices = CoreServices &
-    (ChannelData extends null
-      ? {
-          channel?: PikkuChannel<unknown, Out> | undefined
-        }
-      : {
-          channel: PikkuChannel<ChannelData, Out>
-        }),
-  Session extends CoreUserSession = CoreUserSession,
+  Services extends CoreSingletonServices = CoreServices,
+  Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>,
 > = (
   services: Services,
   data: In,
-  session: Session
-) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
+  wire: Wire
+) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
 
 /**
  * Represents a core API function that can be used without a session.
  *
  * @template In - The input type.
  * @template Out - The output type.
- * @template ChannelData - The channel data type.
  * @template Services - The services type, defaults to `CoreServices`.
- * @template Session - The session type, defaults to `CoreUserSession`.
+ * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
  */
 export type CorePikkuFunctionSessionless<
   In,
   Out,
-  ChannelData extends unknown | null = null,
-  Services extends CoreSingletonServices = CoreServices &
-    (ChannelData extends null
-      ? {
-          channel?: PikkuChannel<unknown, Out> | undefined
-        }
-      : {
-          channel: PikkuChannel<ChannelData, Out>
-        }),
-  Session extends CoreUserSession = CoreUserSession,
+  Services extends CoreSingletonServices = CoreServices,
+  Wire extends PikkuWire<
+    In,
+    Out,
+    false,
+    CoreUserSession,
+    any,
+    any,
+    any
+  > = PikkuWire<In, Out, false, CoreUserSession, any, any, any>,
 > = (
   services: Services,
   data: In,
-  session?: Session
-) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
+  wire: Wire
+) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>
 
 /**
  * Represents a function that checks permissions for a given operation.
@@ -73,8 +64,16 @@ export type CorePikkuFunctionSessionless<
 export type CorePikkuPermission<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = (services: Services, data: In, session?: Session) => Promise<boolean>
+  Wire extends PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession,
+    any,
+    never,
+    never
+  > = PikkuWire<In, never, false, CoreUserSession, never, never, never>,
+> = (services: Services, data: In, wire: Wire) => Promise<boolean>
 
 /**
  * Configuration object for creating a permission with metadata
@@ -86,12 +85,17 @@ export type CorePikkuPermission<
 export type CorePikkuPermissionConfig<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
+  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession
+  >,
 > = {
   /** The permission function */
-  func: CorePikkuPermission<In, Services, Session>
-  /** Optional human-readable name for the permission */
-  name?: string
+  func: CorePikkuPermission<In, Services, Wire>
+  /** Optional human-readable title for the permission */
+  title?: string
   /** Optional description of what the permission checks */
   description?: string
 }
@@ -104,17 +108,19 @@ export type CorePikkuPermissionConfig<
  * ```typescript
  * // Direct function syntax
  * export const adminPermission = pikkuPermission(
- *   async ({ logger }, data, session) => {
- *     return session?.role === 'admin'
+ *   async ({ logger }, _data, { session }) => {
+ *     const currentSession = await session.get()
+ *     return currentSession?.role === 'admin'
  *   }
  * )
  *
  * // Configuration object syntax with metadata
  * export const adminPermission = pikkuPermission({
- *   name: 'Admin Permission',
+ *   title: 'Admin Permission',
  *   description: 'Checks if user has admin role',
- *   func: async ({ logger }, data, session) => {
- *     return session?.role === 'admin'
+ *   func: async ({ logger }, _data, { session }) => {
+ *     const currentSession = await session.get()
+ *     return currentSession?.role === 'admin'
  *   }
  * })
  * ```
@@ -122,12 +128,15 @@ export type CorePikkuPermissionConfig<
 export const pikkuPermission = <
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
+  Wire extends PickRequired<
+    PikkuWire<In, never, false, CoreUserSession>,
+    'session'
+  > = PickRequired<PikkuWire<In, never, false, CoreUserSession>, 'session'>,
 >(
   permission:
-    | CorePikkuPermission<In, Services, Session>
-    | CorePikkuPermissionConfig<In, Services, Session>
-): CorePikkuPermission<In, Services, Session> => {
+    | CorePikkuPermission<In, Services, Wire>
+    | CorePikkuPermissionConfig<In, Services, Wire>
+): CorePikkuPermission<In, Services, Wire> => {
   return typeof permission === 'function' ? permission : permission.func
 }
 
@@ -142,8 +151,13 @@ export const pikkuPermission = <
 export type CorePikkuPermissionFactory<
   In = any,
   Services extends CoreSingletonServices = CoreServices,
-  Session extends CoreUserSession = CoreUserSession,
-> = (input: In) => CorePikkuPermission<any, Services, Session>
+  Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<
+    In,
+    never,
+    false,
+    CoreUserSession
+  >,
+> = (input: In) => CorePikkuPermission<any, Services, Wire>
 
 /**
  * Factory function for creating permission factories
@@ -154,8 +168,9 @@ export type CorePikkuPermissionFactory<
  * export const requireRole = pikkuPermissionFactory<{ role: string }>(({
  *   role
  * }) => {
- *   return pikkuPermission(async ({ logger }, data, session) => {
- *     if (!session || session.role !== role) {
+ *   return pikkuPermission(async ({ logger }, data, { session }) => {
+ *      const currentSession = await session.get()
+ *     if (!currentSession || currentSession.role !== role) {
  *       logger.warn(`Permission denied: required role '${role}'`)
  *       return false
  *     }
@@ -174,24 +189,148 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> =
   | Record<string, PikkuPermission | PikkuPermission[]>
   | undefined
 
+/**
+ * Zod schema type - matches z.ZodType shape for type inference
+ * This avoids requiring zod as a dependency while allowing schema inference
+ */
+export type ZodLike<T = any> = {
+  _input: T
+  _output: T
+}
+
 export type CorePikkuFunctionConfig<
   PikkuFunction extends
-    | CorePikkuFunction<any, any, any, any, any>
-    | CorePikkuFunctionSessionless<any, any, any, any, any>,
+    | CorePikkuFunction<any, any, any, any>
+    | CorePikkuFunctionSessionless<any, any, any, any>,
   PikkuPermission extends CorePikkuPermission<
     any,
     any,
     any
   > = CorePikkuPermission<any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+  InputSchema extends ZodLike | undefined = undefined,
+  OutputSchema extends ZodLike | undefined = undefined,
 > = {
-  name?: string
+  /** Optional human-readable title for the function */
+  title?: string
+  /** Optional description of what the function does */
+  description?: string
+  override?: string
+  tags?: string[]
   expose?: boolean
   internal?: boolean
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
   middleware?: PikkuMiddleware[]
+  input?: InputSchema
+  output?: OutputSchema
+}
+
+/**
+ * A trigger function that sets up a subscription and returns a teardown function.
+ * The trigger is fired via wire.trigger.trigger(data).
+ *
+ * @template TConfig - Configuration type (hardcoded when wired)
+ * @template TOutput - Output type produced when trigger fires
+ * @template Services - Services available to the trigger
+ */
+export type CorePikkuTriggerFunction<
+  TConfig = unknown,
+  TOutput = unknown,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+> = (
+  services: Services,
+  config: TConfig,
+  wire: { trigger: { trigger: (data: TOutput) => void } }
+) => Promise<() => void | Promise<void>>
+
+/**
+ * Configuration object for creating a trigger function with metadata
+ */
+export type CorePikkuTriggerFunctionConfig<
+  TConfig = unknown,
+  TOutput = unknown,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+  ConfigSchema extends ZodLike | undefined = undefined,
+  OutputSchema extends ZodLike | undefined = undefined,
+> = {
+  /** Optional human-readable title for the trigger */
+  title?: string
+  /** Optional description of what the trigger does */
+  description?: string
+  /** Optional tags for categorization */
   tags?: string[]
-  docs?: PikkuDocs
+  /** The trigger function */
+  func: CorePikkuTriggerFunction<TConfig, TOutput, Services>
+  /** Optional Zod schema for config validation */
+  config?: ConfigSchema
+  /** Optional Zod schema for output validation */
+  output?: OutputSchema
+}
+
+/**
+ * Factory function for creating trigger functions
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const redisSubscribeTrigger = pikkuTriggerFunc<
+ *   { channel: string },
+ *   { message: string }
+ * >(async ({ redis }, { channel }, { trigger }) => {
+ *   const subscriber = redis.duplicate()
+ *   await subscriber.subscribe(channel, (msg) => {
+ *     trigger.trigger({ message: msg })
+ *   })
+ *   return () => subscriber.unsubscribe()
+ * })
+ *
+ * // Configuration object syntax with metadata
+ * export const redisSubscribeTrigger = pikkuTriggerFunc({
+ *   title: 'Redis Subscribe Trigger',
+ *   description: 'Listens to Redis pub/sub channel',
+ *   config: z.object({ channel: z.string() }),
+ *   output: z.object({ message: z.string() }),
+ *   func: async ({ redis }, { channel }, { trigger }) => {
+ *     const subscriber = redis.duplicate()
+ *     await subscriber.subscribe(channel, (msg) => {
+ *       trigger.trigger({ message: msg })
+ *     })
+ *     return () => subscriber.unsubscribe()
+ *   }
+ * })
+ * ```
+ */
+export const pikkuTriggerFunc = <
+  TConfig = unknown,
+  TOutput = unknown,
+  Services extends CoreSingletonServices = CoreSingletonServices,
+  ConfigSchema extends ZodLike | undefined = undefined,
+  OutputSchema extends ZodLike | undefined = undefined,
+>(
+  triggerOrConfig:
+    | CorePikkuTriggerFunction<TConfig, TOutput, Services>
+    | CorePikkuTriggerFunctionConfig<
+        TConfig,
+        TOutput,
+        Services,
+        ConfigSchema,
+        OutputSchema
+      >
+): CorePikkuTriggerFunctionConfig<
+  TConfig,
+  TOutput,
+  Services,
+  ConfigSchema,
+  OutputSchema
+> => {
+  if (typeof triggerOrConfig === 'function') {
+    return { func: triggerOrConfig }
+  }
+  return triggerOrConfig
 }

package/src/handle-error.ts

@@ -7,7 +7,7 @@ import { PikkuHTTP } from './wirings/http/http.types.js'
  * Handle errors that occur during route processing
  *
  * @param {any} e - The error that occurred
- * @param {PikkuHTTP | undefined} http - HTTP interaction object
+ * @param {PikkuHTTP | undefined} http - HTTP wire object
  * @param {string} trackerId - Unique ID for tracking this error
  * @param {Logger} logger - Logger service
  * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings

package/src/index.ts

@@ -17,16 +17,21 @@ export * from './wirings/scheduler/index.js'
 export * from './wirings/rpc/index.js'
 export * from './wirings/queue/index.js'
 export * from './wirings/workflow/index.js'
+export * from './wirings/workflow/graph/index.js'
 export * from './wirings/mcp/index.js'
 export * from './wirings/cli/index.js'
+export * from './wirings/forge-node/index.js'
+export * from './wirings/trigger/index.js'
 export * from './errors/index.js'
 export * from './middleware/index.js'
 export * from './utils.js'
 export * from './time-utils.js'
-export { pikkuState } from './pikku-state.js'
 export {
-  runMiddleware,
-  addMiddleware,
-  getMiddlewareByName,
-} from './middleware-runner.js'
+  pikkuState,
+  initializePikkuState,
+  resetPikkuState,
+  addPackageServiceFactories,
+} from './pikku-state.js'
+export type { PikkuPackageState } from './types/state.types.js'
+export { runMiddleware, addMiddleware } from './middleware-runner.js'
 export { addPermission } from './permissions.js'