Interface ICheckpointStore

Persistence contract for checkpoint snapshots.

Implementations may back this with in-memory maps (for testing / ephemeral runs), SQLite / Postgres rows, object storage blobs, or any other durable medium.

All methods are async to accommodate I/O-bound backends without interface changes.

interface ICheckpointStore {
    save(checkpoint): Promise<void>;
    get(checkpointId): Promise<null | Checkpoint>;
    load(runId, nodeId?): Promise<null | Checkpoint>;
    latest(runId): Promise<null | Checkpoint>;
    list(graphId, options?): Promise<CheckpointMetadata[]>;
    delete(checkpointId): Promise<void>;
    fork(checkpointId, patchState?): Promise<string>;
}

Implemented by

Methods

save get load latest list delete fork

Methods

save

  • save(checkpoint): Promise<void>

  • Persist a checkpoint snapshot.

    If a checkpoint with the same id already exists it is overwritten.

    The runtime awaits each save and does not retry one that rejects: the run that asked for the checkpoint ends with the store's error, which GraphRuntime.stream() throws, and a resume by the run id continues from the last checkpoint the store saved. When a save inside a parallel batch rejects, the run ends with the error once the batch's other nodes have finished.

    Parameters

    Returns Promise<void>

    Throws

    The store's error when it cannot persist the checkpoint.

get

load

  • load(runId, nodeId?): Promise<null | Checkpoint>

  • Load a checkpoint for the given runId.

    When nodeId is supplied, returns the most recent checkpoint for that specific node within the run. When nodeId is omitted, returns the most recent checkpoint for the run regardless of node (equivalent to latest(runId)). The most recent checkpoint has the latest timestamp and, of checkpoints with the same timestamp, was saved last: the runtime can save several in one millisecond.

    Parameters

    • runId: string

      The graph run identifier.

    • Optional nodeId: string

      Optional node filter.

    Returns Promise<null | Checkpoint>

    The matching checkpoint, or null when none exists.

latest

  • latest(runId): Promise<null | Checkpoint>

  • Return the most recently persisted checkpoint for a run, or null when the run has no checkpoints. Of checkpoints with the same timestamp, the one saved last is the most recent.

    Parameters

    • runId: string

      The graph run identifier.

    Returns Promise<null | Checkpoint>

list

  • list(graphId, options?): Promise<CheckpointMetadata[]>

  • List lightweight metadata descriptors for all checkpoints belonging to a graph.

    Parameters

    • graphId: string

      The compiled graph identifier.

    • Optional options: {
          limit?: number;
          runId?: string;
      }
      • Optional limit?: number

        Maximum number of entries to return (most-recent-first).

      • Optional runId?: string

        Optional filter to a single run within the graph.

    Returns Promise<CheckpointMetadata[]>

    Array of CheckpointMetadata, sorted by timestamp descending.

delete

  • delete(checkpointId): Promise<void>

  • Permanently remove a checkpoint from the store.

    Silently succeeds when checkpointId does not exist.

    Parameters

    • checkpointId: string

      The checkpoint to remove.

    Returns Promise<void>

fork

  • fork(checkpointId, patchState?): Promise<string>

  • Create a new run branching from an existing checkpoint.

    The operation deep-clones the source checkpoint, assigns a fresh runId and checkpoint id, applies any patchState overrides, persists the new checkpoint, and returns the new runId.

    Parameters

    • checkpointId: string

      The checkpoint to fork from.

    • Optional patchState: Partial<GraphState<unknown, unknown, unknown>>

      Optional partial GraphState overrides applied after cloning.

    Returns Promise<string>

    The new runId for the forked run.

    Throws

    When checkpointId does not exist.

Settings

Member Visibility

Theme

On This Page

savegetloadlatestlistdeletefork