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

package/dist/checkpointer/saver.js

@@ -1,63 +1,309 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBSaver = void 0;
 const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
-const ttl_1 = require("../shared/validation/ttl");
+const boundary_1 = require("../shared/errors/boundary");
+const collaborators_1 = require("../shared/validation/collaborators");
+const option_shape_1 = require("../shared/validation/option-shape");
 const delete_thread_1 = require("./actions/delete-thread");
 const get_tuple_1 = require("./actions/get-tuple");
 const list_1 = require("./actions/list");
 const put_1 = require("./actions/put");
 const put_writes_1 = require("./actions/put-writes");
+const delta_history_1 = require("./internal/delta-history");
+const parse_1 = require("./internal/parse");
 const setup_1 = require("./internal/setup");
 /**
- * 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.
  */
 class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
     context;
-    ownsClient;
-    ddbClient;
+    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) {
-        super(options.serde);
+        super((0, option_shape_1.parseShape)(options, setup_1.SAVER_KEYS, 'options').serde);
         const setup = (0, setup_1.setUpCheckpointer)(options, this.serde);
         this.context = setup.context;
-        this.ownsClient = setup.ownsClient;
-        this.ddbClient = setup.ddbClient;
+        this.shell = setup.shell;
     }
+    /**
+     * 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.
+     */
     async getTuple(config) {
-        return (0, get_tuple_1.getCheckpointTuple)(this.context, config);
+        return (0, boundary_1.guardPublic)('saver.getTuple', () => (0, get_tuple_1.getCheckpointTuple)(this.context, config));
     }
+    /**
+     * 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, options) {
-        return (0, list_1.listCheckpoints)(this.context, config, options);
+        return (0, boundary_1.guardPublicIterable)('saver.list', (0, list_1.listCheckpoints)(this.context, config, options));
     }
-    async put(config, checkpoint, metadata) {
-        return (0, put_1.putCheckpoint)(this.context, config, checkpoint, metadata);
+    /**
+     * 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.
+     */
+    async put(config, checkpoint, metadata, newVersions) {
+        return (0, boundary_1.guardPublic)('saver.put', () => (0, put_1.putCheckpoint)(this.context, config, checkpoint, metadata, newVersions));
     }
+    /**
+     * 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).
+     */
     async putWrites(config, writes, taskId) {
-        return (0, put_writes_1.putWrites)(this.context, config, writes, taskId);
+        return (0, boundary_1.guardPublic)('saver.putWrites', () => (0, put_writes_1.putWrites)(this.context, config, writes, taskId));
     }
-    async deleteThread(threadId) {
-        return (0, delete_thread_1.deleteThread)(this.context, threadId);
+    /**
+     * 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.
+     */
+    async deleteThread(threadId, options) {
+        return (0, boundary_1.guardPublic)('saver.deleteThread', () => {
+            (0, collaborators_1.assertCancelOptions)(options);
+            return (0, delete_thread_1.deleteThread)(this.context, threadId, options);
+        });
     }
-    /** Release owned resources (the underlying client and any S3 client). */
+    /**
+     * 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) {
+        return (0, boundary_1.guardPublic)('saver.getDeltaChannelHistory', () => {
+            const request = (0, parse_1.parseDeltaHistoryRequest)(options);
+            return (0, delta_history_1.deltaChannelHistory)(this.context, (c) => this.getTuple(c), request.config, request.channels);
+        });
+    }
+    /**
+     * 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() {
-        this.context.offloader?.destroy();
-        if (this.ownsClient)
-            this.ddbClient?.destroy();
+        this.shell.release();
     }
     /**
-     * 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.
      */
     async ensureS3LifecycleRule() {
-        if (!this.context.offloader || !this.context.ttl)
-            return;
-        await this.context.offloader.ensureLifecycleRule((0, ttl_1.resolveTtlDaysCeil)(this.context.ttl));
+        return (0, boundary_1.guardPublic)('saver.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule());
     }
 }
 exports.DynamoDBSaver = DynamoDBSaver;
-//# sourceMappingURL=saver.js.map

package/dist/checkpointer/types.d.ts

@@ -1,51 +1,51 @@
+/**
+ * Hides the saver's own modules from the shapes a caller types against.
+ *
+ * The saver's options and the options its delta-channel walk accepts are
+ * declared here, apart from the saver and its actions, so a caller can type
+ * what it builds without importing either. The narrowed `configurable` is
+ * declared beside them for the parser that reads it, not for a caller. The
+ * delta-channel options are pinned equal to upstream's inline parameter
+ * type, so they change only when LangGraph's do.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { PayloadDescriptor } from '../shared/codec/codec';
 import type { BaseAdapterOptions, CodecOptions } from '../shared/options';
 /** Options for {@link DynamoDBSaver}. */
 export type DynamoDBSaverOptions = BaseAdapterOptions & CodecOptions & {
-    /** Optional serializer override (defaults to LangGraph's JSON serializer). */
+    /**
+     * Optional serializer override. The default is the base class's, which is
+     * LangGraph's `JsonPlusSerializer` — **not** the plain JSON serializer the
+     * store and chat-history adapters default to. The two differ on read as
+     * well as on write: `JsonPlusSerializer` reconstructs a `Map`, a `Set`, a
+     * `Uint8Array` or an allow-listed `langchain_core` class from the `lc`
+     * record a stored row carries, so the row selects which constructor runs,
+     * while plain JSON parses and reconstructs nothing. Pass the exported
+     * `JSON_SERDE` for the narrower read path, at the cost of the JSON
+     * projection the README's *Table schema* section tabulates.
+     */
     serde?: SerializerProtocol;
 };
+/**
+ * Options {@link DynamoDBSaver.getDeltaChannelHistory} accepts: the object
+ * `BaseCheckpointSaver.getDeltaChannelHistory` declares inline, named so a
+ * caller can type the options it builds. A test pins it equal to upstream's
+ * parameter type.
+ */
+export interface DeltaChannelHistoryOptions {
+    /** The checkpoint to walk back from; must be an object. */
+    config: RunnableConfig;
+    /**
+     * The delta channels to rebuild, as an array of strings; `[]` reads nothing
+     * and returns `{}`.
+     */
+    channels: string[];
+}
 /** Narrowed shape of `RunnableConfig.configurable` the saver relies on. */
 export interface CheckpointConfigurable {
     thread_id: string;
     checkpoint_ns?: string;
     checkpoint_id?: string;
+    /** Legacy alias of `checkpoint_id` that older callers and API-shaped configs still emit. */
+    thread_ts?: string;
 }
-/** The lightweight `META#` item: structural fields + serialized metadata. */
-export interface CheckpointMetaItem {
-    PK: string;
-    SK: string;
-    threadId: string;
-    checkpointNs: string;
-    checkpointId: string;
-    parentCheckpointId?: string;
-    metadata: PayloadDescriptor;
-    ttl?: number;
-}
-/** The heavy `PAYLOAD#` item: the serialized checkpoint. */
-export interface CheckpointPayloadItem {
-    PK: string;
-    SK: string;
-    checkpoint: PayloadDescriptor;
-    ttl?: number;
-}
-/** A `WRITE#` item: one pending write for a checkpoint/task. */
-export interface CheckpointWriteItem {
-    PK: string;
-    SK: string;
-    taskId: string;
-    index: number;
-    channel: string;
-    /** Identifies the `putWrites` call that produced this row (see item-writer). */
-    writeGroup: string;
-    /**
-     * How many earlier writes in the same call already used this channel.
-     * Optional: rows written before 0.9.0 carry none and read back as 0, which
-     * is exactly the identity they were stored under.
-     */
-    occurrence?: number;
-    value: PayloadDescriptor;
-    ttl?: number;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/checkpointer/types.js

@@ -1,3 +1,12 @@
 "use strict";
+/**
+ * Hides the saver's own modules from the shapes a caller types against.
+ *
+ * The saver's options and the options its delta-channel walk accepts are
+ * declared here, apart from the saver and its actions, so a caller can type
+ * what it builds without importing either. The narrowed `configurable` is
+ * declared beside them for the parser that reads it, not for a caller. The
+ * delta-channel options are pinned equal to upstream's inline parameter
+ * type, so they change only when LangGraph's do.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/factory/factory.d.ts

@@ -1,43 +1,149 @@
-import type { DynamoDBClient, DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
-import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+/**
+ * Hides how several adapters share one client and one set of defaults.
+ *
+ * A caller states its defaults once; which adapter gets the base client
+ * choice and which its own, how the DynamoDB region reaches a shared `s3`
+ * config, and who destroys a client the factory built rather than was handed
+ * are decided here. Teardown is total — one adapter failing to release cannot
+ * strand the others — and a `createAll` that fails partway releases what it
+ * had built before its own error propagates.
+ */
 import { DynamoDBSaver } from '../checkpointer/saver';
 import type { DynamoDBSaverOptions } from '../checkpointer/types';
 import { DynamoDBChatMessageHistory } from '../history/chat-message-history';
 import type { DynamoDBChatMessageHistoryOptions } from '../history/types';
-import type { Logger } from '../shared/logging/logger';
 import { DynamoDBStore } from '../store/store';
 import type { DynamoDBStoreOptions } from '../store/types';
-/** Shared client/logger defaults applied to every adapter the factory builds. */
-export interface FactoryBaseOptions {
-    client?: DynamoDBDocument;
-    clientConfig?: DynamoDBClientConfig;
-    createClient?: (config: DynamoDBClientConfig) => DynamoDBClient;
-    logger?: Logger;
-}
-/** Per-adapter options for {@link DynamoDBFactory.createAll} (client is shared). */
-export interface CreateAllOptions {
-    saver: Omit<DynamoDBSaverOptions, 'client' | 'clientConfig' | 'createClient'>;
-    store: Omit<DynamoDBStoreOptions, 'client' | 'clientConfig' | 'createClient'>;
-    history: Omit<DynamoDBChatMessageHistoryOptions, 'client' | 'clientConfig' | 'createClient'>;
-}
-/** The three adapters sharing one client, plus a combined `destroy`. */
-export interface CreatedAdapters {
-    saver: DynamoDBSaver;
-    store: DynamoDBStore;
-    history: DynamoDBChatMessageHistory;
-    destroy: () => void;
-}
+import type { CreateAllOptions, CreatedAdapters, FactoryBaseOptions } from './types';
 /**
- * Convenience constructors for the adapters. Individual `create*` methods each
- * build their own client; {@link createAll} builds one shared client used by all
- * three and returns a combined `destroy` that tears everything down once.
+ * Convenience constructors for the adapters.
+ *
+ * Individual `create*` methods each build their own client; {@link createAll}
+ * builds one shared client used by all three and returns a combined `destroy`
+ * that tears everything down once. Each adapter validates the options it ends
+ * up with, so the same mistake is caught the same way however the adapter was
+ * built. The factory checks only what it reads itself before an adapter can:
+ * its own base options, client choice and logger, the keys of `createAll`'s
+ * argument, and that each adapter's options are an object at all.
+ *
+ * Every `create*` argument and every `createAll` section is one adapter's
+ * options, and a mistake in one is named the way that adapter's constructor
+ * names it: `options` for a value that is not an object, and the adapter's own
+ * field names (`options.<key>`, `tableName`, …) for anything inside one.
  */
 export declare class DynamoDBFactory {
     private readonly base;
+    /**
+     * Accepts: `base` — the defaults every adapter inherits. Checked here, where
+     * the caller wrote them: an unknown key would otherwise be ignored, and a
+     * `client` next to a `clientConfig` was refused by the first `create*` call
+     * and accepted by `createAll`, for the same base. So is the shape of
+     * `clientConfig`: `createAll` hands its adapters the client built from it,
+     * never the config, so no adapter would see a malformed one. And so is
+     * `logger`, which `createAll` logs its own teardown failures through: a
+     * malformed one threw from inside that teardown, replacing a failed build's
+     * own error with a bare `TypeError`.
+     *
+     * Returns: a factory holding those defaults. It opens nothing: every client
+     * is built by the `create*` call that needs one.
+     *
+     * Throws: `VALIDATION` naming `options.<key>`, `client`, `clientConfig`,
+     * `logger` or `logger.<method>`. Everything else each adapter validates for
+     * itself, since a per-adapter value may still replace it.
+     */
     constructor(base?: FactoryBaseOptions);
+    /** The base options every adapter inherits regardless of which client it uses. */
+    private sharedDefaults;
+    /**
+     * The base `s3` config with the region the DynamoDB side was configured with
+     * already filled in.
+     *
+     * An adapter normally reads that region off its own `clientConfig`
+     * (`offloaderConfigFor`), but the adapters {@link createAll} builds are given
+     * the one shared `client` instead — and a `clientConfig` beside a `client` is
+     * refused, because for the DynamoDB client it would be silently ignored. So
+     * the region has to be carried here, on the config that still needs it:
+     * without it, a bucket reachable only through that region fails with an
+     * opaque `PermanentRedirect` on the first offload, unlike the identical
+     * configuration through `createStore`, which resolves its own region
+     * directly.
+     *
+     * A base `s3`, or its `clientConfig`, that is not an object is handed on
+     * unchanged, for each adapter to refuse by its own name: reading `.region`
+     * off a `null` one would throw here instead, and writing a region into a
+     * malformed `clientConfig` would turn it into an object shape an adapter
+     * then accepts instead of refusing.
+     */
+    private sharedS3;
+    /**
+     * Per-adapter options replace the factory's client choice as a unit: a
+     * `client` handed to `createSaver` also displaces the base `clientConfig`
+     * and `createClient`, because carrying those along is exactly the ambiguous
+     * combination the adapters' option validation rejects. The shared
+     * `ttl`/`compression`/`s3`/`retry` defaults stay either way.
+     */
+    private defaultsFor;
+    /**
+     * A saver on its own client.
+     *
+     * Accepts: `options` — the saver's own, laid over the factory's defaults. A
+     * per-adapter value wins; see {@link defaultsFor} for how a client choice
+     * replaces the factory's as a unit.
+     *
+     * Returns: the saver, which owns the client it built and releases it on
+     * `destroy()`.
+     *
+     * Throws: `VALIDATION` for any invalid option, naming it as the saver's
+     * constructor does — `options` for a value that is not an object, checked
+     * before the defaults are laid under it: reading `.client` off a `null`
+     * value would throw here, and spreading a string would iterate its
+     * characters instead of refusing it.
+     */
     createSaver(options: DynamoDBSaverOptions): DynamoDBSaver;
+    /**
+     * A store on its own client.
+     *
+     * Accepts: as {@link createSaver}, for the store's options.
+     *
+     * Returns: the store.
+     *
+     * Throws: as {@link createSaver}.
+     */
     createStore(options: DynamoDBStoreOptions): DynamoDBStore;
+    /**
+     * A chat history on its own client.
+     *
+     * Accepts: as {@link createSaver}, for the history's options.
+     *
+     * Returns: the chat history.
+     *
+     * Throws: as {@link createSaver}.
+     */
     createChatMessageHistory(options: DynamoDBChatMessageHistoryOptions): DynamoDBChatMessageHistory;
-    createAll(options: CreateAllOptions): CreatedAdapters;
+    /**
+     * Build the adapters whose sections are given, all on one shared client.
+     *
+     * Accepts: `options` — a section per adapter, laid over the factory's shared
+     * defaults; omitting one, or giving it as `undefined`, skips that adapter,
+     * and `{}` builds none. A key that is not a section name is refused rather
+     * than ignored, so a misspelt one cannot silently build nothing. Each section
+     * is that adapter's options, so one that is not an object, `null` included,
+     * is refused before any client is built.
+     *
+     * Returns: the adapters, typed by the sections asked for, and one `destroy`
+     * that releases all of them and the shared client. A client the factory was
+     * given rather than built is never destroyed.
+     *
+     * Throws: `VALIDATION` naming `options` for an argument or a section that
+     * is not an object, or `options.<key>` for a key that is not a section name.
+     * Whatever an adapter's constructor throws — after the adapters already
+     * built and the freshly created client have been released, so a failed call
+     * leaks nothing and the constructor's own error is the one that propagates.
+     *
+     * Guarantees: one DynamoDB client for all three adapters, and one S3 client
+     * per adapter, each under its own key prefix in the shared bucket. Teardown
+     * is total: one adapter failing to release its resources cannot strand the
+     * others.
+     */
+    createAll<O extends CreateAllOptions>(options: O): CreatedAdapters<O>;
 }
-//# sourceMappingURL=factory.d.ts.map