build(spf): build26 from 45504a2b

dist/dev/core/tasks/task.d.ts

@@ -0,0 +1,115 @@
+//#region src/core/tasks/task.d.ts
+/** Recursively marks all properties as readonly. */
+type DeepReadonly<T> = T extends (infer U)[] ? ReadonlyArray<DeepReadonly<U>> : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
+type TaskStatus = 'pending' | 'running' | 'done' | 'error';
+/**
+ * Configuration for a Task.
+ */
+interface TaskConfig {
+  /**
+   * Identifier for this task.
+   * - string: used as-is
+   * - () => string: called once at construction time
+   * - undefined: a unique ID is generated via generateId()
+   */
+  id?: string | (() => string);
+  /**
+   * Optional external AbortSignal to compose with the task's internal one.
+   * The task's work is aborted when either the internal controller (via abort())
+   * or this external signal fires — whichever comes first.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Minimal contract for a schedulable unit of async work.
+ */
+interface TaskLike<TValue = void, TError = unknown> {
+  readonly id: string;
+  readonly status: TaskStatus;
+  readonly value: DeepReadonly<TValue> | undefined;
+  readonly error: DeepReadonly<TError> | undefined;
+  run(): Promise<TValue>;
+  abort(): void;
+}
+/**
+ * Generic reusable task that wraps an async run function.
+ *
+ * Owns its own AbortController so it can always be aborted independently.
+ * Optionally composes an external AbortSignal so that a parent's cancellation
+ * propagates into the task's work without requiring the caller to track the
+ * task separately.
+ *
+ * Ordering guarantee: `value` is written before `status` transitions to `'done'`;
+ * `error` is written before `status` transitions to `'error'`. Any reader
+ * observing `status === 'done'` is guaranteed `value` is already present.
+ */
+declare class Task<TValue = void, TError = unknown> implements TaskLike<TValue, TError> {
+  #private;
+  readonly id: string;
+  constructor(runFn: (signal: AbortSignal) => Promise<TValue>, config?: TaskConfig);
+  get status(): TaskStatus;
+  get value(): DeepReadonly<TValue> | undefined;
+  get error(): DeepReadonly<TError> | undefined;
+  run(): Promise<TValue>;
+  abort(): void;
+}
+/**
+ * Runs tasks concurrently, deduplicated by task id.
+ *
+ * If a task with a given id is already in flight, subsequent schedule() calls
+ * for that id are silently ignored until the first completes. Tasks are stored
+ * so abortAll() can cancel any in-flight work (e.g. on engine cleanup).
+ */
+declare class ConcurrentRunner {
+  #private;
+  schedule<TValue = void, TError = unknown>(task: TaskLike<TValue, TError>): Promise<TValue>;
+  /**
+   * Registers a callback to fire when all currently in-flight tasks settle.
+   * If the runner is already idle, the callback is never called. If abortAll()
+   * is called before the batch settles, the callback is superseded and silently
+   * dropped — no stale callbacks, no generation token required by the caller.
+   */
+  whenSettled(callback: () => void): void;
+  abortAll(): void;
+  destroy(): void;
+}
+/**
+ * Runs tasks one at a time in submission order.
+ *
+ * Each schedule() call returns a Promise that resolves or rejects with the
+ * task's result when it is eventually executed. Tasks wait in queue until the
+ * prior task completes.
+ *
+ * Serialization is achieved by chaining each task's run() onto the tail of a
+ * shared promise chain — no explicit queue or drain loop needed.
+ *
+ * abortAll() aborts all pending (not yet started) tasks and the currently
+ * in-flight task. Pending tasks still run briefly but receive an aborted
+ * signal and are expected to exit early.
+ */
+declare class SerialRunner {
+  #private;
+  schedule<TValue = void, TError = unknown>(task: TaskLike<TValue, TError>): Promise<TValue>;
+  /**
+   * A promise that resolves when all currently-scheduled tasks have settled.
+   * Use the reference as a generation token: capture it after scheduling a
+   * batch, then check identity in the resolution callback to detect whether
+   * a subsequent abortAll() + new batch has superseded this one.
+   */
+  get settled(): Promise<void>;
+  /**
+   * Registers a callback to fire when all currently-pending tasks settle.
+   * If the runner is already idle (no pending or running tasks), the callback
+   * is never called. If new tasks are scheduled before the current batch
+   * settles, the callback is superseded and silently dropped — no stale
+   * callbacks, no generation token required by the caller.
+   */
+  whenSettled(callback: () => void): void;
+  /** Aborts and clears queued tasks without touching the in-flight task. */
+  abortPending(): void;
+  abortAll(): void;
+  destroy(): void;
+}
+//#endregion
+export { ConcurrentRunner, DeepReadonly, SerialRunner, Task, TaskConfig, TaskLike, TaskStatus };
+//# sourceMappingURL=task.d.ts.map