@farukada/aws-langgraph-dynamodb-ts 0.0.2

package/dist/checkpointer/actions/writer.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Writer = void 0;
+const utils_1 = require("../utils");
+/**
+ * Writer class for managing pending writes in DynamoDB
+ * Handles serialization and composite key management
+ */
+class Writer {
+    /** Unique identifier for the conversation thread */
+    thread_id;
+    /** Namespace for checkpoint isolation (default: '') */
+    checkpoint_ns;
+    /** Unique identifier for the checkpoint */
+    checkpoint_id;
+    /** Unique identifier for the task that created this write */
+    task_id;
+    /** Index of the write within the task (0-based) */
+    idx;
+    /** Channel name for the write */
+    channel;
+    /** Type identifier for deserialization */
+    type;
+    /** Serialized value as binary data */
+    value;
+    constructor({ thread_id, checkpoint_ns, checkpoint_id, task_id, idx, channel, type, value, }) {
+        // Validate all inputs
+        (0, utils_1.validateThreadId)(thread_id);
+        (0, utils_1.validateCheckpointNs)(checkpoint_ns);
+        (0, utils_1.validateCheckpointId)(checkpoint_id, true);
+        (0, utils_1.validateTaskId)(task_id);
+        (0, utils_1.validateChannel)(channel);
+        if (!Number.isInteger(idx) || idx < 0) {
+            throw new Error('idx must be a non-negative integer');
+        }
+        this.thread_id = thread_id;
+        this.checkpoint_ns = checkpoint_ns;
+        this.checkpoint_id = checkpoint_id;
+        this.task_id = task_id;
+        this.idx = idx;
+        this.channel = channel;
+        this.type = type;
+        this.value = value;
+    }
+    toDynamoDBItem() {
+        return {
+            thread_id_checkpoint_id_checkpoint_ns: Writer.getPartitionKey({
+                thread_id: this.thread_id,
+                checkpoint_id: this.checkpoint_id,
+                checkpoint_ns: this.checkpoint_ns,
+            }),
+            task_id_idx: [this.task_id, this.idx].join(Writer.separator()),
+            channel: this.channel,
+            type: this.type,
+            value: this.value,
+        };
+    }
+    /**
+     * Deserialize a Writer instance from a DynamoDB item
+     *
+     * @param item - DynamoDB write item
+     * @returns Writer instance
+     * @throws Error if parsing fails or data is invalid
+     */
+    static fromDynamoDBItem({ thread_id_checkpoint_id_checkpoint_ns, task_id_idx, channel, type, value, }) {
+        const parts = thread_id_checkpoint_id_checkpoint_ns.split(this.separator());
+        if (parts.length !== 3) {
+            throw new Error(`Invalid partition key format: expected 3 parts, got ${parts.length}`);
+        }
+        const [thread_id, checkpoint_id, checkpoint_ns] = parts;
+        const idxParts = task_id_idx.split(this.separator());
+        if (idxParts.length !== 2) {
+            throw new Error(`Invalid sort key format: expected 2 parts, got ${idxParts.length}`);
+        }
+        const [task_id, idxStr] = idxParts;
+        const idx = parseInt(idxStr, 10);
+        if (isNaN(idx)) {
+            throw new Error(`Invalid idx value: ${idxStr}`);
+        }
+        return new Writer({
+            thread_id,
+            checkpoint_ns,
+            checkpoint_id,
+            task_id,
+            idx,
+            channel,
+            type,
+            value,
+        });
+    }
+    /**
+     * Generate a partition key for DynamoDB from thread, checkpoint, and namespace
+     *
+     * @param params - Thread ID, checkpoint ID, and namespace
+     * @returns Composite partition key
+     */
+    static getPartitionKey({ thread_id, checkpoint_id, checkpoint_ns, }) {
+        return [thread_id, checkpoint_id, checkpoint_ns].join(this.separator());
+    }
+    /**
+     * Get the separator used for composite keys
+     * Note: Input validation ensures this separator cannot be in any component
+     */
+    static separator() {
+        return ':::';
+    }
+}
+exports.Writer = Writer;
+//# sourceMappingURL=writer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/writer.ts"],"names":[],"mappings":"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"}

package/dist/checkpointer/index.d.ts

@@ -0,0 +1,70 @@
+import { BaseCheckpointSaver, type Checkpoint, type CheckpointTuple, type CheckpointMetadata, type CheckpointListOptions, type PendingWrite, type ChannelVersions } from '@langchain/langgraph-checkpoint';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { DynamoDBSaverOptions } from './types';
+/**
+ * DynamoDB-based checkpoint saver for LangGraph
+ * Provides persistent storage for checkpoints and pending writes
+ */
+export declare class DynamoDBSaver extends BaseCheckpointSaver {
+    private readonly ddbClient;
+    private readonly client;
+    private readonly checkpointsTableName;
+    private readonly writesTableName;
+    private readonly ttlDays?;
+    /**
+     * Create a new DynamoDB checkpoint saver
+     *
+     * @param options - Configuration options for the saver
+     * @param options.checkpointsTableName - Name of the DynamoDB table for checkpoints
+     * @param options.writesTableName - Name of the DynamoDB table for writes
+     * @param options.ttlDays - Optional TTL in days for stored items
+     * @param options.serde - Optional serializer protocol
+     * @param options.clientConfig - Optional DynamoDB client configuration
+     */
+    constructor(options: DynamoDBSaverOptions);
+    /**
+     * Delete a thread and all its checkpoints and writes
+     *
+     * @param threadId - The thread ID to delete
+     * @throws Error if validation fails or operation fails
+     */
+    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Get a checkpoint tuple from DynamoDB
+     *
+     * @param config - Runnable configuration containing thread_id and optional checkpoint_id
+     * @returns CheckpointTuple if found, undefined otherwise
+     * @throws Error if validation fails or operation fails
+     */
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    /**
+     * Save a checkpoint to DynamoDB
+     *
+     * @param config - Runnable configuration
+     * @param checkpoint - Checkpoint to save
+     * @param metadata - Checkpoint metadata
+     * @param newVersions - Channel versions (not used in DynamoDB implementation)
+     * @returns Updated RunnableConfig with checkpoint information
+     * @throws Error if validation fails or operation fails
+     */
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions: ChannelVersions): Promise<RunnableConfig>;
+    /**
+     * Save pending writes to DynamoDB
+     *
+     * @param config - Runnable configuration
+     * @param writes - Array of pending writes to save
+     * @param taskId - Task ID for the writes
+     * @throws Error if validation fails or operation fails
+     */
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    /**
+     * List checkpoints for a thread
+     *
+     * @param config - Runnable configuration containing thread_id
+     * @param options - List options including limit and before checkpoint
+     * @yields CheckpointTuple objects in descending order
+     * @throws Error if validation fails or operation fails
+     */
+    list(config: RunnableConfig, options: CheckpointListOptions | undefined): AsyncGenerator<CheckpointTuple>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/checkpointer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpointer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,iCAAiC,CAAC;AAIzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAkB,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAIpE;;;GAGG;AACH,qBAAa,aAAc,SAAQ,mBAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAElC;;;;;;;;;OASG;gBACS,OAAO,EAAE,oBAAoB;IASzC;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASnD;;;;;;OAMG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAU5E;;;;;;;;;OASG;IACG,GAAG,CACP,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,EAC5B,WAAW,EAAE,eAAe,GAC3B,OAAO,CAAC,cAAc,CAAC;IAY1B;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY9F;;;;;;;OAOG;IACI,IAAI,CACT,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,cAAc,CAAC,eAAe,CAAC;CAgEnC"}

package/dist/checkpointer/index.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBSaver = void 0;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const actions_1 = require("./actions");
+const utils_1 = require("./utils");
+const shared_1 = require("../shared");
+/**
+ * DynamoDB-based checkpoint saver for LangGraph
+ * Provides persistent storage for checkpoints and pending writes
+ */
+class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
+    ddbClient;
+    client;
+    checkpointsTableName;
+    writesTableName;
+    ttlDays;
+    /**
+     * Create a new DynamoDB checkpoint saver
+     *
+     * @param options - Configuration options for the saver
+     * @param options.checkpointsTableName - Name of the DynamoDB table for checkpoints
+     * @param options.writesTableName - Name of the DynamoDB table for writes
+     * @param options.ttlDays - Optional TTL in days for stored items
+     * @param options.serde - Optional serializer protocol
+     * @param options.clientConfig - Optional DynamoDB client configuration
+     */
+    constructor(options) {
+        super(options.serde);
+        this.checkpointsTableName = options.checkpointsTableName;
+        this.writesTableName = options.writesTableName;
+        this.ttlDays = options.ttlDays;
+        this.ddbClient = new client_dynamodb_1.DynamoDBClient(options.clientConfig || {});
+        this.client = lib_dynamodb_1.DynamoDBDocument.from(this.ddbClient);
+    }
+    /**
+     * Delete a thread and all its checkpoints and writes
+     *
+     * @param threadId - The thread ID to delete
+     * @throws Error if validation fails or operation fails
+     */
+    async deleteThread(threadId) {
+        return await (0, actions_1.deleteThreadAction)({
+            client: this.client,
+            checkpointsTableName: this.checkpointsTableName,
+            writesTableName: this.writesTableName,
+            threadId,
+        });
+    }
+    /**
+     * Get a checkpoint tuple from DynamoDB
+     *
+     * @param config - Runnable configuration containing thread_id and optional checkpoint_id
+     * @returns CheckpointTuple if found, undefined otherwise
+     * @throws Error if validation fails or operation fails
+     */
+    async getTuple(config) {
+        return await (0, actions_1.getTupleAction)({
+            client: this.client,
+            checkpointsTableName: this.checkpointsTableName,
+            writesTableName: this.writesTableName,
+            serde: this.serde,
+            config,
+        });
+    }
+    /**
+     * Save a checkpoint to DynamoDB
+     *
+     * @param config - Runnable configuration
+     * @param checkpoint - Checkpoint to save
+     * @param metadata - Checkpoint metadata
+     * @param newVersions - Channel versions (not used in DynamoDB implementation)
+     * @returns Updated RunnableConfig with checkpoint information
+     * @throws Error if validation fails or operation fails
+     */
+    async put(config, checkpoint, metadata, newVersions) {
+        return await (0, actions_1.putAction)({
+            client: this.client,
+            checkpointsTableName: this.checkpointsTableName,
+            serde: this.serde,
+            config,
+            checkpoint,
+            metadata,
+            ttlDays: this.ttlDays,
+        });
+    }
+    /**
+     * Save pending writes to DynamoDB
+     *
+     * @param config - Runnable configuration
+     * @param writes - Array of pending writes to save
+     * @param taskId - Task ID for the writes
+     * @throws Error if validation fails or operation fails
+     */
+    async putWrites(config, writes, taskId) {
+        return await (0, actions_1.putWritesAction)({
+            client: this.client,
+            writesTableName: this.writesTableName,
+            serde: this.serde,
+            config,
+            writes,
+            taskId,
+            ttlDays: this.ttlDays,
+        });
+    }
+    /**
+     * List checkpoints for a thread
+     *
+     * @param config - Runnable configuration containing thread_id
+     * @param options - List options including limit and before checkpoint
+     * @yields CheckpointTuple objects in descending order
+     * @throws Error if validation fails or operation fails
+     */
+    async *list(config, options) {
+        const { limit, before } = options ?? {};
+        const thread_id = config.configurable?.thread_id;
+        // Validate thread_id
+        if (typeof thread_id !== 'string') {
+            throw new Error('thread_id must be a string');
+        }
+        (0, utils_1.validateThreadId)(thread_id);
+        // Validate limit if provided
+        (0, utils_1.validateListLimit)(limit);
+        const expressionAttributeValues = {
+            ':thread_id': thread_id,
+        };
+        let keyConditionExpression = 'thread_id = :thread_id';
+        if (before?.configurable?.checkpoint_id) {
+            keyConditionExpression += ' AND checkpoint_id < :before_checkpoint_id';
+            expressionAttributeValues[':before_checkpoint_id'] = before.configurable.checkpoint_id;
+        }
+        const result = await (0, shared_1.withDynamoDBRetry)(async () => {
+            return await this.client.query({
+                TableName: this.checkpointsTableName,
+                KeyConditionExpression: keyConditionExpression,
+                ExpressionAttributeValues: expressionAttributeValues,
+                Limit: limit,
+                ScanIndexForward: false, // Descending order
+            });
+        });
+        if (result.Items) {
+            for (const item of result.Items) {
+                const checkpoint = (await this.serde.loadsTyped(item.type, item.checkpoint));
+                const metadata = (await this.serde.loadsTyped(item.type, item.metadata));
+                yield {
+                    config: {
+                        configurable: {
+                            thread_id: item.thread_id,
+                            checkpoint_ns: item.checkpoint_ns,
+                            checkpoint_id: item.checkpoint_id,
+                        },
+                    },
+                    checkpoint,
+                    metadata,
+                    parentConfig: item.parent_checkpoint_id
+                        ? {
+                            configurable: {
+                                thread_id: item.thread_id,
+                                checkpoint_ns: item.checkpoint_ns,
+                                checkpoint_id: item.parent_checkpoint_id,
+                            },
+                        }
+                        : undefined,
+                };
+            }
+        }
+    }
+}
+exports.DynamoDBSaver = DynamoDBSaver;
+//# sourceMappingURL=index.js.map

package/dist/checkpointer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkpointer/index.ts"],"names":[],"mappings":"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"}

package/dist/checkpointer/types/index.d.ts

@@ -0,0 +1,162 @@
+import { Checkpoint, CheckpointMetadata, PendingWrite, SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+import { RunnableConfig } from '@langchain/core/runnables';
+/**
+ * Configuration options for DynamoDBSaver
+ *
+ * @property checkpointsTableName - Name of the DynamoDB table for storing checkpoints
+ * @property writesTableName - Name of the DynamoDB table for storing pending writes
+ * @property ttlDays - Optional TTL in days for automatic item expiration (max 1825 days)
+ * @property serde - Optional custom serializer protocol for checkpoint serialization
+ * @property clientConfig - Optional DynamoDB client configuration
+ */
+export interface DynamoDBSaverOptions {
+    checkpointsTableName: string;
+    writesTableName: string;
+    ttlDays?: number;
+    serde?: SerializerProtocol;
+    clientConfig?: DynamoDBClientConfig;
+}
+/**
+ * Properties for creating a Writer instance
+ *
+ * @property thread_id - Unique identifier for the conversation thread
+ * @property checkpoint_ns - Namespace for checkpoint isolation (default: '')
+ * @property checkpoint_id - Unique identifier for the checkpoint
+ * @property task_id - Unique identifier for the task that created the write
+ * @property idx - Index of the write within the task (0-based)
+ * @property channel - Channel name for the write
+ * @property type - Type identifier for deserialization
+ * @property value - Serialized value as binary data
+ */
+export interface WriterProps {
+    thread_id: string;
+    checkpoint_ns: string;
+    checkpoint_id: string;
+    task_id: string;
+    idx: number;
+    channel: string;
+    type: string;
+    value: Uint8Array;
+}
+/**
+ * DynamoDB representation of a pending write
+ * Uses composite keys for efficient querying
+ *
+ * @property thread_id_checkpoint_id_checkpoint_ns - Composite partition key (format: "thread_id:::checkpoint_id:::checkpoint_ns")
+ * @property task_id_idx - Composite sort key (format: "task_id:::idx")
+ * @property channel - Channel name for the write
+ * @property type - Type identifier for deserialization
+ * @property value - Serialized value as binary data
+ */
+export interface DynamoDBWriteItem {
+    thread_id_checkpoint_id_checkpoint_ns: string;
+    task_id_idx: string;
+    channel: string;
+    type: string;
+    value: Uint8Array;
+}
+/**
+ * DynamoDB representation of a checkpoint
+ *
+ * @property thread_id - Unique identifier for the conversation thread (partition key)
+ * @property checkpoint_ns - Namespace for checkpoint isolation
+ * @property checkpoint_id - Unique identifier for the checkpoint (sort key)
+ * @property parent_checkpoint_id - Optional ID of the parent checkpoint for checkpoint chains
+ * @property type - Type identifier for deserialization
+ * @property checkpoint - Serialized checkpoint data as binary
+ * @property metadata - Serialized metadata as binary
+ */
+export interface CheckpointItem {
+    thread_id: string;
+    checkpoint_ns: string;
+    checkpoint_id: string;
+    parent_checkpoint_id?: string;
+    type: string;
+    checkpoint: Uint8Array;
+    metadata: Uint8Array;
+}
+/**
+ * Validated configurable parameters from RunnableConfig
+ *
+ * @property thread_id - Validated unique identifier for the conversation thread
+ * @property checkpoint_ns - Validated namespace for checkpoint isolation (empty string if not provided)
+ * @property checkpoint_id - Optional validated checkpoint identifier
+ */
+export interface ValidatedConfigurable {
+    thread_id: string;
+    checkpoint_ns: string;
+    checkpoint_id: string | undefined;
+}
+/**
+ * Parameters for deleteThread action
+ *
+ * @property client - DynamoDB Document client instance
+ * @property checkpointsTableName - Name of the checkpoints table
+ * @property writesTableName - Name of the pending writes table
+ * @property threadId - Thread identifier to delete
+ */
+export interface DeleteThreadActionParams {
+    client: DynamoDBDocument;
+    checkpointsTableName: string;
+    writesTableName: string;
+    threadId: string;
+}
+/**
+ * Parameters for getTuple action
+ *
+ * @property client - DynamoDB Document client instance
+ * @property checkpointsTableName - Name of the checkpoints table
+ * @property writesTableName - Name of the pending writes table
+ * @property serde - Serialization protocol for checkpoint data
+ * @property config - Runnable configuration with thread_id and optional checkpoint_id
+ */
+export interface GetTupleActionParams {
+    client: DynamoDBDocument;
+    checkpointsTableName: string;
+    writesTableName: string;
+    serde: SerializerProtocol;
+    config: RunnableConfig;
+}
+/**
+ * Parameters for put action
+ *
+ * @property client - DynamoDB Document client instance
+ * @property checkpointsTableName - Name of the checkpoints table
+ * @property serde - Serialization protocol for checkpoint data
+ * @property config - Runnable configuration with thread_id and namespace
+ * @property checkpoint - Checkpoint data to save
+ * @property metadata - Checkpoint metadata to save
+ * @property ttlDays - Optional TTL in days for automatic expiration (max 1825 days)
+ */
+export interface PutActionParams {
+    client: DynamoDBDocument;
+    checkpointsTableName: string;
+    serde: SerializerProtocol;
+    config: RunnableConfig;
+    checkpoint: Checkpoint;
+    metadata: CheckpointMetadata;
+    ttlDays?: number;
+}
+/**
+ * Parameters for putWrites action
+ *
+ * @property client - DynamoDB Document client instance
+ * @property writesTableName - Name of the pending writes table
+ * @property serde - Serialization protocol for write data
+ * @property config - Runnable configuration with thread_id, checkpoint_id, and namespace
+ * @property writes - Array of pending writes to save (max 1000 items)
+ * @property taskId - Task identifier that created these writes
+ * @property ttlDays - Optional TTL in days for automatic expiration (max 1825 days)
+ */
+export interface PutWritesActionParams {
+    client: DynamoDBDocument;
+    writesTableName: string;
+    serde: SerializerProtocol;
+    config: RunnableConfig;
+    writes: PendingWrite[];
+    taskId: string;
+    ttlDays?: number;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/checkpointer/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/types/index.ts"],"names":[],"mappings":"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"}

package/dist/checkpointer/types/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/checkpointer/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/checkpointer/types/index.ts"],"names":[],"mappings":""}

package/dist/checkpointer/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checkpointer utilities
+ */
+export * from './validation';
+export { withDynamoDBRetry, withRetry, type RetryOptions } from '../../shared/utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/checkpointer/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,cAAc,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/checkpointer/utils/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Checkpointer utilities
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = exports.withDynamoDBRetry = void 0;
+__exportStar(require("./validation"), exports);
+// Retry utilities re-exported from shared
+var utils_1 = require("../../shared/utils");
+Object.defineProperty(exports, "withDynamoDBRetry", { enumerable: true, get: function () { return utils_1.withDynamoDBRetry; } });
+Object.defineProperty(exports, "withRetry", { enumerable: true, get: function () { return utils_1.withRetry; } });
+//# sourceMappingURL=index.js.map

package/dist/checkpointer/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/checkpointer/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,+CAA6B;AAC7B,0CAA0C;AAC1C,4CAAqF;AAA5E,0GAAA,iBAAiB,OAAA;AAAE,kGAAA,SAAS,OAAA"}

package/dist/checkpointer/utils/validation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Validation utilities for checkpointer operations
+ */
+export declare class CheckpointerValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate thread ID
+ */
+export declare function validateThreadId(threadId: string): void;
+/**
+ * Validate checkpoint ID
+ */
+export declare function validateCheckpointId(checkpointId: string | undefined, required?: boolean): void;
+/**
+ * Validate checkpoint namespace
+ */
+export declare function validateCheckpointNs(checkpointNs: string | undefined): void;
+/**
+ * Validate task ID
+ */
+export declare function validateTaskId(taskId: string): void;
+/**
+ * Validate channel name
+ */
+export declare function validateChannel(channel: string): void;
+/**
+ * Validate writes array length
+ */
+export declare function validateWritesCount(writesCount: number): void;
+/**
+ * Validate list limit parameter
+ */
+export declare function validateListLimit(limit: number | undefined): void;
+/**
+ * Validate TTL days (wraps shared validation with a checkpointer-specific error type)
+ */
+export declare function validateTTLDays(ttlDays: number | undefined): void;
+/**
+ * Export constants for use in other modules
+ */
+export declare const CheckpointerValidationConstants: {
+    readonly MAX_DELETE_BATCH_SIZE: 100;
+    readonly MAX_WRITES_PER_BATCH: 1000;
+    readonly MAX_LIST_LIMIT: 1000;
+    readonly SEPARATOR: ":::";
+};
+//# sourceMappingURL=validation.d.ts.map

package/dist/checkpointer/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAcH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAyBvD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,QAAQ,GAAE,OAAe,GACxB,IAAI,CAgCN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAyB3E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAmBnD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAcrD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAc7D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAgBjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMjE;AAED;;GAEG;AACH,eAAO,MAAM,+BAA+B;;;;;CAKlC,CAAC"}