@ftschopp/dynatable-core 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# @ftschopp/dynatable-core [2.3.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@2.2.1...@ftschopp/dynatable-core@2.3.0) (2026-06-03)
+
+
+### Features
+
+* **core:** add setDefined to UpdateBuilder ([#58](https://github.com/ftschopp/dynatable/issues/58)) ([851c0dc](https://github.com/ftschopp/dynatable/commit/851c0dc8ab6c6eed0555c874c6230d8997530808)), closes [#56](https://github.com/ftschopp/dynatable/issues/56) [#57](https://github.com/ftschopp/dynatable/issues/57)
+
+## @ftschopp/dynatable-core [2.2.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@2.2.0...@ftschopp/dynatable-core@2.2.1) (2026-06-03)
+
+
+### Bug Fixes
+
+* **core:** reject undefined in update actions with actionable error ([#56](https://github.com/ftschopp/dynatable/issues/56)) ([5b8bee9](https://github.com/ftschopp/dynatable/commit/5b8bee9e9c041abdbff1b2b97d1eaba16730f257)), closes [#55](https://github.com/ftschopp/dynatable/issues/55)
+
 # @ftschopp/dynatable-core [2.2.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@2.1.0...@ftschopp/dynatable-core@2.2.0) (2026-06-02)
 
 

package/README.md

@@ -265,6 +265,27 @@ await table.entities.User.update({ username: 'alice' })
   .where((attr, op) => op.gt(attr.followerCount, 0))
   .execute();
 
+// Note: `.set()`, `.setIfNotExists()`, `.add()` and `.delete()` reject
+// `undefined` values up front. DynamoDB can't encode `undefined` in
+// `ExpressionAttributeValues`, so the builder throws with the offending
+// keys instead of letting the request fail server-side. Use `.remove(attr)`
+// to clear an attribute, or filter `undefined` out of your payload before
+// calling `.set()`. `null` is allowed — it writes the DynamoDB `NULL` type.
+
+// UPSERT via setDefined - sync from an external system where undefined
+// means "this attribute no longer applies". Defined values go to SET,
+// undefined keys go to REMOVE. Internally composes `.set()` + `.remove()`,
+// so all guards (PK template, GSI templates, dedup, GSI key recomputation)
+// apply identically.
+await table.entities.User.update({ username: 'alice' })
+  .setDefined({
+    name: tamsRecord.name,           // SET
+    email: tamsRecord.email,         // may be undefined → REMOVE
+    lastSeenAt: new Date().toISOString(),
+  })
+  .setIfNotExists('createdAt', new Date().toISOString())
+  .execute();
+
 // DELETE - Remove item
 await table.entities.User.delete({ username: 'alice' })
   .returning('ALL_OLD')

package/dist/builders/update/create-update-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-update-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/update/create-update-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAA4B,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAyB7D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,EACnB,MAAM,EAAE,cAAc,EACtB,cAAc,GAAE,SAAS,EAAO,EAChC,aAAa,GAAE;IACb,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;CACuB,EAChD,UAAU,GAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAsB,EACnF,YAAY,SAAI,EAChB,gBAAgB,UAAQ,EACxB,MAAM,CAAC,EAAE,cAAc,EACvB,YAAY,CAAC,EAAE,YAAY,EAC3B,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EACnC,gBAAgB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,EAO/C,oBAAoB,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC7C,aAAa,CAAC,KAAK,CAAC,CA4jBtB"}
+{"version":3,"file":"create-update-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/update/create-update-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAgC,SAAS,EAA4B,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAkE7D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EACvC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,EACnB,MAAM,EAAE,cAAc,EACtB,cAAc,GAAE,SAAS,EAAO,EAChC,aAAa,GAAE;IACb,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,MAAM,EAAE,YAAY,EAAE,CAAC;CACuB,EAChD,UAAU,GAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAsB,EACnF,YAAY,SAAI,EAChB,gBAAgB,UAAQ,EACxB,MAAM,CAAC,EAAE,cAAc,EACvB,YAAY,CAAC,EAAE,YAAY,EAC3B,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EACnC,gBAAgB,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,EAO/C,oBAAoB,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GAC7C,aAAa,CAAC,KAAK,CAAC,CA6lBtB"}

package/dist/builders/update/create-update-builder.js

@@ -25,6 +25,37 @@ function actionAttrName(action) {
     const values = Object.values(action.names);
     return values[0];
 }
+/**
+ * Reject `undefined` before it reaches DynamoDB. SET / ADD / DELETE /
+ * setIfNotExists all encode the value into `ExpressionAttributeValues` — an
+ * `undefined` there is either silently dropped by the marshaller (when
+ * `removeUndefinedValues` is on, which then fails server-side with an unused
+ * expression value error) or rejected outright. Catching it at the call site
+ * gives a useful error and a pointer to the right primitive.
+ *
+ * `null` is intentionally allowed — DynamoDB has a NULL attribute type and
+ * the caller may legitimately want to write it.
+ */
+function assertNoUndefined(method, payload) {
+    const undefinedKeys = 'attr' in payload
+        ? payload.value === undefined
+            ? [payload.attr]
+            : []
+        : Object.entries(payload)
+            .filter(([, v]) => v === undefined)
+            .map(([k]) => k);
+    if (undefinedKeys.length === 0)
+        return;
+    const guidance = method === 'set'
+        ? `Use .remove(attr) to clear an attribute, or filter undefined out ` +
+            `before calling .set().`
+        : method === 'setIfNotExists'
+            ? `setIfNotExists requires a concrete value; omit the key or filter ` +
+                `it out.`
+            : `.${method}() requires a concrete value for each attribute.`;
+    throw new Error(`.${method}() received undefined for key(s) [${undefinedKeys.join(', ')}]. ` +
+        `DynamoDB cannot encode undefined in ExpressionAttributeValues. ${guidance}`);
+}
 /**
  * Creates an UpdateBuilder for an item key and table.
  *
@@ -72,6 +103,7 @@ setIfNotExistsInputs = {}) {
                 attrOrUpdates !== null) {
                 // Multiple updates case
                 const updates = attrOrUpdates;
+                assertNoUndefined('set', updates);
                 const newActions = [];
                 const newSetInputs = { ...setInputs };
                 for (const [attr, val] of Object.entries(updates)) {
@@ -88,6 +120,7 @@ setIfNotExistsInputs = {}) {
             }
             // Single update case
             const attrName = normalizeAttr(attrOrUpdates);
+            assertNoUndefined('set', { attr: attrName, value });
             const valueName = getUniqueValueName(attrName);
             const action = {
                 expression: `#${attrName} = :${valueName}`,
@@ -103,6 +136,7 @@ setIfNotExistsInputs = {}) {
                 typeof attrOrUpdates === 'object' &&
                 attrOrUpdates !== null) {
                 const updates = attrOrUpdates;
+                assertNoUndefined('setIfNotExists', updates);
                 const newActions = [];
                 const newSetIfNotExistsInputs = { ...setIfNotExistsInputs };
                 for (const [attr, val] of Object.entries(updates)) {
@@ -119,6 +153,7 @@ setIfNotExistsInputs = {}) {
             }
             // Single update case
             const attrName = normalizeAttr(attrOrUpdates);
+            assertNoUndefined('setIfNotExists', { attr: attrName, value });
             const valueName = getUniqueValueName(attrName);
             const action = {
                 expression: `#${attrName} = if_not_exists(#${attrName}, :${valueName})`,
@@ -127,6 +162,33 @@ setIfNotExistsInputs = {}) {
             };
             return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, { ...setIfNotExistsInputs, [attrName]: value });
         },
+        setDefined(updates) {
+            // Split the payload, then route through the public `.set()` and
+            // `.remove()` paths so all of their guards apply unchanged: PK
+            // template immutability, GSI template guard 2 (which will reject
+            // any `undefined` targeting a GSI-template field), dedup, and the
+            // index-key recomputation triggered by `setInputs`. Composing the
+            // builder instead of re-emitting actions keeps the surface area
+            // of this method as close to zero as possible.
+            const defined = {};
+            const toRemove = [];
+            for (const [attr, val] of Object.entries(updates)) {
+                if (val === undefined) {
+                    toRemove.push(attr);
+                }
+                else {
+                    defined[attr] = val;
+                }
+            }
+            let next = build();
+            if (Object.keys(defined).length > 0) {
+                next = next.set(defined);
+            }
+            for (const attr of toRemove) {
+                next = next.remove(attr);
+            }
+            return next;
+        },
         remove(attr) {
             const attrName = normalizeAttr(attr);
             const action = {
@@ -137,6 +199,7 @@ setIfNotExistsInputs = {}) {
         },
         add(attr, value) {
             const attrName = normalizeAttr(attr);
+            assertNoUndefined('add', { attr: attrName, value });
             const valueName = getUniqueValueName(attrName);
             const action = {
                 expression: `#${attrName} :${valueName}`,
@@ -147,6 +210,7 @@ setIfNotExistsInputs = {}) {
         },
         delete(attr, value) {
             const attrName = normalizeAttr(attr);
+            assertNoUndefined('delete', { attr: attrName, value });
             const valueName = getUniqueValueName(attrName);
             const action = {
                 expression: `#${attrName} :${valueName}`,

package/dist/builders/update/types.d.ts

@@ -59,6 +59,28 @@ export interface UpdateBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbP
      */
     setIfNotExists(attr: keyof Model | AttrRef, value: any): UpdateBuilder<Model>;
     setIfNotExists(updates: Partial<Model>): UpdateBuilder<Model>;
+    /**
+     * Upsert helper: writes attributes whose value is defined with SET, and
+     * removes attributes whose value is `undefined`. Equivalent to splitting
+     * the payload between `.set()` and `.remove()` at the call site, but
+     * makes the intent explicit at the API.
+     *
+     * Typical use case: syncing from an external system where a missing field
+     * in the source payload means "this attribute no longer applies" rather
+     * than "leave the existing value alone" — the latter is what `.set()`
+     * with `undefined` would imply, and it's a destructive footgun the strict
+     * `.set()` rightly rejects.
+     *
+     * Internally routes through `.set()` and `.remove()`, so every existing
+     * guard (primary-key template, secondary-index templates, dedup,
+     * GSI-key recomputation) applies identically — including the rejection
+     * of `.remove()` on fields used in a GSI template, which will surface as
+     * an error here whenever an `undefined` targets such a field.
+     *
+     * `null` is treated as a defined value and writes the DynamoDB `NULL`
+     * type — only `undefined` triggers the REMOVE branch.
+     */
+    setDefined(updates: Partial<Model>): UpdateBuilder<Model>;
     /**
      * Removes an attribute from the item
      */

package/dist/builders/update/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/update/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEzF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC/F;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAExF;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACnE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnD;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9E,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE9D;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnE;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEtE;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,GACnE,aAAa,CAAC,KAAK,CAAC,CAAC;IAExB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEjF;;OAEG;IACH,QAAQ,IAAI,kBAAkB,CAAC;CAChC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/builders/update/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEzF;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,CAAE,SAAQ,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAC/F;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,SAAS,KAAK,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAExF;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACnE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnD;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9E,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE9D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAE1D;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEnE;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEtE;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,GACnE,aAAa,CAAC,KAAK,CAAC,CAAC;IAExB;;;;;;;;OAQG;IACH,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEjF;;OAEG;IACH,QAAQ,IAAI,kBAAkB,CAAC;CAChC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftschopp/dynatable-core",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",