@langchain/langgraph-checkpoint 0.0.6 → 0.0.8-rc.0

package/dist/store/base.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Represents a stored item with metadata.
+ */
+export interface Item {
+    /**
+     * The stored data as an object. Keys are filterable.
+     */
+    value: Record<string, any>;
+    /**
+     * Unique identifier within the namespace.
+     */
+    id: string;
+    /**
+     * Hierarchical path defining the collection in which this document resides.
+     * Represented as an array of strings, allowing for nested categorization.
+     * For example: ["documents", "user123"]
+     */
+    namespace: string[];
+    /**
+     * Timestamp of item creation.
+     */
+    createdAt: Date;
+    /**
+     * Timestamp of last update.
+     */
+    updatedAt: Date;
+}
+/**
+ * Operation to retrieve an item by namespace and ID.
+ */
+export interface GetOperation {
+    /**
+     * Hierarchical path for the item.
+     */
+    namespace: string[];
+    /**
+     * Unique identifier within the namespace.
+     */
+    id: string;
+}
+/**
+ * Operation to search for items within a namespace prefix.
+ */
+export interface SearchOperation {
+    /**
+     * Hierarchical path prefix to search within.
+     */
+    namespacePrefix: string[];
+    /**
+     * Key-value pairs to filter results.
+     */
+    filter?: Record<string, any>;
+    /**
+     * Maximum number of items to return.
+     * @default 10
+     */
+    limit?: number;
+    /**
+     * Number of items to skip before returning results.
+     * @default 0
+     */
+    offset?: number;
+}
+/**
+ * Operation to store, update, or delete an item.
+ */
+export interface PutOperation {
+    /**
+     * Hierarchical path for the item.
+     * Represented as a tuple of strings, allowing for nested categorization.
+     * @example ["documents", "user123"]
+     */
+    namespace: string[];
+    /**
+     * Unique identifier for the document.
+     * Should be distinct within its namespace.
+     */
+    id: string;
+    /**
+     * Data to be stored, or None to delete the item.
+     * Schema:
+     *  - Should be an object where:
+     *    - Keys are strings representing field names
+     *    - Values can be of any serializable type
+     *  - If null, it indicates that the item should be deleted
+     */
+    value: Record<string, any> | null;
+}
+export type NameSpacePath = (string | "*")[];
+export type NamespaceMatchType = "prefix" | "suffix";
+export interface MatchCondition {
+    matchType: NamespaceMatchType;
+    path: NameSpacePath;
+}
+export interface ListNamespacesOperation {
+    matchConditions?: MatchCondition[];
+    maxDepth?: number;
+    limit: number;
+    offset: number;
+}
+export type Operation = GetOperation | SearchOperation | PutOperation | ListNamespacesOperation;
+export type OperationResults<Tuple extends readonly Operation[]> = {
+    [K in keyof Tuple]: Tuple[K] extends PutOperation ? void : Tuple[K] extends SearchOperation ? Item[] : Tuple[K] extends GetOperation ? Item | null : Tuple[K] extends ListNamespacesOperation ? string[][] : never;
+};
+/**
+ * Abstract base class for key-value stores.
+ */
+export declare abstract class BaseStore {
+    /**
+     * Execute a batch of operations.
+     * @param _operations An array of operations to execute.
+     * @returns A promise that resolves to the results of the operations.
+     */
+    abstract batch<Op extends Operation[]>(_operations: Op): Promise<OperationResults<Op>>;
+    /**
+     * Retrieve a single item.
+     * @param namespace Hierarchical path for the item.
+     * @param id Unique identifier within the namespace.
+     * @returns A promise that resolves to the retrieved item or null if not found.
+     */
+    get(namespace: string[], id: string): Promise<Item | null>;
+    /**
+     * Search for items within a namespace prefix.
+     * @param namespacePrefix Hierarchical path prefix to search within.
+     * @param options Search options.
+     * @param options.filter Key-value pairs to filter results.
+     * @param options.limit Maximum number of items to return (default: 10).
+     * @param options.offset Number of items to skip before returning results (default: 0).
+     * @returns A promise that resolves to a list of items matching the search criteria.
+     */
+    search(namespacePrefix: string[], options?: {
+        filter?: Record<string, any>;
+        limit?: number;
+        offset?: number;
+    }): Promise<Item[]>;
+    /**
+     * Store or update an item.
+     * @param namespace Hierarchical path for the item.
+     * @param id Unique identifier within the namespace.
+     * @param value Object containing the item's data.
+     */
+    put(namespace: string[], id: string, value: Record<string, any>): Promise<void>;
+    /**
+     * Delete an item.
+     * @param namespace Hierarchical path for the item.
+     * @param id Unique identifier within the namespace.
+     */
+    delete(namespace: string[], id: string): Promise<void>;
+    /**
+     * List and filter namespaces in the store.
+     * @param options Options for listing namespaces.
+     * @param options.prefix Filter namespaces that start with this path.
+     * @param options.suffix Filter namespaces that end with this path.
+     * @param options.maxDepth Return namespaces up to this depth in the hierarchy.
+     * @param options.limit Maximum number of namespaces to return (default 100).
+     * @param options.offset Number of namespaces to skip for pagination (default 0).
+     * @returns A promise that resolves to a list of namespace arrays that match the criteria.
+     */
+    listNamespaces(options: {
+        prefix?: string[];
+        suffix?: string[];
+        maxDepth?: number;
+        limit?: number;
+        offset?: number;
+    }): Promise<string[][]>;
+    /**
+     * Stop the store. No-op if not implemented.
+     */
+    stop(): void;
+    /**
+     * Start the store. No-op if not implemented.
+     */
+    start(): void;
+}

package/dist/store/base.js

@@ -0,0 +1,94 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Abstract base class for key-value stores.
+ */
+export class BaseStore {
+    // convenience methods
+    /**
+     * Retrieve a single item.
+     * @param namespace Hierarchical path for the item.
+     * @param id Unique identifier within the namespace.
+     * @returns A promise that resolves to the retrieved item or null if not found.
+     */
+    async get(namespace, id) {
+        const batchResult = await this.batch([{ namespace, id }]);
+        return batchResult[0];
+    }
+    /**
+     * Search for items within a namespace prefix.
+     * @param namespacePrefix Hierarchical path prefix to search within.
+     * @param options Search options.
+     * @param options.filter Key-value pairs to filter results.
+     * @param options.limit Maximum number of items to return (default: 10).
+     * @param options.offset Number of items to skip before returning results (default: 0).
+     * @returns A promise that resolves to a list of items matching the search criteria.
+     */
+    async search(namespacePrefix, options) {
+        const optionsWithDefaults = {
+            limit: 10,
+            offset: 0,
+            ...(options || {}),
+        };
+        const batchResults = await this.batch([
+            { namespacePrefix, ...optionsWithDefaults },
+        ]);
+        return batchResults[0];
+    }
+    /**
+     * Store or update an item.
+     * @param namespace Hierarchical path for the item.
+     * @param id Unique identifier within the namespace.
+     * @param value Object containing the item's data.
+     */
+    async put(namespace, id, value) {
+        await this.batch([{ namespace, id, value }]);
+    }
+    /**
+     * Delete an item.
+     * @param namespace Hierarchical path for the item.
+     * @param id Unique identifier within the namespace.
+     */
+    async delete(namespace, id) {
+        await this.batch([{ namespace, id, value: null }]);
+    }
+    /**
+     * List and filter namespaces in the store.
+     * @param options Options for listing namespaces.
+     * @param options.prefix Filter namespaces that start with this path.
+     * @param options.suffix Filter namespaces that end with this path.
+     * @param options.maxDepth Return namespaces up to this depth in the hierarchy.
+     * @param options.limit Maximum number of namespaces to return (default 100).
+     * @param options.offset Number of namespaces to skip for pagination (default 0).
+     * @returns A promise that resolves to a list of namespace arrays that match the criteria.
+     */
+    async listNamespaces(options) {
+        const { prefix, suffix, maxDepth, limit = 100, offset = 0 } = options;
+        const matchConditions = [];
+        if (prefix) {
+            matchConditions.push({ matchType: "prefix", path: prefix });
+        }
+        if (suffix) {
+            matchConditions.push({ matchType: "suffix", path: suffix });
+        }
+        const op = {
+            matchConditions: matchConditions.length > 0 ? matchConditions : undefined,
+            maxDepth,
+            limit,
+            offset,
+        };
+        const batchResults = await this.batch([op]);
+        return batchResults[0];
+    }
+    /**
+     * Stop the store. No-op if not implemented.
+     */
+    stop() {
+        // no-op if not implemented.
+    }
+    /**
+     * Start the store. No-op if not implemented.
+     */
+    start() {
+        // no-op if not implemented.
+    }
+}

package/dist/store/batch.cjs

@@ -0,0 +1,121 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-explicit-any */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncBatchedStore = void 0;
+const base_js_1 = require("./base.cjs");
+class AsyncBatchedStore extends base_js_1.BaseStore {
+    constructor(store) {
+        super();
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "nextKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "running", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "processingTask", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.store = store;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /**
+     * @ignore
+     * Batch is not implemented here as we're only extending `BaseStore`
+     * to allow it to be passed where `BaseStore` is expected, and implement
+     * the convenience methods (get, search, put, delete).
+     */
+    async batch(_operations) {
+        throw new Error("The `batch` method is not implemented on `AsyncBatchedStore`." +
+            "\n Instead, it calls the `batch` method on the wrapped store." +
+            "\n If you are seeing this error, something is wrong.");
+    }
+    async get(namespace, id) {
+        return this.enqueueOperation({ namespace, id });
+    }
+    async search(namespacePrefix, options) {
+        const { filter, limit = 10, offset = 0 } = options || {};
+        return this.enqueueOperation({
+            namespacePrefix,
+            filter,
+            limit,
+            offset,
+        });
+    }
+    async put(namespace, id, value) {
+        return this.enqueueOperation({ namespace, id, value });
+    }
+    async delete(namespace, id) {
+        return this.enqueueOperation({
+            namespace,
+            id,
+            value: null,
+        });
+    }
+    start() {
+        if (!this.running) {
+            this.running = true;
+            this.processingTask = this.processBatchQueue();
+        }
+    }
+    async stop() {
+        this.running = false;
+        if (this.processingTask) {
+            await this.processingTask;
+        }
+    }
+    enqueueOperation(operation) {
+        return new Promise((resolve, reject) => {
+            const key = this.nextKey;
+            this.nextKey += 1;
+            this.queue.set(key, { operation, resolve, reject });
+        });
+    }
+    async processBatchQueue() {
+        while (this.running) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, 0);
+            });
+            if (this.queue.size === 0)
+                continue;
+            const batch = new Map(this.queue);
+            this.queue.clear();
+            try {
+                const operations = Array.from(batch.values()).map(({ operation }) => operation);
+                const results = await this.store.batch(operations);
+                batch.forEach(({ resolve }, key) => {
+                    const index = Array.from(batch.keys()).indexOf(key);
+                    resolve(results[index]);
+                });
+            }
+            catch (e) {
+                batch.forEach(({ reject }) => {
+                    reject(e);
+                });
+            }
+        }
+    }
+}
+exports.AsyncBatchedStore = AsyncBatchedStore;

package/dist/store/batch.d.ts

@@ -0,0 +1,29 @@
+import { BaseStore, type Item, type Operation, OperationResults } from "./base.js";
+export declare class AsyncBatchedStore extends BaseStore {
+    private store;
+    private queue;
+    private nextKey;
+    private running;
+    private processingTask;
+    constructor(store: BaseStore);
+    get isRunning(): boolean;
+    /**
+     * @ignore
+     * Batch is not implemented here as we're only extending `BaseStore`
+     * to allow it to be passed where `BaseStore` is expected, and implement
+     * the convenience methods (get, search, put, delete).
+     */
+    batch<Op extends Operation[]>(_operations: Op): Promise<OperationResults<Op>>;
+    get(namespace: string[], id: string): Promise<Item | null>;
+    search(namespacePrefix: string[], options?: {
+        filter?: Record<string, any>;
+        limit?: number;
+        offset?: number;
+    }): Promise<Item[]>;
+    put(namespace: string[], id: string, value: Record<string, any>): Promise<void>;
+    delete(namespace: string[], id: string): Promise<void>;
+    start(): void;
+    stop(): Promise<void>;
+    private enqueueOperation;
+    private processBatchQueue;
+}

package/dist/store/batch.js

@@ -0,0 +1,117 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { BaseStore, } from "./base.js";
+export class AsyncBatchedStore extends BaseStore {
+    constructor(store) {
+        super();
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "nextKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "running", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "processingTask", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.store = store;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    /**
+     * @ignore
+     * Batch is not implemented here as we're only extending `BaseStore`
+     * to allow it to be passed where `BaseStore` is expected, and implement
+     * the convenience methods (get, search, put, delete).
+     */
+    async batch(_operations) {
+        throw new Error("The `batch` method is not implemented on `AsyncBatchedStore`." +
+            "\n Instead, it calls the `batch` method on the wrapped store." +
+            "\n If you are seeing this error, something is wrong.");
+    }
+    async get(namespace, id) {
+        return this.enqueueOperation({ namespace, id });
+    }
+    async search(namespacePrefix, options) {
+        const { filter, limit = 10, offset = 0 } = options || {};
+        return this.enqueueOperation({
+            namespacePrefix,
+            filter,
+            limit,
+            offset,
+        });
+    }
+    async put(namespace, id, value) {
+        return this.enqueueOperation({ namespace, id, value });
+    }
+    async delete(namespace, id) {
+        return this.enqueueOperation({
+            namespace,
+            id,
+            value: null,
+        });
+    }
+    start() {
+        if (!this.running) {
+            this.running = true;
+            this.processingTask = this.processBatchQueue();
+        }
+    }
+    async stop() {
+        this.running = false;
+        if (this.processingTask) {
+            await this.processingTask;
+        }
+    }
+    enqueueOperation(operation) {
+        return new Promise((resolve, reject) => {
+            const key = this.nextKey;
+            this.nextKey += 1;
+            this.queue.set(key, { operation, resolve, reject });
+        });
+    }
+    async processBatchQueue() {
+        while (this.running) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, 0);
+            });
+            if (this.queue.size === 0)
+                continue;
+            const batch = new Map(this.queue);
+            this.queue.clear();
+            try {
+                const operations = Array.from(batch.values()).map(({ operation }) => operation);
+                const results = await this.store.batch(operations);
+                batch.forEach(({ resolve }, key) => {
+                    const index = Array.from(batch.keys()).indexOf(key);
+                    resolve(results[index]);
+                });
+            }
+            catch (e) {
+                batch.forEach(({ reject }) => {
+                    reject(e);
+                });
+            }
+        }
+    }
+}

package/dist/store/index.cjs

@@ -0,0 +1,19 @@
+"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 });
+__exportStar(require("./base.cjs"), exports);
+__exportStar(require("./batch.cjs"), exports);
+__exportStar(require("./memory.cjs"), exports);

package/dist/store/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./base.js";
+export * from "./batch.js";
+export * from "./memory.js";

package/dist/store/index.js

@@ -0,0 +1,3 @@
+export * from "./base.js";
+export * from "./batch.js";
+export * from "./memory.js";

package/dist/store/memory.cjs

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStore = void 0;
+const base_js_1 = require("./base.cjs");
+class MemoryStore extends base_js_1.BaseStore {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    async batch(operations) {
+        const results = [];
+        for (const op of operations) {
+            if ("id" in op && "namespace" in op && !("value" in op)) {
+                // GetOperation
+                results.push(this.getOperation(op));
+            }
+            else if ("namespacePrefix" in op) {
+                // SearchOperation
+                results.push(this.searchOperation(op));
+            }
+            else if ("value" in op) {
+                // PutOperation
+                results.push(this.putOperation(op));
+            }
+            else if ("matchConditions" in op) {
+                // ListNamespacesOperation
+                results.push(this.listNamespacesOperation(op));
+            }
+        }
+        return Promise.resolve(results);
+    }
+    getOperation(op) {
+        const namespaceKey = op.namespace.join(":");
+        const item = this.data.get(namespaceKey)?.get(op.id);
+        return item || null;
+    }
+    searchOperation(op) {
+        const candidates = [];
+        for (const [namespace, items] of this.data.entries()) {
+            if (namespace.startsWith(op.namespacePrefix.join(":"))) {
+                candidates.push(...items.values());
+            }
+        }
+        let filteredCandidates = candidates;
+        if (op.filter) {
+            filteredCandidates = candidates.filter((item) => Object.entries(op.filter).every(([key, value]) => item.value[key] === value));
+        }
+        const searchResults = filteredCandidates.slice(op.offset || 0, (op.offset || 0) + (op.limit || 10));
+        return searchResults;
+    }
+    putOperation(op) {
+        const namespaceKey = op.namespace.join(":");
+        if (!this.data.has(namespaceKey)) {
+            this.data.set(namespaceKey, new Map());
+        }
+        const namespaceMap = this.data.get(namespaceKey);
+        if (op.value === null) {
+            namespaceMap.delete(op.id);
+        }
+        else {
+            const now = new Date();
+            if (namespaceMap.has(op.id)) {
+                const item = namespaceMap.get(op.id);
+                item.value = op.value;
+                item.updatedAt = now;
+            }
+            else {
+                namespaceMap.set(op.id, {
+                    value: op.value,
+                    id: op.id,
+                    namespace: op.namespace,
+                    createdAt: now,
+                    updatedAt: now,
+                });
+            }
+        }
+    }
+    listNamespacesOperation(op) {
+        const allNamespaces = Array.from(this.data.keys()).map((ns) => ns.split(":"));
+        let namespaces = allNamespaces;
+        if (op.matchConditions && op.matchConditions.length > 0) {
+            namespaces = namespaces.filter((ns) => op.matchConditions.every((condition) => this.doesMatch(condition, ns)));
+        }
+        if (op.maxDepth !== undefined) {
+            namespaces = Array.from(new Set(namespaces.map((ns) => ns.slice(0, op.maxDepth).join(":")))).map((ns) => ns.split(":"));
+        }
+        namespaces.sort((a, b) => a.join(":").localeCompare(b.join(":")));
+        const paginatedNamespaces = namespaces.slice(op.offset, op.offset + op.limit);
+        return paginatedNamespaces;
+    }
+    doesMatch(matchCondition, key) {
+        const { matchType, path } = matchCondition;
+        if (key.length < path.length) {
+            return false;
+        }
+        if (matchType === "prefix") {
+            return path.every((pElem, index) => {
+                const kElem = key[index];
+                return pElem === "*" || kElem === pElem;
+            });
+        }
+        else if (matchType === "suffix") {
+            return [...path].reverse().every((pElem, index) => {
+                const kElem = key[key.length - 1 - index];
+                return pElem === "*" || kElem === pElem;
+            });
+        }
+        throw new Error(`Unsupported match type: ${matchType}`);
+    }
+}
+exports.MemoryStore = MemoryStore;

package/dist/store/memory.d.ts

@@ -0,0 +1,10 @@
+import { BaseStore, type OperationResults, type Operation } from "./base.js";
+export declare class MemoryStore extends BaseStore {
+    private data;
+    batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
+    private getOperation;
+    private searchOperation;
+    private putOperation;
+    private listNamespacesOperation;
+    private doesMatch;
+}