@zlink-systems/framework 0.30.3 → 0.32.0

package/dist/runtime/foundation/operation-registry.d.ts

@@ -9,8 +9,27 @@ export declare class OperationCancelledError extends Error {
     readonly operationId: bigint;
     constructor(operationId: bigint, message?: string);
 }
-export interface PendingOperation<T> {
+export interface OperationHandle<T> {
     readonly id: bigint;
+    readonly deadlineMs: number | undefined;
+    readonly promise?: Promise<T>;
+    complete(value: T, retentionMs?: number): boolean;
+    fail(reason: unknown): boolean;
+    takeFailure(reason: unknown): boolean;
+    resolveCaller(value: T): boolean;
+    rejectCaller(reason: unknown): boolean;
+    isPending(): boolean;
+    hasObserver(): boolean;
+    setFailureDispatcher(dispatcher: (reason: unknown) => void): void;
+    clearFailureDispatcher(dispatcher: (reason: unknown) => void): void;
+    setObserver(observer: OperationObserver<T, unknown>, context?: unknown): void;
+    deferCompletion(): void;
+    reply(value: T, retentionMs?: number): boolean;
+    replyFailure(reason: unknown): boolean;
+    setSignal(signal: AbortSignal | undefined): void;
+    mapCaller(onValue: (value: unknown) => unknown, onFailure: (error: unknown) => unknown): boolean;
+}
+export interface PendingOperation<T> extends OperationHandle<T> {
     readonly promise: Promise<T>;
 }
 /**
@@ -26,8 +45,10 @@ export interface OperationObserver<T, Context> {
 export declare class OperationRegistry<T, Context = unknown> {
     private readonly clock;
     private readonly onPendingChanged?;
+    private readonly terminalError;
     private readonly entries;
     private nextId;
+    private lastVisitMs;
     private deadlineCursor?;
     /**
      * A lower bound of the earliest pending deadline. Completed entries only
@@ -37,23 +58,32 @@ export declare class OperationRegistry<T, Context = unknown> {
     private scanEarliestDeadlineMs;
     private closed;
     private pendingCount;
-    constructor(clock?: OperationClock, onPendingChanged?: (() => void) | undefined);
-    register(timeoutMs: number, timeoutOwner?: 'registry' | 'sender', context?: Context): PendingOperation<T>;
+    constructor(clock?: OperationClock, onPendingChanged?: (() => void) | undefined, terminalError?: (reason: unknown) => unknown);
+    register(timeoutMs: number, timeoutOwner?: 'registry' | 'sender', context?: Context, absoluteDeadlineMs?: number): PendingOperation<T>;
+    handle(id: bigint): OperationHandle<T>;
     /** Registers an operation whose terminal goes to `observer` instead of a Promise. */
     registerObserved(timeoutMs: number, observer: OperationObserver<T, Context>, context?: Context): bigint;
+    deadline(id: bigint): number | undefined;
+    setFailureDispatcher(id: bigint, dispatcher: (reason: unknown) => void): boolean;
+    clearFailureDispatcher(id: bigint, dispatcher: (reason: unknown) => void): void;
+    takeFailure(id: bigint, reason: unknown): boolean;
     /** The time the next expiry pass has work, as a lower bound (spec 08 §4.2). */
     nextDeadlineMs(): number;
     private notePending;
     complete(id: bigint, value: T, terminalContextRetentionMs?: number): boolean;
+    reply(id: bigint, value: T, terminalContextRetentionMs?: number): boolean;
     fail(id: bigint, reason: unknown): boolean;
     cancel(id: bigint, message?: string): boolean;
     isPending(id: bigint): boolean;
+    setContext(id: bigint, context: Context): void;
     context(id: bigint): Context | undefined;
+    clear(reason: unknown): void;
     close(reason?: string): void;
     failAll(reason: unknown): void;
     get size(): number;
     expire(nowMs: number, turnDeadlineMs: number): number;
     private take;
+    private resetEmptyIndex;
     private pendingEntry;
     private retainTerminal;
 }

package/dist/runtime/foundation/operation-registry.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OperationRegistry = exports.OperationCancelledError = exports.OperationTimeoutError = void 0;
+const abort_1 = require("../abort");
 class OperationTimeoutError extends Error {
     operationId;
     constructor(operationId) {
@@ -19,6 +20,168 @@ class OperationCancelledError extends Error {
     }
 }
 exports.OperationCancelledError = OperationCancelledError;
+class RegistryOperation {
+    registry;
+    id;
+    deadlineMs;
+    context;
+    promise;
+    resolve;
+    reject;
+    observer;
+    failureDispatcher;
+    terminalRetentionMs = 0;
+    signal;
+    callerValue;
+    callerFailure;
+    constructor(registry, id, deadlineMs, context) {
+        this.registry = registry;
+        this.id = id;
+        this.deadlineMs = deadlineMs;
+        this.context = context;
+    }
+    complete(value, retentionMs = this.terminalRetentionMs) {
+        if (this.promise !== undefined)
+            this.observer = undefined;
+        return this.registry.complete(this.id, value, retentionMs);
+    }
+    reply(value, retentionMs = 0) {
+        if (!this.isPending())
+            return false;
+        if (this.promise === undefined || this.observer === undefined)
+            return this.registry.complete(this.id, value, retentionMs);
+        const observer = this.observer;
+        this.observer = this;
+        if (observer !== this)
+            this.terminalRetentionMs = retentionMs;
+        observer.operationCompleted(this.id, value, this.context);
+        return true;
+    }
+    replyFailure(reason) {
+        if (!this.isPending())
+            return false;
+        if (this.promise === undefined || this.observer === undefined)
+            return this.fail(reason);
+        const observer = this.observer;
+        this.observer = this;
+        observer.operationFailed(this.id, reason, this.context);
+        return true;
+    }
+    setSignal(signal) {
+        this.signal = signal;
+        if (signal?.aborted === true)
+            this.handleEvent();
+        else
+            signal?.addEventListener('abort', this, { once: true });
+    }
+    handleEvent() {
+        this.fail(this.signal?.reason ?? (0, abort_1.createAbortError)());
+    }
+    detachSignal() {
+        this.signal?.removeEventListener('abort', this);
+        this.signal = undefined;
+    }
+    mapCaller(onValue, onFailure) {
+        if (this.resolve === undefined || this.reject === undefined)
+            return false;
+        const value = this.callerValue;
+        const failure = this.callerFailure;
+        this.callerValue =
+            value === undefined
+                ? onValue
+                : (reply) => {
+                    let mapped;
+                    try {
+                        mapped = value(reply);
+                    }
+                    catch (error) {
+                        throw onFailure(error);
+                    }
+                    return onValue(mapped);
+                };
+        this.callerFailure =
+            failure === undefined
+                ? onFailure
+                : (error) => {
+                    let mapped = error;
+                    try {
+                        mapped = failure(error);
+                    }
+                    catch (reason) {
+                        mapped = reason;
+                    }
+                    return onFailure(mapped);
+                };
+        return true;
+    }
+    fail(reason) {
+        return this.registry.fail(this.id, reason);
+    }
+    takeFailure(reason) {
+        return this.registry.takeFailure(this.id, reason);
+    }
+    isPending() {
+        return this.registry.isPending(this.id);
+    }
+    setFailureDispatcher(dispatcher) {
+        if (!this.registry.setFailureDispatcher(this.id, dispatcher) && this.promise !== undefined)
+            void this.promise.then(undefined, dispatcher);
+    }
+    clearFailureDispatcher(dispatcher) {
+        this.registry.clearFailureDispatcher(this.id, dispatcher);
+    }
+    hasObserver() {
+        return this.observer !== undefined;
+    }
+    setObserver(observer, context) {
+        if (context !== undefined)
+            this.context = context;
+        this.observer = observer;
+    }
+    deferCompletion() {
+        this.observer = this;
+    }
+    operationCompleted() { }
+    operationFailed() { }
+    resolveCaller(value) {
+        this.detachSignal();
+        const resolve = this.resolve, reject = this.reject, map = this.callerValue;
+        this.resolve = undefined;
+        this.reject = undefined;
+        this.callerValue = undefined;
+        this.callerFailure = undefined;
+        if (resolve === undefined)
+            return false;
+        try {
+            resolve(map === undefined ? value : map(value));
+        }
+        catch (error) {
+            reject?.(error);
+        }
+        return true;
+    }
+    rejectCaller(reason) {
+        this.detachSignal();
+        const reject = this.reject, map = this.callerFailure;
+        this.resolve = undefined;
+        this.reject = undefined;
+        this.callerValue = undefined;
+        this.callerFailure = undefined;
+        if (reject === undefined)
+            return false;
+        let failure = reason;
+        try {
+            if (map !== undefined)
+                failure = map(reason);
+        }
+        catch (error) {
+            failure = error;
+        }
+        reject(failure);
+        return true;
+    }
+}
+const DEADLINE_ROTATION_MS = 256;
 const systemClock = {
     now: () => performance.now()
 };
@@ -26,8 +189,10 @@ const systemClock = {
 class OperationRegistry {
     clock;
     onPendingChanged;
+    terminalError;
     entries = new Map();
     nextId = 1n;
+    lastVisitMs;
     deadlineCursor;
     /**
      * A lower bound of the earliest pending deadline. Completed entries only
@@ -37,28 +202,36 @@ class OperationRegistry {
     scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
     closed = false;
     pendingCount = 0;
-    constructor(clock = systemClock, onPendingChanged) {
+    constructor(clock = systemClock, onPendingChanged, terminalError = (reason) => reason) {
         this.clock = clock;
         this.onPendingChanged = onPendingChanged;
+        this.terminalError = terminalError;
+        this.lastVisitMs = this.clock.now();
     }
-    register(timeoutMs, timeoutOwner = 'registry', context) {
+    register(timeoutMs, timeoutOwner = 'registry', context, absoluteDeadlineMs) {
         if (this.closed)
             throw new Error('Operation registry is closed.');
         if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
             throw new RangeError('timeoutMs must be a non-negative finite number.');
         }
         const id = this.nextId++;
-        let resolve;
-        let reject;
-        const promise = new Promise((onResolve, onReject) => {
-            resolve = onResolve;
-            reject = onReject;
+        const deadlineMs = timeoutOwner === 'registry'
+            ? (absoluteDeadlineMs ?? this.clock.now() + timeoutMs)
+            : undefined;
+        const entry = new RegistryOperation(this, id, deadlineMs, context);
+        entry.promise = new Promise((resolve, reject) => {
+            entry.resolve = resolve;
+            entry.reject = reject;
         });
-        const deadlineMs = timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined;
-        const entry = { context, deadlineMs, resolve, reject };
         this.entries.set(id, entry);
         this.notePending(deadlineMs);
-        return { id, promise };
+        return entry;
+    }
+    handle(id) {
+        const entry = this.entries.get(id);
+        if (!(entry instanceof RegistryOperation))
+            throw new Error(`Operation ${id} has no active registry entry.`);
+        return entry;
     }
     /** Registers an operation whose terminal goes to `observer` instead of a Promise. */
     registerObserved(timeoutMs, observer, context) {
@@ -69,13 +242,44 @@ class OperationRegistry {
         }
         const id = this.nextId++;
         const deadlineMs = this.clock.now() + timeoutMs;
-        this.entries.set(id, { context, deadlineMs, observer });
+        const entry = new RegistryOperation(this, id, deadlineMs, context);
+        entry.observer = observer;
+        this.entries.set(id, entry);
         this.notePending(deadlineMs);
         return id;
     }
+    deadline(id) {
+        return this.entries.get(id)?.deadlineMs;
+    }
+    setFailureDispatcher(id, dispatcher) {
+        const entry = this.pendingEntry(id);
+        if (entry === undefined)
+            return false;
+        entry.failureDispatcher = dispatcher;
+        return true;
+    }
+    clearFailureDispatcher(id, dispatcher) {
+        const entry = this.pendingEntry(id);
+        if (entry?.failureDispatcher === dispatcher)
+            entry.failureDispatcher = undefined;
+    }
+    takeFailure(id, reason) {
+        const entry = this.take(id);
+        if (entry === undefined)
+            return false;
+        entry.failureDispatcher = undefined;
+        entry.observer = undefined;
+        entry.context = undefined;
+        entry.rejectCaller(this.terminalError(reason));
+        return true;
+    }
     /** The time the next expiry pass has work, as a lower bound (spec 08 §4.2). */
     nextDeadlineMs() {
-        return this.earliestDeadlineMs;
+        if (this.entries.size === 0)
+            return Number.POSITIVE_INFINITY;
+        if (this.deadlineCursor !== undefined)
+            return Math.min(this.lastVisitMs, this.earliestDeadlineMs);
+        return Math.min(this.earliestDeadlineMs, this.lastVisitMs + DEADLINE_ROTATION_MS);
     }
     notePending(deadlineMs) {
         this.pendingCount++;
@@ -89,21 +293,33 @@ class OperationRegistry {
         const entry = this.take(id);
         if (entry === undefined)
             return false;
-        if (entry.observer !== undefined)
-            entry.observer.operationCompleted(id, value, entry.context);
+        entry.failureDispatcher = undefined;
+        const observer = entry.observer;
+        entry.observer = undefined;
+        if (observer !== undefined)
+            observer.operationCompleted(id, value, entry.context);
         else
-            entry.resolve(value);
+            entry.resolveCaller(value);
         this.retainTerminal(id, entry, terminalContextRetentionMs);
+        entry.context = undefined;
         return true;
     }
+    reply(id, value, terminalContextRetentionMs = 0) {
+        return this.pendingEntry(id)?.reply(value, terminalContextRetentionMs) ?? false;
+    }
     fail(id, reason) {
         const entry = this.take(id);
         if (entry === undefined)
             return false;
-        if (entry.observer !== undefined)
-            entry.observer.operationFailed(id, reason, entry.context);
-        else
-            entry.reject(reason);
+        reason = this.terminalError(reason);
+        const dispatch = entry.failureDispatcher;
+        entry.failureDispatcher = undefined;
+        dispatch?.(reason);
+        const observer = entry.observer;
+        entry.observer = undefined;
+        observer?.operationFailed(id, reason, entry.context);
+        entry.context = undefined;
+        entry.rejectCaller(reason);
         return true;
     }
     cancel(id, message) {
@@ -112,9 +328,19 @@ class OperationRegistry {
     isPending(id) {
         return this.pendingEntry(id) !== undefined;
     }
+    setContext(id, context) {
+        const entry = this.pendingEntry(id);
+        if (entry !== undefined)
+            entry.context = context;
+    }
     context(id) {
         return this.entries.get(id)?.context;
     }
+    clear(reason) {
+        this.failAll(reason);
+        this.entries.clear();
+        this.resetEmptyIndex();
+    }
     close(reason = 'Operation registry closed.') {
         if (this.closed)
             return;
@@ -122,7 +348,7 @@ class OperationRegistry {
         for (const id of this.entries.keys())
             this.cancel(id, reason);
         this.entries.clear();
-        this.deadlineCursor = undefined;
+        this.resetEmptyIndex();
     }
     failAll(reason) {
         for (const id of this.entries.keys())
@@ -132,13 +358,17 @@ class OperationRegistry {
         return this.pendingCount;
     }
     expire(nowMs, turnDeadlineMs) {
+        if (this.entries.size === 0)
+            return 0;
         let expired = 0;
+        if (this.deadlineCursor === undefined) {
+            this.lastVisitMs = nowMs;
+            this.deadlineCursor = this.entries.entries();
+            this.scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
+        }
+        const cursor = this.deadlineCursor;
         while (this.clock.now() < turnDeadlineMs) {
-            if (this.deadlineCursor === undefined) {
-                this.deadlineCursor = this.entries.entries();
-                this.scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
-            }
-            const current = this.deadlineCursor.next();
+            const current = cursor.next();
             if (current.done === true) {
                 this.deadlineCursor = undefined;
                 // Entries registered during the pass are appended and were scanned.
@@ -149,8 +379,11 @@ class OperationRegistry {
             if (entry.deadlineMs === undefined)
                 continue;
             if (entry.deadlineMs <= nowMs) {
-                if (!this.isPending(id))
+                if (!this.isPending(id)) {
                     this.entries.delete(id);
+                    if (this.entries.size === 0)
+                        this.resetEmptyIndex();
+                }
                 else if (this.fail(id, new OperationTimeoutError(id)))
                     expired++;
             }
@@ -165,26 +398,32 @@ class OperationRegistry {
         if (entry === undefined)
             return undefined;
         this.entries.delete(id);
+        if (this.entries.size === 0)
+            this.resetEmptyIndex();
         this.pendingCount--;
         if (this.pendingCount === 0)
             this.onPendingChanged?.();
         return entry;
     }
+    resetEmptyIndex() {
+        this.deadlineCursor = undefined;
+        this.earliestDeadlineMs = Number.POSITIVE_INFINITY;
+        this.scanEarliestDeadlineMs = Number.POSITIVE_INFINITY;
+    }
     pendingEntry(id) {
         const entry = this.entries.get(id);
-        return entry !== undefined && (entry.resolve !== undefined || entry.observer !== undefined)
+        return entry instanceof RegistryOperation &&
+            (entry.resolve !== undefined || entry.observer !== undefined)
             ? entry
             : undefined;
     }
     retainTerminal(id, entry, retentionMs) {
         if (this.closed || entry.context === undefined || retentionMs === 0)
             return;
-        entry.resolve = undefined;
-        entry.reject = undefined;
-        entry.observer = undefined;
-        entry.deadlineMs = this.clock.now() + retentionMs;
-        this.entries.set(id, entry);
-        this.earliestDeadlineMs = Math.min(this.earliestDeadlineMs, entry.deadlineMs);
+        const retained = { context: entry.context, deadlineMs: this.clock.now() + retentionMs };
+        this.entries.set(id, retained);
+        this.earliestDeadlineMs = Math.min(this.earliestDeadlineMs, retained.deadlineMs);
+        this.onPendingChanged?.();
     }
 }
 exports.OperationRegistry = OperationRegistry;