feat(checkpoint-validation): add custom checkpointer validation tool

.gitignore

@@ -3,6 +3,7 @@ index.js
 index.d.ts
 node_modules
 dist
+coverage/
 .yarn/*
 !.yarn/patches
 !.yarn/plugins
@@ -18,4 +19,4 @@ dist
 .ipynb_checkpoints
 dist-cjs
 **/dist-cjs
-tmp/
+tmp/

libs/checkpoint-validation/.env.example

@@ -0,0 +1,6 @@
+# ------------------LangSmith tracing------------------
+LANGCHAIN_TRACING_V2=true
+LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
+LANGCHAIN_API_KEY=
+LANGCHAIN_PROJECT=
+# -----------------------------------------------------

libs/checkpoint-validation/.eslintrc.cjs

@@ -0,0 +1,69 @@
+module.exports = {
+  extends: [
+    "airbnb-base",
+    "eslint:recommended",
+    "prettier",
+    "plugin:@typescript-eslint/recommended",
+  ],
+  parserOptions: {
+    ecmaVersion: 12,
+    parser: "@typescript-eslint/parser",
+    project: "./tsconfig.json",
+    sourceType: "module",
+  },
+  plugins: ["@typescript-eslint", "no-instanceof", "eslint-plugin-jest"],
+  ignorePatterns: [
+    ".eslintrc.cjs",
+    "scripts",
+    "node_modules",
+    "dist",
+    "dist-cjs",
+    "*.js",
+    "*.cjs",
+    "*.d.ts",
+  ],
+  rules: {
+    "no-process-env": 2,
+    "no-instanceof/no-instanceof": 2,
+    "@typescript-eslint/explicit-module-boundary-types": 0,
+    "@typescript-eslint/no-empty-function": 0,
+    "@typescript-eslint/no-shadow": 0,
+    "@typescript-eslint/no-empty-interface": 0,
+    "@typescript-eslint/no-use-before-define": ["error", "nofunc"],
+    "@typescript-eslint/no-unused-vars": ["warn", { args: "none" }],
+    "@typescript-eslint/no-floating-promises": "error",
+    "@typescript-eslint/no-misused-promises": "error",
+    "arrow-body-style": 0,
+    camelcase: 0,
+    "class-methods-use-this": 0,
+    "import/extensions": [2, "ignorePackages"],
+    "import/no-extraneous-dependencies": [
+      "error",
+      { devDependencies: ["**/*.test.ts"] },
+    ],
+    "import/no-unresolved": 0,
+    "import/prefer-default-export": 0,
+    'jest/no-focused-tests': 'error',
+    "keyword-spacing": "error",
+    "max-classes-per-file": 0,
+    "max-len": 0,
+    "no-await-in-loop": 0,
+    "no-bitwise": 0,
+    "no-console": 0,
+    "no-empty-function": 0,
+    "no-restricted-syntax": 0,
+    "no-shadow": 0,
+    "no-continue": 0,
+    "no-void": 0,
+    "no-underscore-dangle": 0,
+    "no-use-before-define": 0,
+    "no-useless-constructor": 0,
+    "no-return-await": 0,
+    "consistent-return": 0,
+    "no-else-return": 0,
+    "func-names": 0,
+    "no-lonely-if": 0,
+    "prefer-rest-params": 0,
+    "new-cap": ["error", { properties: false, capIsNew: false }],
+  },
+};

libs/checkpoint-validation/.gitignore

@@ -0,0 +1,7 @@
+index.cjs
+index.js
+index.d.ts
+index.d.cts
+node_modules
+dist
+.yarn

libs/checkpoint-validation/.prettierrc

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "requirePragma": false,
+  "insertPragma": false,
+  "proseWrap": "preserve",
+  "htmlWhitespaceSensitivity": "css",
+  "vueIndentScriptAndStyle": false,
+  "endOfLine": "lf"
+}

libs/checkpoint-validation/.release-it.json

@@ -0,0 +1,13 @@
+{
+  "github": {
+    "release": true,
+    "autoGenerate": true,
+    "tokenRef": "GITHUB_TOKEN_RELEASE"
+  },
+  "npm": {
+    "publish": true,
+    "versionArgs": [
+      "--workspaces-update=false"
+    ]
+  }
+}

libs/checkpoint-validation/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.

libs/checkpoint-validation/README.md

@@ -0,0 +1,108 @@
+# @langchain/langgraph-checkpoint-validation
+
+The checkpoint saver validation tool is used to validate that custom checkpoint saver implementations conform to LangGraph's requirements. LangGraph uses [checkpoint savers](https://langchain-ai.github.io/langgraphjs/concepts/persistence/#checkpointer-libraries) for persisting workflow state, providing the ability to "rewind" your workflow to some earlier point in time, and continue execution from there.
+
+The overall process for using this tool is as follows:
+
+1. Write your custom checkpoint saver implementation.
+2. Add a file to your project that defines a [`CheckpointSaverTestInitializer`](./src/types.ts) as its default export.
+3. Run the checkpoint saver validation tool to test your checkpoint saver and determine whether it meets LangGraph's requirements.
+4. Iterate on your custom checkpoint saver as required, until tests pass.
+
+The tool can be executed from the terminal as a CLI, or you can use it as a library to integrate it into your test suite.
+
+## Writing a CheckpointSaverTestInitializer
+
+The `CheckpointSaverTestInitializer` interface ([example](./src/tests/postgresInitializer.ts)) is used by the test harness to create instances of your custom checkpoint saver, and any infrastructure that it requires for testing purposes.
+
+If you intend to execute the tool via the CLI, your `CheckpointSaverTestInitializer` **must** be the default export of the module in which it is defined.
+
+**Synchronous vs Asynchronous initializer functions**: You may return promises from any functions defined in your `CheckpointSaverTestInitializer` according to your needs and the test harness will behave accordingly.
+
+**IMPORTANT**: You must take care to write your `CheckpointSaverTestInitializer` such that instances of your custom checkpoint saver are isolated from one another with respect to persisted state, or else some tests (particularly the ones that exercise the `list` method) will fail. That is, state written by one instance of your checkpoint saver MUST NOT be readable by another instance of your checkpoint saver. That said, there will only ever be one instance of your checkpoint saver live at any given time, so **you may use shared storage, provided it is cleared when your checkpoint saver is created or destroyed.** The structure of the `CheckpointSaverTestInitializer` interface should make this relatively easy to achieve, per the sections below.
+
+
+### (Required) `saverName`: Define a name for your checkpoint saver
+
+`CheckpointSaverTestInitializer` requires you to define a `saverName` field (of type `string`) for use in the test output.
+
+### `beforeAll`: Set up required infrastructure
+
+If your checkpoint saver requires some external infrastructure to be provisioned, you may wish to provision this via the **optional** `beforeAll` function. This function executes exactly once, at the very start of the testing lifecycle. If defined, it is the first function that will be called from your `CheckpointSaverTestInitializer`.
+
+**Timeout duration**: If your `beforeAll` function may take longer than 10 seconds to execute, you can assign a custom timeout duration (as milliseconds) to the optional `beforeAllTimeout` field of your `CheckpointSaverTestInitializer`.
+
+**State isolation note**: Depending on the cost/performance/requirements of your checkpoint saver infrastructure, it **may** make more sense for you to provision it during the `createSaver` step, so you can provide each checkpoint saver instance with its own isolated storage backend. However as mentioned above, you may also provision a single shared storage backend, provided you clear any stored data during the `createSaver` or `destroySaver` step.
+
+### `afterAll`: Tear down required infrastructure
+
+If you set up infrastructure during the `beforeAll` step, you may need to tear it down once the tests complete their execution. You can define this teardown logic in the optional `afterAll` function. Much like `beforeAll` this function will execute exactly one time, after all tests have finished executing.
+
+**IMPORTANT**: If you kill the test runner early this function may not be called. To avoid manual clean-up, give preference to test infrastructure management tools like [TestContainers](https://testcontainers.com/guides/getting-started-with-testcontainers-for-nodejs/), as these tools are designed to detect when this happens and clean up after themselves once the controlling process dies.
+
+### (Required) `createSaver`: Construct your checkpoint saver
+
+`CheckpointSaverTestInitializer` requires you to define a `createSaver(config: RunnableConfig)` function that returns an instance of your custom checkpoint saver. The `config` argument is provided to this function in case it is necessary for the construction of your custom checkpoint saver.
+
+**State isolation note:** If you're provisioning storage during this step, make sure that it is "fresh" storage for each instance of your checkpoint saver. Otherwise if you are using a shared storage setup, be sure to clear it either in this function, or in the `destroySaver` function (described in the section below).
+
+### `destroySaver`: Destroy your checkpoint saver
+
+If your custom checkpoint saver requires an explicit teardown step (for example, to clean up database connections), you can define this in the **optional** `destroySaver(saver: CheckpointSaverT, config: RunnableConfig)` function.
+
+**State isolation note:** If you are using a shared storage setup, be sure to clear it either in this function, or in the `createSaver` function (described in the section above).
+
+### `configure`: Customize the `RunnableConfig` object that is passed during testing
+
+If you need to customize the config argument that is passed to your custom checkpoint saver during testing, you can implement the **optional** `configure(config: RunnableConfig)` function. This function may inspect the default configuration (passed as the `config` argument) and must return an instance of `RunnableConfig`. The `RunnableConfig` returned by this function will be merged with the default config and passed to your checkpoint saver during testing.
+
+Some custom checkpoint savers may require additional custom configuration data to be present in the `configurable` object of the `RunnableConfig` in order to work correctly. For example, custom checkpoint savers that work as part of a multi-tenant application may require authentication details to be passed along in order to enforce data isolation requirements. 
+
+## CLI usage
+
+You may use this tool's CLI either via `npx`, `yarn dlx`, or by installing globally and executing it via the `validate-saver` command.
+
+The only required argument to the tool is the import path for your `CheckpointSaverTestInitializer`. Relative paths must begin with a leading `./` (or `.\`, for Windows), otherwise the path will be interpreted as a module name rather than a relative path.
+
+TypeScript imports **are** supported, so you may pass a path directly to your TypeScript source file.
+
+### NPX & Yarn execution
+
+NPX:
+
+```bash
+cd MySaverProject
+npx @langchain/langgraph-checkpoint-validation ./src/mySaverInitializer.ts
+```
+
+Yarn:
+
+```bash
+yarn dlx @langchain/langgraph-checkpoint-validation ./src/mySaverInitializer.ts
+```
+
+### Global install
+
+NPM:
+
+```bash
+npm install -g @langchain/langgraph-checkpoint-validation
+validate-saver ./src/mySaverInitializer.ts
+```
+
+Yarn:
+
+```bash
+yarn global add @langchain/langgraph-checkpoint-validation
+validate-saver ./src/mySaverInitializer.ts
+```
+
+## Usage in existing Jest test suite
+
+If you wish to integrate this tooling into your existing Jest test suite, you import it as a library, as shown below.
+
+```ts
+import { validate } from "@langchain/langgraph-validation";
+
+validate(MyCheckpointSaverInitializer);
+```

libs/checkpoint-validation/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../dist/cli.js";
+
+await main();

libs/checkpoint-validation/bin/jest.config.cjs

@@ -0,0 +1,19 @@
+// This is the Jest config used by the test harness when being executed via the CLI.
+// For the Jest config for the tests in this project, see the `jest.config.cjs` in the root of the package workspace.
+const path = require("path");
+
+const config = {
+  preset: "ts-jest/presets/default-esm",
+  rootDir: path.resolve(__dirname, "..", "dist"),
+  testEnvironment: "node",
+  testMatch: ["<rootDir>/runner.js"],
+  transform: {
+    "^.+\\.(ts|js)x?$": ["@swc/jest"],
+  },
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.[jt]sx?$": "$1",
+  },
+  maxWorkers: "50%",
+};
+
+module.exports = config;

libs/checkpoint-validation/jest.config.cjs

@@ -0,0 +1,38 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: "ts-jest/presets/default-esm",
+  rootDir: "../../",
+  testEnvironment: "./libs/checkpoint-validation/jest.env.cjs",
+  testMatch: ["<rootDir>/libs/checkpoint-validation/src/**/*.spec.ts"],
+  modulePathIgnorePatterns: ["dist/"],
+
+  collectCoverageFrom: [
+    "<rootDir>/libs/checkpoint/src/memory.ts",
+    "<rootDir>/libs/checkpoint-mongodb/src/index.ts",
+    "<rootDir>/libs/checkpoint-postgres/src/index.ts",
+    "<rootDir>/libs/checkpoint-sqlite/src/index.ts",
+  ],
+
+  coveragePathIgnorePatterns: [
+    ".+\\.(test|spec)\\.ts",
+  ],
+
+  coverageDirectory: "<rootDir>/libs/checkpoint-validation/coverage",
+
+  moduleNameMapper: {
+    "^@langchain/langgraph-(checkpoint(-[^/]+)?)$": "<rootDir>/libs/$1/src/index.ts",
+    "^@langchain/langgraph-(checkpoint(-[^/]+)?)/(.+)\\.js$": "<rootDir>/libs/$1/src/$2.ts",
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  transform: {
+    "^.+\\.tsx?$": ["@swc/jest"],
+  },
+  transformIgnorePatterns: [
+    "/node_modules/(?!@langchain/langgraph-checkpoint-[^/]+)",
+    "\\.pnp\\.[^\\/]+$",
+    "./scripts/jest-setup-after-env.js",
+  ],
+  setupFiles: ["dotenv/config"],
+  testTimeout: 20_000,
+  passWithNoTests: true,
+};

libs/checkpoint-validation/jest.env.cjs

@@ -0,0 +1,12 @@
+const { TestEnvironment } = require("jest-environment-node");
+
+class AdjustedTestEnvironmentToSupportFloat32Array extends TestEnvironment {
+  constructor(config, context) {
+    // Make `instanceof Float32Array` return true in tests
+    // to avoid https://github.com/xenova/transformers.js/issues/57 and https://github.com/jestjs/jest/issues/2549
+    super(config, context);
+    this.global.Float32Array = Float32Array;
+  }
+}
+
+module.exports = AdjustedTestEnvironmentToSupportFloat32Array;

libs/checkpoint-validation/langchain.config.js

@@ -0,0 +1,21 @@
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * @param {string} relativePath
+ * @returns {string}
+ */
+function abs(relativePath) {
+  return resolve(dirname(fileURLToPath(import.meta.url)), relativePath);
+}
+
+export const config = {
+  internals: [/node\:/, /@langchain\/core\//, /async_hooks/],
+  entrypoints: {
+    index: "index"
+  },
+  tsConfigPath: resolve("./tsconfig.json"),
+  cjsSource: "./dist-cjs",
+  cjsDestination: "./dist",
+  abs,
+};