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

package/dist/cjs/checkpointer/internal/read.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Hides which rows a checkpoint read issues, with what consistency, and how a
+ * checkpoint an older release wrote is read back.
+ *
+ * A tuple is a META row, a PAYLOAD row and a checkpoint's WRITE rows, read
+ * strongly for `getTuple` and eventually for `list`, with expired rows absent
+ * however long DynamoDB's sweep lags, and with a pre-v4 checkpoint's `Send`s
+ * migrated from its parent's pending writes. The caller asks for a tuple; which
+ * reads that takes, and in what order, is decided here.
+ */
+import { type Checkpoint, type CheckpointMetadata, type CheckpointPendingWrite, type CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { ThreadAddress } from './parse.js';
+import { type CheckpointLocation, type CheckpointMetaRow, type CheckpointPayloadRow, type MetaReader } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
+/** The thread and namespace a read was asked for. */
+export interface ThreadLocation {
+    readonly threadId: string;
+    readonly checkpointNs: string;
+}
+/** A checkpoint's parent, whose pending writes a pre-v4 checkpoint's migration reads. */
+export interface PendingSendsSource extends ThreadLocation {
+    readonly parentCheckpointId: string | undefined;
+}
+/** Per-read options for the payload and writes reads. */
+export interface ReadOptions {
+    signal?: AbortSignal;
+    /** `false` for bulk reads (`list`) that trade read-your-writes for half the read cost. */
+    consistent?: boolean;
+}
+/**
+ * The META row a read is about: the one `checkpointId` names, else the newest
+ * in the namespace.
+ *
+ * Accepts: `address` — parsed; its `checkpointId` names the row, and its
+ * absence asks for the newest in the namespace. `signal` — aborts the read.
+ * `reader` — the public method this read serves, named when a foreign row is
+ * reported; `getTuple` unless the caller says otherwise.
+ *
+ * Returns: the row, or undefined when there is none — including when every row
+ * in the namespace has expired, or when the only rows there belong to another
+ * writer.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row of ours written by a newer version;
+ * whatever the read throws.
+ *
+ * Guarantees: strongly consistent, and expiry is judged here rather than waited
+ * for, so a checkpoint past its ttl is absent to every reader however long
+ * DynamoDB's sweep lags. The newest-first read returns the first live row of
+ * ours and stops there, stepping over expired and foreign rows
+ * {@link LATEST_META_PAGE_SIZE} at a time when the adapter has a `ttl`, and
+ * reading one row per page when it has none.
+ */
+export declare function fetchTargetMeta(context: CheckpointerContext, address: ThreadAddress, signal?: AbortSignal, reader?: MetaReader): Promise<CheckpointMetaRow | undefined>;
+/**
+ * The PAYLOAD row of one checkpoint.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — defaults to
+ * true; `list` passes false and accepts replica lag, since a listing tolerates
+ * what a read-your-writes `getTuple` does not.
+ *
+ * Returns: the row, or undefined when it is not there — the two rows land in
+ * one transaction, so that is a thread being deleted row by row, or DynamoDB's
+ * expiry sweep reaching the PAYLOAD row before the META row — which the caller
+ * answers as "no checkpoint".
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * read throws.
+ */
+export declare function fetchPayload(context: CheckpointerContext, at: CheckpointLocation, read?: ReadOptions): Promise<CheckpointPayloadRow | undefined>;
+/**
+ * Every pending write stored for one checkpoint, decoded, in write order.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — omitted reads
+ * strongly consistently; `list` passes `false` explicitly and accepts replica
+ * lag, `getTuple` passes `true`.
+ *
+ * Returns: the writes after `dropSupersededWrites` has resolved
+ * first-write-wins; a checkpoint with none returns an empty array.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * query or the payload decode throws.
+ *
+ * Guarantees: the read is deliberately uncapped. It must be complete to be
+ * correct — a `Send` fan-out retried with a changed write order leaves
+ * superseded rows behind that would count toward any cap — so past
+ * {@link LIST_SCAN_WARN_THRESHOLD} rows the read still succeeds and an operator
+ * is told the checkpoint is unusually heavy.
+ */
+export declare function fetchPendingWrites(context: CheckpointerContext, at: CheckpointLocation, read?: ReadOptions): Promise<CheckpointPendingWrite[]>;
+/** 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;
+}
+/**
+ * A full {@link CheckpointTuple} built from a META row.
+ *
+ * Accepts: `thread` — the **caller's** location, never the row's: `thread.threadId`
+ * scopes which S3 object the row may point at, so it must come from the
+ * partition the caller asked for; `thread.checkpointNs` is its namespace.
+ * `options.metadata` — already decoded by a filtered `list`, so a filtered
+ * listing decodes and downloads each metadata blob once, not twice.
+ * `options.consistent` — true for `getTuple`, false for `list`.
+ *
+ * Returns: the tuple, with `parentConfig` set only when the row names a parent;
+ * `undefined` when the PAYLOAD row is absent — a thread mid-delete, or an
+ * expiry sweep that reached the PAYLOAD row first — the same answer a caller
+ * gets for a checkpoint that does not exist.
+ *
+ * Throws: whatever the reads and decodes throw.
+ */
+export declare function assembleTuple(context: CheckpointerContext, thread: ThreadLocation, meta: CheckpointMetaRow, options: AssembleOptions): Promise<CheckpointTuple | undefined>;
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes.
+ *
+ * Accepts: `checkpoint` — any version. `parent` — the checkpoint's own thread
+ * and namespace, plus `parent.parentCheckpointId`, the parent whose pending
+ * writes hold the sends; absent means there is nowhere to migrate from.
+ * `read` — cancellation and consistency for the pending-writes read.
+ *
+ * Returns: the checkpoint untouched when it is v4 or has no parent, and
+ * otherwise a copy with `channel_values[TASKS]` rebuilt. The input is never
+ * mutated.
+ *
+ * Throws: whatever reading the parent's pending writes throws.
+ */
+export declare function migratePendingSends(context: CheckpointerContext, checkpoint: Checkpoint, parent: PendingSendsSource, read: ReadOptions): Promise<Checkpoint>;

package/dist/cjs/checkpointer/internal/read.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchTargetMeta = fetchTargetMeta;
+exports.fetchPayload = fetchPayload;
+exports.fetchPendingWrites = fetchPendingWrites;
+exports.assembleTuple = assembleTuple;
+exports.migratePendingSends = migratePendingSends;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const clock_js_1 = require("../../shared/clock.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const rows_js_1 = require("./rows.js");
+const LATEST_META_PAGE_SIZE = 50;
+async function fetchTargetMeta(context, address, signal, reader = 'getTuple') {
+    const { threadId, checkpointNs, checkpointId } = address;
+    const now = (0, clock_js_1.nowSeconds)();
+    if (checkpointId !== undefined) {
+        const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+            TableName: context.tableName,
+            Key: (0, rows_js_1.metaRowKey)({ threadId, checkpointNs, checkpointId }),
+            ConsistentRead: true,
+        }, request), (0, retry_js_1.retryFor)(context, signal));
+        const meta = (0, rows_js_1.parseHeadRow)(context, result.Item, reader);
+        return meta && !(0, table_schema_js_1.isExpiredRow)(meta, now) ? meta : undefined;
+    }
+    const params = (0, rows_js_1.beginsWithQuery)(context.tableName, (0, rows_js_1.partitionKey)(threadId), (0, rows_js_1.metaSortKeyPrefix)(checkpointNs), {
+        limit: context.ttl === undefined ? 1 : LATEST_META_PAGE_SIZE,
+        consistent: true,
+    });
+    const rows = (0, paginate_js_1.paginateQuery)({
+        retry: (0, retry_js_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, table_schema_js_1.withoutExpired)(params, now),
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    });
+    for await (const raw of rows) {
+        const meta = (0, rows_js_1.parseHeadRow)(context, raw, reader);
+        if (meta && !(0, table_schema_js_1.isExpiredRow)(meta, now))
+            return meta;
+    }
+    return undefined;
+}
+async function fetchPayload(context, at, read = {}) {
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_js_1.payloadRowKey)(at),
+        ConsistentRead: read.consistent ?? true,
+    }, request), (0, retry_js_1.retryFor)(context, read.signal));
+    const item = result.Item;
+    if (item !== undefined)
+        (0, table_schema_js_1.assertReadableRow)(item, 'checkpoint payload');
+    return item;
+}
+async function fetchPendingWrites(context, at, read = {}) {
+    const params = (0, rows_js_1.beginsWithQuery)(context.tableName, (0, rows_js_1.partitionKey)(at.threadId), (0, rows_js_1.writeSortKeyPrefix)(at.checkpointNs, at.checkpointId), { ascending: true, consistent: read.consistent ?? true });
+    const items = [];
+    for await (const item of (0, paginate_js_1.paginateQuery)({
+        retry: (0, retry_js_1.retryFor)(context, read.signal),
+        signal: read.signal,
+        client: context.client,
+        params,
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        const row = (0, rows_js_1.parseWriteRow)(item);
+        if (row === undefined) {
+            context.logger.warn('getTuple: skipped a row that is not a pending-write item', {
+                sortKey: (0, truncate_js_1.truncateForLog)(item.SK),
+            });
+            continue;
+        }
+        items.push(row);
+    }
+    if (items.length >= paginate_js_1.LIST_SCAN_WARN_THRESHOLD) {
+        context.logger.warn('getTuple: a checkpoint carries very many pending-write rows; the read is complete but slow', {
+            threadId: at.threadId,
+            checkpointId: at.checkpointId,
+            rows: items.length,
+        });
+    }
+    return (0, rows_js_1.toPendingWrites)(context, items, at.threadId, read.signal);
+}
+function configFor(threadId, checkpointNs, checkpointId) {
+    return {
+        configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId },
+    };
+}
+async function assembleTuple(context, thread, meta, options) {
+    const read = { signal: options.signal, consistent: options.consistent };
+    const at = { ...thread, checkpointId: meta.checkpointId };
+    const payload = await fetchPayload(context, at, read);
+    if (!payload)
+        return undefined;
+    const [checkpoint, metadata, pendingWrites] = await Promise.all([
+        (0, rows_js_1.readCheckpoint)(context, payload, thread.threadId, options.signal).then((stored) => migratePendingSends(context, stored, { ...thread, parentCheckpointId: meta.parentCheckpointId }, read)),
+        options.metadata ?? (0, rows_js_1.readMetadata)(context, meta, thread.threadId, options.signal),
+        fetchPendingWrites(context, at, read),
+    ]);
+    const tuple = {
+        config: configFor(thread.threadId, thread.checkpointNs, meta.checkpointId),
+        checkpoint,
+        metadata,
+        pendingWrites,
+    };
+    if (meta.parentCheckpointId !== undefined) {
+        tuple.parentConfig = configFor(thread.threadId, thread.checkpointNs, meta.parentCheckpointId);
+    }
+    return tuple;
+}
+async function migratePendingSends(context, checkpoint, parent, read) {
+    if (checkpoint.v >= 4 || parent.parentCheckpointId === undefined)
+        return checkpoint;
+    const writes = await fetchPendingWrites(context, {
+        threadId: parent.threadId,
+        checkpointNs: parent.checkpointNs,
+        checkpointId: parent.parentCheckpointId,
+    }, read);
+    const sends = writes.filter(([, channel]) => channel === langgraph_checkpoint_1.TASKS).map(([, , value]) => value);
+    const versions = Object.values(checkpoint.channel_versions);
+    return {
+        ...checkpoint,
+        channel_values: { ...checkpoint.channel_values, [langgraph_checkpoint_1.TASKS]: sends },
+        channel_versions: {
+            ...checkpoint.channel_versions,
+            [langgraph_checkpoint_1.TASKS]: versions.length > 0 ? (0, langgraph_checkpoint_1.maxChannelVersion)(...versions) : 1,
+        },
+    };
+}