effect-dynamodb 1.24.0 → 1.26.0

package/dist/internal/Hydrate.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @internal `BatchGetItem` by key, results in input order — shared by
+ * `Batch.get` and the hydration of a stream index that does not project the
+ * events it indexes (`EventStore.makeStream({ indexes: { …, projection: "keys" } })`
+ * on a GSI, read through `Query`'s `hydration` hook).
+ *
+ * - Chunks of 100 keys (DynamoDB's `BatchGetItem` limit).
+ * - `UnprocessedKeys` are retried with exponential backoff (`baseDelayMs`,
+ *   doubling); when `maxRetries` run out the call fails with `DynamoError`
+ *   (`operation: "BatchGetItem"`).
+ * - `BatchGetItem` does not preserve order, so responses are matched back to
+ *   their keys through a `Map` on the key attribute values.
+ * - With `rereadMissing`, keys absent from every response are read once more
+ *   with `ConsistentRead: true` — an eventually consistent table read can lag
+ *   a GSI that already holds the entry.
+ *
+ * Keys are sent as given. Callers pass keys that are unique within one
+ * request — a page of one stream's index never repeats a key — and a repeated
+ * key is not de-duplicated: DynamoDB rejects the request ("Provided list of
+ * item keys contains duplicates"), and the rejection is diagnosed (#144) as a
+ * `DynamoError` naming both positions (`describe`), DynamoDB's error kept as
+ * the cause.
+ */
+import type { AttributeValue } from "@aws-sdk/client-dynamodb";
+import { Effect } from "effect";
+import type { DynamoClientError, DynamoClientService } from "../DynamoClient.js";
+/** DynamoDB's limit on the keys of one `BatchGetItem` request. */
+export declare const MAX_BATCH_GET = 100;
+/** Default retries of `UnprocessedKeys`. */
+export declare const MAX_RETRIES = 5;
+/** Default first backoff delay, doubled on each retry. */
+export declare const BASE_DELAY_MS = 100;
+/** One key to fetch: the table and the item's full primary key. */
+export interface HydrateRequest {
+    readonly tableName: string;
+    readonly key: Record<string, AttributeValue>;
+}
+export interface HydrateOptions {
+    /** A `ProjectionExpression` (and its names) sent for every table. */
+    readonly projection?: {
+        readonly expression: string;
+        readonly names: Record<string, string>;
+    } | undefined;
+    readonly maxRetries?: number | undefined;
+    readonly baseDelayMs?: number | undefined;
+    /** Re-read keys missing from the responses once, strongly consistently. */
+    readonly rereadMissing?: boolean | undefined;
+    /**
+     * The entity a request reads and how to name it in an error (`get 2
+     * (User)`), for a rejection of a repeated key. Default: `request <i>`.
+     */
+    readonly describe?: ((position: number) => {
+        readonly entityType: string;
+        readonly source: string;
+    }) | undefined;
+}
+/**
+ * Fetch `requests` and return the raw items in input order, `undefined` where
+ * an item does not exist.
+ */
+export declare const batchGetRaw: (client: DynamoClientService, requests: ReadonlyArray<HydrateRequest>, options?: HydrateOptions) => Effect.Effect<Array<Record<string, AttributeValue> | undefined>, DynamoClientError>;
+//# sourceMappingURL=Hydrate.d.ts.map

package/dist/internal/Hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hydrate.d.ts","sourceRoot":"","sources":["../../src/internal/Hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,0BAA0B,CAAA;AAEjF,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAQhF,kEAAkE;AAClE,eAAO,MAAM,aAAa,MAAM,CAAA;AAChC,4CAA4C;AAC5C,eAAO,MAAM,WAAW,IAAI,CAAA;AAC5B,0DAA0D;AAC1D,eAAO,MAAM,aAAa,MAAM,CAAA;AAEhC,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAChB;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GACvE,SAAS,CAAA;IACb,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EACd,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAChF,SAAS,CAAA;CACd;AAkBD;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,mBAAmB,EAC3B,UAAU,aAAa,CAAC,cAAc,CAAC,EACvC,UAAS,cAAmB,KAC3B,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,CAAC,EAAE,iBAAiB,CAoKjF,CAAA"}

package/dist/internal/Hydrate.js

@@ -0,0 +1,191 @@
+/**
+ * @internal `BatchGetItem` by key, results in input order — shared by
+ * `Batch.get` and the hydration of a stream index that does not project the
+ * events it indexes (`EventStore.makeStream({ indexes: { …, projection: "keys" } })`
+ * on a GSI, read through `Query`'s `hydration` hook).
+ *
+ * - Chunks of 100 keys (DynamoDB's `BatchGetItem` limit).
+ * - `UnprocessedKeys` are retried with exponential backoff (`baseDelayMs`,
+ *   doubling); when `maxRetries` run out the call fails with `DynamoError`
+ *   (`operation: "BatchGetItem"`).
+ * - `BatchGetItem` does not preserve order, so responses are matched back to
+ *   their keys through a `Map` on the key attribute values.
+ * - With `rereadMissing`, keys absent from every response are read once more
+ *   with `ConsistentRead: true` — an eventually consistent table read can lag
+ *   a GSI that already holds the entry.
+ *
+ * Keys are sent as given. Callers pass keys that are unique within one
+ * request — a page of one stream's index never repeats a key — and a repeated
+ * key is not de-duplicated: DynamoDB rejects the request ("Provided list of
+ * item keys contains duplicates"), and the rejection is diagnosed (#144) as a
+ * `DynamoError` naming both positions (`describe`), DynamoDB's error kept as
+ * the cause.
+ */
+import { DynamoError } from "@effect-dynamodb/schema/Errors.js";
+import { Effect } from "effect";
+import { diagnoseFailure, transactItemTarget, withCause, } from "./WriteDiagnosis.js";
+/** DynamoDB's limit on the keys of one `BatchGetItem` request. */
+export const MAX_BATCH_GET = 100;
+/** Default retries of `UnprocessedKeys`. */
+export const MAX_RETRIES = 5;
+/** Default first backoff delay, doubled on each retry. */
+export const BASE_DELAY_MS = 100;
+/** A key attribute value, as a string that is equal iff the values are. */
+const scalarIdentity = (value) => {
+    if (value === undefined)
+        return "-";
+    if (value.S !== undefined)
+        return `S${value.S}`;
+    if (value.N !== undefined)
+        return `N${value.N}`;
+    if (value.B !== undefined)
+        return `B${Array.from(value.B).join(",")}`;
+    return `J${JSON.stringify(value)}`;
+};
+const identity = (tableName, names, item) => [tableName, ...names.map((name) => `${name}=${scalarIdentity(item[name])}`)].join("\u0000");
+/**
+ * Fetch `requests` and return the raw items in input order, `undefined` where
+ * an item does not exist.
+ */
+export const batchGetRaw = (client, requests, options = {}) => Effect.gen(function* () {
+    const results = new Array(requests.length).fill(undefined);
+    if (requests.length === 0)
+        return results;
+    const maxRetries = options.maxRetries ?? MAX_RETRIES;
+    const baseDelayMs = options.baseDelayMs ?? BASE_DELAY_MS;
+    /** The sorted key attribute names of each request, and its identity. */
+    const keyNames = requests.map((request) => Object.keys(request.key).sort());
+    const identities = requests.map((request, i) => identity(request.tableName, keyNames[i], request.key));
+    /**
+     * The item each key of a sent request reads, in request order, named by
+     * its position (a repeated key's occurrences by successive positions).
+     */
+    const repeatTargets = (sentItems) => {
+        const seen = new Map();
+        return Object.entries(sentItems).flatMap(([tableName, entry]) => (entry.Keys ?? []).map((key) => {
+            const names = Object.keys(key).sort();
+            const id = identity(tableName, names, key);
+            const occurrence = seen.get(id) ?? 0;
+            seen.set(id, occurrence + 1);
+            const positions = identities.flatMap((candidate, i) => (candidate === id ? [i] : []));
+            const position = positions[Math.min(occurrence, positions.length - 1)];
+            const described = position === undefined
+                ? { entityType: "unknown", source: "a request" }
+                : (options.describe?.(position) ?? {
+                    entityType: "unknown",
+                    source: `request ${position}`,
+                });
+            return transactItemTarget({ Get: { TableName: tableName, Key: key } }, tableName, names, described.entityType, described.source);
+        }));
+    };
+    /** Fetch the requests at `positions`, filling `results`. */
+    const fetch = (positions, consistentRead) => Effect.gen(function* () {
+        for (let start = 0; start < positions.length; start += MAX_BATCH_GET) {
+            const chunk = positions.slice(start, start + MAX_BATCH_GET);
+            const pending = new Map();
+            /** Per table: the distinct key-name lists its keys use. */
+            const tableKeyNames = new Map();
+            let requestItems = {};
+            for (const position of chunk) {
+                const request = requests[position];
+                const id = identities[position];
+                // A repeated key is still sent: DynamoDB rejects a request whose
+                // keys repeat ("Provided list of item keys contains duplicates"),
+                // and that rejection passes through — the helper does not quietly
+                // de-duplicate. The positions are grouped only for matching.
+                const waiting = pending.get(id);
+                if (waiting !== undefined)
+                    waiting.push(position);
+                else
+                    pending.set(id, [position]);
+                const names = keyNames[position];
+                let lists = tableKeyNames.get(request.tableName);
+                if (lists === undefined) {
+                    lists = new Map();
+                    tableKeyNames.set(request.tableName, lists);
+                }
+                lists.set(names.join("\u0000"), names);
+                let entry = requestItems[request.tableName];
+                if (entry === undefined) {
+                    entry = {
+                        Keys: [],
+                        ...(consistentRead ? { ConsistentRead: true } : {}),
+                        ...(options.projection === undefined
+                            ? {}
+                            : {
+                                ProjectionExpression: options.projection.expression,
+                                ExpressionAttributeNames: options.projection.names,
+                            }),
+                    };
+                    requestItems[request.tableName] = entry;
+                }
+                entry.Keys.push(request.key);
+            }
+            let retries = 0;
+            while (Object.keys(requestItems).length > 0) {
+                const sentItems = requestItems;
+                const response = yield* client.batchGetItem({ RequestItems: sentItems }).pipe(
+                // A key repeated in one request (#144): DynamoDB's rejection,
+                // confirmed and named by the positions that read it.
+                diagnoseFailure({
+                    sent: () => ({ _tag: "BatchGet", targets: () => repeatTargets(sentItems) }),
+                    only: ["RepeatedItem"],
+                    rewrite: (diagnosis, original) => diagnosis._tag !== "RepeatedItem"
+                        ? original
+                        : new DynamoError({
+                            operation: "BatchGetItem",
+                            cause: withCause(`BatchGetItem reads one item more than once — ` +
+                                `${diagnosis.first.source} and ${diagnosis.second.source} both ` +
+                                `read the item at ${diagnosis.second.key}. DynamoDB allows each key ` +
+                                "once in a request, and rejected it. Read the item once.", original),
+                        }),
+                }));
+                for (const [tableName, items] of Object.entries(response.Responses ?? {})) {
+                    const lists = tableKeyNames.get(tableName);
+                    if (lists === undefined)
+                        continue;
+                    for (const item of items) {
+                        for (const names of lists.values()) {
+                            const matched = pending.get(identity(tableName, names, item));
+                            if (matched === undefined)
+                                continue;
+                            for (const position of matched)
+                                results[position] = item;
+                            break;
+                        }
+                    }
+                }
+                const unprocessed = {};
+                for (const [tableName, entry] of Object.entries(response.UnprocessedKeys ?? {})) {
+                    if (entry.Keys !== undefined && entry.Keys.length > 0) {
+                        // Keep what the original request asked for (consistency,
+                        // projection) — only the keys change.
+                        unprocessed[tableName] = { ...requestItems[tableName], Keys: entry.Keys };
+                    }
+                }
+                if (Object.keys(unprocessed).length === 0)
+                    break;
+                retries++;
+                if (retries > maxRetries) {
+                    return yield* new DynamoError({
+                        operation: "BatchGetItem",
+                        cause: new Error(`Unprocessed keys remain after ${maxRetries} retries`),
+                    });
+                }
+                yield* Effect.sleep(`${baseDelayMs * 2 ** (retries - 1)} millis`);
+                requestItems = unprocessed;
+            }
+        }
+    });
+    yield* fetch(requests.map((_, i) => i), false);
+    if (options.rereadMissing === true) {
+        const missing = [];
+        for (let i = 0; i < results.length; i++)
+            if (results[i] === undefined)
+                missing.push(i);
+        if (missing.length > 0)
+            yield* fetch(missing, true);
+    }
+    return results;
+});
+//# sourceMappingURL=Hydrate.js.map

package/dist/internal/Hydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hydrate.js","sourceRoot":"","sources":["../../src/internal/Hydrate.ts"],"names":[],"mappings":"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"}

package/dist/internal/ItemSize.d.ts

@@ -1,38 +1,74 @@
 /**
- * @internal Item sizes by DynamoDB's item-size rules, shared by `Batch.write`'s
- * versioned transactions (chunked by size) and the client-side size check of
- * `Transaction.transactWrite` and `EventStore.append` (#133).
+ * @internal Exact sizes by DynamoDB's own accounting (#144), the one measure
+ * the library uses: `Batch.write` chunks its versioned-put transactions by
+ * it, and the failure-time diagnosis of DynamoDB's write limits
+ * (`internal/WriteDiagnosis.ts`) names the item at fault by it. Nothing here
+ * refuses a write: DynamoDB's own limits are never pre-checked.
+ *
+ * The rules were measured on DynamoDB Local from the `Payload Size` its 4 MB
+ * rejection reports, and confirmed at the exact boundaries: an item of
+ * 409,600 bytes is accepted and 409,601 rejected; a transaction of 4,194,304
+ * bytes is accepted and 4,194,305 rejected.
+ *
+ * - An item is the sum over its attributes of `utf8(name) + size(value)`, with
+ *   no per-item or per-attribute overhead.
+ * - `S`: UTF-8 bytes. `B`: byte length. `BOOL`, `NULL`: 1.
+ * - `N`: see {@link numberBytes} (at most 21 bytes, a negative one included).
+ * - `SS` / `NS` / `BS`: the sum of the elements' sizes, no overhead.
+ * - `L`: `3 + Σ (size(element) + 1)`. `M`: `3 + Σ (utf8(name) + size(value) + 1)`.
+ * - A transaction action: its item (a Put) or its key (any other action), plus
+ *   each of its expressions — see {@link transactItemBytes}.
  */
 import type { AttributeValue, TransactWriteItem } from "@aws-sdk/client-dynamodb";
 /**
- * DynamoDB's limit on the aggregate size of the items in one
- * `TransactWriteItems` request: 4 MB, in the binary megabytes DynamoDB uses
- * for every size limit (an item's 400 KB is 409,600 bytes).
+ * DynamoDB's limit on the size of one `TransactWriteItems` request: 4 MB, in
+ * the binary megabytes DynamoDB uses for every size limit — 4,194,304 bytes,
+ * measured by {@link transactItemBytes}.
  */
 export declare const TRANSACT_WRITE_MAX_BYTES: number;
+/** DynamoDB's limit on the size of one item: 400 KB, which is 409,600 bytes. */
+export declare const ITEM_MAX_BYTES: number;
 export declare const utf8Bytes: (text: string) => number;
 /**
- * Which way a size errs. DynamoDB documents its sizes as approximate, so:
+ * A number's size as DynamoDB stores it. Zero is 1 byte. Otherwise: 1, plus
+ * one byte per base-100 digit pair of the magnitude — pairs aligned to the
+ * decimal point, all-zero pairs trimmed at both ends — plus 1 if negative,
+ * except when the magnitude takes the maximum 20 pairs: a number is never
+ * more than 21 bytes.
  *
- * - `"lower"` never counts more than DynamoDB does — a refusal on it never
- *   refuses what DynamoDB would accept (the transaction check). Numbers count
- *   as DynamoDB stores them: a byte per two significant digits (leading and
- *   trailing zeros trimmed), plus one; list and map overheads aren't counted.
- * - `"upper"` never counts less — a budget on it never overfills (`Batch.write`
- *   chunking). Numbers count by their characters plus one, and lists and maps
- *   carry three bytes plus one per element.
+ * Measured: `1`, `10`, `99`, `100`, `1200`, `1e10`, `0.5`, `0.05`, `0.0012`,
+ * `9.9E+125` → 2; `101`, `120`, `1234`, `1.5`, `12.34`, `10.01` → 3;
+ * `12345`, `1.234`, `-123` → 4; `-1` → 3; a 38-digit integer → 20;
+ * `-123456789012345678901234567890123456.78` (19 pairs) → 21;
+ * `-9.9999999999999999999999999999999999999` and
+ * `-1.2345678901234567890123456789012345678` (20 pairs) → 21.
  */
-export type SizeBound = "lower" | "upper";
-/** An attribute value's size toward its item's, erring the way `bound` says. */
-export declare const attributeBytes: (value: AttributeValue, bound?: SizeBound) => number;
-/** An item's size: its attribute names plus their values. */
-export declare const itemBytes: (item: Record<string, AttributeValue>, bound?: SizeBound) => number;
+export declare const numberBytes: (n: string) => number;
+/** An attribute value's size, by the rules in this module's header. */
+export declare const attributeBytes: (value: AttributeValue) => number;
+/** An item's size: its attribute names plus their values. What the 400 KB limit measures. */
+export declare const itemBytes: (item: Record<string, AttributeValue>) => number;
 /**
- * A lower bound on what one transact entry contributes to its transaction's
- * size, as far as the request shows it: a Put's whole item; a Delete's,
- * ConditionCheck's or Update's key. (An Update's values aren't counted: some
- * may be its condition's, and the item it writes is the stored one updated,
- * which the request does not carry.)
+ * An expression's contribution to a transaction's size: its UTF-8 length as
+ * written, plus, for every placeholder **occurrence**, the substituted name's
+ * UTF-8 bytes (`#name`) or value's size (`:value`). A placeholder the maps do
+ * not define adds nothing (DynamoDB rejects such a request anyway).
+ *
+ * Expressions count toward the 4 MB transaction limit, never toward an item's
+ * 400 KB.
+ */
+export declare const expressionBytes: (expression: string | undefined, names: Record<string, string> | undefined, values: Record<string, AttributeValue> | undefined) => number;
+/**
+ * One action's contribution to its `TransactWriteItems` request's size:
+ *
+ * - a Put's item, or an Update's, Delete's or ConditionCheck's key — never the
+ *   stored item, nor the item an Update produces;
+ * - plus each of its expressions (`ConditionExpression`, an Update's
+ *   `UpdateExpression`) by {@link expressionBytes}.
+ *
+ * `TableName` and `ReturnValuesOnConditionCheckFailure` add nothing.
  */
 export declare const transactItemBytes: (item: TransactWriteItem) => number;
+/** A `TransactWriteItems` request's size: the sum of its actions' contributions. */
+export declare const transactionBytes: (items: ReadonlyArray<TransactWriteItem>) => number;
 //# sourceMappingURL=ItemSize.d.ts.map

package/dist/internal/ItemSize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ItemSize.d.ts","sourceRoot":"","sources":["../../src/internal/ItemSize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAEjF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAkB,CAAA;AAEvD,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,MAA+C,CAAA;AAExF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAgBzC,gFAAgF;AAChF,eAAO,MAAM,cAAc,GAAI,OAAO,cAAc,EAAE,QAAO,SAAmB,KAAG,MAgBlF,CAAA;AAED,6DAA6D;AAC7D,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACpC,QAAO,SAAmB,KACzB,MAIA,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,iBAAiB,KAAG,MAG3D,CAAA"}
+{"version":3,"file":"ItemSize.d.ts","sourceRoot":"","sources":["../../src/internal/ItemSize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAEjF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAkB,CAAA;AAEvD,gFAAgF;AAChF,eAAO,MAAM,cAAc,QAAa,CAAA;AAIxC,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,MAAqC,CAAA;AAE9E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,KAAG,MAkBvC,CAAA;AAED,uEAAuE;AACvE,eAAO,MAAM,cAAc,GAAI,OAAO,cAAc,KAAG,MAgBtD,CAAA;AAED,6FAA6F;AAC7F,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,KAAG,MAI9D,CAAA;AAIH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC1B,YAAY,MAAM,GAAG,SAAS,EAC9B,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EACzC,QAAQ,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,KACjD,MAaF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,iBAAiB,KAAG,MAc3D,CAAA;AAED,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,GAAI,OAAO,aAAa,CAAC,iBAAiB,CAAC,KAAG,MACZ,CAAA"}

package/dist/internal/ItemSize.js

@@ -1,62 +1,145 @@
 /**
- * @internal Item sizes by DynamoDB's item-size rules, shared by `Batch.write`'s
- * versioned transactions (chunked by size) and the client-side size check of
- * `Transaction.transactWrite` and `EventStore.append` (#133).
+ * @internal Exact sizes by DynamoDB's own accounting (#144), the one measure
+ * the library uses: `Batch.write` chunks its versioned-put transactions by
+ * it, and the failure-time diagnosis of DynamoDB's write limits
+ * (`internal/WriteDiagnosis.ts`) names the item at fault by it. Nothing here
+ * refuses a write: DynamoDB's own limits are never pre-checked.
+ *
+ * The rules were measured on DynamoDB Local from the `Payload Size` its 4 MB
+ * rejection reports, and confirmed at the exact boundaries: an item of
+ * 409,600 bytes is accepted and 409,601 rejected; a transaction of 4,194,304
+ * bytes is accepted and 4,194,305 rejected.
+ *
+ * - An item is the sum over its attributes of `utf8(name) + size(value)`, with
+ *   no per-item or per-attribute overhead.
+ * - `S`: UTF-8 bytes. `B`: byte length. `BOOL`, `NULL`: 1.
+ * - `N`: see {@link numberBytes} (at most 21 bytes, a negative one included).
+ * - `SS` / `NS` / `BS`: the sum of the elements' sizes, no overhead.
+ * - `L`: `3 + Σ (size(element) + 1)`. `M`: `3 + Σ (utf8(name) + size(value) + 1)`.
+ * - A transaction action: its item (a Put) or its key (any other action), plus
+ *   each of its expressions — see {@link transactItemBytes}.
  */
 /**
- * DynamoDB's limit on the aggregate size of the items in one
- * `TransactWriteItems` request: 4 MB, in the binary megabytes DynamoDB uses
- * for every size limit (an item's 400 KB is 409,600 bytes).
+ * DynamoDB's limit on the size of one `TransactWriteItems` request: 4 MB, in
+ * the binary megabytes DynamoDB uses for every size limit — 4,194,304 bytes,
+ * measured by {@link transactItemBytes}.
  */
 export const TRANSACT_WRITE_MAX_BYTES = 4 * 1024 * 1024;
-export const utf8Bytes = (text) => new TextEncoder().encode(text).length;
-/** A number's significant digits: sign, point and exponent dropped, zeros trimmed. */
-const significantDigits = (n) => {
-    const mantissa = n.split(/[eE]/)[0] ?? "";
-    const digits = mantissa.replace(/[-+.]/g, "").replace(/^0+/, "").replace(/0+$/, "");
-    return digits.length;
-};
-const numberBytes = (n, bound) => {
-    if (bound === "upper")
-        return n.length + 1;
-    // Zero has no significant digits, and is stored in one byte.
-    const digits = significantDigits(n);
-    return digits === 0 ? 1 : Math.ceil(digits / 2) + 1;
+/** DynamoDB's limit on the size of one item: 400 KB, which is 409,600 bytes. */
+export const ITEM_MAX_BYTES = 400 * 1024;
+const encoder = new TextEncoder();
+export const utf8Bytes = (text) => encoder.encode(text).length;
+/**
+ * A number's size as DynamoDB stores it. Zero is 1 byte. Otherwise: 1, plus
+ * one byte per base-100 digit pair of the magnitude — pairs aligned to the
+ * decimal point, all-zero pairs trimmed at both ends — plus 1 if negative,
+ * except when the magnitude takes the maximum 20 pairs: a number is never
+ * more than 21 bytes.
+ *
+ * Measured: `1`, `10`, `99`, `100`, `1200`, `1e10`, `0.5`, `0.05`, `0.0012`,
+ * `9.9E+125` → 2; `101`, `120`, `1234`, `1.5`, `12.34`, `10.01` → 3;
+ * `12345`, `1.234`, `-123` → 4; `-1` → 3; a 38-digit integer → 20;
+ * `-123456789012345678901234567890123456.78` (19 pairs) → 21;
+ * `-9.9999999999999999999999999999999999999` and
+ * `-1.2345678901234567890123456789012345678` (20 pairs) → 21.
+ */
+export const numberBytes = (n) => {
+    let text = n.trim();
+    const negative = text.startsWith("-");
+    if (negative || text.startsWith("+"))
+        text = text.slice(1);
+    const [mantissa = "", exponent] = text.split(/[eE]/);
+    const [whole = "", fraction = ""] = mantissa.split(".");
+    const all = whole + fraction;
+    const leading = /^0*/.exec(all)[0].length;
+    const digits = all.slice(leading).replace(/0+$/, "");
+    if (digits.length === 0)
+        return 1;
+    // How many significant digits sit before the decimal point (negative: the
+    // first one sits that many places after it). Pairs are aligned to the point,
+    // so an odd count leaves the first digit alone in its pair.
+    const beforePoint = whole.length + Number(exponent ?? 0) - leading;
+    const aligned = (Math.abs(beforePoint) % 2 === 1 ? 1 : 0) + digits.length;
+    const pairs = Math.ceil(aligned / 2);
+    // The sign byte is left off at the maximum 20 pairs (measured).
+    return 1 + pairs + (negative && pairs < 20 ? 1 : 0);
 };
-/** An attribute value's size toward its item's, erring the way `bound` says. */
-export const attributeBytes = (value, bound = "lower") => {
+/** An attribute value's size, by the rules in this module's header. */
+export const attributeBytes = (value) => {
     if (value.S !== undefined)
         return utf8Bytes(value.S);
     if (value.N !== undefined)
-        return numberBytes(value.N, bound);
+        return numberBytes(value.N);
     if (value.B !== undefined)
         return value.B.byteLength;
+    if (value.BOOL !== undefined || value.NULL !== undefined)
+        return 1;
     if (value.SS !== undefined)
         return value.SS.reduce((sum, v) => sum + utf8Bytes(v), 0);
     if (value.NS !== undefined)
-        return value.NS.reduce((sum, v) => sum + numberBytes(v, bound), 0);
+        return value.NS.reduce((sum, v) => sum + numberBytes(v), 0);
     if (value.BS !== undefined)
         return value.BS.reduce((sum, v) => sum + v.byteLength, 0);
-    const overhead = bound === "upper";
-    if (value.L !== undefined) {
-        return value.L.reduce((sum, v) => sum + attributeBytes(v, bound) + (overhead ? 1 : 0), overhead ? 3 : 0);
+    if (value.L !== undefined)
+        return value.L.reduce((sum, v) => sum + attributeBytes(v) + 1, 3);
+    if (value.M !== undefined) {
+        return Object.entries(value.M).reduce((sum, [name, v]) => sum + utf8Bytes(name) + attributeBytes(v) + 1, 3);
+    }
+    return 0;
+};
+/** An item's size: its attribute names plus their values. What the 400 KB limit measures. */
+export const itemBytes = (item) => Object.entries(item).reduce((sum, [name, value]) => sum + utf8Bytes(name) + attributeBytes(value), 0);
+const PLACEHOLDER = /[#:][A-Za-z0-9_]+/g;
+/**
+ * An expression's contribution to a transaction's size: its UTF-8 length as
+ * written, plus, for every placeholder **occurrence**, the substituted name's
+ * UTF-8 bytes (`#name`) or value's size (`:value`). A placeholder the maps do
+ * not define adds nothing (DynamoDB rejects such a request anyway).
+ *
+ * Expressions count toward the 4 MB transaction limit, never toward an item's
+ * 400 KB.
+ */
+export const expressionBytes = (expression, names, values) => {
+    if (expression === undefined)
+        return 0;
+    let bytes = utf8Bytes(expression);
+    for (const [placeholder] of expression.matchAll(PLACEHOLDER)) {
+        if (placeholder.startsWith("#")) {
+            const name = names?.[placeholder];
+            if (name !== undefined)
+                bytes += utf8Bytes(name);
+        }
+        else {
+            const value = values?.[placeholder];
+            if (value !== undefined)
+                bytes += attributeBytes(value);
+        }
     }
-    if (value.M !== undefined)
-        return itemBytes(value.M, bound) + (overhead ? 3 : 0);
-    return 1;
+    return bytes;
 };
-/** An item's size: its attribute names plus their values. */
-export const itemBytes = (item, bound = "lower") => Object.entries(item).reduce((sum, [name, value]) => sum + utf8Bytes(name) + attributeBytes(value, bound), 0);
 /**
- * A lower bound on what one transact entry contributes to its transaction's
- * size, as far as the request shows it: a Put's whole item; a Delete's,
- * ConditionCheck's or Update's key. (An Update's values aren't counted: some
- * may be its condition's, and the item it writes is the stored one updated,
- * which the request does not carry.)
+ * One action's contribution to its `TransactWriteItems` request's size:
+ *
+ * - a Put's item, or an Update's, Delete's or ConditionCheck's key — never the
+ *   stored item, nor the item an Update produces;
+ * - plus each of its expressions (`ConditionExpression`, an Update's
+ *   `UpdateExpression`) by {@link expressionBytes}.
+ *
+ * `TableName` and `ReturnValuesOnConditionCheckFailure` add nothing.
  */
 export const transactItemBytes = (item) => {
-    if (item.Put !== undefined)
-        return itemBytes(item.Put.Item ?? {});
-    return itemBytes(item.Delete?.Key ?? item.Update?.Key ?? item.ConditionCheck?.Key ?? {});
+    const action = item.Put ?? item.Update ?? item.Delete ?? item.ConditionCheck;
+    if (action === undefined)
+        return 0;
+    const names = action.ExpressionAttributeNames;
+    const values = action.ExpressionAttributeValues;
+    const base = item.Put !== undefined
+        ? itemBytes(item.Put.Item ?? {})
+        : itemBytes((item.Update ?? item.Delete ?? item.ConditionCheck)?.Key ?? {});
+    return (base +
+        expressionBytes(action.ConditionExpression, names, values) +
+        expressionBytes(item.Update?.UpdateExpression, names, values));
 };
+/** A `TransactWriteItems` request's size: the sum of its actions' contributions. */
+export const transactionBytes = (items) => items.reduce((sum, item) => sum + transactItemBytes(item), 0);
 //# sourceMappingURL=ItemSize.js.map

package/dist/internal/ItemSize.js.map

@@ -1 +1 @@
-{"version":3,"file":"ItemSize.js","sourceRoot":"","sources":["../../src/internal/ItemSize.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ItemSize.js","sourceRoot":"","sources":["../../src/internal/ItemSize.ts"],"names":[],"mappings":"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"}