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

package/dist/shared/errors/error-code.js

@@ -1,17 +1,99 @@
 "use strict";
+/**
+ * Hides which outcomes a caller can tell apart.
+ *
+ * Every error this library raises carries one of these codes, and a caller
+ * branches on the code rather than on a class, a message or an AWS name. What
+ * produces each code is decided elsewhere, so a newly seen AWS failure maps
+ * onto an existing code without touching this list, and the list is frozen so
+ * no consumer sharing it in a process can change what a comparison means.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorCode = void 0;
 /** Stable, branchable classification for every error this library throws. */
 var ErrorCode;
 (function (ErrorCode) {
     ErrorCode["VALIDATION"] = "VALIDATION";
+    /** A row or payload written in a format version newer than this package reads. */
+    ErrorCode["FORMAT_UNSUPPORTED"] = "FORMAT_UNSUPPORTED";
+    /**
+     * A checkpoint a delta channel still needs has expired, so the channel cannot
+     * be reconstructed and the read refuses rather than returning a shorter value.
+     */
+    ErrorCode["ANCESTOR_EXPIRED"] = "ANCESTOR_EXPIRED";
     ErrorCode["CONDITION_CONFLICT"] = "CONDITION_CONFLICT";
     ErrorCode["RETRY_EXHAUSTED"] = "RETRY_EXHAUSTED";
     ErrorCode["BATCH_WRITE_INCOMPLETE"] = "BATCH_WRITE_INCOMPLETE";
     ErrorCode["COMPRESSION_LIMIT"] = "COMPRESSION_LIMIT";
+    /**
+     * A stored payload's bytes do not match the form its row declares: the row
+     * says gzip and they are not, or they are not the serializer's output. The
+     * payload can never be read, so it is reported rather than retried.
+     */
+    ErrorCode["PAYLOAD_CORRUPT"] = "PAYLOAD_CORRUPT";
     ErrorCode["S3_OFFLOAD_FAILED"] = "S3_OFFLOAD_FAILED";
     ErrorCode["RESULT_TRUNCATED"] = "RESULT_TRUNCATED";
     ErrorCode["ABORTED"] = "ABORTED";
     ErrorCode["COMPENSATION_FAILED"] = "COMPENSATION_FAILED";
+    /**
+     * AWS throttled the request: `ProvisionedThroughputExceededException`,
+     * `ThrottlingException`, `RequestLimitExceeded`, S3's `SlowDown`, an HTTP
+     * 429, or a cancelled transaction whose causes are all transient and include
+     * a throttling reason. Back off, or raise the table's capacity or the account
+     * quota.
+     */
+    ErrorCode["THROTTLED"] = "THROTTLED";
+    /**
+     * AWS or the network failed transiently: `InternalServerError`,
+     * `InternalFailure`, `ServiceUnavailable`, S3's `InternalError`, a request
+     * timeout (`RequestTimeout`, `RequestTimeoutException`, the SDK's
+     * `TimeoutError`), an HTTP 500/502/503/504, or a reset, refused or
+     * unreachable connection. Retry after a backoff. A write that failed this way
+     * may still have been applied.
+     */
+    ErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    /**
+     * Another request was writing the same item or object at the same moment:
+     * `TransactionConflictException`, `TransactionInProgressException`,
+     * `ReplicatedWriteConflictException`, S3's `ConditionalRequestConflict`, or a
+     * cancelled transaction whose only transient cause is a conflict. Retry; more
+     * capacity would not help.
+     */
+    ErrorCode["CONTENTION"] = "CONTENTION";
+    /**
+     * AWS refused the caller's identity or permissions: `AccessDeniedException`,
+     * S3's `AccessDenied`, an expired, unrecognised or malformed credential or
+     * signature. Fix the credentials or the IAM policy; do not retry.
+     * `context.awsErrorName` says which.
+     */
+    ErrorCode["ACCESS_DENIED"] = "ACCESS_DENIED";
+    /**
+     * The table, index, bucket or object is not there: `ResourceNotFoundException`,
+     * S3's `NoSuchBucket` or `NoSuchKey`. Not an absent item — a read of a key that
+     * holds nothing returns nothing.
+     */
+    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    /**
+     * AWS rejected the request as malformed: `ValidationException`,
+     * AWS's `ValidationError` common error, `IdempotentParameterMismatchException`,
+     * or a request body it could not read or accept. Retrying the same request
+     * fails the same way.
+     */
+    ErrorCode["AWS_REJECTED"] = "AWS_REJECTED";
+    /** An AWS request failed and no narrower code applies; `context.awsErrorName` names it. */
+    ErrorCode["AWS_REQUEST_FAILED"] = "AWS_REQUEST_FAILED";
+    /**
+     * A failure that came neither from this package's own checks nor from AWS:
+     * a `VectorBackend`, an `Embeddings` model, a `serde` or a `MultiSessionHistory`
+     * threw something of its own, or this package has a bug. The original is
+     * `cause`.
+     */
+    ErrorCode["UNEXPECTED_ERROR"] = "UNEXPECTED_ERROR";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
-//# sourceMappingURL=error-code.js.map
+// A TypeScript enum compiles to a plain, writable object, and this one is
+// exported from the package root: every consumer in a process shares the same
+// object. One dependency assigning to a member — a test stub, a patch, a
+// typo — rewrites what `error.code === ErrorCode.X` means for every other
+// consumer at once, and nothing is raised anywhere; the branch simply stops
+// matching. Freezing turns that into a refusal at the assignment.
+Object.freeze(ErrorCode);

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

@@ -1,68 +1,167 @@
-import type { WriteRequest } from '../dynamodb/types';
-import { DynamoDbLangGraphError } from './base-error';
-/** Input failed a validation rule before any AWS call was made. */
-export declare class ValidationError extends DynamoDbLangGraphError {
-    constructor(message: string, field?: string);
-}
-/** A conditional write failed because the precondition no longer holds. */
-export declare class ConflictError extends DynamoDbLangGraphError {
-    constructor(message: string, cause?: Error);
-}
-/** A retried operation exhausted its attempt budget. */
-export declare class RetryExhaustedError extends DynamoDbLangGraphError {
-    constructor(message: string, attempts?: number, cause?: Error);
-}
 /**
- * A paginated read hit its runaway guard (item or iteration cap) while more
- * data remained, so the result would have been silently truncated. Narrow the
- * query (filter/prefix) or raise the cap rather than trusting a partial result.
+ * Hides what each of this library's errors carries, for the codes that have
+ * a factory here.
+ *
+ * A failure site with a factory below names it for its code and the facts it
+ * has. The message wording, which facts go into `context` or `details`,
+ * copying a list a caller reads from a `catch` long after the throw,
+ * redacting quoted cause text, and a stack that starts at the caller rather
+ * than inside the factory are decided here once per code, on the one error
+ * class (record 19). `FORMAT_UNSUPPORTED`, `PAYLOAD_CORRUPT`,
+ * `COMPRESSION_LIMIT`, `S3_OFFLOAD_FAILED` and `ANCESTOR_EXPIRED` are raised
+ * with `new DynamoDBLangGraphError` at their own call sites instead, and
+ * every AWS-classified code is wrapped once, by `wrapForeignError` in the
+ * error boundary, not per code here.
  */
-export declare class ResultTruncatedError extends DynamoDbLangGraphError {
-    constructor(cap: string, limit: number);
-}
-/** An operation was cancelled via its AbortSignal. */
-export declare class AbortError extends DynamoDbLangGraphError {
-    constructor(message?: string);
-}
+import type { WriteRequest } from '../dynamodb/client';
+import { DynamoDBLangGraphError } from './base-error';
+import { ErrorCode } from './error-code';
 /**
- * A BatchWriteItem sequence could not drain its UnprocessedItems. Items NOT
- * listed in {@link unprocessed} were acked by DynamoDB and persist — there is
- * no rollback (drive reconciliation from `unprocessed`). `cause`, when given,
- * is the underlying failure that interrupted the drain (e.g. a thrown,
- * non-UnprocessedItems error from a retry round) rather than a clean exhaustion
- * of the UnprocessedItems retry budget.
+ * The error for input that failed a check before any AWS call was made.
+ *
+ * Accepts: `message` — already redacted by whoever composed it. `field` — the
+ * option, argument or cap that failed, dotted for a nested one
+ * (`s3.bucketName`); omitted only where no single input is at fault. `cause` —
+ * the refusal beneath it.
+ *
+ * Returns: a `VALIDATION` error, with `context.field` set when a field was
+ * named — which is what a caller branches on to point at the offending input.
+ *
+ * Throws: nothing; building an error may not fail.
  */
-export declare class BatchWriteIncompleteError extends DynamoDbLangGraphError {
-    readonly succeededCount: number;
-    readonly unprocessed: WriteRequest[];
-    constructor(succeededCount: number, unprocessed: WriteRequest[], retries: number, cause?: Error);
-}
+export declare function validationError(message: string, field?: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.VALIDATION>;
 /**
- * batchWriteAll attempts every chunk rather than stopping at the first
- * failure — a mid-sequence chunk failing does not abandon the chunks after
- * it. `failedChunks` holds each failing chunk's own error (commonly a
- * {@link BatchWriteIncompleteError}); every chunk not represented there
- * drained successfully and its writes persist — there is no rollback.
- * `succeededCount` is the exact number of individual write requests
- * confirmed persisted across every chunk (full chunks plus any failed
- * chunk's own partial drain), more precise than `succeededChunks` alone
- * when a chunk partially drains before exhausting its retries.
+ * The error for a conditional write whose precondition no longer holds.
+ *
+ * Accepts: `message` — what precondition no longer held. `cause` — the
+ * rejection beneath it, when there is one.
+ *
+ * Returns: a `CONDITION_CONFLICT` error. A caller may retry the operation
+ * from a fresh read; nothing was written.
+ *
+ * Throws: nothing; building an error may not fail.
  */
-export declare class BatchWriteAllIncompleteError extends DynamoDbLangGraphError {
-    readonly succeededChunks: number;
-    readonly totalChunks: number;
-    readonly failedChunks: Error[];
-    readonly succeededCount: number;
-    constructor(succeededChunks: number, totalChunks: number, failedChunks: Error[], succeededCount?: number);
-}
+export declare function conflictError(message: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.CONDITION_CONFLICT>;
+/**
+ * The error for a retried operation that exhausted its attempt budget.
+ *
+ * Accepts: `attempts` — how many were made before the budget ran out.
+ * `cause` — the last failure, kept so a caller can classify what actually
+ * went wrong.
+ *
+ * Returns: a `RETRY_EXHAUSTED` error, with `context.attempts` when `attempts`
+ * was given. It says the attempts are spent, **not** that the operation did
+ * not happen: a write whose response was lost is reported this way too, which
+ * is why every caller that would delete something reads the row back first.
+ *
+ * Throws: nothing; building an error may not fail.
+ */
+export declare function retryExhaustedError(message: string, attempts?: number, cause?: Error): DynamoDBLangGraphError<ErrorCode.RETRY_EXHAUSTED>;
 /**
- * A compensating rollback failed after an append-saga chunk error, so the
- * trigger error could not be cleanly undone. Carries the original trigger as
- * `cause` and the rollback failure as {@link rollbackError}; the session's
- * `messageCount` may have drifted — repair it with `reconcileMessageCount`.
+ * The error for a paginated read that hit its runaway guard (item or
+ * iteration cap) while more data remained, so the result would have been
+ * silently truncated. Narrow the query (filter/prefix) or raise the cap rather
+ * than trusting a partial result.
+ *
+ * Accepts: `cap` — which cap was hit (`maxItems`, `maxIterations`). `limit` —
+ * its value, quoted in the message so the fix is obvious.
+ *
+ * Returns: a `RESULT_TRUNCATED` error, with `context.field` naming the cap.
+ * Raised only when data actually remained, so it never turns a complete
+ * result into a failure.
+ *
+ * Throws: nothing; building an error may not fail.
  */
-export declare class CompensationFailedError extends DynamoDbLangGraphError {
-    readonly rollbackError: Error;
-    constructor(cause: Error, rollbackError: Error);
+export declare function resultTruncatedError(cap: string, limit: number): DynamoDBLangGraphError<ErrorCode.RESULT_TRUNCATED>;
+/**
+ * The error for an operation cancelled via its `AbortSignal`.
+ *
+ * Accepts: `message` — defaults to `Operation aborted`. `cause` — the
+ * `AbortSignal`'s own reason, when it carried one.
+ *
+ * Returns: an `ABORTED` error. Distinct from every failure code on purpose: a
+ * caller who cancelled did not encounter a fault, and treating the two alike
+ * reported an incomplete write for a deliberate stop.
+ *
+ * Throws: nothing; building an error may not fail.
+ */
+export declare function abortError(message?: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.ABORTED>;
+/**
+ * The error for a `BatchWriteItem` sequence that could not drain its
+ * `UnprocessedItems`.
+ *
+ * Accepts: `succeededCount` — writes DynamoDB acked. `unprocessed` — the
+ * requests it did not, verbatim, so they can be re-submitted. `retries` —
+ * rounds spent. `cause` — an error that interrupted the drain (a thrown,
+ * non-`UnprocessedItems` error from a retry round), rather than a clean
+ * exhaustion of the `UnprocessedItems` retry budget.
+ *
+ * Returns: a `BATCH_WRITE_INCOMPLETE` error whose `details` (`kind: 'drain'`)
+ * carry both counts and the list. Items *not* listed in `details.unprocessed`
+ * persist: there is no rollback, so reconciliation is driven from that list.
+ * That list is **copied**: it is read from a `catch` long after the throw, and
+ * a caller reusing its request buffer must not be able to rewrite it.
+ *
+ * Throws: nothing; building an error may not fail. Anything but an array of
+ * requests reads as an empty list rather than crashing the report.
+ */
+export declare function batchWriteIncompleteError(succeededCount: number, unprocessed: WriteRequest[], retries: number, cause?: Error): DynamoDBLangGraphError<ErrorCode.BATCH_WRITE_INCOMPLETE>;
+/** What a batch that could not finish reports. */
+export interface IncompleteBatch {
+    /** Chunks (or rows) that committed. */
+    readonly succeeded: number;
+    /** Chunks (or rows) the batch had. */
+    readonly total: number;
+    readonly failures: Error[];
+    /** Requests that committed, when a chunk is more than one request. */
+    readonly succeededCount?: number;
+    readonly unit?: 'row';
 }
-//# sourceMappingURL=errors.d.ts.map
+/**
+ * The error for a `batchWriteAll` pass — or a partition-wide delete — that did
+ * not fully drain. `batchWriteAll` attempts every chunk rather than stopping
+ * at the first failure, so a mid-sequence chunk failing does not abandon the
+ * chunks after it. A partition-wide delete reports through the same shape,
+ * because what it answers is the same question — how much of this call got
+ * through — but it sends one conditional request per row rather than a batch
+ * of twenty-five, so it counts rows where a batch counts chunks and says so in
+ * its message.
+ *
+ * Accepts: `batch.succeeded`/`batch.total` — the chunk tally. `batch.failures`
+ * — each failing chunk's own error, commonly a `BATCH_WRITE_INCOMPLETE` drain
+ * error. `batch.succeededCount` — individual writes confirmed persisted across
+ * every chunk (full chunks plus any failed chunk's own partial drain), which
+ * is more precise than the chunk tally when a chunk partially drains.
+ * `batch.unit` — what the first two counts count; omitting it reproduces the
+ * batch wording exactly.
+ *
+ * Returns: a `BATCH_WRITE_INCOMPLETE` error whose `details` (`kind: 'pass'`)
+ * carry the tally, with the first failing chunk's error as `cause`. Every
+ * chunk not represented in `details.failedChunks` drained successfully and its
+ * writes persist — there is no rollback. The list is **copied**, for the same
+ * reason a drain error copies its own.
+ *
+ * Throws: nothing; building an error may not fail. Anything but an array of
+ * errors reads as an empty list rather than crashing the report.
+ */
+export declare function batchWriteAllIncompleteError(batch: IncompleteBatch): DynamoDBLangGraphError<ErrorCode.BATCH_WRITE_INCOMPLETE>;
+/**
+ * The error for a compensating rollback that failed after an append-saga
+ * chunk error, so the trigger could not be cleanly undone.
+ *
+ * Accepts: `cause` — the failure that triggered the rollback. `rollbackError`
+ * — why the rollback itself could not finish. Both are built from a `catch`,
+ * so either may be whatever a `throw` produced rather than an `Error`.
+ *
+ * Returns: a `COMPENSATION_FAILED` error carrying the trigger as `cause` and
+ * the rollback failure as `details.rollbackError`, each normalised through
+ * `toError` so both are always error-shaped. The session's `messageCount` may
+ * have drifted, which `reconcileMessageCount` repairs; the quoted text of both
+ * errors is redacted before it is embedded.
+ *
+ * Throws: nothing; building an error may not fail. Reading `.message` off a
+ * thrown `null` or `undefined` would throw here, inside the `catch` reporting
+ * the rollback — which is why `toError` normalises both `cause` and
+ * `rollbackError` before anything reads off them.
+ */
+export declare function compensationFailedError(cause: Error, rollbackError: Error): DynamoDBLangGraphError<ErrorCode.COMPENSATION_FAILED>;