@justscale/core 0.1.0

package/dist/process/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @justscale/process - Durable Processes
+ *
+ * Provides primitives for building durable, resumable processes
+ * with serializable state.
+ */
+export type { Signal, ExtractPathParams, ExtractHandlerParams, ParamValue, ModelClass, TypedParams, ProcessConfig, ProcessHandle, ProcessStatus, ProcessDefinition, ProcessContinuation, ProcessState, TimerState, SignalDefinition, LabelHistoryEntry, TimerDuration, SuspendSignalConfig, SuspendTimerConfig, SuspendRaceBranch, SuspendRaceConfig, SuspendConfig, ExecutionResult, ExecutionContext, SwitchProcessState, CompiledSwitchProcess, ProcessExportsMetadata, ExportsData, CompiledSubProcess, SubProcessSpawnConfig, } from './types.js';
+export { DONE, SUSPEND, SUBPROCESS } from './types.js';
+export { createProcess, createSubProcess, SUBPROCESS_DEFINITION } from './createProcess.js';
+export { defineSignals } from './define-signals.js';
+export type { BuiltSignal, SignalBuilder, SignalFactory } from './define-signals.js';
+export { signal, race, delay, scope, stream } from './primitives.js';
+export { DurableCursor, FromCursor, DurableArrayIterator, isDurableIterable, createDurableArrayIterator, } from './primitives.js';
+export { isSignalAllPlaceholder, isSignalSettledPlaceholder, isStreamPlaceholder, } from './primitives.js';
+export type { Duration, DelayPrimitive, DurableCursorType, DurableIterable, DurableQueryIterable, SettledResult, ScopePrimitive, ScopeResult, IdExtractor, ScopeHandler, StreamPrimitive, } from './primitives.js';
+export { isScopePlaceholder } from './primitives.js';
+export { modelNameToIdentityKey, pascalToCamelCase, parseStreamSignal, buildStreamSignal, isWildcardStreamSignal, resolveEntityId, resolveStreamWildcard, } from './stream-utils.js';
+export type { StreamSignalParts, IdentityResolutionOptions, IdentityResolutionResult, } from './stream-utils.js';
+export { __createProcess, setProcessExecutor, getProcessExecutor, withExecutor, registerCompiledProcess } from '../runtime/process/compiled.js';
+export { ProcessExecutor, AbstractProcessExecutor, generateInstanceId, resolvePath, extractIdentity, } from '../runtime/process/executor.js';
+export type { ProcessExecutorContract } from '../runtime/process/executor.js';
+export { registerProcessType, getProcessDescriptor, getProcessRegistry, isProcessable, hasProcessDescriptor, ensureRegistered, findProcessDescriptor, encodeProcessable, decodeProcessable, } from './serialization.js';
+import './builtin-serializers.js';
+export { serializeState, deserializeState } from '../runtime/process/state-serializer.js';
+export { InMemoryProcessStorage, AbstractProcessStorage } from '../runtime/process/storage.js';
+export type { ProcessStorage } from '../runtime/process/storage.js';
+export { AbstractSignalBus, InMemorySignalBus } from '../runtime/process/signal-bus.js';
+export type { SignalBus, SignalMatch, SignalSubscription, RaceSubscription, RaceBranch as SignalRaceBranch, PendingSignal, } from '../runtime/process/signal-bus.js';
+export { InMemoryTimerScheduler } from '../runtime/process/timer-scheduler.js';
+export type { TimerScheduler, ScheduledTimer, TimerFired } from '../runtime/process/timer-scheduler.js';
+export { ScheduledTaskTimerScheduler, TIMER_NAMESPACE, TIMER_TYPE, } from '../runtime/process/scheduled-task-timer.js';
+export type { TimerPayload } from '../runtime/process/scheduled-task-timer.js';
+export { createInMemoryRuntime, createProcessExecutor } from '../runtime/process/factory.js';
+export type { InMemoryRuntime, InMemoryRuntimeOptions, ProcessExecutorOptions } from '../runtime/process/factory.js';
+export { setupTestProcessRuntime, TestClock, createTestClock } from './testing.js';
+export { InMemoryProcessFeature, ProcessExecutorService, ProcessRuntimeService, } from './cluster-plugin.js';
+export type { ProcessRuntimeInstance } from './cluster-plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/process/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/process/index.ts"],"names":[],"mappings":"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"}

package/dist/process/index.js

@@ -0,0 +1,47 @@
+/**
+ * @justscale/process - Durable Processes
+ *
+ * Provides primitives for building durable, resumable processes
+ * with serializable state.
+ */
+// Execution result discriminants
+export { DONE, SUSPEND, SUBPROCESS } from './types.js';
+// Process factory
+export { createProcess, createSubProcess, SUBPROCESS_DEFINITION } from './createProcess.js';
+// Signal group definition (defineSignals with path-based builder API)
+export { defineSignals } from './define-signals.js';
+// Primitives for process control flow
+export { signal, race, delay, scope, stream } from './primitives.js';
+// Durable iterator protocol
+export { DurableCursor, FromCursor, DurableArrayIterator, isDurableIterable, createDurableArrayIterator, } from './primitives.js';
+// Detection helpers for signal types
+export { isSignalAllPlaceholder, isSignalSettledPlaceholder, isStreamPlaceholder, } from './primitives.js';
+// Scope detection helper
+export { isScopePlaceholder } from './primitives.js';
+// Stream-process utilities
+export { modelNameToIdentityKey, pascalToCamelCase, parseStreamSignal, buildStreamSignal, isWildcardStreamSignal, resolveEntityId, resolveStreamWildcard, } from './stream-utils.js';
+// Runtime (for compiled processes)
+export { __createProcess, setProcessExecutor, getProcessExecutor, withExecutor, registerCompiledProcess } from '../runtime/process/compiled.js';
+export { ProcessExecutor, AbstractProcessExecutor, generateInstanceId, resolvePath, extractIdentity, } from '../runtime/process/executor.js';
+// Processable protocol — unified serialization for processes, channels, signals
+/// <reference path="./serialization.global.d.ts" />
+export { registerProcessType, getProcessDescriptor, getProcessRegistry, isProcessable, hasProcessDescriptor, ensureRegistered, findProcessDescriptor, encodeProcessable, decodeProcessable, } from './serialization.js';
+// Built-in Processable types (Date, Map, Set, Reference) — side-effect registration
+import './builtin-serializers.js';
+// State serialization for JSONB round-trips
+export { serializeState, deserializeState } from '../runtime/process/state-serializer.js';
+// Storage abstraction
+export { InMemoryProcessStorage, AbstractProcessStorage } from '../runtime/process/storage.js';
+// Signal bus abstraction
+export { AbstractSignalBus, InMemorySignalBus } from '../runtime/process/signal-bus.js';
+// Timer scheduler abstraction
+export { InMemoryTimerScheduler } from '../runtime/process/timer-scheduler.js';
+// Scheduled task-backed timer scheduler
+export { ScheduledTaskTimerScheduler, TIMER_NAMESPACE, TIMER_TYPE, } from '../runtime/process/scheduled-task-timer.js';
+// Factory for creating runtime configurations
+export { createInMemoryRuntime, createProcessExecutor } from '../runtime/process/factory.js';
+// Testing helper
+export { setupTestProcessRuntime, TestClock, createTestClock } from './testing.js';
+// Process Runtime Service
+export { InMemoryProcessFeature, ProcessExecutorService, ProcessRuntimeService, } from './cluster-plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/process/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/process/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqCH,iCAAiC;AACjC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,kBAAkB;AAClB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE5F,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,sCAAsC;AACtC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAErE,4BAA4B;AAC5B,OAAO,EACL,aAAa,EACb,UAAU,EACV,oBAAoB,EACpB,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAC;AAEzB,qCAAqC;AACrC,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,iBAAiB,CAAC;AAiBzB,yBAAyB;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,2BAA2B;AAC3B,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAO3B,mCAAmC;AACnC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAChJ,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,kBAAkB,EAClB,WAAW,EACX,eAAe,GAChB,MAAM,gCAAgC,CAAC;AAGxC,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,oFAAoF;AACpF,OAAO,0BAA0B,CAAC;AAElC,4CAA4C;AAC5C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAE1F,sBAAsB;AACtB,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAG/F,yBAAyB;AACzB,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAUxF,8BAA8B;AAC9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAG/E,wCAAwC;AACxC,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,UAAU,GACX,MAAM,4CAA4C,CAAC;AAGpD,8CAA8C;AAC9C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAG7F,iBAAiB;AACjB,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEnF,0BAA0B;AAC1B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC"}

package/dist/process/primitives.d.ts

@@ -0,0 +1,393 @@
+/**
+ * @justscale/process - Signal Primitives
+ *
+ * These functions provide the developer API for process control flow.
+ * The actual behavior is implemented through compiler transforms that convert
+ * calls to these functions into opcodes for the process runtime.
+ */
+import type { Signal } from './types.js';
+/**
+ * Symbol for getting the current cursor from a durable iterator.
+ * Called by runtime before suspension to persist position.
+ */
+export declare const DurableCursor: unique symbol;
+/**
+ * Symbol for restoring an iterator from a saved cursor.
+ * Called by runtime on resume to continue iteration.
+ */
+export declare const FromCursor: unique symbol;
+/**
+ * A cursor is the serializable "bookmark" into an iteration.
+ * Must be JSON-serializable (primitives, arrays, plain objects).
+ */
+export type DurableCursorType = string | number | {
+    [key: string]: DurableCursorType;
+} | DurableCursorType[];
+/**
+ * Protocol for durable iteration.
+ * Iterables implementing this can be used in for-of loops with suspension.
+ */
+export interface DurableIterable<T> {
+    /**
+     * Get current cursor position.
+     * Called by runtime before suspension to persist position.
+     */
+    [DurableCursor](): DurableCursorType;
+    /**
+     * Create iterator from a saved cursor.
+     * Called by runtime on resume to continue iteration.
+     */
+    [FromCursor](cursor: DurableCursorType): AsyncIterableIterator<T>;
+}
+/**
+ * Wrapper that makes regular arrays durable.
+ * The cursor is simply the index.
+ */
+export declare class DurableArrayIterator<T> implements DurableIterable<T>, AsyncIterableIterator<T> {
+    private readonly items;
+    private index;
+    constructor(items: readonly T[], initialCursor?: DurableCursorType);
+    [DurableCursor](): DurableCursorType;
+    [FromCursor](cursor: DurableCursorType): AsyncIterableIterator<T>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+    next(): Promise<IteratorResult<T>>;
+}
+/**
+ * Branded interface for durable query iteration.
+ * The compiler detects this type to allow for-of loops over repository queries
+ * in durable processes with proper suspend/resume via keyset pagination.
+ */
+export interface DurableQueryIterable<T, TCursor = Record<string, string | number>> extends AsyncIterable<T>, DurableIterable<T> {
+    readonly __durableIterator: true;
+    readonly __cursorType: TCursor;
+    readonly orderBy: string[];
+}
+/**
+ * Check if a value implements the durable iterator protocol.
+ */
+export declare function isDurableIterable<T>(value: unknown): value is DurableIterable<T>;
+/**
+ * Create a durable iterator from an array.
+ * If a cursor is provided, resumes from that position.
+ */
+export declare function createDurableArrayIterator<T>(items: readonly T[], cursor?: DurableCursorType): DurableArrayIterator<T>;
+/**
+ * Represents a time duration in milliseconds.
+ * Used with the delay primitive for timer signals.
+ */
+export interface Duration {
+    /** Duration in milliseconds */
+    readonly ms: number;
+}
+/**
+ * Result type for signal.settled() - matches Promise.allSettled behavior
+ */
+export type SettledResult<T> = {
+    status: 'fulfilled';
+    value: T;
+} | {
+    status: 'rejected';
+    reason: Error;
+};
+/**
+ * Type helper to extract payloads from signal array
+ */
+type ExtractPayloads<T extends readonly unknown[]> = {
+    [K in keyof T]: T[K] extends Signal<any, infer P, any> ? P : T[K] extends () => Promise<infer R> ? R : unknown;
+};
+/**
+ * Type helper to extract payloads from signal object
+ */
+type ExtractPayloadsObj<T extends Record<string, unknown>> = {
+    [K in keyof T]: T[K] extends Signal<any, infer P, any> ? P : T[K] extends () => Promise<infer R> ? R : unknown;
+};
+/**
+ * signal.all - Wait for all signals in parallel
+ */
+declare function signalAll<T extends readonly unknown[]>(signals: T): Promise<ExtractPayloads<T>>;
+declare function signalAll<T extends Record<string, unknown>>(signals: T): Promise<ExtractPayloadsObj<T>>;
+declare function signalAll<T extends readonly unknown[]>(racer: unknown, signals: T): racer is ExtractPayloads<T>;
+declare function signalAll<T extends Record<string, unknown>>(racer: unknown, signals: T): racer is ExtractPayloadsObj<T>;
+/**
+ * signal.settled - Wait for all signals, collecting results (including failures)
+ */
+declare function signalSettled<T extends readonly unknown[]>(signals: T): Promise<{
+    [K in keyof T]: SettledResult<ExtractPayloads<T>[K]>;
+}>;
+interface SignalFunction {
+    <TIdentity extends readonly unknown[], TPayload, TName extends string>(target: Signal<TIdentity, TPayload, TName>): Promise<TPayload>;
+    <TIdentity extends readonly unknown[], TPayload, TName extends string>(racer: unknown, target: Signal<TIdentity, TPayload, TName>): racer is TPayload;
+    /**
+     * Wait for all signals in parallel.
+     *
+     * @example
+     * ```typescript
+     * // Array form - tuple result
+     * const [a, b] = await signal.all([svc.taskA, svc.taskB])
+     *
+     * // Object form - named result
+     * const { payment, shipping } = await signal.all({
+     *   payment: orders.paid,
+     *   shipping: orders.shipped,
+     * })
+     *
+     * // In race - branch wins when ALL signals fire
+     * const r = race()
+     * switch (true) {
+     *   case signal.all(r, [svc.paid, svc.verified]):
+     *     return 'both confirmed'
+     * }
+     * ```
+     */
+    all: typeof signalAll;
+    /**
+     * Wait for all signals, collecting results including failures.
+     * Similar to Promise.allSettled behavior.
+     *
+     * @example
+     * ```typescript
+     * const results = await signal.settled([svc.taskA, svc.taskB])
+     * // results: [{ status: 'fulfilled', value: T } | { status: 'rejected', reason: Error }, ...]
+     * ```
+     */
+    settled: typeof signalSettled;
+}
+export declare const signal: SignalFunction;
+/**
+ * Create a race context for waiting on multiple signals simultaneously.
+ *
+ * Used with a switch statement to handle whichever signal arrives first.
+ * The compiler transforms this pattern into RACE_START and RACE_SUSPEND opcodes.
+ *
+ * @returns An unknown value that gets narrowed by signal()/delay() in switch cases
+ *
+ * @example
+ * ```typescript
+ * const r = race()
+ * switch (r) {
+ *   case signal(payment.received):
+ *     // r is the payload type: { txId: string }
+ *     return { status: 'paid', txId: r.txId }
+ *
+ *   case signal(payment.failed):
+ *     return { status: 'failed', reason: r.reason }
+ *
+ *   case delay.hours(r, 24):
+ *     return { status: 'timeout' }
+ * }
+ * ```
+ */
+export declare function race(): unknown;
+/**
+ * Delay primitive for creating durable timer signals.
+ *
+ * When awaited inside a process, this suspends the process for the specified
+ * duration. The timer is durable - if the process restarts, it will resume
+ * from the correct time.
+ *
+ * Use the unit methods to specify the duration:
+ * - `delay.seconds(n)` - Wait n seconds
+ * - `delay.minutes(n)` - Wait n minutes
+ * - `delay.hours(n)` - Wait n hours
+ * - `delay.days(n)` - Wait n days
+ *
+ * Supports expressions: `delay.minutes(attempt * 5)`
+ *
+ * In a race switch, pass the race result as first arg.
+ *
+ * @example
+ * ```typescript
+ * // Simple delay
+ * await delay.hours(24)
+ * await delay.minutes(retryCount * 5)  // Expression support
+ *
+ * // In a race - pass r to match the pattern
+ * const r = race()
+ * switch (true) {
+ *   case signal(r, orders.complete):
+ *     console.log(r.orderId)
+ *     break
+ *   case delay.minutes(r, 5):
+ *     // timeout - r is void here
+ *     break
+ * }
+ * ```
+ */
+export interface DelayPrimitive {
+    /** Wait for the specified number of seconds */
+    seconds(n: number): Promise<void>;
+    seconds(racer: unknown, n: number): boolean;
+    /** Wait for the specified number of minutes */
+    minutes(n: number): Promise<void>;
+    minutes(racer: unknown, n: number): boolean;
+    /** Wait for the specified number of hours */
+    hours(n: number): Promise<void>;
+    hours(racer: unknown, n: number): boolean;
+    /** Wait for the specified number of days */
+    days(n: number): Promise<void>;
+    days(racer: unknown, n: number): boolean;
+}
+export declare const delay: DelayPrimitive;
+/**
+ * Result type for scope with handler - collects results from each entity
+ */
+export type ScopeResult<R> = Map<string, R>;
+/**
+ * ID extractor function - extracts entity ID from an entity
+ */
+export type IdExtractor<T> = (entity: T) => string;
+/**
+ * Scope handler function - runs for each entity
+ */
+export type ScopeHandler<T, R> = (entity: T) => Promise<R>;
+/**
+ * Process scoped operations over a collection of entities.
+ *
+ * Scope allows you to run operations per-entity with proper identity routing.
+ * Each entity gets its own execution context with path like `/scope_0/entity-123`.
+ *
+ * **Forms:**
+ *
+ * 1. Signal-first: Wait for a signal per entity
+ * ```typescript
+ * await scope(svc.itemProcessed, orderItems)
+ * ```
+ *
+ * 2. Entities with handler: Run handler per entity
+ * ```typescript
+ * await scope(orderItems, async (item) => {
+ *   await signal(svc.itemProcessed)
+ *   return item.id
+ * })
+ * ```
+ *
+ * 3. Process reference: Spawn subprocess per entity
+ * ```typescript
+ * await scope(ItemProcessor, orderItems)
+ * ```
+ *
+ * Entity identity is automatically derived: `OrderItem` → `orderItemId`
+ *
+ * @example
+ * ```typescript
+ * createProcess({
+ *   path: '/order/:orderId/fulfillment',
+ *   async handler({ svc }, [orderId]) {
+ *     const order = await orders.get(orderId)
+ *
+ *     // Wait for each item to be processed
+ *     await scope(svc.itemProcessed, order.items)
+ *
+ *     return { status: 'all_processed' }
+ *   }
+ * })
+ * ```
+ */
+export interface ScopePrimitive {
+    /**
+     * Wait for a signal per entity.
+     * Signal identity is automatically bound to each entity's ID.
+     */
+    <T, P>(signal: PromiseLike<P>, entities: Iterable<T>): Promise<Map<string, P>>;
+    /**
+     * Wait for a signal per entity with custom ID extractor.
+     */
+    <T, P>(signal: PromiseLike<P>, entities: Iterable<T>, idFn: IdExtractor<T>): Promise<Map<string, P>>;
+    /**
+     * Run a handler per entity.
+     */
+    <T, R>(entities: Iterable<T>, handler: ScopeHandler<T, R>): Promise<Map<string, R>>;
+    /**
+     * Run a handler per entity with custom ID extractor.
+     */
+    <T, R>(entities: Iterable<T>, idFn: IdExtractor<T>, handler: ScopeHandler<T, R>): Promise<Map<string, R>>;
+    /**
+     * Run a handler per entity with explicit parameter alias.
+     */
+    <T, R>(entities: Iterable<T>, alias: string, handler: ScopeHandler<T, R>): Promise<Map<string, R>>;
+}
+export declare const scope: ScopePrimitive;
+/** @internal Check if a value is a scope placeholder */
+export declare function isScopePlaceholder(value: unknown): value is {
+    type: 'signal' | 'handler';
+    entities: unknown;
+    signal?: unknown;
+    handler?: unknown;
+    idFn?: unknown;
+    idFnOrAlias?: unknown;
+};
+/** @internal Check if a value is a signal placeholder */
+export declare function isSignalPlaceholder(value: unknown): value is {
+    signal: unknown;
+};
+/** @internal Check if a value is a race placeholder */
+export declare function isRacePlaceholder(value: unknown): boolean;
+/** @internal Check if a value is a delay placeholder */
+export declare function isDelayPlaceholder(value: unknown): value is {
+    duration: Duration;
+};
+/** @internal Check if a value is a signal.all placeholder */
+export declare function isSignalAllPlaceholder(value: unknown): value is {
+    signals: unknown;
+    isRace: boolean;
+};
+/** @internal Check if a value is a signal.settled placeholder */
+export declare function isSignalSettledPlaceholder(value: unknown): value is {
+    signals: unknown;
+};
+/**
+ * Wait for a stream message inside a process race.
+ *
+ * Streams can be used as suspension points in race patterns, allowing processes
+ * to wake up when a message is published to an entity's stream field.
+ *
+ * **In a race switch (two args):**
+ * Pass the race result as first arg to narrow its type in the case branch.
+ * The stream must be a stream field on an entity (e.g., `order.statusUpdates`).
+ *
+ * The compiler transforms this into appropriate opcodes that subscribe to
+ * stream signals with format: `stream:{tableName}:{entityId}:{fieldName}`
+ *
+ * @example
+ * ```typescript
+ * const Order = defineModel('Order', {
+ *   statusUpdates: field.stream(StatusEvent),
+ * })
+ *
+ * // In a process handler:
+ * const order = await orders.findById(orderId)
+ * const r = race()
+ * switch (true) {
+ *   case stream(r, order.statusUpdates):
+ *     // r is narrowed to { value: StatusEvent }
+ *     console.log('Order updated:', r.value.status)
+ *     break
+ *   case signal(r, payments.timeout):
+ *     console.log('Payment timed out')
+ *     break
+ *   case delay.hours(r, 24):
+ *     console.log('24 hour deadline reached')
+ *     break
+ * }
+ * ```
+ */
+export interface StreamPrimitive {
+    /**
+     * Wait for a stream message in a race pattern.
+     * The stream must be a field on an entity loaded from a repository.
+     *
+     * @param racer - The race context from race()
+     * @param target - The stream field (e.g., entity.messages)
+     * @returns Type guard that narrows racer to { value: T }
+     */
+    <T>(racer: unknown, target: AsyncIterable<T>): racer is {
+        value: T;
+    };
+}
+export declare const stream: StreamPrimitive;
+/** @internal Check if a value is a stream placeholder */
+export declare function isStreamPlaceholder(value: unknown): value is {
+    stream: unknown;
+};
+export {};
+//# sourceMappingURL=primitives.d.ts.map

package/dist/process/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/process/primitives.ts"],"names":[],"mappings":"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"}