@langchain/langgraph-checkpoint 0.0.9 → 0.0.11

package/dist/base.cjs

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maxChannelVersion = exports.compareChannelVersions = exports.BaseCheckpointSaver = exports.copyCheckpoint = exports.emptyCheckpoint = exports.deepCopy = void 0;
+exports.WRITES_IDX_MAP = exports.maxChannelVersion = exports.compareChannelVersions = exports.BaseCheckpointSaver = exports.copyCheckpoint = exports.emptyCheckpoint = exports.deepCopy = void 0;
 const id_js_1 = require("./id.cjs");
+const types_js_1 = require("./serde/types.cjs");
 const jsonplus_js_1 = require("./serde/jsonplus.cjs");
 function deepCopy(obj) {
     if (typeof obj !== "object" || obj === null) {
@@ -85,3 +86,14 @@ function maxChannelVersion(...versions) {
     });
 }
 exports.maxChannelVersion = maxChannelVersion;
+/**
+ * Mapping from error type to error index.
+ * Regular writes just map to their index in the list of writes being saved.
+ * Special writes (e.g. errors) map to negative indices, to avoid those writes from
+ * conflicting with regular writes.
+ * Each Checkpointer implementation should use this mapping in put_writes.
+ */
+exports.WRITES_IDX_MAP = {
+    [types_js_1.ERROR]: -1,
+    [types_js_1.SCHEDULED]: -2,
+};

package/dist/base.d.ts

@@ -1,7 +1,7 @@
 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";
+import { type ChannelProtocol, type SendProtocol } from "./serde/types.js";
 type ChannelVersion = number | string;
 export type ChannelVersions = Record<string, ChannelVersion>;
 export interface Checkpoint<N extends string = string, C extends string = string> {
@@ -78,4 +78,12 @@ export declare abstract class BaseCheckpointSaver<V extends string | number = nu
 }
 export declare function compareChannelVersions(a: ChannelVersion, b: ChannelVersion): number;
 export declare function maxChannelVersion(...versions: ChannelVersion[]): ChannelVersion;
+/**
+ * Mapping from error type to error index.
+ * Regular writes just map to their index in the list of writes being saved.
+ * Special writes (e.g. errors) map to negative indices, to avoid those writes from
+ * conflicting with regular writes.
+ * Each Checkpointer implementation should use this mapping in put_writes.
+ */
+export declare const WRITES_IDX_MAP: Record<string, number>;
 export {};

package/dist/base.js

@@ -1,4 +1,5 @@
 import { uuid6 } from "./id.js";
+import { ERROR, SCHEDULED, } from "./serde/types.js";
 import { JsonPlusSerializer } from "./serde/jsonplus.js";
 export function deepCopy(obj) {
     if (typeof obj !== "object" || obj === null) {
@@ -76,3 +77,14 @@ export function maxChannelVersion(...versions) {
         return compareChannelVersions(max, version) >= 0 ? max : version;
     });
 }
+/**
+ * Mapping from error type to error index.
+ * Regular writes just map to their index in the list of writes being saved.
+ * Special writes (e.g. errors) map to negative indices, to avoid those writes from
+ * conflicting with regular writes.
+ * Each Checkpointer implementation should use this mapping in put_writes.
+ */
+export const WRITES_IDX_MAP = {
+    [ERROR]: -1,
+    [SCHEDULED]: -2,
+};

package/dist/memory.cjs

@@ -69,7 +69,7 @@ class MemorySaver extends base_js_1.BaseCheckpointSaver {
                         configurable: {
                             thread_id,
                             checkpoint_ns,
-                            checkpoint_id,
+                            checkpoint_id: parentCheckpointId,
                         },
                     };
                 }
@@ -125,13 +125,13 @@ class MemorySaver extends base_js_1.BaseCheckpointSaver {
     }
     async *list(config, options) {
         // eslint-disable-next-line prefer-const
-        let { before, limit } = options ?? {};
+        let { before, limit, filter } = options ?? {};
         const threadIds = config.configurable?.thread_id
             ? [config.configurable?.thread_id]
             : Object.keys(this.storage);
         const configCheckpointNamespace = config.configurable?.checkpoint_ns;
         for (const threadId of threadIds) {
-            for (const checkpointNamespace of Object.keys(this.storage[threadId])) {
+            for (const checkpointNamespace of Object.keys(this.storage[threadId] ?? {})) {
                 if (configCheckpointNamespace !== undefined &&
                     checkpointNamespace !== configCheckpointNamespace) {
                     continue;
@@ -147,6 +147,10 @@ class MemorySaver extends base_js_1.BaseCheckpointSaver {
                     }
                     // Parse metadata
                     const metadata = (await this.serde.loadsTyped("json", metadataStr));
+                    if (filter &&
+                        !Object.entries(filter).every(([key, value]) => metadata[key] === value)) {
+                        continue;
+                    }
                     // Limit search results
                     if (limit !== undefined) {
                         if (limit <= 0)

package/dist/memory.js

@@ -66,7 +66,7 @@ export class MemorySaver extends BaseCheckpointSaver {
                         configurable: {
                             thread_id,
                             checkpoint_ns,
-                            checkpoint_id,
+                            checkpoint_id: parentCheckpointId,
                         },
                     };
                 }
@@ -122,13 +122,13 @@ export class MemorySaver extends BaseCheckpointSaver {
     }
     async *list(config, options) {
         // eslint-disable-next-line prefer-const
-        let { before, limit } = options ?? {};
+        let { before, limit, filter } = options ?? {};
         const threadIds = config.configurable?.thread_id
             ? [config.configurable?.thread_id]
             : Object.keys(this.storage);
         const configCheckpointNamespace = config.configurable?.checkpoint_ns;
         for (const threadId of threadIds) {
-            for (const checkpointNamespace of Object.keys(this.storage[threadId])) {
+            for (const checkpointNamespace of Object.keys(this.storage[threadId] ?? {})) {
                 if (configCheckpointNamespace !== undefined &&
                     checkpointNamespace !== configCheckpointNamespace) {
                     continue;
@@ -144,6 +144,10 @@ export class MemorySaver extends BaseCheckpointSaver {
                     }
                     // Parse metadata
                     const metadata = (await this.serde.loadsTyped("json", metadataStr));
+                    if (filter &&
+                        !Object.entries(filter).every(([key, value]) => metadata[key] === value)) {
+                        continue;
+                    }
                     // Limit search results
                     if (limit !== undefined) {
                         if (limit <= 0)

package/dist/serde/types.cjs

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

package/dist/serde/types.d.ts

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

package/dist/serde/types.js

@@ -1 +1,3 @@
 export const TASKS = "__pregel_tasks";
+export const ERROR = "__error__";
+export const SCHEDULED = "__scheduled__";

package/dist/store/base.cjs

@@ -1,7 +1,42 @@
 "use strict";
 /* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BaseStore = void 0;
+exports.BaseStore = exports.InvalidNamespaceError = void 0;
+/**
+ * Error thrown when an invalid namespace is provided.
+ */
+class InvalidNamespaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidNamespaceError";
+    }
+}
+exports.InvalidNamespaceError = InvalidNamespaceError;
+/**
+ * Validates the provided namespace.
+ * @param namespace The namespace to validate.
+ * @throws {InvalidNamespaceError} If the namespace is invalid.
+ */
+function validateNamespace(namespace) {
+    if (namespace.length === 0) {
+        throw new InvalidNamespaceError("Namespace cannot be empty.");
+    }
+    for (const label of namespace) {
+        if (typeof label !== "string") {
+            throw new InvalidNamespaceError(`Invalid namespace label '${label}' found in ${namespace}. Namespace labels ` +
+                `must be strings, but got ${typeof label}.`);
+        }
+        if (label.includes(".")) {
+            throw new InvalidNamespaceError(`Invalid namespace label '${label}' found in ${namespace}. Namespace labels cannot contain periods ('.').`);
+        }
+        if (label === "") {
+            throw new InvalidNamespaceError(`Namespace labels cannot be empty strings. Got ${label} in ${namespace}`);
+        }
+    }
+    if (namespace[0] === "langgraph") {
+        throw new InvalidNamespaceError(`Root label for namespace cannot be "langgraph". Got: ${namespace}`);
+    }
+}
 /**
  * Abstract base class for key-value stores.
  */
@@ -44,6 +79,7 @@ class BaseStore {
      * @param value Object containing the item's data.
      */
     async put(namespace, key, value) {
+        validateNamespace(namespace);
         await this.batch([{ namespace, key, value }]);
     }
     /**

package/dist/store/base.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Error thrown when an invalid namespace is provided.
+ */
+export declare class InvalidNamespaceError extends Error {
+    constructor(message: string);
+}
 /**
  * Represents a stored item with metadata.
  */

package/dist/store/base.js

@@ -1,4 +1,38 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Error thrown when an invalid namespace is provided.
+ */
+export class InvalidNamespaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidNamespaceError";
+    }
+}
+/**
+ * Validates the provided namespace.
+ * @param namespace The namespace to validate.
+ * @throws {InvalidNamespaceError} If the namespace is invalid.
+ */
+function validateNamespace(namespace) {
+    if (namespace.length === 0) {
+        throw new InvalidNamespaceError("Namespace cannot be empty.");
+    }
+    for (const label of namespace) {
+        if (typeof label !== "string") {
+            throw new InvalidNamespaceError(`Invalid namespace label '${label}' found in ${namespace}. Namespace labels ` +
+                `must be strings, but got ${typeof label}.`);
+        }
+        if (label.includes(".")) {
+            throw new InvalidNamespaceError(`Invalid namespace label '${label}' found in ${namespace}. Namespace labels cannot contain periods ('.').`);
+        }
+        if (label === "") {
+            throw new InvalidNamespaceError(`Namespace labels cannot be empty strings. Got ${label} in ${namespace}`);
+        }
+    }
+    if (namespace[0] === "langgraph") {
+        throw new InvalidNamespaceError(`Root label for namespace cannot be "langgraph". Got: ${namespace}`);
+    }
+}
 /**
  * Abstract base class for key-value stores.
  */
@@ -41,6 +75,7 @@ export class BaseStore {
      * @param value Object containing the item's data.
      */
     async put(namespace, key, value) {
+        validateNamespace(namespace);
         await this.batch([{ namespace, key, value }]);
     }
     /**

package/dist/store/memory.cjs

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemoryStore = void 0;
+exports.MemoryStore = exports.InMemoryStore = void 0;
 const base_js_1 = require("./base.cjs");
-class MemoryStore extends base_js_1.BaseStore {
+class InMemoryStore extends base_js_1.BaseStore {
     constructor() {
         super(...arguments);
         Object.defineProperty(this, "data", {
@@ -113,4 +113,8 @@ class MemoryStore extends base_js_1.BaseStore {
         throw new Error(`Unsupported match type: ${matchType}`);
     }
 }
+exports.InMemoryStore = InMemoryStore;
+/** @deprecated Alias for InMemoryStore */
+class MemoryStore extends InMemoryStore {
+}
 exports.MemoryStore = MemoryStore;

package/dist/store/memory.d.ts

@@ -1,5 +1,5 @@
 import { BaseStore, type OperationResults, type Operation } from "./base.js";
-export declare class MemoryStore extends BaseStore {
+export declare class InMemoryStore extends BaseStore {
     private data;
     batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
     private getOperation;
@@ -8,3 +8,6 @@ export declare class MemoryStore extends BaseStore {
     private listNamespacesOperation;
     private doesMatch;
 }
+/** @deprecated Alias for InMemoryStore */
+export declare class MemoryStore extends InMemoryStore {
+}

package/dist/store/memory.js

@@ -1,5 +1,5 @@
 import { BaseStore, } from "./base.js";
-export class MemoryStore extends BaseStore {
+export class InMemoryStore extends BaseStore {
     constructor() {
         super(...arguments);
         Object.defineProperty(this, "data", {
@@ -110,3 +110,6 @@ export class MemoryStore extends BaseStore {
         throw new Error(`Unsupported match type: ${matchType}`);
     }
 }
+/** @deprecated Alias for InMemoryStore */
+export class MemoryStore extends InMemoryStore {
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-checkpoint",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Library with base interfaces for LangGraph checkpoint savers.",
   "type": "module",
   "engines": {
@@ -58,7 +58,7 @@
     "jest-environment-node": "^29.6.4",
     "prettier": "^2.8.3",
     "release-it": "^17.6.0",
-    "rollup": "^4.5.2",
+    "rollup": "^4.23.0",
     "ts-jest": "^29.1.0",
     "tsx": "^4.7.0",
     "typescript": "^4.9.5 || ^5.4.5"