@langchain/langgraph-checkpoint 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2024 LangChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @langchain/langgraph-checkpoint
+
+This library defines the base interface for [LangGraph.js](https://github.com/langchain-ai/langgraphjs) checkpointers. Checkpointers provide persistence layer for LangGraph. They allow you to interact with and manage the graph's state. When you use a graph with a checkpointer, the checkpointer saves a _checkpoint_ of the graph state at every superstep, enabling several powerful capabilities like human-in-the-loop, "memory" between interactions and more.
+
+## Key concepts
+
+### Checkpoint
+
+Checkpoint is a snapshot of the graph state at a given point in time. Checkpoint tuple refers to an object containing checkpoint and the associated config, metadata and pending writes.
+
+### Thread
+
+Threads enable the checkpointing of multiple different runs, making them essential for multi-tenant chat applications and other scenarios where maintaining separate states is necessary. A thread is a unique ID assigned to a series of checkpoints saved by a checkpointer. When using a checkpointer, you must specify a `thread_id` and optionally `checkpoint_id` when running the graph.
+
+- `thread_id` is simply the ID of a thread. This is always required
+- `checkpoint_id` can optionally be passed. This identifier refers to a specific checkpoint within a thread. This can be used to kick of a run of a graph from some point halfway through a thread.
+
+You must pass these when invoking the graph as part of the configurable part of the config, e.g.
+
+```ts
+{ configurable: { thread_id: "1" } }  // valid config
+{ configurable: { thread_id: "1", checkpoint_id: "0c62ca34-ac19-445d-bbb0-5b4984975b2a" } }  // also valid config
+```
+
+### Serde
+
+`@langchain/langgraph-checkpoint` also defines protocol for serialization/deserialization (serde) and provides an default implementation that handles a range of types.
+
+### Pending writes
+
+When a graph node fails mid-execution at a given superstep, LangGraph stores pending checkpoint writes from any other nodes that completed successfully at that superstep, so that whenever we resume graph execution from that superstep we don't re-run the successful nodes.
+
+## Interface
+
+Each checkpointer should conform to `BaseCheckpointSaver` interface and must implement the following methods:
+
+- `.put` - Store a checkpoint with its configuration and metadata.
+- `.putWrites` - Store intermediate writes linked to a checkpoint (i.e. pending writes).
+- `.getTuple` - Fetch a checkpoint tuple using for a given configuration (`thread_id` and `thread_ts`).
+- `.list` - List checkpoints that match a given configuration and filter criteria.
+
+## Usage
+
+```ts
+import { MemorySaver } from "@langchain/langgraph-checkpoint";
+
+const writeConfig = {
+  configurable: {
+    thread_id: "1",
+    checkpoint_ns: ""
+  }
+};
+const readConfig = {
+  configurable: {
+    thread_id: "1"
+  }
+};
+
+const checkpointer = new MemorySaver();
+const checkpoint = {
+  v: 1,
+  ts: "2024-07-31T20:14:19.804150+00:00",
+  id: "1ef4f797-8335-6428-8001-8a1503f9b875",
+  channel_values: {
+    my_key: "meow",
+    node: "node"
+  },
+  channel_versions: {
+    __start__: 2,
+    my_key: 3,
+    start:node: 3,
+    node: 3
+  },
+  versions_seen: {
+    __input__: {},
+    __start__: {
+      __start__: 1
+    },
+    node: {
+      start:node: 2
+    }
+  },
+  pending_sends: [],
+  current_tasks: {}
+}
+
+// store checkpoint
+await checkpointer.put(writeConfig, checkpoint, {}, {})
+
+// load checkpoint
+await checkpointer.get(readConfig)
+
+// list checkpoints
+for await (const checkpoint of checkpointer.list(readConfig)) {
+  console.log(checkpoint);
+}
+```

package/dist/base.cjs

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseCheckpointSaver = exports.copyCheckpoint = exports.emptyCheckpoint = exports.deepCopy = void 0;
+const base_js_1 = require("./serde/base.cjs");
+const id_js_1 = require("./id.cjs");
+function deepCopy(obj) {
+    if (typeof obj !== "object" || obj === null) {
+        return obj;
+    }
+    const newObj = Array.isArray(obj) ? [] : {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            newObj[key] = deepCopy(obj[key]);
+        }
+    }
+    return newObj;
+}
+exports.deepCopy = deepCopy;
+function emptyCheckpoint() {
+    return {
+        v: 1,
+        id: (0, id_js_1.uuid6)(-2),
+        ts: new Date().toISOString(),
+        channel_values: {},
+        channel_versions: {},
+        versions_seen: {},
+        pending_sends: [],
+    };
+}
+exports.emptyCheckpoint = emptyCheckpoint;
+function copyCheckpoint(checkpoint) {
+    return {
+        v: checkpoint.v,
+        id: checkpoint.id,
+        ts: checkpoint.ts,
+        channel_values: { ...checkpoint.channel_values },
+        channel_versions: { ...checkpoint.channel_versions },
+        versions_seen: deepCopy(checkpoint.versions_seen),
+        pending_sends: [...checkpoint.pending_sends],
+    };
+}
+exports.copyCheckpoint = copyCheckpoint;
+class BaseCheckpointSaver {
+    constructor(serde) {
+        Object.defineProperty(this, "serde", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: base_js_1.DefaultSerializer
+        });
+        this.serde = serde || this.serde;
+    }
+    async get(config) {
+        const value = await this.getTuple(config);
+        return value ? value.checkpoint : undefined;
+    }
+    /**
+     * Generate the next version ID for a channel.
+     *
+     * Default is to use integer versions, incrementing by 1. If you override, you can use str/int/float versions,
+     * as long as they are monotonically increasing.
+     */
+    getNextVersion(current, _channel) {
+        return current !== undefined ? current + 1 : 1;
+    }
+}
+exports.BaseCheckpointSaver = BaseCheckpointSaver;

package/dist/base.d.ts

@@ -0,0 +1,75 @@
+import type { RunnableConfig } from "@langchain/core/runnables";
+import { SerializerProtocol } from "./serde/base.js";
+import type { PendingWrite, CheckpointPendingWrite, CheckpointMetadata } from "./types.js";
+import type { ChannelProtocol, SendProtocol } from "./serde/types.js";
+export type ChannelVersions = Record<string, string | number>;
+export interface Checkpoint<N extends string = string, C extends string = string> {
+    /**
+     * Version number
+     */
+    v: number;
+    /**
+     * Checkpoint ID {uuid6}
+     */
+    id: string;
+    /**
+     * Timestamp {new Date().toISOString()}
+     */
+    ts: string;
+    /**
+     * @default {}
+     */
+    channel_values: Record<C, unknown>;
+    /**
+     * @default {}
+     */
+    channel_versions: Record<C, number>;
+    /**
+     * @default {}
+     */
+    versions_seen: Record<N, Record<C, number>>;
+    /**
+     * List of packets sent to nodes but not yet processed.
+     * Cleared by the next checkpoint.
+     */
+    pending_sends: SendProtocol[];
+}
+export interface ReadonlyCheckpoint extends Readonly<Checkpoint> {
+    readonly channel_values: Readonly<Record<string, unknown>>;
+    readonly channel_versions: Readonly<Record<string, number>>;
+    readonly versions_seen: Readonly<Record<string, Readonly<Record<string, number>>>>;
+}
+export declare function deepCopy<T>(obj: T): T;
+export declare function emptyCheckpoint(): Checkpoint;
+export declare function copyCheckpoint(checkpoint: ReadonlyCheckpoint): Checkpoint;
+export interface CheckpointTuple {
+    config: RunnableConfig;
+    checkpoint: Checkpoint;
+    metadata?: CheckpointMetadata;
+    parentConfig?: RunnableConfig;
+    pendingWrites?: CheckpointPendingWrite[];
+}
+export type CheckpointListOptions = {
+    limit?: number;
+    before?: RunnableConfig;
+    filter?: Record<string, any>;
+};
+export declare abstract class BaseCheckpointSaver<V = number> {
+    serde: SerializerProtocol<unknown>;
+    constructor(serde?: SerializerProtocol<unknown>);
+    get(config: RunnableConfig): Promise<Checkpoint | undefined>;
+    abstract getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    abstract list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    abstract put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions: ChannelVersions): Promise<RunnableConfig>;
+    /**
+     * Store intermediate writes linked to a checkpoint.
+     */
+    abstract putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    /**
+     * Generate the next version ID for a channel.
+     *
+     * Default is to use integer versions, incrementing by 1. If you override, you can use str/int/float versions,
+     * as long as they are monotonically increasing.
+     */
+    getNextVersion(current: V | undefined, _channel: ChannelProtocol): number;
+}

package/dist/base.js

@@ -0,0 +1,60 @@
+import { DefaultSerializer } from "./serde/base.js";
+import { uuid6 } from "./id.js";
+export function deepCopy(obj) {
+    if (typeof obj !== "object" || obj === null) {
+        return obj;
+    }
+    const newObj = Array.isArray(obj) ? [] : {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            newObj[key] = deepCopy(obj[key]);
+        }
+    }
+    return newObj;
+}
+export function emptyCheckpoint() {
+    return {
+        v: 1,
+        id: uuid6(-2),
+        ts: new Date().toISOString(),
+        channel_values: {},
+        channel_versions: {},
+        versions_seen: {},
+        pending_sends: [],
+    };
+}
+export function copyCheckpoint(checkpoint) {
+    return {
+        v: checkpoint.v,
+        id: checkpoint.id,
+        ts: checkpoint.ts,
+        channel_values: { ...checkpoint.channel_values },
+        channel_versions: { ...checkpoint.channel_versions },
+        versions_seen: deepCopy(checkpoint.versions_seen),
+        pending_sends: [...checkpoint.pending_sends],
+    };
+}
+export class BaseCheckpointSaver {
+    constructor(serde) {
+        Object.defineProperty(this, "serde", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: DefaultSerializer
+        });
+        this.serde = serde || this.serde;
+    }
+    async get(config) {
+        const value = await this.getTuple(config);
+        return value ? value.checkpoint : undefined;
+    }
+    /**
+     * Generate the next version ID for a channel.
+     *
+     * Default is to use integer versions, incrementing by 1. If you override, you can use str/int/float versions,
+     * as long as they are monotonically increasing.
+     */
+    getNextVersion(current, _channel) {
+        return current !== undefined ? current + 1 : 1;
+    }
+}

package/dist/id.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuid5 = exports.uuid6 = void 0;
+const uuid_1 = require("uuid");
+function uuid6(clockseq) {
+    return (0, uuid_1.v6)({ clockseq });
+}
+exports.uuid6 = uuid6;
+// Skip UUID validation check, since UUID6s
+// generated with negative clockseq are not
+// technically compliant, but still work.
+// See: https://github.com/uuidjs/uuid/issues/511
+function uuid5(name, namespace) {
+    const namespaceBytes = namespace
+        .replace(/-/g, "")
+        .match(/.{2}/g)
+        .map((byte) => parseInt(byte, 16));
+    return (0, uuid_1.v5)(name, new Uint8Array(namespaceBytes));
+}
+exports.uuid5 = uuid5;

package/dist/id.d.ts

@@ -0,0 +1,2 @@
+export declare function uuid6(clockseq: number): string;
+export declare function uuid5(name: string, namespace: string): string;

package/dist/id.js

@@ -0,0 +1,15 @@
+import { v5, v6 } from "uuid";
+export function uuid6(clockseq) {
+    return v6({ clockseq });
+}
+// Skip UUID validation check, since UUID6s
+// generated with negative clockseq are not
+// technically compliant, but still work.
+// See: https://github.com/uuidjs/uuid/issues/511
+export function uuid5(name, namespace) {
+    const namespaceBytes = namespace
+        .replace(/-/g, "")
+        .match(/.{2}/g)
+        .map((byte) => parseInt(byte, 16));
+    return v5(name, new Uint8Array(namespaceBytes));
+}

package/dist/index.cjs

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemorySaver = void 0;
+var memory_js_1 = require("./memory.cjs");
+Object.defineProperty(exports, "MemorySaver", { enumerable: true, get: function () { return memory_js_1.MemorySaver; } });
+__exportStar(require("./base.cjs"), exports);
+__exportStar(require("./id.cjs"), exports);
+__exportStar(require("./types.cjs"), exports);
+__exportStar(require("./serde/base.cjs"), exports);
+__exportStar(require("./serde/types.cjs"), exports);

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { MemorySaver } from "./memory.js";
+export * from "./base.js";
+export * from "./id.js";
+export * from "./types.js";
+export * from "./serde/base.js";
+export * from "./serde/types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { MemorySaver } from "./memory.js";
+export * from "./base.js";
+export * from "./id.js";
+export * from "./types.js";
+export * from "./serde/base.js";
+export * from "./serde/types.js";

package/dist/memory.cjs

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemorySaver = void 0;
+const base_js_1 = require("./base.cjs");
+function _generateKey(threadId, checkpointNamespace, checkpointId) {
+    return JSON.stringify([threadId, checkpointNamespace, checkpointId]);
+}
+class MemorySaver extends base_js_1.BaseCheckpointSaver {
+    constructor(serde) {
+        super(serde);
+        // thread ID ->  checkpoint namespace -> checkpoint ID -> checkpoint mapping
+        Object.defineProperty(this, "storage", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "writes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+    }
+    async getTuple(config) {
+        const thread_id = config.configurable?.thread_id;
+        const checkpoint_ns = config.configurable?.checkpoint_ns ?? "";
+        let checkpoint_id = config.configurable?.checkpoint_id;
+        if (checkpoint_id) {
+            const saved = this.storage[thread_id]?.[checkpoint_ns]?.[checkpoint_id];
+            if (saved !== undefined) {
+                const [checkpoint, metadata, parentCheckpointId] = saved;
+                const writes = this.writes[_generateKey(thread_id, checkpoint_ns, checkpoint_id)] ??
+                    [];
+                const pendingWrites = await Promise.all(writes.map(async ([taskId, channel, value]) => {
+                    return [taskId, channel, await this.serde.parse(value)];
+                }));
+                const parentConfig = parentCheckpointId !== undefined
+                    ? {
+                        configurable: {
+                            thread_id,
+                            checkpoint_ns,
+                            checkpoint_id,
+                        },
+                    }
+                    : undefined;
+                return {
+                    config,
+                    checkpoint: (await this.serde.parse(checkpoint)),
+                    metadata: (await this.serde.parse(metadata)),
+                    pendingWrites,
+                    parentConfig,
+                };
+            }
+        }
+        else {
+            const checkpoints = this.storage[thread_id]?.[checkpoint_ns];
+            if (checkpoints !== undefined) {
+                // eslint-disable-next-line prefer-destructuring
+                checkpoint_id = Object.keys(checkpoints).sort((a, b) => b.localeCompare(a))[0];
+                const saved = checkpoints[checkpoint_id];
+                const [checkpoint, metadata, parentCheckpointId] = saved;
+                const writes = this.writes[_generateKey(thread_id, checkpoint_ns, checkpoint_id)] ??
+                    [];
+                const pendingWrites = await Promise.all(writes.map(async ([taskId, channel, value]) => {
+                    return [taskId, channel, await this.serde.parse(value)];
+                }));
+                const parentConfig = parentCheckpointId !== undefined
+                    ? {
+                        configurable: {
+                            thread_id,
+                            checkpoint_ns,
+                            checkpoint_id: parentCheckpointId,
+                        },
+                    }
+                    : undefined;
+                return {
+                    config: {
+                        configurable: {
+                            thread_id,
+                            checkpoint_id,
+                            checkpoint_ns,
+                        },
+                    },
+                    checkpoint: (await this.serde.parse(checkpoint)),
+                    metadata: (await this.serde.parse(metadata)),
+                    pendingWrites,
+                    parentConfig,
+                };
+            }
+        }
+        return undefined;
+    }
+    async *list(config, options) {
+        // eslint-disable-next-line prefer-const
+        let { before, limit } = options ?? {};
+        const threadIds = config.configurable?.thread_id
+            ? [config.configurable?.thread_id]
+            : Object.keys(this.storage);
+        const checkpointNamespace = config.configurable?.checkpoint_ns ?? "";
+        for (const threadId of threadIds) {
+            const checkpoints = this.storage[threadId]?.[checkpointNamespace] ?? {};
+            const sortedCheckpoints = Object.entries(checkpoints).sort((a, b) => b[0].localeCompare(a[0]));
+            for (const [checkpointId, [checkpoint, metadataStr, parentCheckpointId],] of sortedCheckpoints) {
+                // Filter by checkpoint ID
+                if (before &&
+                    before.configurable?.checkpoint_id &&
+                    checkpointId >= before.configurable.checkpoint_id) {
+                    continue;
+                }
+                // Parse metadata
+                const metadata = (await this.serde.parse(metadataStr));
+                // Limit search results
+                if (limit !== undefined) {
+                    if (limit <= 0)
+                        break;
+                    // eslint-disable-next-line no-param-reassign
+                    limit -= 1;
+                }
+                const writes = this.writes[_generateKey(threadId, checkpointNamespace, checkpointId)] ?? [];
+                const pendingWrites = await Promise.all(writes.map(async ([taskId, channel, value]) => {
+                    return [taskId, channel, await this.serde.parse(value)];
+                }));
+                yield {
+                    config: {
+                        configurable: {
+                            thread_id: threadId,
+                            checkpoint_ns: checkpointNamespace,
+                            checkpoint_id: checkpointId,
+                        },
+                    },
+                    checkpoint: (await this.serde.parse(checkpoint)),
+                    metadata,
+                    pendingWrites,
+                    parentConfig: parentCheckpointId
+                        ? {
+                            configurable: {
+                                thread_id: threadId,
+                                checkpoint_ns: checkpointNamespace,
+                                checkpoint_id: parentCheckpointId,
+                            },
+                        }
+                        : undefined,
+                };
+            }
+        }
+    }
+    async put(config, checkpoint, metadata) {
+        const threadId = config.configurable?.thread_id;
+        const checkpointNamespace = config.configurable?.checkpoint_ns;
+        if (threadId === undefined) {
+            throw new Error(`Failed to put checkpoint. The passed RunnableConfig is missing a required "thread_id" field in its "configurable" property.`);
+        }
+        if (checkpointNamespace === undefined) {
+            throw new Error(`Failed to put checkpoint. The passed RunnableConfig is missing a required "checkpoint_ns" field in its "configurable" property.`);
+        }
+        if (!this.storage[threadId]) {
+            this.storage[threadId] = {};
+        }
+        if (!this.storage[threadId][checkpointNamespace]) {
+            this.storage[threadId][checkpointNamespace] = {};
+        }
+        this.storage[threadId][checkpointNamespace][checkpoint.id] = [
+            this.serde.stringify(checkpoint),
+            this.serde.stringify(metadata),
+            config.configurable?.checkpoint_id, // parent
+        ];
+        return {
+            configurable: {
+                thread_id: threadId,
+                checkpoint_ns: checkpointNamespace,
+                checkpoint_id: checkpoint.id,
+            },
+        };
+    }
+    async putWrites(config, writes, taskId) {
+        const threadId = config.configurable?.thread_id;
+        const checkpointNamespace = config.configurable?.checkpoint_ns;
+        const checkpointId = config.configurable?.checkpoint_id;
+        if (threadId === undefined) {
+            throw new Error(`Failed to put writes. The passed RunnableConfig is missing a required "thread_id" field in its "configurable" property`);
+        }
+        if (checkpointId === undefined) {
+            throw new Error(`Failed to put writes. The passed RunnableConfig is missing a required "checkpoint_id" field in its "configurable" property.`);
+        }
+        const key = _generateKey(threadId, checkpointNamespace, checkpointId);
+        if (this.writes[key] === undefined) {
+            this.writes[key] = [];
+        }
+        const pendingWrites = writes.map(([channel, value]) => {
+            return [taskId, channel, this.serde.stringify(value)];
+        });
+        this.writes[key].push(...pendingWrites);
+    }
+}
+exports.MemorySaver = MemorySaver;

package/dist/memory.d.ts

@@ -0,0 +1,13 @@
+import type { RunnableConfig } from "@langchain/core/runnables";
+import { BaseCheckpointSaver, Checkpoint, CheckpointListOptions, CheckpointTuple } from "./base.js";
+import { SerializerProtocol } from "./serde/base.js";
+import { CheckpointMetadata, CheckpointPendingWrite, PendingWrite } from "./types.js";
+export declare class MemorySaver extends BaseCheckpointSaver {
+    storage: Record<string, Record<string, Record<string, [string, string, string | undefined]>>>;
+    writes: Record<string, CheckpointPendingWrite[]>;
+    constructor(serde?: SerializerProtocol<unknown>);
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+}

package/dist/memory.js

@@ -0,0 +1,192 @@
+import { BaseCheckpointSaver, } from "./base.js";
+function _generateKey(threadId, checkpointNamespace, checkpointId) {
+    return JSON.stringify([threadId, checkpointNamespace, checkpointId]);
+}
+export class MemorySaver extends BaseCheckpointSaver {
+    constructor(serde) {
+        super(serde);
+        // thread ID ->  checkpoint namespace -> checkpoint ID -> checkpoint mapping
+        Object.defineProperty(this, "storage", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "writes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+    }
+    async getTuple(config) {
+        const thread_id = config.configurable?.thread_id;
+        const checkpoint_ns = config.configurable?.checkpoint_ns ?? "";
+        let checkpoint_id = config.configurable?.checkpoint_id;
+        if (checkpoint_id) {
+            const saved = this.storage[thread_id]?.[checkpoint_ns]?.[checkpoint_id];
+            if (saved !== undefined) {
+                const [checkpoint, metadata, parentCheckpointId] = saved;
+                const writes = this.writes[_generateKey(thread_id, checkpoint_ns, checkpoint_id)] ??
+                    [];
+                const pendingWrites = await Promise.all(writes.map(async ([taskId, channel, value]) => {
+                    return [taskId, channel, await this.serde.parse(value)];
+                }));
+                const parentConfig = parentCheckpointId !== undefined
+                    ? {
+                        configurable: {
+                            thread_id,
+                            checkpoint_ns,
+                            checkpoint_id,
+                        },
+                    }
+                    : undefined;
+                return {
+                    config,
+                    checkpoint: (await this.serde.parse(checkpoint)),
+                    metadata: (await this.serde.parse(metadata)),
+                    pendingWrites,
+                    parentConfig,
+                };
+            }
+        }
+        else {
+            const checkpoints = this.storage[thread_id]?.[checkpoint_ns];
+            if (checkpoints !== undefined) {
+                // eslint-disable-next-line prefer-destructuring
+                checkpoint_id = Object.keys(checkpoints).sort((a, b) => b.localeCompare(a))[0];
+                const saved = checkpoints[checkpoint_id];
+                const [checkpoint, metadata, parentCheckpointId] = saved;
+                const writes = this.writes[_generateKey(thread_id, checkpoint_ns, checkpoint_id)] ??
+                    [];
+                const pendingWrites = await Promise.all(writes.map(async ([taskId, channel, value]) => {
+                    return [taskId, channel, await this.serde.parse(value)];
+                }));
+                const parentConfig = parentCheckpointId !== undefined
+                    ? {
+                        configurable: {
+                            thread_id,
+                            checkpoint_ns,
+                            checkpoint_id: parentCheckpointId,
+                        },
+                    }
+                    : undefined;
+                return {
+                    config: {
+                        configurable: {
+                            thread_id,
+                            checkpoint_id,
+                            checkpoint_ns,
+                        },
+                    },
+                    checkpoint: (await this.serde.parse(checkpoint)),
+                    metadata: (await this.serde.parse(metadata)),
+                    pendingWrites,
+                    parentConfig,
+                };
+            }
+        }
+        return undefined;
+    }
+    async *list(config, options) {
+        // eslint-disable-next-line prefer-const
+        let { before, limit } = options ?? {};
+        const threadIds = config.configurable?.thread_id
+            ? [config.configurable?.thread_id]
+            : Object.keys(this.storage);
+        const checkpointNamespace = config.configurable?.checkpoint_ns ?? "";
+        for (const threadId of threadIds) {
+            const checkpoints = this.storage[threadId]?.[checkpointNamespace] ?? {};
+            const sortedCheckpoints = Object.entries(checkpoints).sort((a, b) => b[0].localeCompare(a[0]));
+            for (const [checkpointId, [checkpoint, metadataStr, parentCheckpointId],] of sortedCheckpoints) {
+                // Filter by checkpoint ID
+                if (before &&
+                    before.configurable?.checkpoint_id &&
+                    checkpointId >= before.configurable.checkpoint_id) {
+                    continue;
+                }
+                // Parse metadata
+                const metadata = (await this.serde.parse(metadataStr));
+                // Limit search results
+                if (limit !== undefined) {
+                    if (limit <= 0)
+                        break;
+                    // eslint-disable-next-line no-param-reassign
+                    limit -= 1;
+                }
+                const writes = this.writes[_generateKey(threadId, checkpointNamespace, checkpointId)] ?? [];
+                const pendingWrites = await Promise.all(writes.map(async ([taskId, channel, value]) => {
+                    return [taskId, channel, await this.serde.parse(value)];
+                }));
+                yield {
+                    config: {
+                        configurable: {
+                            thread_id: threadId,
+                            checkpoint_ns: checkpointNamespace,
+                            checkpoint_id: checkpointId,
+                        },
+                    },
+                    checkpoint: (await this.serde.parse(checkpoint)),
+                    metadata,
+                    pendingWrites,
+                    parentConfig: parentCheckpointId
+                        ? {
+                            configurable: {
+                                thread_id: threadId,
+                                checkpoint_ns: checkpointNamespace,
+                                checkpoint_id: parentCheckpointId,
+                            },
+                        }
+                        : undefined,
+                };
+            }
+        }
+    }
+    async put(config, checkpoint, metadata) {
+        const threadId = config.configurable?.thread_id;
+        const checkpointNamespace = config.configurable?.checkpoint_ns;
+        if (threadId === undefined) {
+            throw new Error(`Failed to put checkpoint. The passed RunnableConfig is missing a required "thread_id" field in its "configurable" property.`);
+        }
+        if (checkpointNamespace === undefined) {
+            throw new Error(`Failed to put checkpoint. The passed RunnableConfig is missing a required "checkpoint_ns" field in its "configurable" property.`);
+        }
+        if (!this.storage[threadId]) {
+            this.storage[threadId] = {};
+        }
+        if (!this.storage[threadId][checkpointNamespace]) {
+            this.storage[threadId][checkpointNamespace] = {};
+        }
+        this.storage[threadId][checkpointNamespace][checkpoint.id] = [
+            this.serde.stringify(checkpoint),
+            this.serde.stringify(metadata),
+            config.configurable?.checkpoint_id, // parent
+        ];
+        return {
+            configurable: {
+                thread_id: threadId,
+                checkpoint_ns: checkpointNamespace,
+                checkpoint_id: checkpoint.id,
+            },
+        };
+    }
+    async putWrites(config, writes, taskId) {
+        const threadId = config.configurable?.thread_id;
+        const checkpointNamespace = config.configurable?.checkpoint_ns;
+        const checkpointId = config.configurable?.checkpoint_id;
+        if (threadId === undefined) {
+            throw new Error(`Failed to put writes. The passed RunnableConfig is missing a required "thread_id" field in its "configurable" property`);
+        }
+        if (checkpointId === undefined) {
+            throw new Error(`Failed to put writes. The passed RunnableConfig is missing a required "checkpoint_id" field in its "configurable" property.`);
+        }
+        const key = _generateKey(threadId, checkpointNamespace, checkpointId);
+        if (this.writes[key] === undefined) {
+            this.writes[key] = [];
+        }
+        const pendingWrites = writes.map(([channel, value]) => {
+            return [taskId, channel, this.serde.stringify(value)];
+        });
+        this.writes[key].push(...pendingWrites);
+    }
+}

package/dist/serde/base.cjs

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultSerializer = void 0;
+const load_1 = require("@langchain/core/load");
+exports.DefaultSerializer = {
+    stringify: JSON.stringify,
+    parse: load_1.load,
+};

package/dist/serde/base.d.ts

@@ -0,0 +1,12 @@
+import { load } from "@langchain/core/load";
+export interface SerializerProtocol<D> {
+    stringify(obj: D): string;
+    parse(data: string): Promise<D>;
+}
+export declare const DefaultSerializer: {
+    stringify: {
+        (value: any, replacer?: ((this: any, key: string, value: any) => any) | undefined, space?: string | number | undefined): string;
+        (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string;
+    };
+    parse: typeof load;
+};

package/dist/serde/base.js

@@ -0,0 +1,5 @@
+import { load } from "@langchain/core/load";
+export const DefaultSerializer = {
+    stringify: JSON.stringify,
+    parse: load,
+};

package/dist/serde/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/serde/types.d.ts

@@ -0,0 +1,44 @@
+export interface ChannelProtocol<ValueType = unknown, UpdateType = unknown, CheckpointType = unknown> {
+    ValueType: ValueType;
+    UpdateType: UpdateType;
+    /**
+     * The name of the channel.
+     */
+    lc_graph_name: string;
+    /**
+     * Return a new identical channel, optionally initialized from a checkpoint.
+     * Can be thought of as a "restoration" from a checkpoint which is a "snapshot" of the channel's state.
+     *
+     * @param {CheckpointType | undefined} checkpoint
+     * @param {CheckpointType | undefined} initialValue
+     * @returns {this}
+     */
+    fromCheckpoint(checkpoint?: CheckpointType): this;
+    /**
+     * Update the channel's value with the given sequence of updates.
+     * The order of the updates in the sequence is arbitrary.
+     *
+     * @throws {InvalidUpdateError} if the sequence of updates is invalid.
+     * @param {Array<UpdateType>} values
+     * @returns {void}
+     */
+    update(values: UpdateType[]): void;
+    /**
+     * Return the current value of the channel.
+     *
+     * @throws {EmptyChannelError} if the channel is empty (never updated yet).
+     * @returns {ValueType}
+     */
+    get(): ValueType;
+    /**
+     * Return a string representation of the channel's current state.
+     *
+     * @throws {EmptyChannelError} if the channel is empty (never updated yet), or doesn't support checkpoints.
+     * @returns {CheckpointType | undefined}
+     */
+    checkpoint(): CheckpointType | undefined;
+}
+export interface SendProtocol {
+    node: string;
+    args: any;
+}

package/dist/serde/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export type All = "*";
+export type PendingWriteValue = unknown;
+export type PendingWrite<Channel = string> = [Channel, PendingWriteValue];
+export type CheckpointPendingWrite<TaskId = string> = [
+    TaskId,
+    ...PendingWrite<string>
+];
+export interface CheckpointMetadata {
+    /**
+     * The source of the checkpoint.
+     * - "input": The checkpoint was created from an input to invoke/stream/batch.
+     * - "loop": The checkpoint was created from inside the pregel loop.
+     * - "update": The checkpoint was created from a manual state update.
+     */
+    source: "input" | "loop" | "update";
+    /**
+     * The step number of the checkpoint.
+     * -1 for the first "input" checkpoint.
+     * 0 for the first "loop" checkpoint.
+     * ... for the nth checkpoint afterwards.
+     */
+    step: number;
+    /**
+     * The writes that were made between the previous checkpoint and this one.
+     * Mapping from node name to writes emitted by that node.
+     */
+    writes: Record<string, unknown> | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/index.cjs

@@ -0,0 +1 @@
+module.exports = require('./dist/index.cjs');

package/index.d.cts

@@ -0,0 +1 @@
+export * from './dist/index.js'

package/index.d.ts

@@ -0,0 +1 @@
+export * from './dist/index.js'

package/index.js

@@ -0,0 +1 @@
+export * from './dist/index.js'

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@langchain/langgraph-checkpoint",
+  "version": "0.0.0",
+  "description": "Library with base interfaces for LangGraph checkpoint savers.",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:langchain-ai/langgraphjs.git"
+  },
+  "scripts": {
+    "build": "yarn turbo:command build:internal --filter=@langchain/langgraph-checkpoint",
+    "build:internal": "yarn lc_build_v2 --create-entrypoints --pre --tree-shaking",
+    "lint:eslint": "NODE_OPTIONS=--max-old-space-size=4096 eslint --cache --ext .ts,.js src/",
+    "lint:dpdm": "dpdm --exit-code circular:1 --no-warning --no-tree src/*.ts src/**/*.ts",
+    "lint": "yarn lint:eslint && yarn lint:dpdm",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:dpdm",
+    "prepack": "yarn build",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --testPathIgnorePatterns=\\.int\\.test.ts --testTimeout 30000 --maxWorkers=50%",
+    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch --testPathIgnorePatterns=\\.int\\.test.ts",
+    "test:single": "NODE_OPTIONS=--experimental-vm-modules yarn run jest --config jest.config.cjs --testTimeout 100000",
+    "test:int": "NODE_OPTIONS=--experimental-vm-modules jest --testPathPattern=\\.int\\.test.ts --testTimeout 100000 --maxWorkers=50%",
+    "format": "prettier --config .prettierrc --write \"src\"",
+    "format:check": "prettier --config .prettierrc --check \"src\""
+  },
+  "author": "LangChain",
+  "license": "MIT",
+  "dependencies": {
+    "uuid": "^10.0.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.2.20 <0.3.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@langchain/scripts": "^0.0.22",
+    "@swc/core": "^1.3.90",
+    "@swc/jest": "^0.2.29",
+    "@tsconfig/recommended": "^1.0.3",
+    "@types/uuid": "^10",
+    "@typescript-eslint/eslint-plugin": "^6.12.0",
+    "@typescript-eslint/parser": "^6.12.0",
+    "dotenv": "^16.3.1",
+    "dpdm": "^3.12.0",
+    "eslint": "^8.33.0",
+    "eslint-config-airbnb-base": "^15.0.0",
+    "eslint-config-prettier": "^8.6.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jest": "^28.8.0",
+    "eslint-plugin-no-instanceof": "^1.0.1",
+    "eslint-plugin-prettier": "^4.2.1",
+    "jest": "^29.5.0",
+    "jest-environment-node": "^29.6.4",
+    "prettier": "^2.8.3",
+    "release-it": "^17.6.0",
+    "rollup": "^4.5.2",
+    "ts-jest": "^29.1.0",
+    "tsx": "^4.7.0",
+    "typescript": "^4.9.5 || ^5.4.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./index.d.ts",
+        "require": "./index.d.cts",
+        "default": "./index.d.ts"
+      },
+      "import": "./index.js",
+      "require": "./index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "index.cjs",
+    "index.js",
+    "index.d.ts",
+    "index.d.cts"
+  ]
+}