@arbitro/client 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -86,6 +86,8 @@ interface SubjectInflightLimit {
 }
 interface ConsumerConfig {
     name?: string;
+    /** Shared consumer group name for round-robin delivery. Defaults to `name`. */
+    group?: string;
     filter?: string;
     fanout?: boolean;
     /** Consumer-side ACK policy. None = fire-and-forget delivery, Explicit = consumer must ACK. */
@@ -220,6 +222,35 @@ declare class ClientMetrics {
     snapshot(): ClientMetricsSnapshot;
 }
 
+interface CreateCronBody {
+    readonly name: string;
+    readonly every: string;
+    readonly tz?: string | undefined;
+    readonly timeout_ms: number;
+    readonly overlap: boolean;
+}
+
+type CronHandler = (ctx: CronContext) => Promise<void>;
+/** Context passed to the cron handler on each fire. */
+interface CronContext {
+    /** Cron job name. */
+    readonly name: string;
+    /** UTC timestamp (ms since epoch) when the broker intended this fire. */
+    readonly fireTime: bigint;
+    /** Monotonic fire counter (1-based). */
+    readonly fireCount: bigint;
+}
+declare class CronState {
+    private readonly handlers;
+    register(name: string, config: CreateCronBody, handler: CronHandler): void;
+    remove(name: string): void;
+    getHandler(name: string): CronHandler | undefined;
+    allConfigs(): ReadonlyArray<{
+        name: string;
+        config: CreateCronBody;
+    }>;
+}
+
 type DeliveryHandler = (frame: Buffer) => void;
 declare class Connection {
     private readonly reconnectAddr?;
@@ -234,6 +265,7 @@ declare class Connection {
     private readonly log;
     private activeSubs;
     private metrics?;
+    private cronState?;
     private constructor();
     private attachSocket;
     static connect(addr: string, timeoutMs?: number, tlsCfg?: TlsConfig, reconnectCfg?: ReconnectConfig, logger?: Logger): Promise<Connection>;
@@ -244,13 +276,17 @@ declare class Connection {
      * entry and `reconnects` on successful reconnections. Unset = no-op.
      */
     setMetrics(m: ClientMetrics): void;
+    /** Attach cron state so the connection can dispatch CronFire frames. */
+    setCronState(s: CronState): void;
     private resolvePending;
     private rejectPending;
     private onFrame;
     private handleBatchDeliver;
+    private dispatchCronFire;
     sendSubscribeV2(consumerId: number, filter: Buffer, handler: DeliveryHandler, onRenew?: (newConsumerId: number) => void): Promise<number>;
     cancelSubscription(consumerId: number): void;
     private resubscribeAll;
+    private replayCrons;
     registerRoute(consumerId: number, handler: DeliveryHandler): void;
     unregisterRoute(consumerId: number): void;
     send(frame: Buffer): void;
@@ -431,6 +467,30 @@ declare class Consumer {
     subscribe<T extends Record<string, unknown>>(codec: Encoding<T>, cb: (msg: LazyMessage<T>) => void, opts?: SubscribeOptions): Promise<Subscription>;
 }
 
+declare class CronBuilder {
+    private readonly conn;
+    private readonly cronState;
+    private readonly cronName;
+    private expr;
+    private timezone;
+    private timeoutMs;
+    private allowOverlap;
+    constructor(conn: Connection, cronState: CronState, cronName: string);
+    every(expression: string): this;
+    tz(timezone: string): this;
+    timeout(ms: number): this;
+    overlap(allow: boolean): this;
+    run(handler: CronHandler): Promise<CronHandle>;
+}
+declare class CronHandle {
+    private readonly conn;
+    private readonly cronState;
+    private readonly cronName;
+    constructor(conn: Connection, cronState: CronState, cronName: string);
+    get name(): string;
+    stop(): Promise<void>;
+}
+
 type MsgCallback = (msg: Message) => void;
 declare class ArbitroClient {
     private conn;
@@ -439,6 +499,7 @@ declare class ArbitroClient {
     private readonly logger;
     private readonly sidCache;
     private readonly _metrics;
+    private readonly _cronState;
     constructor(config: ClientConfig);
     connect(): Promise<this>;
     /**
@@ -494,6 +555,13 @@ declare class ArbitroClient {
     publishBatch(streamName: string, messages: BatchPublishEntry[]): Promise<bigint>;
     /** Request-reply. */
     request(streamName: string, subject: string, data: Buffer, timeoutMs?: number): Promise<Buffer>;
+    /**
+     * Publish a message with a delivery delay. The broker parks the message
+     * in its delayed journal and delivers it to consumers after `delayMs`
+     * milliseconds. Returns a Promise that resolves once the broker confirms
+     * receipt.
+     */
+    publishDelayed(streamName: string, subject: string, data: Buffer, delayMs: number): Promise<void>;
     /** Subscribe with explicit consumer config. */
     subscribe(streamName: string, config: ConsumerConfig, callback?: MsgCallback, opts?: SubscribeOptions): Promise<Subscription>;
     /** Subscribe by consumer name only (consumer must already exist). */
@@ -533,6 +601,8 @@ declare class ArbitroClient {
     /** Pre-resolve stream_id from server (GetStream). Required before sync publish(). */
     resolveStream(name: string): Promise<void>;
     stream(name: string, config?: StreamConfig): Stream;
+    /** Start building a cron job. Call `.every()` then `.run()` to register. */
+    cron(name: string): CronBuilder;
     close(): Promise<void>;
 }
 
@@ -586,6 +656,64 @@ declare class Topic<T extends Record<string, unknown>> {
 
 declare function streamId(name: Buffer | string): number;
 
+declare class WorkflowHandle {
+    private readonly workflowName;
+    private readonly taskStreamName;
+    private readonly dlqStreamName;
+    private readonly sub;
+    private readonly triggerSub;
+    constructor(workflowName: string, taskStreamName: string, dlqStreamName: string, sub: unknown, triggerSub: unknown | undefined);
+    get name(): string;
+    get taskStream(): string;
+    get dlqStream(): string;
+    trigger(client: ArbitroClient, context: Buffer): Promise<number>;
+}
+
+interface StepContext {
+    readonly name: string;
+    readonly instanceId: number;
+    readonly stepIndex: number;
+    readonly attempt: number;
+    readonly context: Buffer;
+}
+interface StepResult {
+    readonly context: Buffer;
+}
+type StepHandler = (ctx: StepContext) => Promise<StepResult>;
+declare class WorkflowBuilder {
+    private readonly client;
+    private readonly workflowName;
+    private triggerSubject;
+    private triggerStreamName;
+    private readonly steps;
+    private ackWaitMs;
+    private maxInflightVal;
+    private maxRetriesVal;
+    private maxContextSizeVal;
+    constructor(client: ArbitroClient, workflowName: string);
+    trigger(subject: string): this;
+    triggerStream(streamName: string): this;
+    step(name: string, handler: StepHandler): this;
+    /** Compensation handler for the most recently added step. */
+    compensate(_stepName: string, handler: StepHandler): this;
+    ackWait(ms: number): this;
+    inflight(n: number): this;
+    maxRetries(n: number): this;
+    maxContextSize(bytes: number): this;
+    start(): Promise<WorkflowHandle>;
+    private subscribeWorker;
+    private subscribeTrigger;
+}
+
+/** Bit flag set on stepIndex to mark compensation tasks. */
+declare const COMPENSATION_BIT = 32768;
+interface DecodedTask {
+    readonly instanceId: number;
+    readonly stepIndex: number;
+    readonly attempt: number;
+    readonly context: Buffer;
+}
+
 /** Wraps a ZodObject schema as an Encoding<T>.
  *
  *  - encode: msgpack (no Zod overhead — bytes out)
@@ -599,4 +727,4 @@ declare function zodCodec<S extends ZodRawShape>(zodSchema: ZodObject<S>): Encod
     readonly fields: string[];
 };
 
-export { AckPolicy, ArbitroClient, ArbitroError, type BatchPublishEntry, type ClientConfig, type ClientMetricsSnapshot, Codec, Consumer, type ConsumerConfig, type ConsumerInfo, type DeleteStreamOpts, DeliverPolicy, type Encoding, ErrorCode, type ErrorCodeValue, type FieldType, type FieldTypeMap, type FlushConfig, type InferSchema, type JournalConfig, JournalType, JsonCodec, type LazyMessage, type LogFn, type Logger, Message, type PublishOpts, type ReconnectConfig, type Schema, Stream, type StreamConfig, type StreamInfo, StringCodec, type SubjectInflightLimit, type SubscribeOptions, Subscription, type TlsConfig, Topic, decodeJson, decodeString, encodeJson, encodeString, makeLazyMessage, schema, streamId, zodCodec };
+export { AckPolicy, ArbitroClient, ArbitroError, type BatchPublishEntry, COMPENSATION_BIT, type ClientConfig, type ClientMetricsSnapshot, Codec, Consumer, type ConsumerConfig, type ConsumerInfo, CronBuilder, type CronContext, CronHandle, type CronHandler, type DecodedTask, type DeleteStreamOpts, DeliverPolicy, type Encoding, ErrorCode, type ErrorCodeValue, type FieldType, type FieldTypeMap, type FlushConfig, type InferSchema, type JournalConfig, JournalType, JsonCodec, type LazyMessage, type LogFn, type Logger, Message, type PublishOpts, type ReconnectConfig, type Schema, type StepContext, type StepHandler, type StepResult, Stream, type StreamConfig, type StreamInfo, StringCodec, type SubjectInflightLimit, type SubscribeOptions, Subscription, type TlsConfig, Topic, WorkflowBuilder, WorkflowHandle, decodeJson, decodeString, encodeJson, encodeString, makeLazyMessage, schema, streamId, zodCodec };