@farukada/aws-langgraph-dynamodb-ts 0.2.2 → 0.3.0

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

@@ -1,85 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.putWritesAction = void 0;
-const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
-const shared_1 = require("../../shared");
-const utils_1 = require("../utils");
-const validate_configurable_1 = require("./validate-configurable");
-const writer_1 = require("./writer");
+exports.putWrites = putWrites;
+const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
+const orphans_1 = require("../../shared/codec/s3/orphans");
+const batch_write_1 = require("../../shared/dynamodb/batch-write");
+const errors_1 = require("../../shared/errors/errors");
+const ttl_1 = require("../../shared/validation/ttl");
+const configurable_1 = require("../internal/configurable");
+const item_writer_1 = require("../internal/item-writer");
+const validation_1 = require("../internal/validation");
 /**
- * Save pending writes to DynamoDB
- *
- * @param params - Parameters for the put writes operation
- * @throws Error if validation fails or operation fails
+ * 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.
  */
-const putWritesAction = async (params) => {
-    const { thread_id, checkpoint_ns, checkpoint_id } = (0, validate_configurable_1.validateConfigurable)(params.config.configurable);
-    if (checkpoint_id == null) {
-        throw new Error('Missing checkpoint_id');
+async function putWrites(context, config, writes, taskId) {
+    (0, validation_1.validateTaskId)(taskId);
+    const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
+    if (checkpointId === undefined) {
+        throw new errors_1.ValidationError('checkpoint_id is required to store writes', 'checkpoint_id');
     }
-    // Validate inputs
-    (0, utils_1.validateWritesCount)(params.writes.length);
-    (0, utils_1.validateTaskId)(params.taskId);
-    (0, utils_1.validateTTLDays)(params.ttlDays);
-    // Compute TTL once (ttlSeconds takes precedence) — not per message.
-    let ttl;
-    if (params.ttlSeconds !== undefined) {
-        ttl = (0, shared_1.calculateTTLTimestampFromSeconds)(params.ttlSeconds);
-    }
-    else if (params.ttlDays !== undefined) {
-        ttl = (0, shared_1.calculateTTLTimestamp)(params.ttlDays);
-    }
-    const writeItems = await Promise.all(params.writes.map(async (write, positionalIdx) => {
-        const [type, rawValue] = await params.serde.dumpsTyped(write[1]);
-        // Compress after serialization if compressor is provided
-        const serializedValue = params.compressor
-            ? await params.compressor.compress(rawValue)
-            : rawValue;
-        // Special channels (__error__, __scheduled__, __interrupt__, __resume__) are
-        // stored at the stable negative idx from WRITES_IDX_MAP so repeated writes
-        // for the same taskId overwrite the correct dedicated slot. Regular writes
-        // use their positional index. Matches memory.js:178 from langgraph-checkpoint.
-        const channel = write[0];
-        const idx = langgraph_checkpoint_1.WRITES_IDX_MAP[channel] ?? positionalIdx;
-        // S3 offloading for large write values
-        let s3ValueKey;
-        let storedValue = serializedValue;
-        if (params.s3Offloader && params.s3Offloader.shouldOffload(serializedValue)) {
-            s3ValueKey = await params.s3Offloader.upload(params.s3Offloader.buildKey(thread_id, checkpoint_id, `write-${idx}`), serializedValue);
-            storedValue = new Uint8Array(0); // Empty placeholder in DynamoDB
-        }
-        const item = new writer_1.Writer({
-            thread_id,
-            checkpoint_ns,
-            checkpoint_id,
-            task_id: params.taskId,
-            idx,
-            channel,
-            type,
-            value: storedValue,
-        });
-        const dynamoItem = item.toDynamoDBItem();
-        if (s3ValueKey)
-            dynamoItem.s3_value_key = s3ValueKey;
-        if (ttl !== undefined)
-            dynamoItem.ttl = ttl;
-        return { PutRequest: { Item: dynamoItem } };
-    }));
-    // Batch writes using shared utility with retry logic.
-    // On failure, best-effort-clean any S3 objects we uploaded — errors during cleanup
-    // are only logged since the lifecycle rule is the ultimate backstop.
+    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, ttlTimestamp);
     try {
-        await (0, shared_1.batchWriteAllWithRetry)(params.client, params.writesTableName, writeItems, {
-            signal: params.signal,
-        });
+        await (0, batch_write_1.batchWriteAll)(context.client, context.tableName, items.map((item) => ({ PutRequest: { Item: item } })));
     }
-    catch (err) {
-        if (params.s3Offloader) {
-            const keys = writeItems.map((w) => w.PutRequest.Item.s3_value_key);
-            await (0, shared_1.cleanUpS3Orphans)(params.s3Offloader, keys, 'putWrites failure');
+    catch (error) {
+        if (context.offloader) {
+            await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(items.map((item) => item.value)), 'putWrites', context.logger);
         }
-        throw err;
+        throw error;
     }
-};
-exports.putWritesAction = putWritesAction;
+}
 //# sourceMappingURL=put-writes.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"put-writes.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/put-writes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"put-writes.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/put-writes.ts"],"names":[],"mappings":";;AAiBA,8BAuCC;AArDD,wEAAmE;AACnE,2DAAiE;AACjE,mEAAkE;AAClE,uDAA6D;AAC7D,qDAAoE;AACpE,2DAA4D;AAC5D,yDAA0D;AAE1D,uDAAwD;AAExD;;;GAGG;AACI,KAAK,UAAU,SAAS,CAC7B,OAA4B,EAC5B,MAAsB,EACtB,MAAsB,EACtB,MAAc;IAEd,IAAA,2BAAc,EAAC,MAAM,CAAC,CAAC;IACvB,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,IAAA,+BAAgB,EAAC,MAAM,CAAC,CAAC;IAC1E,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,wBAAe,CAAC,2CAA2C,EAAE,eAAe,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAChC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAA,2BAAqB,EAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,MAAM,KAAK,GAAG,MAAM,IAAA,6BAAe,EACjC,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,MAAM,EACN,YAAY,CACb,CAAC;IACF,IAAI,CAAC;QACH,MAAM,IAAA,2BAAa,EACjB,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,EACjB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CACtD,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,IAAA,0BAAgB,EACpB,OAAO,CAAC,SAAS,EACjB,IAAA,+BAAa,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAC9C,WAAW,EACX,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

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

@@ -1,15 +1,10 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
-import { type PutActionParams } from '../types';
+import type { Checkpoint, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup';
 /**
- * Save a checkpoint to DynamoDB as two items:
- * 1. Metadata item (SK = checkpoint_id) — lightweight, queried by list()
- * 2. Payload item  (SK = PAYLOAD#checkpoint_id) — heavy blob, fetched only by getTuple()
- *
- * Both items are written atomically via transactWrite.
- *
- * @param params - Parameters for the put operation
- * @returns RunnableConfig with the saved checkpoint information
- * @throws Error if validation fails or operation fails
+ * 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.
  */
-export declare const putAction: (params: PutActionParams) => Promise<RunnableConfig>;
+export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
 //# sourceMappingURL=put.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"put.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/put.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAQhE,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GAAU,QAAQ,eAAe,KAAG,OAAO,CAAC,cAAc,CAmL/E,CAAC"}
+{"version":3,"file":"put.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/put.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAQtF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAuCzB"}

package/dist/checkpointer/actions/put.js

@@ -1,173 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.putAction = void 0;
-const shared_1 = require("../../shared");
-const types_1 = require("../types");
-const utils_1 = require("../utils");
-const validate_configurable_1 = require("./validate-configurable");
+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 ttl_1 = require("../../shared/validation/ttl");
+const configurable_1 = require("../internal/configurable");
+const item_writer_1 = require("../internal/item-writer");
 /**
- * Save a checkpoint to DynamoDB as two items:
- * 1. Metadata item (SK = checkpoint_id) — lightweight, queried by list()
- * 2. Payload item  (SK = PAYLOAD#checkpoint_id) — heavy blob, fetched only by getTuple()
- *
- * Both items are written atomically via transactWrite.
- *
- * @param params - Parameters for the put operation
- * @returns RunnableConfig with the saved checkpoint information
- * @throws Error if validation fails or operation fails
+ * 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.
  */
-const putAction = async (params) => {
-    const { thread_id } = (0, validate_configurable_1.validateConfigurable)(params.config.configurable);
-    // Validate checkpoint.id exists and is valid
-    if (!params.checkpoint.id) {
-        throw new Error('Checkpoint ID is required');
-    }
-    (0, utils_1.validateCheckpointId)(params.checkpoint.id, true);
-    (0, utils_1.validateTTLDays)(params.ttlDays);
-    const [type1, rawCheckpoint] = await params.serde.dumpsTyped(params.checkpoint);
-    const [type2, rawMetadata] = await params.serde.dumpsTyped(params.metadata);
-    if (type1 !== type2) {
-        throw new Error('Failed to serialize checkpoint and metadata to the same type.');
-    }
-    // Compress after serialization if compressor is provided
-    const serializedCheckpoint = params.compressor
-        ? await params.compressor.compress(rawCheckpoint)
-        : rawCheckpoint;
-    const serializedMetadata = params.compressor
-        ? await params.compressor.compress(rawMetadata)
-        : rawMetadata;
-    // S3 offloading for large payloads
-    let s3CheckpointKey;
-    let s3MetadataKey;
-    let storedCheckpoint = serializedCheckpoint;
-    let storedMetadata = serializedMetadata;
-    if (params.s3Offloader) {
-        const checkpointId = params.checkpoint.id;
-        if (params.s3Offloader.shouldOffload(serializedCheckpoint)) {
-            s3CheckpointKey = await params.s3Offloader.upload(params.s3Offloader.buildKey(thread_id, checkpointId, 'checkpoint'), serializedCheckpoint);
-            storedCheckpoint = new Uint8Array(0); // Empty placeholder in DynamoDB
-        }
-        if (params.s3Offloader.shouldOffload(serializedMetadata)) {
-            s3MetadataKey = await params.s3Offloader.upload(params.s3Offloader.buildKey(thread_id, checkpointId, 'metadata'), serializedMetadata);
-            storedMetadata = new Uint8Array(0); // Empty placeholder in DynamoDB
-        }
-    }
-    // Compute TTL once for both items
-    let ttl;
-    if (params.ttlSeconds !== undefined) {
-        ttl = (0, shared_1.calculateTTLTimestampFromSeconds)(params.ttlSeconds);
-    }
-    else if (params.ttlDays !== undefined) {
-        ttl = (0, shared_1.calculateTTLTimestamp)(params.ttlDays);
-    }
-    const checkpointNs = params.config.configurable?.checkpoint_ns ?? '';
-    const checkpointId = params.checkpoint.id;
-    // Metadata item — lightweight, read by list() queries
-    const metadataItem = {
-        thread_id,
-        checkpoint_ns: checkpointNs,
-        checkpoint_id: checkpointId,
-        parent_checkpoint_id: params.config.configurable?.checkpoint_id,
-        type: type1,
-        metadata: storedMetadata,
-        s3_checkpoint_key: s3CheckpointKey,
-        s3_metadata_key: s3MetadataKey,
-    };
-    if (ttl !== undefined) {
-        metadataItem.ttl = ttl;
-    }
-    // Payload item — heavy blob, fetched only by getTuple()
-    const payloadItem = {
-        thread_id,
-        checkpoint_id: `${types_1.PAYLOAD_SK_PREFIX}${checkpointId}`,
-        checkpoint: storedCheckpoint,
-    };
-    if (ttl !== undefined) {
-        payloadItem.ttl = ttl;
-    }
-    // Optimistic-concurrency guard on the metadata Put.
-    //
-    // Two concurrent workers racing on the same (thread_id, checkpoint_id) with
-    // *different* parent/type (= divergent lineage) is a bug we want to surface,
-    // not silently resolve last-writer-wins. Two writers agreeing on parent+type
-    // (= legitimate idempotent retry after a transient error) must still succeed.
-    //
-    //   attribute_not_exists(checkpoint_id)                 -- first write ever: OK
-    //   OR (#type = :expected_type AND (                     -- OR same content as prior:
-    //         attribute_not_exists(parent_checkpoint_id)     --    initial checkpoint
-    //         OR parent_checkpoint_id = :expected_parent     --    with named parent
-    //       ))
-    //
-    // The payload Put is left unconditional: payloads are keyed by PAYLOAD#<id>
-    // and contain content-for-content equal data for a given checkpoint, so an
-    // overwrite on retry is always safe.
-    // Normalize `''` to `undefined` so an empty-string parent and an unset parent
-    // are treated as the same "no parent" state. This keeps the ConditionExpression
-    // stable across idempotent retries that might represent "initial checkpoint"
-    // either way (e.g. a migration or a caller that stringifies nulls).
-    const rawExpectedParent = params.config.configurable?.checkpoint_id;
-    const expectedParent = typeof rawExpectedParent === 'string' && rawExpectedParent.length > 0
-        ? rawExpectedParent
-        : undefined;
-    const metadataExpressionAttributeNames = { '#type': 'type' };
-    const metadataExpressionAttributeValues = {
-        ':expected_type': type1,
-    };
-    const parentClause = expectedParent !== undefined
-        ? 'parent_checkpoint_id = :expected_parent'
-        : 'attribute_not_exists(parent_checkpoint_id)';
-    if (expectedParent !== undefined) {
-        metadataExpressionAttributeValues[':expected_parent'] = expectedParent;
-    }
-    const metadataConditionExpression = 'attribute_not_exists(checkpoint_id) ' + `OR (#type = :expected_type AND (${parentClause}))`;
-    // Atomic write: both items must succeed or both fail.
-    // On failure, best-effort-clean any S3 objects we uploaded so they don't linger
-    // until the lifecycle rule sweeps them. Errors during cleanup are only logged.
+async function putCheckpoint(context, config, checkpoint, metadata) {
+    const { threadId, checkpointNs, checkpointId: parentCheckpointId } = (0, configurable_1.readConfigurable)(config);
+    const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
+    const { meta, payload } = await (0, item_writer_1.buildCheckpointItems)(context, threadId, checkpointNs, checkpoint, metadata, parentCheckpointId, ttlTimestamp);
     try {
-        await (0, shared_1.withDynamoDBRetry)(async () => {
-            await params.client.transactWrite({
-                TransactItems: [
-                    {
-                        Put: {
-                            TableName: params.checkpointsTableName,
-                            Item: metadataItem,
-                            ConditionExpression: metadataConditionExpression,
-                            ExpressionAttributeNames: metadataExpressionAttributeNames,
-                            ExpressionAttributeValues: metadataExpressionAttributeValues,
-                        },
-                    },
-                    { Put: { TableName: params.checkpointsTableName, Item: payloadItem } },
-                ],
-            });
-        }, { signal: params.signal });
-    }
-    catch (err) {
-        // Skip S3 orphan cleanup on the optimistic-lock conflict path. S3 keys are
-        // derived deterministically from (thread_id, checkpoint_id), so a divergent
-        // put() on the same checkpoint_id uploads to the *same* keys as the
-        // canonical write already occupies — cleaning them up after a
-        // ConditionalCheckFailed would delete live data still referenced by the
-        // winning transaction. The S3 lifecycle rule is the safe backstop for the
-        // rare case where an overwrite did occur; data integrity beats a few stale
-        // bytes in S3.
-        const isConditionalFailure = err &&
-            typeof err === 'object' &&
-            ('name' in err
-                ? err.name === 'ConditionalCheckFailedException' ||
-                    err.name === 'TransactionCanceledException'
-                : false);
-        if (params.s3Offloader && !isConditionalFailure) {
-            await (0, shared_1.cleanUpS3Orphans)(params.s3Offloader, [s3CheckpointKey, s3MetadataKey], 'put failure');
+        await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite({
+            TransactItems: [
+                { Put: { TableName: context.tableName, Item: meta } },
+                { Put: { TableName: context.tableName, Item: payload } },
+            ],
+        }));
+    }
+    catch (error) {
+        if (context.offloader) {
+            await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([meta.metadata, payload.checkpoint]), 'put', context.logger);
         }
-        throw err;
+        throw error;
     }
     return {
         configurable: {
-            thread_id: metadataItem.thread_id,
-            checkpoint_ns: metadataItem.checkpoint_ns,
-            checkpoint_id: metadataItem.checkpoint_id,
+            thread_id: threadId,
+            checkpoint_ns: checkpointNs,
+            checkpoint_id: checkpoint.id,
         },
     };
-};
-exports.putAction = putAction;
+}
 //# sourceMappingURL=put.js.map

package/dist/checkpointer/actions/put.js.map

@@ -1 +1 @@
-{"version":3,"file":"put.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/put.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"put.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/put.ts"],"names":[],"mappings":";;AAgBA,sCA4CC;AAzDD,wEAAmE;AACnE,2DAAiE;AACjE,uDAAgE;AAChE,qDAAoE;AACpE,2DAA4D;AAC5D,yDAA+D;AAG/D;;;;GAIG;AACI,KAAK,UAAU,aAAa,CACjC,OAA4B,EAC5B,MAAsB,EACtB,UAAsB,EACtB,QAA4B;IAE5B,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,GAAG,IAAA,+BAAgB,EAAC,MAAM,CAAC,CAAC;IAC9F,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAA,2BAAqB,EAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,IAAA,kCAAoB,EAClD,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,kBAAkB,EAClB,YAAY,CACb,CAAC;IACF,IAAI,CAAC;QACH,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC3B,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC;YAC3B,aAAa,EAAE;gBACb,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;gBACrD,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;aACzD;SACF,CAAC,CACH,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,IAAA,0BAAgB,EACpB,OAAO,CAAC,SAAS,EACjB,IAAA,+BAAa,EAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,EAClD,KAAK,EACL,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO;QACL,YAAY,EAAE;YACZ,SAAS,EAAE,QAAQ;YACnB,aAAa,EAAE,YAAY;YAC3B,aAAa,EAAE,UAAU,CAAC,EAAE;SAC7B;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,10 @@
+import type { CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { CheckpointMetaItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/**
+ * 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): Promise<CheckpointTuple | undefined>;
+//# sourceMappingURL=assemble.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/assemble.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AASnD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAkBtC"}

package/dist/checkpointer/internal/assemble.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleTuple = assembleTuple;
+const fetch_1 = require("./fetch");
+const item_reader_1 = require("./item-reader");
+/** 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) {
+    const payload = await (0, fetch_1.fetchPayload)(context, threadId, checkpointNs, meta.checkpointId);
+    if (!payload)
+        return undefined;
+    const [checkpoint, metadata, pendingWrites] = await Promise.all([
+        (0, item_reader_1.readCheckpoint)(context, payload),
+        (0, item_reader_1.readMetadata)(context, meta),
+        (0, fetch_1.fetchPendingWrites)(context, threadId, checkpointNs, meta.checkpointId),
+    ]);
+    const tuple = {
+        config: configFor(threadId, checkpointNs, meta.checkpointId),
+        checkpoint,
+        metadata,
+        pendingWrites,
+    };
+    if (meta.parentCheckpointId !== undefined) {
+        tuple.parentConfig = configFor(threadId, checkpointNs, meta.parentCheckpointId);
+    }
+    return tuple;
+}
+//# sourceMappingURL=assemble.js.map

package/dist/checkpointer/internal/assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/assemble.ts"],"names":[],"mappings":";;AAoBA,sCAuBC;AAvCD,mCAA2D;AAC3D,+CAA6D;AAG7D,2DAA2D;AAC3D,SAAS,SAAS,CAAC,QAAgB,EAAE,YAAoB,EAAE,YAAoB;IAC7E,OAAO;QACL,YAAY,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE;KAChG,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,aAAa,CACjC,OAA4B,EAC5B,QAAgB,EAChB,YAAoB,EACpB,IAAwB;IAExB,MAAM,OAAO,GAAG,MAAM,IAAA,oBAAY,EAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACvF,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC9D,IAAA,4BAAc,EAAC,OAAO,EAAE,OAAO,CAAC;QAChC,IAAA,0BAAY,EAAC,OAAO,EAAE,IAAI,CAAC;QAC3B,IAAA,0BAAkB,EAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC;KACvE,CAAC,CAAC;IACH,MAAM,KAAK,GAAoB;QAC7B,MAAM,EAAE,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC;QAC5D,UAAU;QACV,QAAQ;QACR,aAAa;KACd,CAAC;IACF,IAAI,IAAI,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QAC1C,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,13 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+/** The thread/namespace/checkpoint identifiers extracted from a config. */
+export interface ResolvedConfigurable {
+    threadId: string;
+    checkpointNs: string;
+    checkpointId?: string;
+}
+/**
+ * Narrow `RunnableConfig.configurable` to the identifiers the saver needs,
+ * defaulting the namespace to empty and validating that a thread id is present.
+ */
+export declare function readConfigurable(config: RunnableConfig): ResolvedConfigurable;
+//# sourceMappingURL=configurable.d.ts.map

package/dist/checkpointer/internal/configurable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurable.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/configurable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAKhE,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,oBAAoB,CAa7E"}

package/dist/checkpointer/internal/configurable.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readConfigurable = readConfigurable;
+const validation_1 = require("./validation");
+/**
+ * Narrow `RunnableConfig.configurable` to the identifiers the saver needs,
+ * defaulting the namespace to empty and validating that a thread id is present.
+ */
+function readConfigurable(config) {
+    const configurable = (config.configurable ?? {});
+    (0, validation_1.validateThreadId)(configurable.thread_id);
+    const checkpointNs = configurable.checkpoint_ns ?? '';
+    (0, validation_1.validateCheckpointNs)(checkpointNs);
+    if (configurable.checkpoint_id !== undefined) {
+        (0, validation_1.validateCheckpointId)(configurable.checkpoint_id);
+    }
+    return {
+        threadId: configurable.thread_id,
+        checkpointNs,
+        checkpointId: configurable.checkpoint_id,
+    };
+}
+//# sourceMappingURL=configurable.js.map

package/dist/checkpointer/internal/configurable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configurable.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/configurable.ts"],"names":[],"mappings":";;AAgBA,4CAaC;AA1BD,6CAA4F;AAS5F;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAsB;IACrD,MAAM,YAAY,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,CAA2B,CAAC;IAC3E,IAAA,6BAAgB,EAAC,YAAY,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,YAAY,CAAC,aAAa,IAAI,EAAE,CAAC;IACtD,IAAA,iCAAoB,EAAC,YAAY,CAAC,CAAC;IACnC,IAAI,YAAY,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QAC7C,IAAA,iCAAoB,EAAC,YAAY,CAAC,aAAa,CAAC,CAAC;IACnD,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,YAAY,CAAC,SAAS;QAChC,YAAY;QACZ,YAAY,EAAE,YAAY,CAAC,aAAa;KACzC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,10 @@
+import type { CheckpointPendingWrite } from '@langchain/langgraph-checkpoint';
+import type { CheckpointMetaItem, CheckpointPayloadItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/** Fetch the target META item: by id when given, else the newest in the namespace. */
+export declare function fetchTargetMeta(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId?: string): Promise<CheckpointMetaItem | undefined>;
+/** Fetch the PAYLOAD item for a checkpoint. */
+export declare function fetchPayload(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string): Promise<CheckpointPayloadItem | undefined>;
+/** Fetch and decode every pending write for a checkpoint, in write order. */
+export declare function fetchPendingWrites(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string): Promise<CheckpointPendingWrite[]>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/checkpointer/internal/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAI9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAuB,MAAM,UAAU,CAAC;AAU/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,sFAAsF;AACtF,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAsBzC;AAED,+CAA+C;AAC/C,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAS5C;AAED,6EAA6E;AAC7E,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAYnC"}

package/dist/checkpointer/internal/fetch.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchTargetMeta = fetchTargetMeta;
+exports.fetchPayload = fetchPayload;
+exports.fetchPendingWrites = fetchPendingWrites;
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_1 = require("../../shared/dynamodb/retry");
+const item_reader_1 = require("./item-reader");
+const keys_1 = require("./keys");
+const query_1 = require("./query");
+/** Fetch the target META item: by id when given, else the newest in the namespace. */
+async function fetchTargetMeta(context, threadId, checkpointNs, checkpointId) {
+    if (checkpointId !== undefined) {
+        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+            TableName: context.tableName,
+            Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.metaSortKey)(checkpointNs, checkpointId) },
+            ConsistentRead: true,
+        }));
+        return result.Item;
+    }
+    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.metaSortKeyPrefix)(checkpointNs), {
+        limit: 1,
+        consistent: true,
+    });
+    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.query(params));
+    return result.Items?.[0];
+}
+/** Fetch the PAYLOAD item for a checkpoint. */
+async function fetchPayload(context, threadId, checkpointNs, checkpointId) {
+    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+        TableName: context.tableName,
+        Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.payloadSortKey)(checkpointNs, checkpointId) },
+        ConsistentRead: true,
+    }));
+    return result.Item;
+}
+/** Fetch and decode every pending write for a checkpoint, in write order. */
+async function fetchPendingWrites(context, threadId, checkpointNs, checkpointId) {
+    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.writeSortKeyPrefix)(checkpointNs, checkpointId), { ascending: true, consistent: true });
+    const items = [];
+    for await (const item of (0, paginate_1.paginateQuery)({ client: context.client, params })) {
+        items.push(item);
+    }
+    return (0, item_reader_1.toPendingWrites)(context, items);
+}
+//# sourceMappingURL=fetch.js.map

package/dist/checkpointer/internal/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/fetch.ts"],"names":[],"mappings":";;AAiBA,0CA2BC;AAGD,oCAcC;AAGD,gDAiBC;AA/ED,6DAA+D;AAC/D,uDAAgE;AAEhE,+CAAgD;AAChD,iCAMgB;AAChB,mCAA0C;AAG1C,sFAAsF;AAC/E,KAAK,UAAU,eAAe,CACnC,OAA4B,EAC5B,QAAgB,EAChB,YAAoB,EACpB,YAAqB;IAErB,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;YACjB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,IAAA,mBAAY,EAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,IAAA,kBAAW,EAAC,YAAY,EAAE,YAAY,CAAC,EAAE;YAChF,cAAc,EAAE,IAAI;SACrB,CAAC,CACH,CAAC;QACF,OAAO,MAAM,CAAC,IAAsC,CAAC;IACvD,CAAC;IACD,MAAM,MAAM,GAAG,IAAA,uBAAe,EAC5B,OAAO,CAAC,SAAS,EACjB,IAAA,mBAAY,EAAC,QAAQ,CAAC,EACtB,IAAA,wBAAiB,EAAC,YAAY,CAAC,EAC/B;QACE,KAAK,EAAE,CAAC;QACR,UAAU,EAAE,IAAI;KACjB,CACF,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAmC,CAAC;AAC7D,CAAC;AAED,+CAA+C;AACxC,KAAK,UAAU,YAAY,CAChC,OAA4B,EAC5B,QAAgB,EAChB,YAAoB,EACpB,YAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,IAAA,mBAAY,EAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,IAAA,qBAAc,EAAC,YAAY,EAAE,YAAY,CAAC,EAAE;QACnF,cAAc,EAAE,IAAI;KACrB,CAAC,CACH,CAAC;IACF,OAAO,MAAM,CAAC,IAAyC,CAAC;AAC1D,CAAC;AAED,6EAA6E;AACtE,KAAK,UAAU,kBAAkB,CACtC,OAA4B,EAC5B,QAAgB,EAChB,YAAoB,EACpB,YAAoB;IAEpB,MAAM,MAAM,GAAG,IAAA,uBAAe,EAC5B,OAAO,CAAC,SAAS,EACjB,IAAA,mBAAY,EAAC,QAAQ,CAAC,EACtB,IAAA,yBAAkB,EAAC,YAAY,EAAE,YAAY,CAAC,EAC9C,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CACtC,CAAC;IACF,MAAM,KAAK,GAA0B,EAAE,CAAC;IACxC,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,IAAA,wBAAa,EAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAC3E,KAAK,CAAC,IAAI,CAAC,IAA2B,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAA,6BAAe,EAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AACzC,CAAC"}

package/dist/checkpointer/internal/filter-match.d.ts

@@ -0,0 +1,12 @@
+/** A JSON-comparable value used in metadata filters. */
+export type FilterValue = string | number | boolean | null | FilterValue[] | {
+    [key: string]: FilterValue;
+};
+/**
+ * True when every key in `filter` is present in `metadata` with a deeply equal
+ * value. Equality is structural and key-order-independent for nested objects,
+ * order-significant for arrays, and type-strict (no `3` vs `'3'` coercion). An
+ * empty filter matches everything.
+ */
+export declare function matchesFilter(metadata: Record<string, FilterValue>, filter: Record<string, FilterValue>): boolean;
+//# sourceMappingURL=filter-match.d.ts.map

package/dist/checkpointer/internal/filter-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-match.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/filter-match.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,WAAW,EAAE,GACb;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;CAAE,CAAC;AAEnC;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAClC,OAAO,CAET"}

package/dist/checkpointer/internal/filter-match.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesFilter = matchesFilter;
+const node_util_1 = require("node:util");
+/**
+ * True when every key in `filter` is present in `metadata` with a deeply equal
+ * value. Equality is structural and key-order-independent for nested objects,
+ * order-significant for arrays, and type-strict (no `3` vs `'3'` coercion). An
+ * empty filter matches everything.
+ */
+function matchesFilter(metadata, filter) {
+    return Object.entries(filter).every(([key, value]) => (0, node_util_1.isDeepStrictEqual)(metadata[key], value));
+}
+//# sourceMappingURL=filter-match.js.map

package/dist/checkpointer/internal/filter-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-match.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/filter-match.ts"],"names":[],"mappings":";;AAiBA,sCAKC;AAtBD,yCAA8C;AAW9C;;;;;GAKG;AACH,SAAgB,aAAa,CAC3B,QAAqC,EACrC,MAAmC;IAEnC,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,IAAA,6BAAiB,EAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AACjG,CAAC"}

package/dist/checkpointer/internal/item-reader.d.ts

@@ -0,0 +1,10 @@
+import type { Checkpoint, CheckpointMetadata, CheckpointPendingWrite } from '@langchain/langgraph-checkpoint';
+import type { CheckpointMetaItem, CheckpointPayloadItem, CheckpointWriteItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/** Decode the checkpoint stored in a PAYLOAD item. */
+export declare function readCheckpoint(context: CheckpointerContext, item: CheckpointPayloadItem): Promise<Checkpoint>;
+/** Decode the metadata stored in a META item. */
+export declare function readMetadata(context: CheckpointerContext, item: CheckpointMetaItem): Promise<CheckpointMetadata>;
+/** Decode WRITE items into `[taskId, channel, value]` pending-write tuples. */
+export declare function toPendingWrites(context: CheckpointerContext, items: CheckpointWriteItem[]): Promise<CheckpointPendingWrite[]>;
+//# sourceMappingURL=item-reader.d.ts.map

package/dist/checkpointer/internal/item-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-reader.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,sDAAsD;AACtD,wBAAsB,cAAc,CAClC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,iDAAiD;AACjD,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED,+EAA+E;AAC/E,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,mBAAmB,EAAE,GAC3B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAQnC"}