@pikku/core 0.11.0 → 0.11.2

package/dist/wirings/scheduler/scheduler-runner.d.ts

@@ -1,12 +1,12 @@
-import { type CoreServices, type CoreSingletonServices, type CoreUserSession, type CreateSessionServices } from '../../types/core.types.js';
+import { type CoreServices, type CoreSingletonServices, type CoreUserSession, type CreateWireServices } from '../../types/core.types.js';
 import type { CoreScheduledTask } from './scheduler.types.js';
 import { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 export type RunScheduledTasksParams = {
     name: string;
     session?: CoreUserSession;
     singletonServices: CoreSingletonServices;
-    createSessionServices?: CreateSessionServices<CoreSingletonServices, CoreServices<CoreSingletonServices>, CoreUserSession>;
+    createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices<CoreSingletonServices>, CoreUserSession>;
 };
 export declare const wireScheduler: <PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunctionSessionless<void, void>>>(scheduledTask: CoreScheduledTask<PikkuFunctionConfig>) => void;
-export declare function runScheduledTask({ name, session, singletonServices, createSessionServices, }: RunScheduledTasksParams): Promise<void>;
+export declare function runScheduledTask({ name, session, singletonServices, createWireServices, }: RunScheduledTasksParams): Promise<void>;
 export declare const getScheduledTasks: () => Map<string, CoreScheduledTask>;

package/dist/wirings/scheduler/scheduler-runner.js

@@ -1,12 +1,10 @@
-import { PikkuWiringTypes, } from '../../types/core.types.js';
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js';
-import { closeSessionServices } from '../../utils.js';
+import { closeWireServices } from '../../utils.js';
 import { pikkuState } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
-import { rpcService } from '../rpc/rpc-runner.js';
-import { PikkuUserSessionService } from '../../services/user-session-service.js';
+import { PikkuSessionService } from '../../services/user-session-service.js';
 export const wireScheduler = (scheduledTask) => {
-    const meta = pikkuState('scheduler', 'meta');
+    const meta = pikkuState(null, 'scheduler', 'meta');
     const taskMeta = meta[scheduledTask.name];
     if (!taskMeta) {
         throw new Error('Task metadata not found');
@@ -17,9 +15,8 @@ export const wireScheduler = (scheduledTask) => {
         permissions: scheduledTask.func.permissions,
         middleware: scheduledTask.func.middleware,
         tags: scheduledTask.func.tags,
-        docs: scheduledTask.func.docs,
     });
-    const tasks = pikkuState('scheduler', 'tasks');
+    const tasks = pikkuState(null, 'scheduler', 'tasks');
     if (tasks.has(scheduledTask.name)) {
         throw new Error(`Scheduled task already exists: ${scheduledTask.name}`);
     }
@@ -36,11 +33,11 @@ class ScheduledTaskSkippedError extends PikkuError {
         this.name = 'ScheduledTaskSkippedError';
     }
 }
-export async function runScheduledTask({ name, session, singletonServices, createSessionServices, }) {
-    let sessionServices;
-    const task = pikkuState('scheduler', 'tasks').get(name);
-    const meta = pikkuState('scheduler', 'meta')[name];
-    const userSession = new PikkuUserSessionService();
+export async function runScheduledTask({ name, session, singletonServices, createWireServices, }) {
+    let wireServices;
+    const task = pikkuState(null, 'scheduler', 'tasks').get(name);
+    const meta = pikkuState(null, 'scheduler', 'meta')[name];
+    const userSession = new PikkuSessionService();
     if (session) {
         userSession.set(session);
     }
@@ -50,8 +47,8 @@ export async function runScheduledTask({ name, session, singletonServices, creat
     if (!meta) {
         throw new ScheduledTaskNotFoundError(`Scheduled task meta not found: ${name}`);
     }
-    // Create the scheduled task interaction object
-    const interaction = {
+    // Create the scheduled task wire object
+    const wire = {
         scheduledTask: {
             name,
             schedule: task.schedule,
@@ -60,28 +57,20 @@ export async function runScheduledTask({ name, session, singletonServices, creat
                 throw new ScheduledTaskSkippedError(name, reason);
             },
         },
+        session: userSession,
     };
     try {
         singletonServices.logger.info(`Running schedule task: ${name} | schedule: ${task.schedule}`);
-        const getAllServices = async () => {
-            sessionServices = await createSessionServices?.(singletonServices, interaction, session);
-            return rpcService.injectRPCService({
-                ...singletonServices,
-                ...sessionServices,
-            }, interaction);
-        };
-        const result = await runPikkuFunc(PikkuWiringTypes.scheduler, meta.name, meta.pikkuFuncName, {
+        await runPikkuFunc('scheduler', meta.name, meta.pikkuFuncName, {
             singletonServices,
-            getAllServices,
-            userSession,
+            createWireServices,
             auth: false,
             data: () => undefined,
             inheritedMiddleware: meta.middleware,
             wireMiddleware: task.middleware,
             tags: task.tags,
-            interaction,
+            wire,
         });
-        return result;
     }
     catch (e) {
         const errorResponse = getErrorResponse(e);
@@ -91,11 +80,11 @@ export async function runScheduledTask({ name, session, singletonServices, creat
         throw e;
     }
     finally {
-        if (sessionServices) {
-            await closeSessionServices(singletonServices.logger, sessionServices);
+        if (wireServices) {
+            await closeWireServices(singletonServices.logger, wireServices);
         }
     }
 }
 export const getScheduledTasks = () => {
-    return pikkuState('scheduler', 'tasks');
+    return pikkuState(null, 'scheduler', 'tasks');
 };

package/dist/wirings/scheduler/scheduler.types.d.ts

@@ -1,16 +1,12 @@
-import { PikkuDocs, CoreUserSession, CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
+import { CoreUserSession, CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
 import { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 /**
  * Represents metadata for scheduled tasks, including title, schedule, and documentation.
  */
-export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Record<string, {
-    pikkuFuncName: string;
+export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Record<string, CommonWireMeta & {
     name: string;
     schedule: string;
     session?: UserSession;
-    docs?: PikkuDocs;
-    tags?: string[];
-    middleware?: MiddlewareMetadata[];
 }>;
 /**
  * Represents a core scheduled task.
@@ -19,12 +15,11 @@ export type CoreScheduledTask<PikkuFunctionConfig = CorePikkuFunctionConfig<Core
     name: string;
     schedule: string;
     func: PikkuFunctionConfig;
-    docs?: PikkuDocs;
     tags?: string[];
     middleware?: PikkuMiddleware[];
 };
 /**
- * Represents a scheduled task interaction object for middleware
+ * Represents a scheduled task wire object for middleware
  * Provides information about the current scheduled task execution
  */
 export interface PikkuScheduledTask {

package/dist/wirings/trigger/index.d.ts

@@ -0,0 +1,2 @@
+export * from './trigger.types.js';
+export * from './trigger-runner.js';

package/dist/wirings/trigger/index.js

@@ -0,0 +1,2 @@
+export * from './trigger.types.js';
+export * from './trigger-runner.js';

package/dist/wirings/trigger/trigger-runner.d.ts

@@ -0,0 +1,29 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { CoreTrigger, TriggerInstance } from './trigger.types.js';
+import type { CorePikkuTriggerFunctionConfig } from '../../function/functions.types.js';
+/**
+ * Registers a trigger with the Pikku framework.
+ * The trigger will be available for setup via setupTrigger.
+ */
+export declare const wireTrigger: <TConfig = unknown, TOutput = unknown, TriggerFunctionConfig extends CorePikkuTriggerFunctionConfig<TConfig, TOutput> = CorePikkuTriggerFunctionConfig<TConfig, TOutput>>(trigger: CoreTrigger<TConfig, TOutput, TriggerFunctionConfig>) => void;
+/**
+ * Parameters for setting up a trigger
+ */
+export type SetupTriggerParams<TOutput = unknown> = {
+    name: string;
+    singletonServices: CoreSingletonServices;
+    onTrigger: (data: TOutput) => void | Promise<void>;
+};
+/**
+ * Sets up a registered trigger and starts listening for events.
+ * Returns a TriggerInstance with a teardown function.
+ */
+export declare function setupTrigger<TOutput = unknown>({ name, singletonServices, onTrigger, }: SetupTriggerParams<TOutput>): Promise<TriggerInstance>;
+/**
+ * Gets all registered triggers
+ */
+export declare const getRegisteredTriggers: () => Map<string, CoreTrigger<unknown, unknown, CorePikkuTriggerFunctionConfig<unknown, unknown>>>;
+/**
+ * Gets trigger metadata
+ */
+export declare const getTriggerMeta: () => import("./trigger.types.js").TriggerMeta;

package/dist/wirings/trigger/trigger-runner.js

@@ -0,0 +1,57 @@
+import { pikkuState } from '../../pikku-state.js';
+/**
+ * Registers a trigger with the Pikku framework.
+ * The trigger will be available for setup via setupTrigger.
+ */
+export const wireTrigger = (trigger) => {
+    const meta = pikkuState(null, 'trigger', 'meta');
+    const triggerMeta = meta[trigger.name];
+    if (!triggerMeta) {
+        throw new Error(`Trigger metadata not found: ${trigger.name}`);
+    }
+    const triggers = pikkuState(null, 'trigger', 'triggers');
+    if (triggers.has(trigger.name)) {
+        throw new Error(`Trigger already exists: ${trigger.name}`);
+    }
+    triggers.set(trigger.name, trigger);
+};
+/**
+ * Sets up a registered trigger and starts listening for events.
+ * Returns a TriggerInstance with a teardown function.
+ */
+export async function setupTrigger({ name, singletonServices, onTrigger, }) {
+    const trigger = pikkuState(null, 'trigger', 'triggers').get(name);
+    const meta = pikkuState(null, 'trigger', 'meta')[name];
+    if (!trigger) {
+        throw new Error(`Trigger not found: ${name}`);
+    }
+    if (!meta) {
+        throw new Error(`Trigger metadata not found: ${name}`);
+    }
+    const wire = {
+        trigger: {
+            trigger: (data) => {
+                singletonServices.logger.info(`Trigger fired: ${name}`);
+                onTrigger(data);
+            },
+        },
+    };
+    singletonServices.logger.info(`Setting up trigger: ${name}`);
+    const teardown = await trigger.func.func(singletonServices, trigger.config, wire);
+    return {
+        name,
+        teardown,
+    };
+}
+/**
+ * Gets all registered triggers
+ */
+export const getRegisteredTriggers = () => {
+    return pikkuState(null, 'trigger', 'triggers');
+};
+/**
+ * Gets trigger metadata
+ */
+export const getTriggerMeta = () => {
+    return pikkuState(null, 'trigger', 'meta');
+};

package/dist/wirings/trigger/trigger.types.d.ts

@@ -0,0 +1,42 @@
+import type { CorePikkuTriggerFunctionConfig } from '../../function/functions.types.js';
+/**
+ * The trigger interaction object passed to trigger functions via the wire.
+ * Call trigger() to fire the trigger and start a new workflow/execution.
+ */
+export interface PikkuTrigger<TOutput = unknown> {
+    trigger: (data: TOutput) => void;
+}
+/**
+ * Metadata for registered triggers stored in state.
+ */
+export type TriggerMeta = Record<string, {
+    pikkuFuncName: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+}>;
+/**
+ * Core trigger definition for registration.
+ *
+ * @template TConfig - Configuration type
+ * @template TOutput - Output type
+ */
+export interface CoreTrigger<TConfig = unknown, TOutput = unknown, TriggerFunctionConfig extends CorePikkuTriggerFunctionConfig<TConfig, TOutput> = CorePikkuTriggerFunctionConfig<TConfig, TOutput>> {
+    /** Unique name for this trigger */
+    name: string;
+    /** The trigger function configuration */
+    func: TriggerFunctionConfig;
+    /** Configuration to pass to the trigger function */
+    config: TConfig;
+    /** Optional description */
+    description?: string;
+    /** Optional tags for categorization */
+    tags?: string[];
+}
+/**
+ * Represents a trigger instance with teardown capability
+ */
+export interface TriggerInstance {
+    name: string;
+    teardown: () => void | Promise<void>;
+}

package/dist/wirings/trigger/trigger.types.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/workflow/dsl/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * DSL (Domain Specific Language) workflow exports
+ */
+export { addWorkflow } from './workflow-runner.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow-dsl.types.js';

package/dist/wirings/workflow/dsl/index.js

@@ -0,0 +1,4 @@
+/**
+ * DSL (Domain Specific Language) workflow exports
+ */
+export { addWorkflow } from './workflow-runner.js';

package/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -0,0 +1,286 @@
+/**
+ * DSL (Domain Specific Language) workflow types
+ * These types define the step-based workflow format extracted by the inspector
+ */
+import type { WorkflowRun } from '../workflow.types.js';
+/**
+ * Workflow step options
+ */
+export interface WorkflowStepOptions {
+    /** Display name for logs/UI (optional, doesn't affect execution) */
+    description?: string;
+    /** Number of retry attempts for failed steps (only applies to local execution) */
+    retries?: number;
+    /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
+    retryDelay?: string | number;
+}
+/**
+ * Type signature for workflow.do() RPC form - used by inspector
+ */
+export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(stepName: string, rpcName: string, data: TInput, options?: WorkflowStepOptions) => Promise<TOutput>;
+/**
+ * Type signature for workflow.do() inline form - used by inspector
+ */
+export type WorkflowWireDoInline = <T>(stepName: string, fn: () => Promise<T> | T, options?: WorkflowStepOptions) => Promise<T>;
+/**
+ * Type signature for workflow.sleep() - used by inspector
+ */
+export type WorkflowWireSleep = (stepName: string, duration: string) => Promise<void>;
+/**
+ * Input source for step arguments in DSL workflows
+ */
+export type InputSource = {
+    from: 'input';
+    path: string;
+} | {
+    from: 'outputVar';
+    name: string;
+    path?: string;
+} | {
+    from: 'item';
+    path: string;
+} | {
+    from: 'literal';
+    value: unknown;
+} | {
+    from: 'template';
+    parts: string[];
+    expressions: InputSource[];
+};
+/**
+ * Output binding for return statements in DSL workflows
+ */
+export type OutputBinding = {
+    from: 'outputVar';
+    name: string;
+    path?: string;
+} | {
+    from: 'stateVar';
+    name: string;
+    path?: string;
+} | {
+    from: 'input';
+    path: string;
+} | {
+    from: 'literal';
+    value: unknown;
+} | {
+    from: 'expression';
+    expression: string;
+};
+/**
+ * RPC step metadata (base form)
+ */
+export interface RpcStepMeta {
+    /** RPC form - generates queue worker */
+    type: 'rpc';
+    /** Cache key (stepName from workflow.do) */
+    stepName: string;
+    /** RPC to invoke */
+    rpcName: string;
+    /** Output variable name (if assigned) */
+    outputVar?: string;
+    /** Input source mappings, or 'passthrough' when entire data is passed */
+    inputs?: Record<string, InputSource> | 'passthrough';
+    /** Step options */
+    options?: WorkflowStepOptions;
+}
+/**
+ * Simple condition expression (leaf node)
+ */
+export interface SimpleCondition {
+    type: 'simple';
+    expression: string;
+}
+/**
+ * Nested condition structure supporting AND/OR operations
+ */
+export type Condition = SimpleCondition | {
+    type: 'and';
+    conditions: Condition[];
+} | {
+    type: 'or';
+    conditions: Condition[];
+};
+/**
+ * A single branch in an if/else-if chain
+ */
+export interface BranchCase {
+    /** Condition for this branch */
+    condition: Condition;
+    /** Steps to execute when condition is true */
+    steps: WorkflowStepMeta[];
+}
+/**
+ * Branch step metadata (if/else-if/else control flow)
+ */
+export interface BranchStepMeta {
+    type: 'branch';
+    /** Branches in order: first is "if", rest are "else if" */
+    branches: BranchCase[];
+    /** Else branch steps (when no conditions match) */
+    elseSteps?: WorkflowStepMeta[];
+}
+/**
+ * Parallel group step metadata (Promise.all with multiple steps)
+ */
+export interface ParallelGroupStepMeta {
+    type: 'parallel';
+    /** Child steps to execute in parallel */
+    children: RpcStepMeta[];
+}
+/**
+ * Fanout step metadata (parallel or sequential iteration)
+ */
+export interface FanoutStepMeta {
+    type: 'fanout';
+    /** Step name for this fanout */
+    stepName: string;
+    /** Source array variable name */
+    sourceVar: string;
+    /** Iterator variable name */
+    itemVar: string;
+    /** Execution mode */
+    mode: 'parallel' | 'sequential';
+    /** Child step to execute per iteration */
+    child: RpcStepMeta;
+    /** Time between iterations (sequential mode only) */
+    timeBetween?: string;
+}
+/**
+ * Return step metadata (workflow output)
+ */
+export interface ReturnStepMeta {
+    type: 'return';
+    /** Output bindings */
+    outputs: Record<string, OutputBinding>;
+}
+/**
+ * Inline step metadata (legacy support)
+ */
+export interface InlineStepMeta {
+    /** Inline form - local execution */
+    type: 'inline';
+    /** Cache key (stepName from workflow.do) */
+    stepName: string;
+    /** Display name */
+    description?: string;
+    /** Step options */
+    options?: WorkflowStepOptions;
+}
+/**
+ * Sleep step metadata
+ */
+export interface SleepStepMeta {
+    /** Sleep step */
+    type: 'sleep';
+    /** Cache key (stepName from workflow.sleep) */
+    stepName: string;
+    /** Sleep duration */
+    duration: string | number;
+}
+/**
+ * Cancel step metadata
+ */
+export interface CancelStepMeta {
+    /** Cancel step */
+    type: 'cancel';
+    /** Optional cancellation reason */
+    reason?: string;
+}
+/**
+ * Set step metadata (context variable assignment)
+ */
+export interface SetStepMeta {
+    /** Set step */
+    type: 'set';
+    /** Variable name to set (must be in context) */
+    variable: string;
+    /** Value to assign (literal or expression) */
+    value: unknown;
+}
+/**
+ * Switch case metadata
+ */
+export interface SwitchCaseMeta {
+    /** Case value (literal) or expression */
+    value?: string | number | boolean | null;
+    /** Case expression (for complex cases) */
+    expression?: string;
+    /** Steps to execute for this case */
+    steps: WorkflowStepMeta[];
+}
+/**
+ * Switch step metadata (switch/case control flow)
+ */
+export interface SwitchStepMeta {
+    type: 'switch';
+    /** Expression being switched on */
+    expression: string;
+    /** Case branches */
+    cases: SwitchCaseMeta[];
+    /** Default case steps (optional) */
+    defaultSteps?: WorkflowStepMeta[];
+}
+/**
+ * Filter step metadata (array.filter)
+ */
+export interface FilterStepMeta {
+    type: 'filter';
+    /** Source array variable name */
+    sourceVar: string;
+    /** Iterator variable name */
+    itemVar: string;
+    /** Filter condition */
+    condition: Condition;
+    /** Output variable name (if assigned) */
+    outputVar?: string;
+}
+/**
+ * Array predicate step metadata (array.some, array.every)
+ */
+export interface ArrayPredicateStepMeta {
+    type: 'arrayPredicate';
+    /** Predicate mode */
+    mode: 'some' | 'every';
+    /** Source array variable name */
+    sourceVar: string;
+    /** Iterator variable name */
+    itemVar: string;
+    /** Predicate condition */
+    condition: Condition;
+    /** Output variable name (if assigned) */
+    outputVar?: string;
+}
+/**
+ * Workflow step metadata (extracted by inspector)
+ */
+export type WorkflowStepMeta = RpcStepMeta | BranchStepMeta | ParallelGroupStepMeta | FanoutStepMeta | ReturnStepMeta | InlineStepMeta | SleepStepMeta | CancelStepMeta | SwitchStepMeta | FilterStepMeta | ArrayPredicateStepMeta | SetStepMeta;
+/**
+ * Workflow step wire context for RPC functions
+ * Provides step-level metadata including retry attempt tracking
+ */
+export interface WorkflowStepWire {
+    /** The workflow run ID */
+    runId: string;
+    /** The unique step ID */
+    stepId: string;
+    /** Current attempt number (1-indexed, increments on retry) */
+    attemptCount: number;
+}
+/**
+ * Workflow wire object for DSL workflows
+ * Provides workflow-specific capabilities to function execution
+ */
+export interface PikkuWorkflowWire {
+    /** The workflow name */
+    workflowName: string;
+    /** The current run ID */
+    runId: string;
+    /** Get the current workflow run */
+    getRun: () => Promise<WorkflowRun>;
+    /** Execute a workflow step (overloaded - RPC or inline form) */
+    do: WorkflowWireDoRPC & WorkflowWireDoInline;
+    /** Sleep for a duration */
+    sleep: WorkflowWireSleep;
+}

package/dist/wirings/workflow/dsl/workflow-dsl.types.js

@@ -0,0 +1,5 @@
+/**
+ * DSL (Domain Specific Language) workflow types
+ * These types define the step-based workflow format extracted by the inspector
+ */
+export {};

package/dist/wirings/workflow/dsl/workflow-runner.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Add a workflow to the system
+ * This is called by the generated workflow wirings
+ */
+export declare const addWorkflow: (workflowName: string, workflowFunc: any) => void;

package/dist/wirings/workflow/dsl/workflow-runner.js

@@ -0,0 +1,22 @@
+import { pikkuState } from '../../../pikku-state.js';
+import { addFunction } from '../../../function/function-runner.js';
+/**
+ * Add a workflow to the system
+ * This is called by the generated workflow wirings
+ */
+export const addWorkflow = (workflowName, workflowFunc) => {
+    // Get workflow metadata from inspector
+    const meta = pikkuState(null, 'workflows', 'meta');
+    const workflowMeta = meta[workflowName];
+    if (!workflowMeta) {
+        throw new Error(`Workflow metadata not found for '${workflowName}'. Make sure to run the CLI to generate metadata.`);
+    }
+    // Store workflow definition in state
+    const registrations = pikkuState(null, 'workflows', 'registrations');
+    registrations.set(workflowName, {
+        name: workflowName,
+        func: workflowFunc,
+    });
+    // Register the function with pikku
+    addFunction(workflowMeta.pikkuFuncName, workflowFunc);
+};