dyna-record 0.6.3 → 0.6.4

package/README.md

@@ -212,7 +212,7 @@ class Store extends MyTable {
 }
 ```
 
-- **Supported field types:** `"string"`, `"number"`, `"boolean"`, `"date"` (stored as ISO strings, exposed as `Date` objects), `"enum"` (via `values`), nested `"object"` (via `fields`), and `"array"` (via `items`)
+- **Supported field types:** `"string"`, `"number"`, `"boolean"`, `"date"` (stored as ISO strings, exposed as `Date` objects), `"enum"` (via `values`), nested `"object"` (via `fields`), `"array"` (via `items`), and `"discriminatedUnion"` (via `discriminator` + `variants`)
 - **Nullable fields:** Set `nullable: true` on individual non-object fields within the schema to make them optional
 - **Object attributes are never nullable:** DynamoDB cannot update nested document paths (e.g., `address.geo.lat`) if the parent object does not exist. To prevent this, `@ObjectAttribute` fields always exist as at least an empty object `{}`. Nested object fields within the schema are also never nullable. Non-object fields (primitives, enums, dates, arrays) can still be nullable.
 - **Alias support:** Use the `alias` option to map to a different DynamoDB attribute name
@@ -249,6 +249,48 @@ const schema = {
 
 The schema must be declared with `as const satisfies ObjectSchema` so TypeScript preserves the literal string values for type inference. At runtime, providing an invalid value (e.g., `status: "unknown"`) throws a `ValidationError`.
 
+##### Discriminated union fields
+
+Use `{ type: "discriminatedUnion", discriminator: "...", variants: { ... } }` to define a field that is a tagged union of object types. Each variant is an `ObjectSchema` keyed by its discriminator value. The discriminator key is automatically included in each variant's inferred type as a string literal.
+
+```typescript
+const drawingSchema = {
+  shape: {
+    type: "discriminatedUnion",
+    discriminator: "kind",
+    variants: {
+      circle: { radius: { type: "number" } },
+      square: { side: { type: "number" } }
+    }
+  }
+} as const satisfies ObjectSchema;
+
+@Entity
+class Drawing extends MyTable {
+  declare readonly type: "Drawing";
+
+  @ObjectAttribute({ alias: "Drawing", schema: drawingSchema })
+  public readonly drawing: InferObjectSchema<typeof drawingSchema>;
+}
+
+// TypeScript infers:
+// drawing.shape → { kind: "circle"; radius: number } | { kind: "square"; side: number }
+```
+
+Unlike nested `"object"` fields, discriminated union fields **can be nullable** (`nullable: true`) because they always use **full replacement** on update rather than document path expressions:
+
+```typescript
+// Replaces the entire shape field — no partial merge
+await Drawing.update("123", {
+  drawing: { shape: { kind: "square", side: 10 } }
+});
+```
+
+**Scoping constraints (initial release):**
+
+- Supported at the ObjectAttribute root level and as fields within an ObjectSchema
+- Not supported inside array items or nested inside other discriminated unions
+
 ### Foreign Keys
 
 Define foreign keys in order to support [@BelongsTo](https://docs.dyna-record.com/functions/BelongsTo.html) relationships. A foreign key is required for [@HasOne](https://docs.dyna-record.com/functions/HasOne.html) and [@HasMany](https://docs.dyna-record.com/functions/HasMany.html) relationships.
@@ -990,6 +1032,15 @@ await Store.update("123", {
 });
 ```
 
+**Discriminated unions** within objects are also **full replacement** (not merged):
+
+```typescript
+// Replaces the entire shape — switches from circle to square
+await Drawing.update("123", {
+  drawing: { shape: { kind: "square", side: 10 } }
+});
+```
+
 The instance `update` method returns a deep-merged result, preserving existing fields:
 
 ```typescript

package/dist/src/decorators/attributes/ObjectAttribute.d.ts

@@ -10,7 +10,7 @@ import type { ObjectSchema, InferObjectSchema } from "./types";
  * `ValidationException: The document path provided in the update expression is invalid for update`.
  * To avoid this, `@ObjectAttribute` fields always exist as at least an empty object `{}`.
  *
- * The schema supports all {@link FieldDef} types: primitives, enums, nested objects, and arrays.
+ * The schema supports all {@link FieldDef} types: primitives, enums, nested objects, arrays, and discriminated unions.
  * Non-object fields within the schema may still be nullable.
  *
  * @template S The specific ObjectSchema type used for type inference
@@ -47,6 +47,7 @@ export interface ObjectAttributeOptions<S extends ObjectSchema> extends NonNullA
  * - `"date"` — dates stored as ISO strings (support `nullable: true`)
  * - `"object"` — nested objects, arbitrarily deep (**never nullable**)
  * - `"array"` — lists of any field type (support `nullable: true`, full replacement on update)
+ * - `"discriminatedUnion"` — tagged unions via `discriminator` + `variants` (support `nullable: true`, full replacement on update)
  *
  * Objects within arrays are not subject to the document path limitation because arrays
  * use full replacement on update. Partial updates of individual objects within arrays
@@ -102,6 +103,10 @@ export interface ObjectAttributeOptions<S extends ObjectSchema> extends NonNullA
  * await MyEntity.update("id", { address: { zip: null } });
  * ```
  *
+ * **Discriminated union fields** always use **full replacement** on update — the user
+ * must provide a complete variant object. See {@link DiscriminatedUnionFieldDef} for
+ * the rationale.
+ *
  * Object attributes support filtering in queries using dot-path notation for nested fields
  * and the {@link ContainsFilter | $contains} operator for List membership checks.
  *

package/dist/src/decorators/attributes/ObjectAttribute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectAttribute.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/ObjectAttribute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EACV,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAY,MAAM,SAAS,CAAC;AAGzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,YAAY,CAC5D,SAAQ,uBAAuB;IAC/B;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;CACX;AA6GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,iBAAS,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,CAAC,CAAC,SAAS,YAAY,EACzE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,YAGtB,SAAS,WACR,yBAAyB,CAChC,CAAC,EACD,iBAAiB,CAAC,CAAC,CAAC,EACpB,sBAAsB,CAAC,CAAC,CAAC,CAC1B,UAmBJ;AAED,eAAe,eAAe,CAAC"}
+{"version":3,"file":"ObjectAttribute.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/ObjectAttribute.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EACV,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EAGlB,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,YAAY,CAC5D,SAAQ,uBAAuB;IAC/B;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;CACX;AAgKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,iBAAS,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,CAAC,CAAC,SAAS,YAAY,EACzE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,YAGtB,SAAS,WACR,yBAAyB,CAChC,CAAC,EACD,iBAAiB,CAAC,CAAC,CAAC,EACpB,sBAAsB,CAAC,CAAC,CAAC,CAC1B,UAoBJ;AAED,eAAe,eAAe,CAAC"}

package/dist/src/decorators/attributes/ObjectAttribute.js

@@ -27,11 +27,17 @@ function objectSchemaToZodPartial(schema) {
  * Converts a single {@link FieldDef} to the corresponding partial Zod type.
  * Nested objects use partial schemas; all other types use the standard schema.
  * Object fields are never nullable — they always exist as at least `{}`.
+ * Discriminated union fields use the full schema (not partial) since they
+ * always use full replacement on update.
  */
 function fieldDefToZodPartial(fieldDef) {
     if (fieldDef.type === "object") {
         return objectSchemaToZodPartial(fieldDef.fields);
     }
+    if (fieldDef.type === "discriminatedUnion") {
+        // Discriminated unions use full replacement — same schema as create
+        return discriminatedUnionToZod(fieldDef);
+    }
     // For non-object fields, use the standard schema (includes nullable wrapping)
     return fieldDefToZod(fieldDef);
 }
@@ -48,12 +54,39 @@ function objectSchemaToZod(schema) {
     }
     return zod_1.z.object(shape);
 }
+/**
+ * Builds a Zod `discriminatedUnion` schema from a {@link DiscriminatedUnionFieldDef}.
+ *
+ * Each variant's ObjectSchema is converted to a `z.object()` and extended with a
+ * `z.literal()` for the discriminator key. The resulting schemas are wrapped in
+ * `z.discriminatedUnion()`.
+ *
+ * @param fieldDef The discriminated union field definition
+ * @returns A ZodType that validates discriminated union values
+ */
+function discriminatedUnionToZod(fieldDef) {
+    if (Object.keys(fieldDef.variants).length === 0) {
+        throw new Error("DiscriminatedUnionFieldDef requires at least one variant");
+    }
+    const variantSchemas = Object.entries(fieldDef.variants).map(([variantKey, variantObjectSchema]) => {
+        const variantZod = objectSchemaToZod(variantObjectSchema);
+        return variantZod.extend({
+            [fieldDef.discriminator]: zod_1.z.literal(variantKey)
+        });
+    });
+    let zodType = zod_1.z.discriminatedUnion(fieldDef.discriminator, variantSchemas);
+    if (fieldDef.nullable === true) {
+        zodType = zodType.optional().nullable();
+    }
+    return zodType;
+}
 /**
  * Converts a single {@link FieldDef} to the corresponding Zod type for runtime validation.
  *
  * Handles all field types:
  * - `"object"` → recursively builds a `z.object()` via {@link objectSchemaToZod}.
  *   Object fields are never nullable — DynamoDB requires them to exist for document path updates.
+ * - `"discriminatedUnion"` → `z.discriminatedUnion()` via {@link discriminatedUnionToZod}
  * - `"array"` → `z.array()` wrapping a recursive call for the `items` type
  * - `"string"` → `z.string()`
  * - `"number"` → `z.number()`
@@ -70,6 +103,10 @@ function fieldDefToZod(fieldDef) {
     if (fieldDef.type === "object") {
         return objectSchemaToZod(fieldDef.fields);
     }
+    // Discriminated union fields handle their own nullable wrapping
+    if (fieldDef.type === "discriminatedUnion") {
+        return discriminatedUnionToZod(fieldDef);
+    }
     let zodType;
     switch (fieldDef.type) {
         case "array":
@@ -118,6 +155,7 @@ function fieldDefToZod(fieldDef) {
  * - `"date"` — dates stored as ISO strings (support `nullable: true`)
  * - `"object"` — nested objects, arbitrarily deep (**never nullable**)
  * - `"array"` — lists of any field type (support `nullable: true`, full replacement on update)
+ * - `"discriminatedUnion"` — tagged unions via `discriminator` + `variants` (support `nullable: true`, full replacement on update)
  *
  * Objects within arrays are not subject to the document path limitation because arrays
  * use full replacement on update. Partial updates of individual objects within arrays
@@ -173,6 +211,10 @@ function fieldDefToZod(fieldDef) {
  * await MyEntity.update("id", { address: { zip: null } });
  * ```
  *
+ * **Discriminated union fields** always use **full replacement** on update — the user
+ * must provide a complete variant object. See {@link DiscriminatedUnionFieldDef} for
+ * the rationale.
+ *
  * Object attributes support filtering in queries using dot-path notation for nested fields
  * and the {@link ContainsFilter | $contains} operator for List membership checks.
  *
@@ -188,11 +230,12 @@ function fieldDefToZod(fieldDef) {
  */
 function ObjectAttribute(props) {
     return function (_value, context) {
+        // Fail fast: surface schema validation errors at class definition time.
+        const { schema, ...restProps } = props;
+        const zodSchema = objectSchemaToZod(schema);
+        const partialZodSchema = objectSchemaToZodPartial(schema);
+        const serializers = (0, serializers_1.createObjectSerializer)(schema);
         context.addInitializer(function () {
-            const { schema, ...restProps } = props;
-            const zodSchema = objectSchemaToZod(schema);
-            const partialZodSchema = objectSchemaToZodPartial(schema);
-            const serializers = (0, serializers_1.createObjectSerializer)(schema);
             metadata_1.default.addEntityAttribute(this.constructor.name, {
                 attributeName: context.name.toString(),
                 type: zodSchema,

package/dist/src/decorators/attributes/index.d.ts

@@ -10,5 +10,5 @@ export { default as IdAttribute } from "./IdAttribute";
 export { default as ObjectAttribute } from "./ObjectAttribute";
 export type { ObjectAttributeOptions } from "./ObjectAttribute";
 export * from "./serializers";
-export type { ObjectSchema, InferObjectSchema, FieldDef, PrimitiveFieldDef, ObjectFieldDef, ArrayFieldDef, EnumFieldDef, DateFieldDef } from "./types";
+export type { ObjectSchema, NonUnionObjectSchema, InferObjectSchema, InferDiscriminatedUnion, FieldDef, NonUnionFieldDef, PrimitiveFieldDef, ObjectFieldDef, ArrayFieldDef, EnumFieldDef, DateFieldDef, DiscriminatedUnionFieldDef } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/decorators/attributes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,cAAc,eAAe,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,YAAY,EACZ,YAAY,EACb,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,cAAc,eAAe,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,0BAA0B,EAC3B,MAAM,SAAS,CAAC"}

package/dist/src/decorators/attributes/serializers.d.ts

@@ -19,6 +19,8 @@ export declare const dateSerializer: {
  * - `"date"` fields are converted from `Date` objects to ISO 8601 strings.
  * - `"object"` fields recurse into their nested schema.
  * - `"array"` fields map each item through the same conversion.
+ * - `"discriminatedUnion"` fields look up the variant schema by discriminator value
+ *   and recurse into that variant's object schema, preserving the discriminator key.
  * - `null` and `undefined` values are stripped from the result so that nullable
  *   fields set to `null` are removed from the stored object rather than persisted
  *   as `null` in DynamoDB.
@@ -29,6 +31,21 @@ export declare const dateSerializer: {
  * @returns A new object suitable for DynamoDB storage
  */
 export declare function objectToTableItem(schema: ObjectSchema, value: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Converts a single field value to its DynamoDB table representation based on
+ * the field definition.
+ *
+ * - `"date"` → ISO 8601 string
+ * - `"object"` → recursively converts via {@link objectToTableItem}
+ * - `"array"` → maps each item through the same conversion
+ * - `"discriminatedUnion"` → looks up the variant schema by discriminator value,
+ *   converts via {@link objectToTableItem}, and preserves the discriminator key
+ * - All other types pass through unchanged
+ *
+ * @param fieldDef The {@link FieldDef} describing the field's type
+ * @param val The entity-level value to convert
+ * @returns The DynamoDB-compatible value
+ */
 export declare function convertFieldToTableItem(fieldDef: FieldDef, val: unknown): unknown;
 /**
  * Recursively walks an {@link ObjectSchema} and converts a DynamoDB table item
@@ -37,6 +54,8 @@ export declare function convertFieldToTableItem(fieldDef: FieldDef, val: unknown
  * - `"date"` fields are converted from ISO 8601 strings to `Date` objects.
  * - `"object"` fields recurse into their nested schema.
  * - `"array"` fields map each item through the same conversion.
+ * - `"discriminatedUnion"` fields look up the variant schema by discriminator value
+ *   and recurse into that variant's object schema, preserving the discriminator key.
  * - `null` and `undefined` values are stripped from the result so that absent
  *   fields are represented as `undefined` (omitted) on the entity, consistent
  *   with root-level nullable attribute behaviour.

package/dist/src/decorators/attributes/serializers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializers.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/serializers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;6BACA,oBAAoB,KAAG,OAAO;4BAM/B,OAAO;CAEhC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,OAAO,GACX,OAAO,CAaT;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAiBD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAOxE"}
+{"version":3,"file":"serializers.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/serializers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;6BACA,oBAAoB,KAAG,OAAO;4BAM/B,OAAO;CAEhC,CAAC;AAuBF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,OAAO,GACX,OAAO,CAqBT;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAOxE"}

package/dist/src/decorators/attributes/serializers.js

@@ -21,6 +21,20 @@ exports.dateSerializer = {
     },
     toTableAttribute: (val) => val instanceof Date ? val.toISOString() : undefined
 };
+/**
+ * Resolves the variant schema for a discriminated union value by reading the
+ * discriminator key and looking up the corresponding variant in the field definition.
+ *
+ * Uses `Object.hasOwn` to guard against prototype property pollution — only
+ * own-enumerable variant keys are matched.
+ */
+function resolveVariantSchema(fieldDef, value) {
+    const discriminatorValue = value[fieldDef.discriminator];
+    if (!Object.hasOwn(fieldDef.variants, discriminatorValue)) {
+        return undefined;
+    }
+    return fieldDef.variants[discriminatorValue];
+}
 /**
  * Recursively walks an {@link ObjectSchema} and converts the entity value to its
  * DynamoDB representation.
@@ -28,6 +42,8 @@ exports.dateSerializer = {
  * - `"date"` fields are converted from `Date` objects to ISO 8601 strings.
  * - `"object"` fields recurse into their nested schema.
  * - `"array"` fields map each item through the same conversion.
+ * - `"discriminatedUnion"` fields look up the variant schema by discriminator value
+ *   and recurse into that variant's object schema, preserving the discriminator key.
  * - `null` and `undefined` values are stripped from the result so that nullable
  *   fields set to `null` are removed from the stored object rather than persisted
  *   as `null` in DynamoDB.
@@ -48,6 +64,21 @@ function objectToTableItem(schema, value) {
     }
     return result;
 }
+/**
+ * Converts a single field value to its DynamoDB table representation based on
+ * the field definition.
+ *
+ * - `"date"` → ISO 8601 string
+ * - `"object"` → recursively converts via {@link objectToTableItem}
+ * - `"array"` → maps each item through the same conversion
+ * - `"discriminatedUnion"` → looks up the variant schema by discriminator value,
+ *   converts via {@link objectToTableItem}, and preserves the discriminator key
+ * - All other types pass through unchanged
+ *
+ * @param fieldDef The {@link FieldDef} describing the field's type
+ * @param val The entity-level value to convert
+ * @returns The DynamoDB-compatible value
+ */
 function convertFieldToTableItem(fieldDef, val) {
     switch (fieldDef.type) {
         case "date":
@@ -56,6 +87,15 @@ function convertFieldToTableItem(fieldDef, val) {
             return objectToTableItem(fieldDef.fields, val);
         case "array":
             return val.map(item => convertFieldToTableItem(fieldDef.items, item));
+        case "discriminatedUnion": {
+            const value = val;
+            const variantSchema = resolveVariantSchema(fieldDef, value);
+            if (variantSchema === undefined)
+                return val;
+            const result = objectToTableItem(variantSchema, value);
+            result[fieldDef.discriminator] = value[fieldDef.discriminator];
+            return result;
+        }
         default:
             return val;
     }
@@ -67,6 +107,8 @@ function convertFieldToTableItem(fieldDef, val) {
  * - `"date"` fields are converted from ISO 8601 strings to `Date` objects.
  * - `"object"` fields recurse into their nested schema.
  * - `"array"` fields map each item through the same conversion.
+ * - `"discriminatedUnion"` fields look up the variant schema by discriminator value
+ *   and recurse into that variant's object schema, preserving the discriminator key.
  * - `null` and `undefined` values are stripped from the result so that absent
  *   fields are represented as `undefined` (omitted) on the entity, consistent
  *   with root-level nullable attribute behaviour.
@@ -87,6 +129,13 @@ function tableItemToObject(schema, value) {
     }
     return result;
 }
+/**
+ * Converts a single DynamoDB field value back to its entity representation.
+ *
+ * Mirrors {@link convertFieldToTableItem} in reverse: dates become `Date` objects,
+ * objects and discriminated unions recurse through their schemas, arrays map each item,
+ * and all other types pass through unchanged.
+ */
 function convertFieldToEntityValue(fieldDef, val) {
     switch (fieldDef.type) {
         case "date":
@@ -95,6 +144,15 @@ function convertFieldToEntityValue(fieldDef, val) {
             return tableItemToObject(fieldDef.fields, val);
         case "array":
             return val.map(item => convertFieldToEntityValue(fieldDef.items, item));
+        case "discriminatedUnion": {
+            const value = val;
+            const variantSchema = resolveVariantSchema(fieldDef, value);
+            if (variantSchema === undefined)
+                return val;
+            const result = tableItemToObject(variantSchema, value);
+            result[fieldDef.discriminator] = value[fieldDef.discriminator];
+            return result;
+        }
         default:
             return val;
     }

package/dist/src/decorators/attributes/types.d.ts

@@ -91,8 +91,13 @@ export interface ObjectFieldDef {
 export interface ArrayFieldDef {
     /** Must be `"array"` to indicate a list/array field. */
     type: "array";
-    /** A {@link FieldDef} describing the type of each array element. */
-    items: FieldDef;
+    /**
+     * A {@link NonUnionFieldDef} describing the type of each array element.
+     * Discriminated unions are not supported as array items because arrays use
+     * full replacement on update and the variant-aware serialization semantics
+     * are not defined for array item context.
+     */
+    items: NonUnionFieldDef;
     /** When `true`, the field becomes optional. */
     nullable?: boolean;
 }
@@ -171,6 +176,71 @@ export interface DateFieldDef {
     /** When `true`, the field becomes optional (`Date | undefined`). */
     nullable?: boolean;
 }
+/**
+ * A schema field definition for a discriminated union type.
+ *
+ * The `discriminator` names the key used to distinguish variants, and `variants`
+ * maps each discriminator value to an {@link ObjectSchema} describing that variant's
+ * fields. The discriminator key is automatically added to each variant's inferred type
+ * as a string literal.
+ *
+ * **Update semantics:** Discriminated union fields always use **full replacement** on
+ * update (`SET #field = :value`), never document path merging. This is because:
+ * - Different variants have different field sets — a partial document path update could
+ *   leave orphaned fields from a previous variant leaking through when variants change.
+ * - Avoiding orphaned fields without full replacement would require a read-before-write
+ *   to determine the current discriminator value.
+ * - This matches array update semantics (also full replacement).
+ *
+ * Unlike {@link ObjectFieldDef}, discriminated union fields **can be nullable** because
+ * they always use full replacement on update rather than document path expressions,
+ * so there is no risk of DynamoDB failing on a missing parent path.
+ *
+ * **Scoping constraints (initial release):**
+ * - Supported at the ObjectAttribute root level and as fields within an ObjectSchema
+ * - Not supported inside array items or nested inside other discriminated unions
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   shape: {
+ *     type: "discriminatedUnion",
+ *     discriminator: "kind",
+ *     variants: {
+ *       circle: { radius: { type: "number" } },
+ *       square: { side: { type: "number" } }
+ *     }
+ *   }
+ * } as const satisfies ObjectSchema;
+ *
+ * type T = InferObjectSchema<typeof schema>;
+ * // { shape: { kind: "circle"; radius: number } | { kind: "square"; side: number } }
+ * ```
+ */
+export interface DiscriminatedUnionFieldDef {
+    /** Must be `"discriminatedUnion"` to indicate a discriminated union field. */
+    type: "discriminatedUnion";
+    /** The key name used to discriminate between variants. */
+    discriminator: string;
+    /**
+     * A record mapping each discriminator value to a {@link NonUnionObjectSchema}
+     * describing that variant's fields (excluding the discriminator itself).
+     * Discriminated unions cannot be nested inside other discriminated unions.
+     */
+    variants: Readonly<Record<string, NonUnionObjectSchema>>;
+    /** When `true`, the field becomes optional (`T | undefined`). */
+    nullable?: boolean;
+}
+/**
+ * A field definition that excludes {@link DiscriminatedUnionFieldDef}.
+ *
+ * Used in contexts where discriminated unions are not allowed:
+ * - {@link ArrayFieldDef} `items` — arrays use full replacement and variant-aware
+ *   serialization is not defined for array item context
+ * - {@link DiscriminatedUnionFieldDef} `variants` — discriminated unions cannot
+ *   be nested inside other discriminated unions
+ */
+export type NonUnionFieldDef = PrimitiveFieldDef | DateFieldDef | ObjectFieldDef | ArrayFieldDef | EnumFieldDef;
 /**
  * A field definition within an {@link ObjectSchema}.
  *
@@ -180,10 +250,17 @@ export interface DateFieldDef {
  * - {@link ObjectFieldDef} — nested objects via `fields`
  * - {@link ArrayFieldDef} — arrays/lists via `items`
  * - {@link EnumFieldDef} — string literal enums via `values`
+ * - {@link DiscriminatedUnionFieldDef} — discriminated unions via `discriminator` + `variants`
  *
  * Each variant is discriminated by the `type` property.
  */
-export type FieldDef = PrimitiveFieldDef | DateFieldDef | ObjectFieldDef | ArrayFieldDef | EnumFieldDef;
+export type FieldDef = NonUnionFieldDef | DiscriminatedUnionFieldDef;
+/**
+ * ObjectSchema that excludes discriminated union fields.
+ * Used for {@link DiscriminatedUnionFieldDef} variant schemas where
+ * nested discriminated unions are not allowed.
+ */
+export type NonUnionObjectSchema = Record<string, NonUnionFieldDef>;
 /**
  * Declarative schema for describing the shape of an object attribute.
  *
@@ -205,18 +282,36 @@ export type FieldDef = PrimitiveFieldDef | DateFieldDef | ObjectFieldDef | Array
  * ```
  */
 export type ObjectSchema = Record<string, FieldDef>;
+/**
+ * Infers the TypeScript type of a {@link DiscriminatedUnionFieldDef}.
+ *
+ * Iterates over the variant keys and for each produces a union member that is
+ * `{ [discriminator]: VariantKey } & InferObjectSchema<VariantSchema>`.
+ *
+ * @example
+ * ```typescript
+ * // Given: discriminator: "kind", variants: { circle: { radius: { type: "number" } }, square: { side: { type: "number" } } }
+ * // Produces: { kind: "circle"; radius: number } | { kind: "square"; side: number }
+ * ```
+ */
+export type InferDiscriminatedUnion<F extends DiscriminatedUnionFieldDef> = {
+    [V in keyof F["variants"] & string]: {
+        [D in F["discriminator"]]: V;
+    } & InferObjectSchema<F["variants"][V]>;
+}[keyof F["variants"] & string];
 /**
  * Infers the TypeScript type of a single {@link FieldDef}.
  *
  * Used internally by {@link InferObjectSchema} and for recursive array item inference.
  *
  * Resolution order:
- * 1. {@link ArrayFieldDef} → `Array<InferFieldDef<items>>`
- * 2. {@link ObjectFieldDef} → `InferObjectSchema<fields>`
- * 3. {@link EnumFieldDef} → `values[number]` (string literal union)
- * 4. {@link PrimitiveFieldDef} → `PrimitiveTypeMap[type]`
+ * 1. {@link DiscriminatedUnionFieldDef} → `InferDiscriminatedUnion<F>`
+ * 2. {@link ArrayFieldDef} → `Array<InferFieldDef<items>>`
+ * 3. {@link ObjectFieldDef} → `InferObjectSchema<fields>`
+ * 4. {@link EnumFieldDef} → `values[number]` (string literal union)
+ * 5. {@link PrimitiveFieldDef} → `PrimitiveTypeMap[type]`
  */
-export type InferFieldDef<F extends FieldDef> = F extends ArrayFieldDef ? Array<InferFieldDef<F["items"]>> : F extends ObjectFieldDef ? InferObjectSchema<F["fields"]> : F extends EnumFieldDef ? F["values"][number] : F extends PrimitiveFieldDef ? PrimitiveTypeMap[F["type"]] : never;
+export type InferFieldDef<F extends FieldDef> = F extends DiscriminatedUnionFieldDef ? InferDiscriminatedUnion<F> : F extends ArrayFieldDef ? Array<InferFieldDef<F["items"]>> : F extends ObjectFieldDef ? InferObjectSchema<F["fields"]> : F extends EnumFieldDef ? F["values"][number] : F extends PrimitiveFieldDef ? PrimitiveTypeMap[F["type"]] : never;
 /**
  * Infers the TypeScript type from an {@link ObjectSchema} definition.
  *

package/dist/src/decorators/attributes/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,gBAAgB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,IAAI,EAAE,kBAAkB,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,QAAQ,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,IAAI,EAAE,OAAO,CAAC;IACd,oEAAoE;IACpE,KAAK,EAAE,QAAQ,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAChB,iBAAiB,GACjB,YAAY,GACZ,cAAc,GACd,aAAa,GACb,YAAY,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS,aAAa,GACnE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAChC,CAAC,SAAS,cAAc,GACtB,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAC9B,CAAC,SAAS,YAAY,GACpB,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GACnB,CAAC,SAAS,iBAAiB,GACzB,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAC3B,KAAK,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,YAAY,IAAI;KACrD,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,KAAK,GAAG,CAAC,GAAG,aAAa,CAC1E,CAAC,CAAC,CAAC,CAAC,CACL;CACF,GAAG;KACD,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,aAAa,CAC3E,CAAC,CAAC,CAAC,CAAC,CACL;CACF,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/types.ts"],"names":[],"mappings":"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"}

package/dist/src/operations/utils/flattenObjectForUpdate.d.ts

@@ -8,7 +8,8 @@ import type { DocumentPathOperation } from "./types";
  * - `undefined` → skip (not being updated)
  * - `null` → REMOVE operation
  * - Nested object (`fieldDef.type === "object"`) → recurse, prepending parent path
- * - Everything else (primitives, arrays, dates, enums) → serialize and SET
+ * - Everything else (primitives, arrays, dates, enums, discriminated unions) → serialize and SET
+ *
  *
  * @param parentPath Path segments leading to this object (e.g. ["address"] or ["address", "geo"])
  * @param schema The ObjectSchema describing the object shape

package/dist/src/operations/utils/flattenObjectForUpdate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flattenObjectForUpdate.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/flattenObjectForUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,qBAAqB,EAAE,CAmCzB"}
+{"version":3,"file":"flattenObjectForUpdate.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/flattenObjectForUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,qBAAqB,EAAE,CAkCzB"}

package/dist/src/operations/utils/flattenObjectForUpdate.js

@@ -10,7 +10,8 @@ const serializers_1 = require("../../decorators/attributes/serializers");
  * - `undefined` → skip (not being updated)
  * - `null` → REMOVE operation
  * - Nested object (`fieldDef.type === "object"`) → recurse, prepending parent path
- * - Everything else (primitives, arrays, dates, enums) → serialize and SET
+ * - Everything else (primitives, arrays, dates, enums, discriminated unions) → serialize and SET
+ *
  *
  * @param parentPath Path segments leading to this object (e.g. ["address"] or ["address", "geo"])
  * @param schema The ObjectSchema describing the object shape
@@ -37,7 +38,6 @@ function flattenObjectForUpdate(parentPath, schema, partialValue) {
             ops.push(...nestedOps);
             continue;
         }
-        // Primitives, arrays, dates, enums → serialize and SET
         const serialized = (0, serializers_1.convertFieldToTableItem)(fieldDef, val);
         ops.push({ type: "set", path: fieldPath, value: serialized });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dyna-record",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Typescript Data Modeler and ORM for Dynamo",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",