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

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

@@ -0,0 +1,356 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_ENCODABLE_WRITE_INDEX = exports.WRITE_GROUP_ATTRIBUTE = void 0;
+exports.checkpointerPartitionPrefix = checkpointerPartitionPrefix;
+exports.partitionKey = partitionKey;
+exports.metaSortKey = metaSortKey;
+exports.metaSortKeyPrefix = metaSortKeyPrefix;
+exports.metaAnyNamespacePrefix = metaAnyNamespacePrefix;
+exports.payloadSortKey = payloadSortKey;
+exports.writeSortKey = writeSortKey;
+exports.writeSortKeyBytes = writeSortKeyBytes;
+exports.isCheckpointerSortKey = isCheckpointerSortKey;
+exports.writeSortKeyPrefix = writeSortKeyPrefix;
+exports.metaRowKey = metaRowKey;
+exports.payloadRowKey = payloadRowKey;
+exports.partitionQuery = partitionQuery;
+exports.beginsWithQuery = beginsWithQuery;
+exports.buildCheckpointRows = buildCheckpointRows;
+exports.buildWriteRows = buildWriteRows;
+exports.parseMetaRow = parseMetaRow;
+exports.parseWriteRow = parseWriteRow;
+exports.parseHeadRow = parseHeadRow;
+exports.readCheckpoint = readCheckpoint;
+exports.readMetadata = readMetadata;
+exports.compareByCodePoint = compareByCodePoint;
+exports.compareWriteOrder = compareWriteOrder;
+exports.toPendingWrites = toPendingWrites;
+exports.resolveWriteIndices = resolveWriteIndices;
+exports.dropSupersededWrites = dropSupersededWrites;
+exports.checkpointRowDescriptors = checkpointRowDescriptors;
+exports.checkpointRowUnit = checkpointRowUnit;
+exports.checkpointRowKind = checkpointRowKind;
+exports.checkpointIndexTarget = checkpointIndexTarget;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const clock_js_1 = require("../../shared/clock.js");
+const codec_js_1 = require("../../shared/codec/codec.js");
+const offloader_js_1 = require("../../shared/codec/s3/offloader.js");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const partition_delete_js_1 = require("../../shared/dynamodb/partition-delete.js");
+const recency_index_js_1 = require("../../shared/dynamodb/recency-index.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const ulid_js_1 = require("../../shared/ulid.js");
+exports.WRITE_GROUP_ATTRIBUTE = 'writeGroup';
+const WRITE_INDEX_PAD_WIDTH = 10;
+const WRITE_INDEX_OFFSET = 8;
+exports.MIN_ENCODABLE_WRITE_INDEX = -WRITE_INDEX_OFFSET;
+var CheckpointRowKind;
+(function (CheckpointRowKind) {
+    CheckpointRowKind["META"] = "META";
+    CheckpointRowKind["PAYLOAD"] = "PAYLOAD";
+    CheckpointRowKind["WRITE"] = "WRITE";
+})(CheckpointRowKind || (CheckpointRowKind = {}));
+const ADAPTER_PARTITION_PREFIX = `${table_schema_js_1.ADAPTER_TAGS.checkpointer}${table_schema_js_1.KEY_SEPARATOR}`;
+function checkpointerPartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+function partitionKey(threadId) {
+    return `${ADAPTER_PARTITION_PREFIX}${threadId}`;
+}
+function metaSortKey(checkpointNs, checkpointId) {
+    return `${CheckpointRowKind.META}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}${checkpointId}`;
+}
+function metaSortKeyPrefix(checkpointNs) {
+    return `${CheckpointRowKind.META}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}`;
+}
+function metaAnyNamespacePrefix() {
+    return `${CheckpointRowKind.META}${table_schema_js_1.KEY_SEPARATOR}`;
+}
+function payloadSortKey(checkpointNs, checkpointId) {
+    return `${CheckpointRowKind.PAYLOAD}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}${checkpointId}`;
+}
+function writeSortKey(at) {
+    const offsetIndex = at.index + WRITE_INDEX_OFFSET;
+    if (!Number.isInteger(offsetIndex) ||
+        offsetIndex < 0 ||
+        offsetIndex.toString().length > WRITE_INDEX_PAD_WIDTH) {
+        throw (0, errors_js_1.validationError)(`write index ${at.index} is not an integer encodable at offset ${WRITE_INDEX_OFFSET} ` +
+            `with ${WRITE_INDEX_PAD_WIDTH} digits`, 'index');
+    }
+    const paddedIndex = offsetIndex.toString().padStart(WRITE_INDEX_PAD_WIDTH, '0');
+    return [
+        CheckpointRowKind.WRITE,
+        at.checkpointNs,
+        at.checkpointId,
+        at.taskId,
+        paddedIndex,
+        at.channel,
+    ].join(table_schema_js_1.KEY_SEPARATOR);
+}
+function writeSortKeyBytes(at) {
+    return Buffer.byteLength(writeSortKey({ ...at, index: 0 }), 'utf8');
+}
+function isCheckpointerSortKey(sortKey) {
+    return Object.values(CheckpointRowKind).some((kind) => sortKey.startsWith(`${kind}${table_schema_js_1.KEY_SEPARATOR}`));
+}
+function writeSortKeyPrefix(checkpointNs, checkpointId) {
+    return `${CheckpointRowKind.WRITE}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}${checkpointId}${table_schema_js_1.KEY_SEPARATOR}`;
+}
+function metaRowKey(at) {
+    return { PK: partitionKey(at.threadId), SK: metaSortKey(at.checkpointNs, at.checkpointId) };
+}
+function payloadRowKey(at) {
+    return { PK: partitionKey(at.threadId), SK: payloadSortKey(at.checkpointNs, at.checkpointId) };
+}
+function partitionQuery(tableName, partition, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': partition },
+    };
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+function beginsWithQuery(tableName, partition, skPrefix, options = {}) {
+    const bounded = options.beforeSortKey !== undefined;
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: bounded
+            ? '#pk = :pk AND #sk BETWEEN :skPrefix AND :before'
+            : '#pk = :pk AND begins_with(#sk, :skPrefix)',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_js_1.SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: {
+            ':pk': partition,
+            ':skPrefix': skPrefix,
+            ...(bounded ? { ':before': options.beforeSortKey } : {}),
+        },
+        ScanIndexForward: options.ascending ?? false,
+    };
+    if (options.limit !== undefined && options.limit >= 1)
+        params.Limit = options.limit;
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+function withTtl(item, ttlTimestamp) {
+    if (ttlTimestamp !== undefined)
+        item.ttl = ttlTimestamp;
+    return item;
+}
+async function releaseUploads(context, uploaded, operation) {
+    if (!context.offloader)
+        return;
+    await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+        keys: (0, codec_js_1.collectS3Keys)(uploaded),
+        operation,
+        logger: context.logger,
+    });
+}
+const nextPutObjectId = (0, ulid_js_1.createUlidFactory)();
+async function buildCheckpointRows(context, request, ttlTimestamp) {
+    const { threadId, checkpointNs, checkpointId } = request.address;
+    const deps = (0, codec_js_1.codecDepsOf)(context, request.signal);
+    const pk = partitionKey(threadId);
+    const objectId = nextPutObjectId();
+    const checkpointDescriptor = await (0, codec_js_1.encodePayload)(request.checkpoint, deps, {
+        keyParts: [threadId, checkpointNs, checkpointId, 'checkpoint'],
+        objectId,
+        row: { pk, sk: payloadSortKey(checkpointNs, checkpointId) },
+    });
+    let metadataDescriptor;
+    try {
+        metadataDescriptor = await (0, codec_js_1.encodePayload)(request.metadata, deps, {
+            keyParts: [threadId, checkpointNs, checkpointId, 'metadata'],
+            objectId,
+            row: { pk, sk: metaSortKey(checkpointNs, checkpointId) },
+        });
+    }
+    catch (error) {
+        await releaseUploads(context, [checkpointDescriptor], 'put.encode');
+        throw error;
+    }
+    const index = (0, recency_index_js_1.indexKeys)('CHKPT', checkpointId, (0, clock_js_1.nowIso)(), context.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS);
+    const meta = {
+        PK: pk,
+        SK: metaSortKey(checkpointNs, checkpointId),
+        v: table_schema_js_1.ROW_FORMAT_VERSION,
+        ...index,
+        threadId,
+        checkpointNs,
+        checkpointId,
+        metadata: metadataDescriptor,
+    };
+    if (request.parentCheckpointId !== undefined)
+        meta.parentCheckpointId = request.parentCheckpointId;
+    const payload = {
+        PK: pk,
+        SK: payloadSortKey(checkpointNs, checkpointId),
+        v: table_schema_js_1.ROW_FORMAT_VERSION,
+        checkpoint: checkpointDescriptor,
+    };
+    return { meta: withTtl(meta, ttlTimestamp), payload: withTtl(payload, ttlTimestamp) };
+}
+async function buildWriteRows(context, request, writeGroup, ttlTimestamp) {
+    const { threadId, checkpointNs, checkpointId } = request.address;
+    const { taskId, taskPath } = request;
+    const deps = (0, codec_js_1.codecDepsOf)(context, request.signal);
+    const pk = partitionKey(threadId);
+    const items = [];
+    try {
+        for (const { channel, value, index, occurrence } of resolveWriteIndices(request.writes)) {
+            const sk = writeSortKey({ checkpointNs, checkpointId, taskId, index, channel });
+            const descriptor = await (0, codec_js_1.encodePayload)(value, deps, {
+                keyParts: [threadId, checkpointNs, checkpointId, taskId, `write-${index}`, channel],
+                objectId: writeGroup,
+                row: { pk, sk },
+            });
+            const item = {
+                PK: pk,
+                SK: sk,
+                v: table_schema_js_1.ROW_FORMAT_VERSION,
+                taskId,
+                index,
+                channel,
+                ...(taskPath === undefined ? {} : { taskPath }),
+                writeGroup,
+                occurrence,
+                value: descriptor,
+            };
+            items.push(withTtl(item, ttlTimestamp));
+        }
+    }
+    catch (error) {
+        await releaseUploads(context, items.map((item) => item.value), 'putWrites.encode');
+        throw error;
+    }
+    return items;
+}
+function parseMetaRow(raw) {
+    (0, table_schema_js_1.assertReadableRow)(raw, 'checkpoint');
+    const isCheckpoint = typeof raw.threadId === 'string' &&
+        typeof raw.checkpointId === 'string' &&
+        typeof raw.checkpointNs === 'string' &&
+        typeof raw.metadata === 'object' &&
+        raw.metadata !== null;
+    if (!isCheckpoint)
+        return undefined;
+    const item = raw;
+    const consistent = item.PK === partitionKey(item.threadId) &&
+        item.SK === metaSortKey(item.checkpointNs, item.checkpointId);
+    return consistent ? item : undefined;
+}
+function parseWriteRow(raw) {
+    (0, table_schema_js_1.assertReadableRow)(raw, 'pending write');
+    const isWrite = typeof raw.taskId === 'string' &&
+        typeof raw.channel === 'string' &&
+        (raw.taskPath === undefined || typeof raw.taskPath === 'string') &&
+        typeof raw.value === 'object' &&
+        raw.value !== null;
+    return isWrite ? raw : undefined;
+}
+function parseHeadRow(context, raw, reader) {
+    if (raw === undefined)
+        return undefined;
+    const meta = parseMetaRow(raw);
+    if (!meta) {
+        context.logger.warn(`${reader}: skipped a row that is not a checkpoint meta item`, {
+            sortKey: (0, truncate_js_1.truncateForLog)(raw.SK),
+        });
+    }
+    return meta;
+}
+async function readCheckpoint(context, item, threadId, signal) {
+    return (0, codec_js_1.decodePayload)(item.checkpoint, (0, codec_js_1.codecDepsOf)(context, signal), [threadId]);
+}
+async function readMetadata(context, item, threadId, signal) {
+    return (0, codec_js_1.decodePayload)(item.metadata, (0, codec_js_1.codecDepsOf)(context, signal), [threadId]);
+}
+function compareByCodePoint(a, b) {
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        const left = a.codePointAt(i);
+        const right = b.codePointAt(j);
+        if (left !== right)
+            return left < right ? -1 : 1;
+        i += left > 0xffff ? 2 : 1;
+        j += right > 0xffff ? 2 : 1;
+    }
+    if (i >= a.length && j >= b.length)
+        return 0;
+    return i >= a.length ? -1 : 1;
+}
+function compareWriteOrder(a, b) {
+    return (compareByCodePoint(a.taskPath ?? '', b.taskPath ?? '') ||
+        compareByCodePoint(a.taskId, b.taskId) ||
+        a.index - b.index ||
+        compareByCodePoint(a.channel, b.channel));
+}
+async function toPendingWrites(context, items, threadId, signal) {
+    const deps = (0, codec_js_1.codecDepsOf)(context, signal);
+    const live = [...dropSupersededWrites(items)].sort(compareWriteOrder);
+    const values = await (0, concurrency_js_1.mapWithConcurrency)(live, context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY, (item) => (0, codec_js_1.decodePayload)(item.value, deps, [threadId]));
+    return live.map((item, index) => [
+        item.taskId,
+        item.channel,
+        values[index],
+    ]);
+}
+function resolveWriteIndices(writes) {
+    const bySpecialIndex = new Map();
+    const regular = [];
+    const occurrences = new Map();
+    writes.forEach(([channel, value], positional) => {
+        if (Object.hasOwn(langgraph_checkpoint_1.WRITES_IDX_MAP, channel)) {
+            const index = langgraph_checkpoint_1.WRITES_IDX_MAP[channel];
+            bySpecialIndex.set(index, { channel, value, index, occurrence: 0 });
+            return;
+        }
+        const occurrence = occurrences.get(channel) ?? 0;
+        occurrences.set(channel, occurrence + 1);
+        regular.push({ channel, value, index: positional, occurrence });
+    });
+    return [...bySpecialIndex.values(), ...regular];
+}
+function dropSupersededWrites(items) {
+    const identity = (item) => JSON.stringify([item.taskId, item.channel, item.occurrence ?? 0]);
+    const groupOf = (item) => item.writeGroup ?? '';
+    const earliestGroup = new Map();
+    for (const item of items) {
+        const id = identity(item);
+        const seen = earliestGroup.get(id);
+        const group = groupOf(item);
+        if (seen === undefined || group < seen)
+            earliestGroup.set(id, group);
+    }
+    return items.filter((item) => earliestGroup.get(identity(item)) === groupOf(item));
+}
+const PAYLOAD_ATTRIBUTES = ['metadata', 'checkpoint', 'value'];
+function checkpointRowDescriptors(row) {
+    const named = [];
+    for (const attribute of PAYLOAD_ATTRIBUTES) {
+        const entry = (0, partition_delete_js_1.namedDescriptor)(row, attribute);
+        if (entry !== undefined)
+            named.push(entry);
+    }
+    return named;
+}
+function checkpointRowUnit(row) {
+    return row.SK.split(table_schema_js_1.KEY_SEPARATOR).slice(1, 3).join(table_schema_js_1.KEY_SEPARATOR);
+}
+function checkpointRowKind(row) {
+    return row.SK.split(table_schema_js_1.KEY_SEPARATOR)[0];
+}
+function checkpointIndexTarget(row) {
+    const pk = typeof row.PK === 'string' ? row.PK : '';
+    const sk = typeof row.SK === 'string' ? row.SK : '';
+    if (!pk.startsWith(ADAPTER_PARTITION_PREFIX))
+        return undefined;
+    return sk.startsWith(metaAnyNamespacePrefix()) && typeof row.checkpointId === 'string'
+        ? { tag: 'CHKPT', id: row.checkpointId, at: recency_index_js_1.BACKFILLED_AT }
+        : undefined;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Hides which options the saver accepts, and how the saver is assembled from
+ * them.
+ *
+ * The exhaustive key list of the constructor's options lives here,
+ * compiler-checked against its type, beside the code that resolves those
+ * options into the context every action receives. `list`'s and
+ * `getDeltaChannelHistory`'s options have no list: LangGraph defines them, so
+ * a key it adds is ignored rather than refused (decision record 28).
+ */
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter.js';
+import type { DynamoDBSaverOptions } from '../types.js';
+/**
+ * The keys of the saver's constructor options, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so the list
+ * cannot rot away from the type it guards. It lives with the feature because
+ * the type it is checked against does; `shared/` knows no feature.
+ */
+export declare const SAVER_KEYS: readonly string[];
+/** Resolved collaborators shared by every checkpointer action. */
+export interface CheckpointerContext extends AdapterCore {
+    serde: SerializerProtocol;
+}
+/** Result of wiring up a checkpointer from its options. */
+export interface CheckpointerSetup {
+    context: CheckpointerContext;
+    shell: AdapterShell;
+}
+/**
+ * Check the options, then resolve the client, offloader and serializer.
+ *
+ * Accepts: `options` — already held to the saver's key list by its constructor,
+ * which must read `serde` before anything else runs; checked here before
+ * anything is built, so no half-built saver exists when one is wrong. `serde` —
+ * the serializer the base class resolved, which is the caller's own serializer
+ * when they gave one.
+ *
+ * Returns: the context every action receives, and the shell that releases what
+ * it holds — a client the caller passed in is never destroyed by `destroy()`.
+ *
+ * Throws: `VALIDATION` for an option or collaborator that fails a check,
+ * naming the offending option.
+ *
+ * Guarantees: constructing a saver performs no I/O.
+ */
+export declare function setUpCheckpointer(options: DynamoDBSaverOptions, serde: SerializerProtocol): CheckpointerSetup;

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAVER_KEYS = void 0;
+exports.setUpCheckpointer = setUpCheckpointer;
+const adapter_js_1 = require("../../shared/adapter.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+exports.SAVER_KEYS = (0, option_shape_js_1.allKeysOf)({
+    tableName: 'tableName',
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    ttl: 'ttl',
+    logger: 'logger',
+    retry: 'retry',
+    indexShards: 'indexShards',
+    indexName: 'indexName',
+    readConcurrency: 'readConcurrency',
+    compression: 'compression',
+    s3: 's3',
+    serde: 'serde',
+});
+function setUpCheckpointer(options, serde) {
+    const shell = (0, adapter_js_1.openAdapter)(options, 'checkpointer');
+    return { shell, context: { ...shell.core, serde } };
+}