@pikku/core 0.11.1 → 0.11.2

package/src/function/function-runner.ts

@@ -12,6 +12,7 @@ import {
   PermissionMetadata,
   CoreSingletonServices,
   CreateWireServices,
+  CoreConfig,
 } from '../types/core.types.js'
 import {
   CorePermissionGroup,
@@ -23,11 +24,55 @@ import { ForbiddenError } from '../errors/errors.js'
 import { rpcService } from '../wirings/rpc/rpc-runner.js'
 import { closeWireServices } from '../utils.js'
 
+/**
+ * Get or create singleton services for an external package.
+ * Services are cached in pikkuState to avoid recreation on each call.
+ *
+ * @param packageName - The external package name
+ * @param parentServices - The parent/caller's singleton services (used as base)
+ * @returns The package's singleton services
+ */
+const getOrCreatePackageSingletonServices = async (
+  packageName: string,
+  parentServices: CoreSingletonServices
+): Promise<CoreSingletonServices> => {
+  // Check if we already have cached singleton services for this package
+  const cachedServices = pikkuState(packageName, 'package', 'singletonServices')
+  if (cachedServices) {
+    return cachedServices
+  }
+
+  // Get the package's service factories
+  const factories = pikkuState(packageName, 'package', 'factories')
+  if (!factories || !factories.createSingletonServices) {
+    // No factories registered, use parent services
+    return parentServices
+  }
+
+  // Create config for the package (use parent config if no factory)
+  let config: CoreConfig = parentServices.config
+  if (factories.createConfig) {
+    config = await factories.createConfig(parentServices.variables)
+  }
+
+  // Create singleton services for the package, passing parent services as existing
+  const packageServices = await factories.createSingletonServices(
+    config,
+    parentServices
+  )
+
+  // Cache the services
+  pikkuState(packageName, 'package', 'singletonServices', packageServices)
+
+  return packageServices
+}
+
 export const addFunction = (
   funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>
+  funcConfig: CorePikkuFunctionConfig<any, any>,
+  packageName: string | null = null
 ) => {
-  pikkuState('function', 'functions').set(funcName, funcConfig)
+  pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig)
 }
 
 export const runPikkuFuncDirectly = async <In, Out>(
@@ -35,9 +80,12 @@ export const runPikkuFuncDirectly = async <In, Out>(
   allServices: CoreServices,
   wire: PikkuWire,
   data: In,
-  userSession?: SessionService<CoreUserSession>
+  userSession?: SessionService<CoreUserSession>,
+  packageName: string | null = null
 ) => {
-  const funcConfig = pikkuState('function', 'functions').get(funcName)
+  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
+    funcName
+  )
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
@@ -65,6 +113,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     coerceDataFromSchema,
     tags = [],
     wire,
+    packageName = null,
   }: {
     singletonServices: CoreSingletonServices
     createWireServices?: CreateWireServices
@@ -77,17 +126,35 @@ export const runPikkuFunc = async <In = any, Out = any>(
     coerceDataFromSchema?: boolean
     tags?: string[]
     wire: PikkuWire
+    packageName?: string | null
   }
 ): Promise<Out> => {
-  const funcConfig = pikkuState('function', 'functions').get(funcName)
+  const funcConfig = pikkuState(packageName, 'function', 'functions').get(
+    funcName
+  )
   if (!funcConfig) {
     throw new Error(`Function not found: ${funcName}`)
   }
-  const funcMeta = pikkuState('function', 'meta')[funcName]
+  const allMeta = pikkuState(packageName, 'function', 'meta')
+  const funcMeta = allMeta[funcName]
   if (!funcMeta) {
     throw new Error(`Function meta not found: ${funcName}`)
   }
 
+  // For external packages, get or create their singleton services
+  const resolvedSingletonServices = packageName
+    ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
+    : singletonServices
+
+  // Get the package's createWireServices if available
+  let resolvedCreateWireServices = createWireServices
+  if (packageName) {
+    const factories = pikkuState(packageName, 'package', 'factories')
+    if (factories?.createWireServices) {
+      resolvedCreateWireServices = factories.createWireServices
+    }
+  }
+
   // Convert tags to PermissionMetadata and merge with inheritedPermissions
   const mergedInheritedPermissions: PermissionMetadata[] = [
     ...(inheritedPermissions || []),
@@ -125,14 +192,15 @@ export const runPikkuFunc = async <In = any, Out = any>(
     if (inputSchemaName) {
       // Validate request data against the defined schema, if any
       await validateSchema(
-        singletonServices.logger,
-        singletonServices.schema,
+        resolvedSingletonServices.logger,
+        resolvedSingletonServices.schema,
         inputSchemaName,
-        actualData
+        actualData,
+        packageName
       )
       // Coerce (top level) query string parameters or date objects if specified by the schema
       if (coerceDataFromSchema) {
-        coerceTopLevelDataFromSchema(inputSchemaName, actualData)
+        coerceTopLevelDataFromSchema(inputSchemaName, actualData, packageName)
       }
     }
 
@@ -141,17 +209,18 @@ export const runPikkuFunc = async <In = any, Out = any>(
       wirePermissions: wirePermissions,
       funcInheritedPermissions: funcMeta.permissions,
       funcPermissions: funcConfig.permissions,
-      services: singletonServices,
+      services: resolvedSingletonServices,
       wire: { ...wireWithInitialSession, rpc: undefined } as any,
       data: actualData,
+      packageName,
     })
 
-    const wireServices = await createWireServices?.(
-      singletonServices,
+    const wireServices = await resolvedCreateWireServices?.(
+      resolvedSingletonServices,
       wireWithInitialSession
     )
     try {
-      const services = { ...singletonServices, ...wireServices }
+      const services = { ...resolvedSingletonServices, ...wireServices }
       const rpc = rpcService.getContextRPCService(
         services,
         wireWithInitialSession
@@ -162,7 +231,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
       })
     } finally {
       if (wireServices) {
-        await closeWireServices(singletonServices.logger, wireServices)
+        await closeWireServices(resolvedSingletonServices.logger, wireServices)
       }
     }
   }
@@ -172,11 +241,12 @@ export const runPikkuFunc = async <In = any, Out = any>(
     wireMiddleware,
     funcInheritedMiddleware: funcMeta.middleware,
     funcMiddleware: funcConfig.middleware,
+    packageName,
   })
 
   if (allMiddleware.length > 0) {
     return (await runMiddleware<CorePikkuMiddleware>(
-      singletonServices,
+      resolvedSingletonServices,
       wire,
       allMiddleware,
       executeFunction

package/src/function/functions.types.ts

@@ -94,8 +94,8 @@ export type CorePikkuPermissionConfig<
 > = {
   /** The permission function */
   func: CorePikkuPermission<In, Services, Wire>
-  /** Optional human-readable name for the permission */
-  name?: string
+  /** Optional human-readable title for the permission */
+  title?: string
   /** Optional description of what the permission checks */
   description?: string
 }
@@ -116,7 +116,7 @@ export type CorePikkuPermissionConfig<
  *
  * // 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 }) => {
  *     const currentSession = await session.get()
@@ -189,6 +189,15 @@ 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>
@@ -202,8 +211,14 @@ export type CorePikkuFunctionConfig<
     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
@@ -211,4 +226,111 @@ export type CorePikkuFunctionConfig<
   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[]
+  /** 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/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'

package/src/middleware-runner.ts

@@ -82,9 +82,10 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
  */
 export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   tag: string,
-  middleware: CorePikkuMiddlewareGroup
+  middleware: CorePikkuMiddlewareGroup,
+  packageName: string | null = null
 ): CorePikkuMiddlewareGroup => {
-  const tagGroups = pikkuState('middleware', 'tagGroup')
+  const tagGroups = pikkuState(packageName, 'middleware', 'tagGroup')
   tagGroups[tag] = middleware
   return middleware
 }
@@ -100,10 +101,8 @@ export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
  *
  * @internal
  */
-export const getMiddlewareByName = (
-  name: string
-): CorePikkuMiddleware | undefined => {
-  const middlewareStore = pikkuState('misc', 'middleware')
+const getMiddlewareByName = (name: string): CorePikkuMiddleware | undefined => {
+  const middlewareStore = pikkuState(null, 'misc', 'middleware')
   const middleware = middlewareStore[name]
   return middleware?.[0]
 }
@@ -152,11 +151,13 @@ export const combineMiddleware = (
     wireMiddleware,
     funcInheritedMiddleware,
     funcMiddleware,
+    packageName = null,
   }: {
     wireInheritedMiddleware?: MiddlewareMetadata[]
     wireMiddleware?: CorePikkuMiddleware[]
     funcInheritedMiddleware?: MiddlewareMetadata[]
     funcMiddleware?: CorePikkuMiddleware[]
+    packageName?: string | null
   } = {}
 ): readonly CorePikkuMiddleware[] => {
   if (middlewareCache[wireType][uid]) {
@@ -170,14 +171,18 @@ export const combineMiddleware = (
     for (const meta of wireInheritedMiddleware) {
       if (meta.type === 'http') {
         // Look up HTTP middleware group from pikkuState
-        const group = pikkuState('middleware', 'httpGroup')[meta.route]
+        const group = pikkuState(packageName, 'middleware', 'httpGroup')[
+          meta.route
+        ]
         if (group) {
           // At runtime, all factories should be resolved to middleware
           resolved.push(...(group as CorePikkuMiddleware[]))
         }
       } else if (meta.type === 'tag') {
         // Look up tag middleware group from pikkuState
-        const group = pikkuState('middleware', 'tagGroup')[meta.tag]
+        const group = pikkuState(packageName, 'middleware', 'tagGroup')[
+          meta.tag
+        ]
         if (group) {
           // At runtime, all factories should be resolved to middleware
           resolved.push(...(group as CorePikkuMiddleware[]))
@@ -202,7 +207,9 @@ export const combineMiddleware = (
     for (const meta of funcInheritedMiddleware) {
       if (meta.type === 'tag') {
         // Look up tag middleware group from pikkuState
-        const group = pikkuState('middleware', 'tagGroup')[meta.tag]
+        const group = pikkuState(packageName, 'middleware', 'tagGroup')[
+          meta.tag
+        ]
         if (group) {
           // At runtime, all factories should be resolved to middleware
           resolved.push(...(group as CorePikkuMiddleware[]))

package/src/permissions.test.ts

@@ -1,18 +1,39 @@
 import { describe, test, beforeEach } from 'node:test'
 import * as assert from 'node:assert'
-import {
-  addPermission,
-  getPermissionsForTags,
-  runPermissions,
-} from './permissions.js'
-import { resetPikkuState } from './pikku-state.js'
+import { addPermission, runPermissions } from './permissions.js'
+import { pikkuState, resetPikkuState } from './pikku-state.js'
 import { CoreServices, CoreUserSession } from './types/core.types.js'
-import { CorePermissionGroup } from './function/functions.types.js'
+import {
+  CorePermissionGroup,
+  CorePikkuPermission,
+} from './function/functions.types.js'
 
 beforeEach(() => {
   resetPikkuState()
 })
 
+// Test helper to get permissions for tags (not exported from core to keep it lean)
+const getPermissionsForTags = (
+  tags?: string[]
+): (CorePermissionGroup | CorePikkuPermission)[] => {
+  if (!tags || tags.length === 0) {
+    return []
+  }
+  const permissionsStore = pikkuState(null, 'permissions', 'tagGroup')
+  const result: (CorePermissionGroup | CorePikkuPermission)[] = []
+  for (const tag of new Set(tags)) {
+    const tagPermissions = permissionsStore[tag]
+    if (tagPermissions) {
+      if (Array.isArray(tagPermissions)) {
+        result.push(...tagPermissions)
+      } else {
+        result.push(tagPermissions)
+      }
+    }
+  }
+  return result
+}
+
 const mockServices: CoreServices = {
   logger: {
     info: () => {},
@@ -78,85 +99,6 @@ describe('addPermission', () => {
   })
 })
 
-describe('getPermissionsForTags', () => {
-  test('should return empty array when no tags provided', () => {
-    const permissions = getPermissionsForTags([])
-    assert.deepEqual(permissions, [])
-  })
-
-  test('should return empty array when tags is undefined', () => {
-    const permissions = getPermissionsForTags(undefined)
-    assert.deepEqual(permissions, [])
-  })
-
-  test('should return permissions for single tag', () => {
-    const mockPermission = async () => true
-    addPermission('singleTestTag', [mockPermission])
-
-    const permissions = getPermissionsForTags(['singleTestTag'])
-    assert.equal(permissions.length, 1)
-    assert.equal(permissions[0], mockPermission)
-  })
-
-  test('should return permissions for multiple tags', () => {
-    const mockPermission1 = async () => true
-    const mockPermission2 = async () => false
-
-    addPermission('tag1', [mockPermission1])
-    addPermission('tag2', [mockPermission2])
-
-    const permissions = getPermissionsForTags(['tag1', 'tag2'])
-    assert.equal(permissions.length, 2)
-    assert.equal(permissions[0], mockPermission1)
-    assert.equal(permissions[1], mockPermission2)
-  })
-
-  test('should handle array permissions correctly', () => {
-    const mockPermission1 = async () => true
-    const mockPermission2 = async () => false
-
-    addPermission('arrayHandleTestTag', [mockPermission1, mockPermission2])
-
-    const permissions = getPermissionsForTags(['arrayHandleTestTag'])
-    assert.equal(permissions.length, 2)
-    assert.equal(permissions[0], mockPermission1)
-    assert.equal(permissions[1], mockPermission2)
-  })
-
-  test('should handle non-array permissions correctly', () => {
-    const mockPermissionGroup: CorePermissionGroup = {
-      permissions: [async () => true],
-    }
-
-    addPermission('objectHandleTestTag', mockPermissionGroup)
-
-    const permissions = getPermissionsForTags(['objectHandleTestTag'])
-    assert.equal(permissions.length, 1)
-    assert.equal(permissions[0], mockPermissionGroup)
-  })
-
-  test('should deduplicate tags', () => {
-    const mockPermission = async () => true
-    addPermission('dedupeTestTag', [mockPermission])
-
-    const permissions = getPermissionsForTags([
-      'dedupeTestTag',
-      'dedupeTestTag',
-    ])
-    assert.equal(permissions.length, 1)
-    assert.equal(permissions[0], mockPermission)
-  })
-
-  test('should ignore non-existent tags', () => {
-    const mockPermission = async () => true
-    addPermission('existingTag', [mockPermission])
-
-    const permissions = getPermissionsForTags(['existingTag', 'nonExistentTag'])
-    assert.equal(permissions.length, 1)
-    assert.equal(permissions[0], mockPermission)
-  })
-})
-
 describe('runPermissions', () => {
   test('should pass when no permissions are defined', async () => {
     // Should not throw