@jzhuo3/dynamodb-lib 0.1.1 → 0.1.2

package/README.md

@@ -102,6 +102,31 @@ The constructor accepts independent configurations, rather than using one proces
 
 **Update Expression builders** compose the changes passed to `update` as a command array: `Assign`, `AssignIfNotExists`, `Increment`, `Decrement`, `ListAppend`, `ListPrepend`, `Remove`, `SetAdd`, `SetDelete`.
 
+### Inspecting expressions in unit tests
+
+Call `expression.describe()` for a detached, JSON-serializable snapshot containing `expression`, `expressionAttributeNames`, `expressionAttributeValues`, and (for updates) `updateExpressionGroup`. Expressions without values return an empty values object.
+
+```ts
+const description = SetAdd('tags', new Set(['a', 'b'])).describe();
+// description.expressionAttributeValues:
+// { ':val0': { $type: 'Set', values: ['a', 'b'] } }
+const json = JSON.stringify(description);
+```
+
+Strings, booleans, null, finite numbers, arrays and plain objects keep their JSON shape. Nested native values use these explicit representations:
+
+| Native value | Description |
+| --- | --- |
+| `bigint` | `{ $type: 'BigInt', value: '9007199254740993' }` |
+| SDK `NumberValue` | `{ $type: 'NumberValue', value: '123.456' }` |
+| `Set` | `{ $type: 'Set', values: [...] }` |
+| `Buffer`, `ArrayBuffer`, typed array or `DataView` | `{ $type: 'Binary', encoding: 'base64', value: 'AQI=' }` |
+| `Map` | `{ $type: 'Map', entries: [[key, value], ...] }` |
+| `undefined` | `{ $type: 'Undefined' }` |
+| `NaN`, positive/negative infinity | `{ $type: 'Number', value: 'NaN' }` (or `'Infinity'` / `'-Infinity'`) |
+
+Sets and Maps retain insertion order. Binary views serialize only their visible bytes. Circular references, functions, symbols, enumerable symbol keys, and unsupported class instances (including `Date` and `Blob`) throw `TypeError`. Serialization does not validate whether a value is accepted by DynamoDB. This format is for inspection and assertions, not deserialization or sending to DynamoDB; plain objects containing `$type` remain plain objects. The live expression and its values are unchanged.
+
 ## Detailed documentation
 
 See the [documentation index](doc/README.md) for [every service method](doc/service.md), [configuration](doc/configuration.md), [Condition Expression and Update Expression builders](doc/expressions.md), [transaction methods](doc/transactions.md), and [examples](doc/examples.md).

package/dist/cjs/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/cjs/index.js

@@ -356,6 +356,55 @@ 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 lib_dynamodb_1.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);
+    }
+}
 class DynamoDBExpression {
     expressionAttributeNameMap;
     expressionAttributeValueMap;
@@ -369,6 +418,27 @@ 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 }
+                : {}),
+        };
+    }
 }
 exports.DynamoDBExpression = DynamoDBExpression;
 var DynamoDBTransactionMode;