graphddb 0.2.2 → 0.2.4

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SelectableOf, f as PrimaryKeyOf, E as Executor, g as ExecutionPlanSpec, h as SegmentedKey, i as SelectBuilderSpec, R as RawCondition, j as TransactionSpec, k as Manifest, l as ExecutionPlan, m as ResolvedKey, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, n as CdcEmulatorOptions, o as ChangeHandler, p as Unsubscribe, F as FaultSpec, q as ConcurrentRecomputeRef, C as ChangeEvent, r as EventLog, s as ReplayOptions, t as ShardId, u as TransactionItemSpec, v as Param, w as ParamDescriptor, x as DefinitionMap, O as OperationDefinition, e as DDBModel, M as ModelStatic, y as WriteDefinitionOptions, z as PartialQueryKeyOf, A as StrictSelectSpec, G as EntityInput, H as UniqueQueryKeyOf, I as EntityRef, J as ConditionInput, Q as QueryModelContract, K as QueryMethodSpec, L as CommandModelContract, N as CommandMethodSpec, V as ContractSpec, X as QuerySpec, Y as CommandSpec, Z as ContextSpec, _ as OperationsDocument, $ as AnyOperationDefinition, a0 as BridgeBundle, a1 as ConditionSpec } from './types-SKxZQbQO.js';
-export { a2 as BatchDeleteRequest, a3 as BatchGetRequest, a4 as BatchGetResult, a5 as BatchPutRequest, a6 as BatchResult, a7 as BatchWriteRequest, a8 as CONTRACT_RANGE_FANOUT_CONCURRENCY, a9 as CdcMode, aa as ChangeBatch, ab as ChangeEventName, ac as ClockMode, ad as Column, ae as ColumnMap, af as CommandContractMethodSpec, ag as CommandInputShape, ah as CommandMethod, ai as CommandPlan, aj as CommandResolutionTarget, ak as CommandResultKind, al as CommandSelectShape, am as CompiledFragment, an as ComposeSpec, ao as CondSlot, ap as ConditionCheckInput, aq as Connection, ar as ContractCallSignature, as as ContractCardinality, at as ContractCommandParams, au as ContractCommandResult, av as ContractComposeNode, aw as ContractFromRef, ax as ContractInputArity, ay as ContractItem, az as ContractKeyFieldRef, aA as ContractKeyInput, aB as ContractKeyRef, aC as ContractKeySpec, aD as ContractKind, aE as ContractMethodOp, aF as ContractParamRef, aG as ContractQueryParams, aH as ContractResolution, aI as DeleteOptions, aJ as DeriveEffect, aK as DerivedEdgeWrite, aL as DerivedUpdate, aM as DescriptorBinding, aN as ENTITY_WRITES_MARKER, aO as EdgeEffect, aP as EffectPath, aQ as EmitEffect, aR as EntityWritesDefinition, aS as EntityWritesShape, aT as ExecutableCommandContract, aU as ExecutableQueryContract, aV as FilterInput, aW as FilterSpec, aX as FragmentInput, aY as GsiDefinitionMarker, aZ as GsiOptions, a_ as IdempotencyEffect, a$ as InProcessWriteDescriptor, b0 as InputArity, b1 as KeyDefinitionMarker, b2 as KeySegment, b3 as KeySlot, b4 as KeyStructure, b5 as KeyedResult, b6 as LIFECYCLE_CONTRACT_MARKER, b7 as LifecycleContract, b8 as LifecycleEffects, b9 as LiteralParam, ba as ManifestEntity, bb as ManifestField, bc as ManifestFieldType, bd as ManifestGsi, be as ManifestKey, bf as ManifestRelation, bg as ManifestTable, bh as ModelRef, bi as MutateMode, bj as MutateOptions, bk as MutateParallelResult, bl as MutateTransactionResult, bm as MutationBody, bn as MutationDescriptorMap, bo as MutationFragment, bp as MutationInputProxy, bq as MutationInputRef, br as MutationIntent, bs as NumberParam, bt as OperationKind, bu as OperationSpec, bv as ParallelOpResult, bw as ParamKind, bx as ParamSpec, by as ParamStructure, bz as PlannedCommandMethod, bA as PutOptions, bB as QueryContractMethodSpec, bC as QueryEnvelopeResult, bD as QueryKeyOf, bE as QueryMethod, bF as QueryResult, bG as RangeConditionSpec, bH as ReadEnvelope, bI as ReadOperationType, bJ as ReadRouteDescriptor, bK as ReadRouteOptions, bL as ReadRouteResult, bM as RecordedCompose, bN as RelationBuilder, bO as RelationSelect, bP as RelationSpec, bQ as RequiresEffect, bR as Resolution, bS as SPEC_VERSION, bT as SegmentSpec, bU as SelectBuilder, bV as SelectOf, bW as StartingPosition, bX as StreamViewType, bY as StringParam, bZ as TransactionContext, b_ as TransactionItemType, b$ as UniqueEffect, c0 as Updatable, c1 as UpdateOptions, c2 as WhenSpec, c3 as WriteDescriptor, c4 as WriteEnvelope, c5 as WriteLifecyclePhase, c6 as WriteOperationType, c7 as WriteRecorder, c8 as WriteResultProjection, c9 as attachModelClass, ca as buildDeleteInput, cb as buildPutInput, cc as buildUpdateInput, cd as compileFragment, ce as compileMutationPlan, cf as compileSingleFragmentPlan, cg as cond, ch as contractOfMethodSpec, ci as definePlan, cj as entityWrites, ck as executeBatchGet, cl as executeBatchWrite, cm as executeCommandMethod, cn as executeDelete, co as executeKeyedBatchGet, cp as executePut, cq as executeQueryMethod, cr as executeRangeFanout, cs as executeTransaction, ct as executeUpdate, cu as from, cv as getEntityWrites, cw as gsi, cx as isColumn, cy as isCommandModelContract, cz as isCommandPlan, cA as isContractComposeNode, cB as isContractFromRef, cC as isContractKeyFieldRef, cD as isContractKeyRef, cE as isContractParamRef, cF as isEntityWritesDefinition, cG as isKeySegment, cH as isLifecycleContract, cI as isMutationFragment, cJ as isMutationInputRef, cK as isParam, cL as isPlannedCommandMethod, cM as isQueryModelContract, cN as k, cO as key, cP as lifecyclePhaseForIntent, cQ as mintContractKeyFieldRef, cR as mintContractParamRef, cS as mutation, cT as param, cU as publicCommandModel, cV as publicQueryModel, cW as query, cX as resolveLifecycle, cY as wholeKeysSentinel } from './types-SKxZQbQO.js';
+import { S as SelectableOf, g as PrimaryKeyOf, E as Executor, h as RetryPolicy, i as ExecutionPlanSpec, j as SegmentedKey, k as SelectBuilderSpec, l as RawCondition, m as TransactionSpec, n as Manifest, o as RetryOverride, p as ExecutionPlan, q as ResolvedKey, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, r as CdcEmulatorOptions, s as ChangeHandler, t as Unsubscribe, F as FaultSpec, u as ConcurrentRecomputeRef, C as ChangeEvent, v as EventLog, w as ReplayOptions, x as ShardId, y as TransactionItemSpec, z as Param, A as ParamDescriptor, G as DefinitionMap, O as OperationDefinition, f as DDBModel, M as ModelStatic, H as WriteDefinitionOptions, I as PartialQueryKeyOf, J as StrictSelectSpec, K as EntityInput, L as UniqueQueryKeyOf, N as EntityRef, Q as ConditionInput, V as QueryModelContract, X as QueryMethodSpec, Y as CommandModelContract, Z as CommandMethodSpec, _ as ContractSpec, $ as QuerySpec, a0 as CommandSpec, a1 as ContextSpec, a2 as OperationsDocument, a3 as AnyOperationDefinition, a4 as BridgeBundle, a5 as ConditionSpec } from './types-BEeQ_nSd.js';
+export { a6 as BatchDeleteRequest, a7 as BatchGetRequest, a8 as BatchGetResult, a9 as BatchPutRequest, aa as BatchResult, ab as BatchWriteRequest, ac as CONTRACT_RANGE_FANOUT_CONCURRENCY, ad as CdcMode, ae as ChangeBatch, af as ChangeEventName, ag as ClockMode, ah as Column, ai as ColumnMap, aj as CommandContractMethodSpec, ak as CommandInputShape, al as CommandMethod, am as CommandPlan, an as CommandResolutionTarget, ao as CommandResultKind, ap as CommandSelectShape, aq as CompiledFragment, ar as ComposeSpec, as as CondSlot, at as ConditionCheckInput, au as Connection, av as ContractCallSignature, aw as ContractCardinality, ax as ContractCommandParams, ay as ContractCommandResult, az as ContractComposeNode, aA as ContractFromRef, aB as ContractInputArity, aC as ContractItem, aD as ContractKeyFieldRef, aE as ContractKeyInput, aF as ContractKeyRef, aG as ContractKeySpec, aH as ContractKind, aI as ContractMethodOp, aJ as ContractParamRef, aK as ContractQueryParams, aL as ContractResolution, aM as DEFAULT_MAX_ATTEMPTS, aN as DEFAULT_RETRY_POLICY, aO as DeleteOptions, aP as DeriveEffect, aQ as DerivedEdgeWrite, aR as DerivedUpdate, aS as DescriptorBinding, aT as ENTITY_WRITES_MARKER, aU as EdgeEffect, aV as EffectPath, aW as EmitEffect, aX as EntityWritesDefinition, aY as EntityWritesShape, aZ as ExecutableCommandContract, a_ as ExecutableQueryContract, a$ as FilterInput, b0 as FilterSpec, b1 as FragmentInput, b2 as GsiDefinitionMarker, b3 as GsiOptions, b4 as IdempotencyEffect, b5 as InProcessWriteDescriptor, b6 as InputArity, b7 as KeyDefinitionMarker, b8 as KeySegment, b9 as KeySlot, ba as KeyStructure, bb as KeyedResult, bc as LIFECYCLE_CONTRACT_MARKER, bd as LifecycleContract, be as LifecycleEffects, bf as LiteralParam, bg as ManifestEntity, bh as ManifestField, bi as ManifestFieldType, bj as ManifestGsi, bk as ManifestKey, bl as ManifestRelation, bm as ManifestTable, bn as ModelRef, bo as MutateMode, bp as MutateOptions, bq as MutateParallelResult, br as MutateTransactionResult, bs as MutationBody, bt as MutationDescriptorMap, bu as MutationFragment, bv as MutationInputProxy, bw as MutationInputRef, bx as MutationIntent, by as NumberParam, bz as OperationKind, bA as OperationSpec, bB as ParallelOpResult, bC as ParamKind, bD as ParamSpec, bE as ParamStructure, bF as PlannedCommandMethod, bG as PutOptions, bH as QueryContractMethodSpec, bI as QueryEnvelopeResult, bJ as QueryKeyOf, bK as QueryMethod, bL as QueryResult, bM as RangeConditionSpec, bN as ReadEnvelope, bO as ReadOperationType, bP as ReadRouteDescriptor, bQ as ReadRouteOptions, bR as ReadRouteResult, bS as RecordedCompose, bT as RelationBuilder, bU as RelationSelect, bV as RelationSpec, bW as RequiresEffect, bX as Resolution, bY as RetryInfo, bZ as RetryOperationKind, b_ as SPEC_VERSION, b$ as SegmentSpec, c0 as SelectBuilder, c1 as SelectOf, c2 as StartingPosition, c3 as StreamViewType, c4 as StringParam, c5 as TransactionContext, c6 as TransactionItemType, c7 as UniqueEffect, c8 as Updatable, c9 as UpdateOptions, ca as WhenSpec, cb as WriteDescriptor, cc as WriteEnvelope, cd as WriteLifecyclePhase, ce as WriteOperationType, cf as WriteRecorder, cg as WriteResultProjection, ch as attachModelClass, ci as buildDeleteInput, cj as buildPutInput, ck as buildUpdateInput, cl as compileFragment, cm as compileMutationPlan, cn as compileSingleFragmentPlan, co as cond, cp as contractOfMethodSpec, cq as definePlan, cr as entityWrites, cs as executeBatchGet, ct as executeBatchWrite, cu as executeCommandMethod, cv as executeDelete, cw as executeKeyedBatchGet, cx as executePut, cy as executeQueryMethod, cz as executeRangeFanout, cA as executeTransaction, cB as executeUpdate, cC as from, cD as getEntityWrites, cE as gsi, cF as isColumn, cG as isCommandModelContract, cH as isCommandPlan, cI as isContractComposeNode, cJ as isContractFromRef, cK as isContractKeyFieldRef, cL as isContractKeyRef, cM as isContractParamRef, cN as isEntityWritesDefinition, cO as isKeySegment, cP as isLifecycleContract, cQ as isMutationFragment, cR as isMutationInputRef, cS as isParam, cT as isPlannedCommandMethod, cU as isQueryModelContract, cV as isRetryableError, cW as isRetryableTransactionCancellation, cX as k, cY as key, cZ as lifecyclePhaseForIntent, c_ as mintContractKeyFieldRef, c$ as mintContractParamRef, d0 as mutation, d1 as param, d2 as publicCommandModel, d3 as publicQueryModel, d4 as query, d5 as resolveLifecycle, d6 as wholeKeysSentinel } from './types-BEeQ_nSd.js';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 
@@ -92,6 +92,13 @@ declare class ClientManager {
      */
     private static executor;
     private static defaultExecutor;
+    /**
+     * The globally-configured single-op retry policy (issue #111). `null` ⇒ the
+     * always-on built-in {@link DEFAULT_RETRY_POLICY} applies (retry is enabled out
+     * of the box). Set via {@link DDBModel.setRetryPolicy} / {@link setRetryPolicy};
+     * read at call time by the default {@link RetryingExecutor}.
+     */
+    private static retryPolicy;
     static setClient(client: DynamoDBClient): void;
     static getClient(): DynamoDBClient;
     static getDocumentClient(): Promise<DynamoDBDocumentClient>;
@@ -105,10 +112,23 @@ declare class ClientManager {
      * executor module graph.
      */
     static getExecutor(): Executor;
-    /** Inject a custom executor (test adapter / memory engine). */
+    /**
+     * Inject a custom executor (test adapter / memory engine). It is used AS-IS —
+     * not wrapped in a {@link RetryingExecutor} — so the in-memory adapter (which
+     * never throttles) bypasses the retry layer entirely (issue #111).
+     */
     static setExecutor(executor: Executor): void;
-    /** Restore the default {@link DynamoExecutor}. */
+    /** Restore the default {@link RetryingExecutor}-wrapped {@link DynamoExecutor}. */
     static resetExecutor(): void;
+    /**
+     * Configure the global single-op retry policy (issue #111). Mirrors
+     * {@link setClient} / {@link setTableMapping}: a process-wide setting the default
+     * {@link RetryingExecutor} reads. `null` restores the always-on built-in default.
+     * A per-call `retry?:` override on an operation option bag takes precedence.
+     */
+    static setRetryPolicy(policy: RetryPolicy | null): void;
+    /** The globally-configured retry policy, or `null` for the built-in default. */
+    static getRetryPolicy(): RetryPolicy | null;
     /** @internal — for testing only */
     static reset(): void;
 }
@@ -503,6 +523,13 @@ declare function executeDeclarativeTransaction(spec: TransactionSpec, manifest:
 interface QueryOptions {
     consistentRead?: boolean;
     maxDepth?: number;
+    /**
+     * Per-call throttle / transient-error retry override (issue #111), applied to the
+     * parent read AND to every relation-fan-out send under it. A {@link RetryPolicy}
+     * replaces the global policy for this call; `false` disables retry. Omit to use
+     * the configured (or built-in default) policy.
+     */
+    retry?: RetryOverride;
     /**
      * When `true`, the returned item carries its resolved base-table key as a
      * non-enumerable Symbol property so it can be passed back to `update()`
@@ -547,6 +574,12 @@ interface ListInput {
      * query.
      */
     updatable?: boolean;
+    /**
+     * Per-call throttle / transient-error retry override (issue #111). A
+     * {@link RetryPolicy} replaces the global policy for this read; `false` disables
+     * retry. Omit to use the configured (or built-in default) policy.
+     */
+    retry?: RetryOverride;
 }
 /**
  * Public list result returned by `DDBModel.list()`. Contains exactly the
@@ -618,10 +651,12 @@ declare function plan(metadata: EntityMetadata, input: PlanInput): ExecutionPlan
  *
  * This is the read entry point the planner-driven paths (`query` / `list`) call.
  * It delegates to `ClientManager.getExecutor()`, which is the default
- * {@link import('./dynamo-executor.js').DynamoExecutor} unless a test has
- * injected a `MemoryExecutor` via `ClientManager.setExecutor()`.
+ * {@link import('./retrying-executor.js').RetryingExecutor}-wrapped
+ * {@link import('./dynamo-executor.js').DynamoExecutor} unless a test has injected
+ * a `MemoryExecutor` via `ClientManager.setExecutor()`. The optional
+ * {@link ReadExecOptions} carries a per-call retry override (issue #111).
  */
-declare function execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
+declare function execute(operation: DynamoDBOperation, options?: ReadExecOptions): Promise<ExecutorResult>;
 
 /**
  * The default {@link Executor}: a thin, behavior-preserving move of GraphDDB's
@@ -630,15 +665,65 @@ declare function execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
  * refactor and sends it through `ClientManager.getDocumentClient()`, so the
  * command shapes (and therefore every existing mock-based / integration test)
  * are unchanged.
+ *
+ * The optional per-call options (`ReadExecOptions` / `BatchExecOptions`) carry a
+ * retry override (issue #111) that is meaningful ONLY to {@link RetryingExecutor};
+ * here they are accepted to satisfy the {@link Executor} interface and otherwise
+ * ignored (this executor performs no app-level error retry of its own).
  */
 declare class DynamoExecutor implements Executor {
-    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
-    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
+    execute(operation: DynamoDBOperation, _options?: ReadExecOptions): Promise<ExecutorResult>;
+    batchGet(input: BatchGetExecInput, _options?: ReadExecOptions): Promise<ExecutorResult>;
     put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
     update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
     delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
-    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
-    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
+    batchWrite(tableName: string, items: BatchWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
+    transactWrite(items: TransactWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
+}
+
+/**
+ * {@link RetryingExecutor} — the single-op throttle / transient-error retry layer
+ * (issue #111). It DECORATES an inner {@link Executor} (the default
+ * {@link DynamoExecutor}), wrapping every single-op send — `execute` (Get/Query),
+ * `batchGet` (relation fan-out + planner reads), `put` / `update` / `delete`, and
+ * `transactWrite` — in {@link runWithRetry} so a throttle / transient error is
+ * retried with exponential backoff + jitter under a bounded attempt cap.
+ *
+ * This is the (B) ERROR-retry layer; the (A) partial-batch retry
+ * (`UnprocessedKeys` / `UnprocessedItems`) lives inside `batchGet` / `batchWrite`
+ * and is a SEPARATE concern (see `retry-policy.ts` header). The two share the
+ * backoff function but never merge:
+ *  - `batchGet` here gets an OUTER error-retry wrap (the inner BatchGet still does
+ *    its own UnprocessedKeys retry; the outer wrap catches a hard throttle REJECT
+ *    of the whole send).
+ *  - `batchWrite` is the in-flight bulk path that already owns UnprocessedItems
+ *    retry per chunk; it is passed through UNWRAPPED here to avoid double-counting
+ *    a throttle as both an unprocessed-item retry and an error retry. (Its chunks
+ *    already back off on the shared ramp.)
+ *
+ * The policy precedence per call: an explicit per-call override (`retry:` on the
+ * option bag) wins; otherwise the globally-configured policy
+ * (`DDBModel.setRetryPolicy`); otherwise the always-on {@link DEFAULT_RETRY_POLICY}.
+ * `retry: false`, or a resolved `maxAttempts <= 1`, disables retry for that call.
+ */
+
+declare class RetryingExecutor implements Executor {
+    private readonly inner;
+    private readonly getGlobalPolicy;
+    /**
+     * @param inner the wrapped executor (the real {@link DynamoExecutor}).
+     * @param getGlobalPolicy reads the globally-configured policy (or `null` for the
+     *   built-in default) at CALL time, so a `DDBModel.setRetryPolicy(...)` after the
+     *   executor is constructed still takes effect.
+     */
+    constructor(inner: Executor, getGlobalPolicy: () => RetryPolicy | null);
+    execute(operation: DynamoDBOperation, options?: ReadExecOptions): Promise<ExecutorResult>;
+    batchGet(input: BatchGetExecInput, options?: ReadExecOptions): Promise<ExecutorResult>;
+    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
+    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
+    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
+    batchWrite(tableName: string, items: BatchWriteExecItem[], options?: BatchExecOptions): Promise<void>;
+    transactWrite(items: TransactWriteExecItem[], options?: BatchExecOptions): Promise<void>;
 }
 
 /**
@@ -923,6 +1008,14 @@ interface RelationTraversalOptions {
      * non-enumerable Symbol property so it can be passed back to `update()`.
      */
     updatable?: boolean;
+    /**
+     * Per-call throttle / transient-error retry override (issue #111), threaded from
+     * the read's entry point into every relation-fan-out send (the `BatchGet` for
+     * `belongsTo` / `hasOne`, the `Query` for `hasMany`). A {@link RetryPolicy}
+     * replaces the global policy; `false` disables retry. Threaded unchanged through
+     * every recursion level.
+     */
+    retry?: RetryOverride;
     /**
      * The **declared execution plan** (issue #70c) the traversal HONORS to decide
      * which sibling relations are independent (a concurrency-eligible stage) and the
@@ -2033,4 +2126,4 @@ declare function assertBundleSerializable(bundle: BridgeBundle): void;
  */
 declare function buildBridgeBundle(queries?: DefinitionMap, commands?: DefinitionMap, registry?: typeof MetadataRegistry, transactions?: Record<string, TransactionDefinition>, contractInputs?: ContractInputs): BridgeBundle;
 
-export { type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, DDBModel, DefinitionMap, DeleteInput, DynamoDBOperation, DynamoExecutor, type DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, type EmbeddedMetadata, type EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, type FieldMetadata, type FieldOptions, type FilterExpressionResult, type GsiDefinition, type KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, Manifest, MetadataRegistry, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, ResolvedKey, SegmentedKey, SelectableOf, ShardId, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, createCdcEmulator, createDefaultLinter, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, map, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when };
+export { type AnyModelContract, AnyOperationDefinition, BATCH_GET_MAX_KEYS, BATCH_WRITE_MAX_ITEMS, BatchExecOptions, BatchGetExecInput, BatchWriteExecItem, BridgeBundle, type BuiltContracts, CdcEmulator, CdcEmulatorOptions, ChangeEvent, ChangeHandler, ClientManager, type CollectParams, CommandMethodSpec, CommandModelContract, CommandSpec, ConcurrentRecomputeRef, type ConditionExpressionResult, ConditionInput, ConditionSpec, type ContextOwnership, type ContextOwnershipMap, ContextSpec, type ContractBoundaryViolation, type ContractInputs, type ContractMap, type ContractN1Violation, ContractSpec, DDBModel, DefinitionMap, DeleteInput, DynamoDBOperation, DynamoExecutor, type DynamoType, EDGE_WRITES_MARKER, type EdgeLifecycle, type EdgeWriteDeclaration, type EdgeWriteRecorder, type EdgeWritesDefinition, type EmbeddedMetadata, type EntityMetadata, EntityRef, EventLog, ExecutionPlan, Executor, ExecutorResult, type ExplainInput, FaultSpec, type FieldMetadata, type FieldOptions, type FilterExpressionResult, type GsiDefinition, type KeyDefinition, type LintResult, type LintRule, Linter, type ListInput, type ListOptions, MAX_TRANSACT_ITEMS, Manifest, MetadataRegistry, type ModelOptions, ModelStatic, OLD_VALUE_NAMESPACE, OperationDefinition, OperationsDocument, Param, ParamDescriptor, type Parameterize, PartialQueryKeyOf, type PerKeyCursorEnvelope, type PlanInput, PrimaryKeyOf, type ProjectionResult, PutInput, QueryMethodSpec, QueryModelContract, type QueryOptions$1 as QueryOptions, QuerySpec, RawCondition, ReadExecOptions, type RelationLimitOptions, type RelationMetadata, type RelationOptions, type RelationTraversalOptions, ReplayOptions, ResolvedKey, RetryOverride, RetryPolicy, RetryingExecutor, SegmentedKey, SelectableOf, ShardId, TableMapping, TransactWriteExecItem, type TransactionDefinition, TransactionItemSpec, type TransactionParamShape, type TransactionRef, TransactionSpec, type TxConditionCheckOptions, type TxForEachInstruction, type TxForEachOptions, type TxInstruction, type TxRecorder, type TxWriteInstruction, type TxWriteOptions, UniqueQueryKeyOf, type UpdateExpressionResult, UpdateInput, type WhenComparison, WriteDefinitionOptions, WriteExecOptions, WriteResult, assertBundleSerializable, assertContractBoundaries, assertContractN1Safe, assertJsonSerializable, assertSupportedCondition, belongsTo, binary, boolean, buildBridgeBundle, buildConditionExpression, buildContexts, buildContracts, buildManifest, buildOperations, buildProjection, buildQuerySpec, buildTransactionSpec, buildTransactions, buildUpdateExpression, collectContractBoundaryViolations, collectContractN1Violations, compileFilterExpression, createCdcEmulator, createDefaultLinter, datetime, decodeCursor, decodePerKeyCursor, defineCommands, defineDelete, defineList, definePut, defineQueries, defineQuery, defineTransaction, defineTransactions, defineUpdate, deriveEdgeWriteItems, deriveEdgeWriteItemsFor, deriveModelEdgeWriteItems, derivePrefix, detectRelationFields, edgeWrites, embedded, encodeCursor, encodePerKeyCursor, evaluateFilter, execute, executeDeclarativeTransaction, executeExplain, executeList, executeQuery, expandTransaction, field, getEdgeWrites, getImplicitKeyFields, gsiAmbiguityRule, hasMany, hasOne, hydrate, isEdgeWritesDefinition, isSelectBuilder, isTransactionRef, list, literal, map, missingGsiRule, model, noScanRule, number, numberSet, plan, queryBoundaryRule, relationDepthRule, requireLimitRule, resolveKey, resolveRelations, serializeContractKey, serializeFieldValue, string, stringSet, validateDepth, validateGsiAmbiguity, when };

package/dist/index.js

@@ -86,19 +86,22 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-CXIAECRS.js";
+} from "./chunk-IQEOJVHI.js";
 import {
   CdcEmulator,
   createCdcEmulator
-} from "./chunk-27XBTYVK.js";
+} from "./chunk-LNESVUTO.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
   ClientManager,
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_RETRY_POLICY,
   DynamoExecutor,
   Linter,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
+  RetryingExecutor,
   TableMapping,
   TransactionContext,
   attachModelClass,
@@ -123,6 +126,8 @@ import {
   isKeySegment,
   isParam,
   isRawCondition,
+  isRetryableError,
+  isRetryableTransactionCancellation,
   k,
   key,
   missingGsiRule,
@@ -134,7 +139,7 @@ import {
   resolveKey,
   resolveModelClass,
   serializeFieldValue
-} from "./chunk-3MI43FHU.js";
+} from "./chunk-GCPEUPAA.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -1044,6 +1049,8 @@ export {
   CdcEmulator,
   ClientManager,
   DDBModel,
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_RETRY_POLICY,
   DynamoExecutor,
   EDGE_WRITES_MARKER,
   ENTITY_WRITES_MARKER,
@@ -1052,6 +1059,7 @@ export {
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
   OLD_VALUE_NAMESPACE,
+  RetryingExecutor,
   SPEC_VERSION,
   TableMapping,
   TransactionContext,
@@ -1155,6 +1163,8 @@ export {
   isParam,
   isPlannedCommandMethod,
   isQueryModelContract,
+  isRetryableError,
+  isRetryableTransactionCancellation,
   isSelectBuilder,
   isTransactionRef,
   k,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { E as Executor, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, M as ModelStatic, e as DDBModel, C as ChangeEvent } from '../types-SKxZQbQO.js';
+import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-BEeQ_nSd.js';
 import '@aws-sdk/client-dynamodb';
 
 /**
@@ -71,15 +71,15 @@ declare class MemoryStore {
 declare class MemoryExecutor implements Executor {
     private readonly store;
     constructor(store: MemoryStore);
-    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
-    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
+    execute(operation: DynamoDBOperation, _options?: ReadExecOptions): Promise<ExecutorResult>;
+    batchGet(input: BatchGetExecInput, _options?: ReadExecOptions): Promise<ExecutorResult>;
     private getItem;
     private query;
     put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
     update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
     delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
-    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
-    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
+    batchWrite(tableName: string, items: BatchWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
+    transactWrite(items: TransactWriteExecItem[], _options?: BatchExecOptions): Promise<void>;
     private restoreTable;
     /**
      * Evaluate a transaction `ConditionCheck` (issue #81): read the keyed item and

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-27XBTYVK.js";
+} from "../chunk-LNESVUTO.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-3MI43FHU.js";
+} from "../chunk-GCPEUPAA.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {
@@ -543,7 +543,10 @@ var MemoryExecutor = class {
   }
   store;
   // ── reads ────────────────────────────────────────────────────────────────
-  async execute(operation) {
+  // The optional per-call options (`ReadExecOptions` / `BatchExecOptions`) carry a
+  // retry override (issue #111) that only `RetryingExecutor` acts on; the in-memory
+  // adapter never throttles, so it accepts and ignores them.
+  async execute(operation, _options) {
     if (operation.type === "GetItem") {
       return this.getItem(operation);
     }
@@ -552,7 +555,7 @@ var MemoryExecutor = class {
     }
     return this.query(operation);
   }
-  async batchGet(input) {
+  async batchGet(input, _options) {
     const items = [];
     for (const key of input.keys) {
       const found = this.store.getItem(
@@ -673,7 +676,7 @@ var MemoryExecutor = class {
     this.store.deleteItem(input.TableName, pk, sk);
     return options?.returnOldImage && prior ? { oldItem: prior } : {};
   }
-  async batchWrite(tableName, items) {
+  async batchWrite(tableName, items, _options) {
     for (const item of items) {
       if (item.type === "put") {
         this.store.putItem(tableName, item.item);
@@ -686,7 +689,7 @@ var MemoryExecutor = class {
       }
     }
   }
-  async transactWrite(items) {
+  async transactWrite(items, _options) {
     if (items.length === 0) return;
     const touchedTables = /* @__PURE__ */ new Set();
     for (const it of items) {