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

package/dist/{shared/dynamodb/table-schema.js → esm/shared/dynamodb/table-schema.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides the conventions every row of the shared table follows, whichever
  * adapter wrote it.
@@ -11,21 +10,12 @@
  * that feature's `rows` module's decision; that they are written into these
  * attributes and read back in this order is this module's.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_ROW_FORMAT_VERSION = exports.ROW_FORMAT_VERSION = exports.ADAPTER_TAGS = exports.KEY_SEPARATOR = exports.MAX_SORT_KEY_BYTES = exports.MAX_KEY_SEGMENT_BYTES = exports.MAX_PARTITION_ID_BYTES = exports.SORT_KEY_ATTRIBUTE = exports.PARTITION_KEY_ATTRIBUTE = void 0;
-exports.rowKeyOf = rowKeyOf;
-exports.rowVersionOf = rowVersionOf;
-exports.assertReadableRow = assertReadableRow;
-exports.withRowVersion = withRowVersion;
-exports.isExpiredRow = isExpiredRow;
-exports.withoutExpired = withoutExpired;
-exports.compareSortKeys = compareSortKeys;
-const base_error_1 = require("../errors/base-error");
-const error_code_1 = require("../errors/error-code");
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { AttributeMap } from './client.js';
 /** The attribute every row is partitioned by. */
-exports.PARTITION_KEY_ATTRIBUTE = 'PK';
+export declare const PARTITION_KEY_ATTRIBUTE = "PK";
 /** The attribute every row is sorted by within its partition. */
-exports.SORT_KEY_ATTRIBUTE = 'SK';
+export declare const SORT_KEY_ATTRIBUTE = "SK";
 /**
  * Byte caps on caller-supplied identifiers, measured as UTF-8. DynamoDB caps a
  * partition key at 2048 bytes and a sort key at 1024; S3 caps an object key at
@@ -35,30 +25,59 @@ exports.SORT_KEY_ATTRIBUTE = 'SK';
  *
  * Partition-key identifiers: `thread_id` and `sessionId`.
  */
-exports.MAX_PARTITION_ID_BYTES = 1024;
+export declare const MAX_PARTITION_ID_BYTES = 1024;
 /**
- * Sort-key segments: `checkpoint_ns`, `checkpoint_id`, `taskId`, a pending-write
- * channel, a store namespace element and a store `key`.
+ * Sort-key segments other than the checkpoint namespace and a pending-write
+ * channel: `checkpoint_id`, `taskId`, a store namespace element and a store
+ * `key`.
  */
-exports.MAX_KEY_SEGMENT_BYTES = 256;
+export declare const MAX_KEY_SEGMENT_BYTES = 256;
+/**
+ * A pending-write channel's own cap. Every other segment is one identifier,
+ * but LangGraph names the channel behind a static fan-in after every source
+ * node — `join:<a>+<b>+…:<end>` — so a channel is as long as a graph's node
+ * names together, and nine sources with ordinary names pass 256 bytes. The
+ * channel is the last segment of the WRITE sort key, so DynamoDB's cap on the
+ * whole key is the bound that matters, and the composed-key check enforces it
+ * against the namespace, checkpoint id and task id the channel sits behind.
+ */
+export declare const MAX_WRITE_CHANNEL_BYTES = 1024;
+/**
+ * The checkpoint namespace's own cap. LangGraph names a subgraph's namespace
+ * after its parent's, a separator, the node's name and a 36-character task id
+ * (`${parent}|${node}:${taskId}`), so each level of nesting adds roughly forty
+ * bytes plus the node name; 256 bytes stopped a graph at its fifth or sixth
+ * level. Twice that keeps the rows a namespace composes inside DynamoDB's
+ * sort-key cap, which the composed-key checks enforce either way.
+ */
+export declare const MAX_CHECKPOINT_NS_BYTES = 512;
 /**
  * DynamoDB cap on a whole sort key; composed keys are checked against it too.
  *
  * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html
  */
-exports.MAX_SORT_KEY_BYTES = 1024;
+export declare const MAX_SORT_KEY_BYTES = 1024;
 /**
  * The separator between the segments of every key this package composes. No
  * caller-supplied identifier may contain it (the parsers refuse it), which is
  * what lets a key be read back into its parts and matched by prefix (record 2).
  */
-exports.KEY_SEPARATOR = '#';
+export declare const KEY_SEPARATOR = "#";
 /**
  * The tag each adapter's partition keys open with. The three differ in their
  * first character, so no two adapters' partitions can collide on a shared
  * table, whatever identifiers their callers reuse (record 2).
  */
-exports.ADAPTER_TAGS = { checkpointer: 'CHKPT', store: 'STORE', history: 'HIST' };
+export declare const ADAPTER_TAGS: {
+    readonly checkpointer: 'CHKPT';
+    readonly store: 'STORE';
+    readonly history: 'HIST';
+};
+/** A row's primary key, as a `Key` document and as the key half of an item. */
+export interface RowKey {
+    PK: string;
+    SK: string;
+}
 /**
  * The key of a row already in hand.
  *
@@ -69,8 +88,10 @@ exports.ADAPTER_TAGS = { checkpointer: 'CHKPT', store: 'STORE', history: 'HIST'
  *
  * Throws: nothing.
  */
-function rowKeyOf(row) {
-    return { PK: row.PK, SK: row.SK };
+export declare function rowKeyOf(row: AttributeMap): RowKey;
+/** The only attribute this module reads: a row's own format version. */
+export interface VersionedRow {
+    v?: number;
 }
 /**
  * The format version this package stamps on every row it writes.
@@ -82,9 +103,9 @@ function rowKeyOf(row) {
  * and undefined*, which reversed first-write-wins for pending writes across an
  * upgrade. A row states its own version instead.
  */
-exports.ROW_FORMAT_VERSION = 1;
+export declare const ROW_FORMAT_VERSION = 1;
 /** The highest version this package knows how to read. */
-exports.SUPPORTED_ROW_FORMAT_VERSION = 1;
+export declare const SUPPORTED_ROW_FORMAT_VERSION = 1;
 /**
  * A row's format version.
  *
@@ -95,9 +116,7 @@ exports.SUPPORTED_ROW_FORMAT_VERSION = 1;
  *
  * Throws: nothing.
  */
-function rowVersionOf(row) {
-    return typeof row.v === 'number' ? row.v : 0;
-}
+export declare function rowVersionOf(row: VersionedRow): number;
 /**
  * Refuse a row written by a newer version of this package.
  *
@@ -113,25 +132,7 @@ function rowVersionOf(row) {
  * version does not know is how a reader returns a checkpoint with silently
  * missing state, so the caller is told to upgrade instead.
  */
-function assertReadableRow(row, what) {
-    const version = rowVersionOf(row);
-    if (version <= exports.SUPPORTED_ROW_FORMAT_VERSION)
-        return;
-    throw new base_error_1.DynamoDBLangGraphError(`this ${what} row was written in format version ${version}; this version of the library ` +
-        `reads up to ${exports.SUPPORTED_ROW_FORMAT_VERSION} — upgrade to read it`, error_code_1.ErrorCode.FORMAT_UNSUPPORTED, { field: 'v' });
-}
-/**
- * The item with this release's format version stamped on it.
- *
- * Accepts: `item` — any item about to be written; an existing `v` is replaced.
- *
- * Returns: a copy carrying `v`, leaving the input untouched.
- *
- * Throws: nothing.
- */
-function withRowVersion(item) {
-    return { ...item, v: exports.ROW_FORMAT_VERSION };
-}
+export declare function assertReadableRow(row: VersionedRow, what: string): void;
 /**
  * Whether a row has reached its TTL.
  *
@@ -143,14 +144,14 @@ function withRowVersion(item) {
  *
  * Throws: nothing.
  *
- * Guarantees: an expired row is absent to every reader even while DynamoDB's
- * own sweep lags, which it may by up to 48 hours
- * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html).
+ * Guarantees: a caller that applies this hides an expired row even while
+ * DynamoDB's own sweep lags, which AWS documents as typically within a few days of the
+ * `ttl`, with no fixed bound
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html).
  */
-function isExpiredRow(row, nowSeconds) {
-    return row.ttl !== undefined && row.ttl <= nowSeconds;
-}
-const TTL_FILTER = 'attribute_not_exists(#ttl) OR #ttl > :now';
+export declare function isExpiredRow(row: {
+    ttl?: number;
+}, nowSeconds: number): boolean;
 /**
  * The same query with expired rows filtered out server-side.
  *
@@ -168,16 +169,7 @@ const TTL_FILTER = 'attribute_not_exists(#ttl) OR #ttl > :now';
  * {@link isExpiredRow} check, because the query is built and its rows are read
  * at two different instants, and DynamoDB applies a filter *after* `Limit`.
  */
-function withoutExpired(params, nowSeconds) {
-    return {
-        ...params,
-        FilterExpression: params.FilterExpression
-            ? `(${params.FilterExpression}) AND (${TTL_FILTER})`
-            : TTL_FILTER,
-        ExpressionAttributeNames: { ...params.ExpressionAttributeNames, '#ttl': 'ttl' },
-        ExpressionAttributeValues: { ...params.ExpressionAttributeValues, ':now': nowSeconds },
-    };
-}
+export declare function withoutExpired<T extends QueryCommandInput | ScanCommandInput>(params: T, nowSeconds: number): T;
 /**
  * Order two DynamoDB string sort keys the way the server orders them.
  *
@@ -204,6 +196,4 @@ function withoutExpired(params, nowSeconds) {
  *
  * Throws: nothing.
  */
-function compareSortKeys(left, right) {
-    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
-}
+export declare function compareSortKeys(left: string, right: string): number;

package/dist/esm/shared/dynamodb/table-schema.js

@@ -0,0 +1,43 @@
+import { DynamoDBLangGraphError } from '../errors/base-error.js';
+import { ErrorCode } from '../errors/error-code.js';
+export const PARTITION_KEY_ATTRIBUTE = 'PK';
+export const SORT_KEY_ATTRIBUTE = 'SK';
+export const MAX_PARTITION_ID_BYTES = 1024;
+export const MAX_KEY_SEGMENT_BYTES = 256;
+export const MAX_WRITE_CHANNEL_BYTES = 1024;
+export const MAX_CHECKPOINT_NS_BYTES = 512;
+export const MAX_SORT_KEY_BYTES = 1024;
+export const KEY_SEPARATOR = '#';
+export const ADAPTER_TAGS = { checkpointer: 'CHKPT', store: 'STORE', history: 'HIST' };
+export function rowKeyOf(row) {
+    return { PK: row.PK, SK: row.SK };
+}
+export const ROW_FORMAT_VERSION = 1;
+export const SUPPORTED_ROW_FORMAT_VERSION = 1;
+export function rowVersionOf(row) {
+    return typeof row.v === 'number' ? row.v : 0;
+}
+export function assertReadableRow(row, what) {
+    const version = rowVersionOf(row);
+    if (version <= SUPPORTED_ROW_FORMAT_VERSION)
+        return;
+    throw new DynamoDBLangGraphError(`this ${what} row was written in format version ${version}; this version of the library ` +
+        `reads up to ${SUPPORTED_ROW_FORMAT_VERSION} — upgrade to read it`, ErrorCode.FORMAT_UNSUPPORTED, { field: 'v' });
+}
+export function isExpiredRow(row, nowSeconds) {
+    return row.ttl !== undefined && row.ttl <= nowSeconds;
+}
+const TTL_FILTER = 'attribute_not_exists(#ttl) OR #ttl > :now';
+export function withoutExpired(params, nowSeconds) {
+    return {
+        ...params,
+        FilterExpression: params.FilterExpression
+            ? `(${params.FilterExpression}) AND (${TTL_FILTER})`
+            : TTL_FILTER,
+        ExpressionAttributeNames: { ...params.ExpressionAttributeNames, '#ttl': 'ttl' },
+        ExpressionAttributeValues: { ...params.ExpressionAttributeValues, ':now': nowSeconds },
+    };
+}
+export function compareSortKeys(left, right) {
+    return Buffer.compare(Buffer.from(left, 'utf8'), Buffer.from(right, 'utf8'));
+}

package/dist/esm/shared/errors/base-error.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Hides the one error class and what counts as an error at all.
+ *
+ * Every failure this package raises is a `DynamoDBLangGraphError` told apart by
+ * its code (record 19), recognisable across copies of the package by a brand
+ * rather than by `instanceof`; and whatever a caller's code or a dependency
+ * throws — a string, `undefined`, an object — is turned into an `Error` before
+ * anything reads it.
+ */
+import type { WriteRequest } from '../dynamodb/client.js';
+import { ErrorCode } from './error-code.js';
+/**
+ * Structured, log-safe context attached to every library error. Identifiers
+ * and counts only — never a payload or a credential.
+ */
+export interface ErrorContext {
+    /** The DynamoDB table the operation targeted, when known. */
+    tableName?: string;
+    /** The public operation (`saver.put`, `store.batch`, …) or internal step that failed. */
+    operation?: string;
+    /** The option, argument or cap that failed validation or was exceeded. */
+    field?: string;
+    /** The S3 object key involved, for offload failures. */
+    key?: string;
+    /** Attempts made before a retry budget was exhausted. */
+    attempts?: number;
+    /** The thread a checkpointer failure belongs to. */
+    threadId?: string;
+    /** The checkpoint a checkpointer failure names. */
+    checkpointId?: string;
+    /**
+     * The AWS exception name of the failure underneath, when that failure was
+     * AWS-shaped (it carried the SDK's `$metadata`, or a name the classifier
+     * knows or that ends in `Exception`). Lifted off `cause.name` so a log line
+     * or an alert can branch on it without walking `cause`.
+     */
+    awsErrorName?: string;
+    /** The AWS request id (`cause.$metadata.requestId`), which AWS Support asks for. */
+    requestId?: string;
+    /** The HTTP status of the failed AWS response (`cause.$metadata.httpStatusCode`). */
+    httpStatusCode?: number;
+}
+/** What one `BatchWriteItem` drain left behind when it ran out of rounds. */
+export interface BatchDrainDetails {
+    readonly kind: 'drain';
+    /** Writes DynamoDB acknowledged; they persist, since there is no rollback. */
+    readonly succeededCount: number;
+    /** The requests DynamoDB did not acknowledge, verbatim, so they can be re-submitted. */
+    readonly unprocessed: readonly WriteRequest[];
+    /** `UnprocessedItems` rounds spent. */
+    readonly retries: number;
+}
+/**
+ * The tally of a pass that attempted every chunk (`unit: 'chunk'`, 25-row
+ * `BatchWriteItem` chunks) or every row (`unit: 'row'`, one conditional delete
+ * per row) before reporting.
+ */
+export interface BatchPassDetails {
+    readonly kind: 'pass';
+    readonly unit: 'chunk' | 'row';
+    readonly succeededChunks: number;
+    readonly totalChunks: number;
+    /** Each failing chunk's or row's own error. */
+    readonly failedChunks: readonly Error[];
+    /** Individual writes confirmed persisted across the whole pass. */
+    readonly succeededCount: number;
+}
+/** What a `BATCH_WRITE_INCOMPLETE` error reports: one drain, or a whole pass. */
+export type BatchWriteIncompleteDetails = BatchDrainDetails | BatchPassDetails;
+/** What a `COMPENSATION_FAILED` error reports besides its trigger, which is `cause`. */
+export interface CompensationFailedDetails {
+    /**
+     * Why the append could not be undone or settled: the rollback's own
+     * failure (itself often a `BATCH_WRITE_INCOMPLETE`), the read-back's
+     * failure, or the write's own failure when some attempt of it may still
+     * be applied.
+     */
+    readonly rollbackError: Error;
+}
+/** The codes that carry details, and the shape each one carries. */
+export interface ErrorDetailsByCode {
+    [ErrorCode.BATCH_WRITE_INCOMPLETE]: BatchWriteIncompleteDetails;
+    [ErrorCode.COMPENSATION_FAILED]: CompensationFailedDetails;
+}
+/** The details a code carries; `undefined` for every code not in {@link ErrorDetailsByCode}. */
+export type ErrorDetailsFor<C extends ErrorCode> = C extends keyof ErrorDetailsByCode ? ErrorDetailsByCode[C] : undefined;
+/**
+ * Base class for every error this library throws. Carries a branchable
+ * {@link ErrorCode}, structured {@link ErrorContext}, code-specific
+ * {@link details}, and a native `cause` chain. Detected via
+ * {@link isDynamoDBLangGraphError} (a symbol brand) rather than `instanceof`,
+ * which is banned repo-wide.
+ */
+export declare class DynamoDBLangGraphError<C extends ErrorCode = ErrorCode> extends Error {
+    readonly code: C;
+    readonly context: ErrorContext;
+    /** Declared, not emitted: a code without details leaves no `undefined`-valued own property. */
+    readonly details: ErrorDetailsFor<C>;
+    /**
+     * Accepts: `message` — already redacted by whoever composed it, since it reaches
+     * `err.message`, which an application may print without a redacting logger.
+     * `code` — the code this error branches on. `context` — identifiers and counts
+     * only, never a payload or a credential. It is **copied**, so a caller that
+     * reuses one builder object cannot rewrite the context of an error already in
+     * flight; `null` reads as an absent one. `cause` — the failure below this one,
+     * kept as the native `cause` chain. `details` — the code-specific record
+     * {@link ErrorDetailsByCode} names, copied like `context`. The parameter is
+     * optional for every code, including the two whose `details` property is
+     * typed as always present (`BATCH_WRITE_INCOMPLETE`, `COMPENSATION_FAILED`):
+     * nothing at compile time stops a direct `new` from leaving it out, and an
+     * error built that way has no `details` at runtime whatever its type says.
+     * Inside this package those two codes are only ever built by the factories
+     * that always pass them.
+     *
+     * Returns: the error, branded so {@link isDynamoDBLangGraphError} recognises it
+     * across realms and across two copies of this package. The brand is
+     * non-enumerable, so it never reaches a log or a JSON serialization.
+     *
+     * Throws: nothing; building an error may not fail.
+     */
+    constructor(message: string, code: C, context?: ErrorContext, cause?: Error, details?: ErrorDetailsFor<C>);
+}
+/**
+ * Every library error, as a union discriminated by `code`: comparing `code`
+ * narrows `details` to the shape that code carries.
+ */
+export type AnyDynamoDBLangGraphError = {
+    [C in ErrorCode]: DynamoDBLangGraphError<C>;
+}[ErrorCode];
+/**
+ * Whether `value` is one of this library's errors.
+ *
+ * Accepts: whatever a `catch` clause binds, as it is — an error from any realm
+ * or any copy of this package, and any other value a `throw` can produce:
+ * `null`, `undefined`, a string, a number, a symbol. Declared `unknown`
+ * because that is what `strict` types a `catch` binding, and the documented
+ * place to call this is the first line inside one.
+ *
+ * Returns: whether it carries the brand, narrowed to the union discriminated by
+ * `code`. A symbol registered by name, not `instanceof`: two copies of this
+ * package in one dependency tree produce two classes but one symbol, and an
+ * error crossing a realm boundary keeps its properties while losing its
+ * prototype. Anything that cannot carry a property answers `false`. Earlier
+ * releases set the same brand, so an older copy of this package installed
+ * beside this one has its errors recognised too — in that release's shape: no
+ * `details`, the counts as flat properties, and possibly a code this union
+ * does not list (`UPSTREAM`).
+ *
+ * Throws: nothing. The `in` operator raises a `TypeError` on a non-object, and
+ * a guard that throws inside the `catch` it was called from would replace the
+ * failure the caller is reporting with one of its own.
+ */
+export declare function isDynamoDBLangGraphError(value: unknown): value is AnyDynamoDBLangGraphError;
+/**
+ * Whether `value` is one of this library's errors carrying `code`.
+ *
+ * Accepts: anything a `catch` can bind. `code` — the code to test for.
+ *
+ * Returns: `true` only for a branded error whose `code` is `code`, narrowed so
+ * its `details` are typed. An unbranded object that merely carries a `code`
+ * property is not one: recognition is by brand and code together, never by a
+ * name or a shape.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function hasErrorCode<C extends ErrorCode>(value: Error, code: C): value is DynamoDBLangGraphError<C>;
+/**
+ * A caller's own copy of a branded error that several concurrent callers would
+ * otherwise share — a cached rejected import, a cached rejected client build.
+ * Sharing the one instance is safe while nothing on the path back to a public
+ * method writes to it, but the public boundary does: it stamps
+ * `context.operation` and `context.tableName`, each independently when the
+ * error does not already carry it, in place, and a second caller reaching the
+ * same shared instance through a *different* public method would then find
+ * the first caller's operation and table already sitting in its own context,
+ * unable to write its own. Giving each
+ * caller its own instance up front — same `message`, `code`, `context` and
+ * `cause` — keeps the two from ever writing to one object. Not a general
+ * clone: an *unbranded* failure needs none, since `wrapForeignError`
+ * (`shared/errors/boundary.ts`) already builds a fresh wrapper for it at
+ * every boundary crossing, unlike a branded error, which crosses unwrapped.
+ *
+ * Accepts: `error` — anything a `catch` can bind.
+ *
+ * Returns: a new `DynamoDBLangGraphError` carrying the same `message`, `code`,
+ * `context`, `cause` and `details` as `error`, when `error` already was one;
+ * `error` itself, unchanged, for anything else. The copy does not carry
+ * `RETRY_EXHAUSTED`'s non-enumerable record of whether a write's retry budget
+ * may still land, so it is not for a budget error: a caller judging one asks
+ * the original.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function copyForCaller(error: Error): Error;
+/**
+ * What a log line calls a failure.
+ *
+ * Accepts: any error a `catch` bound.
+ *
+ * Returns: the `code` of one of this library's errors, and the `name` of any
+ * other. Every library error shares one name, so the name alone would log
+ * `DynamoDBLangGraphError` for a refused input and a spent retry budget alike;
+ * the code is what tells them apart, and like a name it is an identifier, never
+ * a payload.
+ *
+ * Throws: nothing for an error. A value that cannot carry a property raises
+ * the `TypeError` reading its `name` raises, as reading it directly would.
+ */
+export declare function failureLabel(error: Error): string;
+/**
+ * A caught value as an `Error`.
+ *
+ * Kept in this module rather than in `boundary.ts`, which otherwise reads as
+ * its natural home: `shared/logging/secret-patterns.ts` calls this to
+ * normalise whatever a `catch` bound before redacting it, and `boundary.ts`
+ * itself calls `redactedMessage` while building the error it wraps a foreign
+ * failure into. Both edges are real, so the two modules cannot import each
+ * other without a cycle; this module depends on neither.
+ *
+ * Accepts: `value` — declared `Error` because callers narrow a catch clause
+ * with `toError(error as Error)`, but anything can be thrown in JavaScript:
+ * a string, `undefined`, a plain object, a `BigInt`, a symbol.
+ *
+ * Returns: the value itself when it is error-shaped — an object carrying a
+ * string `message`, which keeps an SDK error's own fields and `cause` intact;
+ * otherwise a fresh `Error` describing what was thrown.
+ *
+ * Throws: **nothing**. This runs inside `catch` blocks, so a throw here would
+ * discard the failure being reported and replace it with its own.
+ */
+export declare function toError(value: Error): Error;

package/dist/esm/shared/errors/base-error.js

@@ -0,0 +1,64 @@
+import { ErrorCode } from './error-code.js';
+const ERROR_BRAND = Symbol.for('@farukada/aws-langgraph-dynamodb-ts/error');
+function isList(field) {
+    return Array.isArray(field);
+}
+function copyDetails(details) {
+    if (details === null || typeof details !== 'object')
+        return details;
+    const fields = Object.entries(details);
+    return Object.fromEntries(fields.map(([key, value]) => [key, isList(value) ? [...value] : value]));
+}
+export class DynamoDBLangGraphError extends Error {
+    code;
+    context;
+    constructor(message, code, context = {}, cause, details) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = 'DynamoDBLangGraphError';
+        this.code = code;
+        this.context = { ...context };
+        if (details !== undefined)
+            this.details = copyDetails(details);
+        Object.defineProperty(this, ERROR_BRAND, { value: true, enumerable: false });
+    }
+}
+export function isDynamoDBLangGraphError(value) {
+    return typeof value === 'object' && value !== null && ERROR_BRAND in value;
+}
+export function hasErrorCode(value, code) {
+    return isDynamoDBLangGraphError(value) && value.code === code;
+}
+export function copyForCaller(error) {
+    if (!isDynamoDBLangGraphError(error))
+        return error;
+    return new DynamoDBLangGraphError(error.message, error.code, error.context, error.cause, error.details);
+}
+export function failureLabel(error) {
+    return isDynamoDBLangGraphError(error) ? error.code : error.name;
+}
+function describeThrown(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined || value === null)
+        return `${String(value)} was thrown`;
+    try {
+        return JSON.stringify(value) ?? `a ${typeof value} value was thrown`;
+    }
+    catch {
+        return `an unserializable ${typeof value} value was thrown`;
+    }
+}
+export function toError(value) {
+    if (value !== null && typeof value === 'object' && messageOf(value) !== undefined)
+        return value;
+    return new Error(describeThrown(value));
+}
+function messageOf(value) {
+    try {
+        const { message } = value;
+        return typeof message === 'string' ? message : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/shared/errors/boundary.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Hides what crosses the public boundary.
+ *
+ * Only this package's own error leaves a public method (record 13): an error of
+ * its own passes through, given the public operation and the table it surfaced
+ * through for whichever of the two it does not already name, and anything
+ * else — an SDK failure, a caller's thrown value — is classified and wrapped
+ * with its cause attached and its text redacted.
+ */
+import { type AnyDynamoDBLangGraphError, DynamoDBLangGraphError } from './base-error.js';
+/**
+ * Normalise anything escaping a public method into the library's error model.
+ *
+ * Accepts: anything a `catch` produced — an `Error`, or a value that is not one
+ * (`toError` settles that first). `operation` — the public method's name.
+ * `tableName` — the adapter's table, when the method has one.
+ *
+ * Returns: a branded library error — the same one, when it already was one,
+ * with whichever of `context.operation` and `context.tableName` it does not
+ * already carry filled in — or anything else wrapped by {@link wrapForeignError}
+ * with the code the classifier assigns, stamped the same way.
+ *
+ * Throws: nothing. It runs inside a `catch`, where throwing would discard the
+ * failure being reported and replace it with its own.
+ */
+export declare function toPublicError(error: Error, operation: string, tableName?: string): AnyDynamoDBLangGraphError;
+/**
+ * Run a public operation so that every rejection is a library error.
+ *
+ * Accepts: `operation` — the public method's name, which the error carries.
+ * `fn` — the work. `tableName` — the adapter's table, which the error carries.
+ *
+ * Returns: whatever `fn` resolves to, untouched.
+ *
+ * Throws: a library error, always. Applied once, at each adapter class method,
+ * so internal code can keep rethrowing SDK errors verbatim — the retry
+ * classifier depends on their shape, and wrapping them early would blind it.
+ */
+export declare function guardPublic<T>(operation: string, fn: () => Promise<T>, tableName?: string): Promise<T>;
+/**
+ * The same guard for a streaming result.
+ *
+ * Accepts: `operation` — the public method's name. `source` — the generator to
+ * relay. `tableName` — the adapter's table.
+ *
+ * Returns: a generator yielding the source's items untouched. A consumer that
+ * stops early still closes the source, so an abandoned listing stops reading
+ * rather than paging on in the background.
+ *
+ * Throws: a library error, always — including for a failure raised
+ * mid-iteration, which is the case a `try` around the loop body would miss.
+ */
+export declare function guardPublicIterable<T>(operation: string, source: AsyncGenerator<T>, tableName?: string): AsyncGenerator<T>;
+/**
+ * The same guard for a synchronous public method.
+ *
+ * Accepts: `operation` — the public method's name. `fn` — the work.
+ * `tableName` — the adapter's table.
+ *
+ * Returns: whatever `fn` returns.
+ *
+ * Throws: a library error, always — what a client's own `destroy` threw
+ * included, classified like any other foreign failure and kept as `cause`.
+ */
+export declare function guardPublicSync<T>(operation: string, fn: () => T, tableName?: string): T;
+/**
+ * A failure from below this library, as one of its errors.
+ *
+ * Accepts: `cause` — whatever a `catch` bound: an AWS SDK error, a transport
+ * error, or what a `VectorBackend`, `Embeddings`, `serde` or `MultiSessionHistory`
+ * threw. `operation` — the public method it surfaced through.
+ *
+ * Returns: an error whose code is {@link classifyAwsError}'s answer for
+ * {@link classifiableCause} of the normalised `cause` — so an AWS or network
+ * failure found down the cause chain still earns its own code rather than
+ * `UNEXPECTED_ERROR`. Its context names `operation` and — for whichever node
+ * was classified — `awsErrorName`, `requestId` and `httpStatusCode`. Its
+ * `cause` is the original, normalised through {@link toError}, kept whole
+ * regardless of which node down the chain supplied the code. The message
+ * quotes the cause's own name cut at the log cap and its own text redacted
+ * and cut at the relay cap, because `err.message` reaches applications that
+ * print it without a redacting logger.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function wrapForeignError(cause: Error, operation: string): DynamoDBLangGraphError;