@temporalio/workflow/lib/random-streams.d.ts

Temporal.io SDK Workflow sub-package

/**
 * A deterministic PRNG stream scoped to the current Workflow execution.
 *
 * Workflow code already gets a deterministic default stream through `Math.random()`.
 * This interface exposes additional named streams that are derived from the workflow
 * seed without consuming that default stream. Repeated calls to
 * {@link getRandomStream} with the same name refer to the same logical stream state
 * for the current workflow execution, and that state is preserved across activations.
 *
 * The primary use case is workflow plugins and interceptors that need private,
 * replay-stable entropy without perturbing user workflow randomness.
 *
 * @experimental This API may be removed or changed in the future.
 */
export interface WorkflowRandomStream {
    /**
     * Draw the next deterministic pseudo-random number from this stream.
     *
     * This is equivalent to `Math.random()`, but isolated from the workflow's main
     * random stream and from other named streams.
     */
    random(): number;
    /**
     * Generate a deterministic UUIDv4 backed by this stream.
     */
    uuid4(): string;
    /**
     * Fill a byte array deterministically from this stream.
     */
    fill(bytes: Uint8Array): Uint8Array;
    /**
     * Run `fn` with scoped workflow-random helpers such as `Math.random()` and `uuid4()`
     * routed through this stream.
     *
     * This is the scoped override API for workflow random streams. It is intended for
     * bounded plugin/interceptor code that needs existing calls to `Math.random()` or
     * `uuid4()` to use this stream without perturbing the workflow's default random
     * sequence or any other named stream.
     *
     * The override follows async continuations started by `fn`. Workflow interceptor
     * `next(...)` continuations restore the downstream workflow random scope before
     * entering the rest of the interceptor chain or workflow code, so a temporary
     * plugin scope does not leak downstream unless that downstream code explicitly
     * establishes its own scope.
     *
     * Prefer explicit `stream.random()` / `stream.uuid4()` calls when that is practical.
     * Use `stream.with(...)` when a temporary scoped override is the better fit, or
     * when you want to keep the stream instance in module scope and reuse it directly.
     */
    with<T>(fn: () => T): T;
}
/**
 * The default deterministic random stream for the current workflow execution.
 *
 * This exposes the same underlying sequence used by workflow-level `Math.random()`
 * when no named override is active. It can be useful for plugin/interceptor code
 * that wants an explicit handle to the main workflow random stream, including from
 * inside a temporary named scope established by another `WorkflowRandomStream`.
 *
 * @experimental This API may be removed or changed in the future.
 */
export declare const workflowRandom: WorkflowRandomStream;
/**
 * Get a named deterministic random stream for the current workflow execution.
 *
 * Named streams are derived from the workflow seed and a stable stream name,
 * without consuming the workflow's default `Math.random()` stream. Repeated
 * calls with the same `name` within a workflow execution refer to the same
 * logical stream state, including across activations.
 *
 * This is the preferred entry point for workflow plugins and interceptors that
 * need their own deterministic entropy. Use stable package- or module-style
 * names so the stream identity remains replay-safe, then keep the returned
 * `WorkflowRandomStream` around and call its methods directly.
 *
 * @experimental This API may be removed or changed in the future.
 */
export declare function getRandomStream(name: string): WorkflowRandomStream;