@voyantjs/workflows 0.0.0 → 0.6.8

package/src/workflow.ts

@@ -1,46 +1,47 @@
 // Workflow declaration and the `ctx` object.
 // Authoritative contract in docs/sdk-surface.md §2–§3.
 
+import type { Condition } from "./conditions.js"
 import type {
   Duration,
   EnvironmentName,
   MachineType,
-  RetryPolicy,
   RateLimitSpec,
+  RetryPolicy,
   RunStatus,
   RunTrigger,
-} from "./types.js";
-import type { Condition } from "./conditions.js";
+} from "./types.js"
 
 // ---- Workflow ----
 
 export interface WorkflowHandle<TInput = unknown, TOutput = unknown> {
-  readonly id: string;
+  readonly id: string
   /** Phantom; used only for TypeScript inference of `workflows.trigger(...)`. */
-  readonly __input?: TInput;
-  readonly __output?: TOutput;
+  readonly __input?: TInput
+  readonly __output?: TOutput
 }
 
 export interface WorkflowConfig<TInput, TOutput> {
-  id: string;
-  input?: unknown;
-  output?: unknown;
-  description?: string;
-  schedule?: ScheduleDeclaration | ScheduleDeclaration[];
-  concurrency?: ConcurrencyPolicy<TInput>;
-  retry?: RetryPolicy;
-  timeout?: Duration;
-  defaultRuntime?: "edge" | "node";
-  tags?: string[];
-  run: (input: TInput, ctx: WorkflowContext<TInput>) => Promise<TOutput>;
+  id: string
+  input?: unknown
+  output?: unknown
+  description?: string
+  schedule?: ScheduleDeclaration | ScheduleDeclaration[]
+  concurrency?: ConcurrencyPolicy<TInput>
+  retry?: RetryPolicy
+  timeout?: Duration
+  defaultRuntime?: "edge" | "node"
+  tags?: string[]
+  run: (input: TInput, ctx: WorkflowContext<TInput>) => Promise<TOutput>
 }
 
 /**
  * Internal registered form of a workflow. The executor takes this
  * plus a request and drives the body.
  */
-export interface WorkflowDefinition<TInput = unknown, TOutput = unknown> extends WorkflowHandle<TInput, TOutput> {
-  readonly config: WorkflowConfig<TInput, TOutput>;
+export interface WorkflowDefinition<TInput = unknown, TOutput = unknown>
+  extends WorkflowHandle<TInput, TOutput> {
+  readonly config: WorkflowConfig<TInput, TOutput>
 }
 
 export type ScheduleDeclaration = (
@@ -48,18 +49,18 @@ export type ScheduleDeclaration = (
   | { every: Duration }
   | { at: string | Date }
 ) & {
-  timezone?: string;
-  input?: unknown | (() => unknown | Promise<unknown>);
-  enabled?: boolean;
-  overlap?: "skip" | "queue" | "allow";
-  environments?: EnvironmentName[];
-  name?: string;
-};
+  timezone?: string
+  input?: unknown | (() => unknown | Promise<unknown>)
+  enabled?: boolean
+  overlap?: "skip" | "queue" | "allow"
+  environments?: EnvironmentName[]
+  name?: string
+}
 
 export interface ConcurrencyPolicy<TInput> {
-  key?: string | ((input: TInput) => string);
-  limit?: number;
-  strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin";
+  key?: string | ((input: TInput) => string)
+  limit?: number
+  strategy?: "queue" | "cancel-in-progress" | "cancel-newest" | "round-robin"
 }
 
 /**
@@ -69,32 +70,33 @@ export interface ConcurrencyPolicy<TInput> {
  * manifest from a user bundle at load-time). Module-local `const`
  * would create a private map per bundle copy.
  */
-const REGISTRY_KEY = "__voyantWorkflowRegistry" as const;
+const REGISTRY_KEY = "__voyantWorkflowRegistry" as const
 const globalRef = globalThis as unknown as Record<
   typeof REGISTRY_KEY,
   Map<string, WorkflowDefinition> | undefined
->;
+>
 const REGISTRY: Map<string, WorkflowDefinition> =
-  globalRef[REGISTRY_KEY] ??= new Map<string, WorkflowDefinition>();
+  globalRef[REGISTRY_KEY] ?? new Map<string, WorkflowDefinition>()
+globalRef[REGISTRY_KEY] = REGISTRY
 
 /** Declare a workflow. See docs/sdk-surface.md §2.1. */
 export function workflow<TInput = unknown, TOutput = unknown>(
   config: WorkflowConfig<TInput, TOutput>,
 ): WorkflowDefinition<TInput, TOutput> {
   if (REGISTRY.has(config.id)) {
-    throw new Error(`workflow id "${config.id}" is already registered`);
+    throw new Error(`workflow id "${config.id}" is already registered`)
   }
   const def: WorkflowDefinition<TInput, TOutput> = {
     id: config.id,
     config,
-  };
-  REGISTRY.set(config.id, def as WorkflowDefinition);
-  return def;
+  }
+  REGISTRY.set(config.id, def as WorkflowDefinition)
+  return def
 }
 
 /** Internal: look up a registered workflow by id. */
 export function getWorkflow(id: string): WorkflowDefinition | undefined {
-  return REGISTRY.get(id);
+  return REGISTRY.get(id)
 }
 
 /**
@@ -103,7 +105,7 @@ export function getWorkflow(id: string): WorkflowDefinition | undefined {
  * public API — implementation detail of the SDK/CLI pair.
  */
 export function __listRegisteredWorkflows(): WorkflowDefinition[] {
-  return [...REGISTRY.values()];
+  return [...REGISTRY.values()]
 }
 
 /**
@@ -113,171 +115,171 @@ export function __listRegisteredWorkflows(): WorkflowDefinition[] {
  * runs. Not part of the stable public API.
  */
 export function __resetRegistry(): void {
-  REGISTRY.clear();
+  REGISTRY.clear()
 }
 
 // ---- Context ----
 
 export interface RunContext {
-  id: string;
-  number: number;
-  attempt: number;
-  triggeredBy: RunTrigger;
-  tags: readonly string[];
-  startedAt: number;
+  id: string
+  number: number
+  attempt: number
+  triggeredBy: RunTrigger
+  tags: readonly string[]
+  startedAt: number
 }
 
 export interface EnvironmentContext {
-  name: EnvironmentName;
+  name: EnvironmentName
   git?: {
-    commit: string;
-    branch: string;
-    pr?: { number: number; url: string };
-  };
+    commit: string
+    branch: string
+    pr?: { number: number; url: string }
+  }
 }
 
 export interface WorkflowContext<_TInput = unknown> {
-  readonly run: RunContext;
-  readonly workflow: { id: string; version: string };
-  readonly environment: EnvironmentContext;
-  readonly project: { id: string; slug: string };
-  readonly organization: { id: string; slug: string };
-  readonly invocationCount: number;
-  readonly signal: AbortSignal;
-
-  step: StepApi;
-  sleep: (duration: Duration) => Promise<void>;
-  waitForEvent: WaitForEventApi;
-  waitForSignal: WaitForSignalApi;
-  waitForToken: WaitForTokenApi;
-  invoke: InvokeApi;
-  parallel: ParallelApi;
-  stream: StreamApi;
-  group: GroupApi;
-  compensate: () => Promise<never>;
-  metadata: MetadataApi;
-
-  now: () => number;
-  random: () => number;
-  randomUUID: () => string;
-
-  setRetry: (policy: RetryPolicy) => void;
+  readonly run: RunContext
+  readonly workflow: { id: string; version: string }
+  readonly environment: EnvironmentContext
+  readonly project: { id: string; slug: string }
+  readonly organization: { id: string; slug: string }
+  readonly invocationCount: number
+  readonly signal: AbortSignal
+
+  step: StepApi
+  sleep: (duration: Duration) => Promise<void>
+  waitForEvent: WaitForEventApi
+  waitForSignal: WaitForSignalApi
+  waitForToken: WaitForTokenApi
+  invoke: InvokeApi
+  parallel: ParallelApi
+  stream: StreamApi
+  group: GroupApi
+  compensate: () => Promise<never>
+  metadata: MetadataApi
+
+  now: () => number
+  random: () => number
+  randomUUID: () => string
+
+  setRetry: (policy: RetryPolicy) => void
 }
 
 // ---- Step ----
 
 export interface StepApi {
-  <T>(id: string, fn: StepFn<T>): Promise<T>;
-  <T>(id: string, opts: StepOptions<T>, fn: StepFn<T>): Promise<T>;
+  <T>(id: string, fn: StepFn<T>): Promise<T>
+  <T>(id: string, opts: StepOptions<T>, fn: StepFn<T>): Promise<T>
 }
 
-export type StepFn<T> = (stepCtx: StepContext) => Promise<T>;
+export type StepFn<T> = (stepCtx: StepContext) => Promise<T>
 
 export interface StepContext {
-  signal: AbortSignal;
-  attempt: number;
-  log: (level: "info" | "warn" | "error", msg: string, data?: object) => void;
+  signal: AbortSignal
+  attempt: number
+  log: (level: "info" | "warn" | "error", msg: string, data?: object) => void
 }
 
 export interface StepOptions<T = unknown> {
-  runtime?: "edge" | "node";
-  machine?: MachineType;
-  timeout?: Duration;
-  retry?: RetryPolicy | { max: 0 };
-  idempotencyKey?: string;
-  compensate?: (output: T) => Promise<void>;
-  rateLimit?: RateLimitSpec;
-  waitFor?: Condition;
-  cancelIf?: Condition;
-  skipIf?: Condition;
+  runtime?: "edge" | "node"
+  machine?: MachineType
+  timeout?: Duration
+  retry?: RetryPolicy | { max: 0 }
+  idempotencyKey?: string
+  compensate?: (output: T) => Promise<void>
+  rateLimit?: RateLimitSpec
+  waitFor?: Condition
+  cancelIf?: Condition
+  skipIf?: Condition
 }
 
 // ---- Waits ----
 
 export interface Waitable<T> extends PromiseLike<T | null> {
-  [Symbol.asyncIterator](): AsyncIterableIterator<T>;
-  close(): void;
+  [Symbol.asyncIterator](): AsyncIterableIterator<T>
+  close(): void
 }
 
-export interface WaitForEventApi {
-  <T = unknown>(eventType: string, opts?: WaitForEventOptions<T>): Waitable<T>;
-}
+export type WaitForEventApi = <T = unknown>(
+  eventType: string,
+  opts?: WaitForEventOptions<T>,
+) => Waitable<T>
 
 export interface WaitForEventOptions<T> {
-  match?: Partial<T> | ((payload: T) => boolean);
-  timeout?: Duration;
-  lookback?: Duration;
-  bufferSize?: number;
-  onTimeout?: "null" | "throw";
+  match?: Partial<T> | ((payload: T) => boolean)
+  timeout?: Duration
+  lookback?: Duration
+  bufferSize?: number
+  onTimeout?: "null" | "throw"
 }
 
-export interface WaitForSignalApi {
-  <T = unknown>(name: string, opts?: WaitForSignalOptions<T>): Waitable<T>;
-}
+export type WaitForSignalApi = <T = unknown>(
+  name: string,
+  opts?: WaitForSignalOptions<T>,
+) => Waitable<T>
 export interface WaitForSignalOptions<T> extends WaitForEventOptions<T> {}
 
-export interface WaitForTokenApi {
-  <T = unknown>(opts?: WaitForTokenOptions<T>): Promise<TokenWait<T>>;
-}
+export type WaitForTokenApi = <T = unknown>(opts?: WaitForTokenOptions<T>) => Promise<TokenWait<T>>
 export interface WaitForTokenOptions<_T> {
-  tokenId?: string;
-  timeout?: Duration;
-  onTimeout?: "null" | "throw";
-  schema?: unknown;
+  tokenId?: string
+  timeout?: Duration
+  onTimeout?: "null" | "throw"
+  schema?: unknown
 }
 export interface TokenWait<T> {
-  tokenId: string;
-  url: string;
-  wait: () => Promise<T | null>;
+  tokenId: string
+  url: string
+  wait: () => Promise<T | null>
 }
 
 // ---- Invoke / parallel ----
 
-export interface InvokeApi {
-  <TIn, TOut>(
-    workflow: WorkflowHandle<TIn, TOut>,
-    input: TIn,
-    opts?: InvokeOptions,
-  ): Promise<TOut>;
-}
+export type InvokeApi = <TIn, TOut>(
+  workflow: WorkflowHandle<TIn, TOut>,
+  input: TIn,
+  opts?: InvokeOptions,
+) => Promise<TOut>
 
 export interface InvokeOptions {
-  idempotencyKey?: string;
-  tags?: string[];
-  lockToVersion?: string;
-  detach?: boolean;
+  idempotencyKey?: string
+  tags?: string[]
+  lockToVersion?: string
+  /**
+   * Fire-and-forget child run. The child is still triggered and
+   * persisted, but the parent does not wait for its output or error.
+   * The awaited result resolves to `undefined`; callers should not use
+   * detached invokes for control flow.
+   */
+  detach?: boolean
 }
 
-export interface ParallelApi {
-  <T, R>(
-    items: readonly T[],
-    fn: (item: T, index: number) => Promise<R>,
-    opts?: ParallelOptions,
-  ): Promise<R[]>;
-}
+export type ParallelApi = <T, R>(
+  items: readonly T[],
+  fn: (item: T, index: number) => Promise<R>,
+  opts?: ParallelOptions,
+) => Promise<R[]>
 
 export interface ParallelOptions {
-  concurrency?: number;
-  settle?: boolean;
+  concurrency?: number
+  settle?: boolean
 }
 
 // ---- Streams ----
 
 export interface StreamApi {
-  text(streamId: string, source: AsyncIterable<string>): Promise<void>;
-  json<T>(streamId: string, source: AsyncIterable<T>): Promise<void>;
-  bytes(streamId: string, source: AsyncIterable<Uint8Array>): Promise<void>;
-  <T>(streamId: string, fn: () => AsyncGenerator<T>): Promise<void>;
+  text(streamId: string, source: AsyncIterable<string>): Promise<void>
+  json<T>(streamId: string, source: AsyncIterable<T>): Promise<void>
+  bytes(streamId: string, source: AsyncIterable<Uint8Array>): Promise<void>
+  <T>(streamId: string, fn: () => AsyncGenerator<T>): Promise<void>
 }
 
 // ---- Groups (scoped compensation) ----
 
-export interface GroupApi {
-  <T>(name: string, fn: (scope: GroupScope) => Promise<T>): Promise<T>;
-}
+export type GroupApi = <T>(name: string, fn: (scope: GroupScope) => Promise<T>) => Promise<T>
 export interface GroupScope {
-  step: StepApi;
-  compensate: () => Promise<never>;
+  step: StepApi
+  compensate: () => Promise<never>
 }
 
 // ---- Metadata ----
@@ -288,19 +290,19 @@ export type MetadataValue =
   | boolean
   | null
   | MetadataValue[]
-  | { [key: string]: MetadataValue };
+  | { [key: string]: MetadataValue }
 
 export interface MetadataMutatorSubset {
-  set(key: string, value: MetadataValue): void;
-  increment(key: string, by?: number): void;
-  append<T>(key: string, value: T): void;
-  remove(key: string): void;
+  set(key: string, value: MetadataValue): void
+  increment(key: string, by?: number): void
+  append<T>(key: string, value: T): void
+  remove(key: string): void
 }
 
 export interface MetadataApi extends MetadataMutatorSubset {
-  flush(): Promise<void>;
-  parent?: MetadataMutatorSubset;
-  root?: MetadataMutatorSubset;
+  flush(): Promise<void>
+  parent?: MetadataMutatorSubset
+  root?: MetadataMutatorSubset
 }
 
-export type { RunStatus };
+export type { RunStatus }