@pikku/core 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,12 +1,46 @@
 ## 0.11.0
 
+## 0.11.2
+
+### Patch Changes
+
+- db9c7bf: Add workflow graph system with type-safe builder
+
+## 0.11.2
+
+### Features
+
+- f35e89da: Add workflow graph system with type-safe builder
+  - `createGraph<RPCMap>()` for building workflow graphs with full type safety
+  - `wireWorkflowGraph()` for registering workflow graphs
+  - `graphNode()` helper for type-safe node creation
+  - Graph scheduler for execution (continueGraph, startWorkflowGraph)
+  - TypedRef for type-safe input refs in workflow graphs
+  - `setBranchTaken` added to WorkflowService interface
+  - Trigger runner for workflow triggers
+
+### Breaking Changes
+
+- Rename `pikkuWorkflowFunc` to `pikkuWorkflowComplexFunc`
+- Rename `pikkuWorkflowDSTFunc` to `pikkuWorkflowFunc`
+
+## 0.11.1
+
+### Patch Changes
+
+- 4b811db: chore: updating all dependencies
+- e12a00c: feat: adding initialSession to PikkuWire which is correctly typed (undefined / not depending on function type)
+- 4579434: breaking: changing the signature of functions
+- 28aeb7f: breaking: extract docs in the wiring meta
+- ce902b1: feat: adding in pikkuSimpleWorkflowFunc
+- 06e1a31: breaking: change session services to wire services
+
 ### Minor Changes
 
 - Add workflow orchestration engine with step execution and retries
 - Add scheduler service abstraction
 - Remove file-based channel and eventhub stores
 
-
 # @pikku/core
 
 ## 0.10.2

package/dist/errors/error-handler.js

@@ -19,7 +19,7 @@ export class PikkuError extends Error {
  * @param details - The details of the error.
  */
 export const addError = (error, { status, message }) => {
-    pikkuState('misc', 'errors').set(error, { status, message });
+    pikkuState(null, 'misc', 'errors').set(error, { status, message });
 };
 /**
  * Adds multiple errors to the API errors map.
@@ -36,10 +36,10 @@ export const addErrors = (errors) => {
  * @returns An object containing the status and message, or undefined if the error is not found.
  */
 export const getErrorResponse = (error) => {
-    const errors = Array.from(pikkuState('misc', 'errors').entries());
+    const errors = Array.from(pikkuState(null, 'misc', 'errors').entries());
     const foundError = errors.find(([e]) => e.name === error.constructor.name);
     if (foundError) {
         return foundError[1];
     }
-    return pikkuState('misc', 'errors').get(error);
+    return pikkuState(null, 'misc', 'errors').get(error);
 };

package/dist/errors/errors.d.ts

@@ -2,7 +2,7 @@
  * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
  */
 import { PikkuError } from './error-handler.js';
-export declare class InvalidMiddlewareInteractionError extends PikkuError {
+export declare class InvalidMiddlewareWireError extends PikkuError {
 }
 /**
  * The server cannot or will not process the request due to client error (e.g., malformed request syntax).

package/dist/errors/errors.js

@@ -2,11 +2,11 @@
  * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
  */
 import { addError, PikkuError } from './error-handler.js';
-export class InvalidMiddlewareInteractionError extends PikkuError {
+export class InvalidMiddlewareWireError extends PikkuError {
 }
-addError(InvalidMiddlewareInteractionError, {
+addError(InvalidMiddlewareWireError, {
     status: 500,
-    message: 'The middleware interaction is invalid for the current wiring type.',
+    message: 'The middleware wire is invalid for the current wiring type.',
 });
 /**
  * The server cannot or will not process the request due to client error (e.g., malformed request syntax).

package/dist/function/function-runner.d.ts

@@ -1,12 +1,11 @@
-import { CoreServices, CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, CoreSingletonServices, PikkuInteraction, MiddlewareMetadata, PermissionMetadata } from '../types/core.types.js';
+import { CoreServices, CoreUserSession, CorePikkuMiddleware, PikkuWiringTypes, PikkuWire, MiddlewareMetadata, PermissionMetadata, CoreSingletonServices, CreateWireServices } from '../types/core.types.js';
 import { CorePermissionGroup, CorePikkuFunctionConfig, CorePikkuPermission } from './functions.types.js';
-import { UserSessionService } from '../services/user-session-service.js';
-export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>) => void;
-export declare const runPikkuFuncDirectly: <In, Out>(funcName: string, allServices: CoreServices, data: In, session?: CoreUserSession) => Promise<Out>;
-export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { getAllServices, singletonServices, data, userSession, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags, interaction, }: {
+import { SessionService } from '../services/user-session-service.js';
+export declare const addFunction: (funcName: string, funcConfig: CorePikkuFunctionConfig<any, any>, packageName?: string | null) => void;
+export declare const runPikkuFuncDirectly: <In, Out>(funcName: string, allServices: CoreServices, wire: PikkuWire, data: In, userSession?: SessionService<CoreUserSession>, packageName?: string | null) => Promise<Out>;
+export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTypes, wireId: string, funcName: string, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags, wire, packageName, }: {
     singletonServices: CoreSingletonServices;
-    getAllServices: (session?: CoreUserSession) => Promise<CoreServices> | CoreServices;
-    userSession?: UserSessionService<CoreUserSession>;
+    createWireServices?: CreateWireServices;
     data: () => Promise<In> | In;
     auth?: boolean;
     inheritedMiddleware?: MiddlewareMetadata[];
@@ -15,5 +14,6 @@ export declare const runPikkuFunc: <In = any, Out = any>(wireType: PikkuWiringTy
     wirePermissions?: CorePermissionGroup | CorePikkuPermission[];
     coerceDataFromSchema?: boolean;
     tags?: string[];
-    interaction: PikkuInteraction;
+    wire: PikkuWire;
+    packageName?: string | null;
 }) => Promise<Out>;

package/dist/function/function-runner.js

@@ -3,25 +3,76 @@ import { runPermissions } from '../permissions.js';
 import { pikkuState } from '../pikku-state.js';
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js';
 import { ForbiddenError } from '../errors/errors.js';
-export const addFunction = (funcName, funcConfig) => {
-    pikkuState('function', 'functions').set(funcName, funcConfig);
+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, parentServices) => {
+    // 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 = 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 runPikkuFuncDirectly = async (funcName, allServices, data, session) => {
-    const funcConfig = pikkuState('function', 'functions').get(funcName);
+export const addFunction = (funcName, funcConfig, packageName = null) => {
+    pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig);
+};
+export const runPikkuFuncDirectly = async (funcName, allServices, wire, data, userSession, packageName = null) => {
+    const funcConfig = pikkuState(packageName, 'function', 'functions').get(funcName);
     if (!funcConfig) {
         throw new Error(`Function not found: ${funcName}`);
     }
-    return (await funcConfig.func(allServices, data, session));
+    // Inject session into wire
+    const wireWithSession = {
+        ...wire,
+        session: userSession,
+    };
+    return (await funcConfig.func(allServices, data, wireWithSession));
 };
-export const runPikkuFunc = async (wireType, wireId, funcName, { getAllServices, singletonServices, data, userSession, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags = [], interaction, }) => {
-    const funcConfig = pikkuState('function', 'functions').get(funcName);
+export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServices, createWireServices, data, auth: wiringAuth, inheritedMiddleware, wireMiddleware, inheritedPermissions, wirePermissions, coerceDataFromSchema, tags = [], wire, packageName = null, }) => {
+    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 = [
         ...(inheritedPermissions || []),
@@ -29,16 +80,21 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { getAllServices,
     ];
     // Helper function to run permissions and execute the function
     const executeFunction = async () => {
-        const session = await userSession?.get();
+        const initialSession = wire.session?.freezeInitial();
+        const wireWithInitialSession = {
+            ...wire,
+            initialSession,
+        };
         if (wiringAuth === true || funcConfig.auth === true) {
             // This means it was explicitly enabled in either wiring or function and has to be respected
-            if (!session) {
+            if (!initialSession) {
                 throw new ForbiddenError('Authentication required');
             }
         }
         if (wiringAuth === undefined && funcConfig.auth === undefined) {
             // We always default to requiring auth unless explicitly disabled
-            if (!session) {
+            if (!initialSession) {
+                // TODO: Critical, we need to figure out how to make this work with different wirings
                 // throw new ForbiddenError('Authentication required')
             }
         }
@@ -48,37 +104,46 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { getAllServices,
         const inputSchemaName = funcMeta.inputSchemaName;
         if (inputSchemaName) {
             // Validate request data against the defined schema, if any
-            await validateSchema(singletonServices.logger, singletonServices.schema, inputSchemaName, actualData);
+            await validateSchema(resolvedSingletonServices.logger, resolvedSingletonServices.schema, inputSchemaName, 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);
             }
         }
-        const allServices = await getAllServices(session);
-        // Run permissions check with combined permissions: inheritedPermissions (including tags) → wirePermissions → funcPermissions
         await runPermissions(wireType, wireId, {
             wireInheritedPermissions: mergedInheritedPermissions,
             wirePermissions: wirePermissions,
             funcInheritedPermissions: funcMeta.permissions,
             funcPermissions: funcConfig.permissions,
-            allServices,
+            services: resolvedSingletonServices,
+            wire: { ...wireWithInitialSession, rpc: undefined },
             data: actualData,
-            session,
+            packageName,
         });
-        return await funcConfig.func(allServices, actualData, session);
+        const wireServices = await resolvedCreateWireServices?.(resolvedSingletonServices, wireWithInitialSession);
+        try {
+            const services = { ...resolvedSingletonServices, ...wireServices };
+            const rpc = rpcService.getContextRPCService(services, wireWithInitialSession);
+            return await funcConfig.func(services, actualData, {
+                ...wireWithInitialSession,
+                rpc,
+            });
+        }
+        finally {
+            if (wireServices) {
+                await closeWireServices(resolvedSingletonServices.logger, wireServices);
+            }
+        }
     };
-    // Combine all middleware: inheritedMiddleware → wireMiddleware → funcMiddleware
     const allMiddleware = combineMiddleware(wireType, wireId, {
         wireInheritedMiddleware: inheritedMiddleware,
         wireMiddleware,
         funcInheritedMiddleware: funcMeta.middleware,
         funcMiddleware: funcConfig.middleware,
+        packageName,
     });
     if (allMiddleware.length > 0) {
-        return (await runMiddleware({
-            ...singletonServices,
-            userSession,
-        }, interaction, allMiddleware, executeFunction));
+        return (await runMiddleware(resolvedSingletonServices, wire, allMiddleware, executeFunction));
     }
     return (await executeFunction());
 };

package/dist/function/functions.types.d.ts

@@ -1,33 +1,23 @@
-import { PikkuChannel } from '../wirings/channel/channel.types.js';
-import type { CoreServices, CoreSingletonServices, CoreUserSession, PikkuDocs, CorePikkuMiddleware } from '../types/core.types.js';
+import type { CoreServices, CoreSingletonServices, CoreUserSession, 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: Services, data: In, session: Session) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuFunction<In, Out, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, 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: Services, data: In, session?: Session) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuFunctionSessionless<In, Out, 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, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
 /**
  * Represents a function that checks permissions for a given operation.
  *
@@ -35,7 +25,7 @@ export type CorePikkuFunctionSessionless<In, Out, ChannelData extends unknown |
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
-export type CorePikkuPermission<In = any, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, data: In, session?: Session) => Promise<boolean>;
+export type CorePikkuPermission<In = any, Services extends CoreSingletonServices = CoreServices, 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
  *
@@ -43,11 +33,11 @@ export type CorePikkuPermission<In = any, Services extends CoreSingletonServices
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
-export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = {
+export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonServices = CoreServices, 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;
 };
@@ -59,22 +49,24 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonSe
  * ```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'
  *   }
  * })
  * ```
  */
-export declare const pikkuPermission: <In = any, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession>(permission: CorePikkuPermission<In, Services, Session> | CorePikkuPermissionConfig<In, Services, Session>) => CorePikkuPermission<In, Services, Session>;
+export declare const pikkuPermission: <In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PickRequired<PikkuWire<In, never, false, CoreUserSession>, "session"> = PickRequired<PikkuWire<In, never, false, CoreUserSession>, "session">>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
 /**
  * A factory function that takes input and returns a permission
  * Used when permissions need configuration/input parameters
@@ -83,7 +75,7 @@ export declare const pikkuPermission: <In = any, Services extends CoreSingletonS
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
-export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (input: In) => CorePikkuPermission<any, Services, Session>;
+export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<In, never, false, CoreUserSession>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
 /**
  * Factory function for creating permission factories
  * Use this when your permission needs configuration/input parameters
@@ -93,8 +85,9 @@ export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonS
  * 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
  *     }
@@ -105,14 +98,92 @@ export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonS
  */
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
 export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Record<string, PikkuPermission | PikkuPermission[]> | undefined;
-export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>> = {
-    name?: string;
+/**
+ * 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> | CorePikkuFunctionSessionless<any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends ZodLike | undefined = undefined, OutputSchema extends ZodLike | undefined = undefined> = {
+    /** 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 declare 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>;

package/dist/function/functions.types.js

@@ -6,17 +6,19 @@
  * ```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'
  *   }
  * })
  * ```
@@ -33,8 +35,9 @@ export const pikkuPermission = (permission) => {
  * 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
  *     }
@@ -46,3 +49,43 @@ export const pikkuPermission = (permission) => {
 export const pikkuPermissionFactory = (factory) => {
     return factory;
 };
+/**
+ * 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 = (triggerOrConfig) => {
+    if (typeof triggerOrConfig === 'function') {
+        return { func: triggerOrConfig };
+    }
+    return triggerOrConfig;
+};

package/dist/handle-error.d.ts

@@ -4,7 +4,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/dist/handle-error.js

@@ -4,7 +4,7 @@ import { NotFoundError } from './errors/errors.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/dist/index.d.ts

@@ -17,12 +17,16 @@ 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';
+export { 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/dist/index.js

@@ -17,12 +17,15 @@ 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';
+export { pikkuState, initializePikkuState, resetPikkuState, addPackageServiceFactories, } from './pikku-state.js';
+export { runMiddleware, addMiddleware } from './middleware-runner.js';
 export { addPermission } from './permissions.js';