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

package/dist/esm/history/internal/setup.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Hides which options the history and its methods accept, and how the history
+ * is assembled from them.
+ *
+ * The exhaustive key list of every option bag — the constructor's,
+ * `getMessages`', `listSessions`' — lives here, compiler-checked against its
+ * type, beside the code that resolves the constructor's options into the
+ * context every action receives.
+ */
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter.js';
+import type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions } from '../types.js';
+/**
+ * Max attempts for the message-append transaction. It shares one session's
+ * metadata row across every concurrent `addMessages` caller on that session,
+ * so a burst of concurrent appends can collide repeatedly; combined with the
+ * existing 100ms base / 5000ms cap backoff, this keeps worst-case retrying
+ * within AWS's documented guidance to bound conflict retries to "around one
+ * minute" (see DynamoDB's "Error retries and exponential backoff" guide).
+ * This bound is exact for clients this library constructs, which disable the
+ * AWS SDK's own internal retries (`maxAttempts: 1`, see
+ * `resolveDynamoDBClient`). An injected client that keeps SDK retries stacks
+ * them inside each attempt; construction warns about that.
+ */
+export declare const MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
+/**
+ * The keys of each chat-history option bag, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
+ * cannot rot away from the type it guards. They live with the feature because
+ * the types they are checked against do; `shared/` knows no feature.
+ */
+export declare const HISTORY_KEYS: readonly string[];
+/** See {@link HISTORY_KEYS}. */
+export declare const GET_MESSAGES_KEYS: readonly string[];
+/** See {@link HISTORY_KEYS}. */
+export declare const LIST_SESSIONS_KEYS: readonly string[];
+/** Resolved collaborators shared by every chat-history action. */
+export interface HistoryContext extends AdapterCore {
+    serde: SerializerProtocol;
+    ulid: () => string;
+    onCorruptMessage: CorruptMessagePolicy;
+}
+/** Result of wiring up a chat-history adapter from its options. */
+export interface HistorySetup {
+    context: HistoryContext;
+    shell: AdapterShell;
+}
+/**
+ * Validate the options, then resolve the client, offloader and serializer.
+ *
+ * Accepts: `options` — validated first, so no half-built adapter exists when
+ * one is wrong. `onCorruptMessage` is checked against its union here because a
+ * JavaScript caller can pass a string the type never admits, and an
+ * unrecognised policy would silently behave as `'skip'` — dropping messages a
+ * caller asked to be told about.
+ *
+ * Returns: the context every action shares, and the shell that releases what
+ * it holds — a client the caller passed in is never destroyed by `destroy()`.
+ *
+ * Throws: `VALIDATION` naming the offending option.
+ *
+ * Guarantees: constructing an adapter performs no I/O.
+ */
+export declare function setUpHistory(options: DynamoDBChatMessageHistoryOptions): HistorySetup;

package/dist/esm/history/internal/setup.js

@@ -0,0 +1,56 @@
+import { openAdapter } from '../../shared/adapter.js';
+import { JSON_SERDE } from '../../shared/codec/json-serde.js';
+import { validationError } from '../../shared/errors/errors.js';
+import { createUlidFactory } from '../../shared/ulid.js';
+import { allKeysOf, assertShape } from '../../shared/validation/option-shape.js';
+export const MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
+export const HISTORY_KEYS = 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',
+    onCorruptMessage: 'onCorruptMessage',
+});
+export const GET_MESSAGES_KEYS = allKeysOf({
+    limit: 'limit',
+    before: 'before',
+    signal: 'signal',
+});
+export const LIST_SESSIONS_KEYS = allKeysOf({
+    limit: 'limit',
+    cursor: 'cursor',
+    maxIterations: 'maxIterations',
+    maxItems: 'maxItems',
+    signal: 'signal',
+});
+const CORRUPT_MESSAGE_POLICIES = ['skip', 'throw'];
+function assertCorruptMessagePolicy(policy) {
+    if (policy !== undefined && !CORRUPT_MESSAGE_POLICIES.includes(policy)) {
+        throw validationError(`onCorruptMessage must be one of ${CORRUPT_MESSAGE_POLICIES.join(' | ')}`, 'onCorruptMessage');
+    }
+}
+export function setUpHistory(options) {
+    assertShape(options, HISTORY_KEYS, 'options');
+    const shell = openAdapter(options, 'history', {
+        options: () => assertCorruptMessagePolicy(options.onCorruptMessage),
+        attemptFloor: MESSAGE_APPEND_RETRY_MAX_ATTEMPTS,
+    });
+    return {
+        shell,
+        context: {
+            ...shell.core,
+            serde: options.serde ?? JSON_SERDE,
+            ulid: createUlidFactory(),
+            onCorruptMessage: options.onCorruptMessage ?? 'skip',
+        },
+    };
+}

package/dist/esm/history/session-adapter.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Hides a multi-session history behind LangChain's single-session interface.
+ *
+ * `RunnableWithMessageHistory` wants a history bound to one conversation and
+ * calls it with no session id. This view fixes the session and the read window
+ * at construction, validates both there, and forwards each call to the
+ * multi-session history it wraps, through the same error boundary. The window
+ * bounds what a chain reads, never what is written or cleared.
+ */
+import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
+import type { BaseMessage } from '@langchain/core/messages';
+/** The read window an adapter applies to every `getMessages`. */
+export type AdapterWindow = {
+    limit?: number;
+};
+/**
+ * A history holding many sessions, addressed by session id: what a
+ * single-session adapter wraps. `DynamoDBChatMessageHistory` is one.
+ */
+export interface MultiSessionHistory {
+    getMessages(sessionId: string, window?: AdapterWindow): Promise<BaseMessage[]>;
+    addMessages(sessionId: string, messages: BaseMessage[]): Promise<void>;
+    clear(sessionId: string): Promise<void>;
+}
+/**
+ * Single-session view over a {@link MultiSessionHistory}, implementing LangChain's
+ * `BaseListChatMessageHistory` so it can drive `RunnableWithMessageHistory`.
+ * A `window` bounds what every read hands the chain — `{ limit: 50 }` feeds it
+ * the newest fifty messages instead of the whole session.
+ */
+export declare class DynamoDBSessionChatMessageHistory extends BaseListChatMessageHistory {
+    private readonly backend;
+    lc_namespace: string[];
+    private readonly sessionId;
+    private readonly window;
+    /**
+     * Accepts: `backend` — the multi-session adapter this view delegates to,
+     * checked structurally for {@link MultiSessionHistory}'s own members. `sessionId`
+     * — the one session it is bound to, validated the same way every other
+     * adapter method validates a session id. `window` — bounds every read it
+     * performs; when given, only the `limit` key `AdapterWindow` declares, an
+     * integer from 1 to the package's page ceiling. `0` is refused: this window
+     * is what `RunnableWithMessageHistory` reads on every invocation, and an
+     * empty one is indistinguishable from a conversation that never happened.
+     *
+     * Returns: the view. Normally built through
+     * `DynamoDBChatMessageHistory.forSession`, which is the supported route.
+     * The adapter keeps the window it parsed, not the caller's object, so
+     * changing that object afterwards changes nothing.
+     *
+     * Throws: `VALIDATION` naming `backend`, `backend.<member>` for the first
+     * missing method, `sessionId`, `window` for a window that is not an object,
+     * `window.<key>` for a key `AdapterWindow` does not declare, or `limit`. Checking here reports a caller's mistake at
+     * construction instead of rebranding it as an upstream failure on first use.
+     */
+    constructor(backend: MultiSessionHistory, sessionId: string, window?: AdapterWindow);
+    /**
+     * This session's messages in chronological order.
+     *
+     * Accepts: nothing — the session and the window are fixed at construction,
+     * which is what `BaseListChatMessageHistory` requires.
+     *
+     * Returns: the messages, bounded by the adapter's window. LangChain calls
+     * this on every chain invocation, so the window is what keeps a long session
+     * from growing the prompt without limit.
+     *
+     * Throws: whatever the backend's `getMessages` throws, wrapped with
+     * the code the classifier assigns unless it is already one of this library's
+     * own errors.
+     */
+    getMessages(): Promise<BaseMessage[]>;
+    /**
+     * Append one message to this session.
+     *
+     * Accepts: `message` — a LangChain message.
+     *
+     * Returns: nothing.
+     *
+     * Throws: as {@link addMessages}.
+     */
+    addMessage(message: BaseMessage): Promise<void>;
+    /**
+     * Append messages to this session.
+     *
+     * Accepts: `messages` — LangChain messages; an empty list writes nothing.
+     *
+     * Returns: nothing, and only once every message has landed.
+     *
+     * Throws: whatever the backend's `addMessages` throws, wrapped with
+     * the code the classifier assigns unless it is already one of this library's
+     * own errors.
+     *
+     * Guarantees: the window bounds what is *read*, never what is written — the
+     * session keeps every message appended to it.
+     */
+    addMessages(messages: BaseMessage[]): Promise<void>;
+    /**
+     * Delete this session's messages, metadata and offloaded objects.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Clearing a session that does not exist is not an error.
+     *
+     * Throws: whatever the backend's `clear` throws, wrapped with the code the
+     * classifier assigns unless it is already one of this library's own errors.
+     *
+     * Guarantees: the whole session goes, not the window.
+     * `BaseListChatMessageHistory` declares `clear()`, and a chain that calls it
+     * is asking for exactly that.
+     */
+    clear(): Promise<void>;
+}

package/dist/esm/history/session-adapter.js

@@ -0,0 +1,34 @@
+import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
+import { guardPublic } from '../shared/errors/boundary.js';
+import { assertMembers } from '../shared/validation/collaborators.js';
+import { allKeysOf, assertShape } from '../shared/validation/option-shape.js';
+import { parseMessageWindow, parseSessionId, } from './internal/parse.js';
+const ADAPTER_WINDOW_KEYS = allKeysOf({ limit: 'limit' });
+const MULTI_SESSION_HISTORY_MEMBERS = ['getMessages', 'addMessages', 'clear'];
+export class DynamoDBSessionChatMessageHistory extends BaseListChatMessageHistory {
+    backend;
+    lc_namespace = ['langchain', 'stores', 'message', 'dynamodb'];
+    sessionId;
+    window;
+    constructor(backend, sessionId, window) {
+        super();
+        this.backend = backend;
+        assertMembers(backend, MULTI_SESSION_HISTORY_MEMBERS, 'backend');
+        this.sessionId = parseSessionId(sessionId);
+        if (window !== undefined)
+            assertShape(window, ADAPTER_WINDOW_KEYS, 'window');
+        this.window = window === undefined ? undefined : parseMessageWindow(window);
+    }
+    getMessages() {
+        return guardPublic('session.getMessages', () => this.backend.getMessages(this.sessionId, this.window));
+    }
+    addMessage(message) {
+        return guardPublic('session.addMessage', () => this.backend.addMessages(this.sessionId, [message]));
+    }
+    addMessages(messages) {
+        return guardPublic('session.addMessages', () => this.backend.addMessages(this.sessionId, messages));
+    }
+    clear() {
+        return guardPublic('session.clear', () => this.backend.clear(this.sessionId));
+    }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * Hides the history's implementation from the types a caller names.
+ *
+ * Every option and result of the multi-session history's reads, writes and
+ * listings is declared here, with no run-time code, so a caller can type
+ * what it builds without importing an action, a parser or a row module. The
+ * parsed forms the actions work from belong to the parser and the row
+ * shapes to the modules that own them, so either can change without moving
+ * a published type.
+ */
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options.js';
+/** Options for {@link DynamoDBChatMessageHistory}. */
+export type DynamoDBChatMessageHistoryOptions = BaseAdapterOptions & CodecOptions & {
+    /**
+     * Optional serializer override. The default is the exported `JSON_SERDE`,
+     * plain JSON: what it stores is the JSON projection of a value, and the
+     * README's *Table schema* section tabulates where that differs from the
+     * value itself.
+     */
+    serde?: SerializerProtocol;
+    /**
+     * What `getMessages` does when a stored message cannot be decoded. It
+     * covers a payload nobody can read — bytes that are no longer the form
+     * the row declares, a gone S3 object, a descriptor that is not one — and
+     * a stored message LangChain cannot rebuild. It does not govern a
+     * payload larger than this reader's `compression.maxDecompressedBytes`
+     * or `s3.maxDownloadBytes` (a limit of this reader's, not a lost
+     * payload), nor a serializer declining intact bytes: a `serdeType` the
+     * configured serializer has no grammar for after a config change, like
+     * an `lc` record naming a class outside its allow-list, is reported
+     * under **both** policies, because a payload this reader merely may not
+     * rebuild is not a payload that is gone. `'skip'` (the default) drops
+     * the item, logs it at `error` with its sort key so an operator can
+     * locate it, and returns the rest; `'throw'` fails the whole read, which
+     * is all-or-nothing but leaves the session unreadable until the bad row
+     * is removed out of band.
+     */
+    onCorruptMessage?: CorruptMessagePolicy;
+};
+/** How `getMessages` handles an item it cannot decode. */
+export type CorruptMessagePolicy = 'skip' | 'throw';
+/**
+ * Which slice of a session `getMessages` returns. Both bounds are optional
+ * and combine: `{ limit: 50, before }` is the fifty messages just before
+ * `before`.
+ */
+export interface MessageWindow {
+    /**
+     * Return only the newest `limit` messages — still in chronological order. An
+     * integer from 1 to 10,000: the page rule every `limit` in
+     * this package follows, with the one floor of 1 it has. `0` is refused rather
+     * than answered with nothing, since for a window into a conversation it is
+     * far more likely a bug than a request — and the empty window it would
+     * produce is what a chain reads as the whole session.
+     */
+    limit?: number;
+    /** Return only messages appended before this instant (millisecond precision). */
+    before?: Date;
+}
+/** Options for `getMessages`: the read window plus cancellation. */
+export type GetMessagesOptions = MessageWindow & CancelOptions;
+/** Options for `listSessions`: the page, the scan caps, and cancellation. */
+export interface ListSessionsOptions extends CancelOptions {
+    /**
+     * How many sessions to return, newest-updated first; an integer from 0 to
+     * 10,000.
+     *
+     * With a configured `indexName` it is the page size and defaults to 100.
+     * Without one the read is a table scan that cannot be paged: an explicit
+     * limit still selects the newest N, but omitting it returns every session,
+     * because there would be no cursor to fetch the rest with. `0` returns an
+     * empty page on either path and reads neither.
+     */
+    limit?: number;
+    /**
+     * Opaque cursor from a previous page. Requires a configured `indexName` —
+     * without the index there is no position to resume from, and passing one is
+     * refused rather than answered with the first page again.
+     */
+    cursor?: string;
+    /** Cap on scan pages before `RESULT_TRUNCATED` (default 1000). Scan path only. */
+    maxIterations?: number;
+    /** Cap on rows read into memory before `RESULT_TRUNCATED` (default 10 000). Scan path only. */
+    maxItems?: number;
+}
+/** One page of {@link SessionMetadata}, and where the next one resumes. */
+export interface SessionPage {
+    sessions: SessionMetadata[];
+    /** Absent when this page is the last one, or when the read was a scan. */
+    nextCursor?: string;
+}
+/** Summary of a stored chat session. */
+export interface SessionMetadata {
+    sessionId: string;
+    title?: string;
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+    /** When the session's TTL expires, as an ISO-8601 instant; absent when no TTL is stored. */
+    expiresAt?: string;
+}

package/dist/esm/history/types.js

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

package/dist/esm/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AWS DynamoDB implementation of LangGraph's checkpoint saver, memory store
+ * and chat message history, in TypeScript.
+ *
+ * Hides where anything lives.
+ *
+ * This module re-exports and declares nothing of its own, so which module
+ * holds an adapter, the factory, the error class, the serializer or a
+ * collaborator type is free to change without moving anything a caller
+ * imports. What appears here is the whole supported surface; the package's
+ * exports map admits no deep import, so nothing else is reachable.
+ *
+ * @packageDocumentation
+ */
+export { DynamoDBSaver } from './checkpointer/saver.js';
+export type { DeltaChannelHistoryOptions, DynamoDBSaverOptions } from './checkpointer/types.js';
+export { DynamoDBStore } from './store/store.js';
+export type { DynamoDBStoreOptions, ListNamespacesOptions, SearchOptions, VectorReconcileResult, } from './store/types.js';
+export type { VectorBackend, VectorMatch, VectorRef, VectorScoreDirection, } from './store/vector-backend.js';
+export { DynamoDBChatMessageHistory } from './history/chat-message-history.js';
+export { DynamoDBSessionChatMessageHistory } from './history/session-adapter.js';
+export type { AdapterWindow, MultiSessionHistory } from './history/session-adapter.js';
+export type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionPage, MessageWindow, SessionMetadata, } from './history/types.js';
+/**
+ * Operator tool: give rows written before the recency index their index keys.
+ * Run it before setting `indexName` on any adapter — see its own documentation
+ * for why enabling the index first hides pre-existing rows from the listings.
+ */
+export { backfillRecencyIndex } from './backfill/backfill.js';
+export type { BackfillOptions, BackfillResult } from './backfill/backfill.js';
+export { DynamoDBFactory } from './factory/factory.js';
+export type { AdapterSection, CreateAllOptions, CreatedAdapters, FactoryBaseOptions, } from './factory/types.js';
+/**
+ * The plain JSON serializer the store and chat-history adapters use by
+ * default, exported so a checkpointer can be given it in place of LangGraph's
+ * `JsonPlusSerializer`, whose read path instantiates the class a stored
+ * `{"lc": …}` record names. See the README's *Trust boundary* note and
+ * `SECURITY.md`.
+ */
+export { JSON_SERDE } from './shared/codec/json-serde.js';
+export { DynamoDBLangGraphError, isDynamoDBLangGraphError } from './shared/errors/base-error.js';
+export type { AnyDynamoDBLangGraphError, BatchDrainDetails, BatchPassDetails, BatchWriteIncompleteDetails, CompensationFailedDetails, ErrorContext, ErrorDetailsByCode, ErrorDetailsFor, } from './shared/errors/base-error.js';
+export { ErrorCode } from './shared/errors/error-code.js';
+export type { Logger, LogArgument } from './shared/logging/logger.js';
+export { redactLogger, redactSecrets } from './shared/logging/redaction.js';
+export type { Redactable, RedactLoggerOptions } from './shared/logging/redaction.js';
+export type { CancelOptions, BaseAdapterOptions, CodecOptions } from './shared/options.js';
+export type { DynamoDBDocumentLike, WriteRequest } from './shared/dynamodb/client.js';
+export type { RetryAttemptInfo, RetryOptions, RetryPolicy } from './shared/dynamodb/retry.js';
+export type { TtlOption } from './shared/validation/ttl.js';
+export type { CompressionConfig } from './shared/codec/compression.js';
+export type { S3OffloadConfig } from './shared/codec/s3/config.js';
+export type { S3ClientConfigLike, S3ClientOption, S3ClientOptions, S3RegionLike, } from './shared/codec/s3/client-types.js';

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+export { DynamoDBSaver } from './checkpointer/saver.js';
+export { DynamoDBStore } from './store/store.js';
+export { DynamoDBChatMessageHistory } from './history/chat-message-history.js';
+export { DynamoDBSessionChatMessageHistory } from './history/session-adapter.js';
+export { backfillRecencyIndex } from './backfill/backfill.js';
+export { DynamoDBFactory } from './factory/factory.js';
+export { JSON_SERDE } from './shared/codec/json-serde.js';
+export { DynamoDBLangGraphError, isDynamoDBLangGraphError } from './shared/errors/base-error.js';
+export { ErrorCode } from './shared/errors/error-code.js';
+export { redactLogger, redactSecrets } from './shared/logging/redaction.js';

package/dist/esm/shared/adapter.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Hides what an adapter owns for its lifetime, and how it lets go of it.
+ *
+ * Every adapter resolves the same things from its options — a DynamoDB client
+ * it either built, and so must destroy, or was handed, and so must not; an S3
+ * offloader when it offloads; a logger; a retry policy; the recency index's
+ * settings — releases them the same way, and provisions the same lifecycle
+ * rule from its ttl. Whether an adapter owns its client is decided in
+ * `dynamodb/client.ts`; this module only reads that decision, to release a
+ * client it built and leave an injected one alone.
+ */
+import type { CompressionConfig } from './codec/compression.js';
+import { type AdapterName } from './codec/s3/config.js';
+import { S3Offloader } from './codec/s3/offloader.js';
+import { type DynamoDBDocumentLike } from './dynamodb/client.js';
+import { type RetryOptions } from './dynamodb/retry.js';
+import { type Logger } from './logging/logger.js';
+import type { BaseAdapterOptions, CodecOptions } from './options.js';
+import { type TtlOption } from './validation/ttl.js';
+/** Anything an adapter holds open and must hand back when it is torn down. */
+export interface Releasable {
+    destroy(): void;
+}
+/**
+ * Release every resource, whatever any one of them does.
+ *
+ * The hazard is the one `DynamoDBFactory`'s own `release` names: a teardown
+ * written as a sequence of statements stops at the first throw, so everything
+ * after it is stranded with no reference left to reach it by. An adapter's
+ * teardown is such a sequence — the S3 offloader, then the DynamoDB client it
+ * built — and an S3 client whose sockets are already gone throws from its own
+ * `destroy`, which would leave the DynamoDB client open for the life of the
+ * process. Each resource is therefore released whatever the ones before it
+ * threw.
+ *
+ * Accepts: `resources` — in the order they should be released; an absent one
+ * (an adapter with no offloader, a client the caller injected and therefore
+ * owns) is skipped rather than guarded at each call site.
+ *
+ * Returns: nothing.
+ *
+ * Throws: the **first** failure, and only after every resource has been
+ * offered its release, so nothing is stranded behind it. Raised rather than
+ * logged because the default logger discards everything: a caller who never
+ * configured one would otherwise be told nowhere at all that a client of theirs
+ * is still holding sockets. A later failure is dropped, because a caller can
+ * act on one report and the first one names the resource that actually broke.
+ * A `throw` that produced something other than an `Error` is normalised, so a
+ * caller's `catch` is handed the same shape whatever a client raised.
+ */
+export declare function releaseOwned(resources: readonly (Releasable | undefined)[]): void;
+/** What every adapter resolves from its options and every operation reads. */
+export interface AdapterCore {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    compression?: CompressionConfig;
+    offloader?: S3Offloader;
+    ttl?: TtlOption;
+    logger: Logger;
+    /** Retry budget and backoff for every DynamoDB call, with the retry debug log attached. */
+    retry?: RetryOptions;
+    /**
+     * Index partitions per adapter for the recency index; see `indexKeys`.
+     * Absent means the default, which is where it is resolved.
+     */
+    indexShards?: number;
+    /** Payloads decoded at once by one call; the memory ceiling’s multiplier. */
+    readConcurrency?: number;
+    /** Name of the recency index, when the table carries one; see `BaseAdapterOptions.indexName`. */
+    indexName?: string;
+}
+/** An adapter's hold on what it owns. */
+export interface AdapterShell {
+    readonly core: AdapterCore;
+    /** Provision the S3 lifecycle rule for the configured ttl; see {@link ensureLifecycleFor}. */
+    ensureLifecycleRule(): Promise<void>;
+    /**
+     * Release the offloader, and the DynamoDB client when the adapter built it;
+     * see {@link releaseOwned}. `release` runs once; a later call does nothing.
+     */
+    release(): void;
+}
+/** The checks an adapter adds to the shared ones, and where they run. */
+export interface AdapterChecks {
+    /** Runs after the shared option checks and before the collaborator checks. */
+    options?: () => void;
+    /** Runs after the shared collaborator checks, before anything is built. */
+    collaborators?: () => void;
+    /** The fewest attempts the adapter's own writes need; see `resolveRetryPolicy`. */
+    attemptFloor?: number;
+}
+/** The options every adapter takes, with the serializer each may add. */
+export type AdapterOptions = BaseAdapterOptions & CodecOptions & {
+    serde?: object;
+};
+/**
+ * Provision the S3 lifecycle rule that expires what an adapter offloads, on its
+ * ttl, so an offloaded payload does not outlive the DynamoDB item that points
+ * at it.
+ *
+ * The rule is expressed in whole days because that is the only granularity S3
+ * lifecycle expiration accepts, while the DynamoDB TTL is in seconds; see
+ * `lifecycleExpirationDays` for the rounding, which is always up.
+ *
+ * Accepts: `core` — the adapter's offloader, ttl and logger.
+ *
+ * Returns: nothing. Without an offloader there is nothing to rule over, and
+ * without a ttl no item expires, so any rule would delete a payload a live row
+ * still needs: either absence does nothing. Installing a rule that is already
+ * there is a no-op too, so calling this 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: whatever reading or writing the bucket's lifecycle configuration
+ * throws, `VALIDATION` naming `s3.keyPrefix` when the rule id this prefix
+ * would take is already held by a different prefix, and `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.
+ *
+ * Guarantees: needs the bucket-level `s3:GetLifecycleConfiguration` /
+ * `s3:PutLifecycleConfiguration` permissions, which are broader than the
+ * object-level CRUD the rest of offload uses — so this is a provisioning call,
+ * not a per-request one.
+ */
+export declare function ensureLifecycleFor(core: Pick<AdapterCore, 'offloader' | 'ttl' | 'logger'>): Promise<void>;
+/**
+ * Check an adapter's options and resolve what it will own.
+ *
+ * Accepts: `options` — the adapter's, already held to its own key list, and
+ * checked first, so no half-built adapter exists when one is wrong.
+ * `adapter` — which adapter, which names its default S3 key prefix. `checks` —
+ * the adapter's own option and collaborator checks, and its retry floor.
+ *
+ * Returns: the shell: the core every operation reads, with every shared
+ * default filled in here and nowhere else, and the adapter's two lifetime
+ * operations. A client the caller passed in is never destroyed by `release`.
+ *
+ * Throws: `VALIDATION` for an option or a collaborator that fails a shared
+ * check or one of `checks`, in that order.
+ *
+ * Guarantees: no I/O. The stacked-retry check is deliberately not awaited: it
+ * is a warning about a caller-supplied client, not a precondition.
+ */
+export declare function openAdapter(options: AdapterOptions, adapter: AdapterName, checks?: AdapterChecks): AdapterShell;

package/dist/esm/shared/adapter.js

@@ -0,0 +1,65 @@
+import { offloaderConfigFor } from './codec/s3/config.js';
+import { S3Offloader } from './codec/s3/offloader.js';
+import { DEFAULT_READ_CONCURRENCY } from './concurrency.js';
+import { resolveDynamoDBClient, warnOnStackedRetries, } from './dynamodb/client.js';
+import { DEFAULT_INDEX_SHARDS } from './dynamodb/recency-index.js';
+import { resolveRetryPolicy } from './dynamodb/retry.js';
+import { toError } from './errors/base-error.js';
+import { resolveLogger } from './logging/logger.js';
+import { assertBaseCollaborators } from './validation/collaborators.js';
+import { assertBaseAdapterOptions } from './validation/options.js';
+import { lifecycleExpirationDays } from './validation/ttl.js';
+export function releaseOwned(resources) {
+    let first;
+    for (const resource of resources) {
+        try {
+            resource?.destroy();
+        }
+        catch (error) {
+            first ??= toError(error);
+        }
+    }
+    if (first !== undefined)
+        throw first;
+}
+export async function ensureLifecycleFor(core) {
+    if (!core.offloader || !core.ttl)
+        return;
+    await core.offloader.ensureLifecycleRule(lifecycleExpirationDays(core.ttl), core.logger);
+}
+export function openAdapter(options, adapter, checks = {}) {
+    assertBaseAdapterOptions(options);
+    checks.options?.();
+    assertBaseCollaborators(options);
+    checks.collaborators?.();
+    const logger = resolveLogger(options.logger);
+    const resolved = resolveDynamoDBClient(options);
+    if (!resolved.ownsClient)
+        void warnOnStackedRetries(resolved.client, logger);
+    const offloader = options.s3
+        ? new S3Offloader(offloaderConfigFor(options.s3, adapter, options.clientConfig), logger)
+        : undefined;
+    const core = {
+        client: resolved.client,
+        tableName: options.tableName,
+        compression: options.compression,
+        offloader,
+        ttl: options.ttl,
+        logger,
+        retry: resolveRetryPolicy(options.retry, logger, checks.attemptFloor),
+        indexShards: options.indexShards ?? DEFAULT_INDEX_SHARDS,
+        readConcurrency: options.readConcurrency ?? DEFAULT_READ_CONCURRENCY,
+        indexName: options.indexName,
+    };
+    let released = false;
+    return {
+        core,
+        ensureLifecycleRule: () => ensureLifecycleFor(core),
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            releaseOwned([offloader, resolved.ownsClient ? resolved.ddbClient : undefined]);
+        },
+    };
+}