@farukada/aws-langgraph-dynamodb-ts 1.0.0-rc.1 → 1.0.0

package/package.json

@@ -1,76 +1,98 @@
 {
   "name": "@farukada/aws-langgraph-dynamodb-ts",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0",
   "license": "MIT",
-  "description": "AWS DynamoDB implementation for LangGraph Memory Store and Checkpoint Saver in TypeScript",
+  "description": "DynamoDB persistence for LangGraph.js: checkpoint saver, long-term memory store with semantic search, and chat message history, with optional S3 offload, compression and TTL",
   "keywords": [
     "aws",
     "dynamodb",
     "langchain",
     "langgraph",
     "checkpointer",
-    "memory-store"
+    "checkpoint-saver",
+    "memory-store",
+    "long-term-memory",
+    "chat-history",
+    "semantic-search",
+    "s3",
+    "typescript"
   ],
   "author": "Faruk Ada <info@farukada.com>",
   "homepage": "https://github.com/FarukAda/aws-langgraph-dynamodb-ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/FarukAda/aws-langgraph-dynamodb-ts"
+    "url": "git+https://github.com/FarukAda/aws-langgraph-dynamodb-ts.git"
   },
   "bugs": {
     "url": "https://github.com/FarukAda/aws-langgraph-dynamodb-ts/issues"
   },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=22.0.0",
-    "npm": ">=10.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node scripts/clean.mjs && npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -p tsconfig.build.json --removeComments --declaration false && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:cjs": "tsc -p tsconfig.build.cjs.json --removeComments --declaration false && tsc -p tsconfig.build.cjs.json --emitDeclarationOnly && node scripts/mark-cjs.mjs",
     "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "typecheck:all": "tsc --noEmit",
     "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"*.config.ts\" \"**/*.mjs\" --no-error-on-unmatched-pattern",
     "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"*.config.ts\" \"**/*.mjs\" --fix --no-error-on-unmatched-pattern",
     "test": "jest --coverage",
-    "test:integration": "jest --config jest.integration.config.ts",
+    "test:integration": "jest --config jest.integration.config.mjs",
     "test:integration:up": "docker compose up -d",
     "test:integration:down": "docker compose down",
-    "test:conformance": "jest --config jest.conformance.config.ts",
-    "test:aws": "jest --config jest.aws.config.ts",
+    "test:conformance": "jest --config jest.conformance.config.mjs",
+    "test:aws": "jest --config jest.aws.config.mjs",
     "test:static": "jest test/static",
+    "test:scripts": "node --test \"test/scripts/**/*.test.mjs\"",
     "test:package-smoke": "node --test test/package-smoke/smoke.test.mjs",
+    "test:consumer-types": "node --test test/package-smoke/consumer-types.test.mjs",
+    "test:surface": "node scripts/run-with-timeout.mjs 150 -- node --test --test-force-exit --test-timeout=120000 test/surface/surface.test.mjs",
+    "test:surface:update": "node scripts/update-surface-baseline.mjs",
     "prepublishOnly": "npm run typecheck && npm run typecheck:all && npm run lint && npm run build && npm test",
     "docs": "typedoc",
     "docs:watch": "typedoc --watch",
+    "check:docs": "node scripts/check-doc-samples.mjs",
+    "check:links": "node scripts/check-doc-links.mjs",
     "unused": "knip",
-    "depcheck": "depcheck .",
+    "peer-floors": "node scripts/peer-floors.mjs",
+    "ci:require-green": "node scripts/require-green-ci.mjs",
+    "changelog-section": "node scripts/changelog-section.mjs",
+    "sbom": "node scripts/generate-sbom.mjs",
     "cpd": "jscpd ./src --threshold 2 --min-lines 3 --reporters console --silent --format typescript,javascript",
     "cpd:full": "jscpd ./src --threshold 2 --min-lines 3 --reporters console-full --format typescript,javascript",
     "cpd:test": "jscpd ./test --threshold 2 --min-lines 3 --reporters console-full --format typescript,javascript",
-    "pack:check": "node scripts/pack-check.mjs && publint && attw --pack . --profile node16"
+    "example:checkpointer": "npm run build && node examples/live-checkpointer.mjs",
+    "example:persist": "npm run build && node examples/live-persist.mjs",
+    "example:store": "npm run build && node examples/live-store.mjs",
+    "example:agent": "npm run build && node examples/live-agent.mjs",
+    "pack:check": "node scripts/pack-check.mjs && publint && attw --pack ."
   },
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1116.0",
-    "@aws-sdk/lib-dynamodb": "^3.1116.0",
+    "@aws-sdk/client-dynamodb": "^3.1151.0",
+    "@aws-sdk/lib-dynamodb": "^3.1151.0",
     "@aws-sdk/util-dynamodb": "^3.996.9"
   },
   "peerDependencies": {
-    "@aws-sdk/client-s3": "^3.901.0",
-    "@langchain/core": "^1.2.9",
-    "@langchain/langgraph-checkpoint": "^1.1.5"
-  },
-  "overrides": {
-    "uuid": ">=11.1.1"
+    "@aws-sdk/client-s3": "^3.1151.0",
+    "@langchain/core": "^1.2.17",
+    "@langchain/langgraph-checkpoint": "^1.2.0"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-s3": {
@@ -79,37 +101,37 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@aws-sdk/client-s3": "^3.1116.0",
+    "@aws-sdk/client-s3": "^3.1151.0",
     "@eslint/js": "^10.0.1",
-    "@langchain/aws": "^1.4.4",
-    "@langchain/langgraph": "^1.3.2",
-    "@langchain/langgraph-checkpoint-validation": "^1.1.1",
+    "@langchain/aws": "^1.4.6",
+    "@langchain/langgraph": "^1.5.0",
+    "@langchain/langgraph-checkpoint-validation": "^1.2.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.6.5",
     "@typescript/native": "npm:typescript@^7.0.2",
     "aws-sdk-client-mock": "^4.1.0",
-    "depcheck": "^1.4.7",
-    "eslint": "^10.9.0",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-no-instanceof": "^1.0.1",
-    "eslint-plugin-perfectionist": "^5.10.1",
-    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-perfectionist": "^5.12.1",
+    "eslint-plugin-prettier": "^5.5.7",
     "eslint-plugin-unused-imports": "^4.4.1",
     "expect-type": "^1.4.0",
-    "fast-check": "^4.9.0",
-    "jest": "^30.4.2",
+    "fast-check": "^4.10.2",
+    "jest": "^30.5.2",
+    "jest-environment-node": "^30.5.2",
     "jiti": "^2.7.0",
-    "jscpd": "^5.0.16",
-    "knip": "^6.32.2",
-    "prettier": "^3.9.6",
-    "publint": "^0.3.24",
-    "ts-jest": "^29.4.12",
-    "ts-node": "^10.9.2",
+    "jscpd": "^5.4.1",
+    "knip": "^6.41.0",
+    "langchain": "^1.5.16",
+    "prettier": "^3.9.10",
+    "publint": "^0.3.25",
+    "ts-jest": "^29.4.14",
     "typedoc": "^0.28.20",
-    "typedoc-plugin-markdown": "^4.12.0",
+    "typedoc-plugin-markdown": "^4.14.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "^8.67.0",
-    "zod": "^4.4.3"
+    "typescript-eslint": "^8.71.2",
+    "zod": "^4.6.7"
   },
   "prettier": {
     "semi": true,

package/dist/checkpointer/actions/delete-thread.d.ts

@@ -1,10 +0,0 @@
-import type { CheckpointerContext } from '../internal/setup';
-/**
- * Delete every checkpoint, payload, and write for a thread (all share the
- * thread's partition), best-effort deleting any offloaded S3 objects. Rows
- * this adapter does not own are left in place and logged, so a shared-table
- * partition holding a foreign row is never collaterally wiped.
- */
-export declare function deleteThread(context: CheckpointerContext, threadId: string, options?: {
-    signal?: AbortSignal;
-}): Promise<void>;

package/dist/checkpointer/actions/delete-thread.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.deleteThread = deleteThread;
-const partition_delete_1 = require("../../shared/dynamodb/partition-delete");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const keys_1 = require("../internal/keys");
-const query_1 = require("../internal/query");
-const validation_1 = require("../internal/validation");
-/** The offloaded payloads a checkpointer row can reference. */
-function descriptorsOf(row) {
-    return [
-        row.metadata,
-        row.checkpoint,
-        row.value,
-    ];
-}
-/**
- * Delete every checkpoint, payload, and write for a thread (all share the
- * thread's partition), best-effort deleting any offloaded S3 objects. Rows
- * this adapter does not own are left in place and logged, so a shared-table
- * partition holding a foreign row is never collaterally wiped.
- */
-async function deleteThread(context, threadId, options = {}) {
-    (0, validation_1.validateThreadId)(threadId);
-    await (0, partition_delete_1.deletePartitionRows)({
-        client: context.client,
-        tableName: context.tableName,
-        params: (0, query_1.partitionQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), { consistent: true }),
-        logger: context.logger,
-        retry: (0, retry_policy_1.retryFor)(context, options.signal),
-        signal: options.signal,
-        offloader: context.offloader,
-        operation: 'deleteThread',
-        ownsSortKey: keys_1.isCheckpointerSortKey,
-        descriptorsOf,
-        scope: [threadId],
-    });
-}

package/dist/checkpointer/actions/get-tuple.d.ts

@@ -1,11 +0,0 @@
-import type { RunnableConfig } from '@langchain/core/runnables';
-import type { CheckpointTuple } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from '../internal/setup';
-/**
- * Load a checkpoint tuple: the target checkpoint (by id, or the newest in the
- * namespace), its metadata, its pending writes, and a parent config when the
- * checkpoint has a parent. Returns undefined when no matching checkpoint
- * exists — including for a config that names no thread at all, which the
- * reference savers answer with "nothing" rather than an error.
- */
-export declare function getCheckpointTuple(context: CheckpointerContext, config: RunnableConfig): Promise<CheckpointTuple | undefined>;

package/dist/checkpointer/actions/get-tuple.js

@@ -1,25 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCheckpointTuple = getCheckpointTuple;
-const assemble_1 = require("../internal/assemble");
-const configurable_1 = require("../internal/configurable");
-const fetch_1 = require("../internal/fetch");
-/**
- * Load a checkpoint tuple: the target checkpoint (by id, or the newest in the
- * namespace), its metadata, its pending writes, and a parent config when the
- * checkpoint has a parent. Returns undefined when no matching checkpoint
- * exists — including for a config that names no thread at all, which the
- * reference savers answer with "nothing" rather than an error.
- */
-async function getCheckpointTuple(context, config) {
-    if (config.configurable?.thread_id === undefined)
-        return undefined;
-    const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
-    const meta = await (0, fetch_1.fetchTargetMeta)(context, threadId, checkpointNs, checkpointId, config.signal);
-    if (!meta)
-        return undefined;
-    return (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta, {
-        signal: config.signal,
-        consistent: true,
-    });
-}

package/dist/checkpointer/actions/list.d.ts

@@ -1,20 +0,0 @@
-import type { RunnableConfig } from '@langchain/core/runnables';
-import type { CheckpointListOptions, CheckpointTuple } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from '../internal/setup';
-/**
- * Yield checkpoint tuples for a thread, newest first: every namespace when the
- * config names none (grouped by namespace, newest first within each), else the
- * one namespace given. Without a `thread_id` every thread in the table is
- * listed through a table scan, as the reference savers do; that read is
- * unordered across threads and cross-tenant by construction. Honors
- * `options.before` (only checkpoints older than the given id),
- * `options.filter` (metadata equality), and `options.limit` (max tuples
- * yielded; the read stops right after the yield that reaches it).
- *
- * The scan is deliberately unbounded: this generator streams and never
- * accumulates, `limit` returns early, and a raw-row cap would turn a caller
- * asking for a handful of rare matches over a large thread into a hard error
- * instead of the true (possibly empty) answer. Past the warning threshold an
- * operator is told to narrow the filter or pass a limit.
- */
-export declare function listCheckpoints(context: CheckpointerContext, config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;

package/dist/checkpointer/actions/list.js

@@ -1,113 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.listCheckpoints = listCheckpoints;
-const clock_1 = require("../../shared/clock");
-const constants_1 = require("../../shared/constants");
-const expiry_1 = require("../../shared/dynamodb/expiry");
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const scan_1 = require("../../shared/dynamodb/scan");
-const assemble_1 = require("../internal/assemble");
-const fetch_1 = require("../internal/fetch");
-const item_reader_1 = require("../internal/item-reader");
-const list_scope_1 = require("../internal/list-scope");
-/**
- * The tuple for one META item that passes every filter, assembled eventually
- * consistently (a history listing tolerates a replica lag `getTuple` does not)
- * and reusing the metadata the filter already decoded. Undefined when the row
- * is filtered out or its payload is missing.
- */
-async function tupleFor(context, meta, scope) {
-    if (!(0, list_scope_1.passesKeyFilters)(meta, scope))
-        return undefined;
-    const verdict = await (0, list_scope_1.passesMetadataFilter)(context, meta, scope);
-    if (!verdict.pass)
-        return undefined;
-    return (0, assemble_1.assembleTuple)(context, meta.threadId, meta.checkpointNs, meta, {
-        signal: scope.signal,
-        consistent: false,
-        metadata: verdict.metadata,
-    });
-}
-/** A `checkpoint_id` addresses one row: read it directly instead of scanning the namespace for it. */
-async function* listOne(context, scope) {
-    const meta = await (0, fetch_1.fetchTargetMeta)(context, scope.threadId, scope.checkpointNs ?? '', scope.checkpointId, scope.signal);
-    if (!meta)
-        return;
-    const tuple = await tupleFor(context, meta, scope);
-    if (tuple)
-        yield tuple;
-}
-/** Narrow a scanned row, warning about (and skipping) one that is not a checkpoint meta item. */
-function narrowOrWarn(context, raw) {
-    const meta = (0, item_reader_1.narrowMetaItem)(raw);
-    if (!meta) {
-        context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
-            sortKey: raw.SK,
-        });
-    }
-    return meta;
-}
-/** The META rows a scope covers: a partition query for a thread, a table scan without one. */
-function metaRows(context, scope, now) {
-    const retry = (0, retry_policy_1.retryFor)(context, scope.signal);
-    const bounds = { maxItems: Number.POSITIVE_INFINITY, maxIterations: Number.POSITIVE_INFINITY };
-    return scope.threadId === undefined
-        ? (0, scan_1.paginateScan)({
-            retry,
-            signal: scope.signal,
-            client: context.client,
-            params: (0, expiry_1.withoutExpired)((0, list_scope_1.listScan)(context, scope), now),
-            ...bounds,
-        })
-        : (0, paginate_1.paginateQuery)({
-            retry,
-            signal: scope.signal,
-            client: context.client,
-            params: (0, expiry_1.withoutExpired)((0, list_scope_1.listQuery)(context, { ...scope, threadId: scope.threadId }), now),
-            ...bounds,
-        });
-}
-/**
- * Yield checkpoint tuples for a thread, newest first: every namespace when the
- * config names none (grouped by namespace, newest first within each), else the
- * one namespace given. Without a `thread_id` every thread in the table is
- * listed through a table scan, as the reference savers do; that read is
- * unordered across threads and cross-tenant by construction. Honors
- * `options.before` (only checkpoints older than the given id),
- * `options.filter` (metadata equality), and `options.limit` (max tuples
- * yielded; the read stops right after the yield that reaches it).
- *
- * The scan is deliberately unbounded: this generator streams and never
- * accumulates, `limit` returns early, and a raw-row cap would turn a caller
- * asking for a handful of rare matches over a large thread into a hard error
- * instead of the true (possibly empty) answer. Past the warning threshold an
- * operator is told to narrow the filter or pass a limit.
- */
-async function* listCheckpoints(context, config, options) {
-    const scope = (0, list_scope_1.readListScope)(config, options);
-    if (scope.threadId !== undefined && scope.checkpointId !== undefined) {
-        yield* listOne(context, { ...scope, threadId: scope.threadId });
-        return;
-    }
-    const now = (0, clock_1.nowSeconds)();
-    let yielded = 0;
-    let scanned = 0;
-    for await (const raw of metaRows(context, scope, now)) {
-        scanned += 1;
-        if (scanned === constants_1.LIST_SCAN_WARN_THRESHOLD) {
-            context.logger.warn('list: scanned a large number of rows without the caller stopping; this read is ' +
-                'deliberately unbounded, so narrow the filter or pass options.limit', { threadId: scope.threadId, checkpointNs: scope.checkpointNs, scanned });
-        }
-        const meta = narrowOrWarn(context, raw);
-        if (!meta || (0, expiry_1.isExpiredRow)(meta, now))
-            continue;
-        const tuple = await tupleFor(context, meta, scope);
-        if (!tuple)
-            continue;
-        yield tuple;
-        yielded += 1;
-        if (scope.limit !== undefined && yielded >= scope.limit)
-            return;
-    }
-}

package/dist/checkpointer/actions/put-writes.d.ts

@@ -1,15 +0,0 @@
-import type { RunnableConfig } from '@langchain/core/runnables';
-import type { PendingWrite } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from '../internal/setup';
-/**
- * Persist a task's intermediate writes for a checkpoint as one item per write.
- * Requires `checkpoint_id` in the config — writes always attach to a checkpoint.
- * Regular writes are first-write-wins (matching the reference checkpointer
- * contract); special negative-index writes always overwrite (see
- * {@link writeSpecialItemsWithCleanup}). Regular-write cleanup only ever
- * targets uploads confirmed unreferenced (see {@link writeRegularItems}): a
- * verified non-commit, or a guard rejection whose returned row provably
- * belongs to another call. An upload can leak but a live row can never be
- * stranded pointing at a deleted object.
- */
-export declare function putWrites(context: CheckpointerContext, config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;

package/dist/checkpointer/actions/put-writes.js

@@ -1,62 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.putWrites = putWrites;
-const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
-const orphans_1 = require("../../shared/codec/s3/orphans");
-const errors_1 = require("../../shared/errors/errors");
-const ulid_1 = require("../../shared/ulid");
-const ttl_1 = require("../../shared/validation/ttl");
-const configurable_1 = require("../internal/configurable");
-const item_writer_1 = require("../internal/item-writer");
-const regular_write_1 = require("../internal/regular-write");
-const special_write_cleanup_1 = require("../internal/special-write-cleanup");
-const validation_1 = require("../internal/validation");
-/**
- * Stamps each `putWrites` call, serving two purposes at once. It nonces every
- * S3 upload, so a repeated write never shares an object with an earlier
- * attempt. And because ULIDs are lexicographically time-ordered — and this
- * factory is strictly monotonic even within a single millisecond — it lets the
- * read side identify the *earliest* call that wrote a given channel (see
- * `dropSupersededWrites`). A random UUID nonces just as well but carries no
- * ordering, which would leave that choice arbitrary.
- */
-const nextWriteGroup = (0, ulid_1.createUlidFactory)();
-/** Best-effort delete `items`' offloaded S3 objects, if an offloader is configured. */
-async function cleanUpItems(context, items) {
-    if (!context.offloader)
-        return;
-    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(items.map((item) => item.value)), 'putWrites', context.logger);
-}
-/**
- * Persist a task's intermediate writes for a checkpoint as one item per write.
- * Requires `checkpoint_id` in the config — writes always attach to a checkpoint.
- * Regular writes are first-write-wins (matching the reference checkpointer
- * contract); special negative-index writes always overwrite (see
- * {@link writeSpecialItemsWithCleanup}). Regular-write cleanup only ever
- * targets uploads confirmed unreferenced (see {@link writeRegularItems}): a
- * verified non-commit, or a guard rejection whose returned row provably
- * belongs to another call. An upload can leak but a live row can never be
- * stranded pointing at a deleted object.
- */
-async function putWrites(context, config, writes, taskId) {
-    (0, validation_1.validateTaskId)(taskId);
-    const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
-    const signal = config.signal;
-    if (checkpointId === undefined) {
-        throw new errors_1.ValidationError('checkpoint_id is required to store writes', 'checkpoint_id');
-    }
-    if (writes.length === 0)
-        return;
-    const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
-    const items = await (0, item_writer_1.buildWriteItems)(context, threadId, checkpointNs, checkpointId, taskId, writes, nextWriteGroup(), ttlTimestamp);
-    const special = items.filter((item) => item.index < 0);
-    const regular = items.filter((item) => item.index >= 0);
-    const [specialError, regularOutcome] = await Promise.all([
-        (0, special_write_cleanup_1.writeSpecialItemsWithCleanup)(context, threadId, special, signal),
-        (0, regular_write_1.writeRegularItems)(context, regular, signal),
-    ]);
-    await cleanUpItems(context, regularOutcome.deadUploads);
-    const firstError = specialError ?? regularOutcome.error;
-    if (firstError)
-        throw firstError;
-}

package/dist/checkpointer/actions/put.d.ts

@@ -1,17 +0,0 @@
-import type { RunnableConfig } from '@langchain/core/runnables';
-import type { ChannelVersions, Checkpoint, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from '../internal/setup';
-/**
- * Persist a checkpoint and its metadata as a transactional pair of META and
- * PAYLOAD items, returning the config that addresses the stored checkpoint. The
- * incoming `checkpoint_id` (if any) becomes the new checkpoint's parent.
- * `newVersions` names the channels that changed in this step: only those and
- * the ones the parent stored are persisted (see `storedChannelsFor`).
- *
- * On failure with S3 offload configured, the rows are read back before any
- * upload is deleted (see {@link verifyCheckpointLanded}): a transaction that
- * committed and lost its response is reported as success, a confirmed
- * non-commit cleans up this call's own nonced uploads, and an unverifiable
- * outcome leaks them rather than risk stranding a live row.
- */
-export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions?: ChannelVersions): Promise<RunnableConfig>;

package/dist/checkpointer/actions/put.js

@@ -1,73 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.putCheckpoint = putCheckpoint;
-const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
-const orphans_1 = require("../../shared/codec/s3/orphans");
-const retry_1 = require("../../shared/dynamodb/retry");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const ulid_1 = require("../../shared/ulid");
-const ttl_1 = require("../../shared/validation/ttl");
-const checkpoint_write_verify_1 = require("../internal/checkpoint-write-verify");
-const configurable_1 = require("../internal/configurable");
-const item_writer_1 = require("../internal/item-writer");
-const stored_channels_1 = require("../internal/stored-channels");
-const validation_1 = require("../internal/validation");
-/**
- * Nonces every put's S3 uploads (see {@link buildCheckpointItems}). A ULID
- * rather than a UUID because it sorts by time, which keeps a bucket listing of
- * one checkpoint's objects readable.
- */
-const nextPutNonce = (0, ulid_1.createUlidFactory)();
-/**
- * Persist a checkpoint and its metadata as a transactional pair of META and
- * PAYLOAD items, returning the config that addresses the stored checkpoint. The
- * incoming `checkpoint_id` (if any) becomes the new checkpoint's parent.
- * `newVersions` names the channels that changed in this step: only those and
- * the ones the parent stored are persisted (see `storedChannelsFor`).
- *
- * On failure with S3 offload configured, the rows are read back before any
- * upload is deleted (see {@link verifyCheckpointLanded}): a transaction that
- * committed and lost its response is reported as success, a confirmed
- * non-commit cleans up this call's own nonced uploads, and an unverifiable
- * outcome leaks them rather than risk stranding a live row.
- */
-async function putCheckpoint(context, config, checkpoint, metadata, newVersions) {
-    const { threadId, checkpointNs, checkpointId: parentCheckpointId } = (0, configurable_1.readConfigurable)(config);
-    const signal = config.signal;
-    (0, validation_1.validateCheckpointId)(checkpoint.id);
-    const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
-    const storedChannels = await (0, stored_channels_1.storedChannelsFor)(context, threadId, checkpointNs, checkpoint, newVersions, parentCheckpointId, signal);
-    const { meta, payload } = await (0, item_writer_1.buildCheckpointItems)(context, threadId, checkpointNs, checkpoint, metadata, nextPutNonce(), parentCheckpointId, ttlTimestamp, storedChannels);
-    const stored = {
-        configurable: {
-            thread_id: threadId,
-            checkpoint_ns: checkpointNs,
-            checkpoint_id: checkpoint.id,
-        },
-    };
-    try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite({
-            TransactItems: [
-                { Put: { TableName: context.tableName, Item: meta } },
-                { Put: { TableName: context.tableName, Item: payload } },
-            ],
-        }), (0, retry_policy_1.retryFor)(context, signal));
-    }
-    catch (error) {
-        if (!context.offloader)
-            throw error;
-        const verdict = await (0, checkpoint_write_verify_1.verifyCheckpointLanded)(context, meta, payload);
-        if (verdict === 'landed') {
-            context.logger.debug('put: transaction committed although its response was lost', {
-                threadId,
-                checkpointId: checkpoint.id,
-            });
-            return stored;
-        }
-        if (verdict === 'not-landed') {
-            await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([meta.metadata, payload.checkpoint]), 'put', context.logger);
-        }
-        throw error;
-    }
-    return stored;
-}

package/dist/checkpointer/internal/assemble.d.ts

@@ -1,17 +0,0 @@
-import type { CheckpointMetadata, CheckpointTuple } from '@langchain/langgraph-checkpoint';
-import type { CheckpointMetaItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/** How a tuple is assembled: cancellation, read consistency, and metadata already decoded by the caller. */
-export interface AssembleOptions {
-    signal?: AbortSignal;
-    /** `true` for `getTuple` (read-your-writes), `false` for the eventually-consistent `list` path. */
-    consistent: boolean;
-    /** Metadata the caller decoded to apply a filter, so it is not decoded (or downloaded) twice. */
-    metadata?: CheckpointMetadata;
-}
-/**
- * Assemble a full {@link CheckpointTuple} from a META item: fetch and decode its
- * payload, metadata, and pending writes, attaching a parent config when present.
- * Returns undefined when the payload item is missing (inconsistent state).
- */
-export declare function assembleTuple(context: CheckpointerContext, threadId: string, checkpointNs: string, meta: CheckpointMetaItem, options: AssembleOptions): Promise<CheckpointTuple | undefined>;

package/dist/checkpointer/internal/assemble.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.assembleTuple = assembleTuple;
-const fetch_1 = require("./fetch");
-const item_reader_1 = require("./item-reader");
-const pending_sends_1 = require("./pending-sends");
-/** Build a config that addresses a specific checkpoint. */
-function configFor(threadId, checkpointNs, checkpointId) {
-    return {
-        configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId },
-    };
-}
-/**
- * Assemble a full {@link CheckpointTuple} from a META item: fetch and decode its
- * payload, metadata, and pending writes, attaching a parent config when present.
- * Returns undefined when the payload item is missing (inconsistent state).
- */
-async function assembleTuple(context, threadId, checkpointNs, meta, options) {
-    const read = { signal: options.signal, consistent: options.consistent };
-    const payload = await (0, fetch_1.fetchPayload)(context, threadId, checkpointNs, meta.checkpointId, read);
-    if (!payload)
-        return undefined;
-    const [checkpoint, metadata, pendingWrites] = await Promise.all([
-        (0, item_reader_1.readCheckpoint)(context, payload, threadId).then((stored) => (0, pending_sends_1.migratePendingSends)(context, stored, threadId, checkpointNs, meta.parentCheckpointId, read)),
-        options.metadata ?? (0, item_reader_1.readMetadata)(context, meta, threadId),
-        (0, fetch_1.fetchPendingWrites)(context, threadId, checkpointNs, meta.checkpointId, read),
-    ]);
-    const tuple = {
-        config: configFor(threadId, checkpointNs, meta.checkpointId),
-        checkpoint,
-        metadata,
-        pendingWrites,
-    };
-    if (meta.parentCheckpointId !== undefined) {
-        tuple.parentConfig = configFor(threadId, checkpointNs, meta.parentCheckpointId);
-    }
-    return tuple;
-}