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

package/dist/shared/errors/boundary.js

@@ -1,143 +0,0 @@
-"use strict";
-/**
- * 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 with the operation named, and anything else — an SDK
- * failure, a caller's thrown value — is classified and wrapped with its cause
- * attached and its text redacted.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toPublicError = toPublicError;
-exports.guardPublic = guardPublic;
-exports.guardPublicIterable = guardPublicIterable;
-exports.wrapForeignError = wrapForeignError;
-const secret_patterns_1 = require("../logging/secret-patterns");
-const truncate_1 = require("../logging/truncate");
-const base_error_1 = require("./base-error");
-const classify_1 = require("./classify");
-const error_code_1 = require("./error-code");
-/**
- * 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).
- *
- * Returns: a branded library error unchanged, since its code was assigned
- * closer to the failure and wins; anything else wrapped by
- * {@link wrapForeignError}, with the code the classifier assigns.
- *
- * Throws: nothing. It runs inside a `catch`, where throwing would discard the
- * failure being reported and replace it with its own.
- */
-function toPublicError(error, operation) {
-    const normalized = (0, base_error_1.toError)(error);
-    return (0, base_error_1.isDynamoDBLangGraphError)(normalized)
-        ? normalized
-        : wrapForeignError(normalized, operation);
-}
-/**
- * Run a public operation so that every rejection is a library error.
- *
- * Accepts: `operation` — the public method's name, which the wrapped error
- * carries. `fn` — the work.
- *
- * 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.
- */
-async function guardPublic(operation, fn) {
-    try {
-        return await fn();
-    }
-    catch (error) {
-        throw toPublicError(error, operation);
-    }
-}
-/**
- * The same guard for a streaming result.
- *
- * Accepts: `operation` — the public method's name. `source` — the generator to
- * relay.
- *
- * 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.
- */
-async function* guardPublicIterable(operation, source) {
-    try {
-        for await (const item of source)
-            yield item;
-    }
-    catch (error) {
-        throw toPublicError(error, operation);
-    }
-}
-/** How far {@link classifiableCause} walks a cause chain before giving up. */
-const MAX_CAUSE_DEPTH = 32;
-/**
- * The node in `error`'s own cause chain — `error` itself, then its `cause`,
- * then that error's own `cause`, and so on — that {@link classifyAwsError}
- * does not answer `UNEXPECTED_ERROR` for.
- *
- * Accepts: `error` — the outermost foreign failure, already normalised by
- * {@link toError}.
- *
- * Returns: the first node the classifier places under an AWS or network code,
- * so a caller's own error wrapping a modeled SDK exception, or an SDK error
- * whose own `cause` is a raw transport failure, still classifies on the
- * AWS/network failure underneath rather than losing it one level up — the
- * same failure the retry layer's cause-chain walk (`isRetryableError` in
- * `shared/dynamodb/retry.ts`) already sees. `error` itself when
- * nothing in its chain classifies either. The walk gives up after
- * {@link MAX_CAUSE_DEPTH} nodes, and a cycle in the chain stops it rather than
- * looping, exactly as that other walk does.
- *
- * Throws: nothing, for any value {@link toError} can produce.
- */
-function classifiableCause(error) {
-    const seen = new WeakSet();
-    let node = error;
-    for (let depth = 0; depth <= MAX_CAUSE_DEPTH; depth += 1) {
-        if ((0, classify_1.classifyAwsError)(node) !== error_code_1.ErrorCode.UNEXPECTED_ERROR)
-            return node;
-        if (typeof node !== 'object' || node === null || seen.has(node))
-            break;
-        seen.add(node);
-        const next = node.cause;
-        if (next === undefined)
-            break;
-        node = next;
-    }
-    return error;
-}
-/**
- * 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.
- */
-function wrapForeignError(cause, operation) {
-    const below = (0, base_error_1.toError)(cause);
-    const classifiable = classifiableCause(below);
-    return new base_error_1.DynamoDBLangGraphError(`${operation}: ${(0, truncate_1.truncateForLog)(below.name)}: ${(0, secret_patterns_1.redactedMessage)(below)}`, (0, classify_1.classifyAwsError)(classifiable), { operation, ...(0, classify_1.awsDiagnostics)(classifiable) }, below);
-}

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

@@ -1,97 +0,0 @@
-/**
- * Hides which AWS failures are the same failure.
- *
- * An SDK error arrives as a name, an HTTP status, a Node network `code` or —
- * for a cancelled transaction — a list of per-item reasons, and several of
- * those arrivals mean one thing to a caller deciding what to do. Their mapping
- * to one `ErrorCode`, and the retry layer's default list of transient names,
- * come from one table here (record 19), so no call site compares an AWS
- * exception name of its own.
- */
-import type { ErrorContext } from './base-error';
-import { ErrorCode } from './error-code';
-/**
- * The Node.js system error codes the SDK's own retry strategy treats as
- * transient regardless of name (`@smithy/core` retry `NODEJS_TIMEOUT_ERROR_CODES`
- * and `NODEJS_NETWORK_ERROR_CODES`). Matched on the error's own `code`.
- */
-export declare const TRANSIENT_NETWORK_ERROR_CODES: readonly string[];
-/**
- * HTTP statuses the SDK retries regardless of name: throttling (429) and the
- * transient server statuses (`@smithy/core` retry `TRANSIENT_ERROR_STATUS_CODES`).
- * They classify an error the SDK could not map to a modeled exception, which
- * arrives as `name: 'Unknown'` with only its status.
- */
-export declare const TRANSIENT_HTTP_STATUSES: readonly number[];
-/**
- * AWS error name to code. Each name is declared by the installed
- * `@aws-sdk/client-dynamodb` or `@aws-sdk/client-s3`, or documented on a page
- * `test/static/aws-error-names.test.ts` cites; that test fails on any other.
- */
-export declare const AWS_ERROR_CODES: Readonly<Record<string, ErrorCode>>;
-/**
- * The retry layer's default tokens: every name {@link AWS_ERROR_CODES} maps to
- * a retryable code, and the network codes. Derived rather than listed, so the
- * retry layer and the code a caller sees share one list of transient names.
- * They differ at two edges: the retry layer also retries on the SDK's
- * `$retryable` trait, which {@link classifyAwsError} does not read, and it
- * walks the cause chain matching `errno` and `syscall` too, where the
- * classifier reads one error's `name`, `code` and status.
- */
-export declare const DEFAULT_RETRYABLE_ERRORS: readonly string[];
-/**
- * The code a failure that is not one of this library's own belongs to.
- *
- * Accepts: anything a `catch` can bind — an SDK error, a transport error, a
- * value from caller-supplied code, `null`, a string.
- *
- * Returns: a transaction cancellation's code from its reasons (a sole
- * `ConditionalCheckFailed` cause is `CONDITION_CONFLICT`; all-transient causes
- * are `THROTTLED` or `CONTENTION`); otherwise the table's code for the error's
- * own `name`; otherwise `SERVICE_UNAVAILABLE` for a transient network `code`;
- * otherwise by HTTP status — 412 `CONDITION_CONFLICT`, 429 `THROTTLED`,
- * 500/502/503/504 `SERVICE_UNAVAILABLE`; otherwise `AWS_REQUEST_FAILED` for an
- * AWS-shaped error and `UNEXPECTED_ERROR` for anything else. Only the error's
- * own fields are read, never its `cause`.
- *
- * Throws: nothing, for any value. It runs inside `catch` blocks.
- */
-export declare function classifyAwsError(error: Error): ErrorCode;
-/**
- * The fields an operator needs first, lifted off an AWS-shaped error.
- *
- * Accepts: anything a `catch` can bind.
- *
- * Returns: `awsErrorName`, `requestId` and `httpStatusCode`, each only when
- * present and well-typed, for an error carrying `$metadata` or a name the table
- * knows or that ends in `Exception`; `{}` for anything else — a bare network
- * failure included, since it may be a caller's own connection rather than AWS's.
- *
- * Throws: nothing, for any value.
- */
-export declare function awsDiagnostics(error: Error): Pick<ErrorContext, 'awsErrorName' | 'requestId' | 'httpStatusCode'>;
-/**
- * Whether an S3 read failed because the object is gone.
- *
- * Accepts: anything a `catch` can bind.
- *
- * Returns: true for `NoSuchKey` only. `NOT_FOUND` also covers a missing
- * bucket, which is a configuration fault; reading it as a lost payload would
- * write off data that is still there.
- *
- * Throws: nothing, for any value.
- */
-export declare function isMissingObject(error: Error): boolean;
-/**
- * Whether reading a bucket's lifecycle configuration failed because the bucket
- * has none.
- *
- * Accepts: anything a `catch` can bind.
- *
- * Returns: true for `NoSuchLifecycleConfiguration` only. `NOT_FOUND` also
- * covers a missing bucket, table or object; reading one of those as "no rules
- * yet" would start a rule set for a bucket that is not there.
- *
- * Throws: nothing, for any value.
- */
-export declare function isMissingLifecycleConfiguration(error: Error): boolean;

package/dist/shared/errors/classify.js

@@ -1,257 +0,0 @@
-"use strict";
-/**
- * Hides which AWS failures are the same failure.
- *
- * An SDK error arrives as a name, an HTTP status, a Node network `code` or —
- * for a cancelled transaction — a list of per-item reasons, and several of
- * those arrivals mean one thing to a caller deciding what to do. Their mapping
- * to one `ErrorCode`, and the retry layer's default list of transient names,
- * come from one table here (record 19), so no call site compares an AWS
- * exception name of its own.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RETRYABLE_ERRORS = exports.AWS_ERROR_CODES = exports.TRANSIENT_HTTP_STATUSES = exports.TRANSIENT_NETWORK_ERROR_CODES = void 0;
-exports.classifyAwsError = classifyAwsError;
-exports.awsDiagnostics = awsDiagnostics;
-exports.isMissingObject = isMissingObject;
-exports.isMissingLifecycleConfiguration = isMissingLifecycleConfiguration;
-const cancellation_1 = require("../dynamodb/cancellation");
-const error_code_1 = require("./error-code");
-/**
- * The Node.js system error codes the SDK's own retry strategy treats as
- * transient regardless of name (`@smithy/core` retry `NODEJS_TIMEOUT_ERROR_CODES`
- * and `NODEJS_NETWORK_ERROR_CODES`). Matched on the error's own `code`.
- */
-exports.TRANSIENT_NETWORK_ERROR_CODES = [
-    'ECONNRESET',
-    'ECONNREFUSED',
-    'EPIPE',
-    'ETIMEDOUT',
-    'EHOSTUNREACH',
-    'ENETUNREACH',
-    'ENOTFOUND',
-    'EAI_AGAIN',
-];
-/**
- * HTTP statuses the SDK retries regardless of name: throttling (429) and the
- * transient server statuses (`@smithy/core` retry `TRANSIENT_ERROR_STATUS_CODES`).
- * They classify an error the SDK could not map to a modeled exception, which
- * arrives as `name: 'Unknown'` with only its status.
- */
-exports.TRANSIENT_HTTP_STATUSES = [429, 500, 502, 503, 504];
-/** The status S3 answers a failed `If-None-Match: *` precondition with. */
-const PRECONDITION_FAILED_STATUS = 412;
-const TRANSACTION_CANCELLED = 'TransactionCanceledException';
-/**
- * AWS error name to code. Each name is declared by the installed
- * `@aws-sdk/client-dynamodb` or `@aws-sdk/client-s3`, or documented on a page
- * `test/static/aws-error-names.test.ts` cites; that test fails on any other.
- */
-exports.AWS_ERROR_CODES = {
-    ProvisionedThroughputExceededException: error_code_1.ErrorCode.THROTTLED,
-    ThrottlingException: error_code_1.ErrorCode.THROTTLED,
-    RequestLimitExceeded: error_code_1.ErrorCode.THROTTLED,
-    SlowDown: error_code_1.ErrorCode.THROTTLED,
-    InternalServerError: error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    InternalFailure: error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    ServiceUnavailable: error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    InternalError: error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    RequestTimeout: error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    RequestTimeoutException: error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    TimeoutError: error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    TransactionConflictException: error_code_1.ErrorCode.CONTENTION,
-    TransactionInProgressException: error_code_1.ErrorCode.CONTENTION,
-    ReplicatedWriteConflictException: error_code_1.ErrorCode.CONTENTION,
-    /**
-     * S3's `409` on a conditional write whose key was deleted between the check
-     * and the write; the S3 User Guide's remedy on `PutObject` is to retry the
-     * upload (*How to prevent object overwrites with conditional writes*,
-     * "Conditional write behavior").
-     */
-    ConditionalRequestConflict: error_code_1.ErrorCode.CONTENTION,
-    AccessDeniedException: error_code_1.ErrorCode.ACCESS_DENIED,
-    AccessDenied: error_code_1.ErrorCode.ACCESS_DENIED,
-    ExpiredTokenException: error_code_1.ErrorCode.ACCESS_DENIED,
-    ExpiredToken: error_code_1.ErrorCode.ACCESS_DENIED,
-    IncompleteSignature: error_code_1.ErrorCode.ACCESS_DENIED,
-    IncompleteSignatureException: error_code_1.ErrorCode.ACCESS_DENIED,
-    InvalidAccessKeyId: error_code_1.ErrorCode.ACCESS_DENIED,
-    MissingAuthenticationTokenException: error_code_1.ErrorCode.ACCESS_DENIED,
-    NotAuthorized: error_code_1.ErrorCode.ACCESS_DENIED,
-    SignatureDoesNotMatch: error_code_1.ErrorCode.ACCESS_DENIED,
-    UnrecognizedClientException: error_code_1.ErrorCode.ACCESS_DENIED,
-    ResourceNotFoundException: error_code_1.ErrorCode.NOT_FOUND,
-    NoSuchBucket: error_code_1.ErrorCode.NOT_FOUND,
-    NoSuchKey: error_code_1.ErrorCode.NOT_FOUND,
-    NoSuchLifecycleConfiguration: error_code_1.ErrorCode.NOT_FOUND,
-    ValidationException: error_code_1.ErrorCode.AWS_REJECTED,
-    ValidationError: error_code_1.ErrorCode.AWS_REJECTED,
-    IdempotentParameterMismatchException: error_code_1.ErrorCode.AWS_REJECTED,
-    MalformedHttpRequestException: error_code_1.ErrorCode.AWS_REJECTED,
-    RequestEntityTooLargeException: error_code_1.ErrorCode.AWS_REJECTED,
-    ConditionalCheckFailedException: error_code_1.ErrorCode.CONDITION_CONFLICT,
-    PreconditionFailed: error_code_1.ErrorCode.CONDITION_CONFLICT,
-    /** An item collection past 10 GB: neither a retry nor a changed request helps; an operator must act. */
-    ItemCollectionSizeLimitExceededException: error_code_1.ErrorCode.AWS_REQUEST_FAILED,
-    /** Endpoint discovery is not used by this package, so this is reported rather than acted on. */
-    InvalidEndpointException: error_code_1.ErrorCode.AWS_REQUEST_FAILED,
-    /** Its reasons are read first; this is the answer when they settle nothing. */
-    TransactionCanceledException: error_code_1.ErrorCode.AWS_REQUEST_FAILED,
-    /**
-     * Read by name, not from the caller's signal: a collaborator — a
-     * `vectorBackend`, `index.embeddings` — rejecting with an `AbortError` from
-     * its own timeout is `ABORTED` too, even when the caller's signal never fired.
-     */
-    AbortError: error_code_1.ErrorCode.ABORTED,
-};
-/** The codes a caller retries after a backoff. */
-const RETRYABLE_CODES = [
-    error_code_1.ErrorCode.THROTTLED,
-    error_code_1.ErrorCode.SERVICE_UNAVAILABLE,
-    error_code_1.ErrorCode.CONTENTION,
-];
-/**
- * The retry layer's default tokens: every name {@link AWS_ERROR_CODES} maps to
- * a retryable code, and the network codes. Derived rather than listed, so the
- * retry layer and the code a caller sees share one list of transient names.
- * They differ at two edges: the retry layer also retries on the SDK's
- * `$retryable` trait, which {@link classifyAwsError} does not read, and it
- * walks the cause chain matching `errno` and `syscall` too, where the
- * classifier reads one error's `name`, `code` and status.
- */
-exports.DEFAULT_RETRYABLE_ERRORS = [
-    ...Object.entries(exports.AWS_ERROR_CODES)
-        .filter(([, code]) => RETRYABLE_CODES.includes(code))
-        .map(([name]) => name),
-    ...exports.TRANSIENT_NETWORK_ERROR_CODES,
-];
-/** The table's code for `name`; `undefined` for any other value, never read through the prototype. */
-function declaredCodeOf(name) {
-    return typeof name === 'string' && Object.hasOwn(exports.AWS_ERROR_CODES, name)
-        ? exports.AWS_ERROR_CODES[name]
-        : undefined;
-}
-/** The response's HTTP status, when the error carries well-typed `$metadata`. */
-function statusOf(fields) {
-    const metadata = fields.$metadata;
-    return typeof metadata === 'object' &&
-        metadata !== null &&
-        typeof metadata.httpStatusCode === 'number'
-        ? metadata.httpStatusCode
-        : undefined;
-}
-/** Whether the error carries the SDK's `$metadata`, or a name the table knows or that ends in `Exception`. */
-function isAwsShaped(fields) {
-    if (typeof fields.$metadata === 'object' && fields.$metadata !== null)
-        return true;
-    const { name } = fields;
-    return (typeof name === 'string' && (declaredCodeOf(name) !== undefined || name.endsWith('Exception')));
-}
-/** The code of a cancelled transaction, read from its reasons. */
-function cancellationCode(error) {
-    if ((0, cancellation_1.conditionalCheckFailure)(error) !== undefined)
-        return error_code_1.ErrorCode.CONDITION_CONFLICT;
-    if ((0, cancellation_1.transientCancellation)(error) === true) {
-        return (0, cancellation_1.throttledCancellation)(error) ? error_code_1.ErrorCode.THROTTLED : error_code_1.ErrorCode.CONTENTION;
-    }
-    return exports.AWS_ERROR_CODES[TRANSACTION_CANCELLED];
-}
-/**
- * The code a failure that is not one of this library's own belongs to.
- *
- * Accepts: anything a `catch` can bind — an SDK error, a transport error, a
- * value from caller-supplied code, `null`, a string.
- *
- * Returns: a transaction cancellation's code from its reasons (a sole
- * `ConditionalCheckFailed` cause is `CONDITION_CONFLICT`; all-transient causes
- * are `THROTTLED` or `CONTENTION`); otherwise the table's code for the error's
- * own `name`; otherwise `SERVICE_UNAVAILABLE` for a transient network `code`;
- * otherwise by HTTP status — 412 `CONDITION_CONFLICT`, 429 `THROTTLED`,
- * 500/502/503/504 `SERVICE_UNAVAILABLE`; otherwise `AWS_REQUEST_FAILED` for an
- * AWS-shaped error and `UNEXPECTED_ERROR` for anything else. Only the error's
- * own fields are read, never its `cause`.
- *
- * Throws: nothing, for any value. It runs inside `catch` blocks.
- */
-function classifyAwsError(error) {
-    if (typeof error !== 'object' || error === null)
-        return error_code_1.ErrorCode.UNEXPECTED_ERROR;
-    const fields = error;
-    if (fields.name === TRANSACTION_CANCELLED)
-        return cancellationCode(error);
-    const declared = declaredCodeOf(fields.name);
-    if (declared !== undefined)
-        return declared;
-    if (typeof fields.code === 'string' && exports.TRANSIENT_NETWORK_ERROR_CODES.includes(fields.code)) {
-        return error_code_1.ErrorCode.SERVICE_UNAVAILABLE;
-    }
-    const status = statusOf(fields);
-    if (status === PRECONDITION_FAILED_STATUS)
-        return error_code_1.ErrorCode.CONDITION_CONFLICT;
-    if (status === 429)
-        return error_code_1.ErrorCode.THROTTLED;
-    if (status !== undefined && exports.TRANSIENT_HTTP_STATUSES.includes(status)) {
-        return error_code_1.ErrorCode.SERVICE_UNAVAILABLE;
-    }
-    return isAwsShaped(fields) ? error_code_1.ErrorCode.AWS_REQUEST_FAILED : error_code_1.ErrorCode.UNEXPECTED_ERROR;
-}
-/**
- * The fields an operator needs first, lifted off an AWS-shaped error.
- *
- * Accepts: anything a `catch` can bind.
- *
- * Returns: `awsErrorName`, `requestId` and `httpStatusCode`, each only when
- * present and well-typed, for an error carrying `$metadata` or a name the table
- * knows or that ends in `Exception`; `{}` for anything else — a bare network
- * failure included, since it may be a caller's own connection rather than AWS's.
- *
- * Throws: nothing, for any value.
- */
-function awsDiagnostics(error) {
-    if (typeof error !== 'object' || error === null)
-        return {};
-    const fields = error;
-    if (!isAwsShaped(fields))
-        return {};
-    const out = {};
-    if (typeof fields.name === 'string')
-        out.awsErrorName = fields.name;
-    const status = statusOf(fields);
-    if (status !== undefined)
-        out.httpStatusCode = status;
-    const requestId = fields.$metadata?.requestId;
-    if (typeof requestId === 'string')
-        out.requestId = requestId;
-    return out;
-}
-/**
- * Whether an S3 read failed because the object is gone.
- *
- * Accepts: anything a `catch` can bind.
- *
- * Returns: true for `NoSuchKey` only. `NOT_FOUND` also covers a missing
- * bucket, which is a configuration fault; reading it as a lost payload would
- * write off data that is still there.
- *
- * Throws: nothing, for any value.
- */
-function isMissingObject(error) {
-    return (typeof error === 'object' && error !== null && error.name === 'NoSuchKey');
-}
-/**
- * Whether reading a bucket's lifecycle configuration failed because the bucket
- * has none.
- *
- * Accepts: anything a `catch` can bind.
- *
- * Returns: true for `NoSuchLifecycleConfiguration` only. `NOT_FOUND` also
- * covers a missing bucket, table or object; reading one of those as "no rules
- * yet" would start a rule set for a bucket that is not there.
- *
- * Throws: nothing, for any value.
- */
-function isMissingLifecycleConfiguration(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        error.name === 'NoSuchLifecycleConfiguration');
-}