@jzhuo3/dynamodb-lib 0.1.1 → 0.1.2

package/dist/esm/index.d.ts

@@ -135,6 +135,20 @@ export declare function ListPrepend(attribute: string, value: Array<any>, upsert
 export declare function Remove(attribute: string): DynamoDBExpression;
 export declare function SetAdd(attribute: string, value: Set<any>): DynamoDBExpression;
 export declare function SetDelete(attribute: string, value: Set<any>): DynamoDBExpression;
+/** JSON-compatible value used by expression descriptions. */
+export type DynamoDBExpressionSerializedValue = null | boolean | number | string | DynamoDBExpressionSerializedValue[] | {
+    [key: string]: DynamoDBExpressionSerializedValue;
+};
+export type DynamoDBExpressionDescription = {
+    /** DynamoDB expression string, e.g. `#attr0 = :val0`. */
+    expression: string;
+    /** Placeholder -> attribute name (e.g. `#attr0` -> `VersionStamp`). */
+    expressionAttributeNames: Record<string, string>;
+    /** Placeholder -> JSON-compatible value; native non-JSON values use explicit `$type` tags. */
+    expressionAttributeValues: Record<string, DynamoDBExpressionSerializedValue>;
+    /** Which update clause the expression belongs to (SET/REMOVE/ADD/DELETE). */
+    updateExpressionGroup?: 'SET' | 'REMOVE' | 'ADD' | 'DELETE';
+};
 export declare class DynamoDBExpression {
     expressionAttributeNameMap: Map<string, string>;
     expressionAttributeValueMap: Map<string, any> | null;
@@ -143,6 +157,14 @@ export declare class DynamoDBExpression {
     constructor(expressionAttributeNameMap?: Map<string, string>, // e.g. #attr0 -> attribute
     expressionAttributeValueMap?: Map<string, any> | null, // e.g. :val0 -> value
     expression?: string, updateExpressionGroup?: "SET" | "REMOVE" | "ADD" | "DELETE" | undefined);
+    /**
+     * Detached, JSON-serializable description of the expression. Intended for logging,
+     * debugging, and unit tests that need to assert on a built expression
+     * without reaching into the internal Maps.
+     * Sets, bigint, binary, Maps, NumberValue, undefined and non-finite numbers
+     * use explicit `$type` tags. Circular and unsupported values throw TypeError.
+     */
+    describe(): DynamoDBExpressionDescription;
 }
 export declare enum DynamoDBTransactionMode {
     READ = "READ",

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 import { Agent } from 'https';
 import { DynamoDBClient, ReturnConsumedCapacity, } from '@aws-sdk/client-dynamodb';
-import { DynamoDBDocumentClient, GetCommand, BatchGetCommand, QueryCommand, PutCommand, BatchWriteCommand, UpdateCommand, DeleteCommand, TransactGetCommand, TransactWriteCommand, } from '@aws-sdk/lib-dynamodb';
+import { DynamoDBDocumentClient, NumberValue, GetCommand, BatchGetCommand, QueryCommand, PutCommand, BatchWriteCommand, UpdateCommand, DeleteCommand, TransactGetCommand, TransactWriteCommand, } from '@aws-sdk/lib-dynamodb';
 import { diff, camel, snake } from 'radash';
 const silentLogger = { debug() { }, warn() { }, error() { } };
 export class DynamoDBError extends Error {
@@ -324,6 +324,55 @@ export function SetDelete(attribute, value) {
     const expression = `${path} :val0`;
     return new DynamoDBExpression(expressionAttributeNameMap, expressionAttributeValueMap, expression, 'DELETE');
 }
+function serializeExpressionValue(value, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : { $type: 'Number', value: String(value) };
+    }
+    if (typeof value === 'bigint')
+        return { $type: 'BigInt', value: value.toString() };
+    if (value === undefined)
+        return { $type: 'Undefined' };
+    if (typeof value !== 'object') {
+        throw new TypeError(`Cannot describe expression value of type ${typeof value}`);
+    }
+    if (ancestors.has(value))
+        throw new TypeError('Cannot describe circular expression value');
+    ancestors.add(value);
+    try {
+        if (value instanceof NumberValue)
+            return { $type: 'NumberValue', value: value.toString() };
+        if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+            const bytes = value instanceof ArrayBuffer
+                ? Buffer.from(value)
+                : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+            return { $type: 'Binary', encoding: 'base64', value: bytes.toString('base64') };
+        }
+        if (value instanceof Set) {
+            return { $type: 'Set', values: Array.from(value, item => serializeExpressionValue(item, ancestors)) };
+        }
+        if (Array.isArray(value))
+            return Array.from(value, item => serializeExpressionValue(item, ancestors));
+        if (value instanceof Map) {
+            return { $type: 'Map', entries: Array.from(value, ([key, item]) => [
+                    serializeExpressionValue(key, ancestors), serializeExpressionValue(item, ancestors),
+                ]) };
+        }
+        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+            throw new TypeError('Cannot describe unsupported expression value object');
+        }
+        if (Object.getOwnPropertySymbols(value).some(key => Object.prototype.propertyIsEnumerable.call(value, key))) {
+            throw new TypeError('Cannot describe expression value with symbol keys');
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key, serializeExpressionValue(item, ancestors),
+        ]));
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
 export class DynamoDBExpression {
     expressionAttributeNameMap;
     expressionAttributeValueMap;
@@ -337,6 +386,27 @@ export class DynamoDBExpression {
         this.expression = expression;
         this.updateExpressionGroup = updateExpressionGroup;
     }
+    /**
+     * Detached, JSON-serializable description of the expression. Intended for logging,
+     * debugging, and unit tests that need to assert on a built expression
+     * without reaching into the internal Maps.
+     * Sets, bigint, binary, Maps, NumberValue, undefined and non-finite numbers
+     * use explicit `$type` tags. Circular and unsupported values throw TypeError.
+     */
+    describe() {
+        return {
+            expression: this.expression,
+            expressionAttributeNames: Object.fromEntries(this.expressionAttributeNameMap),
+            expressionAttributeValues: this.expressionAttributeValueMap
+                ? Object.fromEntries(Array.from(this.expressionAttributeValueMap, ([key, value]) => [
+                    key, serializeExpressionValue(value),
+                ]))
+                : {},
+            ...(this.updateExpressionGroup !== undefined
+                ? { updateExpressionGroup: this.updateExpressionGroup }
+                : {}),
+        };
+    }
 }
 export var DynamoDBTransactionMode;
 (function (DynamoDBTransactionMode) {