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

package/dist/{shared/dynamodb/cancellation.js → esm/shared/dynamodb/cancellation.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides how a cancelled transaction says why it failed.
  *
@@ -9,21 +8,28 @@
  * condition are read here and nowhere else, so the retry layer, the error
  * classifier and the writers that act on a rejection cannot read one apart.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCancellationReasons = getCancellationReasons;
-exports.conditionalCheckFailure = conditionalCheckFailure;
-exports.transientCancellation = transientCancellation;
-exports.throttledCancellation = throttledCancellation;
-exports.conditionFailedAt = conditionFailedAt;
-/** The reason code an item that was not the cause carries. */
-const NOT_THE_CAUSE = 'None';
+import type { AttributeValue } from '@aws-sdk/client-dynamodb';
 /**
- * The reason code a guard rejection arrives under inside a transaction. It is
- * *not* the exception name the same rejection carries outside one
- * (`ConditionalCheckFailedException`); the two strings are neither
- * interchangeable nor prefixes to test for.
+ * One entry of a TransactWriteItems/TransactionCanceledException's
+ * CancellationReasons. `Item` is the row the service attached to the item whose
+ * condition failed, in raw AttributeValue form — an error payload is not
+ * unmarshalled by the document client the way a response is.
  */
-const CONDITION_FAILED = 'ConditionalCheckFailed';
+export interface CancellationReason {
+    Code?: string;
+    Item?: Record<string, AttributeValue>;
+}
+/**
+ * The fields a write's rejection can arrive in: the exception's own name, and
+ * the per-item reasons a cancelled transaction carries instead. Both are
+ * optional because this is an arbitrary error seen through a reader's eyes — a
+ * rejection outside a transaction names itself and carries no reasons, one
+ * inside a transaction carries reasons under a name of its own.
+ */
+export interface RejectionFields {
+    name?: string;
+    CancellationReasons?: CancellationReason[];
+}
 /**
  * The per-item reasons a `TransactWriteItems` cancellation carries.
  *
@@ -51,9 +57,7 @@ const CONDITION_FAILED = 'ConditionalCheckFailed';
  * property read raised a `TypeError` there, inside the classification the
  * retry layer makes before it decides whether to try again.
  */
-function getCancellationReasons(error) {
-    return error?.CancellationReasons;
-}
+export declare function getCancellationReasons(error: RejectionFields): CancellationReason[] | undefined;
 /**
  * The reason belonging to the one item a transaction's guard turned away.
  *
@@ -80,22 +84,7 @@ function getCancellationReasons(error) {
  *
  * Throws: nothing.
  */
-function conditionalCheckFailure(error) {
-    const reasons = getCancellationReasons(error) ?? [];
-    const causes = reasons.filter((reason) => reason.Code !== NOT_THE_CAUSE);
-    return causes.length === 1 && causes[0].Code === CONDITION_FAILED ? causes[0] : undefined;
-}
-/**
- * Cancellation reason codes (from a `TransactionCanceledException`'s
- * `CancellationReasons`) that are transient and safe to retry. `None` marks an
- * item that was not the cause and is ignored.
- */
-const TRANSIENT_CANCELLATION_REASONS = [
-    'None',
-    'TransactionConflict',
-    'ThrottlingError',
-    'ProvisionedThroughputExceeded',
-];
+export declare function conditionalCheckFailure(error: RejectionFields): CancellationReason | undefined;
 /**
  * Whether a cancelled transaction failed only for transient reasons.
  *
@@ -107,20 +96,7 @@ const TRANSIENT_CANCELLATION_REASONS = [
  *
  * Throws: nothing, for any value; see {@link getCancellationReasons}.
  */
-function transientCancellation(error) {
-    const reasons = getCancellationReasons(error);
-    if (!reasons)
-        return undefined;
-    // `length > 0` is load-bearing: `.every()` is vacuously true on an empty
-    // array, which would make a reason-less cancellation retryable — the exact
-    // opposite of what this function documents. AWS populates one reason per
-    // `TransactItems` entry, so an empty array should not occur; if it ever
-    // does, the conservative answer is not to retry.
-    return (reasons.length > 0 &&
-        reasons.every((reason) => reason.Code === undefined || TRANSIENT_CANCELLATION_REASONS.includes(reason.Code)));
-}
-/** Cancellation reason codes that mean the request was throttled. */
-const THROTTLING_REASONS = ['ThrottlingError', 'ProvisionedThroughputExceeded'];
+export declare function transientCancellation(error: RejectionFields): boolean | undefined;
 /**
  * Whether a cancelled transaction was throttled.
  *
@@ -132,9 +108,7 @@ const THROTTLING_REASONS = ['ThrottlingError', 'ProvisionedThroughputExceeded'];
  *
  * Throws: nothing, for any value.
  */
-function throttledCancellation(error) {
-    return (getCancellationReasons(error) ?? []).some((reason) => reason.Code !== undefined && THROTTLING_REASONS.includes(reason.Code));
-}
+export declare function throttledCancellation(error: RejectionFields): boolean;
 /**
  * Whether the item at `index` of a cancelled transaction failed its condition.
  *
@@ -147,6 +121,4 @@ function throttledCancellation(error) {
  *
  * Throws: nothing, for any value.
  */
-function conditionFailedAt(error, index) {
-    return getCancellationReasons(error)?.[index]?.Code === CONDITION_FAILED;
-}
+export declare function conditionFailedAt(error: RejectionFields, index: number): boolean;

package/dist/esm/shared/dynamodb/cancellation.js

@@ -0,0 +1,30 @@
+const NOT_THE_CAUSE = 'None';
+const CONDITION_FAILED = 'ConditionalCheckFailed';
+export function getCancellationReasons(error) {
+    return error?.CancellationReasons;
+}
+export function conditionalCheckFailure(error) {
+    const reasons = getCancellationReasons(error) ?? [];
+    const causes = reasons.filter((reason) => reason.Code !== NOT_THE_CAUSE);
+    return causes.length === 1 && causes[0].Code === CONDITION_FAILED ? causes[0] : undefined;
+}
+const TRANSIENT_CANCELLATION_REASONS = [
+    'None',
+    'TransactionConflict',
+    'ThrottlingError',
+    'ProvisionedThroughputExceeded',
+];
+export function transientCancellation(error) {
+    const reasons = getCancellationReasons(error);
+    if (!reasons)
+        return undefined;
+    return (reasons.length > 0 &&
+        reasons.every((reason) => reason.Code === undefined || TRANSIENT_CANCELLATION_REASONS.includes(reason.Code)));
+}
+const THROTTLING_REASONS = ['ThrottlingError', 'ProvisionedThroughputExceeded'];
+export function throttledCancellation(error) {
+    return (getCancellationReasons(error) ?? []).some((reason) => reason.Code !== undefined && THROTTLING_REASONS.includes(reason.Code));
+}
+export function conditionFailedAt(error, index) {
+    return getCancellationReasons(error)?.[index]?.Code === CONDITION_FAILED;
+}

package/dist/{shared/dynamodb/client.js → esm/shared/dynamodb/client.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides the DynamoDB client: the part of the DocumentClient this package calls,
  * the row shapes that part speaks, and how a client this package builds bounds
@@ -10,12 +9,9 @@
  * and a socket timeout are set, and the one place that knows whether the
  * adapter owns the client it holds.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SOCKET_TIMEOUT_MS = exports.DEFAULT_REQUEST_TIMEOUT_MS = void 0;
-exports.resolveDynamoDBClient = resolveDynamoDBClient;
-exports.warnOnStackedRetries = warnOnStackedRetries;
-const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
-const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+import { DynamoDBClient, type DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocument, type NativeAttributeValue, type TransactWriteCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { Logger } from '../logging/logger.js';
 /**
  * How long one request attempt may take on a client this library builds
  * (10 seconds) before the SDK's request handler destroys it and rejects with a
@@ -26,16 +22,17 @@ const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
  * of them defaults to 0 — a hung socket holds that attempt open forever and
  * the write lifetime bounds nothing.
  *
- * Measured, not picked. Across the fan-out widths this package documents, the
- * worst interval the handler itself saw — socket acquisition including the
- * wait behind the agent's fifty sockets, connect, request write and
- * time-to-first-response-header — was 0.92 s, at a thousand concurrent writes
- * of 20 KB values, and ten seconds is roughly eleven times that. The asymmetry
- * settles the close call: too large leaves one attempt hanging for at most ten
- * seconds, which the write lifetime's own headroom absorbs, while too small
- * turns a healthy wide fan-out into a retry storm.
+ * Measured, not picked. At a thousand concurrent writes of 20 KB values —
+ * wider than one call's own fan-out now runs, but within reach of several
+ * calls sharing one client — the worst interval the handler itself saw —
+ * socket acquisition including the wait behind the agent's fifty sockets,
+ * connect, request write and time-to-first-response-header — was 0.92 s, and
+ * ten seconds is roughly eleven times that. The asymmetry settles the close
+ * call: too large leaves one attempt hanging for at most ten seconds, which
+ * the write lifetime's own headroom absorbs, while too small turns a healthy
+ * wide fan-out into a retry storm.
  */
-exports.DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
 /**
  * How long a socket may sit idle (5 seconds) on a client this library builds
  * before the request handler destroys the request. Which error that surfaces
@@ -60,7 +57,18 @@ exports.DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
  * threshold so raising it fails loudly instead of disabling the only bound a
  * stalled transfer has.
  */
-exports.DEFAULT_SOCKET_TIMEOUT_MS = 5_000;
+export declare const DEFAULT_SOCKET_TIMEOUT_MS = 5000;
+/** A resolved DynamoDB client plus its ownership flag. */
+export interface ResolvedDynamoDBClient {
+    ddbClient: DynamoDBClient | undefined;
+    client: DynamoDBDocumentLike;
+    ownsClient: boolean;
+}
+/** Options for {@link resolveDynamoDBClient}. */
+export interface ResolveClientOptions {
+    client?: DynamoDBDocumentLike;
+    clientConfig?: DynamoDBClientConfig;
+}
 /**
  * The DocumentClient an adapter will use, and whether it owns it.
  *
@@ -82,38 +90,11 @@ exports.DEFAULT_SOCKET_TIMEOUT_MS = 5_000;
  * bounds how long one attempt may run, which `maxAttempts` alone does not. A
  * `requestHandler` in `clientConfig` replaces that default whole rather than
  * merging with it — the documented escape hatch, and equally the documented
- * way to give up the bound. An injected client keeps whatever it was built
- * with — see {@link warnOnStackedRetries}.
+ * way to give up the bound. Either key named with `undefined` overrides
+ * nothing and keeps its default. An injected client keeps whatever it was
+ * built with — see {@link warnOnStackedRetries}.
  */
-function resolveDynamoDBClient(options) {
-    if (options.client) {
-        return { ddbClient: undefined, client: options.client, ownsClient: false };
-    }
-    const createClient = options.createClient ?? ((config) => new client_dynamodb_1.DynamoDBClient(config));
-    // `throwOnRequestTimeout` is what makes the request timeout a bound: without
-    // it the handler only logs a warning when the timeout is breached.
-    // `socketTimeout` is here because `requestTimeout` stops applying the moment
-    // response *headers* arrive — the handler resolves there and clears its
-    // timers — so it says nothing about a response body that then stalls
-    // mid-stream, and an idle timer does. No `connectionTimeout` is passed,
-    // deliberately — its timer starts when the request is created and is
-    // cleared only when the agent *assigns* a socket, so the time a request
-    // spends queued behind `maxSockets` counts against it. At the thousand-wide
-    // fan-out this package documents, any value short enough to be useful
-    // destroys healthy writes that this library then retries, and any value
-    // long enough to be safe bounds nothing the request timeout does not
-    // already bound.
-    const ddbClient = createClient({
-        maxAttempts: 1,
-        requestHandler: {
-            requestTimeout: exports.DEFAULT_REQUEST_TIMEOUT_MS,
-            socketTimeout: exports.DEFAULT_SOCKET_TIMEOUT_MS,
-            throwOnRequestTimeout: true,
-        },
-        ...options.clientConfig,
-    });
-    return { ddbClient, client: lib_dynamodb_1.DynamoDBDocument.from(ddbClient), ownsClient: true };
-}
+export declare function resolveDynamoDBClient(options: ResolveClientOptions): ResolvedDynamoDBClient;
 /**
  * Warn once when an injected client keeps the SDK's own retries.
  *
@@ -149,19 +130,48 @@ function resolveDynamoDBClient(options) {
  * handed over, so one without a handler timeout leaves a single attempt
  * unbounded even with the SDK's retries switched off.
  */
-async function warnOnStackedRetries(client, logger) {
-    const report = client.config
-        ?.maxAttempts;
-    if (typeof report !== 'function')
-        return;
-    try {
-        const maxAttempts = await report();
-        if (maxAttempts > 1) {
-            logger.warn("injected DynamoDB client keeps the SDK's own retries; they stack inside this library's " +
-                'retry budget — construct it with maxAttempts: 1 unless that is intended', { maxAttempts });
-        }
-    }
-    catch {
-        // A client that cannot report its retry setting is left alone.
-    }
-}
+export declare function warnOnStackedRetries(client: DynamoDBDocumentLike, logger: Logger): Promise<void>;
+/**
+ * A row, or a key, as the DocumentClient returns and takes it: attribute names
+ * mapped to values that nothing has checked yet. Each feature's row parser
+ * turns one into that feature's row type.
+ */
+export type AttributeMap = Record<string, NativeAttributeValue>;
+/**
+ * A single `BatchWriteItem` write request, as the document client takes it —
+ * a `PutRequest` carrying the item, or a `DeleteRequest` carrying the key:
+ * the shape of each entry a `BATCH_WRITE_INCOMPLETE` error's
+ * `details.unprocessed` carries, verbatim, so a caller can re-submit it.
+ */
+export type WriteRequest = {
+    PutRequest: {
+        Item: Record<string, NativeAttributeValue>;
+    };
+} | {
+    DeleteRequest: {
+        Key: Record<string, NativeAttributeValue>;
+    };
+};
+/** One action of a `TransactWriteItems` request, as the document client takes it. */
+export type TransactAction = NonNullable<TransactWriteCommandInput['TransactItems']>[number];
+/**
+ * The DocumentClient surface this library uses, named by shape rather than by
+ * identity. A `DynamoDBDocument` satisfies it, and so does a client built from
+ * a different copy of `@aws-sdk/lib-dynamodb`.
+ *
+ * That second case is the reason it exists. A consumer pinned to an older SDK
+ * than this package depends on gets a second, newer copy nested under the
+ * package; naming `DynamoDBDocument` in an option type would name *that* copy,
+ * and the client the consumer built is then a different type with the same
+ * name — refused at compile time for a method this library never calls, on the
+ * injection path the documentation recommends. Injection always worked at
+ * runtime; only the compiler stood in the way.
+ *
+ * The members are the eight the runtime collaborator check already requires,
+ * pinned equal to that list by a test — a client this type accepts and the
+ * constructor then rejects, or the reverse, would be worse than either rule
+ * alone. Picking them off `DynamoDBDocument` keeps each signature the SDK's
+ * own, so the internals stay exactly as type-safe as they were and the
+ * signatures cannot drift from the SDK this package installs.
+ */
+export type DynamoDBDocumentLike = Pick<DynamoDBDocument, 'batchWrite' | 'delete' | 'get' | 'put' | 'query' | 'scan' | 'transactWrite' | 'update'>;

package/dist/esm/shared/dynamodb/client.js

@@ -0,0 +1,35 @@
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocument, } from '@aws-sdk/lib-dynamodb';
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+export const DEFAULT_SOCKET_TIMEOUT_MS = 5_000;
+export function resolveDynamoDBClient(options) {
+    if (options.client) {
+        return { ddbClient: undefined, client: options.client, ownsClient: false };
+    }
+    const createClient = options.createClient ?? ((config) => new DynamoDBClient(config));
+    const ddbClient = createClient({
+        ...options.clientConfig,
+        maxAttempts: options.clientConfig?.maxAttempts ?? 1,
+        requestHandler: options.clientConfig?.requestHandler ?? {
+            requestTimeout: DEFAULT_REQUEST_TIMEOUT_MS,
+            socketTimeout: DEFAULT_SOCKET_TIMEOUT_MS,
+            throwOnRequestTimeout: true,
+        },
+    });
+    return { ddbClient, client: DynamoDBDocument.from(ddbClient), ownsClient: true };
+}
+export async function warnOnStackedRetries(client, logger) {
+    const report = client.config
+        ?.maxAttempts;
+    if (typeof report !== 'function')
+        return;
+    try {
+        const maxAttempts = await report();
+        if (maxAttempts > 1) {
+            logger.warn("injected DynamoDB client keeps the SDK's own retries; they stack inside this library's " +
+                'retry budget — construct it with maxAttempts: 1 unless that is intended', { maxAttempts });
+        }
+    }
+    catch {
+    }
+}