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

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

@@ -1,31 +1,54 @@
-import type { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+/**
+ * Hides which options the saver and its methods accept, and how the saver is
+ * assembled from them.
+ *
+ * The exhaustive key list of every option bag — the constructor's, `list`'s,
+ * `getDeltaChannelHistory`'s — lives here, compiler-checked against its type,
+ * beside the code that resolves the constructor's options into the context
+ * every action receives.
+ */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { CompressionConfig } from '../../shared/codec/compression';
-import { S3Offloader } from '../../shared/codec/s3/offloader';
-import { type Logger } from '../../shared/logging/logger';
-import type { TtlOption } from '../../shared/validation/ttl';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter';
 import type { DynamoDBSaverOptions } from '../types';
+/**
+ * The keys of each checkpointer option bag, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
+ * cannot rot away from the type it guards. They live with the feature because
+ * the types they are checked against do; `shared/` knows no feature.
+ */
+export declare const SAVER_KEYS: readonly string[];
+/** See {@link SAVER_KEYS}. */
+export declare const SAVER_LIST_KEYS: readonly string[];
+/**
+ * See {@link SAVER_KEYS}. `DeltaChannelHistoryOptions` is pinned equal to
+ * `BaseCheckpointSaver.getDeltaChannelHistory`'s own parameter type, the
+ * contract that method implements, so this list is checked against it.
+ */
+export declare const DELTA_CHANNEL_HISTORY_KEYS: readonly string[];
 /** Resolved collaborators shared by every checkpointer action. */
-export interface CheckpointerContext {
-    client: DynamoDBDocument;
-    tableName: string;
+export interface CheckpointerContext extends AdapterCore {
     serde: SerializerProtocol;
-    compression?: CompressionConfig;
-    offloader?: S3Offloader;
-    ttl?: TtlOption;
-    logger: Logger;
 }
 /** Result of wiring up a checkpointer from its options. */
 export interface CheckpointerSetup {
     context: CheckpointerContext;
-    ddbClient: DynamoDBClient | undefined;
-    ownsClient: boolean;
+    shell: AdapterShell;
 }
 /**
- * Resolve the DynamoDB client, optional S3 offloader, and logging into the
- * context every action receives, plus the ownership info the class needs to
- * tear resources down.
+ * 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;
-//# sourceMappingURL=setup.d.ts.map

package/dist/checkpointer/internal/setup.js

@@ -1,36 +1,72 @@
 "use strict";
+/**
+ * Hides which options the saver and its methods accept, and how the saver is
+ * assembled from them.
+ *
+ * The exhaustive key list of every option bag — the constructor's, `list`'s,
+ * `getDeltaChannelHistory`'s — lives here, compiler-checked against its type,
+ * beside the code that resolves the constructor's options into the context
+ * every action receives.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DELTA_CHANNEL_HISTORY_KEYS = exports.SAVER_LIST_KEYS = exports.SAVER_KEYS = void 0;
 exports.setUpCheckpointer = setUpCheckpointer;
-const config_1 = require("../../shared/codec/s3/config");
-const offloader_1 = require("../../shared/codec/s3/offloader");
-const constants_1 = require("../../shared/constants");
-const client_1 = require("../../shared/dynamodb/client");
-const logger_1 = require("../../shared/logging/logger");
+const adapter_1 = require("../../shared/adapter");
+const option_shape_1 = require("../../shared/validation/option-shape");
+/**
+ * The keys of each checkpointer option bag, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
+ * cannot rot away from the type it guards. They live with the feature because
+ * the types they are checked against do; `shared/` knows no feature.
+ */
+exports.SAVER_KEYS = (0, option_shape_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',
+});
+/** See {@link SAVER_KEYS}. */
+exports.SAVER_LIST_KEYS = (0, option_shape_1.allKeysOf)({
+    limit: 'limit',
+    before: 'before',
+    filter: 'filter',
+});
+/**
+ * See {@link SAVER_KEYS}. `DeltaChannelHistoryOptions` is pinned equal to
+ * `BaseCheckpointSaver.getDeltaChannelHistory`'s own parameter type, the
+ * contract that method implements, so this list is checked against it.
+ */
+exports.DELTA_CHANNEL_HISTORY_KEYS = (0, option_shape_1.allKeysOf)({
+    config: 'config',
+    channels: 'channels',
+});
 /**
- * Resolve the DynamoDB client, optional S3 offloader, and logging into the
- * context every action receives, plus the ownership info the class needs to
- * tear resources down.
+ * 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.
  */
 function setUpCheckpointer(options, serde) {
-    const resolved = (0, client_1.resolveDynamoDBClient)(options);
-    const offloader = options.s3
-        ? new offloader_1.S3Offloader({
-            ...options.s3,
-            keyPrefix: options.s3.keyPrefix ?? (0, config_1.defaultAdapterKeyPrefix)(constants_1.DEFAULT_S3_KEY_PREFIX, 'checkpointer'),
-        })
-        : undefined;
-    return {
-        context: {
-            client: resolved.client,
-            tableName: options.tableName,
-            serde,
-            compression: options.compression,
-            offloader,
-            ttl: options.ttl,
-            logger: (0, logger_1.resolveLogger)(options.logger),
-        },
-        ddbClient: resolved.ddbClient,
-        ownsClient: resolved.ownsClient,
-    };
+    const shell = (0, adapter_1.openAdapter)(options, 'checkpointer');
+    return { shell, context: { ...shell.core, serde } };
 }
-//# sourceMappingURL=setup.js.map

package/dist/checkpointer/saver.d.ts

@@ -1,30 +1,270 @@
+/**
+ * Hides the checkpointer's collaborators behind LangGraph's saver contract.
+ *
+ * `DynamoDBSaver` is the `BaseCheckpointSaver` a graph is handed: it resolves
+ * its client, offloader, logger and retry policy once and delegates each
+ * read and write to one action, save `getDeltaChannelHistory`, whose walk
+ * lives in `internal/delta-history` instead. Each asynchronous method is
+ * also the error boundary, so a raw AWS SDK error never reaches a caller
+ * unclassified (record 13); `destroy` releases what the saver owns and is
+ * the one synchronous exception. Actions can be split, merged or reordered
+ * without the public surface moving.
+ */
 import type { RunnableConfig } from '@langchain/core/runnables';
-import { BaseCheckpointSaver, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type PendingWrite } from '@langchain/langgraph-checkpoint';
-import type { DynamoDBSaverOptions } from './types';
+import { BaseCheckpointSaver, type ChannelVersions, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type DeltaChannelHistory, type PendingWrite } from '@langchain/langgraph-checkpoint';
+import type { CancelOptions } from '../shared/options';
+import type { DeltaChannelHistoryOptions, DynamoDBSaverOptions } from './types';
 /**
- * DynamoDB-backed LangGraph checkpoint saver. A thin orchestrator: it resolves
- * its collaborators once and delegates every operation to a focused action.
+ * DynamoDB-backed LangGraph checkpoint saver. Every public method rejects only
+ * with this library's error, whose `code` says what failed — an AWS failure
+ * included.
  */
 export declare class DynamoDBSaver extends BaseCheckpointSaver {
     private readonly context;
-    private readonly ownsClient;
-    private readonly ddbClient;
+    private readonly shell;
+    /**
+     * Accepts: `options` — validated here, so a misconfiguration surfaces at
+     * construction rather than on the first request. `options.serde` reaches the
+     * base class, which is why the resolved `this.serde` is what the context
+     * gets.
+     *
+     * Returns: a saver that owns the client it built, or borrows the one it was
+     * given.
+     *
+     * Throws: `VALIDATION` naming the offending option.
+     *
+     * Guarantees: no I/O. Constructing a saver issues no request, so it is safe
+     * at module scope and in a Lambda's init phase.
+     */
     constructor(options: DynamoDBSaverOptions);
+    /**
+     * Read one checkpoint with its metadata and pending writes.
+     *
+     * Accepts: `config` — an object; `config.configurable`, when present, an
+     * object too. `config.configurable.checkpoint_id` — names the checkpoint, and
+     * `thread_ts` is read in its place when it is absent; the absence of both
+     * asks for the newest in the namespace. `checkpoint_ns` defaults to the root
+     * namespace. A config naming no `thread_id` is accepted: its other
+     * identifiers are still validated. `config.signal` — aborts the reads.
+     *
+     * Returns: the tuple, or `undefined` for an unknown thread, an unknown
+     * checkpoint, a config naming no thread, or a checkpoint whose payload row is
+     * not there yet.
+     *
+     * Throws: `VALIDATION`, before any read, naming `config` for a config that
+     * is not an object, `configurable` for a `configurable` that is present and
+     * not an object, `signal` for a signal that is not `AbortSignal`-shaped, or
+     * `thread_id`, `checkpoint_ns`, `checkpoint_id` or `thread_ts` for a
+     * malformed identifier, and — from a row rather than from the call —
+     * `descriptor` for a payload descriptor no reader could make sense of, `s3`
+     * for an offloaded row with no offloader configured, `s3Key` for a row
+     * addressing an object outside the thread's own path, or `serde` for a
+     * payload the configured serializer refuses to reconstruct;
+     * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer release wrote;
+     * `PAYLOAD_CORRUPT` for a payload that is no longer the form its row
+     * declares; `S3_OFFLOAD_FAILED` for an offloaded payload that cannot be
+     * downloaded; `COMPRESSION_LIMIT` for one whose decompressed size would pass
+     * the cap; a classified AWS failure; `RETRY_EXHAUSTED`; `ABORTED`.
+     *
+     * Guarantees: strongly consistent, so a checkpoint just written is always
+     * seen.
+     */
     getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    /**
+     * Stream checkpoints newest first.
+     *
+     * Accepts: `config` — one namespace, every namespace of a thread when
+     * `checkpoint_ns` is omitted, or every thread in the table when `thread_id`
+     * is omitted, which is a table scan, or a read of the recency index when
+     * `indexName` is set. `options.before`, `options.filter` and
+     * `options.limit` follow the reference savers; `limit: 0` yields nothing,
+     * and a negative one is refused rather than answered with nothing, so that a
+     * page size whose computation went wrong is reported instead of hidden.
+     *
+     * Returns: an async generator over the tuples. Abandoning it stops the read,
+     * so a consumer that breaks early pays for no further page.
+     *
+     * Throws: `VALIDATION`, raised from the first `.next()`, since a
+     * generator runs none of its body until pulled, and before any read: naming
+     * `config`, `configurable` or `signal` for a config of the wrong shape, as
+     * {@link getTuple} does, or `thread_id`, `checkpoint_ns`, `checkpoint_id` or
+     * `thread_ts` for a malformed identifier — all checked before `options`;
+     * then `options` for options that are not an object, `options.<key>` for a
+     * key this package does not read, `filter` for a filter that is not an
+     * object, `limit` for a limit that is not an integer from 0 to
+     * `MAX_PAGE_LIMIT` (10,000), and `before` for a `before` that is not an
+     * object or whose `configurable.checkpoint_id` is
+     * neither absent (`undefined`, `null` or `''`) nor a well-formed checkpoint
+     * id. `FORMAT_UNSUPPORTED`; `RESULT_TRUNCATED`, without a `thread_id` and
+     * with `indexName`, for an index shard whose pages do not end; a classified AWS failure;
+     * `RETRY_EXHAUSTED`; `ABORTED`.
+     *
+     * Guarantees: eventually consistent — a listing tolerates the replica lag
+     * `getTuple` does not.
+     * @remarks One read per page — or, without a `thread_id` and with `indexName`,
+     * at least one query per index shard per page of 100 rows — plus two per
+     * yielded tuple (see the README cost table).
+     */
     list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
-    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+    /**
+     * Store a checkpoint and its metadata in one transaction.
+     *
+     * Accepts: `config` — shaped as {@link getTuple} requires, and naming a
+     * `thread_id`. `config.configurable.checkpoint_id` — becomes the new
+     * checkpoint's parent. `config.signal` — aborts the write. `checkpoint` —
+     * every channel value it carries is stored. `newVersions` — accepted to
+     * satisfy `BaseCheckpointSaver.put` and deliberately ignored: LangGraph passes
+     * it empty for a fork and for an empty update, so narrowing by it would store
+     * nothing for either (decision record 10).
+     *
+     * Returns: the config addressing the stored checkpoint, which is what the
+     * caller passes back to continue the thread.
+     *
+     * Throws: `VALIDATION` naming `config`, `configurable` or `signal` for a
+     * config of the wrong shape, `thread_id` for a missing or malformed thread
+     * id, `checkpoint_ns`, `checkpoint_id` or `thread_ts` for a malformed
+     * identifier, `checkpoint` for a `null` or `undefined` checkpoint,
+     * `checkpoint_id` for a malformed `checkpoint.id`, `payload` for a payload
+     * too large to store inline without `s3`, or `s3Key` for an offloaded
+     * object's key over S3's cap; `S3_OFFLOAD_FAILED` when an offloaded payload
+     * cannot be uploaded; a classified AWS failure; `RETRY_EXHAUSTED`; `ABORTED`.
+     *
+     * Guarantees: both rows land or neither does. Writing the same
+     * `checkpoint.id` again replaces both, so a retry is safe. Each put uploads
+     * its offloaded payloads under an id of its own, so the objects the replaced
+     * rows named are not deleted with them: they are left to the lifecycle rule
+     * `ensureS3LifecycleRule()` provisions.
+     */
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions?: ChannelVersions): Promise<RunnableConfig>;
+    /**
+     * Store a task's pending writes for the checkpoint `config` names.
+     *
+     * Accepts: `config` — shaped as {@link getTuple} requires, naming a
+     * `thread_id` and a `checkpoint_id`, since writes attach to a checkpoint.
+     * `config.signal` — aborts the writes. `writes` — an array of
+     * `[channel, value]` arrays, one row each, written in parallel; an empty list
+     * writes nothing. `taskId` — validated as the key segment it becomes.
+     *
+     * Returns: nothing. Losing a first-write-wins race is a normal outcome, not
+     * a failure.
+     *
+     * Throws: `VALIDATION` naming `taskId` for a malformed task id; `config`,
+     * `configurable` or `signal` for a config of the wrong shape; `thread_id`,
+     * `checkpoint_ns`, `checkpoint_id` or `thread_ts` for a malformed
+     * identifier, and `checkpoint_id` when the config names none; `writes` for
+     * writes that is not an array, or holds an entry that is not one; `channel`
+     * for a malformed channel; `sortKey` for identifiers composing a sort key
+     * over DynamoDB's cap; `payload` for a value too large to store inline
+     * without `s3`; or `s3Key` for an offloaded object's key over S3's cap.
+     * `S3_OFFLOAD_FAILED`; a classified AWS failure; `RETRY_EXHAUSTED`; `ABORTED`.
+     *
+     * Guarantees: regular writes are first-write-wins; special channels
+     * (`__interrupt__`, `__resume__`, `__error__`, `__scheduled__`) overwrite,
+     * with `s3` through a compare-and-swap on the row each call observed, so that
+     * each call releases the payload it superseded rather than one a concurrent
+     * call already replaced. An offloaded object can still be orphaned and left
+     * to the lifecycle rule: when the compare-and-swap is exhausted and the write
+     * overwrites unconditionally, when a delete fails, when the row cannot be read
+     * before the write, when a failed write cannot be verified, or in one
+     * double-fault interleaving (see the README's S3 offloading notes).
+     */
     putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
-    deleteThread(threadId: string): Promise<void>;
-    /** Release owned resources (the underlying client and any S3 client). */
+    /**
+     * Delete every checkpoint, payload and pending write of a thread.
+     *
+     * Accepts: `threadId` — validated. `options.signal` — aborts between pages.
+     *
+     * Returns: nothing. Deleting a thread that does not exist is not an error.
+     *
+     * Throws: `VALIDATION` naming `options` for options that are not an
+     * object, `options.<key>` for a key this package does not read, `signal`
+     * for a signal that is not `AbortSignal`-shaped, or `thread_id` for a
+     * malformed `threadId`;
+     * `BATCH_WRITE_INCOMPLETE` when a row's delete fails, counting rows
+     * rather than batches and carrying what did succeed; a classified AWS failure;
+     * `ABORTED` when the signal fires, which is what a cancel surfaces as
+     * rather than an incomplete delete, even when it fires part-way through the
+     * pass. A row refused because it was rewritten after the partition read
+     * raises nothing: it is left exactly as its writer left it, reported at
+     * `warn`, and counted as skipped.
+     *
+     * Guarantees: a row this adapter did not write is left in place and logged,
+     * and neither is a row rewritten since the read — so an acknowledged write is
+     * no longer erased, nor the object it names released, by a delete that
+     * observed the row before it. Single pass: call it when the thread is
+     * quiescent, since a checkpoint written at a key the read never saw survives
+     * it, and so does the re-landing of an inline pending write, which carries no
+     * request token on purpose. What comes back there is an ordinary row, naming
+     * no object this call could have released.
+     */
+    deleteThread(threadId: string, options?: CancelOptions): Promise<void>;
+    /**
+     * Walk a checkpoint's ancestors for the delta channels named, returning each
+     * channel's on-path writes oldest-first and its nearest stored value.
+     *
+     * Overrides the inherited walk, which stops silently at an ancestor it cannot
+     * read and lets the consumer restart the channel from empty. A TTL computed
+     * per put puts that within reach here, so an ancestor a channel still needs
+     * that has expired is reported instead of dropped.
+     *
+     * Accepts: `options` — must be an object naming exactly `config` and
+     * `channels`, the shape `BaseCheckpointSaver`'s own signature declares.
+     * `options.channels` — the delta channels to rebuild, required; an empty
+     * array reads nothing rather than being refused, since it is a legitimate
+     * "nothing to rebuild" request. `options.config` — the checkpoint to walk
+     * back from, shaped as {@link getTuple} requires and checked for that shape
+     * even when there is nothing to read; its `signal` aborts the whole walk —
+     * every ancestor read, not only the first — and the hop it fires on is the
+     * last read the call makes.
+     *
+     * Returns: per channel, its on-path writes oldest-first and the nearest
+     * stored value found.
+     *
+     * Throws: `VALIDATION` naming `options` for options that are not an
+     * object, `options.<key>` for an unknown key, `config`, `configurable` or
+     * `signal` for a config of the wrong shape, or `channels` for a value that
+     * is not an array of strings, and, once a channel is named, `thread_id`,
+     * `checkpoint_ns`, `checkpoint_id` or `thread_ts` for a malformed
+     * identifier; `ANCESTOR_EXPIRED` when a checkpoint a channel still needs has
+     * expired; a classified AWS failure; `RETRY_EXHAUSTED`; `ABORTED`, which a walk
+     * cancelled as it reached an expired ancestor reports in place of
+     * `ANCESTOR_EXPIRED`.
+     *
+     * Guarantees: the walk stops at the first ancestor answering for every
+     * channel, so a deep thread costs reads only as far back as the nearest
+     * snapshot.
+     */
+    getDeltaChannelHistory(options: DeltaChannelHistoryOptions): Promise<Record<string, DeltaChannelHistory>>;
+    /**
+     * Release owned resources.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Idempotent, and a no-op for a client the caller injected
+     * — that one is theirs to close.
+     *
+     * Throws: whatever a resource's own `destroy` raises — but only after every
+     * other one has been released, so a client that fails to close never strands
+     * the one behind it.
+     */
     destroy(): void;
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded payloads don't outlive the items that point at them.
+     *
+     * Accepts: nothing; the rule follows the configured `s3` and `ttl`. A no-op
+     * without both, since there would be no bucket to rule over or no expiry to
+     * match.
+     *
+     * Returns: nothing. Installing a rule that is already there is a no-op too,
+     * so calling it on every deploy is safe.
+     *
+     * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
+     * a classified AWS failure when the bucket's lifecycle cannot be read or written.
+     * @remarks Needs the bucket-level `s3:GetLifecycleConfiguration` and
+     * `s3:PutLifecycleConfiguration` permissions, which are broader than the
+     * object-level CRUD the rest of S3 offload needs. Call it once at deployment,
+     * not per request.
      */
     ensureS3LifecycleRule(): Promise<void>;
 }
-//# sourceMappingURL=saver.d.ts.map