effect-dynamodb 1.35.0 → 1.36.0

package/dist/Entity.js

@@ -17,10 +17,10 @@ import * as KeyComposer from "@effect-dynamodb/schema/KeyComposer.js";
 import { normalizeGsiConfig } from "@effect-dynamodb/schema/KeyComposer.js";
 import { deriveSourceText } from "@effect-dynamodb/schema/VectorIndex.js";
 import { Cause, Context, Crypto, Data, DateTime, Effect, Equal, Option, Schema, Stream, } from "effect";
-import { DynamoClient } from "./DynamoClient.js";
 import { attributeValueEquals } from "./internal/AttributeValueEquals.js";
 import { isBoundOp, makeBoundAppend, makeBoundDelete, makeBoundGet, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
 import { BoundQueryImpl, entityNaming, } from "./internal/BoundQuery.js";
+import * as Capacity from "./internal/Capacity.js";
 import { compileExpr, createConditionOps, emptyPartProblem, isExpr, nonEmptyCondition, parseShorthand, parseSimpleShorthand, toExpr, } from "./internal/Expr.js";
 import { countOperators, expressionFits } from "./internal/ExpressionLimits.js";
 import { BASE_DELAY_MS, MAX_RETRIES } from "./internal/Hydrate.js";
@@ -199,6 +199,11 @@ const compileCondition = (cond, resolveDbNameFn) => {
     return compileExpr(expr, resolveDbNameFn);
 };
 /** Attempts a guarded put makes before it reports a lost race (#133). */
+/** Name a get- or delete-shaped op for consumed-capacity reports (its builder carries it). */
+const namedOp = (op, name) => {
+    Capacity.nameBuilder(op._builder, name);
+    return op;
+};
 const GUARDED_PUT_ATTEMPTS = 3;
 /**
  * @internal A delete's item was deleted between its read and its write, with
@@ -1458,7 +1463,7 @@ const makeImpl = (config, precomputedData) => {
         const needsFullSource = needing.some(([logicalName, definition]) => withVectors?.[logicalName] === undefined &&
             definition.sourceFields.some((field) => !(field in merged)));
         if (needsFullSource) {
-            const client = yield* DynamoClient;
+            const client = yield* Capacity.client;
             const current = yield* client.getItem({ TableName: tableName, Key: marshalledKey });
             if (current.Item) {
                 const currentDomain = fromAttributeMap(current.Item);
@@ -1766,7 +1771,7 @@ const makeImpl = (config, precomputedData) => {
      * update still WAS applied: {@link UpdateAppliedButUnreadable}.
      */
     const readRetainPostImage = (tableName, marshalledKey, replaced, ourVersion, ourIncarnation, derivedSets, derivedRemoves, ttlAttrName, encodedKey) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const ours = (item) => item !== undefined &&
             (incarnationAttr === undefined ||
                 attributeValueEquals(item[incarnationAttr], ourIncarnation));
@@ -1962,7 +1967,7 @@ const makeImpl = (config, precomputedData) => {
      * a digit, a segment with a composite name — so a key range bounds them.
      */
     const legacyHistory = (args) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const primary = config.indexes.primary;
         const prefix = args.kind === "version"
             ? DynamoSchema.composeVersionKeyPrefix(schema, entityType)
@@ -2016,7 +2021,7 @@ const makeImpl = (config, precomputedData) => {
      * without a segment, whichever is later (its own on a tie).
      */
     const latestTombstone = (tableName, pk, liveSk) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const primary = config.indexes.primary;
         const own = (yield* client.query({
             TableName: tableName,
@@ -2144,7 +2149,7 @@ const makeImpl = (config, precomputedData) => {
     const ownedSentinels = (tableName, candidates, owner) => Effect.gen(function* () {
         if (candidates.length === 0)
             return [];
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const pkField = config.indexes.primary.pk.field;
         const skField = config.indexes.primary.sk.field;
         const ownerPk = toAttributeValue(owner.pk);
@@ -2208,7 +2213,7 @@ const makeImpl = (config, precomputedData) => {
      * overwriting its earlier incarnation's history.
      */
     const highestRetainedVersion = (tableName, pk, liveSk) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const primary = config.indexes.primary;
         const { Items } = yield* client.query({
             TableName: tableName,
@@ -2260,7 +2265,7 @@ const makeImpl = (config, precomputedData) => {
      * is final.
      */
     const planPut = (args) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const pkField = config.indexes.primary.pk.field;
         const skField = config.indexes.primary.sk.field;
         const item = { ...args.item };
@@ -2470,7 +2475,7 @@ const makeImpl = (config, precomputedData) => {
      * concurrency error.
      */
     const runGuardedPut = (args) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         let lost;
         for (let attempt = 0; attempt < GUARDED_PUT_ATTEMPTS; attempt++) {
             const plan = yield* planPut(args);
@@ -2601,7 +2606,7 @@ const makeImpl = (config, precomputedData) => {
     const executeCascade = (cascadeConfig, sourceDomainData, sourceIdValue) => Effect.gen(function* () {
         const { targets, filter, mode } = cascadeConfig;
         const sourceEntityType = entityType;
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         if (!sourceIdentifierField)
             return undefined;
         const allUpdateOps = [];
@@ -2788,7 +2793,7 @@ const makeImpl = (config, precomputedData) => {
     // dereference `self` when called by users, after make() has returned
     let self;
     const put = (input) => new EntityPutImpl((mode, opts) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
@@ -2974,7 +2979,7 @@ const makeImpl = (config, precomputedData) => {
     // get operation
     // ---------------------------------------------------------------------------
     const get = (key) => new EntityGetImpl((mode, opts) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const { name: tableName } = yield* tableTag;
         // Caller key: Type side in, ENCODED out (see `encodeKey`).
         const encodedKey = yield* encodeKey(key, "get.decode");
@@ -3091,7 +3096,7 @@ const makeImpl = (config, precomputedData) => {
         // The caller's condition, ANDed onto `patch`'s exists guard — a guard
         // no `.condition()` can replace (#133).
         const userCond = withGuard(uState.patch ? { attributeExists: [config.indexes.primary.pk.field] } : undefined, uState.condition);
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
@@ -4574,7 +4579,7 @@ const makeImpl = (config, precomputedData) => {
         // so the row is read here, and a missing row is answered to the op as
         // its write would have been answered: it takes the same path.
         if (!recorded.readOwnRow && items.length > 0) {
-            const client = yield* DynamoClient;
+            const client = yield* Capacity.client;
             const { name: tableName } = yield* tableTag;
             const read = yield* client.getItem({
                 TableName: tableName,
@@ -4760,7 +4765,7 @@ const makeImpl = (config, precomputedData) => {
     // delete operation
     // ---------------------------------------------------------------------------
     const del = (key) => new EntityDeleteImpl((opts) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
@@ -5151,7 +5156,7 @@ const makeImpl = (config, precomputedData) => {
      * itself fails the upsert, as it fails an update.
      */
     const guardedUpsert = (input, mode, opts) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const { name: tableName } = yield* tableTag;
         yield* checkWithVectorNames(opts.withVectors, "upsert");
         // Required fields are required whether or not the item exists.
@@ -5252,7 +5257,7 @@ const makeImpl = (config, precomputedData) => {
             omitsIndexedDefault(input)) {
             return yield* guardedUpsert(input, mode, opts);
         }
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const { name: tableName } = yield* tableTag;
         // Clock-backed time source for createdAt/updatedAt SET clauses.
         const now = yield* DateTime.now;
@@ -5561,7 +5566,7 @@ const makeImpl = (config, precomputedData) => {
     //   `ValidationError("append.followUp")`. Undetected on skipFollowUp path.
     // ---------------------------------------------------------------------------
     const timeSeriesConfig = config.timeSeries;
-    const append = (input, givenCondition, skipFollowUp = false, removeAttrs) => Effect.gen(function* () {
+    const appendCore = (input, givenCondition, skipFollowUp = false, removeAttrs) => Effect.gen(function* () {
         if (!timeSeriesConfig) {
             return yield* new ValidationError({
                 entityType,
@@ -5590,7 +5595,7 @@ const makeImpl = (config, precomputedData) => {
                 cause: `append: ${emptyPart} Nothing was sent.`,
             });
         }
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
@@ -5962,6 +5967,8 @@ const makeImpl = (config, precomputedData) => {
     // ---------------------------------------------------------------------------
     // history operation — BoundQuery for event items only
     // ---------------------------------------------------------------------------
+    // The public `append`: the core as the named operation (consumed capacity, #174).
+    const append = (input, givenCondition, skipFollowUp = false, removeAttrs) => Capacity.operation("Entity.append", { target: entityType }, appendCore(input, givenCondition, skipFollowUp, removeAttrs));
     const history = (key) => {
         if (!timeSeriesConfig) {
             throw new Error(`[EDD-9010] Entity "${entityType}": .history() requires timeSeries config on the entity.`);
@@ -6061,7 +6068,7 @@ const makeImpl = (config, precomputedData) => {
     // getVersion operation
     // ---------------------------------------------------------------------------
     const getVersion = (key, versionNumber) => new EntityGetImpl((mode, opts) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const { name: tableName } = yield* tableTag;
         // Caller key: Type side in, ENCODED out (see `encodeKey`).
         const encodedKey = yield* encodeKey(key, "getVersion.decode");
@@ -6113,7 +6120,7 @@ const makeImpl = (config, precomputedData) => {
                 const legacy = yield* legacyHistory({ tableName, pk: pkValue, liveSk, kind: "version" });
                 if (legacy.length === 0)
                     return {};
-                const client = yield* DynamoClient;
+                const client = yield* Capacity.client;
                 const own = new Set();
                 let start;
                 do {
@@ -6244,7 +6251,7 @@ const makeImpl = (config, precomputedData) => {
     // restore operation
     // ---------------------------------------------------------------------------
     const restore = (key) => new EntityGetImpl((mode, _opts) => Effect.gen(function* () {
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const tc = yield* tableTag;
         const tableName = tc.name;
         const ttlAttrName = resolveTtlAttributeName(tc);
@@ -6446,7 +6453,7 @@ const makeImpl = (config, precomputedData) => {
                     "delete(key).condition(...) instead.",
             });
         }
-        const client = yield* DynamoClient;
+        const client = yield* Capacity.client;
         const { name: tableName } = yield* tableTag;
         // Caller key: Type side in, ENCODED out (see `encodeKey`).
         const encodedKey = yield* encodeKey(key, "purge.decode");
@@ -6743,7 +6750,7 @@ const makeImpl = (config, precomputedData) => {
         _liveRows: liveRows,
         _attachPrototype: attachPrototype,
         _overTombstone: (tableName, item) => Effect.gen(function* () {
-            const client = yield* DynamoClient;
+            const client = yield* Capacity.client;
             return yield* overTombstone(self, client, tableName, item);
         }),
         _configure: (injectedSchema, injectedTableTag) => {
@@ -6776,11 +6783,16 @@ const makeImpl = (config, precomputedData) => {
         deleteIfExists,
         upsert,
         scan,
-        getVersion,
+        // Lifecycle ops reuse the get / delete carriers; their builders carry the
+        // operation name consumed-capacity reports use (#174).
+        getVersion: (key, versionNumber) => namedOp(getVersion(key, versionNumber), "Entity.getVersion"),
         versions,
-        restore,
-        purge,
-        deleted: { get: deletedGet, list: deletedList },
+        restore: (key) => namedOp(restore(key), "Entity.restore"),
+        purge: (key) => namedOp(purge(key), "Entity.purge"),
+        deleted: {
+            get: (key) => namedOp(deletedGet(key), "Entity.deleted.get"),
+            list: deletedList,
+        },
         append,
         history,
         set,
@@ -6821,7 +6833,8 @@ export const bind = (entity) => Effect.gen(function* () {
     // Crypto-requiring entity ops typecheck. A platform override supplied via
     // `DynamoClient.make({ crypto })` is already in `baseCtx` and is respected
     // (we only fill the default when absent). See `DESIGN.md`.
-    const baseCtx = yield* Effect.context();
+    // Detached: no current operation or parent span is pinned for later calls (#174).
+    const baseCtx = Capacity.detachContext(yield* Effect.context());
     const ctx = Option.isSome(Context.getOption(baseCtx, Crypto.Crypto))
         ? baseCtx
         : Context.add(baseCtx, Crypto.Crypto, makeDefaultCrypto());
@@ -6849,12 +6862,13 @@ export const bind = (entity) => Effect.gen(function* () {
     // pre-resolved provide. Used by `versions` and `deleted.list` accessors so consumers
     // get the same fluent .collect() / .fetch() / .paginate() / .reverse() / .limit() /
     // .filter() ergonomics they get from index accessors and `.scan()`.
-    const wrapAsBoundQuery = (q) => {
+    const wrapAsBoundQuery = (q, operation) => {
         const bqConfig = {
             pathBuilder: createPathBuilder(),
             conditionOps: createConditionOps(),
             provide,
             ...entityNaming(entity._resolveDbName),
+            operation: { name: operation, target: entity.entityType },
         };
         return new BoundQueryImpl(q, bqConfig);
     };
@@ -6880,10 +6894,10 @@ export const bind = (entity) => Effect.gen(function* () {
         const primary = entity.indexes.primary;
         const boundEntityVersion = entity._entityVersion;
         const concurrency = options?.concurrency ?? 4;
-        return provide(Effect.gen(function* () {
+        return provide(Capacity.operation("Entity.reembed", { target: entity.entityType }, Effect.gen(function* () {
             if (vectorDefs.length === 0)
                 return 0;
-            const client = yield* DynamoClient;
+            const client = yield* Capacity.client;
             const { name: tableName } = yield* entity._tableTag;
             const reembedItem = (marshalled) => Effect.gen(function* () {
                 const raw = fromAttributeMap(marshalled);
@@ -6982,7 +6996,7 @@ export const bind = (entity) => Effect.gen(function* () {
                 exclusiveStartKey = page.LastEvaluatedKey;
             } while (exclusiveStartKey !== undefined);
             return updated;
-        }));
+        })));
     };
     return {
         // CRUD — fluent bound builders (yieldable, no .run() terminal)
@@ -6996,13 +7010,13 @@ export const bind = (entity) => Effect.gen(function* () {
         patch: (key) => makeBoundUpdate(entity.patch(key), boundCrudConfig),
         deleteIfExists: (key) => makeBoundDelete(entity.deleteIfExists(key), boundCrudConfig),
         // Lifecycle
-        getVersion: (key, version) => provide(entity.getVersion(key, version)._run("record")),
-        versions: (key) => wrapAsBoundQuery(entity.versions(key)),
-        restore: (key) => provide(entity.restore(key)._run("record")),
+        getVersion: (key, version) => provide(entity.getVersion(key, version)._exec("record")),
+        versions: (key) => wrapAsBoundQuery(entity.versions(key), "Entity.versions"),
+        restore: (key) => provide(entity.restore(key)._exec("record")),
         purge: (key) => provide(entity.purge(key).asEffect()),
         deleted: {
-            get: (key) => provide(entity.deleted.get(key)._run("record")),
-            list: (key) => wrapAsBoundQuery(entity.deleted.list(key)),
+            get: (key) => provide(entity.deleted.get(key)._exec("record")),
+            list: (key) => wrapAsBoundQuery(entity.deleted.list(key), "Entity.deleted.list"),
         },
         // Time-series (no-ops when entity is not configured; runtime check in
         // the entity-level `append` returns a ValidationError).
@@ -7061,17 +7075,37 @@ export const bind = (entity) => Effect.gen(function* () {
                 skFields: orderBy ? [orderBy] : [],
                 composeSkCondition,
                 ...entityNaming(entity._resolveDbName),
+                operation: { name: "Entity.history", target: entity.entityType },
             };
             return new BoundQueryImpl(q, bqConfig);
         },
         // Query execution
+        // Each helper is a named operation, inside `provide` (consumed capacity, #174).
         paginate: (q, ...combinators) => {
             const final = applyQuery(q, combinators);
-            return Stream.unwrap(provide(Query.paginate(final))).pipe(Stream.flatMap((page) => Stream.fromIterable(page)));
+            const options = {
+                ...Query.operationOptions(final),
+                target: entity.entityType,
+            };
+            return Stream.unwrap(provide(Effect.flatMap(Query.paginate(final), (pages) => Capacity.operationStream("Entity.paginate", options, pages)))).pipe(Stream.flatMap((page) => Stream.fromIterable(page)));
+        },
+        collect: (q, ...combinators) => {
+            const final = applyQuery(q, combinators);
+            const options = {
+                ...Query.operationOptions(final),
+                target: entity.entityType,
+            };
+            return provide(Capacity.operation("Entity.collect", options, Query.collect(final)));
+        },
+        fetch: (q, ...combinators) => {
+            const final = applyQuery(q, combinators);
+            const options = {
+                ...Query.operationOptions(final),
+                target: entity.entityType,
+            };
+            return provide(Capacity.operation("Entity.fetch", options, Query.execute(final)));
         },
-        collect: (q, ...combinators) => provide(Query.collect(applyQuery(q, combinators))),
-        fetch: (q, ...combinators) => provide(Query.execute(applyQuery(q, combinators))),
-        scanFetch: (...combinators) => provide(Query.execute(applyQuery(entity.scan(), combinators))),
+        scanFetch: (...combinators) => provide(Capacity.operation("Entity.scan", { target: entity.entityType }, Query.execute(applyQuery(entity.scan(), combinators)))),
     };
 });
 const tagged = (tags) => (e) => typeof e === "object" && e !== null && "_tag" in e && tags.has(String(e._tag));