@jzhuo3/dynamodb-lib 0.1.0 → 0.1.2

package/PUBLISHING.md

@@ -34,7 +34,15 @@ npm publish --access public
 
 `prepublishOnly` runs the source, unit, build and package checks. Integration tests are explicit because they require an available database; CI runs them against DynamoDB Local. The AWS SDK dependency tree is deliberately bundled with the archive, alongside `npm-shrinkwrap.json`, to preserve the tested Node 18-compatible, patched dependencies. After updating dependencies, refresh the shrinkwrap and run the clean consumer installation check as well as the Node runtime matrix.
 
-This repository contains a verification workflow, but no automatic publishing trigger; the actual release identity and credentials still need to be configured.
+## Automated publishing
+
+Commit and push the workflows and both Release Please configuration files before creating the next release. `release-please.yml` uses the repository variable `RELEASE_APP_CLIENT_ID` and secret `RELEASE_APP_PRIVATE_KEY` to prepare release PRs and create GitHub releases after those PRs are merged.
+
+When a non-prerelease GitHub release is published, `.github/workflows/publish.yml` checks that its tag is `vX.Y.Z` and matches `package.json`. It runs the reusable CI workflow against that exact commit, including unit, package, coverage, clean installation, and DynamoDB Local integration checks across Node 18, 20, 22, and 24. Only after verification passes does its `publish` job enter the `npm` environment and publish using Node 24 and npm 11. Draft releases and prereleases do not publish to npm.
+
+Configure the npm package's GitHub Actions trusted publisher with owner `maczhuo`, repository `dynamodb-lib`, workflow filename `publish.yml`, environment `npm`, and permission for direct `npm publish`. The GitHub environment `npm` must allow release tags such as `v*`. No `NPM_TOKEN` is required. Any environment approval rules will pause the publish job until satisfied.
+
+The workflow does not retroactively publish existing GitHub releases. If a run fails before publication, fix the external configuration and rerun the failed jobs from GitHub Actions. An already published npm version cannot be published again; code or workflow fixes require a new release containing those changes. Initial package creation may still require the manual bootstrap described above.
 
 Official references (checked September 2026):
 

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",