@pikku/core 0.10.2 → 0.11.1

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

@@ -1,4 +1,3 @@
-import { PikkuWiringTypes, } from '../../types/core.types.js';
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { ForbiddenError } from '../../errors/errors.js';
@@ -13,11 +12,11 @@ const getPikkuFunctionName = (rpcName) => {
 // Context-aware RPC client for use within services
 export class ContextAwareRPCService {
     services;
-    interaction;
+    wire;
     options;
-    constructor(services, interaction, options) {
+    constructor(services, wire, options) {
         this.services = services;
-        this.interaction = interaction;
+        this.wire = wire;
         this.options = options;
     }
     async rpcExposed(funcName, data) {
@@ -31,27 +30,54 @@ export class ContextAwareRPCService {
         return await this.rpc(funcName, data);
     }
     async rpc(funcName, data) {
-        const rpcDepth = this.services.rpc?.depth || 0;
-        const pikkuFuncName = getPikkuFunctionName(funcName);
-        return runPikkuFunc(PikkuWiringTypes.rpc, pikkuFuncName, pikkuFuncName, {
+        const rpcDepth = this.wire.rpc?.depth || 0;
+        const updatedWire = {
+            ...this.wire,
+            rpc: this.wire.rpc
+                ? {
+                    ...this.wire.rpc,
+                    depth: rpcDepth + 1,
+                    global: false,
+                }
+                : undefined,
+        };
+        return runPikkuFunc('rpc', funcName, getPikkuFunctionName(funcName), {
             auth: this.options.requiresAuth,
+            // TODO: this is a hack since services have already been created
+            // but is valid since we don't want to keep creating new wire services
             singletonServices: this.services,
-            getAllServices: () => {
-                this.services.rpc = this.services.rpc
-                    ? {
-                        ...this.services.rpc,
-                        depth: rpcDepth + 1,
-                        global: false,
-                    }
-                    : undefined;
-                return this.services;
-            },
             data: () => data,
-            userSession: this.services.userSession,
             coerceDataFromSchema: this.options.coerceDataFromSchema,
-            interaction: this.interaction,
+            wire: updatedWire,
         });
     }
+    async rpcWithWire(rpcName, data, wire) {
+        const rpcDepth = this.wire.rpc?.depth || 0;
+        const mergedWire = {
+            ...this.wire,
+            ...wire,
+            rpc: this.wire.rpc
+                ? {
+                    ...this.wire.rpc,
+                    depth: rpcDepth + 1,
+                    global: false,
+                }
+                : undefined,
+        };
+        return runPikkuFunc('rpc', rpcName, getPikkuFunctionName(rpcName), {
+            auth: this.options.requiresAuth,
+            singletonServices: this.services,
+            data: () => data,
+            coerceDataFromSchema: this.options.coerceDataFromSchema,
+            wire: mergedWire,
+        });
+    }
+    async startWorkflow(workflowName, input) {
+        if (!this.services.workflowService) {
+            throw new Error('WorkflowService service not available');
+        }
+        return this.services.workflowService.startWorkflow(workflowName, input, this);
+    }
 }
 // RPC Service class for the global interface
 export class PikkuRPCService {
@@ -61,21 +87,19 @@ export class PikkuRPCService {
         this.config = config;
     }
     // Convenience function for initializing
-    injectRPCService(services, interaction, requiresAuth, depth = 0) {
-        const serviceCopy = {
-            ...services,
-        };
-        const serviceRPC = new ContextAwareRPCService(serviceCopy, interaction, {
+    getContextRPCService(services, wire, requiresAuth, depth = 0) {
+        const serviceRPC = new ContextAwareRPCService(services, wire, {
             coerceDataFromSchema: this.config?.coerceDataFromSchema,
             requiresAuth,
         });
-        serviceCopy.rpc = {
+        return {
             depth,
             global: false,
             invoke: serviceRPC.rpc.bind(serviceRPC),
             invokeExposed: serviceRPC.rpc.bind(serviceRPC),
+            startWorkflow: serviceRPC.startWorkflow.bind(serviceRPC),
+            rpcWithWire: serviceRPC.rpcWithWire.bind(serviceRPC),
         };
-        return serviceCopy;
     }
 }
 // Create a singleton instance

package/dist/wirings/rpc/rpc-types.d.ts

@@ -6,6 +6,7 @@ export type PikkuRPC<invoke extends Function = any> = {
 export type RPCMeta = {
     pikkuFuncName: string;
     expose: boolean;
+    internal?: boolean;
 };
 /**
  * Type for RPC handlers

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,10 +1,8 @@
-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 taskMeta = meta[scheduledTask.name];
@@ -17,7 +15,6 @@ 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');
     if (tasks.has(scheduledTask.name)) {
@@ -36,11 +33,11 @@ class ScheduledTaskSkippedError extends PikkuError {
         this.name = 'ScheduledTaskSkippedError';
     }
 }
-export async function runScheduledTask({ name, session, singletonServices, createSessionServices, }) {
-    let sessionServices;
+export async function runScheduledTask({ name, session, singletonServices, createWireServices, }) {
+    let wireServices;
     const task = pikkuState('scheduler', 'tasks').get(name);
     const meta = pikkuState('scheduler', 'meta')[name];
-    const userSession = new PikkuUserSessionService();
+    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,8 +80,8 @@ 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);
         }
     }
 }

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/workflow/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Workflow module exports
+ */
+export type { CoreWorkflow, WorkflowStepOptions, WorkflowStepMeta, RpcStepMeta, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, InputSource, OutputBinding, PikkuWorkflowWire, PikkuWorkflow, WorkflowsMeta, WorkflowRun, StepState, WorkflowStatus, StepStatus, } from './workflow.types.js';
+export { PikkuWorkflowService } from './pikku-workflow-service.js';
+export { addWorkflow } from './workflow-runner.js';
+/**
+ * @deprecated This function is no longer used and will be removed in a future release.
+ * It exists only for backwards compatibility with generated code.
+ * TODO: Remove this export in a future release after updating code generation
+ */
+export declare const wireWorkflow: <T extends {
+    name: string;
+    func: any;
+}>(workflow: T) => void;

package/dist/wirings/workflow/index.js

@@ -0,0 +1,14 @@
+/**
+ * Workflow module exports
+ */
+export { PikkuWorkflowService } from './pikku-workflow-service.js';
+// Internal registration function (used by generated code)
+export { addWorkflow } from './workflow-runner.js';
+/**
+ * @deprecated This function is no longer used and will be removed in a future release.
+ * It exists only for backwards compatibility with generated code.
+ * TODO: Remove this export in a future release after updating code generation
+ */
+export const wireWorkflow = (workflow) => {
+    // Empty function - no longer used, kept for backwards compatibility
+};

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -0,0 +1,160 @@
+import { CoreConfig, CoreSingletonServices, CreateWireServices, SerializedError } from '../../types/core.types.js';
+import type { StepState, WorkflowRun, WorkflowStatus, WorkflowService, WorkflowStepOptions } from './workflow.types.js';
+export declare class WorkflowServiceNotInitialized extends Error {
+}
+export declare class WorkflowStepNameNotString extends Error {
+    constructor(stepName: any);
+}
+/**
+ * Abstract workflow state service
+ * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
+ * Combines orchestration and step execution
+ */
+export declare abstract class PikkuWorkflowService implements WorkflowService {
+    private config;
+    private singletonServices;
+    private createWireServices;
+    constructor();
+    setServices(singletonServices: CoreSingletonServices, createWireServices: CreateWireServices, { workflow }: CoreConfig): void;
+    /**
+     * Create a new workflow run
+     * @param name - Workflow name
+     * @param input - Input data for the workflow
+     * @returns Run ID
+     */
+    abstract createRun(workflowName: string, input: any): Promise<string>;
+    /**
+     * Get a workflow run by ID
+     * @param id - Run ID
+     * @returns Workflow run or null if not found
+     */
+    abstract getRun(id: string): Promise<WorkflowRun | null>;
+    /**
+     * Get workflow run history (all step attempts in chronological order)
+     * @param runId - Run ID
+     * @returns Array of step states with step names, ordered oldest to newest
+     */
+    abstract getRunHistory(runId: string): Promise<Array<StepState & {
+        stepName: string;
+    }>>;
+    /**
+     * Update workflow run status
+     * @param id - Run ID
+     * @param status - New status
+     */
+    abstract updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    /**
+     * Insert initial step state (called by orchestrator)
+     * Creates pending step in both workflow_step and workflow_step_history
+     * @param runId - Run ID
+     * @param stepName - Step cache key
+     * @param rpcName - RPC function name
+     * @param data - Step input data
+     * @param stepOptions - Step options (retries, retryDelay)
+     * @returns Step state with generated stepId
+     */
+    abstract insertStepState(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: WorkflowStepOptions): Promise<StepState>;
+    /**
+     * Get step state by cache key (read-only)
+     * @param runId - Run ID
+     * @param stepName - Step cache key (from workflow.do)
+     * @returns Step state with attemptCount calculated from history
+     */
+    abstract getStepState(runId: string, stepName: string): Promise<StepState>;
+    /**
+     * Mark step as running
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     */
+    abstract setStepRunning(stepId: string): Promise<void>;
+    /**
+     * Mark step as scheduled (queued for execution)
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     */
+    abstract setStepScheduled(stepId: string): Promise<void>;
+    /**
+     * Store step result and mark as succeeded
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     * @param result - Step result
+     */
+    abstract setStepResult(stepId: string, result: any): Promise<void>;
+    /**
+     * Store step error and mark as failed
+     * Updates both workflow_step and workflow_step_history
+     * @param stepId - Step ID
+     * @param error - Error object
+     */
+    abstract setStepError(stepId: string, error: Error): Promise<void>;
+    /**
+     * Create a new retry attempt for a failed step
+     * Inserts new pending step in both workflow_step and workflow_step_history
+     * Resets status to 'pending' with new stepId
+     * Copies metadata (rpcName, data, retries, retryDelay) from failed attempt
+     * @param failedStepId - Failed step ID to copy from
+     * @returns New step state for the retry attempt
+     */
+    abstract createRetryAttempt(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    /**
+     * Execute function within a run lock to prevent concurrent modifications
+     * @param id - Run ID
+     * @param fn - Function to execute
+     * @returns Function result
+     */
+    abstract withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute function within a step lock to prevent concurrent step execution
+     * @param runId - Run ID
+     * @param stepName - Step name
+     * @param fn - Function to execute
+     * @returns Function result
+     */
+    abstract withStepLock<T>(runId: string, stepName: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Close any open connections
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Resume a paused workflow by triggering the orchestrator
+     * @param runId - Run ID
+     */
+    resumeWorkflow(runId: string): Promise<void>;
+    /**
+     * Execute a workflow sleep step completion
+     * Sets the step result to null and resumes the workflow
+     * @param data - Sleeper input data
+     */
+    executeWorkflowSleep(runId: string, stepId: string): Promise<void>;
+    /**
+     * Schedule orchestrator retry with delay
+     * @param runId - Run ID
+     * @param retryDelay - Delay in milliseconds or duration string (optional)
+     */
+    protected scheduleOrchestratorRetry(runId: string, retryDelay?: number | string): Promise<void>;
+    /**
+     * Start a new workflow run
+     */
+    startWorkflow<I>(name: string, input: I, rpcService: any): Promise<{
+        runId: string;
+    }>;
+    runWorkflowJob(runId: string, rpcService: any): Promise<void>;
+    /**
+     * Execute a single workflow step (called by worker)
+     * Handles idempotency, RPC execution, result storage, retry logic, and orchestrator triggering
+     */
+    executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: any): Promise<void>;
+    /**
+     * Orchestrate workflow execution (called by orchestrator)
+     * Runs workflow job and handles async exceptions
+     */
+    orchestrateWorkflow(runId: string, rpcService: any): Promise<void>;
+    private verifyQueueService;
+    private rpcStep;
+    private inlineStep;
+    private sleepStep;
+    private cancelWorkflow;
+    private createWorkflowWire;
+    private verifyStepName;
+    private getConfig;
+}