@ftschopp/dynatable-core 2.3.1 → 2.3.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## @ftschopp/dynatable-core [2.3.2](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@2.3.1...@ftschopp/dynatable-core@2.3.2) (2026-06-08)
+
+
+### Bug Fixes
+
+* **core:** materialize primary-key template vars on update() upserts ([#60](https://github.com/ftschopp/dynatable/issues/60)) ([425ec39](https://github.com/ftschopp/dynatable/commit/425ec396b9cb58898575e0fa2ef9cd5d9317a1ce))
+
 ## @ftschopp/dynatable-core [2.3.1](https://github.com/ftschopp/dynatable/compare/@ftschopp/dynatable-core@2.3.0...@ftschopp/dynatable-core@2.3.1) (2026-06-05)
 
 

package/dist/entity/create-entity-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-entity-api.d.ts","sourceRoot":"","sources":["../../src/entity/create-entity-api.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AActF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAMtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CA6PtE,CAAC"}
+{"version":3,"file":"create-entity-api.d.ts","sourceRoot":"","sources":["../../src/entity/create-entity-api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AActF,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAOtD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,eAAe,EAC3D,WAAW,MAAM,EACjB,WAAW,MAAM,EACjB,OAAO,KAAK,EACZ,QAAQ,cAAc,EACtB,UAAS,gBAAqB,KAC7B,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAoPtE,CAAC"}

package/dist/entity/create-entity-api.js

@@ -4,6 +4,7 @@ exports.createEntityAPI = void 0;
 const model_utils_1 = require("../utils/model-utils");
 const zod_utils_1 = require("../utils/zod-utils");
 const builders_1 = require("../builders");
+const build_upsert_seed_1 = require("./transforms/build-upsert-seed");
 const with_middleware_1 = require("./middleware/with-middleware");
 const factories_1 = require("./middleware/factories");
 const key_validation_1 = require("./validation/key-validation");
@@ -101,22 +102,13 @@ const createEntityAPI = (tableName, modelName, model, client, options = {}) => {
             // Resolve any key defaults or computed keys
             const fullKey = (0, model_utils_1.resolveKeys)(model, key);
             const builder = (0, builders_1.createUpdateBuilder)(tableName, fullKey, client, [], 
-            // Seed a SET for the `_type` discriminator, mirroring how put() stamps
-            // it onto the item and how query()/scan() hand-write the `_type` filter.
-            // UpdateItem is an upsert — a create-via-update on a non-existent key
-            // would otherwise produce an item without `_type`, invisible to the
-            // type-filtered query()/scan(). The builder stays agnostic of `_type`:
-            // it just processes whatever actions it is handed. A fixed `:_type`
-            // placeholder keeps it out of the value-name counter so it never
-            // perturbs the numbering of the caller's own actions.
+            // UpdateItem is an upsert: seed the entity's identity columns (`_type`
+            // discriminator + primary-key template vars) so a create-via-update
+            // round-trips with its `id` intact and stays visible to the
+            // type-filtered query()/scan(). See buildUpsertSeedActions for the full
+            // rationale and why these never trip the builder's PK-immutability guard.
             {
-                set: [
-                    {
-                        expression: '#_type = :_type',
-                        names: { '#_type': '_type' },
-                        values: { ':_type': modelName },
-                    },
-                ],
+                set: (0, build_upsert_seed_1.buildUpsertSeedActions)(model, modelName, key),
                 remove: [],
                 add: [],
                 delete: [],

package/dist/entity/transforms/build-upsert-seed.d.ts

@@ -0,0 +1,38 @@
+import { ModelDefinition } from '../../core/types';
+import { UpdateAction } from '../../builders';
+/**
+ * Builds the SET actions that seed an `update()` so a create-via-update
+ * (DynamoDB's UpdateItem is an upsert) produces a fully-formed item rather than
+ * a half-written one.
+ *
+ * UpdateItem on a non-existent key writes only the Key (PK/SK) plus the caller's
+ * explicit actions. That leaves two gaps versus `put()`, which writes the whole
+ * validated model:
+ *
+ *  1. `_type` discriminator — `query()`/`scan()` filter on `#_type = :_type`, so
+ *     an item created without it is silently invisible to both.
+ *  2. Primary-key template variables (e.g. `id` in `PK: 'OPERATION#${id}'`) —
+ *     they stay embedded inside the PK/SK strings and never become standalone
+ *     columns, so a read with `cleanInternalKeys` (which strips PK/SK without
+ *     reconstructing the vars) returns the item with `id: undefined`.
+ *
+ * Seeding both here mirrors how `put()` materializes the model. The update
+ * builder stays agnostic — it just processes the actions it is handed. Two
+ * properties make the seed safe to inject:
+ *
+ *  - Fixed `:_type` / `:_key_<attr>` placeholders keep these values out of the
+ *    builder's value-name counter, so they never perturb the numbering of the
+ *    caller's own `.set()` values (`:name_0`, …).
+ *  - The key-var actions write the exact value already encoded in the Key, so
+ *    they can never drift, and they bypass the PK-template immutability guard
+ *    because that guard only inspects the caller's `.set()` payload — not the
+ *    seeded actions handed to the builder.
+ *
+ * @param model     - The entity's model definition (source of the key templates)
+ * @param modelName - The entity name, written as the `_type` discriminator
+ * @param key       - The template-variable-bearing key passed to `update()`
+ *                    (e.g. `{ id: '123' }`)
+ * @returns The SET actions to seed the update builder's `set` list with.
+ */
+export declare const buildUpsertSeedActions: (model: ModelDefinition, modelName: string, key: Record<string, unknown>) => UpdateAction[];
+//# sourceMappingURL=build-upsert-seed.d.ts.map

package/dist/entity/transforms/build-upsert-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-upsert-seed.d.ts","sourceRoot":"","sources":["../../../src/entity/transforms/build-upsert-seed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,eAAe,EACtB,WAAW,MAAM,EACjB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC3B,YAAY,EA4Bd,CAAC"}

package/dist/entity/transforms/build-upsert-seed.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUpsertSeedActions = void 0;
+const model_utils_1 = require("../../utils/model-utils");
+/**
+ * Builds the SET actions that seed an `update()` so a create-via-update
+ * (DynamoDB's UpdateItem is an upsert) produces a fully-formed item rather than
+ * a half-written one.
+ *
+ * UpdateItem on a non-existent key writes only the Key (PK/SK) plus the caller's
+ * explicit actions. That leaves two gaps versus `put()`, which writes the whole
+ * validated model:
+ *
+ *  1. `_type` discriminator — `query()`/`scan()` filter on `#_type = :_type`, so
+ *     an item created without it is silently invisible to both.
+ *  2. Primary-key template variables (e.g. `id` in `PK: 'OPERATION#${id}'`) —
+ *     they stay embedded inside the PK/SK strings and never become standalone
+ *     columns, so a read with `cleanInternalKeys` (which strips PK/SK without
+ *     reconstructing the vars) returns the item with `id: undefined`.
+ *
+ * Seeding both here mirrors how `put()` materializes the model. The update
+ * builder stays agnostic — it just processes the actions it is handed. Two
+ * properties make the seed safe to inject:
+ *
+ *  - Fixed `:_type` / `:_key_<attr>` placeholders keep these values out of the
+ *    builder's value-name counter, so they never perturb the numbering of the
+ *    caller's own `.set()` values (`:name_0`, …).
+ *  - The key-var actions write the exact value already encoded in the Key, so
+ *    they can never drift, and they bypass the PK-template immutability guard
+ *    because that guard only inspects the caller's `.set()` payload — not the
+ *    seeded actions handed to the builder.
+ *
+ * @param model     - The entity's model definition (source of the key templates)
+ * @param modelName - The entity name, written as the `_type` discriminator
+ * @param key       - The template-variable-bearing key passed to `update()`
+ *                    (e.g. `{ id: '123' }`)
+ * @returns The SET actions to seed the update builder's `set` list with.
+ */
+const buildUpsertSeedActions = (model, modelName, key) => {
+    const seed = [
+        {
+            expression: '#_type = :_type',
+            names: { '#_type': '_type' },
+            values: { ':_type': modelName },
+        },
+    ];
+    // Collect every variable referenced by the primary-key templates (a var may
+    // appear in both PK and SK; the Set dedupes it to a single SET action).
+    const keyTemplateVars = new Set();
+    for (const keyDef of Object.values(model.key)) {
+        for (const v of (0, model_utils_1.extractTemplateVars)(keyDef.value))
+            keyTemplateVars.add(v);
+    }
+    for (const v of keyTemplateVars) {
+        // A missing var would already have been caught by validateKeyFields; guard
+        // anyway so we never emit an action with an undefined value.
+        if (key[v] === undefined)
+            continue;
+        seed.push({
+            expression: `#${v} = :_key_${v}`,
+            names: { [`#${v}`]: v },
+            values: { [`:_key_${v}`]: key[v] },
+        });
+    }
+    return seed;
+};
+exports.buildUpsertSeedActions = buildUpsertSeedActions;

package/package.json

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