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

package/dist/cjs/store/store.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBStore = void 0;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const boundary_js_1 = require("../shared/errors/boundary.js");
+const collaborators_js_1 = require("../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../shared/validation/option-shape.js");
+const list_namespaces_js_1 = require("./actions/list-namespaces.js");
+const put_js_1 = require("./actions/put.js");
+const reconcile_vector_index_js_1 = require("./actions/reconcile-vector-index.js");
+const search_js_1 = require("./actions/search.js");
+const batch_plan_js_1 = require("./internal/batch-plan.js");
+const get_item_js_1 = require("./internal/get-item.js");
+const parse_js_1 = require("./internal/parse.js");
+const setup_js_1 = require("./internal/setup.js");
+class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
+    context;
+    shell;
+    constructor(options) {
+        super();
+        const setup = (0, setup_js_1.setUpStore)(options);
+        this.context = setup.context;
+        this.shell = setup.shell;
+    }
+    async dispatch(operation, readConcurrency) {
+        switch (operation.kind) {
+            case 'search':
+                return (0, search_js_1.searchItems)({ ...this.context, readConcurrency }, operation);
+            case 'put':
+            case 'delete':
+                await (0, put_js_1.putItem)(this.context, operation);
+                return null;
+            case 'get':
+                return (0, get_item_js_1.getItem)(this.context, operation.address);
+            case 'list':
+                return (0, list_namespaces_js_1.listNamespaces)(this.context, operation);
+        }
+    }
+    async execute(operations) {
+        return (0, batch_plan_js_1.runBatch)(operations, (operation, readConcurrency) => this.dispatch(operation, readConcurrency), this.context.readConcurrency);
+    }
+    async batch(operations) {
+        return (0, boundary_js_1.guardPublic)('store.batch', async () => {
+            const results = await this.execute((0, parse_js_1.parseOperations)(operations));
+            return results;
+        }, this.context.tableName);
+    }
+    async get(namespace, key) {
+        return (0, boundary_js_1.guardPublic)('store.get', async () => {
+            const [item] = await this.execute([
+                { kind: 'get', address: (0, parse_js_1.parseStoreAddress)(namespace, key) },
+            ]);
+            return item;
+        }, this.context.tableName);
+    }
+    async put(namespace, key, value, index) {
+        return (0, boundary_js_1.guardPublic)('store.put', async () => {
+            await this.execute([(0, parse_js_1.parsePutArguments)(namespace, key, value, index)]);
+        }, this.context.tableName);
+    }
+    async delete(namespace, key) {
+        return (0, boundary_js_1.guardPublic)('store.delete', async () => {
+            await this.execute([{ kind: 'delete', address: (0, parse_js_1.parseStoreAddress)(namespace, key) }]);
+        }, this.context.tableName);
+    }
+    async listNamespaces(options = {}) {
+        return (0, boundary_js_1.guardPublic)('store.listNamespaces', async () => {
+            const [namespaces] = await this.execute([(0, parse_js_1.parseListNamespacesOptions)(options)]);
+            return namespaces;
+        }, this.context.tableName);
+    }
+    async search(namespacePrefix, options = {}) {
+        return (0, boundary_js_1.guardPublic)('store.search', () => {
+            const prefix = (0, parse_js_1.parseNamespacePrefix)(namespacePrefix, 'namespacePrefix');
+            (0, option_shape_js_1.assertObjectShape)(options, 'options');
+            (0, collaborators_js_1.assertSignalLike)(options.signal);
+            const { signal, ...rest } = options;
+            return (0, search_js_1.searchItems)(this.context, (0, parse_js_1.parseSearch)(prefix, rest), signal);
+        }, this.context.tableName);
+    }
+    reconcileVectorIndex(namespacePrefix, options) {
+        return (0, boundary_js_1.guardPublic)('store.reconcileVectorIndex', () => {
+            (0, collaborators_js_1.assertCancelOptions)(options);
+            return (0, reconcile_vector_index_js_1.reconcileVectorIndex)(this.context, namespacePrefix, options);
+        }, this.context.tableName);
+    }
+    stop() {
+        this.destroy();
+    }
+    destroy() {
+        (0, boundary_js_1.guardPublicSync)('store.destroy', () => this.shell.release(), this.context.tableName);
+    }
+    async ensureS3LifecycleRule() {
+        return (0, boundary_js_1.guardPublic)('store.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule(), this.context.tableName);
+    }
+}
+exports.DynamoDBStore = DynamoDBStore;

package/dist/{store → cjs/store}/types.d.ts

@@ -12,18 +12,25 @@
  * type what it builds without learning how it is checked.
  */
 import type { IndexConfig, SearchOperation, SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options';
-import type { VectorBackend, VectorScoreDirection } from './vector-backend';
-/** Options for {@link DynamoDBStore}. */
-export type DynamoDBStoreOptions = BaseAdapterOptions & CodecOptions & {
+import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options.js';
+import type { VectorBackend, VectorScoreDirection } from './vector-backend.js';
+/**
+ * Options for {@link DynamoDBStore}.
+ *
+ * `indexName` and `indexShards` are not store options: no store read uses the
+ * recency index, so a store given either refuses it as an unknown key.
+ */
+export type DynamoDBStoreOptions = Omit<BaseAdapterOptions, 'indexName' | 'indexShards'> & CodecOptions & {
     /**
      * Optional semantic-search index configuration (embeddings + fields).
      *
      * Without a `vectorBackend` the vectors live on the item itself, one per
-     * extracted path at roughly 10 bytes per dimension. They are not counted
-     * toward `s3.thresholdBytes` — offload decides on the payload alone — so a
-     * value near the threshold plus many vectors is the combination to watch
-     * against DynamoDB's 400 KB item limit; see that option's note.
+     * text the configured fields extract — a wildcard path such as
+     * `sections[*].text` extracts one per element — at up to 10 bytes per
+     * dimension. They are not counted toward `s3.thresholdBytes` — offload
+     * decides on the payload alone — and a row they would take past
+     * DynamoDB's 400 KB item limit is refused with `VALIDATION` naming
+     * `index` before anything is written.
      */
     index?: IndexConfig;
     /**
@@ -46,9 +53,17 @@ export type DynamoDBStoreOptions = BaseAdapterOptions & CodecOptions & {
      * Cap on rows read into memory by one search, namespace listing or
      * reconcile before `RESULT_TRUNCATED`. Reaching it is an error, not a
      * truncation: a partial answer is never returned as a complete one.
-     * Defaults to `MAX_TOTAL_ROWS_IN_MEMORY`.
+     * Defaults to 10,000; the ceiling is 1,000,000.
      */
     maxScanItems?: number;
+    /**
+     * Cap on DynamoDB pages one search, namespace listing or reconcile reads
+     * before `RESULT_TRUNCATED` (default 1000; a page is at most 1 MB).
+     * `Infinity` reads to the end. It is the cap a rootless search or listing
+     * over a large table meets first when most of what it scans is not store
+     * rows, since those pages hold few rows for `maxScanItems` to count.
+     */
+    maxIterations?: number;
     /**
      * Direction of the score a `vectorBackend` returns. `'relevance'` (the
      * default) forwards it unchanged; `'distance'` negates and re-sorts, so a
@@ -82,7 +97,7 @@ export interface ListNamespacesOptions {
      */
     maxDepth?: number;
     /**
-     * How many namespaces to return, from 0 to `MAX_PAGE_LIMIT` (10,000);
+     * How many namespaces to return, from 0 to 10,000;
      * default 100. `0` returns an empty array without reading the table.
      */
     limit?: number;

package/dist/cjs/store/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/store/vector-backend.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VECTOR_SCORE_DIRECTIONS = void 0;
+exports.VECTOR_SCORE_DIRECTIONS = ['relevance', 'distance'];

package/dist/esm/backfill/backfill.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Hides how rows written before the recency index are given its keys.
+ *
+ * The index is opt-in (record 8), so a table can hold rows from before it
+ * existed. An operator walks the table a page at a time, resumably, and gives
+ * each row the keys its adapter would have written; which rows those are is
+ * each adapter's own answer, asked here, and a row that gained keys since the
+ * scan read it is left alone.
+ */
+import type { AttributeMap, DynamoDBDocumentLike } from '../shared/dynamodb/client.js';
+import { type IndexTarget } from '../shared/dynamodb/recency-index.js';
+import { type RetryOptions } from '../shared/dynamodb/retry.js';
+/**
+ * Give rows written before the recency index their index keys.
+ *
+ * **Run this before setting `indexName` on any adapter.** A row without the
+ * keys is not in the index, so enabling the index first would make every
+ * pre-existing session and checkpoint silently vanish from the listings
+ * that read it — the rows are still there, and every other read still returns
+ * them, but a listing would not.
+ *
+ * Safe to re-run and safe to run while adapters are writing: every write is
+ * conditional on the row still being there and having no keys yet, so a row a
+ * live adapter has already indexed is left exactly as it is, and a row deleted
+ * after the scan found it stays deleted rather than being re-created by an
+ * `UpdateItem`, which upserts.
+ *
+ * `indexShards` must match what the saver and the history use. A mismatch
+ * puts rows on shards no listing queries, which looks exactly like the rows
+ * being missing.
+ *
+ * Accepts: `options` — validated in full before any read: only the keys
+ * `BackfillOptions` declares; `tableName`, `indexShards` and the numbers in
+ * `retry` by the adapters' rules; `signal` as their methods check it; a
+ * `client` providing `scan` and `update`. `options.pageSize` — a positive integer,
+ * default 100. `options.cursor` — from a previous run, to resume.
+ * `options.maxPages` — how far one run goes, so a large table can be
+ * backfilled in bounded slices. `options.indexShards` — must equal the
+ * saver's and the history's setting, and has their ceiling. `options.dryRun` — a boolean.
+ * `options.signal` — cancels the run; `retry.signal` does so when there is no
+ * top-level `signal`, and the top-level one wins when both are given.
+ *
+ * Returns: how many rows were scanned, how many were given keys and how many
+ * were skipped — a row no listing reaches, and a row whose write the condition
+ * refused because the row already has keys or is gone — plus a `nextCursor`
+ * when the run stopped short of the end. An absent cursor means the table is
+ * fully backfilled.
+ *
+ * Throws: `VALIDATION` naming the offending option, before any DynamoDB
+ * call; `RETRY_EXHAUSTED` once a transient failure has used every attempt;
+ * `ABORTED` when `signal` fires, or `retry.signal` when no top-level `signal`
+ * is given; any other error the scan or the writes throw, wrapped with the
+ * code the classifier assigns — this is the function's own error boundary,
+ * the same as every adapter's public methods, so a caller's mistake never escapes as a bare
+ * exception. A refused write is none of these: it is an outcome for one row,
+ * reported in `skipped`.
+ *
+ * Guarantees: every write is conditional on the row still being there and
+ * having no keys yet, so re-running is safe, running against a live table is
+ * safe, a row a live adapter has already indexed is left exactly as it is, and
+ * a row deleted between the scan and the write is never re-created. Neither
+ * refusal stops the run: both mean this run has nothing to do for that row, so
+ * the row is counted as skipped and the walk carries on to the rest of the
+ * table.
+ */
+export declare function backfillRecencyIndex(options: BackfillOptions): Promise<BackfillResult>;
+/**
+ * Which rows the index covers: the checkpointer and the chat history each
+ * answer for their own rows; a store row is in no listing the index serves.
+ *
+ * Accepts: `row` — any row a table scan returns, including a foreign one and
+ * one whose `PK`/`SK` are not strings.
+ *
+ * Returns: the index identity, or undefined for a row no listing reaches — a
+ * foreign row, a payload or write row, a META row carrying no `checkpointId`,
+ * or a store row.
+ *
+ * Throws: nothing. A backfill walks the whole table; one unrecognised row must
+ * be skipped, not fatal.
+ */
+export declare function indexTargetOf(row: AttributeMap): IndexTarget | undefined;
+/**
+ * A scan position, as an opaque string.
+ *
+ * Accepts: `key` — a `LastEvaluatedKey` from the scan being resumed.
+ *
+ * Returns: it base64url-encoded. Opaque to the caller: its shape is not a
+ * promise, which is what leaves the encoding free to change.
+ *
+ * Throws: nothing.
+ */
+export declare function encodeScanCursor(key: AttributeMap): string;
+/**
+ * The scan position a cursor encodes.
+ *
+ * Accepts: `cursor` — as a previous page returned it.
+ *
+ * Returns: the `ExclusiveStartKey` to resume from — always exactly `{ PK,
+ * SK }`, both strings, since a plain table `Scan` (no `IndexName`) never
+ * returns a `LastEvaluatedKey` shaped any other way.
+ *
+ * Throws: `VALIDATION` naming `cursor` for anything this tool did not
+ * issue — text that is not base64url, that does not decode to JSON, or that
+ * decodes to anything but `{ PK: string, SK: string }`: an array, an object
+ * missing either key, carrying an extra one, or carrying a non-string value
+ * for either. A cursor is fed straight back to DynamoDB as
+ * `ExclusiveStartKey`, so a value of the wrong shape is refused here rather
+ * than surfacing as a raw `ValidationException` from the service.
+ */
+export declare function decodeScanCursor(cursor: string): AttributeMap;
+/** What one pass of the backfill did, and where to resume. */
+export interface BackfillResult {
+    /** Rows the scan returned: those without index keys, since its filter drops every row that has them. Not the rows DynamoDB evaluated, which a filter does not reduce. */
+    scanned: number;
+    /** Rows given index keys. */
+    indexed: number;
+    /**
+     * Rows this run wrote no keys for: one no listing reaches, and one whose
+     * write the condition refused because it already has keys or is gone.
+     */
+    skipped: number;
+    /**
+     * Opaque; absent when the table is fully walked. Pass it back to continue —
+     * the pass is resumable, so a large table can be backfilled in bounded runs.
+     */
+    nextCursor?: string;
+}
+/** What the backfill needs to walk a table. A key this type does not declare is refused. */
+export interface BackfillOptions {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    /** Must equal the saver's and the history's `indexShards`, or rows land on shards no listing queries. */
+    indexShards?: number;
+    /** Rows per scan page. */
+    pageSize?: number;
+    /** Stop after this many pages and return a cursor. Default: walk the whole table. */
+    maxPages?: number;
+    cursor?: string;
+    /** Report what would change without writing. */
+    dryRun?: boolean;
+    /**
+     * The full retry surface, not the adapters' narrower `RetryPolicy`:
+     * `onRetry` is backfill's only way to observe retries in progress, since it
+     * takes no `logger`.
+     */
+    retry?: RetryOptions;
+    signal?: AbortSignal;
+}
+/**
+ * Validate every option `backfillRecencyIndex` reads, before any of them is
+ * read for real.
+ *
+ * Accepts: `options` — must be an object naming only the nine keys
+ * {@link BackfillOptions} declares. `tableName` and `client` are required, the
+ * rest optional; each, when given, follows the same rule an adapter's own
+ * option of the same name does. `tableName` reuses the adapters' own
+ * `tableName` validator outright; `indexShards` is held to the adapters'
+ * shard cap of 1024; and `retry` shares its numeric bounds with
+ * the adapters' own `retry` validator while accepting the wider surface
+ * backfill's `RetryOptions` needs, so a mismatch between backfill and the
+ * adapters it feeds cannot drift in on what a bound means.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `options.<key>` for an unknown key;
+ * `tableName`; `client` or `client.<member>`; `indexShards`, `pageSize` or
+ * `maxPages` for a non-positive-integer bound (`indexShards` is additionally
+ * capped); `dryRun` for a non-boolean; `retry`/`retry.<key>`; `signal`.
+ */
+export declare function assertBackfillOptions(options: BackfillOptions): void;

package/dist/esm/backfill/backfill.js

@@ -0,0 +1,170 @@
+import { checkpointIndexTarget } from '../checkpointer/internal/rows.js';
+import { sessionIndexTarget } from '../history/internal/session.js';
+import { DEFAULT_READ_CONCURRENCY, mapWithConcurrency } from '../shared/concurrency.js';
+import { isConditionalCheckFailed } from '../shared/dynamodb/idempotent-write.js';
+import { DEFAULT_INDEX_SHARDS, INDEX_PARTITION_ATTRIBUTE, INDEX_SORT_ATTRIBUTE, indexKeys, MAX_INDEX_SHARDS, } from '../shared/dynamodb/recency-index.js';
+import { withDynamoDBRetry } from '../shared/dynamodb/retry.js';
+import { PARTITION_KEY_ATTRIBUTE, rowKeyOf } from '../shared/dynamodb/table-schema.js';
+import { guardPublic } from '../shared/errors/boundary.js';
+import { validationError } from '../shared/errors/errors.js';
+import { assertClientTranslation, assertMembers, assertSignalLike, } from '../shared/validation/collaborators.js';
+import { allKeysOf, assertShape } from '../shared/validation/option-shape.js';
+import { assertRetryBounds, assertTableName } from '../shared/validation/options.js';
+import { assertInteger, assertStringArray } from '../shared/validation/primitives.js';
+function runRetry(options) {
+    return { ...options.retry, signal: options.signal ?? options.retry?.signal };
+}
+async function indexRow(options, row, shards) {
+    const target = indexTargetOf(row);
+    if (target === undefined)
+        return false;
+    const keys = indexKeys(target.tag, target.id, target.at, shards);
+    if (options.dryRun)
+        return true;
+    try {
+        await writeIndexKeys(options, row, keys);
+    }
+    catch (error) {
+        if (!isConditionalCheckFailed(error))
+            throw error;
+        return false;
+    }
+    return true;
+}
+async function writeIndexKeys(options, row, keys) {
+    await withDynamoDBRetry((request) => options.client.update({
+        TableName: options.tableName,
+        Key: rowKeyOf(row),
+        UpdateExpression: 'SET #gpk = :gpk, #gsk = :gsk',
+        ExpressionAttributeNames: {
+            '#gpk': INDEX_PARTITION_ATTRIBUTE,
+            '#gsk': INDEX_SORT_ATTRIBUTE,
+        },
+        ExpressionAttributeValues: { ':gpk': keys.gsi1pk, ':gsk': keys.gsi1sk },
+        ConditionExpression: `attribute_exists(${PARTITION_KEY_ATTRIBUTE}) AND attribute_not_exists(#gpk)`,
+    }, request), runRetry(options));
+}
+async function backfillPage(options, shards, startKey) {
+    const result = await withDynamoDBRetry((request) => options.client.scan({
+        TableName: options.tableName,
+        Limit: options.pageSize ?? 100,
+        ExclusiveStartKey: startKey,
+        FilterExpression: 'attribute_not_exists(#gpk)',
+        ExpressionAttributeNames: { '#gpk': INDEX_PARTITION_ATTRIBUTE },
+    }, request), runRetry(options));
+    const rows = (result.Items ?? []);
+    const written = await mapWithConcurrency(rows, DEFAULT_READ_CONCURRENCY, (row) => indexRow(options, row, shards));
+    return {
+        rows: rows.length,
+        indexed: written.filter(Boolean).length,
+        nextKey: result.LastEvaluatedKey,
+    };
+}
+export async function backfillRecencyIndex(options) {
+    return guardPublic('backfillRecencyIndex', async () => {
+        assertBackfillOptions(options);
+        const shards = options.indexShards ?? DEFAULT_INDEX_SHARDS;
+        let startKey = options.cursor === undefined ? undefined : decodeScanCursor(options.cursor);
+        let scanned = 0;
+        let indexed = 0;
+        for (let page = 1;; page++) {
+            const result = await backfillPage(options, shards, startKey);
+            scanned += result.rows;
+            indexed += result.indexed;
+            startKey = result.nextKey;
+            if (startKey === undefined)
+                break;
+            if (options.maxPages !== undefined && page >= options.maxPages) {
+                return {
+                    scanned,
+                    indexed,
+                    skipped: scanned - indexed,
+                    nextCursor: encodeScanCursor(startKey),
+                };
+            }
+        }
+        return { scanned, indexed, skipped: scanned - indexed };
+    });
+}
+export function indexTargetOf(row) {
+    return checkpointIndexTarget(row) ?? sessionIndexTarget(row);
+}
+export function encodeScanCursor(key) {
+    return Buffer.from(JSON.stringify(key), 'utf8').toString('base64url');
+}
+function isTableKeyShape(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 2 && typeof value.PK === 'string' && typeof value.SK === 'string';
+}
+export function decodeScanCursor(cursor) {
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!isTableKeyShape(decoded))
+            throw new Error('not a scan position');
+        return decoded;
+    }
+    catch {
+        throw validationError('cursor is not one this tool issued', 'cursor');
+    }
+}
+const BACKFILL_KEYS = allKeysOf({
+    client: 'client',
+    tableName: 'tableName',
+    indexShards: 'indexShards',
+    pageSize: 'pageSize',
+    maxPages: 'maxPages',
+    cursor: 'cursor',
+    dryRun: 'dryRun',
+    retry: 'retry',
+    signal: 'signal',
+});
+const BACKFILL_CLIENT_MEMBERS = ['scan', 'update'];
+const BACKFILL_RETRY_KEYS = allKeysOf({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+    retryableErrors: 'retryableErrors',
+    isRetryable: 'isRetryable',
+    onRetry: 'onRetry',
+    signal: 'signal',
+    rng: 'rng',
+});
+function assertBackfillRetryOptions(retry) {
+    assertShape(retry, BACKFILL_RETRY_KEYS, 'retry');
+    assertRetryBounds(retry);
+    if (retry.retryableErrors !== undefined) {
+        assertStringArray(retry.retryableErrors, 'retry.retryableErrors');
+    }
+    if (retry.isRetryable !== undefined && typeof retry.isRetryable !== 'function') {
+        throw validationError('retry.isRetryable must be a function', 'retry.isRetryable');
+    }
+    if (retry.onRetry !== undefined && typeof retry.onRetry !== 'function') {
+        throw validationError('retry.onRetry must be a function', 'retry.onRetry');
+    }
+    if (retry.rng !== undefined && typeof retry.rng !== 'function') {
+        throw validationError('retry.rng must be a function', 'retry.rng');
+    }
+    assertSignalLike(retry.signal, 'retry.signal');
+}
+function assertPositiveBound(value, field, max) {
+    if (value === undefined)
+        return;
+    assertInteger(value, field, max === undefined ? { min: 1 } : { min: 1, max });
+}
+export function assertBackfillOptions(options) {
+    assertShape(options, BACKFILL_KEYS, 'options');
+    assertTableName(options.tableName);
+    assertMembers(options.client, BACKFILL_CLIENT_MEMBERS, 'client');
+    assertClientTranslation(options.client);
+    assertPositiveBound(options.indexShards, 'indexShards', MAX_INDEX_SHARDS);
+    assertPositiveBound(options.pageSize, 'pageSize');
+    assertPositiveBound(options.maxPages, 'maxPages');
+    if (options.dryRun !== undefined && typeof options.dryRun !== 'boolean') {
+        throw validationError('dryRun must be a boolean', 'dryRun');
+    }
+    if (options.retry !== undefined)
+        assertBackfillRetryOptions(options.retry);
+    assertSignalLike(options.signal);
+}

package/dist/{checkpointer/actions/delete-thread.js → esm/checkpointer/actions/delete-thread.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides what deleting a thread means for the checkpointer's rows.
  *
@@ -8,12 +7,7 @@
  * write rewritten after the read is left alone. A caller names a thread and
  * never learns the row kinds, their sort keys or how a refusal is counted.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.deleteThread = deleteThread;
-const partition_delete_1 = require("../../shared/dynamodb/partition-delete");
-const retry_1 = require("../../shared/dynamodb/retry");
-const parse_1 = require("../internal/parse");
-const rows_1 = require("../internal/rows");
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * Delete exactly the checkpoint, payload and write rows of one thread that the
  * partition read observed.
@@ -51,22 +45,6 @@ const rows_1 = require("../internal/rows");
  * the read never saw still survives the pass, which is why the thread should be
  * quiescent.
  */
-async function deleteThread(context, threadId, options = {}) {
-    const thread = (0, parse_1.parseThreadId)(threadId);
-    await (0, partition_delete_1.deletePartitionRows)({
-        client: context.client,
-        tableName: context.tableName,
-        params: (0, rows_1.partitionQuery)(context.tableName, (0, rows_1.partitionKey)(thread), { consistent: true }),
-        logger: context.logger,
-        retry: (0, retry_1.retryFor)(context, options.signal),
-        signal: options.signal,
-        offloader: context.offloader,
-        operation: 'deleteThread',
-        ownsSortKey: rows_1.isCheckpointerSortKey,
-        descriptorsOf: rows_1.checkpointRowDescriptors,
-        idAttribute: rows_1.WRITE_GROUP_ATTRIBUTE,
-        unitOf: rows_1.checkpointRowUnit,
-        kindOf: rows_1.checkpointRowKind,
-        scope: [thread],
-    });
-}
+export declare function deleteThread(context: CheckpointerContext, threadId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;

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

@@ -0,0 +1,23 @@
+import { deletePartitionRows } from '../../shared/dynamodb/partition-delete.js';
+import { retryFor } from '../../shared/dynamodb/retry.js';
+import { parseThreadId } from '../internal/parse.js';
+import { checkpointRowDescriptors, checkpointRowKind, checkpointRowUnit, isCheckpointerSortKey, partitionKey, partitionQuery, WRITE_GROUP_ATTRIBUTE, } from '../internal/rows.js';
+export async function deleteThread(context, threadId, options = {}) {
+    const thread = parseThreadId(threadId);
+    await deletePartitionRows({
+        client: context.client,
+        tableName: context.tableName,
+        params: partitionQuery(context.tableName, partitionKey(thread), { consistent: true }),
+        logger: context.logger,
+        retry: retryFor(context, options.signal),
+        signal: options.signal,
+        offloader: context.offloader,
+        operation: 'deleteThread',
+        ownsSortKey: isCheckpointerSortKey,
+        descriptorsOf: checkpointRowDescriptors,
+        idAttribute: WRITE_GROUP_ATTRIBUTE,
+        unitOf: checkpointRowUnit,
+        kindOf: checkpointRowKind,
+        scope: [thread],
+    });
+}

package/dist/{checkpointer/actions/get-tuple.js → esm/checkpointer/actions/get-tuple.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides which checkpoint a read config resolves to.
  *
@@ -8,10 +7,9 @@
  * as the reference saver answers. That the read is strongly consistent, so a
  * checkpoint just written is always seen, is fixed here too.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCheckpointTuple = getCheckpointTuple;
-const parse_1 = require("../internal/parse");
-const read_1 = require("../internal/read");
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * One checkpoint with its metadata and pending writes.
  *
@@ -24,8 +22,9 @@ const read_1 = require("../internal/read");
  * `config.signal` — cancels the reads; checked before any of them.
  *
  * Returns: the tuple, or undefined for an unknown thread, an unknown
- * checkpoint, a config naming no thread, or a META row whose PAYLOAD row is not
- * there yet — the window the ordered write leaves open.
+ * checkpoint, a config naming no thread, or a META row whose PAYLOAD row is
+ * gone — a thread mid-delete, or an expiry sweep that reached the PAYLOAD row
+ * first; the two are written in one transaction, so no write leaves that gap.
  *
  * Throws: `VALIDATION`, before any read, naming `config`, `configurable` or
  * `signal` for a config of the wrong shape, or `thread_id`, `checkpoint_ns`,
@@ -34,20 +33,4 @@ const read_1 = require("../internal/read");
  *
  * Guarantees: strongly consistent, so a checkpoint just written is always seen.
  */
-async function getCheckpointTuple(context, config) {
-    const parsed = (0, parse_1.parseConfig)(config);
-    if (parsed.threadId === undefined)
-        return undefined;
-    const address = {
-        threadId: parsed.threadId,
-        checkpointNs: parsed.checkpointNs ?? parse_1.ROOT_NAMESPACE,
-        checkpointId: parsed.checkpointId,
-    };
-    const meta = await (0, read_1.fetchTargetMeta)(context, address, parsed.signal);
-    if (!meta)
-        return undefined;
-    return (0, read_1.assembleTuple)(context, { threadId: address.threadId, checkpointNs: address.checkpointNs }, meta, {
-        signal: parsed.signal,
-        consistent: true,
-    });
-}
+export declare function getCheckpointTuple(context: CheckpointerContext, config: RunnableConfig): Promise<CheckpointTuple | undefined>;

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

@@ -0,0 +1,19 @@
+import { parseConfig, ROOT_NAMESPACE } from '../internal/parse.js';
+import { assembleTuple, fetchTargetMeta } from '../internal/read.js';
+export async function getCheckpointTuple(context, config) {
+    const parsed = parseConfig(config);
+    if (parsed.threadId === undefined)
+        return undefined;
+    const address = {
+        threadId: parsed.threadId,
+        checkpointNs: parsed.checkpointNs ?? ROOT_NAMESPACE,
+        checkpointId: parsed.checkpointId,
+    };
+    const meta = await fetchTargetMeta(context, address, parsed.signal);
+    if (!meta)
+        return undefined;
+    return assembleTuple(context, { threadId: address.threadId, checkpointNs: address.checkpointNs }, meta, {
+        signal: parsed.signal,
+        consistent: true,
+    });
+}