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

package/dist/checkpointer/internal/write-guard.js

@@ -1,16 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reportGuardRejection = reportGuardRejection;
+exports.rejectionProvesForeignRow = rejectionProvesForeignRow;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
 /**
  * The channel recorded on the row that turned a write away, or undefined when
- * the service returned no attributes. `ReturnValuesOnConditionCheckFailure:
- * 'ALL_OLD'` attaches the existing item to the exception at no extra round
- * trip, but — verified against real DynamoDB — the document client does not
- * unmarshall an *error* payload the way it unmarshalls a response, so the
- * attribute arrives in raw AttributeValue form.
+ * the service returned no attributes (`ReturnValuesOnConditionCheckFailure:
+ * 'ALL_OLD'` attaches the existing item to the exception at no extra round trip).
  */
 function rejectedChannel(error) {
-    return error.Item?.channel?.S;
+    return (0, conditional_put_1.rejectedItem)(error)?.channel;
 }
 /**
  * Report a guard rejection. Sort keys carry their channel, so a rejection
@@ -36,4 +35,14 @@ function reportGuardRejection(context, item, error) {
         channel: item.channel,
     });
 }
-//# sourceMappingURL=write-guard.js.map
+/**
+ * True when the guard rejection's returned row provably belongs to another
+ * `putWrites` call, so this call's own upload is dead and safe to delete. A
+ * retried put whose response was lost can be rejected by the row it wrote
+ * itself, so an equal group — or no attributes at all — proves nothing and
+ * must not be taken as "my upload is dead".
+ */
+function rejectionProvesForeignRow(item, error) {
+    const group = (0, conditional_put_1.rejectedItem)(error)?.writeGroup;
+    return group !== undefined && group !== item.writeGroup;
+}

package/dist/checkpointer/internal/write-index.d.ts

@@ -34,4 +34,3 @@ export interface ResolvedWrite {
  * regular, not resolve to an inherited function reference.
  */
 export declare function resolveWriteIndices(writes: PendingWrite[]): ResolvedWrite[];
-//# sourceMappingURL=write-index.d.ts.map

package/dist/checkpointer/internal/write-index.js

@@ -39,4 +39,3 @@ function resolveWriteIndices(writes) {
     });
     return [...bySpecialIndex.values(), ...regular];
 }
-//# sourceMappingURL=write-index.js.map

package/dist/checkpointer/saver.d.ts

@@ -1,30 +1,70 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
-import { BaseCheckpointSaver, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type PendingWrite } from '@langchain/langgraph-checkpoint';
+import { BaseCheckpointSaver, type ChannelVersions, type Checkpoint, type CheckpointListOptions, type CheckpointMetadata, type CheckpointTuple, type PendingWrite } from '@langchain/langgraph-checkpoint';
+import type { CancelOptions } from '../shared/options';
 import type { DynamoDBSaverOptions } from './types';
 /**
  * DynamoDB-backed LangGraph checkpoint saver. A thin orchestrator: it resolves
  * its collaborators once and delegates every operation to a focused action.
+ * Every public method is the library's error boundary — a raw AWS SDK error
+ * escaping an action surfaces as an `UpstreamError`.
  */
 export declare class DynamoDBSaver extends BaseCheckpointSaver {
     private readonly context;
     private readonly ownsClient;
     private readonly ddbClient;
     constructor(options: DynamoDBSaverOptions);
+    /**
+     * Read one checkpoint with its metadata and pending writes: the one
+     * `checkpoint_id` names, else the newest in the namespace. Strongly
+     * consistent, so a checkpoint just written is always seen. Returns
+     * `undefined` for an unknown thread or checkpoint, or a config without a
+     * thread.
+     * @throws ValidationError for a malformed identifier; UpstreamError, RetryExhaustedError, AbortError (`config.signal`).
+     */
     getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    /**
+     * Stream checkpoints newest first: one namespace, every namespace of a
+     * thread when `checkpoint_ns` is omitted, or every thread in the table when
+     * `thread_id` is omitted (a table scan). Eventually consistent. `before`,
+     * `filter` and `limit` follow the reference savers.
+     * @remarks One read per page plus two per yielded tuple (see the README cost table).
+     * @throws ValidationError, UpstreamError, RetryExhaustedError, AbortError.
+     */
     list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
-    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+    /**
+     * Store a checkpoint and its metadata in one transaction and return the
+     * config that addresses it. `config.checkpoint_id` becomes the parent;
+     * `newVersions` names the channels that changed, and only those plus the
+     * ones the parent stored are persisted. Last writer wins for a repeated
+     * `checkpoint_id`.
+     * @throws ValidationError; UpstreamError; RetryExhaustedError; AbortError; S3_OFFLOAD_FAILED when an offloaded payload cannot be uploaded.
+     */
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions?: ChannelVersions): Promise<RunnableConfig>;
+    /**
+     * Store a task's pending writes for the checkpoint `config` names, one row
+     * per write, written in parallel. Regular writes are first-write-wins;
+     * special channels (`__interrupt__`, `__resume__`, `__error__`,
+     * `__scheduled__`) overwrite, guarded so two concurrent calls never orphan
+     * an offloaded object.
+     * @throws ValidationError when `checkpoint_id` is missing or a channel is malformed; UpstreamError; RetryExhaustedError; AbortError.
+     */
     putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
-    deleteThread(threadId: string): Promise<void>;
+    /**
+     * Delete every checkpoint, payload and pending write of a thread and their
+     * offloaded objects. Single pass: call it when the thread is quiescent.
+     * @throws BatchWriteAllIncompleteError when a delete batch does not fully drain; UpstreamError; AbortError (`options.signal`).
+     */
+    deleteThread(threadId: string, options?: CancelOptions): Promise<void>;
     /** Release owned resources (the underlying client and any S3 client). */
     destroy(): void;
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever. No-ops when
+     * S3 offload or TTL isn't configured; throws when the bucket cannot be read
+     * or written. 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.
      */
     ensureS3LifecycleRule(): Promise<void>;
 }
-//# sourceMappingURL=saver.d.ts.map

package/dist/checkpointer/saver.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBSaver = void 0;
 const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const boundary_1 = require("../shared/errors/boundary");
 const ttl_1 = require("../shared/validation/ttl");
 const delete_thread_1 = require("./actions/delete-thread");
 const get_tuple_1 = require("./actions/get-tuple");
@@ -12,6 +13,8 @@ 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.
+ * Every public method is the library's error boundary — a raw AWS SDK error
+ * escaping an action surfaces as an `UpstreamError`.
  */
 class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
     context;
@@ -24,20 +27,57 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
         this.ownsClient = setup.ownsClient;
         this.ddbClient = setup.ddbClient;
     }
+    /**
+     * Read one checkpoint with its metadata and pending writes: the one
+     * `checkpoint_id` names, else the newest in the namespace. Strongly
+     * consistent, so a checkpoint just written is always seen. Returns
+     * `undefined` for an unknown thread or checkpoint, or a config without a
+     * thread.
+     * @throws ValidationError for a malformed identifier; UpstreamError, RetryExhaustedError, AbortError (`config.signal`).
+     */
     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: one namespace, every namespace of a
+     * thread when `checkpoint_ns` is omitted, or every thread in the table when
+     * `thread_id` is omitted (a table scan). Eventually consistent. `before`,
+     * `filter` and `limit` follow the reference savers.
+     * @remarks One read per page plus two per yielded tuple (see the README cost table).
+     * @throws ValidationError, UpstreamError, RetryExhaustedError, AbortError.
+     */
     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 and return the
+     * config that addresses it. `config.checkpoint_id` becomes the parent;
+     * `newVersions` names the channels that changed, and only those plus the
+     * ones the parent stored are persisted. Last writer wins for a repeated
+     * `checkpoint_id`.
+     * @throws ValidationError; UpstreamError; RetryExhaustedError; AbortError; S3_OFFLOAD_FAILED when an offloaded payload cannot be uploaded.
+     */
+    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, one row
+     * per write, written in parallel. Regular writes are first-write-wins;
+     * special channels (`__interrupt__`, `__resume__`, `__error__`,
+     * `__scheduled__`) overwrite, guarded so two concurrent calls never orphan
+     * an offloaded object.
+     * @throws ValidationError when `checkpoint_id` is missing or a channel is malformed; UpstreamError; RetryExhaustedError; AbortError.
+     */
     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 and their
+     * offloaded objects. Single pass: call it when the thread is quiescent.
+     * @throws BatchWriteAllIncompleteError when a delete batch does not fully drain; UpstreamError; AbortError (`options.signal`).
+     */
+    async deleteThread(threadId, options) {
+        return (0, boundary_1.guardPublic)('saver.deleteThread', () => (0, delete_thread_1.deleteThread)(this.context, threadId, options));
     }
     /** Release owned resources (the underlying client and any S3 client). */
     destroy() {
@@ -46,18 +86,20 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
             this.ddbClient?.destroy();
     }
     /**
-     * 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 objects don't outlive their DynamoDB item forever. No-ops when
+     * S3 offload or TTL isn't configured; throws when the bucket cannot be read
+     * or written. 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.
      */
     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', async () => {
+            if (!this.context.offloader || !this.context.ttl)
+                return;
+            await this.context.offloader.ensureLifecycleRule((0, ttl_1.lifecycleExpirationDays)(this.context.ttl));
+        });
     }
 }
 exports.DynamoDBSaver = DynamoDBSaver;
-//# sourceMappingURL=saver.js.map

package/dist/checkpointer/types.d.ts

@@ -11,6 +11,8 @@ 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 {
@@ -21,6 +23,12 @@ export interface CheckpointMetaItem {
     checkpointId: string;
     parentCheckpointId?: string;
     metadata: PayloadDescriptor;
+    /**
+     * The channels whose values the PAYLOAD row holds: those the put's
+     * `newVersions` named plus those carried over from the parent. Absent on
+     * rows written before this attribute, which hold every value they were given.
+     */
+    storedChannels?: string[];
     ttl?: number;
 }
 /** The heavy `PAYLOAD#` item: the serialized checkpoint. */
@@ -48,4 +56,3 @@ export interface CheckpointWriteItem {
     value: PayloadDescriptor;
     ttl?: number;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/checkpointer/types.js

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

package/dist/factory/factory.d.ts

@@ -1,32 +1,10 @@
-import type { DynamoDBClient, DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
-import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 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
@@ -35,9 +13,28 @@ export interface CreatedAdapters {
 export declare class DynamoDBFactory {
     private readonly base;
     constructor(base?: FactoryBaseOptions);
+    /** The base options every adapter inherits regardless of which client it uses. */
+    private sharedDefaults;
+    /**
+     * 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, with the factory's shared defaults underneath `options`. */
     createSaver(options: DynamoDBSaverOptions): DynamoDBSaver;
+    /** A store on its own client, with the factory's shared defaults underneath `options`. */
     createStore(options: DynamoDBStoreOptions): DynamoDBStore;
+    /** A chat history on its own client, with the factory's shared defaults underneath `options`. */
     createChatMessageHistory(options: DynamoDBChatMessageHistoryOptions): DynamoDBChatMessageHistory;
-    createAll(options: CreateAllOptions): CreatedAdapters;
+    /**
+     * Build the adapters whose sections are given, all on one shared client and
+     * with the factory's shared defaults underneath each section. If any
+     * constructor throws (a store with `vectorBackend` but no `index`, say), the
+     * adapters already built and the freshly created client are destroyed
+     * before the error propagates, so a failed call leaks nothing.
+     */
+    createAll<O extends CreateAllOptions>(options: O): CreatedAdapters<O>;
 }
-//# sourceMappingURL=factory.d.ts.map

package/dist/factory/factory.js

@@ -5,6 +5,11 @@ const saver_1 = require("../checkpointer/saver");
 const chat_message_history_1 = require("../history/chat-message-history");
 const client_1 = require("../shared/dynamodb/client");
 const store_1 = require("../store/store");
+function overridesClient(options) {
+    return (options.client !== undefined ||
+        options.clientConfig !== undefined ||
+        options.createClient !== undefined);
+}
 /**
  * Convenience constructors for the adapters. Individual `create*` methods each
  * build their own client; {@link createAll} builds one shared client used by all
@@ -15,33 +20,68 @@ class DynamoDBFactory {
     constructor(base = {}) {
         this.base = base;
     }
+    /** The base options every adapter inherits regardless of which client it uses. */
+    sharedDefaults() {
+        const { logger, ttl, compression, s3, retry } = this.base;
+        return { logger, ttl, compression, s3, retry };
+    }
+    /**
+     * 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.
+     */
+    defaultsFor(options) {
+        return overridesClient(options) ? this.sharedDefaults() : this.base;
+    }
+    /** A saver on its own client, with the factory's shared defaults underneath `options`. */
     createSaver(options) {
-        return new saver_1.DynamoDBSaver({ ...this.base, ...options });
+        return new saver_1.DynamoDBSaver({ ...this.defaultsFor(options), ...options });
     }
+    /** A store on its own client, with the factory's shared defaults underneath `options`. */
     createStore(options) {
-        return new store_1.DynamoDBStore({ ...this.base, ...options });
+        return new store_1.DynamoDBStore({ ...this.defaultsFor(options), ...options });
     }
+    /** A chat history on its own client, with the factory's shared defaults underneath `options`. */
     createChatMessageHistory(options) {
-        return new chat_message_history_1.DynamoDBChatMessageHistory({ ...this.base, ...options });
+        return new chat_message_history_1.DynamoDBChatMessageHistory({ ...this.defaultsFor(options), ...options });
     }
+    /**
+     * Build the adapters whose sections are given, all on one shared client and
+     * with the factory's shared defaults underneath each section. If any
+     * constructor throws (a store with `vectorBackend` but no `index`, say), the
+     * adapters already built and the freshly created client are destroyed
+     * before the error propagates, so a failed call leaks nothing.
+     */
     createAll(options) {
         const resolved = (0, client_1.resolveDynamoDBClient)(this.base);
-        const client = resolved.client;
-        const saver = new saver_1.DynamoDBSaver({ ...this.base, ...options.saver, client });
-        const store = new store_1.DynamoDBStore({ ...this.base, ...options.store, client });
-        const history = new chat_message_history_1.DynamoDBChatMessageHistory({ ...this.base, ...options.history, client });
-        return {
-            saver,
-            store,
-            history,
-            destroy: () => {
-                saver.destroy();
-                store.destroy();
-                history.destroy();
-                resolved.ddbClient?.destroy();
-            },
+        const shared = { ...this.sharedDefaults(), client: resolved.client };
+        const built = [];
+        /** Record an adapter the moment it exists, so a later failure can still tear it down. */
+        const track = (adapter) => {
+            built.push(adapter);
+            return adapter;
+        };
+        const destroy = () => {
+            for (const adapter of built)
+                adapter.destroy();
+            resolved.ddbClient?.destroy();
         };
+        const { saver, store, history } = options;
+        try {
+            const adapters = {
+                saver: saver && track(new saver_1.DynamoDBSaver({ ...shared, ...saver })),
+                store: store && track(new store_1.DynamoDBStore({ ...shared, ...store })),
+                history: history && track(new chat_message_history_1.DynamoDBChatMessageHistory({ ...shared, ...history })),
+                destroy,
+            };
+            return adapters;
+        }
+        catch (error) {
+            destroy();
+            throw error;
+        }
     }
 }
 exports.DynamoDBFactory = DynamoDBFactory;
-//# sourceMappingURL=factory.js.map

package/dist/factory/types.d.ts

@@ -0,0 +1,57 @@
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import type { DynamoDBDocument } from '@aws-sdk/lib-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 { RetryPolicy } from '../shared/dynamodb/retry-policy';
+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';
+/**
+ * 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
+ * across its checkpointer, store and history. A per-adapter option wins.
+ */
+export interface FactoryBaseOptions {
+    /**
+     * Reused as-is by every adapter. Construct it with `maxAttempts: 1`, or the
+     * SDK's own retries stack inside the library's retry budget (each adapter
+     * logs a `warn` at construction when they would).
+     */
+    client?: DynamoDBDocument;
+    clientConfig?: DynamoDBClientConfig;
+    logger?: Logger;
+    ttl?: TtlOption;
+    compression?: CompressionConfig;
+    s3?: S3OffloadConfig;
+    retry?: RetryPolicy;
+}
+/** An adapter's own options inside {@link CreateAllOptions}: everything but the shared client. */
+export type AdapterSection<Options> = Omit<Options, 'client' | 'clientConfig' | 'createClient'>;
+/** Per-adapter options for `DynamoDBFactory.createAll`; omit a section to skip that adapter. */
+export interface CreateAllOptions {
+    saver?: AdapterSection<DynamoDBSaverOptions>;
+    store?: AdapterSection<DynamoDBStoreOptions>;
+    history?: AdapterSection<DynamoDBChatMessageHistoryOptions>;
+}
+/**
+ * The adapters `createAll` built, typed by the sections it was given: an
+ * omitted section is `undefined`. The default names the all-three result.
+ */
+export interface CreatedAdapters<O extends CreateAllOptions = Required<CreateAllOptions>> {
+    saver: O extends {
+        saver: object;
+    } ? DynamoDBSaver : undefined;
+    store: O extends {
+        store: object;
+    } ? DynamoDBStore : undefined;
+    history: O extends {
+        history: object;
+    } ? DynamoDBChatMessageHistory : undefined;
+    /** Tear down every built adapter and the shared client, once. */
+    destroy: () => void;
+}

package/dist/factory/types.js

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

package/dist/history/actions/add-messages.d.ts

@@ -12,5 +12,4 @@ import type { HistoryContext } from '../internal/setup';
  * Per item the 400 KB DynamoDB limit still applies; enable S3 offloading so
  * large payloads become small descriptors and stay well under the limits.
  */
-export declare function addMessages(context: HistoryContext, sessionId: string, messages: BaseMessage[]): Promise<void>;
-//# sourceMappingURL=add-messages.d.ts.map
+export declare function addMessages(context: HistoryContext, sessionId: string, messages: BaseMessage[], signal?: AbortSignal): Promise<void>;

package/dist/history/actions/add-messages.js

@@ -57,13 +57,14 @@ async function buildItems(context, sessionId, stored, ttlTimestamp) {
  * Per item the 400 KB DynamoDB limit still applies; enable S3 offloading so
  * large payloads become small descriptors and stay well under the limits.
  */
-async function addMessages(context, sessionId, messages) {
+async function addMessages(context, sessionId, messages, signal) {
     (0, validation_1.validateSessionId)(sessionId);
     if (messages.length === 0)
         return;
     const stored = (0, messages_1.mapChatMessagesToStoredMessages)(messages);
+    (0, validation_1.validateStorableMessages)(stored);
     const anchor = context.ttl
-        ? await (0, ttl_anchor_1.resolveTtlAnchor)(context, sessionId, (0, ttl_1.calculateTtlTimestamp)(context.ttl))
+        ? await (0, ttl_anchor_1.resolveTtlAnchor)(context, sessionId, (0, ttl_1.calculateTtlTimestamp)(context.ttl), signal)
         : undefined;
     const items = await buildItems(context, sessionId, stored, anchor?.ttlTimestamp);
     const chunks = (0, message_chunker_1.chunkBySize)(items, MAX_MESSAGES_PER_TRANSACTION, MAX_TRANSACTION_BYTES);
@@ -72,6 +73,5 @@ async function addMessages(context, sessionId, messages) {
         title: (0, title_generator_1.deriveTitle)(stored),
         ttlTimestamp: anchor?.ttlTimestamp,
         forceTtlRefresh: anchor?.refresh,
-    });
+    }, signal);
 }
-//# sourceMappingURL=add-messages.js.map

package/dist/history/actions/clear.d.ts

@@ -5,5 +5,6 @@ import type { HistoryContext } from '../internal/setup';
  * place and logged, so a shared-table partition holding a foreign row is never
  * collaterally wiped.
  */
-export declare function clearSession(context: HistoryContext, sessionId: string): Promise<void>;
-//# sourceMappingURL=clear.d.ts.map
+export declare function clearSession(context: HistoryContext, sessionId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/history/actions/clear.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearSession = clearSession;
 const partition_delete_1 = require("../../shared/dynamodb/partition-delete");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const keys_1 = require("../internal/keys");
 const query_1 = require("../internal/query");
 const validation_1 = require("../internal/validation");
@@ -15,17 +16,19 @@ function descriptorsOf(row) {
  * place and logged, so a shared-table partition holding a foreign row is never
  * collaterally wiped.
  */
-async function clearSession(context, sessionId) {
+async function clearSession(context, sessionId, options = {}) {
     (0, validation_1.validateSessionId)(sessionId);
     await (0, partition_delete_1.deletePartitionRows)({
         client: context.client,
         tableName: context.tableName,
         params: (0, query_1.sessionItemsQuery)(context.tableName, sessionId, { consistent: true }),
         logger: context.logger,
+        retry: (0, retry_policy_1.retryFor)(context, options.signal),
+        signal: options.signal,
         offloader: context.offloader,
         operation: 'history.clear',
         ownsSortKey: keys_1.isHistorySortKey,
         descriptorsOf,
+        scope: [sessionId],
     });
 }
-//# sourceMappingURL=clear.js.map

package/dist/history/actions/get-messages.d.ts

@@ -1,10 +1,17 @@
 import { type BaseMessage } from '@langchain/core/messages';
+import type { CancelOptions } from '../../shared/options';
 import type { HistoryContext } from '../internal/setup';
+import type { MessageWindow } from '../types';
 /**
- * Return a session's messages in chronological order. Items past their TTL are
- * filtered out on read (DynamoDB's background TTL sweep can lag by up to 48h),
- * so the returned history is never stale. An item that cannot be decoded is
- * handled per `onCorruptMessage` (see {@link decodeOrSkip}).
+ * Return a session's messages in chronological order — the whole session, or
+ * the window `options` selects: `limit` keeps only the newest `limit`
+ * messages, `before` only those appended before that instant (see
+ * {@link readWindow}). Items past their TTL are filtered out on read
+ * (DynamoDB's background TTL sweep can lag by up to 48h), so the returned
+ * history is never stale. A corrupt item — see
+ * {@link decodeMessage} for exactly what counts — is handled per
+ * `onCorruptMessage`: `'throw'` fails the read with the underlying error;
+ * `'skip'` (the default) reports it at `error` with its sort key and returns
+ * the rest. Every other failure propagates regardless of the policy.
  */
-export declare function getMessages(context: HistoryContext, sessionId: string): Promise<BaseMessage[]>;
-//# sourceMappingURL=get-messages.d.ts.map
+export declare function getMessages(context: HistoryContext, sessionId: string, options?: MessageWindow & CancelOptions): Promise<BaseMessage[]>;