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

package/dist/{checkpointer → cjs/checkpointer}/internal/setup.d.ts

@@ -1,30 +1,23 @@
 /**
- * Hides which options the saver and its methods accept, and how the saver is
- * assembled from them.
+ * Hides which options the saver accepts, 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.
+ * The exhaustive key list of the constructor's options lives here,
+ * compiler-checked against its type, beside the code that resolves those
+ * options into the context every action receives. `list`'s and
+ * `getDeltaChannelHistory`'s options have no list: LangGraph defines them, so
+ * a key it adds is ignored rather than refused (decision record 28).
  */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import { type AdapterCore, type AdapterShell } from '../../shared/adapter';
-import type { DynamoDBSaverOptions } from '../types';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter.js';
+import type { DynamoDBSaverOptions } from '../types.js';
 /**
- * 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.
+ * The keys of the saver's constructor options, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so the list
+ * cannot rot away from the type it guards. It lives with the feature because
+ * the type it is checked against does; `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 extends AdapterCore {
     serde: SerializerProtocol;

package/dist/cjs/checkpointer/internal/setup.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAVER_KEYS = void 0;
+exports.setUpCheckpointer = setUpCheckpointer;
+const adapter_js_1 = require("../../shared/adapter.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+exports.SAVER_KEYS = (0, option_shape_js_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',
+});
+function setUpCheckpointer(options, serde) {
+    const shell = (0, adapter_js_1.openAdapter)(options, 'checkpointer');
+    return { shell, context: { ...shell.core, serde } };
+}

package/dist/{checkpointer → cjs/checkpointer}/saver.d.ts

@@ -4,16 +4,17 @@
  * `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.
+ * 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';
-import type { DeltaChannelHistoryOptions, DynamoDBSaverOptions } from './types';
+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
@@ -49,7 +50,7 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      *
      * 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.
+     * 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
@@ -71,7 +72,10 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      */
     getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
     /**
-     * Stream checkpoints newest first.
+     * 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`
@@ -89,15 +93,17 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * `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
+     * 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`.
+     * `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.
@@ -125,9 +131,10 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * 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`.
+     * 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
@@ -135,28 +142,38 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * 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>;
+    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.
+     * `[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; `config`,
+     * 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 `s3Key` for an offloaded object's key over S3's cap.
-     * `S3_OFFLOAD_FAILED`; a classified AWS failure; `RETRY_EXHAUSTED`; `ABORTED`.
+     * 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,
@@ -168,11 +185,13 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * 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>;
+    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` — aborts between pages.
+     * 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.
      *
@@ -207,9 +226,10 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * 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
+     * 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
@@ -221,12 +241,13 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * stored value found.
      *
      * Throws: `VALIDATION` naming `options` for options that are not an
-     * object, `options.<key>` for an unknown key, `config`, `configurable` or
+     * 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; a classified AWS failure; `RETRY_EXHAUSTED`; `ABORTED`, which a walk
+     * 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`.
      *
@@ -243,9 +264,10 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * 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.
+     * 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;
     /**
@@ -257,14 +279,28 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * match.
      *
      * Returns: nothing. Installing a rule that is already there is a no-op too,
-     * so calling it on every deploy is safe.
+     * 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.
+     * 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.
+     * 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/cjs/checkpointer/saver.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBSaver = void 0;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const boundary_js_1 = require("../shared/errors/boundary.js");
+const collaborators_js_1 = require("../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../shared/validation/option-shape.js");
+const delete_thread_js_1 = require("./actions/delete-thread.js");
+const get_tuple_js_1 = require("./actions/get-tuple.js");
+const list_js_1 = require("./actions/list.js");
+const put_writes_js_1 = require("./actions/put-writes.js");
+const put_js_1 = require("./actions/put.js");
+const delta_history_js_1 = require("./internal/delta-history.js");
+const parse_js_1 = require("./internal/parse.js");
+const setup_js_1 = require("./internal/setup.js");
+class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
+    context;
+    shell;
+    constructor(options) {
+        super((0, option_shape_js_1.parseShape)(options, setup_js_1.SAVER_KEYS, 'options').serde);
+        const setup = (0, setup_js_1.setUpCheckpointer)(options, this.serde);
+        this.context = setup.context;
+        this.shell = setup.shell;
+    }
+    async getTuple(config) {
+        return (0, boundary_js_1.guardPublic)('saver.getTuple', () => (0, get_tuple_js_1.getCheckpointTuple)(this.context, config), this.context.tableName);
+    }
+    list(config, options) {
+        return (0, boundary_js_1.guardPublicIterable)('saver.list', (0, list_js_1.listCheckpoints)(this.context, config, options), this.context.tableName);
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        return (0, boundary_js_1.guardPublic)('saver.put', () => (0, put_js_1.putCheckpoint)(this.context, config, checkpoint, metadata), this.context.tableName);
+    }
+    async putWrites(config, writes, taskId, taskPath) {
+        return (0, boundary_js_1.guardPublic)('saver.putWrites', () => (0, put_writes_js_1.putWrites)(this.context, config, writes, taskId, taskPath), this.context.tableName);
+    }
+    async deleteThread(threadId, options) {
+        return (0, boundary_js_1.guardPublic)('saver.deleteThread', () => {
+            (0, collaborators_js_1.assertCancelOptions)(options);
+            return (0, delete_thread_js_1.deleteThread)(this.context, threadId, options);
+        }, this.context.tableName);
+    }
+    getDeltaChannelHistory(options) {
+        return (0, boundary_js_1.guardPublic)('saver.getDeltaChannelHistory', () => {
+            const request = (0, parse_js_1.parseDeltaHistoryRequest)(options);
+            return (0, delta_history_js_1.deltaChannelHistory)(this.context, (c) => this.getTuple(c), request.config, request.channels);
+        }, this.context.tableName);
+    }
+    destroy() {
+        (0, boundary_js_1.guardPublicSync)('saver.destroy', () => this.shell.release(), this.context.tableName);
+    }
+    async ensureS3LifecycleRule() {
+        return (0, boundary_js_1.guardPublic)('saver.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule(), this.context.tableName);
+    }
+}
+exports.DynamoDBSaver = DynamoDBSaver;

package/dist/{checkpointer → cjs/checkpointer}/types.d.ts

@@ -10,7 +10,7 @@
  */
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { BaseAdapterOptions, CodecOptions } from '../shared/options';
+import type { BaseAdapterOptions, CodecOptions } from '../shared/options.js';
 /** Options for {@link DynamoDBSaver}. */
 export type DynamoDBSaverOptions = BaseAdapterOptions & CodecOptions & {
     /**

package/dist/cjs/checkpointer/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/{factory → cjs/factory}/factory.d.ts

@@ -8,17 +8,18 @@
  * 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 { DynamoDBStore } from '../store/store';
-import type { DynamoDBStoreOptions } from '../store/types';
-import type { CreateAllOptions, CreatedAdapters, FactoryBaseOptions } from './types';
+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 their own client; {@link createAll}
+ * 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
@@ -55,8 +56,8 @@ export declare class DynamoDBFactory {
     /** 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 `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
@@ -66,15 +67,17 @@ export declare class DynamoDBFactory {
      * 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.
+     * 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.
      *
-     * A base `s3`, or its `clientConfig`, that is not an object is handed on
+     * 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 sharedS3;
+    private withTableRegion;
     /**
      * Per-adapter options replace the factory's client choice as a unit: a
      * `client` handed to `createSaver` also displaces the base `clientConfig`
@@ -84,14 +87,15 @@ export declare class DynamoDBFactory {
      */
     private defaultsFor;
     /**
-     * A saver on its own client.
+     * 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; see {@link defaultsFor} for how a client choice
-     * replaces the factory's as a unit.
+     * 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, which owns the client it built and releases it on
-     * `destroy()`.
+     * 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
@@ -101,7 +105,7 @@ export declare class DynamoDBFactory {
      */
     createSaver(options: DynamoDBSaverOptions): DynamoDBSaver;
     /**
-     * A store on its own client.
+     * 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.
      *
@@ -111,7 +115,8 @@ export declare class DynamoDBFactory {
      */
     createStore(options: DynamoDBStoreOptions): DynamoDBStore;
     /**
-     * A chat history on its own client.
+     * 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.
      *

package/dist/cjs/factory/factory.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBFactory = void 0;
+const saver_js_1 = require("../checkpointer/saver.js");
+const chat_message_history_js_1 = require("../history/chat-message-history.js");
+const client_types_js_1 = require("../shared/codec/s3/client-types.js");
+const client_js_1 = require("../shared/dynamodb/client.js");
+const base_error_js_1 = require("../shared/errors/base-error.js");
+const logger_js_1 = require("../shared/logging/logger.js");
+const truncate_js_1 = require("../shared/logging/truncate.js");
+const collaborators_js_1 = require("../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../shared/validation/option-shape.js");
+const options_js_1 = require("../shared/validation/options.js");
+const store_js_1 = require("../store/store.js");
+const FACTORY_BASE_KEYS = (0, option_shape_js_1.allKeysOf)({
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    logger: 'logger',
+    ttl: 'ttl',
+    compression: 'compression',
+    s3: 's3',
+    retry: 'retry',
+});
+const CREATE_ALL_KEYS = (0, option_shape_js_1.allKeysOf)({
+    saver: 'saver',
+    store: 'store',
+    history: 'history',
+});
+function release(logger, close) {
+    try {
+        close();
+    }
+    catch (error) {
+        logger.warn('factory.destroy: an adapter did not release its resources', {
+            reason: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(error)),
+        });
+    }
+}
+function overridesClient(options) {
+    return (options.client !== undefined ||
+        options.clientConfig !== undefined ||
+        options.createClient !== undefined);
+}
+function given(options) {
+    const kept = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined)
+            kept[key] = value;
+    }
+    return kept;
+}
+class DynamoDBFactory {
+    base;
+    constructor(base = {}) {
+        this.base = base;
+        (0, option_shape_js_1.assertShape)(base, FACTORY_BASE_KEYS, 'options');
+        (0, options_js_1.assertClientChoice)(base);
+        if (base.logger !== undefined)
+            (0, collaborators_js_1.assertMembers)(base.logger, collaborators_js_1.LOGGER_MEMBERS, 'logger');
+    }
+    sharedDefaults() {
+        const { logger, ttl, compression, s3, retry } = this.base;
+        return { logger, ttl, compression, s3, retry };
+    }
+    withTableRegion(s3) {
+        if (!(0, option_shape_js_1.isObjectShape)(s3))
+            return s3;
+        if (s3.clientConfig !== undefined && !(0, option_shape_js_1.isObjectShape)(s3.clientConfig))
+            return s3;
+        const region = (0, client_types_js_1.s3ClientOptions)(s3.clientConfig).region ?? this.base.clientConfig?.region;
+        if (region === undefined)
+            return s3;
+        return { ...s3, clientConfig: { ...s3.clientConfig, region } };
+    }
+    defaultsFor(options) {
+        return overridesClient(options) ? this.sharedDefaults() : this.base;
+    }
+    createSaver(options) {
+        (0, option_shape_js_1.assertObjectShape)(options, 'options');
+        const own = given(options);
+        return new saver_js_1.DynamoDBSaver({ ...this.defaultsFor(own), ...own });
+    }
+    createStore(options) {
+        (0, option_shape_js_1.assertObjectShape)(options, 'options');
+        const own = given(options);
+        return new store_js_1.DynamoDBStore({ ...this.defaultsFor(own), ...own });
+    }
+    createChatMessageHistory(options) {
+        (0, option_shape_js_1.assertObjectShape)(options, 'options');
+        const own = given(options);
+        return new chat_message_history_js_1.DynamoDBChatMessageHistory({ ...this.defaultsFor(own), ...own });
+    }
+    createAll(options) {
+        (0, option_shape_js_1.assertShape)(options, CREATE_ALL_KEYS, 'options');
+        const { saver, store, history } = options;
+        for (const section of [saver, store, history]) {
+            if (section !== undefined)
+                (0, option_shape_js_1.assertObjectShape)(section, 'options');
+        }
+        const logger = (0, logger_js_1.resolveLogger)(this.base.logger);
+        const resolved = (0, client_js_1.resolveDynamoDBClient)(this.base);
+        const shared = { ...this.sharedDefaults(), client: resolved.client };
+        const onSharedClient = (section) => {
+            const options = { ...shared, ...given(section) };
+            return { ...options, s3: this.withTableRegion(options.s3) };
+        };
+        const built = [];
+        const track = (adapter) => {
+            built.push(adapter);
+            return adapter;
+        };
+        let destroyed = false;
+        const destroy = () => {
+            if (destroyed)
+                return;
+            destroyed = true;
+            for (const adapter of built)
+                release(logger, () => adapter.destroy());
+            release(logger, () => resolved.ddbClient?.destroy());
+        };
+        try {
+            const adapters = {
+                saver: saver && track(new saver_js_1.DynamoDBSaver(onSharedClient(saver))),
+                store: store && track(new store_js_1.DynamoDBStore(onSharedClient(store))),
+                history: history && track(new chat_message_history_js_1.DynamoDBChatMessageHistory(onSharedClient(history))),
+                destroy,
+            };
+            return adapters;
+        }
+        catch (error) {
+            destroy();
+            throw error;
+        }
+    }
+}
+exports.DynamoDBFactory = DynamoDBFactory;

package/dist/{factory → cjs/factory}/types.d.ts

@@ -7,18 +7,18 @@
  * compiler knows which adapters it got without a runtime check.
  */
 import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
-import type { DynamoDBSaver } from '../checkpointer/saver';
-import type { DynamoDBSaverOptions } from '../checkpointer/types';
-import type { DynamoDBChatMessageHistory } from '../history/chat-message-history';
-import type { DynamoDBChatMessageHistoryOptions } from '../history/types';
-import type { CompressionConfig } from '../shared/codec/compression';
-import type { S3OffloadConfig } from '../shared/codec/s3/config';
-import type { DynamoDBDocumentLike } from '../shared/dynamodb/client';
-import type { RetryPolicy } from '../shared/dynamodb/retry';
-import type { Logger } from '../shared/logging/logger';
-import type { TtlOption } from '../shared/validation/ttl';
-import type { DynamoDBStore } from '../store/store';
-import type { DynamoDBStoreOptions } from '../store/types';
+import type { DynamoDBSaver } from '../checkpointer/saver.js';
+import type { DynamoDBSaverOptions } from '../checkpointer/types.js';
+import type { DynamoDBChatMessageHistory } from '../history/chat-message-history.js';
+import type { DynamoDBChatMessageHistoryOptions } from '../history/types.js';
+import type { CompressionConfig } from '../shared/codec/compression.js';
+import type { S3OffloadConfig } from '../shared/codec/s3/config.js';
+import type { DynamoDBDocumentLike } from '../shared/dynamodb/client.js';
+import type { RetryPolicy } from '../shared/dynamodb/retry.js';
+import type { Logger } from '../shared/logging/logger.js';
+import type { TtlOption } from '../shared/validation/ttl.js';
+import type { DynamoDBStore } from '../store/store.js';
+import type { DynamoDBStoreOptions } from '../store/types.js';
 /**
  * Defaults applied to every adapter the factory builds: the client (or how to
  * build one) and the cross-cutting options a team usually wants identical

package/dist/cjs/factory/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });