@tyvm/knowhow 0.0.161 → 0.0.163

package/ts_build/src/services/stateful/ProcessMirror.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessMirror = void 0;
+const crypto_1 = require("crypto");
+const changesIterable_1 = require("./changesIterable");
+const types_1 = require("./types");
+class ProcessMirror {
+    source;
+    doc;
+    stateListeners = new Set();
+    controlListeners = new Set();
+    unwatch;
+    constructor(source, doc) {
+        this.source = source;
+        this.doc = doc;
+        this.unwatch = source.watchDocument((d, events) => this.ingest(d, events));
+    }
+    static async open(source) {
+        const doc = await source.readDocument();
+        if (!doc)
+            throw new Error("ProcessMirror.open: source has no document");
+        return new ProcessMirror(source, doc);
+    }
+    ingest(next, events) {
+        const prev = this.doc;
+        const newer = next.version > prev.version ||
+            next.controlVersion > prev.controlVersion ||
+            next.observedControlVersion > prev.observedControlVersion;
+        if (!newer)
+            return;
+        this.doc = next;
+        if (next.controlVersion > prev.controlVersion) {
+            const change = {
+                controlVersion: next.controlVersion,
+                prev: prev.control,
+                next: next.control,
+                source: "source",
+            };
+            for (const cb of [...this.controlListeners])
+                this.safe(() => cb(change));
+        }
+        if (next.version > prev.version || events.length) {
+            const change = {
+                version: next.version,
+                prev: prev.state,
+                next: next.state,
+                events,
+            };
+            for (const cb of [...this.stateListeners])
+                this.safe(() => cb(change));
+        }
+    }
+    safe(fn) {
+        try {
+            fn();
+        }
+        catch {
+        }
+    }
+    get meta() {
+        return this.doc.meta;
+    }
+    getState() {
+        return this.doc.state;
+    }
+    getControl() {
+        return this.doc.control;
+    }
+    getLifecycle() {
+        return this.doc.lifecycle;
+    }
+    getDocument() {
+        return this.doc;
+    }
+    isControlObserved() {
+        return this.doc.observedControlVersion >= this.doc.controlVersion;
+    }
+    onStateUpdated(cb) {
+        this.stateListeners.add(cb);
+        return () => {
+            this.stateListeners.delete(cb);
+        };
+    }
+    onControlUpdated(cb) {
+        this.controlListeners.add(cb);
+        return () => {
+            this.controlListeners.delete(cb);
+        };
+    }
+    changes(signal) {
+        return (0, changesIterable_1.changesIterable)((cb) => this.onStateUpdated(cb), () => (0, types_1.isTerminalStatus)(this.doc.lifecycle.status), signal);
+    }
+    async applyControl(patch) {
+        const p = typeof patch === "function"
+            ? patch(structuredClone(this.doc.control))
+            : patch;
+        await this.source.writeControl(p);
+    }
+    async send(kind, payload, opts = {}) {
+        await this.source.appendInput({ kind, payload, id: opts.id, from: opts.from });
+    }
+    pause() {
+        return this.applyControl({ desired: "paused" });
+    }
+    resume() {
+        return this.applyControl({ desired: "running" });
+    }
+    cancel() {
+        return this.applyControl({ desired: "cancelled" });
+    }
+    interrupt(message) {
+        return this.applyControl({ interrupt: { id: (0, crypto_1.randomUUID)(), message } });
+    }
+    close() {
+        this.unwatch?.();
+        this.unwatch = undefined;
+    }
+}
+exports.ProcessMirror = ProcessMirror;
+//# sourceMappingURL=ProcessMirror.js.map

package/ts_build/src/services/stateful/ProcessMirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessMirror.js","sourceRoot":"","sources":["../../../../src/services/stateful/ProcessMirror.ts"],"names":[],"mappings":"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"}

package/ts_build/src/services/stateful/ResumableProcess.d.ts

@@ -0,0 +1,11 @@
+import type { Channel, DocSource } from "./channels/Channel";
+import { ProcessInit, StatefulProcess } from "./StatefulProcess";
+import type { BaseControl, ProcessDocument } from "./types";
+export declare abstract class ResumableProcess<S = any, C extends BaseControl = BaseControl, E = never> extends StatefulProcess<S, C, E> {
+    abstract start(input: unknown): Promise<unknown>;
+    protected abstract resumeFrom(doc: ProcessDocument<S, C>): Promise<unknown>;
+    resumeRun(): Promise<unknown>;
+    static load<P extends ResumableProcess<any, any, any>>(this: new (init: ProcessInit<any, any>) => P, from: ProcessDocument | Pick<DocSource, "readDocument">, opts?: {
+        channels?: Channel[];
+    }): Promise<P>;
+}

package/ts_build/src/services/stateful/ResumableProcess.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResumableProcess = void 0;
+const StatefulProcess_1 = require("./StatefulProcess");
+class ResumableProcess extends StatefulProcess_1.StatefulProcess {
+    resumeRun() {
+        return this.run(() => this.resumeFrom(this.snapshot()));
+    }
+    static async load(from, opts = {}) {
+        const doc = "meta" in from ? from : await from.readDocument();
+        if (!doc)
+            throw new Error("ResumableProcess.load: no document found");
+        const p = new this({ kind: doc.meta.kind, document: doc });
+        for (const ch of opts.channels ?? [])
+            await p.attach(ch);
+        return p;
+    }
+}
+exports.ResumableProcess = ResumableProcess;
+//# sourceMappingURL=ResumableProcess.js.map

package/ts_build/src/services/stateful/ResumableProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResumableProcess.js","sourceRoot":"","sources":["../../../../src/services/stateful/ResumableProcess.ts"],"names":[],"mappings":";;;AACA,uDAAiE;AAcjE,MAAsB,gBAIpB,SAAQ,iCAAwB;IAKhC,SAAS;QACP,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAEf,IAAuD,EACvD,OAAiC,EAAE;QAEnC,MAAM,GAAG,GACP,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACpD,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;QAC3D,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE;YAAE,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC;IACX,CAAC;CACF;AAzBD,4CAyBC"}

package/ts_build/src/services/stateful/StatefulProcess.d.ts

@@ -0,0 +1,92 @@
+import { Channel, ChannelLogger } from "./channels/Channel";
+import { BaseControl, ControlChange, InputCursor, InputItem, Lifecycle, ProcessDocument, ProcessHandle, ProcessMeta, ProcessStatus, StateChange, Unsubscribe } from "./types";
+export interface ProcessInit<S, C extends BaseControl = BaseControl> {
+    id?: string;
+    kind: string;
+    name?: string;
+    parentId?: string;
+    schemaVersion?: number;
+    links?: Record<string, string>;
+    state?: S;
+    control?: C;
+    lifecycle?: Partial<Lifecycle>;
+    document?: ProcessDocument<S, C>;
+    log?: ChannelLogger;
+}
+export declare abstract class StatefulProcess<S = any, C extends BaseControl = BaseControl, E = never> implements ProcessHandle<S, C, E> {
+    private _meta;
+    private _state;
+    private _control;
+    private _lifecycle;
+    private _version;
+    private _controlVersion;
+    private _observedControlVersion;
+    private _channels;
+    private pumps;
+    private stateListeners;
+    private controlListeners;
+    private controlWaiters;
+    private controlChain;
+    private inputChain;
+    private inbox;
+    private inputWaiters;
+    private localSeq;
+    protected log: ChannelLogger;
+    constructor(init: ProcessInit<S, C>);
+    get meta(): ProcessMeta;
+    getState(): Readonly<S>;
+    getControl(): Readonly<C>;
+    getLifecycle(): Readonly<Lifecycle>;
+    snapshot(): ProcessDocument<S, C>;
+    protected update(mutate: (draft: S) => void | S, opts?: {
+        events?: E[];
+        reason?: string;
+    }): void;
+    protected replaceState(next: S, opts?: {
+        events?: E[];
+        reason?: string;
+    }): void;
+    protected emit(...events: E[]): void;
+    protected setStatus(status: ProcessStatus, extra?: Partial<Lifecycle>): void;
+    protected consume(items: InputItem[], cursor: InputCursor, apply: (draft: S, items: InputItem[]) => void): void;
+    private afterCommit;
+    applyControl(patch: Partial<C> | ((c: C) => C), source?: string): void;
+    private reconcile;
+    send(kind: string, payload: unknown, opts?: {
+        id?: string;
+        from?: string;
+    }): InputItem;
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+    interrupt(message?: string): void;
+    protected onControl?(change: ControlChange<C>): void | Promise<void>;
+    protected onPause?(): void | Promise<void>;
+    protected onResume?(): void | Promise<void>;
+    protected onCancel?(): void | Promise<void>;
+    protected onInterrupt?(message?: string): void | Promise<void>;
+    protected onInput?(items: InputItem[], cursor: InputCursor): void | Promise<void>;
+    private enqueueDelivery;
+    private deliverInput;
+    private serveInputWaiters;
+    private rejectInputWaitersIfCancelled;
+    waitForInput(filter?: {
+        kind?: string;
+        timeoutMs?: number;
+    }): Promise<InputItem>;
+    onStateUpdated(cb: (c: StateChange<S, E>) => void): Unsubscribe;
+    onControlUpdated(cb: (c: ControlChange<C>) => void): Unsubscribe;
+    changes(signal?: AbortSignal): AsyncIterable<StateChange<S, E>>;
+    private wakeControlWaiters;
+    private nextControlChange;
+    checkpoint(): Promise<void>;
+    private makeContext;
+    attach(channel: Channel<S, C, E>): Promise<Unsubscribe>;
+    private removeChannel;
+    detach(channelId: string): Promise<void>;
+    channels(): readonly Channel<S, C, E>[];
+    flush(): Promise<void>;
+    persisted(version: number, channelId?: string): Promise<void>;
+    close(): Promise<void>;
+    run<R>(body: (p: this) => Promise<R>): Promise<R>;
+}