@ayepi/work 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -3,6 +3,14 @@ import { MaybePromise } from "@ayepi/core";
 
 //#region src/internal.d.ts
 
+/**
+ * Override how work/group ids are generated process-wide — e.g. sortable or prefixed ids. Affects
+ * **build-time** work ids (builders are minted outside a system) and any engine ids without their own
+ * `generateId`. Pass nothing to reset to the default UUID generator.
+ */
+declare const setIdGenerator: (fn?: () => string) => void;
+/** Generate an id via the active generator. */
+
 /** The signature of a `logWith`-style context wrapper (`@ayepi/log`'s `logWith`). */
 type LogWith = <R>(add: object, inner: () => R) => R;
 /** The default {@link LogWith}: runs `inner` with no added context. */
@@ -414,18 +422,58 @@ declare function retry<R>(fn: (state: RetryState) => Promise<R>, options?: Retry
 /**
  * A queueable, type-carrying unit of work produced by a {@link WorkBuilder}. Its `id`
  * is assigned at build time (so you can reference it before queueing — e.g. to depend
- * on it). `__out` is a phantom: it never exists at runtime, it only threads the output
- * type through `enqueue`.
+ * on it). It carries **two** phantom types: `S` — what `.result()` resolves to when this
+ * item is awaited alone — and `G` — what it contributes to the **group** when group-awaited
+ * (its own value plus everything it queues, transitively). Phantoms never exist at runtime.
  */
-interface Work<Name extends string = string, O = unknown> {
+interface Work<Name extends string = string, S = unknown, G = unknown> {
   /** Stable id, assigned when the instance is built. */
   readonly id: string;
   /** The work type name (the registry key). */
   readonly type: Name;
   /** The (already type-checked) input payload. */
   readonly input: unknown;
-  /** Phantom output-type carrier — never present at runtime. */
-  readonly __out: O;
+  /** Phantom: the *awaited-alone* result type. */
+  readonly __self: S;
+  /** Phantom: the *group-awaited* contribution type. */
+  readonly __group: G;
+}
+/** Brand for {@link WorkResult} — also makes the result distinguishable from a raw value at runtime. */
+declare const WORK_RESULT: unique symbol;
+/** An item that contributes to a group: a built {@link Work} or a {@link WorkResult}. */
+type GroupItem = Work<string, unknown, unknown> | WorkResult<unknown, unknown>;
+/** The group contribution `G` of one {@link GroupItem}. */
+type GroupOfItem<X> = X extends Work<string, unknown, infer G> ? G : X extends WorkResult<unknown, infer G> ? G : never;
+/** The group contribution of one item or a tuple/array of items. */
+type GroupOf<Is> = Is extends readonly GroupItem[] ? GroupOfItem<Is[number]> : GroupOfItem<Is>;
+/**
+ * What a handler **returns**: an instruction the system carries out, typed by its *awaited-alone*
+ * result `S` and its *group* contribution `G`. Built by {@link WorkContext.result} (a value),
+ * {@link WorkContext.queue} (run sub-works), or {@link WorkContext.void} (nothing). Chain native
+ * dependencies with {@link next}.
+ *
+ * The chain method is **`next`**, not `then` — a `then` member would make this a *thenable*, and the
+ * engine's `Promise.resolve(...)` of the handler's return would try to adopt/await it.
+ */
+interface WorkResult<S, G> {
+  /** Phantom brand (type-only; the runtime object carries a separate symbol). */
+  readonly [WORK_RESULT]: true;
+  /** Phantom: the *awaited-alone* result type. */
+  readonly __self: S;
+  /** Phantom: the *group* contribution type. */
+  readonly __group: G;
+  /**
+   * Native dependency: once the works this result queued satisfy `condition` (default `'all-success'`),
+   * queue `next`. Returns a result whose group widens by `next`'s contribution.
+   */
+  next<const Ns extends GroupItem | readonly GroupItem[]>(next: Ns, condition?: DependencyCondition, options?: WorkInstanceOptions): WorkResult<S, G | GroupOf<Ns>>;
+}
+/** Options for {@link WorkContext.result}. */
+interface ResultOptions<R> {
+  /** Lock the group result to this value — later contributors can't overwrite it. */
+  readonly final?: boolean;
+  /** Accumulate instead of overwrite: fold this work's value into the existing group result. */
+  readonly append?: (existing: R | undefined) => R;
 }
 /** The execution context handed to a {@link WorkHandler}. */
 interface WorkContext {
@@ -435,18 +483,23 @@ interface WorkContext {
   readonly groupId: string;
   /** Delivery attempt (1 = first try; higher after a retry). */
   readonly attempt: number;
-  /** Queue child work **into the same group**; returns the child id(s). */
-  queue(work: Work, options?: WorkInstanceOptions): string;
-  queue(works: readonly Work[], options?: WorkInstanceOptions): string[];
-  /** Set the group's result (last-writer-wins) — what a top-level `await enqueue(...)` resolves to. */
-  setResult(result: unknown): void;
+  /** The id of the work that queued this one (undefined for a top-level `enqueue`). */
+  readonly parent?: string;
+  /** When this work was queued by a fired dependency, the ids it depended on. */
+  readonly dependents?: readonly string[];
+  /** Contribute a **value** to the group (and to this item's own `.result()`). */
+  result<R>(value: R, options?: ResultOptions<R>): WorkResult<R, R>;
+  /** Queue sub-work into the same group (works and/or nested results); this item delegates (`.result()` = void). */
+  queue<const Is extends GroupItem | readonly GroupItem[]>(items: Is, options?: WorkInstanceOptions): WorkResult<void, GroupOf<Is>>;
+  /** Contribute nothing. */
+  void(): WorkResult<void, void>;
   /** Read the current {@link WorkState} of other work items (for dependency-style coordination). */
   states(ids: readonly string[]): Promise<(WorkState | undefined)[]>;
   /** Win a one-time distributed claim for `key` (returns `true` once across the fleet). */
   claim(key: string): Promise<boolean>;
 }
-/** A work handler: maps typed input (+ context) to typed output. */
-type WorkHandler<I, O> = (input: I, ctx: WorkContext) => O | Promise<O>;
+/** A work handler: maps typed input (+ context) to a {@link WorkResult} describing what it produced. */
+type WorkHandler<I, S, G> = (input: I, ctx: WorkContext) => WorkResult<S, G> | Promise<WorkResult<S, G>>;
 /**
  * Per-instance options resolved at enqueue time and **serialized with the instance**.
  * Provided at queue time, as per-type constants, or computed by {@link WorkOptions.options}.
@@ -467,6 +520,13 @@ interface WorkInstanceOptions {
   readonly priority?: number;
   /** Fairness group label — consumed by `balancedDoer`. */
   readonly group?: string;
+  /**
+   * Absolute time (epoch ms) by which the item must have **started and finished**. Past it, the item
+   * is no longer retried — it goes terminal and an `'expired'` event fires. Wins over {@link timeout}.
+   */
+  readonly deadline?: number;
+  /** Relative deadline (ms from enqueue) — `deadline = queueAt + timeout`. See {@link deadline}. */
+  readonly timeout?: number;
   /** Skip the durable queue and run this item directly via the doer (in-process; see {@link WorkOptions.skipQueue}). */
   readonly skipQueue?: boolean;
 }
@@ -536,6 +596,14 @@ interface WorkOptions<I> {
   readonly onFailure?: FailureClassifier;
   /** Derive `logWith` context from this type's input (merged over the global hook). */
   readonly logContext?: (input: I) => object;
+  /** Default relative deadline (ms from enqueue) for this type — see {@link WorkInstanceOptions.timeout}. */
+  readonly timeout?: number;
+  /**
+   * Require every `ctx.queue`/`ctx.result`/`.next` to be **returned** from the handler (so the group
+   * type reflects it) — an un-returned instruction throws. Overrides {@link WorkSystemOptions.strictReturn}.
+   * Set `false` to allow detached `ctx.queue` (the work still runs, but its group type won't include it).
+   */
+  readonly strictReturn?: boolean;
   /**
    * Run this type **without the durable queue** — straight to the doer, in-process.
    * Retries, grouping, priority, events, and results still work; there is no queue,
@@ -544,50 +612,55 @@ interface WorkOptions<I> {
    */
   readonly skipQueue?: boolean;
 }
-/** The full definition behind a {@link WorkBuilder}. */
-interface WorkDefinition<I, O> {
+/** The full definition behind a {@link WorkBuilder}. `S`/`G` are the work's self/group result types. */
+interface WorkDefinition<I, S, G> {
   readonly name: string;
-  readonly handler: WorkHandler<I, O>;
+  readonly handler: WorkHandler<I, S, G>;
   readonly options: WorkOptions<I>;
-  /** Present for batched work types (see {@link defineBatchWork}). */
-  readonly batch?: BatchConfig<I, O>;
+  /** Present for batched work types (see {@link defineBatchWork}); a batch produces a value per item. */
+  readonly batch?: BatchConfig<I, S>;
 }
 /**
  * A callable work builder. Invoke it with the work's input to mint a queueable
  * {@link Work} (with a fresh id); it also exposes its `type` and underlying `def`.
  */
-interface WorkBuilder<Name extends string, I, O> {
+interface WorkBuilder<Name extends string, I, S, G> {
   /** Build a type-checked, queueable instance from this work's input. */
-  (input: I): Work<Name, O>;
+  (input: I): Work<Name, S, G>;
   /** The work type name. */
   readonly type: Name;
   /** The underlying definition (handler + options). */
-  readonly def: WorkDefinition<I, O>;
+  readonly def: WorkDefinition<I, S, G>;
 }
 /** The loose base every {@link WorkBuilder} satisfies regardless of its input type. */
-type AnyWorkBuilder = WorkBuilder<string, never, unknown>;
+type AnyWorkBuilder = WorkBuilder<string, never, unknown, unknown>;
 /**
- * Define a work type. Returns a {@link WorkBuilder} — a function that builds queueable
- * instances — typed by its input `I` and output `O`.
+ * Define a work type. The handler **returns a {@link WorkResult}** — `ctx.result(value)`,
+ * `ctx.queue(...)`, `ctx.void()`, or a `.next(...)` chain — and its `S`/`G` types are inferred
+ * from that return: `S` is what `.result()` resolves to alone, `G` what it contributes to the group.
  */
-declare function defineWork<Name extends string, I, O>(name: Name, handler: WorkHandler<I, O>, opts?: WorkOptions<I>): WorkBuilder<Name, I, O>;
+declare function defineWork<Name extends string, I, S, G>(name: Name, handler: WorkHandler<I, S, G>, opts?: WorkOptions<I>): WorkBuilder<Name, I, S, NonVoidUnion<G>>;
 /**
- * Define a **batched** work type. Items still enqueue, retry, prioritize, and join
- * groups individually, but execute together via {@link BatchConfig.run} once `size`
- * accumulate or `maxWait` ms elapse — so each `.result()` resolves to its aligned
- * output. The per-type {@link WorkOptions.doer} governs how many *batches* run at once.
+ * Define a **batched** work type. Items still enqueue, retry, prioritize, and join groups
+ * individually, but execute together via {@link BatchConfig.run} once `size` accumulate or `maxWait`
+ * ms elapse — so each `.result()` resolves to its aligned output `O` (which is also its group
+ * contribution). The per-type {@link WorkOptions.doer} governs how many *batches* run at once.
  */
-declare function defineBatchWork<Name extends string, I, O>(name: Name, config: BatchConfig<I, O> & WorkOptions<I>): WorkBuilder<Name, I, O>;
+declare function defineBatchWork<Name extends string, I, O>(name: Name, config: BatchConfig<I, O> & WorkOptions<I>): WorkBuilder<Name, I, O, NonVoidUnion<O>>;
 /** The input type a builder accepts. */
 type InputOf<B> = B extends ((input: infer I) => unknown) ? I : never;
-/** The output type a builder's instances carry. */
-type OutputOf<B> = B extends ((...args: never[]) => Work<string, infer O>) ? O : never;
+/** The *awaited-alone* result type a builder's instances carry. */
+type SelfOf<B> = B extends ((...args: never[]) => Work<string, infer S, unknown>) ? S : never;
+/** The *group* contribution type a builder's instances carry. */
+type GroupOfBuilder<B> = B extends ((...args: never[]) => Work<string, unknown, infer G>) ? G : never;
 /** The name of a builder. */
 type NameOf<B> = B extends {
   readonly type: infer N extends string;
 } ? N : never;
-/** The output type carried by a {@link Work}. */
-type OutputOfWork<W> = W extends Work<string, infer O> ? O : unknown;
+/** The *awaited-alone* result type carried by a {@link Work}. */
+type SelfOfWork<W> = W extends Work<string, infer S, unknown> ? S : unknown;
+/** The *group* contribution type carried by a {@link Work}. */
+type GroupOfWork<W> = W extends Work<string, unknown, infer G> ? G : unknown;
 /** Drop `void`/`undefined` from a union (work that returns "nothing"). */
 type NonVoidUnion<U> = Exclude<U, void | undefined>;
 /** The union of every registered work name. */
@@ -598,16 +671,13 @@ type BuilderForName<Defs extends readonly AnyWorkBuilder[], K extends string> =
 }>;
 /** The input type of the registry's work named `K`. */
 type InputForName<Defs extends readonly AnyWorkBuilder[], K extends string> = InputOf<BuilderForName<Defs, K>>;
-/** The output type of the registry's work named `K`. */
-type OutputForName<Defs extends readonly AnyWorkBuilder[], K extends string> = OutputOf<BuilderForName<Defs, K>>;
-/**
- * The group's final result type: the union of every registered work's non-void
- * output. The value a top-level `await enqueue(...)` resolves to.
- */
-type GroupResult<Defs extends readonly AnyWorkBuilder[]> = NonVoidUnion<OutputOf<Defs[number]>>;
+/** The *awaited-alone* result type of the registry's work named `K`. */
+type SelfForName<Defs extends readonly AnyWorkBuilder[], K extends string> = SelfOf<BuilderForName<Defs, K>>;
+/** The *group* contribution type of the registry's work named `K`. */
+type GroupForName<Defs extends readonly AnyWorkBuilder[], K extends string> = GroupOfBuilder<BuilderForName<Defs, K>>;
 /**
- * The thenable returned by `enqueue`. **Awaiting it resolves to the group result**
- * ({@link GroupResult}); use {@link result} for this item's own output and
+ * The thenable returned by `enqueue`. **Awaiting it resolves to the group result** (the
+ * root work's `Group` contribution); use {@link result} for this item's own output and
  * {@link group} for the explicit group form.
  */
 interface WorkHandle<Self, Group> extends PromiseLike<Group> {
@@ -669,6 +739,8 @@ type WorkEvent = {
   readonly id: string;
   readonly type: string;
   readonly groupId: string;
+  readonly parent?: string;
+  readonly dependents?: readonly string[];
   readonly at: number;
 } | {
   readonly kind: 'started';
@@ -676,6 +748,8 @@ type WorkEvent = {
   readonly type: string;
   readonly groupId: string;
   readonly attempt: number;
+  readonly parent?: string;
+  readonly dependents?: readonly string[];
   readonly at: number;
 } | {
   readonly kind: 'deferred';
@@ -691,6 +765,8 @@ type WorkEvent = {
   readonly groupId: string;
   readonly attempt: number;
   readonly result: unknown;
+  readonly parent?: string;
+  readonly dependents?: readonly string[];
   readonly at: number;
 } | {
   readonly kind: 'failed';
@@ -700,6 +776,17 @@ type WorkEvent = {
   readonly attempt: number;
   readonly error: string;
   readonly willRetry: boolean;
+  readonly parent?: string;
+  readonly dependents?: readonly string[];
+  readonly at: number;
+} | {
+  readonly kind: 'expired';
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  readonly deadline: number;
+  readonly parent?: string;
+  readonly dependents?: readonly string[];
   readonly at: number;
 } | {
   readonly kind: 'group-done';
@@ -844,6 +931,17 @@ interface WorkSystemOptions {
    * Exposed back as {@link WorkSystem.metrics}.
    */
   readonly metrics?: Metrics;
+  /**
+   * Require a handler to **return** every `ctx.queue`/`ctx.result`/`.next` it creates (so the work's
+   * group type reflects it); an un-returned instruction throws (default `true`). Per-type
+   * {@link WorkOptions.strictReturn} overrides. Turn off if you don't care about precise group typing.
+   */
+  readonly strictReturn?: boolean;
+  /**
+   * Generate the ids the **engine** mints (group ids, name-form item ids, dependency keys, re-pushes).
+   * Defaults to the process generator (see `setIdGenerator`, which also governs build-time work ids).
+   */
+  readonly generateId?: () => string;
   /** Start the worker loop immediately (default true). */
   readonly autoStart?: boolean;
   /** Clock injection for tests (default `Date.now`). */
@@ -853,10 +951,10 @@ interface WorkSystemOptions {
 }
 /** The work system returned by `createWork`. */
 interface WorkSystem<Defs extends readonly AnyWorkBuilder[]> {
-  /** Enqueue a built instance; await the handle for the group result, `.result()` for its own. */
-  enqueue<W extends Work>(work: W, options?: WorkInstanceOptions): WorkHandle<OutputOfWork<W>, GroupResult<Defs>>;
+  /** Enqueue a built instance; await the handle for the **group** result, `.result()` for its own. */
+  enqueue<W extends Work>(work: W, options?: WorkInstanceOptions): WorkHandle<SelfOfWork<W>, GroupOfWork<W>>;
   /** Enqueue by registered name with a type-checked input. */
-  enqueue<K extends RegistryNames<Defs>>(name: K, input: InputForName<Defs, K>, options?: WorkInstanceOptions): WorkHandle<OutputForName<Defs, K>, GroupResult<Defs>>;
+  enqueue<K extends RegistryNames<Defs>>(name: K, input: InputForName<Defs, K>, options?: WorkInstanceOptions): WorkHandle<SelfForName<Defs, K>, GroupForName<Defs, K>>;
   /** Register a recurring schedule; returns a cancel function. */
   schedule(config: ScheduleConfig): () => void;
   /** Start the worker + scheduler loops (idempotent). */
@@ -939,6 +1037,7 @@ declare const WORK_METRICS: {
   readonly retried: "work.retried";
   readonly deferred: "work.deferred";
   readonly rescheduled: "work.rescheduled";
+  readonly expired: "work.expired";
   readonly active: "work.active";
   readonly pending: "work.pending";
   readonly running: "work.running";
@@ -1113,7 +1212,7 @@ declare function conditionMet(condition: DependencyCondition, states: readonly (
  * Build a dependency: when the works it waits `on` satisfy `config`, it queues its
  * `queue` dependents (once). Enqueue it like any work.
  */
-declare function dependency(opts: DependencyOptions): Work<typeof DEPENDENCY_TYPE, void>;
+declare function dependency(opts: DependencyOptions): Work<typeof DEPENDENCY_TYPE, void, void>;
 /**
  * The non-blocking handler for {@link DEPENDENCY_TYPE}: check once, then fire or
  * re-queue. Registered automatically by every work system. Remembers terminal statuses
@@ -1148,12 +1247,14 @@ declare function nextAfter(expr: string, fromMs: number): number | undefined;
 declare const work: WorkSystem<readonly AnyWorkBuilder[]>;
 /** Enqueue on the default system (instance form). */
 declare const enqueue: {
-  <W extends Work>(work: W, options?: WorkInstanceOptions): WorkHandle<OutputOfWork<W>, unknown>;
+  <W extends Work>(work: W, options?: WorkInstanceOptions): WorkHandle<SelfOfWork<W>, GroupOfWork<W>>;
   <K extends string>(name: K, input: InputOf<Extract<AnyWorkBuilder, {
     readonly type: K;
-  }>>, options?: WorkInstanceOptions): WorkHandle<OutputOf<Extract<AnyWorkBuilder, {
+  }>>, options?: WorkInstanceOptions): WorkHandle<SelfOf<Extract<AnyWorkBuilder, {
+    readonly type: K;
+  }>>, GroupOfBuilder<Extract<AnyWorkBuilder, {
     readonly type: K;
-  }>>, unknown>;
+  }>>>;
 };
 /** Register a recurring schedule on the default system. */
 declare const schedule: (config: ScheduleConfig) => () => void;
@@ -1164,4 +1265,4 @@ declare const stop: () => Promise<void>;
 /** Snapshot the default system's known work states. */
 declare const list: () => Promise<WorkState[]>;
 //#endregion
-export { type ActiveWork, type AdaptiveDelay, type AdaptiveDelayOptions, type AnyWorkBuilder, type Backend, type BackpressureContext, type BatchConfig, type BoundedDoerOptions, type BuilderForName, type Counter, DEFAULT_BUCKETS, DEFAULT_RETRY_OPTIONS, DEPENDENCY_TYPE, type DeadLettered, type DependencyCondition, type DependencyOptions, type Doer, type DoerTaskOptions, type FailureClassifier, type FailureDecision, type Gauge, type GroupResult, type InputForName, type InputOf, type JsonCodec, type Labels, type MemoryBackendOptions, type MemoryOptions, type MemoryQueue, type MemoryQueueOptions, type MemoryQueuePersistence, type Metrics, type MetricsOptions, type NameOf, type NonVoidUnion, type OutputForName, type OutputOf, type OutputOfWork, type PubSub, type PulledWork, type PushOptions, type Queue, type QueueFsLike, type RegistryNames, RetryAbort, type RetryOptions, type RetryState, type ScheduleConfig, type StatBucket, type StatKind, type StatMeta, type StatSummary, type StatValue, type Store, type Summary, type UnhandledWorkGroupInfo, type UnlimitedDoerOptions, WORK_METRICS, type Work, type WorkAcceptInfo, type WorkBuilder, type WorkContext, type WorkDefinition, WorkDelayError, type WorkDelaySpec, type WorkEvent, type WorkFailureInfo, type WorkHandle, type WorkHandler, type WorkInstanceOptions, type WorkOptions, type WorkState, type WorkStatus, type WorkSystem, type WorkSystemOptions, adaptiveDelay, ageDoer, backoff, balancedDoer, conditionMet, createMetrics, createWork, defaultCodec, defineBatchWork, defineWork, dependency, enqueue, formatPrometheus, getDefaultRetryOptions, list, memoryBackend, memoryPubSub, memoryQueue, memoryStore, nextAfter, parseCron, priorityDoer, retry, schedule, setDefaultRetryOptions, start, stop, unlimitedDoer, work };
+export { type ActiveWork, type AdaptiveDelay, type AdaptiveDelayOptions, type AnyWorkBuilder, type Backend, type BackpressureContext, type BatchConfig, type BoundedDoerOptions, type BuilderForName, type Counter, DEFAULT_BUCKETS, DEFAULT_RETRY_OPTIONS, DEPENDENCY_TYPE, type DeadLettered, type DependencyCondition, type DependencyOptions, type Doer, type DoerTaskOptions, type FailureClassifier, type FailureDecision, type Gauge, type GroupForName, type GroupItem, type GroupOf, type GroupOfBuilder, type GroupOfItem, type GroupOfWork, type InputForName, type InputOf, type JsonCodec, type Labels, type MemoryBackendOptions, type MemoryOptions, type MemoryQueue, type MemoryQueueOptions, type MemoryQueuePersistence, type Metrics, type MetricsOptions, type NameOf, type NonVoidUnion, type PubSub, type PulledWork, type PushOptions, type Queue, type QueueFsLike, type RegistryNames, type ResultOptions, RetryAbort, type RetryOptions, type RetryState, type ScheduleConfig, type SelfForName, type SelfOf, type SelfOfWork, type StatBucket, type StatKind, type StatMeta, type StatSummary, type StatValue, type Store, type Summary, type UnhandledWorkGroupInfo, type UnlimitedDoerOptions, WORK_METRICS, type Work, type WorkAcceptInfo, type WorkBuilder, type WorkContext, type WorkDefinition, WorkDelayError, type WorkDelaySpec, type WorkEvent, type WorkFailureInfo, type WorkHandle, type WorkHandler, type WorkInstanceOptions, type WorkOptions, type WorkResult, type WorkState, type WorkStatus, type WorkSystem, type WorkSystemOptions, adaptiveDelay, ageDoer, backoff, balancedDoer, conditionMet, createMetrics, createWork, defaultCodec, defineBatchWork, defineWork, dependency, enqueue, formatPrometheus, getDefaultRetryOptions, list, memoryBackend, memoryPubSub, memoryQueue, memoryStore, nextAfter, parseCron, priorityDoer, retry, schedule, setDefaultRetryOptions, setIdGenerator, start, stop, unlimitedDoer, work };