@lostgradient/weft 0.2.0

package/dist/core/engine/handle-result.js

@@ -0,0 +1,74 @@
+import { EngineDisposedError } from "./errors.js";
+import { WorkflowHandle } from "./handles.js";
+import { loadWorkflowResult, loadWorkflowState } from "./storage-io.js";
+export function createWorkflowHandleWithResultPromise(internals, workflowId) {
+  const handle = new WorkflowHandle(workflowId, internals.engine);
+  cacheHandle(internals, workflowId, handle);
+  return handle;
+}
+export function createWorkflowResultWaiter(internals, workflowId) {
+  const { promise, resolve, reject } = Promise.withResolvers(), waiter = { promise, resolve, reject };
+  internals.resultResolvers.set(workflowId, waiter);
+  promise.catch(() => {});
+  return waiter;
+}
+export function getWorkflowResultPromise(internals, workflowId) {
+  const existingWaiter = internals.resultResolvers.get(workflowId);
+  if (existingWaiter)
+    return existingWaiter.promise;
+  if (internals.disposed) {
+    const rejected = Promise.reject(new EngineDisposedError);
+    rejected.catch(() => {});
+    return rejected;
+  }
+  const waiter = createWorkflowResultWaiter(internals, workflowId);
+  bootstrapWorkflowResultResolver(internals, workflowId, waiter);
+  return waiter.promise;
+}
+export async function bootstrapWorkflowResultResolver(internals, workflowId, waiter) {
+  try {
+    const state = await loadWorkflowState(internals, workflowId);
+    if (linkToReplacementWaiter(internals, workflowId, waiter))
+      return;
+    if (!state) {
+      internals.resultResolvers.delete(workflowId);
+      waiter.reject(Error(`Workflow "${workflowId}" not found in storage`));
+      return;
+    }
+    if (state.status === "running" || state.status === "pending")
+      return;
+    try {
+      const result = await loadWorkflowResult(internals, workflowId);
+      clearResultWaiter(internals, workflowId, waiter);
+      waiter.resolve(result);
+    } catch (error) {
+      clearResultWaiter(internals, workflowId, waiter);
+      waiter.reject(error);
+    }
+  } catch (error) {
+    clearResultWaiter(internals, workflowId, waiter);
+    waiter.reject(error);
+  }
+}
+function linkToReplacementWaiter(internals, workflowId, waiter) {
+  const currentWaiter = internals.resultResolvers.get(workflowId);
+  if (currentWaiter === void 0 || currentWaiter === waiter)
+    return !1;
+  currentWaiter.promise.then(waiter.resolve, waiter.reject);
+  return !0;
+}
+function clearResultWaiter(internals, workflowId, waiter) {
+  if (internals.resultResolvers.get(workflowId) === waiter)
+    internals.resultResolvers.delete(workflowId);
+}
+export function cacheHandle(internals, workflowId, handle) {
+  const existing = internals.handleCache.get(workflowId);
+  if (existing)
+    internals.finalizationRegistry.unregister(existing.unregisterToken);
+  const unregisterToken = {};
+  internals.handleCache.set(workflowId, {
+    ref: new WeakRef(handle),
+    unregisterToken
+  });
+  internals.finalizationRegistry.register(handle, workflowId, unregisterToken);
+}

package/dist/core/engine/handles.d.ts

@@ -0,0 +1,137 @@
+import type { QueryDefinition, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition, WorkflowState } from '../types.ts';
+export declare function getWorkflowExecutionStartedAt(state: Pick<WorkflowState, 'createdAt' | 'startedAt'>): number;
+export declare const HANDLE_RESULT_PROMISE: unique symbol;
+export interface WorkflowHandleEngine extends EventTarget {
+    [HANDLE_RESULT_PROMISE](workflowId: string): Promise<unknown>;
+    cancel(workflowId: string): Promise<void>;
+    signal(workflowId: string, name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
+    update(workflowId: string, name: string, payload?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    query(workflowId: string, name: string, input?: unknown): Promise<unknown>;
+    getAttributes(workflowId: string): Promise<Record<string, SearchAttributeValue> | null>;
+    setAttributes(workflowId: string, attributes: Record<string, SearchAttributeValue>): Promise<void>;
+    addTags(workflowId: string, ...tags: string[]): Promise<void>;
+    removeTags(workflowId: string, ...tags: string[]): Promise<void>;
+    get(workflowId: string): Promise<WorkflowState | null>;
+}
+export interface ScheduleHandleEngine {
+    pauseSchedule(scheduleId: string): Promise<void>;
+    resumeSchedule(scheduleId: string): Promise<void>;
+    cancelSchedule(scheduleId: string): Promise<void>;
+    updateSchedule(scheduleId: string, newSpec: string | ScheduleSpec): Promise<void>;
+    getSchedule(scheduleId: string): Promise<ScheduleSummary | null>;
+}
+/**
+ * Handle to a running or completed workflow. Returned by {@link Engine.start}
+ * and {@link Engine.getHandle}. Use `handle.result()` to await the final
+ * value, `handle.cancel()` to stop execution, `handle.signal(name, payload)`
+ * to send a signal, and `handle.update(name, payload)` to send a synchronous
+ * update. Use `query()`, `getAttributes()`/`setAttributes()`, and
+ * `addTags()`/`removeTags()` for read-only handlers, search metadata, and tag
+ * management. Also an `AsyncIterable` of lifecycle events.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, WorkflowHandle, activity } from '@lostgradient/weft';
+ * import type { WorkflowContext, Context } from '@lostgradient/weft';
+ *
+ * const greet = activity({ name: 'greet', execute: async (i: unknown) => `hi ${i}` });
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'wave' }).execute(async function* (ctx: WorkflowContext, input: unknown) {
+ *     return yield* ctx.run(greet, input);
+ *   }),
+ * );
+ *
+ * const handle = await engine.start('wave', 'world');
+ * const typedHandle: WorkflowHandle = handle;
+ * const result = await handle.result();
+ * void typedHandle;
+ * console.log(result); // 'hi world'
+ * ```
+ *
+ * @example Iterate workflow lifecycle events
+ * ```ts
+ * import { Engine, workflow, type WorkflowHandle } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ *
+ * const handle = await engine.start('ping', null);
+ * const typedHandle: WorkflowHandle = handle;
+ * for await (const event of handle) {
+ *   console.log(event.type);
+ * }
+ * void typedHandle;
+ * ```
+ */
+export declare class WorkflowHandle<TResult = unknown> extends EventTarget implements AsyncDisposable {
+    #private;
+    readonly id: string;
+    constructor(id: string, engine: WorkflowHandleEngine);
+    result(): Promise<TResult>;
+    cancel(): Promise<void>;
+    signal(name: SignalDefinition): Promise<void>;
+    signal<TInput>(name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
+    signal(name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
+    update<TOutput>(name: UpdateDefinition<void, TOutput>, payload?: void, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update<TInput, TOutput>(name: UpdateDefinition<TInput, TOutput>, payload: TInput, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update(name: string, payload?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    query<TOutput>(name: QueryDefinition<void, TOutput>): Promise<TOutput>;
+    query<TInput, TOutput>(name: QueryDefinition<TInput, TOutput>, input: TInput): Promise<TOutput>;
+    query(name: string, input?: unknown): Promise<unknown>;
+    getAttributes(): Promise<Record<string, SearchAttributeValue> | null>;
+    setAttributes(attributes: Record<string, SearchAttributeValue>): Promise<void>;
+    addTags(...tags: string[]): Promise<void>;
+    removeTags(...tags: string[]): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Event>;
+    [Symbol.observable](): {
+        subscribe: (observer: {
+            next?: (event: Event) => void;
+            complete?: () => void;
+            error?: (error: Error) => void;
+        }) => {
+            unsubscribe: () => void;
+        };
+    };
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Handle to a recurring schedule created by {@link Engine.schedule}. Use
+ * `handle.pause()`, `handle.resume()`, `handle.cancel()`, or
+ * `handle.update(cronExpression)` to manage the schedule lifecycle.
+ * `handle.describe()` returns the current {@link ScheduleSummary}.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, ScheduleHandle } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'daily-report' }).execute(async function* () { return 'ok'; }));
+ *
+ * const handle = await engine.schedule('daily-report', null, '0 9 * * *');
+ * const typedHandle: ScheduleHandle = handle;
+ * await handle.pause();
+ * const summary = await handle.describe();
+ * void typedHandle;
+ * console.log(summary.status); // 'paused'
+ * await handle.cancel();
+ * ```
+ */
+export declare class ScheduleHandle {
+    #private;
+    readonly id: string;
+    constructor(id: string, engine: ScheduleHandleEngine);
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cancel(): Promise<void>;
+    update(newSpec: string | ScheduleSpec): Promise<void>;
+    describe(): Promise<ScheduleSummary>;
+}

package/dist/core/engine/handles.js

@@ -0,0 +1,173 @@
+import {
+  WorkflowCancelledEvent,
+  WorkflowCompletedEvent,
+  WorkflowFailedEvent,
+  WorkflowTimedOutEvent
+} from "../events.js";
+import { WorkflowTimeoutError } from "../timeouts.js";
+import { messageName } from "../types.js";
+import { createWorkflowHandleEventIterator } from "./handle-iteration.js";
+export function getWorkflowExecutionStartedAt(state) {
+  return state.startedAt ?? state.createdAt;
+}
+function synthesizeTerminalEventFromState(state) {
+  switch (state.status) {
+    case "completed": {
+      const duration = state.updatedAt - getWorkflowExecutionStartedAt(state);
+      return new WorkflowCompletedEvent(state.id, state.result, duration);
+    }
+    case "failed": {
+      const error = Error(state.error ?? "Workflow failed");
+      if (state.errorStack)
+        error.stack = state.errorStack;
+      return new WorkflowFailedEvent(state.id, error);
+    }
+    case "cancelled":
+      return new WorkflowCancelledEvent(state.id);
+    case "timed-out": {
+      const elapsed = state.updatedAt - getWorkflowExecutionStartedAt(state);
+      return new WorkflowTimedOutEvent(state.id, "execution", elapsed, state.terminationReason);
+    }
+    default:
+      return null;
+  }
+}
+export const HANDLE_RESULT_PROMISE = Symbol("handleResultPromise");
+
+export class WorkflowHandle extends EventTarget {
+  id;
+  #engine;
+  #resultPromise;
+  constructor(id, engine) {
+    super();
+    this.id = id;
+    this.#engine = engine;
+    this.#resultPromise = void 0;
+  }
+  async result() {
+    this.#resultPromise ??= this.#engine[HANDLE_RESULT_PROMISE](this.id);
+    return this.#resultPromise;
+  }
+  async cancel() {
+    return this.#engine.cancel(this.id);
+  }
+  async signal(nameOrDefinition, payload, options) {
+    return this.#engine.signal(this.id, messageName(nameOrDefinition), payload, options);
+  }
+  async update(nameOrDefinition, payload, options) {
+    return this.#engine.update(this.id, messageName(nameOrDefinition), payload, options);
+  }
+  async query(nameOrDefinition, input) {
+    return this.#engine.query(this.id, messageName(nameOrDefinition), input);
+  }
+  async getAttributes() {
+    return this.#engine.getAttributes(this.id);
+  }
+  async setAttributes(attributes) {
+    return this.#engine.setAttributes(this.id, attributes);
+  }
+  async addTags(...tags) {
+    return this.#engine.addTags(this.id, ...tags);
+  }
+  async removeTags(...tags) {
+    return this.#engine.removeTags(this.id, ...tags);
+  }
+  async* [Symbol.asyncIterator]() {
+    yield* createWorkflowHandleEventIterator(this, () => this.#engine.get(this.id), synthesizeTerminalEventFromState);
+  }
+  [Symbol.observable]() {
+    return {
+      subscribe: (observer) => {
+        const controller = new AbortController, nextListener = observer.next?.bind(observer), types = [
+          "workflow:completed",
+          "workflow:failed",
+          "workflow:cancelled",
+          "workflow:timed-out",
+          "activity:started",
+          "activity:completed"
+        ];
+        let terminalDelivered = !1;
+        if (nextListener) {
+          const guardedNext = (event) => {
+            if (terminalDelivered)
+              return;
+            nextListener(event);
+          };
+          for (const type of types)
+            this.addEventListener(type, guardedNext, { signal: controller.signal });
+        }
+        const errorHandler = (event) => {
+          if (terminalDelivered)
+            return;
+          if (event instanceof WorkflowFailedEvent) {
+            terminalDelivered = !0;
+            observer.error?.(event.error);
+          } else if (event instanceof WorkflowTimedOutEvent) {
+            terminalDelivered = !0;
+            observer.error?.(new WorkflowTimeoutError(event.workflowId, event.timeoutType, event.elapsed));
+          }
+        };
+        this.addEventListener("workflow:failed", errorHandler, { signal: controller.signal });
+        this.addEventListener("workflow:timed-out", errorHandler, { signal: controller.signal });
+        const completeListener = observer.complete?.bind(observer), completeDispatcher = () => {
+          if (terminalDelivered)
+            return;
+          terminalDelivered = !0;
+          completeListener?.();
+        };
+        this.addEventListener("workflow:completed", completeDispatcher, {
+          signal: controller.signal
+        });
+        this.addEventListener("workflow:cancelled", completeDispatcher, {
+          signal: controller.signal
+        });
+        (async () => {
+          const persisted = await this.#engine.get(this.id);
+          if (controller.signal.aborted || terminalDelivered || !persisted)
+            return;
+          const synthetic = synthesizeTerminalEventFromState(persisted);
+          if (!synthetic)
+            return;
+          nextListener?.(synthetic);
+          if (synthetic instanceof WorkflowFailedEvent)
+            errorHandler(synthetic);
+          else if (synthetic instanceof WorkflowTimedOutEvent)
+            errorHandler(synthetic);
+          else
+            completeDispatcher();
+        })();
+        return {
+          unsubscribe: controller.abort.bind(controller)
+        };
+      }
+    };
+  }
+  async[Symbol.asyncDispose]() {}
+}
+
+export class ScheduleHandle {
+  id;
+  #engine;
+  constructor(id, engine) {
+    this.id = id;
+    this.#engine = engine;
+  }
+  async pause() {
+    await this.#engine.pauseSchedule(this.id);
+  }
+  async resume() {
+    await this.#engine.resumeSchedule(this.id);
+  }
+  async cancel() {
+    await this.#engine.cancelSchedule(this.id);
+  }
+  async update(newSpec) {
+    await this.#engine.updateSchedule(this.id, newSpec);
+  }
+  async describe() {
+    const schedule = await this.#engine.getSchedule(this.id);
+    if (!schedule)
+      throw Error(`Schedule "${this.id}" not found`);
+    return schedule;
+  }
+}