import { WorkflowError } from "./errors/index.js";
import { CheckpointStore } from "@graphorin/core";

//#region src/timer-driver.d.ts

/** The slice of {@link Workflow} the driver needs (structural). */
interface TickableWorkflow {
  readonly name: string;
  tick(threadId: string, opts?: {
    readonly now?: number;
  }): Promise<{
    readonly fired: boolean;
    readonly nextWakeAt: number | null;
  }>;
}
/** One workflow the driver polls, paired with its checkpoint store. */
interface TimerDriverEntry {
  readonly workflow: TickableWorkflow;
  readonly checkpointStore: CheckpointStore;
}
/**
 * Thrown by {@link createTimerDriver} when an entry's checkpoint store
 * does not implement the optional `listSuspended` - a driver that
 * silently skipped such stores would look healthy while every timer
 * sleeps forever.
 *
 * @stable
 */
declare class TimerDriverStoreUnsupportedError extends WorkflowError {
  readonly workflowName: string;
  constructor(workflowName: string, storeName: string);
}
/** @stable */
interface CreateTimerDriverOptions {
  readonly workflows: ReadonlyArray<TimerDriverEntry>;
  /** Poll interval upper bound (ms). Default 30000. */
  readonly pollIntervalMs?: number;
  /** Max due threads ticked per workflow per sweep. Default 100. */
  readonly batchLimit?: number;
  /** Injectable clock (offline tests). Default `Date.now`. */
  readonly now?: () => number;
  readonly setTimeoutImpl?: (fn: () => void, ms: number) => unknown;
  readonly clearTimeoutImpl?: (handle: unknown) => void;
  /**
   * Per-thread failure sink; the driver survives and moves on. A
   * `checkpoint-version-conflict` never reaches it - in a
   * multi-process deployment two drivers may race the same due thread
   * and the store CAS makes the loser benign by design.
   */
  readonly onError?: (workflowName: string, threadId: string, error: unknown) => void;
}
/** @stable */
interface TimerDriverStatus {
  readonly running: boolean;
  readonly sweeps: number;
  readonly fired: number;
  readonly errors: number;
  readonly lastSweepAt?: number;
  readonly nextWakeAt?: number;
}
/**
 * Handle returned by {@link createTimerDriver}.
 *
 * @stable
 */
interface TimerDriver {
  start(): void;
  stop(): void;
  status(): TimerDriverStatus;
  /** Run one poll pass immediately; resolves with the fired count. */
  sweep(): Promise<number>;
}
/**
 * Build a polling driver over the supplied workflows. Call
 * `start()` to begin polling; the next pass is scheduled at
 * `min(pollIntervalMs, earliest nextWakeAt)` so a short timer does not
 * wait out a long poll interval.
 *
 * @stable
 */
declare function createTimerDriver(options: CreateTimerDriverOptions): TimerDriver;
//#endregion
export { CreateTimerDriverOptions, TickableWorkflow, TimerDriver, TimerDriverEntry, TimerDriverStatus, TimerDriverStoreUnsupportedError, createTimerDriver };
//# sourceMappingURL=timer-driver.d.ts.map