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

package/dist/esm/checkpointer/saver.d.ts

@@ -0,0 +1,306 @@
+/**
+ * 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. Every method is also the error
+ * boundary, so a raw AWS SDK error never reaches a caller unclassified
+ * (record 13) — an asynchronous one through `guardPublic`/`guardPublicIterable`,
+ * and the synchronous `destroy`, which releases what the saver owns, through
+ * `guardPublicSync`. Actions can be split, merged or reordered without the
+ * public surface moving.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+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.js';
+import type { DeltaChannelHistoryOptions, DynamoDBSaverOptions } from './types.js';
+/**
+ * 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 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
+     * gone — a thread being deleted, or an expiry sweep that reached it first.
+     *
+     * 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 — within a thread, and across threads
+     * through the recency index; the table scan a thread-less call falls back to
+     * without `indexName` yields in the table's own order, oldest first within a
+     * thread and threads in no particular order.
+     *
+     * 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, `filter` for a filter
+     * that is not an object, `limit` for a limit that is not an integer from 0 to
+     * 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`. An option key this version does not read is
+     * ignored rather than refused: LangGraph defines these options and passes
+     * its own through (`getStateHistory`), so a key it adds must not turn a
+     * listing into a refusal (decision record 28).
+     *
+     * 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>;
+    /**
+     * 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, once offloaded, larger than
+     * `s3.maxDownloadBytes`; `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: a special channel's row is
+     * written alongside the rest, a regular row at most 32 at a time; an empty
+     * list writes nothing. `taskId` — validated as the key segment it becomes.
+     * `taskPath` — the task's serialized path, which LangGraph 1.5 passes
+     * (`@langchain/langgraph-checkpoint@1.2.0`) and earlier LangGraphs do not;
+     * stored beside every row of the call, and the first key of the order
+     * `getTuple`, `list` and `getDeltaChannelHistory` read a checkpoint's
+     * writes back in (the reference's `writesSortKey`: path, then task id, then
+     * index, strings compared by code point). A row written without one sorts
+     * as the empty path, first.
+     *
+     * Returns: nothing. Losing a first-write-wins race is a normal outcome, not
+     * a failure.
+     *
+     * Throws: `VALIDATION` naming `taskId` for a malformed task id, or
+     * `taskPath` for a path that is not a string; `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, once offloaded, larger than `s3.maxDownloadBytes`; 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, taskPath?: string): Promise<void>;
+    /**
+     * Delete every checkpoint, payload and pending write of a thread.
+     *
+     * Accepts: `threadId` — validated. `options.signal` — ends the read or
+     * delete in flight and any wait between them; the deletes already
+     * acknowledged stay deleted.
+     *
+     * 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` — an object carrying `config` and `channels`, the
+     * shape `BaseCheckpointSaver`'s own signature declares; LangGraph calls this
+     * itself, so a key a later LangGraph adds is ignored rather than refused
+     * (decision record 28). `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, `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 or is gone, or the chain of parents loops; 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: the first failure a resource's own `destroy` raised, as a
+     * `DynamoDBLangGraphError` (`UNEXPECTED_ERROR` unless the failure was AWS's)
+     * with it as `cause` — raised only after every other resource has been
+     * released, and only by the first call: `destroy()` is idempotent.
+     */
+    destroy(): void;
+    /**
+     * 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. When it writes the rules but
+     * cannot confirm within its polling window that a re-read shows them — S3
+     * documents that a lifecycle configuration can take minutes to propagate —
+     * it logs a `warn` and returns rather than throwing: the rules were
+     * written, and a later call can confirm them.
+     *
+     * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
+     * a classified AWS failure when the bucket's lifecycle cannot be read or
+     * written; `CONTENTION` when every one of the five rounds this call polls
+     * needs a write — a competing writer replacing the configuration on every
+     * single re-read.
+     * @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 — and when several adapters or processes provision the
+     * same bucket, call them one at a time and run each again after a few
+     * minutes once every one of them has run.
+     *
+     * Lowering the `ttl` is safe for new rows at once; the rule is not. Lower
+     * `ttl` now, and call this again only once the old `ttl` has elapsed since,
+     * because until then rows written under the old value still name objects
+     * the shorter rule would expire. Raising the `ttl` is safe at once.
+     */
+    ensureS3LifecycleRule(): Promise<void>;
+}

package/dist/esm/checkpointer/saver.js

@@ -0,0 +1,52 @@
+import { BaseCheckpointSaver, } from '@langchain/langgraph-checkpoint';
+import { guardPublic, guardPublicIterable, guardPublicSync } from '../shared/errors/boundary.js';
+import { assertCancelOptions } from '../shared/validation/collaborators.js';
+import { parseShape } from '../shared/validation/option-shape.js';
+import { deleteThread as deleteThreadAction } from './actions/delete-thread.js';
+import { getCheckpointTuple } from './actions/get-tuple.js';
+import { listCheckpoints } from './actions/list.js';
+import { putWrites as putWritesAction } from './actions/put-writes.js';
+import { putCheckpoint } from './actions/put.js';
+import { deltaChannelHistory } from './internal/delta-history.js';
+import { parseDeltaHistoryRequest } from './internal/parse.js';
+import { SAVER_KEYS, setUpCheckpointer } from './internal/setup.js';
+export class DynamoDBSaver extends BaseCheckpointSaver {
+    context;
+    shell;
+    constructor(options) {
+        super(parseShape(options, SAVER_KEYS, 'options').serde);
+        const setup = setUpCheckpointer(options, this.serde);
+        this.context = setup.context;
+        this.shell = setup.shell;
+    }
+    async getTuple(config) {
+        return guardPublic('saver.getTuple', () => getCheckpointTuple(this.context, config), this.context.tableName);
+    }
+    list(config, options) {
+        return guardPublicIterable('saver.list', listCheckpoints(this.context, config, options), this.context.tableName);
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        return guardPublic('saver.put', () => putCheckpoint(this.context, config, checkpoint, metadata), this.context.tableName);
+    }
+    async putWrites(config, writes, taskId, taskPath) {
+        return guardPublic('saver.putWrites', () => putWritesAction(this.context, config, writes, taskId, taskPath), this.context.tableName);
+    }
+    async deleteThread(threadId, options) {
+        return guardPublic('saver.deleteThread', () => {
+            assertCancelOptions(options);
+            return deleteThreadAction(this.context, threadId, options);
+        }, this.context.tableName);
+    }
+    getDeltaChannelHistory(options) {
+        return guardPublic('saver.getDeltaChannelHistory', () => {
+            const request = parseDeltaHistoryRequest(options);
+            return deltaChannelHistory(this.context, (c) => this.getTuple(c), request.config, request.channels);
+        }, this.context.tableName);
+    }
+    destroy() {
+        guardPublicSync('saver.destroy', () => this.shell.release(), this.context.tableName);
+    }
+    async ensureS3LifecycleRule() {
+        return guardPublic('saver.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule(), this.context.tableName);
+    }
+}

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

@@ -0,0 +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 { BaseAdapterOptions, CodecOptions } from '../shared/options.js';
+/** Options for {@link DynamoDBSaver}. */
+export type DynamoDBSaverOptions = BaseAdapterOptions & CodecOptions & {
+    /**
+     * 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;
+}

package/dist/esm/checkpointer/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/factory/factory.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 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.js';
+import type { DynamoDBSaverOptions } from '../checkpointer/types.js';
+import { DynamoDBChatMessageHistory } from '../history/chat-message-history.js';
+import type { DynamoDBChatMessageHistoryOptions } from '../history/types.js';
+import { DynamoDBStore } from '../store/store.js';
+import type { DynamoDBStoreOptions } from '../store/types.js';
+import type { CreateAllOptions, CreatedAdapters, FactoryBaseOptions } from './types.js';
+/**
+ * Convenience constructors for the adapters.
+ *
+ * Individual `create*` methods each build one adapter, on the factory's `client`
+ * when it was given one and otherwise on a client of their own; {@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;
+    /**
+     * An `s3` config with the region the DynamoDB side was configured with
+     * filled in, when it names none of its own.
+     *
+     * 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. It is asked of the `s3` an adapter ends up with — the base one,
+     * or a section's own, which replaces the base one whole — so neither is left
+     * without the region the other would have had.
+     *
+     * An `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 withTableRegion;
+    /**
+     * 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 the factory's `client` when it has one and otherwise on its own.
+     *
+     * Accepts: `options` — the saver's own, laid over the factory's defaults. A
+     * per-adapter value wins, and a key given as `undefined` is not a value;
+     * a client choice (`client`, `clientConfig` or neither) replaces the
+     * factory's as a unit.
+     *
+     * Returns: the saver. It owns, and releases on `destroy()`, only a client it
+     * built itself; a `client` from the factory is never closed by it.
+     *
+     * 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 the factory's `client` when it has one and otherwise on its own.
+     *
+     * Accepts: as {@link createSaver}, for the store's options.
+     *
+     * Returns: the store.
+     *
+     * Throws: as {@link createSaver}.
+     */
+    createStore(options: DynamoDBStoreOptions): DynamoDBStore;
+    /**
+     * A chat history, on the factory's `client` when it has one and otherwise on
+     * its own.
+     *
+     * Accepts: as {@link createSaver}, for the history's options.
+     *
+     * Returns: the chat history.
+     *
+     * Throws: as {@link createSaver}.
+     */
+    createChatMessageHistory(options: DynamoDBChatMessageHistoryOptions): DynamoDBChatMessageHistory;
+    /**
+     * 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>;
+}