@justscale/core 0.1.0

package/dist/runtime/process/executor.d.ts

@@ -0,0 +1,279 @@
+/**
+ * @justscale/process - Process Executor
+ *
+ * Switch-based executor for durable processes.
+ * Uses pluggable storage, signal bus, and timer scheduler.
+ */
+import type { ServiceToken, Resolver, Container } from '../../core/index.js';
+import type { LockProvider } from '../../index.js';
+import { type CompiledSwitchProcess, type ProcessContinuation, type ProcessHandle, type ProcessStatus, type Signal, type SwitchProcessState } from '../../process/types.js';
+import type { ProcessStorage } from './storage.js';
+import type { SignalBus } from './signal-bus.js';
+import type { TimerScheduler, TimerFired } from './timer-scheduler.js';
+export declare function generateInstanceId(path: string, params: readonly unknown[]): string;
+/**
+ * Detect whether an instanceId belongs to a subprocess and split it into
+ * `${parentInstanceId}/${subKey}` where `subKey` starts with `__sub:`.
+ * Returns { parentInstanceId: null, subKey: null } for non-subprocess IDs.
+ * A subprocess may itself have subprocesses — we split at the LAST `/__sub:`
+ * boundary so the direct parent is always returned.
+ */
+export declare function parseChildInstanceId(instanceId: string): {
+    parentInstanceId: string | null;
+    subKey: string | null;
+};
+/**
+ * Resolve a path pattern with params to a concrete path.
+ */
+export declare function resolvePath(path: string, params: readonly unknown[]): string;
+/**
+ * Extract identity map from path params.
+ *
+ * Throws on missing params to stay consistent with generateInstanceId.
+ * A process that lacks a required path param must fail loudly on both
+ * id generation and identity extraction; silent coercion to "undefined"
+ * hides routing bugs.
+ */
+export declare function extractIdentity(path: string, params: readonly unknown[]): Record<string, string>;
+export interface ExportsPublishPayload {
+    instanceId: string;
+    processId: string;
+    exports: Record<string, unknown>;
+}
+export interface ProcessExecutorOptions {
+    /** DI container for context propagation (optional - if not provided, context won't be propagated) */
+    container?: Container;
+    /** Resolver function for resolving service dependencies */
+    resolve: Resolver;
+    /** Storage backend for process state */
+    storage: ProcessStorage;
+    /** Signal bus for routing signals */
+    signalBus: SignalBus;
+    /** Timer scheduler for delays */
+    timerScheduler: TimerScheduler;
+    /** Lock provider for exclusive process execution (optional for backwards compat) */
+    lockProvider?: LockProvider;
+    /** Callback to publish exports changes (wired by infrastructure layer to channel backend) */
+    publishExports?: (payload: ExportsPublishPayload) => Promise<void>;
+}
+/**
+ * Interface for process executor functionality.
+ * Used for structural typing with bindService.
+ */
+export interface ProcessExecutorContract {
+    createSignal<TIdentity extends readonly unknown[] = [], TPayload = void, TName extends string = string>(name: TName, identityParams?: string[]): Signal<TIdentity, TPayload, TName>;
+    emit(signal: string, identity: Record<string, string>, payload?: unknown): Promise<number>;
+    receiveTimerFire(fired: TimerFired): void;
+}
+declare const AbstractProcessExecutor_base: import("@justscale/core").AbstractClass<ProcessExecutorContract>;
+/**
+ * Abstract ProcessExecutor for dependency injection.
+ *
+ * Inject this into services to create signals bound to the executor:
+ *
+ * @example
+ * ```typescript
+ * const OrderSignals = defineService({
+ *   inject: { executor: AbstractProcessExecutor },
+ *   factory: ({ executor }) => ({
+ *     shipped: executor.createSignal<[orderId: string]>('orders.shipped', ['orderId']),
+ *   })
+ * })
+ * ```
+ */
+export declare abstract class AbstractProcessExecutor extends AbstractProcessExecutor_base {
+}
+/**
+ * Executes durable processes using switch-based execution model.
+ *
+ * Features:
+ * - VM-style switch execution with suspension/resumption
+ * - Signal routing via SignalBus
+ * - Timer scheduling via TimerScheduler
+ * - State persistence via ProcessStorage
+ */
+export declare class ProcessExecutor extends AbstractProcessExecutor {
+    private readonly container;
+    private readonly resolve;
+    private readonly storage;
+    private readonly signalBus;
+    private readonly timerScheduler;
+    private readonly lockProvider;
+    private readonly executorId;
+    private completions;
+    private resolvedServicesCache;
+    private subscriptions;
+    private processRegistry;
+    private originContexts;
+    private yieldQueues;
+    private handles;
+    private readonly lockOptions;
+    private readonly publishExports;
+    constructor(options: ProcessExecutorOptions);
+    /**
+     * Register a process definition for resumption after signals.
+     */
+    register(process: CompiledSwitchProcess<Record<string, ServiceToken>>): void;
+    /**
+     * Start or resume a process.
+     */
+    start<TResult>(process: CompiledSwitchProcess<Record<string, ServiceToken>>, params: readonly unknown[]): Promise<ProcessHandle<TResult>>;
+    /**
+     * Emit a signal to waiting processes.
+     *
+     * Lock acquisition happens in handleSignalMatch() when the signal is delivered.
+     * This avoids deadlock since handleSignalMatch() is called synchronously from emit().
+     */
+    emit(signal: string, identity: Record<string, string>, payload?: unknown): Promise<number>;
+    /**
+     * Create a signal bound to this executor.
+     *
+     * The returned signal is callable directly and will emit through this executor,
+     * which handles locking to prevent dead letters.
+     *
+     * @param name - Signal name for routing (e.g., 'orders.shipped')
+     * @param identityParams - Names of identity parameters (e.g., ['orderId'])
+     *
+     * @example
+     * ```typescript
+     * const OrderSignals = defineService({
+     *   inject: { executor: ProcessExecutor },
+     *   factory: ({ executor }) => ({
+     *     shipped: executor.createSignal<[orderId: string], { trackingNumber: string }>(
+     *       'orders.shipped',
+     *       ['orderId']
+     *     ),
+     *   })
+     * })
+     *
+     * // Usage: await orderSignals.shipped('order-123', { trackingNumber: 'ABC' })
+     * ```
+     */
+    createSignal<TIdentity extends readonly unknown[] = [], TPayload = void, TName extends string = string>(name: TName, identityParams?: string[]): Signal<TIdentity, TPayload, TName>;
+    /**
+     * Execute a switch-based process.
+     * Runs within a full request scope for context propagation (if container available).
+     */
+    private execute;
+    /**
+     * Handle process suspension.
+     */
+    private suspend;
+    /**
+     * Re-subscribe a suspended process to its signals.
+     * Called when loading a suspended process from storage, since in-memory
+     * signal bus doesn't persist subscriptions across restarts.
+     */
+    private resubscribeSuspended;
+    private handleSignalMatch;
+    private handleTimerFired;
+    receiveTimerFire(fired: TimerFired): void;
+    /**
+     * Handle scope suspension: fan-out over entities.
+     *
+     * For signal-first form: subscribe to the signal for each entity's identity.
+     * For handler form: spawn sub-processes for each entity.
+     *
+     * When all entities complete, resume the parent process at resumeStep.
+     */
+    private handleScopeSuspend;
+    /**
+     * Notify that a scope entity has completed.
+     * Decrements the remaining counter and resumes parent if all done.
+     */
+    notifyScopeEntityComplete(instanceId: string, scopeId: number, entityId: string, result: unknown): Promise<void>;
+    private loadState;
+    private saveState;
+    private spawnSubprocess;
+    /**
+     * Apply a child execute() result — from either the initial spawn or a
+     * signal-driven resume. Mutates parent.vars[subKey] for DONE/SUSPEND,
+     * resumes the parent on awaited DONE, and manages the parent lock.
+     *
+     * `fromSpawn=true` means the parent is currently inside its own execute()
+     * loop and should resume there for detached outcomes. `fromSpawn=false`
+     * means resumeChild called us and the parent was otherwise idle/suspended;
+     * detached outcomes just save + release.
+     */
+    private applyChildResult;
+    private subscribeChildSuspension;
+    /**
+     * Resume a child process after one of its signal subscriptions fired.
+     * The child's instanceId encodes its scope as `${parentInstanceId}/__sub:name:args`.
+     * We load the parent row, extract the child's nested state, apply the signal
+     * match, and re-enter child.execute(). On child DONE, applyChildResult
+     * resumes the parent if the parent was awaiting.
+     */
+    private resumeChild;
+    private buildFrozenExports;
+    private resolveServices;
+    private calculateExpiry;
+    /**
+     * Resolve stream signal wildcard to actual entity ID.
+     *
+     * Stream signals from the compiler have format: stream:ModelName:*:fieldName
+     * The * needs to be resolved using the process identity at runtime.
+     *
+     * Uses the shared stream-utils for proper camelCase conversion that handles:
+     * - Standard models: Order → orderId
+     * - Acronyms: ABC → abcId, HTTPServer → httpServerId
+     * - Numbers: V2Order → v2OrderId
+     *
+     * @example
+     * Input: stream:Order:*:statusUpdates, identity: { orderId: 'abc123' }
+     * Output: stream:Order:abc123:statusUpdates
+     */
+    private resolveStreamWildcard;
+    private trackSubscription;
+    private untrackSubscription;
+    private cleanupSubscriptions;
+    /**
+     * Cascade-cancel all live subprocesses of a parent reaching a terminal
+     * state. Lexical scope dictates lifetime: children's subscriptions are
+     * torn down so they can no longer receive signals and resume. Nested
+     * blob stays in parent.vars for post-mortem inspection.
+     */
+    private cleanupChildSubscriptions;
+    /**
+     * Acquire a process lock. No-op if no lock provider configured.
+     * Blocks until lock is acquired - JustScale locks never fail.
+     */
+    private acquireLock;
+    /**
+     * Release a process lock. No-op if no lock provider configured.
+     */
+    private releaseLock;
+    private complete;
+    private fail;
+    /**
+     * Get a process state by instance ID.
+     */
+    get(instanceId: string): Promise<SwitchProcessState | null>;
+    queryByStatus(status: ProcessStatus): AsyncIterable<SwitchProcessState>;
+    queryByProcessId(processId: string): AsyncIterable<SwitchProcessState>;
+    /**
+     * Cancel a process instance.
+     * Only processes in 'pending' or 'suspended' status can be cancelled.
+     * Cleans up subscriptions, timers, and rejects the completion promise.
+     *
+     * @returns true if the process was cancelled, false if it was already completed/failed
+     */
+    cancel(instanceId: string): Promise<boolean>;
+    /**
+     * Create a ProcessContinuation for a generator process.
+     * Allows iterating over yielded values with a durable consumer cursor.
+     *
+     * @param instanceId - The process instance ID
+     * @param consumerId - Optional consumer ID for reconnecting to a previous cursor position.
+     *                     If not provided, a new consumer is created starting from the beginning.
+     */
+    createContinuation<TYield, TReturn>(instanceId: string, consumerId?: string): Promise<ProcessContinuation<TYield, TReturn>>;
+    /** Start the timer scheduler */
+    startTimers(): void;
+    /** Stop the timer scheduler */
+    stopTimers(): void;
+    /** Clear caches (for testing) */
+    clearCaches(): void;
+}
+export {};
+//# sourceMappingURL=executor.d.ts.map

package/dist/runtime/process/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/runtime/process/executor.ts"],"names":[],"mappings":"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"}