@asaidimu/runtime 1.0.0

package/index.d.ts

@@ -0,0 +1,153 @@
+import { Result, SystemError } from "@asaidimu/utils-error";
+import { PipelineFactory, PipelineRegistry, PipelineRunResult, RoutingPipelineDefinition, RunContext, RunInfo, TimelineStore } from "@asaidimu/utils-pipeline";
+import { DeepPartial, StoreRegistry } from "@asaidimu/utils-store";
+import { EventBus } from "@asaidimu/utils-events";
+
+//#region src/runtime/types/workflow.d.ts
+type WorkflowState<T extends Record<string, any> = Record<string, any>> = T;
+interface WorkflowEvent<Payload = unknown> {
+  type: string;
+  payload: Payload;
+  timestamp: number;
+  state?: WorkflowState;
+}
+type WorkflowTrigger = {
+  id: string;
+  event: string;
+  predicate: (event: WorkflowEvent, state?: WorkflowState) => boolean;
+};
+interface Workflow<T extends Record<string, any> = Record<string, any>> {
+  id: string;
+  label: string;
+  triggers: Record<string, WorkflowTrigger>;
+  pipelines: Record<string, RoutingPipelineDefinition<WorkflowState<T>>>;
+}
+//#endregion
+//#region src/runtime/types/service.d.ts
+interface RunServiceContext {
+  runId: string;
+  workflowId: string;
+  triggerId: string;
+}
+type ServiceDefinition<T> = {
+  id: string;
+  scope: "singleton";
+  factory: () => T | Promise<T>;
+} | {
+  id: string;
+  scope: "transient";
+  factory: (ctx: RunServiceContext) => T | Promise<T>;
+};
+//#endregion
+//#region src/runtime/types/runtime.d.ts
+declare const ABORT_EVENT: "__abort__";
+declare const SIGNAL_EVENT: "__signal__";
+type WorkflowExecutionMode = {
+  type: "transient";
+  concurrency?: number;
+  capacity?: number;
+} | {
+  type: "serialized";
+  capacity?: number;
+} | {
+  type: "singleton_loop";
+  onActive?: "drop" | "signal" | "replace";
+  replacementGracePeriod?: number;
+} | {
+  type: "exclusive";
+  onActive?: "reject" | "queue_single";
+};
+type DispatchResult = {
+  status: "accepted";
+  runId?: string;
+} | {
+  status: "queued";
+  position: number;
+} | {
+  status: "rejected";
+  reason: "queue_full" | "singleton_active" | "exclusive_active" | "terminating" | "filtered";
+} | {
+  status: "signalled";
+  runId: string;
+};
+type InvokeResult = Result<PipelineRunResult<WorkflowState>, SystemError, {
+  runId: string;
+  triggerId: string;
+}>;
+interface WorkflowRuntimeOptions {
+  bus: EventBus<Record<string, any>>;
+  storeRegistry: StoreRegistry<WorkflowState>;
+  timelineStore?: TimelineStore<WorkflowState>;
+  services?: ServiceDefinition<unknown>[];
+}
+interface RegisterOptions {
+  mode: WorkflowExecutionMode;
+  onPrepare: (context: Readonly<RunContext<WorkflowState>>) => Promise<void>;
+  onComplete: (result: Result<PipelineRunResult<WorkflowState>, SystemError>) => Promise<void>;
+  onResume?: (context: Readonly<RunContext<WorkflowState>>) => Promise<void>;
+  onCleanup?: () => Promise<void>;
+  onDispatch?: (result: DispatchResult) => void;
+}
+//#endregion
+//#region src/runtime/runtime/runtime.d.ts
+declare class WorkflowRuntime {
+  private readonly bus;
+  private readonly storeRegistry;
+  private readonly timelineStore;
+  /** Built-in watch service. Always present. */
+  private readonly pauseService;
+  /** User-defined run-scoped service definitions, instantiated per run. */
+  private readonly runServiceDefinitions;
+  /** Global container holding all registered services accessible by steps. */
+  private readonly serviceContainer;
+  private readonly workflows;
+  private readonly index;
+  private readonly subscriptions;
+  /**
+   * runId → PausedRunEntry.
+   * Populated when a run pauses. Cleared when run ends or is aborted.
+   */
+  private readonly pausedRuns;
+  private readonly abortUnsubscribe;
+  private readonly signalUnsubscribe;
+  constructor(options: WorkflowRuntimeOptions);
+  static createTestTimelineStore(database?: string): Promise<TimelineStore<any>>;
+  register(workflow: Workflow, options: RegisterOptions): Promise<void>;
+  deregister(workflowId: string): void;
+  hasWorkflow(workflowId: string): boolean;
+  listWorkflows(): string[];
+  stop(): Promise<void>;
+  registry(workflowId: string): PipelineRegistry<WorkflowState> | undefined;
+  watch(workflowId: string, runId: string): RunInfo<WorkflowState> | undefined;
+  listAllRuns(): Array<RunInfo<WorkflowState> & {
+    workflowId: string;
+  }>;
+  invoke(workflowId: string, triggerId: string, event: WorkflowEvent): Promise<InvokeResult>;
+  resume(runId: string, patch?: DeepPartial<WorkflowState>): Promise<InvokeResult>;
+  signal(runId: string, patch: DeepPartial<WorkflowState>): Promise<void>;
+  private dispatch;
+  private executePipeline;
+  private spawnRun;
+  private drainWatchQueue;
+  private abortRun;
+  private buildExecutionContext;
+  private acquireBusSubscription;
+  private releaseBusSubscription;
+  private getOrCreateFactory;
+  private generateRunId;
+}
+//#endregion
+//#region src/runtime/types/pause.d.ts
+type PauseOperator = ">=" | "<=" | "==" | "!=" | ">" | "<" | "exists";
+interface PauseCondition {
+  field: string;
+  op: PauseOperator;
+  value?: unknown;
+}
+interface PauseDescriptor {
+  eventType: string;
+  conditions: PauseCondition[];
+  patch?: DeepPartial<WorkflowState>;
+}
+//#endregion
+export { ABORT_EVENT, type DispatchResult, type InvokeResult, type PauseCondition, type PauseDescriptor, type PauseOperator, type RegisterOptions, SIGNAL_EVENT, type ServiceDefinition, type Workflow, type WorkflowEvent, type WorkflowExecutionMode, WorkflowRuntime, type WorkflowRuntimeOptions, type WorkflowState, type WorkflowTrigger };

package/index.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@asaidimu/utils-artifacts"),t=require("@asaidimu/utils-database"),n=require("@asaidimu/utils-error"),r=require("@asaidimu/utils-pipeline"),i=require("@asaidimu/utils-store"),a=require("@asaidimu/utils-sync");const o=`__abort__`,s=`__signal__`;var c=class{workflowId;concurrency;capacity;inFlight=0;queueSize=0;closed=!1;constructor(e,t,n){this.workflowId=e,this.concurrency=t,this.capacity=n}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`queue_full`};if(this.inFlight<this.concurrency)return this.inFlight++,this.run(e,t,n),{status:`accepted`};if(this.queueSize>=this.capacity)return{status:`rejected`,reason:`queue_full`};this.queueSize++;let r=this.queueSize;return await new Promise(e=>{let t=()=>{if(this.closed){e();return}this.inFlight<this.concurrency?(this.inFlight++,this.queueSize--,e()):setTimeout(t,0)};setTimeout(t,0)}),this.closed?{status:`rejected`,reason:`queue_full`}:(this.run(e,t,n),{status:`queued`,position:r})}settle(e){}close(){this.closed=!0}async run(e,t,n){try{await n(e,t)}finally{this.inFlight--}}},l=class{workflowId;capacity;serializer;queueDepth=0;closed=!1;constructor(e,t){this.workflowId=e,this.capacity=t,this.serializer=new a.Serializer({capacity:t,yieldMode:`macrotask`})}async accept(e,t,n){if(this.closed||this.queueDepth>=this.capacity)return{status:`rejected`,reason:`queue_full`};let r=this.queueDepth;return this.queueDepth++,await this.serializer.do(async()=>{try{await n(e,t)}finally{this.queueDepth--}}),r===0?{status:`accepted`}:{status:`queued`,position:r}}settle(e){}close(){this.closed=!0,this.serializer.close()}},u=class{workflowId;onActive;replacementGracePeriod;deliverSignal;state=`idle`;activeRunId;settleResolve;closed=!1;constructor(e,t,n,r){this.workflowId=e,this.onActive=t,this.replacementGracePeriod=n,this.deliverSignal=r}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`singleton_active`};if(this.state===`idle`){this.state=`starting`;let r=await n(e,t);return r||(this.state=`idle`,this.activeRunId=void 0),{status:`accepted`,runId:r}}if(this.state===`terminating`)return{status:`rejected`,reason:`terminating`};switch(this.onActive){case`drop`:return{status:`rejected`,reason:`singleton_active`};case`signal`:{let e=this.activeRunId??``;return e?this.deliverSignal(e,t):console.warn(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": signal requested but activeRunId unknown (state="${this.state}"). Event "${t.type}" dropped.`),{status:`signalled`,runId:e}}case`replace`:return this.handleReplace(e,t,n)}}settle(e){(this.state===`starting`||e===this.activeRunId)&&(this.activeRunId=e,this.state=`running`),this.state===`terminating`&&e===this.activeRunId&&this.settleResolve?.()}close(){this.closed=!0,this.settleResolve?.()}async handleReplace(e,t,n){if(this.state=`terminating`,this.activeRunId&&console.info(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": replacing run "${this.activeRunId}" with new event "${t.type}".`),await Promise.race([new Promise(e=>{this.settleResolve=e}),new Promise(e=>setTimeout(e,this.replacementGracePeriod))]),this.settleResolve=void 0,this.closed)return this.state=`idle`,{status:`rejected`,reason:`singleton_active`};this.state=`starting`,this.activeRunId=void 0;let r=await n(e,t);return r||(this.state=`idle`),{status:`accepted`,runId:r}}},d=class{workflowId;onActive;activeRunId;pending;closed=!1;constructor(e,t){this.workflowId=e,this.onActive=t}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`exclusive_active`};if(!this.activeRunId){let r=await n(e,t);return r&&(this.activeRunId=r),{status:`accepted`,runId:r}}return this.onActive===`reject`?{status:`rejected`,reason:`exclusive_active`}:(this.pending={triggerId:e,event:t,spawn:n},{status:`queued`,position:1})}settle(e){if(e===this.activeRunId&&(this.activeRunId=void 0,this.pending&&!this.closed)){let{triggerId:e,event:t,spawn:n}=this.pending;this.pending=void 0,n(e,t).then(e=>{e&&(this.activeRunId=e)})}}close(){this.closed=!0,this.pending=void 0}},f=class{registrations=new Map;byEventType=new Map;busSubscriptions=new Map;bus;resumeCallback;constructor(e){this.bus=e.bus,this.resumeCallback=e.resume}register(e,t){let n=this.registrations.get(e);n||(n=new Map,this.registrations.set(e,n));let r={runId:e,descriptor:t,queue:[],parked:!1};n.set(t.eventType,r);let i=this.byEventType.get(t.eventType);i||(i=new Set,this.byEventType.set(t.eventType,i)),i.add(e),this.acquireBusSubscription(t.eventType)}cancel(e,t){let n=this.registrations.get(e);n&&(n.delete(t),n.size===0&&this.registrations.delete(e),this.removeFromReverseIndex(e,t),this.releaseBusSubscription(t))}onRunPaused(e){let t=this.registrations.get(e);if(!t)return null;for(let e of t.values())if(e.queue.length>0)return e.queue.shift();for(let e of t.values())e.parked=!0;return null}onRunEnded(e){let t=this.registrations.get(e);if(t){for(let[n]of t)this.removeFromReverseIndex(e,n),this.releaseBusSubscription(n);this.registrations.delete(e)}}onEvent(e,t){let n=this.byEventType.get(e);if(!(!n||n.size===0))for(let r of n){let n=this.registrations.get(r);if(!n)continue;let i=n.get(e);if(!i||!this.evaluate(i.descriptor.conditions,t))continue;let a=this.resolve(i.descriptor,t);i.parked?(i.parked=!1,this.resumeCallback(r,a.patch)):i.queue.push(a)}}evaluate(e,t){for(let n of e){let e=this.getField(t,n.field);if(n.op===`exists`){if(e==null)return!1;continue}if(e==null)return!1;try{switch(n.op){case`==`:if(e!=n.value)return!1;break;case`!=`:if(e==n.value)return!1;break;case`>`:if(!(e>n.value))return!1;break;case`>=`:if(!(e>=n.value))return!1;break;case`<`:if(!(e<n.value))return!1;break;case`<=`:if(!(e<=n.value))return!1;break;default:return!1}}catch{return!1}}return!0}resolve(e,t){return{eventPayload:t,patch:{...e.patch??{},__watch_event__:t}}}getField(e,t){let n=t.split(`.`),r=e;for(let e of n){if(r==null||typeof r!=`object`&&!Array.isArray(r))return;let t=Number(e);r=!isNaN(t)&&Array.isArray(r)?r[t]:r[e]}return r}acquireBusSubscription(e){if(this.busSubscriptions.has(e))return;let t=this.bus.subscribe(e,t=>{this.onEvent(e,t)});this.busSubscriptions.set(e,t)}releaseBusSubscription(e){let t=this.byEventType.get(e);if(t&&t.size>0)return;let n=this.busSubscriptions.get(e);if(n){try{n()}catch{}this.busSubscriptions.delete(e)}}removeFromReverseIndex(e,t){let n=this.byEventType.get(t);n&&(n.delete(e),n.size===0&&this.byEventType.delete(t))}},p=class{bus;storeRegistry;timelineStore;pauseService;runServiceDefinitions=[];serviceContainer;workflows=new Map;index=new Map;subscriptions=new Map;pausedRuns=new Map;abortUnsubscribe;signalUnsubscribe;constructor(t){this.bus=t.bus,this.storeRegistry=t.storeRegistry,this.timelineStore=t.timelineStore,this.pauseService=new f({bus:this.bus,resume:async(e,t)=>{this.resume(e,t)}}),this.serviceContainer=new e.ArtifactContainer(new i.ReactiveDataStore({}));for(let e of t.services??[]){if(e.id===`__pause_service__`)throw new n.SystemError({code:n.ErrorCodes.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__pause_service__" is reserved for the built-in PauseService and cannot be redefined.`});e.scope===`singleton`?this.serviceContainer.register({key:e.id,factory:()=>e.factory(),scope:`singleton`}):this.runServiceDefinitions.push(e)}this.serviceContainer.register({key:`__pause_service__`,factory:()=>this.pauseService,scope:`singleton`}),this.abortUnsubscribe=this.bus.subscribe(o,e=>{this.abortRun(e.run)}),this.signalUnsubscribe=this.bus.subscribe(s,e=>{this.signal(e.runId,e.patch)})}static async createTestTimelineStore(e=`test-timeline-database`){return new r.TimelineStore(await(0,t.DatabaseConnection)({database:e,validate:!0,predicates:{},enableTelemetry:!0},t.createIndexedDbStore))}async register(e,t){if(this.workflows.has(e.id))throw new n.SystemError({code:n.ErrorCodes.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Workflow "${e.id}" is already registered. Call deregister("${e.id}") before registering again.`});let i=r.PipelineRegistry.get(`workflow:${e.id}`,{onExpired:(t,n)=>{console.info(`[WorkflowRuntime] Run "${t}" pause-window expired for workflow "${e.id}". Checkpoint: ${n.pipelineId}.`)},onExportFailed:(t,n)=>{console.error(`[WorkflowRuntime] Deferred export failed for run "${t}" in workflow "${e.id}":`,n)}}),a=async e=>{let n=e.ok?e.value.runId:e.error?.runId;n&&(s.executionContext.settle(n),this.pauseService.onRunEnded(n),this.pausedRuns.delete(n)),i.prune();try{await t.onComplete(e)}finally{await t.onCleanup?.()}},o=this.buildExecutionContext(e.id,t.mode),s;s={workflow:e,mode:t.mode,executionContext:o,factories:new Map,registry:i,hooks:{onPrepare:t.onPrepare,onComplete:a,onResume:t.onResume,onDispatch:t.onDispatch,onCleanup:t.onCleanup}},this.workflows.set(e.id,s);for(let[t,n]of Object.entries(e.triggers)){let r={workflowId:e.id,triggerId:t,trigger:n},i=this.index.get(n.event);i||(i=new Set,this.index.set(n.event,i)),i.add(r),await this.acquireBusSubscription(n.event)}}deregister(e){let t=this.workflows.get(e);if(t){for(let n of Object.values(t.workflow.triggers)){let t=this.index.get(n.event);if(t){for(let n of t)n.workflowId===e&&t.delete(n);t.size===0&&this.index.delete(n.event)}this.releaseBusSubscription(n.event)}t.executionContext.close(),r.PipelineRegistry.destroy(`workflow:${e}`),t.factories.clear(),this.workflows.delete(e)}}hasWorkflow(e){return this.workflows.has(e)}listWorkflows(){return Array.from(this.workflows.keys())}async stop(){for(let e of Array.from(this.workflows.keys()))this.deregister(e);try{this.abortUnsubscribe()}catch{}try{this.signalUnsubscribe()}catch{}}registry(e){return this.workflows.get(e)?.registry}watch(e,t){return this.workflows.get(e)?.registry.get(t)}listAllRuns(){let e=[];for(let[t,n]of this.workflows)for(let r of n.registry.list())e.push({...r,workflowId:t});return e}async invoke(e,t,r){let i=this.workflows.get(e);if(!i)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: workflow "${e}" is not registered.`});if(!i.workflow.pipelines[t])throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: no pipeline definition for workflow "${e}" trigger "${t}".`});let a=this.generateRunId(e,t),o=await this.executePipeline(i,t,a,r);return o.ok&&o.value.status===`paused`?(this.pausedRuns.set(a,{workflowId:e,triggerId:t}),await this.drainWatchQueue(a)):await i.hooks.onComplete(o),o.ok?n.Result.ok(o.value,{runId:a,triggerId:t}):n.Result.fail(o.error,{runId:a,triggerId:t})}async resume(e,t={}){let r=this.pausedRuns.get(e);if(!r)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] resume() failed: run "${e}" is not in the paused runs registry. It may have already completed, been aborted, or the runId is incorrect.`});let{workflowId:a,triggerId:o}=r,s=this.workflows.get(a);if(!s)throw new n.SystemError({code:n.ErrorCodes.RESOURCE_RELEASED.code,message:`[WorkflowRuntime] resume() failed: workflow "${a}" is no longer registered. The workflow may have been deregistered while the run was paused.`});let c=this.getOrCreateFactory(s,o),l=s.registry.hold(e),u;try{let t=await c.resume(e);if(!t.ok)throw t.error;u=t.value}catch(t){throw new n.SystemError({code:n.ErrorCodes.INTERNAL_ERROR.code,message:`[WorkflowRuntime] resume() failed to reconstruct context for run "${e}"`,cause:t})}l||u.container.extend(this.serviceContainer),Object.keys(t).length>0&&u.write(t),u.write({__watch__:i.DELETE_SYMBOL}),await s.hooks.onResume?.(u);let d=await u.run();if(d.ok&&d.value.status===`paused`)await this.drainWatchQueue(e);else{let t=this.workflows.get(a);if(t)try{await t.hooks.onComplete(d)}catch(t){console.error(`[WorkflowRuntime] onComplete hook threw during resume for run "${e}":`,t)}}return d.ok?n.Result.ok(d.value,{runId:e,triggerId:o}):n.Result.fail(d.error,{runId:e,triggerId:o})}async signal(e,t){for(let n of this.workflows.values()){let r=n.registry.get(e);if(r?.context){r.context.write(t);return}}}dispatch(e,t){let n=this.index.get(e);if(!n||n.size===0)return;let r={type:e,payload:t,timestamp:Date.now()};for(let e of n){let t=!0;if(e.trigger.predicate)try{t=e.trigger.predicate(r)}catch(n){console.error(`[WorkflowRuntime] Predicate threw for workflow "${e.workflowId}" trigger "${e.triggerId}":`,n),t=!1}if(!t){this.workflows.get(e.workflowId)?.hooks.onDispatch?.({status:`rejected`,reason:`filtered`});continue}let n=this.workflows.get(e.workflowId);n&&n.executionContext.accept(e.triggerId,r,(e,t)=>this.spawnRun(n,e,t)).then(e=>{n.hooks.onDispatch?.(e)}).catch(t=>{console.error(`[WorkflowRuntime] ExecutionContext.accept() threw for workflow "${e.workflowId}":`,t)})}}async executePipeline(e,t,i,a){let o=this.timelineStore?new r.TimelineRecorder(this.timelineStore,{}):void 0,s=this.getOrCreateFactory(e,t),c;try{c=await s.prepare(void 0,i),o&&await o.attach(c),await c.store.set({__trigger_event__:a})}catch(e){o&&await o.detach().catch(()=>{});let t=e instanceof n.SystemError?e:new n.SystemError({code:`PIPELINE_PREPARE_FAILED`,message:e instanceof Error?e.message:String(e)});return n.Result.fail(t)}c.container.extend(this.serviceContainer),await e.hooks.onPrepare(c);let l=await c.run();return o&&await o.detach().catch(()=>{}),l}async spawnRun(e,t,n){let r=this.generateRunId(e.workflow.id,t);return this.executePipeline(e,t,r,n).then(async n=>{if(n.ok&&n.value.status===`paused`){this.pausedRuns.set(r,{workflowId:e.workflow.id,triggerId:t}),await this.drainWatchQueue(r);return}try{await e.hooks.onComplete(n)}catch(e){console.error(`[WorkflowRuntime] onComplete hook threw for run "${r}":`,e)}}).catch(e=>{console.error(`[WorkflowRuntime] Pipeline execution failed for run "${r}":`,e)}),r}async drainWatchQueue(e){let t=this.pauseService.onRunPaused(e);if(t!==null)try{await this.resume(e,t.patch)}catch(t){console.error(`[WorkflowRuntime] drainWatchQueue: resume() failed for run "${e}":`,t),this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}}async abortRun(e){for(let t of this.workflows.values()){let n=t.registry.get(e);if(n?.context){try{n.context.abort()}catch(t){console.error(`[WorkflowRuntime] Error aborting run "${e}":`,t)}break}}this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}buildExecutionContext(e,t){switch(t.type){case`transient`:return new c(e,t.concurrency??10,t.capacity??1e3);case`serialized`:return new l(e,t.capacity??1e3);case`singleton_loop`:return new u(e,t.onActive??`drop`,t.replacementGracePeriod??5e3,(e,t)=>this.signal(e,{__singleton_event__:t}));case`exclusive`:return new d(e,t.onActive??`reject`)}}async acquireBusSubscription(e){let t=this.subscriptions.get(e);t||(t=new a.SharedResource(()=>this.bus.subscribe(e,t=>{this.dispatch(e,t)}),t=>{try{t?.(),this.subscriptions.delete(e)}catch{}},{gracePeriod:`sync`}),this.subscriptions.set(e,t)),await t.acquire()}releaseBusSubscription(e){this.subscriptions.get(e)?.release()}getOrCreateFactory(e,t){let i=e.factories.get(t);if(i)return i;let a=e.workflow.pipelines[t];if(!a)throw new n.SystemError({code:n.ErrorCodes.NOT_FOUND.code,message:`[WorkflowRuntime] No pipeline definition found for workflow "${e.workflow.id}" trigger "${t}". Ensure workflow.pipelines["${t}"] is populated by the compiler.`});let o=new r.PipelineFactory(a,{storeFactory:async e=>this.storeRegistry.get(e),registry:e.registry});return e.factories.set(t,o),o}generateRunId(e,t){return`${e}:${t}:${Date.now()}:${Math.random().toString(36).slice(2)}`}};exports.ABORT_EVENT=o,exports.SIGNAL_EVENT=s,exports.WorkflowRuntime=p;

package/index.mjs

@@ -0,0 +1 @@
+import{ArtifactContainer as e}from"@asaidimu/utils-artifacts";import{DatabaseConnection as t,createIndexedDbStore as n}from"@asaidimu/utils-database";import{ErrorCodes as r,Result as i,SystemError as a}from"@asaidimu/utils-error";import{PipelineFactory as o,PipelineRegistry as s,TimelineRecorder as c,TimelineStore as l}from"@asaidimu/utils-pipeline";import{DELETE_SYMBOL as u,ReactiveDataStore as d}from"@asaidimu/utils-store";import{Serializer as f,SharedResource as p}from"@asaidimu/utils-sync";const m=`__abort__`,h=`__signal__`;var g=class{workflowId;concurrency;capacity;inFlight=0;queueSize=0;closed=!1;constructor(e,t,n){this.workflowId=e,this.concurrency=t,this.capacity=n}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`queue_full`};if(this.inFlight<this.concurrency)return this.inFlight++,this.run(e,t,n),{status:`accepted`};if(this.queueSize>=this.capacity)return{status:`rejected`,reason:`queue_full`};this.queueSize++;let r=this.queueSize;return await new Promise(e=>{let t=()=>{if(this.closed){e();return}this.inFlight<this.concurrency?(this.inFlight++,this.queueSize--,e()):setTimeout(t,0)};setTimeout(t,0)}),this.closed?{status:`rejected`,reason:`queue_full`}:(this.run(e,t,n),{status:`queued`,position:r})}settle(e){}close(){this.closed=!0}async run(e,t,n){try{await n(e,t)}finally{this.inFlight--}}},_=class{workflowId;capacity;serializer;queueDepth=0;closed=!1;constructor(e,t){this.workflowId=e,this.capacity=t,this.serializer=new f({capacity:t,yieldMode:`macrotask`})}async accept(e,t,n){if(this.closed||this.queueDepth>=this.capacity)return{status:`rejected`,reason:`queue_full`};let r=this.queueDepth;return this.queueDepth++,await this.serializer.do(async()=>{try{await n(e,t)}finally{this.queueDepth--}}),r===0?{status:`accepted`}:{status:`queued`,position:r}}settle(e){}close(){this.closed=!0,this.serializer.close()}},v=class{workflowId;onActive;replacementGracePeriod;deliverSignal;state=`idle`;activeRunId;settleResolve;closed=!1;constructor(e,t,n,r){this.workflowId=e,this.onActive=t,this.replacementGracePeriod=n,this.deliverSignal=r}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`singleton_active`};if(this.state===`idle`){this.state=`starting`;let r=await n(e,t);return r||(this.state=`idle`,this.activeRunId=void 0),{status:`accepted`,runId:r}}if(this.state===`terminating`)return{status:`rejected`,reason:`terminating`};switch(this.onActive){case`drop`:return{status:`rejected`,reason:`singleton_active`};case`signal`:{let e=this.activeRunId??``;return e?this.deliverSignal(e,t):console.warn(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": signal requested but activeRunId unknown (state="${this.state}"). Event "${t.type}" dropped.`),{status:`signalled`,runId:e}}case`replace`:return this.handleReplace(e,t,n)}}settle(e){(this.state===`starting`||e===this.activeRunId)&&(this.activeRunId=e,this.state=`running`),this.state===`terminating`&&e===this.activeRunId&&this.settleResolve?.()}close(){this.closed=!0,this.settleResolve?.()}async handleReplace(e,t,n){if(this.state=`terminating`,this.activeRunId&&console.info(`[WorkflowRuntime] SingletonLoop "${this.workflowId}": replacing run "${this.activeRunId}" with new event "${t.type}".`),await Promise.race([new Promise(e=>{this.settleResolve=e}),new Promise(e=>setTimeout(e,this.replacementGracePeriod))]),this.settleResolve=void 0,this.closed)return this.state=`idle`,{status:`rejected`,reason:`singleton_active`};this.state=`starting`,this.activeRunId=void 0;let r=await n(e,t);return r||(this.state=`idle`),{status:`accepted`,runId:r}}},y=class{workflowId;onActive;activeRunId;pending;closed=!1;constructor(e,t){this.workflowId=e,this.onActive=t}async accept(e,t,n){if(this.closed)return{status:`rejected`,reason:`exclusive_active`};if(!this.activeRunId){let r=await n(e,t);return r&&(this.activeRunId=r),{status:`accepted`,runId:r}}return this.onActive===`reject`?{status:`rejected`,reason:`exclusive_active`}:(this.pending={triggerId:e,event:t,spawn:n},{status:`queued`,position:1})}settle(e){if(e===this.activeRunId&&(this.activeRunId=void 0,this.pending&&!this.closed)){let{triggerId:e,event:t,spawn:n}=this.pending;this.pending=void 0,n(e,t).then(e=>{e&&(this.activeRunId=e)})}}close(){this.closed=!0,this.pending=void 0}},b=class{registrations=new Map;byEventType=new Map;busSubscriptions=new Map;bus;resumeCallback;constructor(e){this.bus=e.bus,this.resumeCallback=e.resume}register(e,t){let n=this.registrations.get(e);n||(n=new Map,this.registrations.set(e,n));let r={runId:e,descriptor:t,queue:[],parked:!1};n.set(t.eventType,r);let i=this.byEventType.get(t.eventType);i||(i=new Set,this.byEventType.set(t.eventType,i)),i.add(e),this.acquireBusSubscription(t.eventType)}cancel(e,t){let n=this.registrations.get(e);n&&(n.delete(t),n.size===0&&this.registrations.delete(e),this.removeFromReverseIndex(e,t),this.releaseBusSubscription(t))}onRunPaused(e){let t=this.registrations.get(e);if(!t)return null;for(let e of t.values())if(e.queue.length>0)return e.queue.shift();for(let e of t.values())e.parked=!0;return null}onRunEnded(e){let t=this.registrations.get(e);if(t){for(let[n]of t)this.removeFromReverseIndex(e,n),this.releaseBusSubscription(n);this.registrations.delete(e)}}onEvent(e,t){let n=this.byEventType.get(e);if(!(!n||n.size===0))for(let r of n){let n=this.registrations.get(r);if(!n)continue;let i=n.get(e);if(!i||!this.evaluate(i.descriptor.conditions,t))continue;let a=this.resolve(i.descriptor,t);i.parked?(i.parked=!1,this.resumeCallback(r,a.patch)):i.queue.push(a)}}evaluate(e,t){for(let n of e){let e=this.getField(t,n.field);if(n.op===`exists`){if(e==null)return!1;continue}if(e==null)return!1;try{switch(n.op){case`==`:if(e!=n.value)return!1;break;case`!=`:if(e==n.value)return!1;break;case`>`:if(!(e>n.value))return!1;break;case`>=`:if(!(e>=n.value))return!1;break;case`<`:if(!(e<n.value))return!1;break;case`<=`:if(!(e<=n.value))return!1;break;default:return!1}}catch{return!1}}return!0}resolve(e,t){return{eventPayload:t,patch:{...e.patch??{},__watch_event__:t}}}getField(e,t){let n=t.split(`.`),r=e;for(let e of n){if(r==null||typeof r!=`object`&&!Array.isArray(r))return;let t=Number(e);r=!isNaN(t)&&Array.isArray(r)?r[t]:r[e]}return r}acquireBusSubscription(e){if(this.busSubscriptions.has(e))return;let t=this.bus.subscribe(e,t=>{this.onEvent(e,t)});this.busSubscriptions.set(e,t)}releaseBusSubscription(e){let t=this.byEventType.get(e);if(t&&t.size>0)return;let n=this.busSubscriptions.get(e);if(n){try{n()}catch{}this.busSubscriptions.delete(e)}}removeFromReverseIndex(e,t){let n=this.byEventType.get(t);n&&(n.delete(e),n.size===0&&this.byEventType.delete(t))}},x=class{bus;storeRegistry;timelineStore;pauseService;runServiceDefinitions=[];serviceContainer;workflows=new Map;index=new Map;subscriptions=new Map;pausedRuns=new Map;abortUnsubscribe;signalUnsubscribe;constructor(t){this.bus=t.bus,this.storeRegistry=t.storeRegistry,this.timelineStore=t.timelineStore,this.pauseService=new b({bus:this.bus,resume:async(e,t)=>{this.resume(e,t)}}),this.serviceContainer=new e(new d({}));for(let e of t.services??[]){if(e.id===`__pause_service__`)throw new a({code:r.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Service id "__pause_service__" is reserved for the built-in PauseService and cannot be redefined.`});e.scope===`singleton`?this.serviceContainer.register({key:e.id,factory:()=>e.factory(),scope:`singleton`}):this.runServiceDefinitions.push(e)}this.serviceContainer.register({key:`__pause_service__`,factory:()=>this.pauseService,scope:`singleton`}),this.abortUnsubscribe=this.bus.subscribe(m,e=>{this.abortRun(e.run)}),this.signalUnsubscribe=this.bus.subscribe(h,e=>{this.signal(e.runId,e.patch)})}static async createTestTimelineStore(e=`test-timeline-database`){return new l(await t({database:e,validate:!0,predicates:{},enableTelemetry:!0},n))}async register(e,t){if(this.workflows.has(e.id))throw new a({code:r.DUPLICATE_KEY.code,message:`[WorkflowRuntime] Workflow "${e.id}" is already registered. Call deregister("${e.id}") before registering again.`});let n=s.get(`workflow:${e.id}`,{onExpired:(t,n)=>{console.info(`[WorkflowRuntime] Run "${t}" pause-window expired for workflow "${e.id}". Checkpoint: ${n.pipelineId}.`)},onExportFailed:(t,n)=>{console.error(`[WorkflowRuntime] Deferred export failed for run "${t}" in workflow "${e.id}":`,n)}}),i=async e=>{let r=e.ok?e.value.runId:e.error?.runId;r&&(c.executionContext.settle(r),this.pauseService.onRunEnded(r),this.pausedRuns.delete(r)),n.prune();try{await t.onComplete(e)}finally{await t.onCleanup?.()}},o=this.buildExecutionContext(e.id,t.mode),c;c={workflow:e,mode:t.mode,executionContext:o,factories:new Map,registry:n,hooks:{onPrepare:t.onPrepare,onComplete:i,onResume:t.onResume,onDispatch:t.onDispatch,onCleanup:t.onCleanup}},this.workflows.set(e.id,c);for(let[t,n]of Object.entries(e.triggers)){let r={workflowId:e.id,triggerId:t,trigger:n},i=this.index.get(n.event);i||(i=new Set,this.index.set(n.event,i)),i.add(r),await this.acquireBusSubscription(n.event)}}deregister(e){let t=this.workflows.get(e);if(t){for(let n of Object.values(t.workflow.triggers)){let t=this.index.get(n.event);if(t){for(let n of t)n.workflowId===e&&t.delete(n);t.size===0&&this.index.delete(n.event)}this.releaseBusSubscription(n.event)}t.executionContext.close(),s.destroy(`workflow:${e}`),t.factories.clear(),this.workflows.delete(e)}}hasWorkflow(e){return this.workflows.has(e)}listWorkflows(){return Array.from(this.workflows.keys())}async stop(){for(let e of Array.from(this.workflows.keys()))this.deregister(e);try{this.abortUnsubscribe()}catch{}try{this.signalUnsubscribe()}catch{}}registry(e){return this.workflows.get(e)?.registry}watch(e,t){return this.workflows.get(e)?.registry.get(t)}listAllRuns(){let e=[];for(let[t,n]of this.workflows)for(let r of n.registry.list())e.push({...r,workflowId:t});return e}async invoke(e,t,n){let o=this.workflows.get(e);if(!o)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: workflow "${e}" is not registered.`});if(!o.workflow.pipelines[t])throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] invoke() failed: no pipeline definition for workflow "${e}" trigger "${t}".`});let s=this.generateRunId(e,t),c=await this.executePipeline(o,t,s,n);return c.ok&&c.value.status===`paused`?(this.pausedRuns.set(s,{workflowId:e,triggerId:t}),await this.drainWatchQueue(s)):await o.hooks.onComplete(c),c.ok?i.ok(c.value,{runId:s,triggerId:t}):i.fail(c.error,{runId:s,triggerId:t})}async resume(e,t={}){let n=this.pausedRuns.get(e);if(!n)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] resume() failed: run "${e}" is not in the paused runs registry. It may have already completed, been aborted, or the runId is incorrect.`});let{workflowId:o,triggerId:s}=n,c=this.workflows.get(o);if(!c)throw new a({code:r.RESOURCE_RELEASED.code,message:`[WorkflowRuntime] resume() failed: workflow "${o}" is no longer registered. The workflow may have been deregistered while the run was paused.`});let l=this.getOrCreateFactory(c,s),d=c.registry.hold(e),f;try{let t=await l.resume(e);if(!t.ok)throw t.error;f=t.value}catch(t){throw new a({code:r.INTERNAL_ERROR.code,message:`[WorkflowRuntime] resume() failed to reconstruct context for run "${e}"`,cause:t})}d||f.container.extend(this.serviceContainer),Object.keys(t).length>0&&f.write(t),f.write({__watch__:u}),await c.hooks.onResume?.(f);let p=await f.run();if(p.ok&&p.value.status===`paused`)await this.drainWatchQueue(e);else{let t=this.workflows.get(o);if(t)try{await t.hooks.onComplete(p)}catch(t){console.error(`[WorkflowRuntime] onComplete hook threw during resume for run "${e}":`,t)}}return p.ok?i.ok(p.value,{runId:e,triggerId:s}):i.fail(p.error,{runId:e,triggerId:s})}async signal(e,t){for(let n of this.workflows.values()){let r=n.registry.get(e);if(r?.context){r.context.write(t);return}}}dispatch(e,t){let n=this.index.get(e);if(!n||n.size===0)return;let r={type:e,payload:t,timestamp:Date.now()};for(let e of n){let t=!0;if(e.trigger.predicate)try{t=e.trigger.predicate(r)}catch(n){console.error(`[WorkflowRuntime] Predicate threw for workflow "${e.workflowId}" trigger "${e.triggerId}":`,n),t=!1}if(!t){this.workflows.get(e.workflowId)?.hooks.onDispatch?.({status:`rejected`,reason:`filtered`});continue}let n=this.workflows.get(e.workflowId);n&&n.executionContext.accept(e.triggerId,r,(e,t)=>this.spawnRun(n,e,t)).then(e=>{n.hooks.onDispatch?.(e)}).catch(t=>{console.error(`[WorkflowRuntime] ExecutionContext.accept() threw for workflow "${e.workflowId}":`,t)})}}async executePipeline(e,t,n,r){let o=this.timelineStore?new c(this.timelineStore,{}):void 0,s=this.getOrCreateFactory(e,t),l;try{l=await s.prepare(void 0,n),o&&await o.attach(l),await l.store.set({__trigger_event__:r})}catch(e){o&&await o.detach().catch(()=>{});let t=e instanceof a?e:new a({code:`PIPELINE_PREPARE_FAILED`,message:e instanceof Error?e.message:String(e)});return i.fail(t)}l.container.extend(this.serviceContainer),await e.hooks.onPrepare(l);let u=await l.run();return o&&await o.detach().catch(()=>{}),u}async spawnRun(e,t,n){let r=this.generateRunId(e.workflow.id,t);return this.executePipeline(e,t,r,n).then(async n=>{if(n.ok&&n.value.status===`paused`){this.pausedRuns.set(r,{workflowId:e.workflow.id,triggerId:t}),await this.drainWatchQueue(r);return}try{await e.hooks.onComplete(n)}catch(e){console.error(`[WorkflowRuntime] onComplete hook threw for run "${r}":`,e)}}).catch(e=>{console.error(`[WorkflowRuntime] Pipeline execution failed for run "${r}":`,e)}),r}async drainWatchQueue(e){let t=this.pauseService.onRunPaused(e);if(t!==null)try{await this.resume(e,t.patch)}catch(t){console.error(`[WorkflowRuntime] drainWatchQueue: resume() failed for run "${e}":`,t),this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}}async abortRun(e){for(let t of this.workflows.values()){let n=t.registry.get(e);if(n?.context){try{n.context.abort()}catch(t){console.error(`[WorkflowRuntime] Error aborting run "${e}":`,t)}break}}this.pauseService.onRunEnded(e),this.pausedRuns.delete(e)}buildExecutionContext(e,t){switch(t.type){case`transient`:return new g(e,t.concurrency??10,t.capacity??1e3);case`serialized`:return new _(e,t.capacity??1e3);case`singleton_loop`:return new v(e,t.onActive??`drop`,t.replacementGracePeriod??5e3,(e,t)=>this.signal(e,{__singleton_event__:t}));case`exclusive`:return new y(e,t.onActive??`reject`)}}async acquireBusSubscription(e){let t=this.subscriptions.get(e);t||(t=new p(()=>this.bus.subscribe(e,t=>{this.dispatch(e,t)}),t=>{try{t?.(),this.subscriptions.delete(e)}catch{}},{gracePeriod:`sync`}),this.subscriptions.set(e,t)),await t.acquire()}releaseBusSubscription(e){this.subscriptions.get(e)?.release()}getOrCreateFactory(e,t){let n=e.factories.get(t);if(n)return n;let i=e.workflow.pipelines[t];if(!i)throw new a({code:r.NOT_FOUND.code,message:`[WorkflowRuntime] No pipeline definition found for workflow "${e.workflow.id}" trigger "${t}". Ensure workflow.pipelines["${t}"] is populated by the compiler.`});let s=new o(i,{storeFactory:async e=>this.storeRegistry.get(e),registry:e.registry});return e.factories.set(t,s),s}generateRunId(e,t){return`${e}:${t}:${Date.now()}:${Math.random().toString(36).slice(2)}`}};export{m as ABORT_EVENT,h as SIGNAL_EVENT,x as WorkflowRuntime};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@asaidimu/runtime",
+  "version": "1.0.0",
+  "description": "A runtime for workflows built on \"@asaidimu/utils-pipeline\".",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "keywords": [
+    "typescript",
+    "utility"
+  ],
+  "author": "Saidimu <47994458+asaidimu@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaidimu/erp-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asaidimu/erp-utils/issues"
+  },
+  "homepage": "https://github.com/asaidimu/erp-utils/tree/main/src/runtime#readme",
+  "files": [
+    "./*"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@asaidimu/utils-store": "^10.2.9",
+    "@asaidimu/utils-database": "^3.1.13",
+    "@asaidimu/utils-sync": "^2.3.4",
+    "@asaidimu/utils-pipeline": "^1.3.10",
+    "@asaidimu/utils-artifacts": "^8.2.16",
+    "@asaidimu/utils-error": "^1.0.0",
+    "@asaidimu/utils-events": "^1.2.5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest",
+    "access": "public"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/npm",
+        {
+          "pkgRoot": "./dist"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md",
+            "package.json"
+          ],
+          "message": "chore(release): Release @asaidimu/runtime v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  },
+  "peerDependencies": {}
+}