dyna-record 0.4.10 → 0.5.0

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

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dateSerializer = void 0;
+exports.objectToTableItem = objectToTableItem;
+exports.convertFieldToTableItem = convertFieldToTableItem;
+exports.tableItemToObject = tableItemToObject;
+exports.createObjectSerializer = createObjectSerializer;
 /**
  * Provides serialization and deserialization functions for date attributes when interfacing with a DynamoDB table, enabling the conversion between the table's string-based date representation and JavaScript's `Date` object. DynamoDb dos not support Date types naturally, this utility allows for Date attributes to be serialized to an entity and stored as ISO strings in Dynamo.
  *
@@ -17,3 +21,98 @@ exports.dateSerializer = {
     },
     toTableAttribute: (val) => val?.toISOString() ?? undefined
 };
+/**
+ * Recursively walks an {@link ObjectSchema} and converts the entity value to its
+ * DynamoDB representation.
+ *
+ * - `"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.
+ * - `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.
+ * - All other field types pass through unchanged.
+ *
+ * @param schema The {@link ObjectSchema} describing the object shape
+ * @param value  The entity-level object value to convert
+ * @returns A new object suitable for DynamoDB storage
+ */
+function objectToTableItem(schema, value) {
+    const result = {};
+    for (const [key, fieldDef] of Object.entries(schema)) {
+        const val = value[key];
+        if (val === undefined || val === null) {
+            continue;
+        }
+        result[key] = convertFieldToTableItem(fieldDef, val);
+    }
+    return result;
+}
+function convertFieldToTableItem(fieldDef, val) {
+    switch (fieldDef.type) {
+        case "date":
+            return val.toISOString();
+        case "object":
+            return objectToTableItem(fieldDef.fields, val);
+        case "array":
+            return val.map(item => convertFieldToTableItem(fieldDef.items, item));
+        default:
+            return val;
+    }
+}
+/**
+ * Recursively walks an {@link ObjectSchema} and converts a DynamoDB table item
+ * back to its entity representation.
+ *
+ * - `"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.
+ * - `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.
+ * - All other field types pass through unchanged.
+ *
+ * @param schema The {@link ObjectSchema} describing the object shape
+ * @param value  The DynamoDB table item to convert
+ * @returns A new object with entity-level types (e.g. `Date` instead of string)
+ */
+function tableItemToObject(schema, value) {
+    const result = {};
+    for (const [key, fieldDef] of Object.entries(schema)) {
+        const val = value[key];
+        if (val === undefined || val === null) {
+            continue;
+        }
+        result[key] = convertFieldToEntityValue(fieldDef, val);
+    }
+    return result;
+}
+function convertFieldToEntityValue(fieldDef, val) {
+    switch (fieldDef.type) {
+        case "date":
+            return new Date(val);
+        case "object":
+            return tableItemToObject(fieldDef.fields, val);
+        case "array":
+            return val.map(item => convertFieldToEntityValue(fieldDef.items, item));
+        default:
+            return val;
+    }
+}
+/**
+ * Creates a {@link Serializers} pair for an {@link ObjectSchema}.
+ *
+ * The returned serializers handle:
+ * - Converting `Date` fields to/from ISO 8601 strings for DynamoDB storage.
+ * - Stripping `null` and `undefined` values so that nullable fields set to
+ *   `null` during updates are removed from the stored object.
+ *
+ * @param schema The {@link ObjectSchema} describing the object shape
+ * @returns A `Serializers` object with `toTableAttribute` and `toEntityAttribute` functions
+ */
+function createObjectSerializer(schema) {
+    return {
+        toTableAttribute: (val) => objectToTableItem(schema, val),
+        toEntityAttribute: (val) => tableItemToObject(schema, val)
+    };
+}

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

@@ -8,16 +8,18 @@
  * | `"string"`  | `string`        |
  * | `"number"`  | `number`        |
  * | `"boolean"` | `boolean`       |
+ * | `"date"`    | `Date`          |
  */
 export interface PrimitiveTypeMap {
     string: string;
     number: number;
     boolean: boolean;
+    date: Date;
 }
 /**
  * The allowed primitive type strings for object schema fields.
  *
- * Derived from the keys of {@link PrimitiveTypeMap}: `"string" | "number" | "boolean"`.
+ * Derived from the keys of {@link PrimitiveTypeMap}: `"string" | "number" | "boolean" | "date"`.
  */
 export type PrimitiveFieldType = keyof PrimitiveTypeMap;
 /**
@@ -35,7 +37,7 @@ export type PrimitiveFieldType = keyof PrimitiveTypeMap;
 export interface PrimitiveFieldDef {
     /** The primitive type — `"string"`, `"number"`, or `"boolean"`. */
     type: PrimitiveFieldType;
-    /** When `true`, the field accepts `null` and becomes optional (`T | null | undefined`). */
+    /** When `true`, the field becomes optional (`T | undefined`). */
     nullable?: boolean;
 }
 /**
@@ -43,6 +45,15 @@ export interface PrimitiveFieldDef {
  *
  * The `fields` property is itself an {@link ObjectSchema}, enabling arbitrarily deep nesting.
  *
+ * **Object fields are never nullable.** DynamoDB cannot update nested document paths
+ * (e.g. `address.geo.lat`) if an intermediate object does not exist, which causes:
+ * `ValidationException: The document path provided in the update expression is invalid for update`.
+ * To avoid this, object-type fields always exist as at least an empty object `{}`.
+ * Non-object fields within the object may still be nullable.
+ *
+ * Objects within arrays are not subject to this limitation because arrays use full
+ * replacement on update rather than document path expressions.
+ *
  * @example
  * ```typescript
  * const schema = {
@@ -50,7 +61,8 @@ export interface PrimitiveFieldDef {
  *     type: "object",
  *     fields: {
  *       lat: { type: "number" },
- *       lng: { type: "number" }
+ *       lng: { type: "number" },
+ *       notes: { type: "string", nullable: true }
  *     }
  *   }
  * } as const satisfies ObjectSchema;
@@ -61,8 +73,6 @@ export interface ObjectFieldDef {
     type: "object";
     /** The nested {@link ObjectSchema} describing the object's shape. */
     fields: ObjectSchema;
-    /** When `true`, the field accepts `null` and becomes optional. */
-    nullable?: boolean;
 }
 /**
  * A schema field definition for an array/list type.
@@ -83,7 +93,7 @@ export interface ArrayFieldDef {
     type: "array";
     /** A {@link FieldDef} describing the type of each array element. */
     items: FieldDef;
-    /** When `true`, the field accepts `null` and becomes optional. */
+    /** When `true`, the field becomes optional. */
     nullable?: boolean;
 }
 /**
@@ -120,7 +130,7 @@ export interface ArrayFieldDef {
  * type T = InferObjectSchema<typeof schema>;
  * // {
  * //   status: "active" | "inactive";
- * //   category?: "home" | "work" | "other" | null;
+ * //   category?: "home" | "work" | "other";
  * //   geo: { accuracy: "precise" | "approximate" };
  * //   roles: ("admin" | "user" | "guest")[];
  * // }
@@ -138,7 +148,27 @@ export interface EnumFieldDef {
      * Must contain at least one value (enforced by the `[string, ...string[]]` tuple type).
      */
     values: readonly [string, ...string[]];
-    /** When `true`, the field accepts `null` and becomes optional. */
+    /** When `true`, the field becomes optional. */
+    nullable?: boolean;
+}
+/**
+ * A schema field definition for a date type.
+ *
+ * Date fields are stored as ISO 8601 strings in DynamoDB and exposed as
+ * JavaScript `Date` objects on entities, mirroring `@DateAttribute` behavior.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   createdDate: { type: "date" },
+ *   deletedAt: { type: "date", nullable: true }
+ * } as const satisfies ObjectSchema;
+ * ```
+ */
+export interface DateFieldDef {
+    /** Must be `"date"` to indicate a date field. */
+    type: "date";
+    /** When `true`, the field becomes optional (`Date | undefined`). */
     nullable?: boolean;
 }
 /**
@@ -146,13 +176,14 @@ export interface EnumFieldDef {
  *
  * This is the union of all supported field types:
  * - {@link PrimitiveFieldDef} — `"string"`, `"number"`, `"boolean"`
+ * - {@link DateFieldDef} — dates stored as ISO strings, exposed as `Date` objects
  * - {@link ObjectFieldDef} — nested objects via `fields`
  * - {@link ArrayFieldDef} — arrays/lists via `items`
  * - {@link EnumFieldDef} — string literal enums via `values`
  *
  * Each variant is discriminated by the `type` property.
  */
-export type FieldDef = PrimitiveFieldDef | ObjectFieldDef | ArrayFieldDef | EnumFieldDef;
+export type FieldDef = PrimitiveFieldDef | DateFieldDef | ObjectFieldDef | ArrayFieldDef | EnumFieldDef;
 /**
  * Declarative schema for describing the shape of an object attribute.
  *
@@ -191,9 +222,11 @@ export type InferFieldDef<F extends FieldDef> = F extends ArrayFieldDef ? Array<
  *
  * - Primitive fields map to their TS equivalents via {@link PrimitiveTypeMap}
  * - Enum fields become a union of their `values` (`values[number]`)
- * - Nested object fields recurse through `InferObjectSchema`
+ * - Nested object fields recurse through `InferObjectSchema` — always required (never nullable)
  * - Array fields become `T[]` where `T` is inferred from `items`
- * - Fields with `nullable: true` become optional and accept `null` (`T | null | undefined`)
+ * - Fields with `nullable: true` become optional (`T | undefined`)
+ * - Object fields are always required because DynamoDB cannot update nested document paths
+ *   if an intermediate object does not exist
  *
  * @example
  * ```typescript
@@ -211,13 +244,17 @@ export type InferFieldDef<F extends FieldDef> = F extends ArrayFieldDef ? Array<
  * //   status: "active" | "inactive";
  * //   tags: string[];
  * //   geo: { lat: number; lng: number };
- * //   age?: number | null;
+ * //   age?: number;
  * // }
  * ```
  */
 export type InferObjectSchema<S extends ObjectSchema> = {
-    [K in keyof S as S[K]["nullable"] extends true ? never : K]: InferFieldDef<S[K]>;
+    [K in keyof S as S[K] extends {
+        nullable: true;
+    } ? never : K]: InferFieldDef<S[K]>;
 } & {
-    [K in keyof S as S[K]["nullable"] extends true ? K : never]?: InferFieldDef<S[K]> | null;
+    [K in keyof S as S[K] extends {
+        nullable: true;
+    } ? K : never]?: InferFieldDef<S[K]>;
 };
 //# sourceMappingURL=types.d.ts.map

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;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,gBAAgB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,IAAI,EAAE,kBAAkB,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,QAAQ,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,IAAI,EAAE,OAAO,CAAC;IACd,oEAAoE;IACpE,KAAK,EAAE,QAAQ,CAAC;IAChB,kEAAkE;IAClE,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,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAChB,iBAAiB,GACjB,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,YAAY,IAAI;KACrD,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,GAAG,aAAa,CACxE,CAAC,CAAC,CAAC,CAAC,CACL;CACF,GAAG;KACD,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,aAAa,CACzE,CAAC,CAAC,CAAC,CAAC,CACL,GAAG,IAAI;CACT,CAAC"}
+{"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"}

package/dist/src/metadata/AttributeMetadata.d.ts

@@ -2,6 +2,7 @@ import { type ZodType } from "zod";
 import type DynaRecord from "../DynaRecord";
 import type { AttributeMetadataOptions, Serializers } from "./types";
 import type { EntityClass } from "../types";
+import type { ObjectSchema } from "../decorators/attributes/types";
 /**
  * Represents the metadata for an attribute of an entity, including its name, alias (if any), nullability, and serialization strategies.
  *
@@ -23,6 +24,8 @@ declare class AttributeMetadata {
     readonly serializers?: Serializers;
     readonly type: ZodType;
     readonly foreignKeyTarget?: EntityClass<DynaRecord>;
+    readonly objectSchema?: ObjectSchema;
+    readonly partialType?: ZodType;
     constructor(options: AttributeMetadataOptions);
 }
 export default AttributeMetadata;

package/dist/src/metadata/AttributeMetadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AttributeMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/AttributeMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,cAAM,iBAAiB;IACrB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,OAAO,CAAC;IAClC,SAAgB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1C,SAAgB,IAAI,EAAE,OAAO,CAAC;IAC9B,SAAgB,gBAAgB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;gBAE/C,OAAO,EAAE,wBAAwB;CAa9C;AAED,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"AttributeMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/AttributeMetadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAEnE;;;;;;;;;;;;;GAaG;AACH,cAAM,iBAAiB;IACrB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,OAAO,CAAC;IAClC,SAAgB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1C,SAAgB,IAAI,EAAE,OAAO,CAAC;IAC9B,SAAgB,gBAAgB,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAC3D,SAAgB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5C,SAAgB,WAAW,CAAC,EAAE,OAAO,CAAC;gBAE1B,OAAO,EAAE,wBAAwB;CAe9C;AAED,eAAe,iBAAiB,CAAC"}

package/dist/src/metadata/AttributeMetadata.js

@@ -21,17 +21,22 @@ class AttributeMetadata {
     serializers;
     type;
     foreignKeyTarget;
+    objectSchema;
+    partialType;
     constructor(options) {
         this.name = options.attributeName;
         this.alias = options.alias ?? options.attributeName;
         this.nullable = options.nullable ?? false;
         this.serializers = options.serializers;
         this.foreignKeyTarget = options.foreignKeyTarget;
+        this.objectSchema = options.objectSchema;
         if (options.nullable === true) {
             this.type = options.type.optional().nullable();
+            this.partialType = options.partialType?.optional().nullable();
         }
         else {
             this.type = options.type;
+            this.partialType = options.partialType;
         }
     }
 }

package/dist/src/metadata/EntityMetadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntityMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/EntityMetadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,mBAAmB,EACnB,8BAA8B,EAC9B,2BAA2B,EAC5B,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAY7D,KAAK,WAAW,GAAG,KAAK,GAAG,IAAI,EAAE,GAAG,KAAK,UAAU,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,cAAM,cAAc;;IAClB;;OAEG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC;;OAEG;IACH,SAAgB,UAAU,EAAE,wBAAwB,CAAC;IACrD;;OAEG;IACH,SAAgB,eAAe,EAAE,wBAAwB,CAAC;IAE1D;;OAEG;IACH,SAAgB,aAAa,EAAE,2BAA2B,CAAC;IAE3D,SAAgB,WAAW,EAAE,WAAW,CAAC;IAEzC;;OAEG;IACI,OAAO,EAAE,MAAM,CAAC;gBAiBX,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM;IAS5D;;;OAGG;IACI,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAOtD;;;;;OAKG;IACI,+BAA+B,CACpC,UAAU,EAAE,uBAAuB,CAAC,UAAU,CAAC,GAC9C,uBAAuB,CAAC,UAAU,CAAC;IAatC;;;;;;OAMG;IACI,sCAAsC,CAC3C,UAAU,EAAE,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,GACvD,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;IA0B/C;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;IACH,IAAW,gBAAgB,IAAI,oBAAoB,EAAE,CAEpD;IAED;;OAEG;IACH,IAAW,sBAAsB,IAAI,qBAAqB,EAAE,CAI3D;IAED;;OAEG;IACH,IAAW,oBAAoB,IAAI,mBAAmB,EAAE,CAIvD;IAED;;OAEG;IACH,IAAW,+BAA+B,IAAI,8BAA8B,EAAE,CAE7E;IAED;;OAEG;IACH,IAAW,gBAAgB,IAAI,gBAAgB,CAO9C;IAED;;;OAGG;IACH,IAAW,oBAAoB,IAAI,2BAA2B,EAAE,CAE/D;IAED;;;OAGG;IACH,IAAW,8BAA8B,IAAI,2BAA2B,EAAE,CAUzE;CACF;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"EntityMetadata.d.ts","sourceRoot":"","sources":["../../../src/metadata/EntityMetadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,mBAAmB,EACnB,8BAA8B,EAC9B,2BAA2B,EAC5B,MAAM,GAAG,CAAC;AACX,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAY7D,KAAK,WAAW,GAAG,KAAK,GAAG,IAAI,EAAE,GAAG,KAAK,UAAU,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,cAAM,cAAc;;IAClB;;OAEG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC;;OAEG;IACH,SAAgB,UAAU,EAAE,wBAAwB,CAAC;IACrD;;OAEG;IACH,SAAgB,eAAe,EAAE,wBAAwB,CAAC;IAE1D;;OAEG;IACH,SAAgB,aAAa,EAAE,2BAA2B,CAAC;IAE3D,SAAgB,WAAW,EAAE,WAAW,CAAC;IAEzC;;OAEG;IACI,OAAO,EAAE,MAAM,CAAC;gBAuBX,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM;IAS5D;;;OAGG;IACI,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAStD;;;;;OAKG;IACI,+BAA+B,CACpC,UAAU,EAAE,uBAAuB,CAAC,UAAU,CAAC,GAC9C,uBAAuB,CAAC,UAAU,CAAC;IAatC;;;;;;OAMG;IACI,sCAAsC,CAC3C,UAAU,EAAE,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,GACvD,OAAO,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC;IA0B/C;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;IACH,IAAW,gBAAgB,IAAI,oBAAoB,EAAE,CAEpD;IAED;;OAEG;IACH,IAAW,sBAAsB,IAAI,qBAAqB,EAAE,CAI3D;IAED;;OAEG;IACH,IAAW,oBAAoB,IAAI,mBAAmB,EAAE,CAIvD;IAED;;OAEG;IACH,IAAW,+BAA+B,IAAI,8BAA8B,EAAE,CAE7E;IAED;;OAEG;IACH,IAAW,gBAAgB,IAAI,gBAAgB,CAO9C;IAED;;;OAGG;IACH,IAAW,oBAAoB,IAAI,2BAA2B,EAAE,CAE/D;IAED;;;OAGG;IACH,IAAW,8BAA8B,IAAI,2BAA2B,EAAE,CAUzE;CACF;AAED,eAAe,cAAc,CAAC"}

package/dist/src/metadata/EntityMetadata.js

@@ -53,6 +53,11 @@ class EntityMetadata {
      * Object containing zod attributes. Built programmatically via decorators and used to create schemas
      */
     #zodAttributes = {};
+    /**
+     * Object containing zod attributes for partial (update) validation.
+     * ObjectAttributes use their partialType; others use the standard type.
+     */
+    #zodPartialAttributes = {};
     constructor(entityClass, tableClassName) {
         this.EntityClass = entityClass;
         this.tableClassName = tableClassName;
@@ -68,6 +73,8 @@ class EntityMetadata {
         this.attributes[attrMeta.name] = attrMeta;
         this.tableAttributes[attrMeta.alias] = attrMeta;
         this.#zodAttributes[attrMeta.name] = attrMeta.type;
+        this.#zodPartialAttributes[attrMeta.name] =
+            attrMeta.partialType ?? attrMeta.type;
     }
     /**
      * Parse raw entity defined attributes (not reserved/relationship attributes) from input and ensure they are entity defined attributes.
@@ -98,7 +105,7 @@ class EntityMetadata {
         if (this.#schemaPartial === undefined) {
             const tableMeta = _1.default.getTable(this.tableClassName);
             this.#schemaPartial = zod_1.z
-                .object(this.#zodAttributes)
+                .object(this.#zodPartialAttributes)
                 .omit(tableMeta.reservedKeys)
                 .partial()
                 .transform((data) => {

package/dist/src/metadata/types.d.ts

@@ -3,6 +3,7 @@ import type { AttributeMetadata, BelongsToRelationship, EntityMetadata, JoinTabl
 import type DynaRecord from "../DynaRecord";
 import type { EntityClass, MakeOptional } from "../types";
 import type { ZodType } from "zod";
+import type { ObjectSchema } from "../decorators/attributes/types";
 /**
  * Represents relationship metadata that includes a foreign key reference to another entity.
  */
@@ -99,6 +100,16 @@ export interface AttributeMetadataOptions {
      * Used to enforce referential integrity even when a relationship decorator is not present.
      */
     foreignKeyTarget?: EntityClass<DynaRecord>;
+    /**
+     * When the attribute is an ObjectAttribute, stores the original ObjectSchema
+     * for use in partial update operations (document path expressions).
+     */
+    objectSchema?: ObjectSchema;
+    /**
+     * When present, an alternative Zod type used for partial (update) validation.
+     * ObjectAttributes use this to allow partial field updates.
+     */
+    partialType?: ZodType;
 }
 /**
  * A relationship that is either BelongsTo (bi-directional to parent) or OwnedBy (uni directional to parent)

package/dist/src/metadata/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/metadata/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/metadata/types.ts"],"names":[],"mappings":"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"}

package/dist/src/operations/Update/Update.d.ts

@@ -85,7 +85,12 @@ declare class Update<T extends DynaRecord> extends OperationBase<T> {
      *
      * **What it does:**
      * - Merges the provided attributes with `updatedAt` (automatically set to the current time).
-     * - Converts the updated attributes into a DynamoDB update expression.
+     * - For `@ObjectAttribute` fields with non-null values, flattens the partial object into
+     *   {@link DocumentPathOperation | document path operations} (e.g., `SET #address.#street = :address_street`)
+     *   instead of replacing the entire map. Nested objects are recursively flattened.
+     * - For regular attributes and `@ObjectAttribute` fields set to `null`, uses the standard
+     *   expression builder (existing full-replacement / REMOVE behavior).
+     * - Combines both regular and document path expressions into a single DynamoDB update expression.
      *
      * @param attributes - The partial attributes to be updated on the entity.
      * @returns An object containing:

package/dist/src/operations/Update/Update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Update.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/Update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAGL,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAmB5B,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACvB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAmB,WAAW,EAAgB,MAAM,aAAa,CAAC;AA4D9E;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC;gBAG1D,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,kBAAkB,CAAC,EAAE,oBAAoB;IAO3C;;;;;;;;;;;;;;OAcG;IACU,GAAG,CACd,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,CAAC,UAAU,CAAC,EACrC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;cAoDhB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;OAIG;IACH,OAAO,CAAC,uCAAuC;IAY/C;;;;;;OAMG;IACH,OAAO,CAAC,sCAAsC;IAoC9C;;;;;;;;;;;;;;;OAeG;YACW,QAAQ;IAsDtB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;IAY3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAyBlC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,0BAA0B;IA0DlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iCAAiC;IAuBzC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,8BAA8B;IAkCtC;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAkBlC;;;;;OAKG;IACH,OAAO,CAAC,mCAAmC;IAsB3C;;;;;;;;OAQG;IACH,OAAO,CAAC,sCAAsC;IAqC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAuCrC;;;;;;;;;OASG;IACH,OAAO,CAAC,4BAA4B;IAgCpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAwBrC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;OAGG;IACH,OAAO,CAAC,iCAAiC;CAU1C;AAED,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Update.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/Update.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAGL,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAqB5B,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,sBAAsB,EACvB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAmB,WAAW,EAAgB,MAAM,aAAa,CAAC;AA4D9E;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC;gBAG1D,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,kBAAkB,CAAC,EAAE,oBAAoB;IAO3C;;;;;;;;;;;;;;OAcG;IACU,GAAG,CACd,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,CAAC,UAAU,CAAC,EACrC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;cAoDhB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlD;;;;OAIG;IACH,OAAO,CAAC,uCAAuC;IAY/C;;;;;;OAMG;IACH,OAAO,CAAC,sCAAsC;IAoC9C;;;;;;;;;;;;;;;OAeG;YACW,QAAQ;IAsDtB;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IA4B7B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,mBAAmB;IAuC3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAyBlC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,0BAA0B;IA0DlC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iCAAiC;IAuBzC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,8BAA8B;IAkCtC;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAkBlC;;;;;OAKG;IACH,OAAO,CAAC,mCAAmC;IAsB3C;;;;;;;;OAQG;IACH,OAAO,CAAC,sCAAsC;IAqC9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAuCrC;;;;;;;;;OASG;IACH,OAAO,CAAC,4BAA4B;IAgCpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAwBrC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;OAGG;IACH,OAAO,CAAC,iCAAiC;CAU1C;AAED,eAAe,MAAM,CAAC"}

package/dist/src/operations/Update/Update.js

@@ -210,7 +210,12 @@ class Update extends OperationBase_1.default {
      *
      * **What it does:**
      * - Merges the provided attributes with `updatedAt` (automatically set to the current time).
-     * - Converts the updated attributes into a DynamoDB update expression.
+     * - For `@ObjectAttribute` fields with non-null values, flattens the partial object into
+     *   {@link DocumentPathOperation | document path operations} (e.g., `SET #address.#street = :address_street`)
+     *   instead of replacing the entire map. Nested objects are recursively flattened.
+     * - For regular attributes and `@ObjectAttribute` fields set to `null`, uses the standard
+     *   expression builder (existing full-replacement / REMOVE behavior).
+     * - Combines both regular and document path expressions into a single DynamoDB update expression.
      *
      * @param attributes - The partial attributes to be updated on the entity.
      * @returns An object containing:
@@ -223,8 +228,25 @@ class Update extends OperationBase_1.default {
             ...attributes,
             updatedAt: new Date()
         };
-        const tableAttrs = (0, utils_1.entityToTableItem)(this.EntityClass, updatedAttrs);
-        const expression = (0, utils_2.expressionBuilder)(tableAttrs);
+        const entityAttrs = metadata_1.default.getEntityAttributes(this.EntityClass.name);
+        // Separate ObjectAttribute fields (non-null) for document path handling
+        const regularAttrs = {};
+        const allDocumentPathOps = [];
+        for (const [key, val] of Object.entries(updatedAttrs)) {
+            const attrMeta = entityAttrs[key];
+            if (attrMeta?.objectSchema !== undefined) {
+                // ObjectAttribute → flatten for document path updates (objects are never nullable)
+                const alias = attrMeta.alias;
+                const ops = (0, utils_2.flattenObjectForUpdate)([alias], attrMeta.objectSchema, val);
+                allDocumentPathOps.push(...ops);
+            }
+            else {
+                // Regular attribute → existing behavior
+                regularAttrs[key] = val;
+            }
+        }
+        const tableAttrs = (0, utils_1.entityToTableItem)(this.EntityClass, regularAttrs);
+        const expression = (0, utils_2.expressionBuilder)(tableAttrs, allDocumentPathOps);
         return { updatedAttrs, expression };
     }
     /**

package/dist/src/operations/Update/types.d.ts

@@ -9,23 +9,47 @@ import type { EntityDefinedAttributes } from "../types";
 type NullableProperties<T> = {
     [K in keyof T]: undefined extends T[K] ? K : never;
 }[keyof T];
+/**
+ * Recursively resolves the value type for `AllowNullForNullable`.
+ *
+ * For plain object types (not `Date`, arrays, primitives, or functions),
+ * wraps with `Partial<>` and recurses via {@link AllowNullForNullable} so that:
+ * - All fields within `@ObjectAttribute` objects are optional in update payloads,
+ *   matching the partial update semantics (only provided fields are modified).
+ * - Nullable fields at any nesting depth receive `| null` during updates.
+ *
+ * Primitives, `Date`, arrays, and functions pass through unchanged.
+ */
+type AllowNullForNullableValue<T> = T extends Date | readonly unknown[] | string | number | boolean | null | undefined | ((...args: unknown[]) => unknown) ? T : T extends Record<string, unknown> ? Partial<AllowNullForNullable<T>> : T;
 /**
  * Transforms a type `T` by allowing `null` as an additional type for its nullable properties.
  *
+ * Recurses into plain object values (e.g. object schema attributes) so that
+ * nullable fields at any depth receive `| null`, matching root-level nullable
+ * attribute behavior during updates.
+ *
  * @typeParam T - The type whose properties are to be transformed.
  * @returns A new type with properties of `T` where each nullable property is also allowed to be `null`.
  */
 type AllowNullForNullable<T> = {
-    [K in keyof T]: K extends NullableProperties<T> ? T[K] | null : T[K];
+    [K in keyof T]: K extends NullableProperties<T> ? AllowNullForNullableValue<NonNullable<T[K]>> | null | undefined : AllowNullForNullableValue<T[K]>;
 };
 /**
- * Attributes of an entity to update. Not all properties are required. Setting a nullable property to null will remove the attribute from the item
+ * Attributes of an entity to update. Not all properties are required. Setting a nullable property to null will remove the attribute from the item.
+ *
+ * For `@ObjectAttribute` fields, all nested fields are `Partial` — you only need to provide the
+ * fields you want to change. Omitted fields are preserved in DynamoDB via document path expressions.
  *
  * @example
  * await MockModel.update("123", {
  *   nonNullableAttr: "new val", // Sets new value
  *   nullableAttr: null // Remove the value. This will throw a compile time error if the property is not nullable
  * })
+ *
+ * @example Partial ObjectAttribute update
+ * await MockModel.update("123", {
+ *   address: { street: "456 Oak Ave" } // Only updates street, preserves other fields
+ * })
  */
 export type UpdateOptions<T extends DynaRecord> = Partial<AllowNullForNullable<EntityDefinedAttributes<T>>>;
 /**

package/dist/src/operations/Update/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;GAKG;AACH,KAAK,kBAAkB,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACnD,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;;;;GAKG;AACH,KAAK,oBAAoB,CAAC,CAAC,IAAI;KAC5B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;CACrE,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,UAAU,IAAI,OAAO,CACvD,oBAAoB,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,UAAU,IAAI,IAAI,CACxD,OAAO,CAAC,CAAC,CAAC,EACV,WAAW,CACZ,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/operations/Update/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;GAKG;AACH,KAAK,kBAAkB,CAAC,CAAC,IAAI;KAC1B,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACnD,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;;;;;;;;;GAUG;AACH,KAAK,yBAAyB,CAAC,CAAC,IAAI,CAAC,SACjC,IAAI,GACJ,SAAS,OAAO,EAAE,GAClB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GACjC,CAAC,GACD,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,GAChC,CAAC,CAAC;AAER;;;;;;;;;GASG;AACH,KAAK,oBAAoB,CAAC,CAAC,IAAI;KAC5B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,SAAS,kBAAkB,CAAC,CAAC,CAAC,GAC3C,yBAAyB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/D,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,UAAU,IAAI,OAAO,CACvD,oBAAoB,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,UAAU,IAAI,IAAI,CACxD,OAAO,CAAC,CAAC,CAAC,EACV,WAAW,CACZ,CAAC"}

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

@@ -1,9 +1,10 @@
 import type { DynamoTableItem } from "../../types";
-import type { UpdateExpression } from "./types";
+import type { UpdateExpression, DocumentPathOperation } from "./types";
 /**
- * Builds a dynamo expression given the table attributes
+ * Builds a dynamo expression given the table attributes and optional document path operations
  * @param tableAttrs The table aliases of the entity attributes
+ * @param documentPathOps Optional document path operations for partial ObjectAttribute updates
  * @returns
  */
-export declare const expressionBuilder: (tableAttrs: DynamoTableItem) => UpdateExpression;
+export declare const expressionBuilder: (tableAttrs: DynamoTableItem, documentPathOps?: DocumentPathOperation[]) => UpdateExpression;
 //# sourceMappingURL=expressionBuilder.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"expressionBuilder.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/expressionBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAUjB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,eAChB,eAAe,KAC1B,gBAoBF,CAAC"}
+{"version":3,"file":"expressionBuilder.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/expressionBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EACV,gBAAgB,EAGhB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAyBjB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,eAChB,eAAe,oBACT,qBAAqB,EAAE,KACxC,gBAiEF,CAAC"}

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

@@ -2,14 +2,46 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.expressionBuilder = void 0;
 /**
- * Builds a dynamo expression given the table attributes
+ * Builds a dynamo expression given the table attributes and optional document path operations
  * @param tableAttrs The table aliases of the entity attributes
+ * @param documentPathOps Optional document path operations for partial ObjectAttribute updates
  * @returns
  */
-const expressionBuilder = (tableAttrs) => {
+const expressionBuilder = (tableAttrs, documentPathOps) => {
     const sorted = sortAttributesByOperand(tableAttrs);
     const setExpression = buildUpdateSetExpression(sorted.set);
     const removeExpression = buildUpdateRemoveExpression(sorted.remove);
+    // Merge document path operations into the expressions
+    if (documentPathOps !== undefined && documentPathOps.length > 0) {
+        const docPathResult = buildDocumentPathExpressions(documentPathOps);
+        // Merge SET items
+        if (docPathResult.setItems.length > 0) {
+            Object.assign(setExpression.ExpressionAttributeNames, docPathResult.expressionAttributeNames);
+            Object.assign(setExpression.ExpressionAttributeValues, docPathResult.expressionAttributeValues);
+            const existingSet = setExpression.UpdateExpression;
+            const docSetClause = docPathResult.setItems.join(", ");
+            if (existingSet !== "") {
+                // Append to existing SET clause
+                setExpression.UpdateExpression = `${existingSet}, ${docSetClause}`;
+            }
+            else {
+                setExpression.UpdateExpression = `SET ${docSetClause}`;
+            }
+        }
+        // Merge REMOVE items
+        if (docPathResult.removeItems.length > 0) {
+            // Add names used in REMOVE paths
+            Object.assign(removeExpression.ExpressionAttributeNames, docPathResult.expressionAttributeNames);
+            const existingRemove = removeExpression.UpdateExpression;
+            const docRemoveClause = docPathResult.removeItems.join(", ");
+            if (existingRemove !== "") {
+                removeExpression.UpdateExpression = `${existingRemove}, ${docRemoveClause}`;
+            }
+            else {
+                removeExpression.UpdateExpression = `REMOVE ${docRemoveClause}`;
+            }
+        }
+    }
     return {
         // If the operation has only REMOVE actions, it will not have expression attribute values
         ExpressionAttributeValues: setExpression.ExpressionAttributeValues,
@@ -26,6 +58,35 @@ const expressionBuilder = (tableAttrs) => {
     };
 };
 exports.expressionBuilder = expressionBuilder;
+/**
+ * Build document path expressions from DocumentPathOperations
+ */
+const buildDocumentPathExpressions = (ops) => {
+    const result = {
+        setItems: [],
+        removeItems: [],
+        expressionAttributeNames: {},
+        expressionAttributeValues: {}
+    };
+    for (const op of ops) {
+        // Build the document path expression: #segment1.#segment2.#segment3
+        const pathExpr = op.path.map(seg => `#${seg}`).join(".");
+        // Build the value placeholder: :segment1_segment2_segment3
+        const valuePlaceholder = `:${op.path.join("_")}`;
+        // Register all path segment names
+        for (const seg of op.path) {
+            result.expressionAttributeNames[`#${seg}`] = seg;
+        }
+        if (op.type === "set") {
+            result.setItems.push(`${pathExpr} = ${valuePlaceholder}`);
+            result.expressionAttributeValues[valuePlaceholder] = op.value;
+        }
+        else {
+            result.removeItems.push(pathExpr);
+        }
+    }
+    return result;
+};
 /**
  * Sort attributes based on their operand
  * @param tableAttrs