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

package/dist/esm/shared/dynamodb/cancellation.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Hides how a cancelled transaction says why it failed.
+ *
+ * A `TransactionCanceledException` carries one raw reason per item, in the
+ * order the items were sent, under codes that are not the exception names the
+ * same failures carry outside a transaction. Which reason is a guard
+ * rejection, which are transient or throttling, and which item failed its
+ * 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.
+ */
+import type { AttributeValue } from '@aws-sdk/client-dynamodb';
+/**
+ * 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.
+ */
+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.
+ *
+ * Accepts: `error` — any error; only a `TransactionCanceledException` carries
+ * the field.
+ *
+ * Its parameter is the weak {@link RejectionFields} rather than `Error`, which
+ * is a deliberate trade: `{}` and `{ name }` now compile where they did not,
+ * and in exchange this module stays the only place that dereferences
+ * `CancellationReasons`, so {@link conditionalCheckFailure}, the retry
+ * classifier and the two history readers cannot drift apart in how they read
+ * it. Every value that reaches it at runtime comes from a `catch`; the two
+ * call sites inside this package that pass it along rather than an `Error`
+ * ({@link conditionalCheckFailure} and `isConditionalCheckFailed`) received
+ * one from a `catch` themselves.
+ *
+ * Returns: one entry per transaction item, in the order the items were sent
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html),
+ * or `undefined` when the error carries none — which is what an older service
+ * response, a different failure, or a thrown value that is not an object at
+ * all looks like.
+ *
+ * Throws: **nothing**, for any value a `throw` can produce. Every value that
+ * reaches this came from a `catch`, and `null` is one a `catch` can bind: the
+ * property read raised a `TypeError` there, inside the classification the
+ * retry layer makes before it decides whether to try again.
+ */
+export declare function getCancellationReasons(error: RejectionFields): CancellationReason[] | undefined;
+/**
+ * The reason belonging to the one item a transaction's guard turned away.
+ *
+ * A cancellation names every item, so "was this write rejected by its
+ * condition?" is only answerable once the items that were merely along for the
+ * ride are set aside. What must remain is a single cause, and it must be the
+ * condition: a cancellation that also failed a second item for its own reason
+ * is not a guard rejection, and reporting one would hide the other failure.
+ *
+ * A reason carrying no `Code` counts as a cause here, while the retry
+ * classifier treats that same shape as transient. The disagreement is
+ * deliberate, because the two readers are conservative in opposite directions:
+ * for the classifier, an unreadable reason may be retried, which a request
+ * token makes harmless; here it must **not** be read as a clean rejection,
+ * since acting on one discards whatever else the transaction failed on. AWS
+ * populates `Code` for every item, so neither branch is reachable in practice.
+ *
+ * Accepts: `error` — any error; only a cancellation carries reasons.
+ *
+ * Returns: the sole `ConditionalCheckFailed` reason — with the rejected row
+ * attached when the item asked for it — or `undefined` for every other error,
+ * including a cancellation with no reasons, a different cause, or more than
+ * one.
+ *
+ * Throws: nothing.
+ */
+export declare function conditionalCheckFailure(error: RejectionFields): CancellationReason | undefined;
+/**
+ * Whether a cancelled transaction failed only for transient reasons.
+ *
+ * Accepts: `error` — any error; only a cancellation carries reasons.
+ *
+ * Returns: `undefined` when the error carries no reasons, so the caller's
+ * ordinary signal matching applies; otherwise whether every reason is
+ * transient. A cancellation carrying no reasons at all is not transient.
+ *
+ * Throws: nothing, for any value; see {@link getCancellationReasons}.
+ */
+export declare function transientCancellation(error: RejectionFields): boolean | undefined;
+/**
+ * Whether a cancelled transaction was throttled.
+ *
+ * Accepts: `error` — any error; only a cancellation carries reasons.
+ *
+ * Returns: true when any reason is a throttling reason. Meaningful only for a
+ * cancellation {@link transientCancellation} already found transient, which is
+ * the one place it is asked.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function throttledCancellation(error: RejectionFields): boolean;
+/**
+ * Whether the item at `index` of a cancelled transaction failed its condition.
+ *
+ * Accepts: `error` — any error. `index` — the item's position in the
+ * `TransactItems` the caller sent; reasons come back in that order.
+ *
+ * Returns: true when that item's reason is `ConditionalCheckFailed`, whatever
+ * the other items' reasons are; false for anything that is not such a
+ * cancellation.
+ *
+ * Throws: nothing, for any value.
+ */
+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/esm/shared/dynamodb/client.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 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
+ * each request.
+ *
+ * The structural type is what lets a caller inject any DocumentClient-shaped
+ * object, and it is public; the row shapes travel through every module that
+ * reads or writes a row; the construction is the one place a request timeout
+ * and a socket timeout are set, and the one place that knows whether the
+ * adapter owns the client it holds.
+ */
+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
+ * retryable `TimeoutError`. `MAX_WRITE_LIFETIME_MS`
+ * (`src/shared/dynamodb/retry.ts`) bounds how many attempts *start*; it is
+ * checked between them, so it can refuse to begin another wait and can never
+ * shorten the attempt already in flight. Without a handler timeout — every one
+ * of them defaults to 0 — a hung socket holds that attempt open forever and
+ * the write lifetime bounds nothing.
+ *
+ * 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.
+ */
+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
+ * as depends on when it fires: before response headers the handler's own
+ * rejection reaches the caller as a `TimeoutError`, while after them the call
+ * has already resolved and the destroy arrives through the response stream
+ * instead, as an `ECONNRESET` abort. Both are classified retryable, so either
+ * way a stalled transfer becomes a retry of this library's own. An idle timer
+ * rather than a deadline: activity in either direction resets it, so it bounds
+ * a transfer that has stalled and never one that is merely slow, and its clock
+ * starts at socket assignment rather than at request creation. What each
+ * client needs it *for* differs, so that belongs at each client's own call
+ * site rather than here.
+ *
+ * Not a tuning knob. The handler installs the socket listener immediately only
+ * below 6 000 ms; at or above that it defers registration by 3 000 ms and
+ * returns the deferral's timer id, which the handler's clear-on-resolve
+ * cancels when response headers arrive — so at 6 000 or more the field
+ * silently stops doing anything for every response that answers inside three
+ * seconds, which is the normal case. That is a fact about the request handler
+ * and about neither client. A unit assertion holds this value under that
+ * threshold so raising it fails loudly instead of disabling the only bound a
+ * stalled transfer has.
+ */
+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.
+ *
+ * Accepts: `client` — an injected DocumentClient, used as-is; `clientConfig` —
+ * what one is built from when no client is injected; `createClient` — the test
+ * seam that builds it. `assertBaseAdapterOptions` rejects an injected client
+ * given alongside either of the other two, so only one branch is ever taken.
+ *
+ * Returns: the document client, the raw client behind it when this call built
+ * one, and `ownsClient` — true only then. An injected client is never
+ * destroyed by `destroy()`; it may be shared with the caller's own code and
+ * with the other adapters.
+ *
+ * Throws: whatever the SDK constructor throws for an unusable config.
+ *
+ * Guarantees: a client this call builds gets `maxAttempts: 1` unless the config
+ * overrides it, so the SDK performs no retries of its own and this library's
+ * retry layer is the only one. It also gets a default request handler that
+ * 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. Either key named with `undefined` overrides
+ * nothing and keeps its default. An injected client keeps whatever it was
+ * built with — see {@link warnOnStackedRetries}.
+ */
+export declare function resolveDynamoDBClient(options: ResolveClientOptions): ResolvedDynamoDBClient;
+/**
+ * Warn once when an injected client keeps the SDK's own retries.
+ *
+ * Accepts: `client` — the caller's. A client that cannot report its setting —
+ * a stub, a mock, a future SDK shape — is left alone.
+ *
+ * Returns: nothing. Deliberately not awaited by its callers: it is a warning
+ * about a caller-supplied client, not a precondition for using it, so
+ * constructing an adapter stays free of I/O.
+ *
+ * Throws: nothing, ever. The SDK's own config resolution can reject, and a
+ * rejection here would surface as an unhandled rejection from a constructor
+ * that did nothing wrong.
+ *
+ * Guarantees: the SDK's retries run inside every attempt of this library's
+ * retry layer, so the budget the constants and README describe multiplies (5 ×
+ * 3 requests per operation at the SDK default) and a throttling event turns
+ * into a retry storm. Saying so once, at construction, is the only place the
+ * caller can act on it.
+ *
+ * The one gap a deadline cannot cover. A tokened write's budget is bounded by
+ * `MAX_WRITE_LIFETIME_MS`, but that bound is checked between attempts: it can
+ * refuse to start another wait, and it cannot shorten an attempt already in
+ * flight. An injected client that retries internally turns one of this
+ * library's attempts into several of its own, so the time spent inside a
+ * single attempt stops being bounded by anything this library sets — which is
+ * why the warning says to construct it with `maxAttempts: 1`.
+ *
+ * `maxAttempts: 1` is necessary but not sufficient. The per-attempt bound
+ * holds for an injected client only if it also carries its own request
+ * timeout: a client this library builds is given one
+ * ({@link resolveDynamoDBClient}), and an injected client is used exactly as
+ * handed over, so one without a handler timeout leaves a single attempt
+ * unbounded even with the SDK's retries switched off.
+ */
+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 {
+    }
+}