@langchain/langgraph-checkpoint 0.0.12 → 0.0.13

package/dist/base.cjs

@@ -96,4 +96,6 @@ exports.maxChannelVersion = maxChannelVersion;
 exports.WRITES_IDX_MAP = {
     [types_js_1.ERROR]: -1,
     [types_js_1.SCHEDULED]: -2,
+    [types_js_1.INTERRUPT]: -3,
+    [types_js_1.RESUME]: -4,
 };

package/dist/base.js

@@ -1,5 +1,5 @@
 import { uuid6 } from "./id.js";
-import { ERROR, SCHEDULED, } from "./serde/types.js";
+import { ERROR, INTERRUPT, RESUME, SCHEDULED, } from "./serde/types.js";
 import { JsonPlusSerializer } from "./serde/jsonplus.js";
 export function deepCopy(obj) {
     if (typeof obj !== "object" || obj === null) {
@@ -87,4 +87,6 @@ export function maxChannelVersion(...versions) {
 export const WRITES_IDX_MAP = {
     [ERROR]: -1,
     [SCHEDULED]: -2,
+    [INTERRUPT]: -3,
+    [RESUME]: -4,
 };

package/dist/serde/types.cjs

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SCHEDULED = exports.ERROR = exports.TASKS = void 0;
+exports.RESUME = exports.INTERRUPT = exports.SCHEDULED = exports.ERROR = exports.TASKS = void 0;
 exports.TASKS = "__pregel_tasks";
 exports.ERROR = "__error__";
 exports.SCHEDULED = "__scheduled__";
+exports.INTERRUPT = "__interrupt__";
+exports.RESUME = "__resume__";

package/dist/serde/types.d.ts

@@ -1,6 +1,8 @@
 export declare const TASKS = "__pregel_tasks";
 export declare const ERROR = "__error__";
 export declare const SCHEDULED = "__scheduled__";
+export declare const INTERRUPT = "__interrupt__";
+export declare const RESUME = "__resume__";
 export interface ChannelProtocol<ValueType = unknown, UpdateType = unknown, CheckpointType = unknown> {
     ValueType: ValueType;
     UpdateType: UpdateType;

package/dist/serde/types.js

@@ -1,3 +1,5 @@
 export const TASKS = "__pregel_tasks";
 export const ERROR = "__error__";
 export const SCHEDULED = "__scheduled__";
+export const INTERRUPT = "__interrupt__";
+export const RESUME = "__resume__";

package/dist/store/base.cjs

@@ -1,7 +1,6 @@
 "use strict";
-/* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseStore = exports.InvalidNamespaceError = void 0;
+exports.BaseStore = exports.tokenizePath = exports.getTextAtPath = exports.InvalidNamespaceError = void 0;
 /**
  * Error thrown when an invalid namespace is provided.
  */
@@ -38,69 +37,160 @@ function validateNamespace(namespace) {
     }
 }
 /**
- * Abstract base class for key-value stores.
+ * Utility function to get text at a specific JSON path
+ */
+function getTextAtPath(obj, path) {
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+        if (part.includes("[")) {
+            const [arrayName, indexStr] = part.split("[");
+            const index = indexStr.replace("]", "");
+            if (!current[arrayName])
+                return [];
+            if (index === "*") {
+                const results = [];
+                for (const item of current[arrayName]) {
+                    if (typeof item === "string")
+                        results.push(item);
+                }
+                return results;
+            }
+            const idx = parseInt(index, 10);
+            if (Number.isNaN(idx))
+                return [];
+            current = current[arrayName][idx];
+        }
+        else {
+            current = current[part];
+        }
+        if (current === undefined)
+            return [];
+    }
+    return typeof current === "string" ? [current] : [];
+}
+exports.getTextAtPath = getTextAtPath;
+/**
+ * Tokenizes a JSON path into parts
+ */
+function tokenizePath(path) {
+    return path.split(".");
+}
+exports.tokenizePath = tokenizePath;
+/**
+ * Abstract base class for persistent key-value stores.
+ *
+ * Stores enable persistence and memory that can be shared across threads,
+ * scoped to user IDs, assistant IDs, or other arbitrary namespaces.
+ *
+ * Features:
+ * - Hierarchical namespaces for organization
+ * - Key-value storage with metadata
+ * - Vector similarity search (if configured)
+ * - Filtering and pagination
  */
 class BaseStore {
-    // convenience methods
     /**
-     * Retrieve a single item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
-     * @returns A promise that resolves to the retrieved item or null if not found.
+     * Retrieve a single item by its namespace and key.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
+     * @returns Promise resolving to the item or null if not found
      */
     async get(namespace, key) {
-        const batchResult = await this.batch([{ namespace, key }]);
-        return batchResult[0];
+        return (await this.batch([{ namespace, key }]))[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.
+     * Supports both metadata filtering and vector similarity search.
+     *
+     * @param namespacePrefix Hierarchical path prefix to search within
+     * @param options Search options for filtering and pagination
+     * @returns Promise resolving to list of matching items with relevance scores
+     *
+     * @example
+     * // Search with filters
+     * await store.search(["documents"], {
+     *   filter: { type: "report", status: "active" },
+     *   limit: 5,
+     *   offset: 10
+     * });
+     *
+     * // Vector similarity search
+     * await store.search(["users", "content"], {
+     *   query: "technical documentation about APIs",
+     *   limit: 20
+     * });
      */
-    async search(namespacePrefix, options) {
-        const optionsWithDefaults = {
-            limit: 10,
-            offset: 0,
-            ...(options || {}),
-        };
-        const batchResults = await this.batch([
-            { namespacePrefix, ...optionsWithDefaults },
-        ]);
-        return batchResults[0];
+    async search(namespacePrefix, options = {}) {
+        const { filter, limit = 10, offset = 0, query } = options;
+        return (await this.batch([
+            {
+                namespacePrefix,
+                filter,
+                limit,
+                offset,
+                query,
+            },
+        ]))[0];
     }
     /**
      * Store or update an item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
-     * @param value Object containing the item's data.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
+     * @param value Object containing the item's data
+     * @param index Optional indexing configuration
+     *
+     * @example
+     * // Simple storage
+     * await store.put(["docs"], "report", { title: "Annual Report" });
+     *
+     * // With specific field indexing
+     * await store.put(
+     *   ["docs"],
+     *   "report",
+     *   {
+     *     title: "Q4 Report",
+     *     chapters: [{ content: "..." }, { content: "..." }]
+     *   },
+     *   ["title", "chapters[*].content"]
+     * );
      */
-    async put(namespace, key, value) {
+    async put(namespace, key, value, index) {
         validateNamespace(namespace);
-        await this.batch([{ namespace, key, value }]);
+        await this.batch([{ namespace, key, value, index }]);
     }
     /**
-     * Delete an item.
-     * @param namespace Hierarchical path for the item.
-     * @param key Unique identifier within the namespace.
+     * Delete an item from the store.
+     *
+     * @param namespace Hierarchical path for the item
+     * @param key Unique identifier within the namespace
      */
     async delete(namespace, key) {
         await this.batch([{ namespace, key, 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.
+     * Used to explore data organization and navigate the namespace hierarchy.
+     *
+     * @param options Options for listing namespaces
+     * @returns Promise resolving to list of namespace paths
+     *
+     * @example
+     * // List all namespaces under "documents"
+     * await store.listNamespaces({
+     *   prefix: ["documents"],
+     *   maxDepth: 2
+     * });
+     *
+     * // List namespaces ending with "v1"
+     * await store.listNamespaces({
+     *   suffix: ["v1"],
+     *   limit: 50
+     * });
      */
-    async listNamespaces(options) {
+    async listNamespaces(options = {}) {
         const { prefix, suffix, maxDepth, limit = 100, offset = 0 } = options;
         const matchConditions = [];
         if (prefix) {
@@ -109,26 +199,22 @@ class BaseStore {
         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];
+        return (await this.batch([
+            {
+                matchConditions: matchConditions.length ? matchConditions : undefined,
+                maxDepth,
+                limit,
+                offset,
+            },
+        ]))[0];
     }
     /**
-     * Stop the store. No-op if not implemented.
+     * Start the store. Override if initialization is needed.
      */
-    stop() {
-        // no-op if not implemented.
-    }
+    start() { }
     /**
-     * Start the store. No-op if not implemented.
+     * Stop the store. Override if cleanup is needed.
      */
-    start() {
-        // no-op if not implemented.
-    }
+    stop() { }
 }
 exports.BaseStore = BaseStore;