@ftschopp/dynatable-core 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# @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)
+
+
+### Features
+
+* **core:** add setIfNotExists to UpdateBuilder for immutable upsert fields ([#54](https://github.com/ftschopp/dynatable/issues/54)) ([a35d208](https://github.com/ftschopp/dynatable/commit/a35d2087f7b28c46c95a6da98dca910b4a8ee97c))
+
+# @ftschopp/dynatable-core [2.1.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@2.0.0...@ftschopp/dynatable-core@2.1.0) (2026-06-01)
+
+
+### Features
+
+* **core:** auto-inject equality conditions for literal-template keys in query builder ([5ecb781](https://github.com/ftschopp/dynatable/commit/5ecb78130a393a63eb255a49116177bff1caa496))
+
 # @ftschopp/dynatable-core [2.0.0](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@1.6.1...@ftschopp/dynatable-core@2.0.0) (2026-05-11)
 
 

package/README.md

@@ -258,6 +258,7 @@ await table.entities.User.put({
 // UPDATE - Modify attributes
 await table.entities.User.update({ username: 'alice' })
   .set('name', 'Alice Johnson')
+  .setIfNotExists('createdAt', new Date().toISOString()) // write only on first insert
   .add('followerCount', 1)
   .remove('email')
   .returning('ALL_NEW')

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

@@ -1 +1 @@
-{"version":3,"file":"create-query-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/query/create-query-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAiB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAid7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,CAAC,KAAK,CAAC,CA0BrB"}
+{"version":3,"file":"create-query-builder.d.ts","sourceRoot":"","sources":["../../../src/builders/query/create-query-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM1D,OAAO,EAAE,YAAY,EAA8B,MAAM,SAAS,CAAC;AACnE,OAAO,EAAiB,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AA4hB7D;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EACtC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,YAAY,CAAC,KAAK,CAAC,CA0BrB"}

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

@@ -85,6 +85,43 @@ function applyKeyTemplate(template, fieldName, fieldValue, keyOperator) {
         `with only "${fieldName}" provided — the template still contains unfilled ` +
         `variable(s). Use beginsWith for prefix queries on composite keys.`);
 }
+/**
+ * Heuristic for identifying a hash (partition) key by name. Used only to
+ * decide whether a literal-template auto-injection covers DynamoDB's
+ * "Query needs a partition key" requirement — for actual key resolution
+ * we go through {@link keyBelongsToIndex} instead.
+ *
+ * Convention: primary is literally `PK`; index keys are `${indexName}PK`
+ * (conventional) or any `…PK`-suffixed name (non-conventional, opted in
+ * via `KeyDefinition.indexName`). The legitimate non-conventional case
+ * `BySpotifyId` / `lookupPK` is captured by the `endsWith('PK')` check.
+ */
+function isHashKeyName(keyName, indexName) {
+    return indexName ? keyName.endsWith('PK') : keyName === 'PK';
+}
+/**
+ * Collects every key on the active index (or primary) whose template is
+ * fully literal — no `${...}` variables. These keys can't be referenced
+ * by attribute name in `where()` (there is no template var to bind to),
+ * so the query builder synthesizes the equality condition itself.
+ *
+ * Two real-world patterns this enables:
+ *  1. Entity-type partition: `GSI1PK: 'AIRPORT'` with a variable SK —
+ *     "give me every Airport, filtered/range-scoped by SK".
+ *  2. Singleton sort-key marker: `SK: 'PROFILE'` paired with a variable
+ *     PK like `'USER#${userId}'` — auto-injecting SK turns a wasteful
+ *     "scan the whole user partition then filter" into a direct lookup.
+ */
+function getLiteralKeys(model, indexName) {
+    if (!model)
+        return [];
+    const entries = indexName
+        ? Object.entries(model.index ?? {}).filter(([keyName, keyDef]) => keyBelongsToIndex(keyName, keyDef, indexName))
+        : Object.entries(model.key);
+    return entries
+        .filter(([, keyDef]) => (0, model_utils_1.extractTemplateVars)(keyDef.value).length === 0)
+        .map(([keyName, keyDef]) => ({ keyName, value: keyDef.value }));
+}
 /**
  * Separates a condition tree into key conditions and filter conditions
  * Key conditions are rewritten to use actual DynamoDB key names (PK/SK)
@@ -236,12 +273,38 @@ function createQueryExecutor(state) {
             }
             // Separate key conditions from filter conditions
             const { keyConditions, filterConditions } = separateConditions(state.condition, state.model, state.indexName);
-            // DynamoDB Query requires at least a partition-key condition. If
-            // separation didn't pick anything as a key condition, the caller is
-            // either filtering on non-key attributes (which means they want
-            // scan()) or referencing the wrong attribute name. Fail loudly here
-            // instead of letting the SDK reject the request at execute time.
-            if (keyConditions.length === 0) {
+            // Auto-inject equality conditions for keys whose template is fully
+            // literal — they have no `${vars}`, so the user can't reference
+            // them via `attr.*` in `where()`. Two real patterns this enables:
+            //   1. Entity-type GSI partition: `GSI1PK: 'AIRPORT'` — without
+            //      injection DynamoDB rejects the Query for missing the PK.
+            //   2. Sort-key marker: `SK: 'PROFILE'` paired with a variable PK
+            //      like `'USER#${userId}'` — without injection the query reads
+            //      every item under that PK and post-filters by `_type`.
+            // The `covered` check is defensive — a literal-template key can't
+            // appear in user conditions (no template var to bind) — but cheap
+            // protection against future schema shapes.
+            const literalKeys = getLiteralKeys(state.model, state.indexName);
+            const userKeyConditionCount = keyConditions.length;
+            for (const { keyName, value } of literalKeys) {
+                const covered = keyConditions.some((cond) => Object.values(cond.names ?? {}).includes(keyName));
+                if (covered)
+                    continue;
+                keyConditions.push({
+                    expression: `#${keyName} = :${keyName}_literal`,
+                    names: { [`#${keyName}`]: keyName },
+                    values: { [`:${keyName}_literal`]: value },
+                });
+            }
+            // DynamoDB Query requires at least a partition-key condition. The
+            // friendly error fires when:
+            //   - the user's where() contributed zero key conditions, AND
+            //   - no auto-injected literal covers the hash key.
+            // We can't blindly check `keyConditions.length === 0` after
+            // injection because a literal SK alone would silently slip past
+            // and produce a less helpful DynamoDB error.
+            const literalHashInjected = literalKeys.some(({ keyName }) => isHashKeyName(keyName, state.indexName));
+            if (userKeyConditionCount === 0 && !literalHashInjected) {
                 const keyTemplates = state.indexName
                     ? Object.entries(state.model?.index ?? {})
                         .filter(([keyName, def]) => keyBelongsToIndex(keyName, def, state.indexName))

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

@@ -16,5 +16,5 @@ export declare function createUpdateBuilder<Model>(tableName: string, key: Parti
     remove: UpdateAction[];
     add: UpdateAction[];
     delete: UpdateAction[];
-}, returnMode?: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW', valueCounter?: number, enableTimestamps?: boolean, logger?: DynamoDBLogger, indexContext?: IndexContext, setInputs?: Record<string, any>, consumedCapacity?: 'INDEXES' | 'TOTAL' | 'NONE'): UpdateBuilder<Model>;
+}, returnMode?: 'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW', valueCounter?: number, enableTimestamps?: boolean, logger?: DynamoDBLogger, indexContext?: IndexContext, setInputs?: Record<string, any>, consumedCapacity?: 'INDEXES' | 'TOTAL' | 'NONE', setIfNotExistsInputs?: Record<string, any>): UpdateBuilder<Model>;
 //# sourceMappingURL=create-update-builder.d.ts.map

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,GAC9C,aAAa,CAAC,KAAK,CAAC,CAubtB"}
+{"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"}

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

@@ -34,7 +34,14 @@ function actionAttrName(action) {
  * cannot be fully resolved from the primary-key vars plus the updates, building
  * the params throws — the caller must include the missing fields in `.set()`.
  */
-function createUpdateBuilder(tableName, key, client, prevConditions = [], updateActions = { set: [], remove: [], add: [], delete: [] }, returnMode = 'NONE', valueCounter = 0, enableTimestamps = false, logger, indexContext, setInputs = {}, consumedCapacity) {
+function createUpdateBuilder(tableName, key, client, prevConditions = [], updateActions = { set: [], remove: [], add: [], delete: [] }, returnMode = 'NONE', valueCounter = 0, enableTimestamps = false, logger, indexContext, setInputs = {}, consumedCapacity, 
+// Tracks attributes targeted by `.setIfNotExists()` separately from
+// `setInputs`. Index recomputation reads `setInputs` to resolve template
+// values; conditional writes can't supply a static value (DynamoDB picks
+// current vs `:v` at write time), so they must NOT participate in template
+// resolution — but the PK-template / index-template guards still need to
+// see them to reject schema-incompatible usage.
+setIfNotExistsInputs = {}) {
     const conditions = [...prevConditions];
     const getUniqueValueName = (baseName) => {
         return `${baseName}_${valueCounter++}`;
@@ -54,7 +61,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
             });
             const opBuilder = (0, shared_1.createOpBuilder)();
             const condition = fn(attrs, opBuilder);
-            return createUpdateBuilder(tableName, key, client, [...conditions, condition], updateActions, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
+            return createUpdateBuilder(tableName, key, client, [...conditions, condition], updateActions, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, setIfNotExistsInputs);
         },
         set(attrOrUpdates, value) {
             // When no value is provided and the first arg is a plain object,
@@ -77,7 +84,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                     });
                     newSetInputs[attrName] = val;
                 }
-                return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, ...newActions] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, newSetInputs, consumedCapacity);
+                return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, ...newActions] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, newSetInputs, consumedCapacity, setIfNotExistsInputs);
             }
             // Single update case
             const attrName = normalizeAttr(attrOrUpdates);
@@ -87,7 +94,38 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 names: { [`#${attrName}`]: attrName },
                 values: { [`:${valueName}`]: value },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, { ...setInputs, [attrName]: value }, consumedCapacity);
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, { ...setInputs, [attrName]: value }, consumedCapacity, setIfNotExistsInputs);
+        },
+        setIfNotExists(attrOrUpdates, value) {
+            // Object form: treat as Partial<Model>. The AttrRef overload always
+            // passes a value, so it routes through the single-update path below.
+            if (value === undefined &&
+                typeof attrOrUpdates === 'object' &&
+                attrOrUpdates !== null) {
+                const updates = attrOrUpdates;
+                const newActions = [];
+                const newSetIfNotExistsInputs = { ...setIfNotExistsInputs };
+                for (const [attr, val] of Object.entries(updates)) {
+                    const attrName = attr;
+                    const valueName = getUniqueValueName(attrName);
+                    newActions.push({
+                        expression: `#${attrName} = if_not_exists(#${attrName}, :${valueName})`,
+                        names: { [`#${attrName}`]: attrName },
+                        values: { [`:${valueName}`]: val },
+                    });
+                    newSetIfNotExistsInputs[attrName] = val;
+                }
+                return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, ...newActions] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, newSetIfNotExistsInputs);
+            }
+            // Single update case
+            const attrName = normalizeAttr(attrOrUpdates);
+            const valueName = getUniqueValueName(attrName);
+            const action = {
+                expression: `#${attrName} = if_not_exists(#${attrName}, :${valueName})`,
+                names: { [`#${attrName}`]: attrName },
+                values: { [`:${valueName}`]: value },
+            };
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, set: [...updateActions.set, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, { ...setIfNotExistsInputs, [attrName]: value });
         },
         remove(attr) {
             const attrName = normalizeAttr(attr);
@@ -95,7 +133,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 expression: `#${attrName}`,
                 names: { [`#${attrName}`]: attrName },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, remove: [...updateActions.remove, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, remove: [...updateActions.remove, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, setIfNotExistsInputs);
         },
         add(attr, value) {
             const attrName = normalizeAttr(attr);
@@ -105,7 +143,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 names: { [`#${attrName}`]: attrName },
                 values: { [`:${valueName}`]: value },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, add: [...updateActions.add, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, add: [...updateActions.add, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, setIfNotExistsInputs);
         },
         delete(attr, value) {
             const attrName = normalizeAttr(attr);
@@ -115,13 +153,13 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 names: { [`#${attrName}`]: attrName },
                 values: { [`:${valueName}`]: value },
             };
-            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, delete: [...updateActions.delete, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
+            return createUpdateBuilder(tableName, key, client, conditions, { ...updateActions, delete: [...updateActions.delete, action] }, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, setIfNotExistsInputs);
         },
         returning(mode) {
-            return createUpdateBuilder(tableName, key, client, conditions, updateActions, mode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity);
+            return createUpdateBuilder(tableName, key, client, conditions, updateActions, mode, valueCounter, enableTimestamps, logger, indexContext, setInputs, consumedCapacity, setIfNotExistsInputs);
         },
         returnConsumedCapacity(mode) {
-            return createUpdateBuilder(tableName, key, client, conditions, updateActions, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, mode);
+            return createUpdateBuilder(tableName, key, client, conditions, updateActions, returnMode, valueCounter, enableTimestamps, logger, indexContext, setInputs, mode, setIfNotExistsInputs);
         },
         dbParams() {
             // Clone updateActions to avoid mutation
@@ -136,6 +174,7 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 // structured) — for remove/add/delete we read from the action's
                 // attribute-name map.
                 const setFields = Object.keys(setInputs);
+                const setIfNotExistsFields = Object.keys(setIfNotExistsInputs);
                 const removeFields = updateActions.remove
                     .map(actionAttrName)
                     .filter((n) => !!n);
@@ -150,15 +189,21 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 // the user changes a field that participates in the PK/SK template,
                 // the row's PK doesn't move (DynamoDB doesn't allow that) but the
                 // attribute does — leaving an inconsistent row whose PK encodes the
-                // old value. Catch this on every op (.set / .remove / .add / .delete)
-                // before it leaves the process.
+                // old value. Catch this on every op (.set / .setIfNotExists /
+                // .remove / .add / .delete) before it leaves the process.
                 const primaryKeyTemplateVars = new Set();
                 for (const keyDef of Object.values(indexContext.model.key)) {
                     for (const v of (0, model_utils_1.extractTemplateVars)(keyDef.value)) {
                         primaryKeyTemplateVars.add(v);
                     }
                 }
-                const allTouched = [...setFields, ...removeFields, ...addFields, ...deleteFields];
+                const allTouched = [
+                    ...setFields,
+                    ...setIfNotExistsFields,
+                    ...removeFields,
+                    ...addFields,
+                    ...deleteFields,
+                ];
                 const pkConflicts = [
                     ...new Set(allTouched.filter((f) => primaryKeyTemplateVars.has(f))),
                 ];
@@ -174,6 +219,13 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 // the new value, REMOVE strips the field entirely, and DELETE
                 // mutates a Set without naming a scalar. Switching to .set(field,
                 // newValue) lets the recompute path handle it correctly.
+                //
+                // Guard 3: .setIfNotExists() against a field used in a SECONDARY-index
+                // template. The resolved value is decided by DynamoDB at write time
+                // (current attr vs `:v`), so the recompute path cannot statically
+                // produce a value that's guaranteed consistent with the stored
+                // attribute. Allowing it would silently corrupt the index whenever
+                // the conditional write keeps the existing value.
                 if (indexContext.model.index) {
                     const indexTemplateVars = new Set();
                     for (const indexDef of Object.values(indexContext.model.index)) {
@@ -192,6 +244,18 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                             `recomputed without an explicit new value. Use .set(field, ` +
                             `newValue) instead so the index key is recomputed atomically.`);
                     }
+                    const ifNotExistsGsiConflicts = [
+                        ...new Set(setIfNotExistsFields.filter((f) => indexTemplateVars.has(f))),
+                    ];
+                    if (ifNotExistsGsiConflicts.length > 0) {
+                        throw new Error(`Cannot use .setIfNotExists() on field(s) ` +
+                            `[${ifNotExistsGsiConflicts.join(', ')}] — they participate in a ` +
+                            `secondary-index template, and if_not_exists() may keep the ` +
+                            `existing value at write time, which would leave the index key ` +
+                            `inconsistent with the stored attribute. Either restructure the ` +
+                            `schema so this field is not part of any GSI template, or perform ` +
+                            `a get + conditional .set() in two steps.`);
+                    }
                 }
                 const { actions: idxActions, missing } = (0, model_utils_1.computeIndexUpdates)(indexContext.model, indexContext.keyVars, setInputs);
                 if (missing.length > 0) {
@@ -237,6 +301,27 @@ function createUpdateBuilder(tableName, key, client, prevConditions = [], update
                 };
                 actionsToProcess.set = [...actionsToProcess.set, timestampAction];
             }
+            // Dedup guard: DynamoDB rejects overlapping document paths inside a
+            // SET expression (e.g. `SET #foo = :a, #foo = :b` → ValidationException
+            // "Two document paths overlap"). Catch the common footguns —
+            // .set().set() on the same key, .set() + .setIfNotExists() on the
+            // same key, and enableTimestamps + .set/.setIfNotExists('updatedAt')
+            // — before the network round-trip. Runs AFTER the timestamp injection
+            // so #updatedAt collisions are also reported.
+            const setActionNames = actionsToProcess.set
+                .map(actionAttrName)
+                .filter((n) => !!n);
+            const duplicateSetAttrs = [
+                ...new Set(setActionNames.filter((n, i) => setActionNames.indexOf(n) !== i)),
+            ];
+            if (duplicateSetAttrs.length > 0) {
+                throw new Error(`Update would emit multiple SET actions targeting the same ` +
+                    `attribute(s) [${duplicateSetAttrs.join(', ')}]. DynamoDB rejects ` +
+                    `overlapping document paths. Check that you're not combining ` +
+                    `.set() and .setIfNotExists() on the same field, calling .set() ` +
+                    `twice for the same key, or targeting an attribute that ` +
+                    `enableTimestamps already manages (updatedAt).`);
+            }
             const buildSection = (label, actions, includeValues) => actions.length === 0
                 ? null
                 : {

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

@@ -40,6 +40,25 @@ export interface UpdateBuilder<Model> extends Omit<OperationBuilder<Model>, 'dbP
      */
     set(attr: keyof Model | AttrRef, value: any): UpdateBuilder<Model>;
     set(updates: Partial<Model>): UpdateBuilder<Model>;
+    /**
+     * Conditionally sets an attribute only if it does not already exist on the
+     * item, using DynamoDB's `if_not_exists()` SET function. Emits
+     * `#attr = if_not_exists(#attr, :v)`.
+     *
+     * Primary use case: upsert patterns where some fields must be written only
+     * on first insert (immutable `createdAt`, `firstSeenAt`, initial counters).
+     *
+     * Restrictions enforced at `dbParams()` time:
+     * - The field must not participate in the primary-key template (PK is
+     *   immutable; the conditional write is meaningless).
+     * - The field must not participate in any secondary-index template,
+     *   because the resolved value is decided by DynamoDB at write time and
+     *   the index key cannot be recomputed safely.
+     * - The same attribute cannot also be targeted by `.set()` in the same
+     *   update — DynamoDB rejects overlapping document paths.
+     */
+    setIfNotExists(attr: keyof Model | AttrRef, value: any): UpdateBuilder<Model>;
+    setIfNotExists(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;;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;;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.0.0",
+  "version": "2.2.0",
   "description": "Core library for DynamoDB single table design",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",