dyna-record 0.4.11 → 0.5.0

package/README.md

@@ -22,6 +22,7 @@ Note: ACID compliant according to DynamoDB [limitations](https://docs.aws.amazon
   - [Query](#query)
     - [Filtering on Object Attributes](#filtering-on-object-attributes)
   - [Update](#update)
+    - [Updating Object Attributes](#updating-object-attributes)
   - [Delete](#delete)
 - [Type Safety Features](#type-safety-features)
 - [Best Practices](#best-practices)
@@ -197,18 +198,15 @@ const addressSchema = {
 class Store extends MyTable {
   @ObjectAttribute({ alias: "Address", schema: addressSchema })
   public readonly address: InferObjectSchema<typeof addressSchema>;
-
-  @ObjectAttribute({ alias: "Metadata", schema: metaSchema, nullable: true })
-  public readonly metadata?: InferObjectSchema<typeof metaSchema>;
 }
 ```
 
 - **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`)
-- **Nullable fields:** Set `nullable: true` on individual fields within the schema to remove them
-- **Nullable object attributes:** Set `nullable: true` on the decorator options to make the entire object optional
+- **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
 - **Storage:** Objects are stored as native DynamoDB Map types
-- **Updates:** Updates replace the entire object (not a partial merge)
+- **Partial updates:** Updates are partial — only the fields you provide are modified. Omitted fields are preserved. Nested objects are recursively merged. See [Updating Object Attributes](#updating-object-attributes)
 - **Filtering:** Object attributes support dot-path filtering in queries — see [Filtering on Object Attributes](#filtering-on-object-attributes)
 
 ##### Enum fields
@@ -696,6 +694,55 @@ await Pet.update("123", {
 });
 ```
 
+#### Updating Object Attributes
+
+Object attribute updates are **partial** — only the fields you provide are modified, and omitted fields are preserved. This uses DynamoDB document path expressions under the hood (e.g., `SET #address.#street = :address_street`) for efficient field-level updates.
+
+```typescript
+// Only updates street — city, zip, geo, etc. are preserved
+await Store.update("123", {
+  address: { street: "456 New St" }
+});
+```
+
+**Nested objects** are recursively merged:
+
+```typescript
+// Only updates lat — lng and accuracy are preserved
+await Store.update("123", {
+  address: {
+    geo: { lat: 42 }
+  }
+});
+```
+
+**Nullable fields** within the object can be removed by setting them to `null`:
+
+```typescript
+// Removes zip, preserves all other fields
+await Store.update("123", {
+  address: { zip: null }
+});
+```
+
+**Arrays** within objects are **full replacement** (not merged):
+
+```typescript
+// Replaces the entire tags array
+await Store.update("123", {
+  address: { tags: ["new-tag-1", "new-tag-2"] }
+});
+```
+
+The instance `update` method returns a deep-merged result, preserving existing fields:
+
+```typescript
+const updated = await storeInstance.update({
+  address: { street: "New Street" }
+});
+// updated.address.city → still has the original value
+```
+
 #### Instance Method
 
 There is an instance `update` method that has the same rules above, but returns the full updated instance.

package/dist/src/DynaRecord.d.ts

@@ -231,12 +231,21 @@ declare abstract class DynaRecord implements DynaRecordBase {
      *   { referentialIntegrityCheck: false }
      * );
      * ```
+     *
+     * @example Partial update of an ObjectAttribute (only provided fields are modified, omitted fields are preserved)
+     * ```typescript
+     * await User.update("userId", { address: { street: "456 Oak Ave" } });
+     * ```
      */
     static update<T extends DynaRecord>(this: EntityClass<T>, id: string, attributes: UpdateOptions<T>, options?: {
         referentialIntegrityCheck?: boolean;
     }): Promise<void>;
     /**
-     *  Same as the static `update` method but on an instance. Returns the full updated instance
+     *  Same as the static `update` method but on an instance. Returns the full updated instance.
+     *
+     * For `@ObjectAttribute` fields, the returned instance deep merges the partial update
+     * with the existing object value — omitted fields are preserved, and fields set to `null`
+     * are removed.
      *
      * @example Updating an entity.
      * ```typescript
@@ -248,6 +257,13 @@ declare abstract class DynaRecord implements DynaRecordBase {
      * const updatedInstance = await instance.update({ email: "newemail@example.com", someKey: null });
      * ```
      *
+     * @example Partial ObjectAttribute update with deep merge
+     * ```typescript
+     * // instance.address is { street: "123 Main", city: "Springfield", zip: 12345 }
+     * const updated = await instance.update({ address: { street: "456 Oak Ave" } });
+     * // updated.address is { street: "456 Oak Ave", city: "Springfield", zip: 12345 }
+     * ```
+     *
      * @example With referential integrity check disabled
      * ```typescript
      * const updatedInstance = await instance.update(

package/dist/src/DynaRecord.d.ts.map

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

package/dist/src/DynaRecord.js

@@ -70,7 +70,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const metadata_1 = __importStar(require("./metadata"));
 const decorators_1 = require("./decorators");
 const operations_1 = require("./operations");
-const utils_1 = require("./utils");
+const utils_1 = require("./operations/utils");
+const utils_2 = require("./utils");
 /**
  * Serves as an abstract base class for entities in the ORM system. It defines standard fields such as `id`, `type`, `createdAt`, and `updatedAt`, and provides static methods for CRUD operations and queries. This class encapsulates common behaviors and properties that all entities share, leveraging decorators for attribute metadata and supporting operations like finding, creating, updating, and deleting entities.
  *
@@ -195,13 +196,22 @@ let DynaRecord = (() => {
          *   { referentialIntegrityCheck: false }
          * );
          * ```
+         *
+         * @example Partial update of an ObjectAttribute (only provided fields are modified, omitted fields are preserved)
+         * ```typescript
+         * await User.update("userId", { address: { street: "456 Oak Ave" } });
+         * ```
          */
         static async update(id, attributes, options) {
             const op = new operations_1.Update(this);
             await op.run(id, attributes, options);
         }
         /**
-         *  Same as the static `update` method but on an instance. Returns the full updated instance
+         *  Same as the static `update` method but on an instance. Returns the full updated instance.
+         *
+         * For `@ObjectAttribute` fields, the returned instance deep merges the partial update
+         * with the existing object value — omitted fields are preserved, and fields set to `null`
+         * are removed.
          *
          * @example Updating an entity.
          * ```typescript
@@ -213,6 +223,13 @@ let DynaRecord = (() => {
          * const updatedInstance = await instance.update({ email: "newemail@example.com", someKey: null });
          * ```
          *
+         * @example Partial ObjectAttribute update with deep merge
+         * ```typescript
+         * // instance.address is { street: "123 Main", city: "Springfield", zip: 12345 }
+         * const updated = await instance.update({ address: { street: "456 Oak Ave" } });
+         * // updated.address is { street: "456 Oak Ave", city: "Springfield", zip: 12345 }
+         * ```
+         *
          * @example With referential integrity check disabled
          * ```typescript
          * const updatedInstance = await instance.update(
@@ -226,11 +243,12 @@ let DynaRecord = (() => {
             const op = new operations_1.Update(InstanceClass);
             const updatedAttributes = await op.run(this.id, attributes, options);
             const clone = structuredClone(this);
-            // Update the current instance with new attributes
-            Object.assign(clone, updatedAttributes);
+            const entityAttrs = metadata_1.default.getEntityAttributes(InstanceClass.name);
+            // Deep merge ObjectAttributes, shallow assign everything else
+            (0, utils_1.mergePartialObjectAttributes)(clone, updatedAttributes, entityAttrs);
             const updatedInstance = Object.fromEntries(Object.entries(clone).filter(([_, value]) => value !== null));
             // Return the updated instance, which is of type `this`
-            return (0, utils_1.createInstance)(InstanceClass, updatedInstance);
+            return (0, utils_2.createInstance)(InstanceClass, updatedInstance);
         }
         /**
          * Delete an entity by ID
@@ -270,7 +288,7 @@ let DynaRecord = (() => {
             if (tableItem[typeAlias] !== this.name) {
                 throw new Error("Unable to convert dynamo item to entity. Invalid type");
             }
-            return (0, utils_1.tableItemToEntity)(this, tableItem);
+            return (0, utils_2.tableItemToEntity)(this, tableItem);
         }
         /**
          * Get the partition key for an entity

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

@@ -1,11 +1,17 @@
 import type DynaRecord from "../../DynaRecord";
-import type { AttributeDecoratorContext, AttributeOptions } from "../types";
+import type { AttributeDecoratorContext, NonNullAttributeOptions } from "../types";
 import type { ObjectSchema, InferObjectSchema } from "./types";
 /**
  * Options for the `@ObjectAttribute` decorator.
- * Extends {@link AttributeOptions} with a required `schema` field describing the object shape.
+ * Extends {@link NonNullAttributeOptions} with a required `schema` field describing the object shape.
+ *
+ * **Object attributes are never nullable.** DynamoDB cannot update nested document paths
+ * (e.g. `address.geo.lat`) if the parent object does not exist, which causes:
+ * `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.
+ * Non-object fields within the schema may still be nullable.
  *
  * @template S The specific ObjectSchema type used for type inference
  *
@@ -13,12 +19,9 @@ import type { ObjectSchema, InferObjectSchema } from "./types";
  * ```typescript
  * @ObjectAttribute({ alias: "Address", schema: addressSchema })
  * public readonly address: InferObjectSchema<typeof addressSchema>;
- *
- * @ObjectAttribute({ alias: "Meta", schema: metaSchema, nullable: true })
- * public readonly meta?: InferObjectSchema<typeof metaSchema>;
  * ```
  */
-export interface ObjectAttributeOptions<S extends ObjectSchema> extends AttributeOptions {
+export interface ObjectAttributeOptions<S extends ObjectSchema> extends NonNullAttributeOptions {
     /**
      * The {@link ObjectSchema} defining the structure of the object attribute.
      *
@@ -32,21 +35,28 @@ export interface ObjectAttributeOptions<S extends ObjectSchema> extends Attribut
  * Objects are stored as native DynamoDB Map types and validated at runtime against the provided schema.
  * The TypeScript type is inferred from the schema using {@link InferObjectSchema}.
  *
- * Can be set to nullable via decorator props.
+ * **Object attributes are never nullable.** DynamoDB cannot update nested document paths
+ * (e.g. `address.geo.lat`) if the parent object does not exist, which causes:
+ * `ValidationException: The document path provided in the update expression is invalid for update`.
+ * To prevent this, `@ObjectAttribute` fields must always exist as at least an empty object `{}`.
+ * Similarly, nested object fields within the schema cannot be nullable.
  *
  * **Supported field types within the schema:**
- * - `"string"`, `"number"`, `"boolean"` — primitives
- * - `"enum"` — string literal unions, validated at runtime via `z.enum()`
- * - `"object"` — nested objects (arbitrarily deep)
- * - `"array"` — lists of any field type
+ * - `"string"`, `"number"`, `"boolean"` — primitives (support `nullable: true`)
+ * - `"enum"` — string literal unions (support `nullable: true`)
+ * - `"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)
  *
- * All field types support `nullable: true` to remove them
+ * 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
+ * are not supported.
  *
  * @template T The class type that the decorator is applied to
  * @template S The ObjectSchema type used for validation and type inference
  * @template K The inferred TypeScript type from the schema
  * @template P The decorator options type
- * @param props An {@link ObjectAttributeOptions} object providing the `schema` and optional `alias` and `nullable` configuration.
+ * @param props An {@link ObjectAttributeOptions} object providing the `schema` and optional `alias`.
  * @returns A class field decorator function
  *
  * Usage example:
@@ -69,9 +79,6 @@ export interface ObjectAttributeOptions<S extends ObjectSchema> extends Attribut
  * class MyEntity extends MyTable {
  *   @ObjectAttribute({ alias: 'Address', schema: addressSchema })
  *   public address: InferObjectSchema<typeof addressSchema>;
- *
- *   @ObjectAttribute({ alias: 'Meta', schema: metaSchema, nullable: true })
- *   public meta?: InferObjectSchema<typeof metaSchema>;
  * }
  *
  * // TypeScript infers:
@@ -79,6 +86,22 @@ export interface ObjectAttributeOptions<S extends ObjectSchema> extends Attribut
  * // address.geo.accuracy → "precise" | "approximate"
  * ```
  *
+ * **Partial updates:** When updating an entity, `@ObjectAttribute` fields support partial
+ * updates — only the fields you provide are modified, omitted fields are preserved. Under
+ * the hood, dyna-record generates DynamoDB document path expressions
+ * (e.g., `SET #address.#street = :address_street`) instead of replacing the entire map.
+ * Nested objects are recursively merged. Arrays within objects are full replacement.
+ * Setting a nullable field within an object to `null` generates a `REMOVE` expression
+ * for that specific field.
+ *
+ * ```typescript
+ * // Only updates street — city, zip, geo are preserved
+ * await MyEntity.update("id", { address: { street: "456 Oak Ave" } });
+ *
+ * // Remove a nullable field within the object
+ * await MyEntity.update("id", { address: { zip: null } });
+ * ```
+ *
  * Object attributes support filtering in queries using dot-path notation for nested fields
  * and the {@link ContainsFilter | $contains} operator for List membership checks.
  *
@@ -92,6 +115,6 @@ export interface ObjectAttributeOptions<S extends ObjectSchema> extends Attribut
  * });
  * ```
  */
-declare function ObjectAttribute<T extends DynaRecord, const S extends ObjectSchema, P extends ObjectAttributeOptions<S>>(props: P): (_value: undefined, context: AttributeDecoratorContext<T, InferObjectSchema<S>, P>) => void;
+declare function ObjectAttribute<T extends DynaRecord, const S extends ObjectSchema>(props: ObjectAttributeOptions<S>): (_value: undefined, context: AttributeDecoratorContext<T, InferObjectSchema<S>, ObjectAttributeOptions<S>>) => void;
 export default ObjectAttribute;
 //# sourceMappingURL=ObjectAttribute.d.ts.map

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,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAY,MAAM,SAAS,CAAC;AAGzE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,YAAY,CAC5D,SAAQ,gBAAgB;IACxB;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;CACX;AAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,iBAAS,eAAe,CACtB,CAAC,SAAS,UAAU,EACpB,KAAK,CAAC,CAAC,SAAS,YAAY,EAC5B,CAAC,SAAS,sBAAsB,CAAC,CAAC,CAAC,EACnC,KAAK,EAAE,CAAC,YAEE,SAAS,WACR,yBAAyB,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,UAkBjE;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,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;AA8GD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,UAqBJ;AAED,eAAe,eAAe,CAAC"}

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

@@ -6,6 +6,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const zod_1 = require("zod");
 const metadata_1 = __importDefault(require("../../metadata"));
 const serializers_1 = require("./serializers");
+/**
+ * Converts an {@link ObjectSchema} to a partial Zod schema for update validation.
+ *
+ * All fields become optional (can be omitted). Nullable fields accept `null`.
+ * Non-nullable fields reject `null`. Nested objects are recursively partial.
+ * Array items validate normally (full replacement).
+ *
+ * @param schema The object schema definition
+ * @returns A ZodType that validates partial objects matching the schema
+ */
+function objectSchemaToZodPartial(schema) {
+    const shape = {};
+    for (const [key, fieldDef] of Object.entries(schema)) {
+        shape[key] = fieldDefToZodPartial(fieldDef);
+    }
+    return zod_1.z.object(shape).partial();
+}
+/**
+ * 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 `{}`.
+ */
+function fieldDefToZodPartial(fieldDef) {
+    if (fieldDef.type === "object") {
+        return objectSchemaToZodPartial(fieldDef.fields);
+    }
+    // For non-object fields, use the standard schema (includes nullable wrapping)
+    return fieldDefToZod(fieldDef);
+}
 /**
  * Converts an {@link ObjectSchema} to a Zod schema for runtime validation.
  *
@@ -23,24 +52,26 @@ function objectSchemaToZod(schema) {
  * 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"` → recursively builds a `z.object()` via {@link objectSchemaToZod}.
+ *   Object fields are never nullable — DynamoDB requires them to exist for document path updates.
  * - `"array"` → `z.array()` wrapping a recursive call for the `items` type
  * - `"string"` → `z.string()`
  * - `"number"` → `z.number()`
  * - `"boolean"` → `z.boolean()`
  * - `"enum"` → `z.enum(values)` for string literal validation
  *
- * When `nullable` is `true`, wraps the type with `.optional().nullable()`.
+ * When `nullable` is `true` (non-object fields only), wraps the type with `.optional().nullable()`.
  *
  * @param fieldDef The field definition to convert
  * @returns A ZodType that validates values matching the field definition
  */
 function fieldDefToZod(fieldDef) {
+    // Object fields return early — they are never nullable
+    if (fieldDef.type === "object") {
+        return objectSchemaToZod(fieldDef.fields);
+    }
     let zodType;
     switch (fieldDef.type) {
-        case "object":
-            zodType = objectSchemaToZod(fieldDef.fields);
-            break;
         case "array":
             zodType = zod_1.z.array(fieldDefToZod(fieldDef.items));
             break;
@@ -76,21 +107,28 @@ function fieldDefToZod(fieldDef) {
  * Objects are stored as native DynamoDB Map types and validated at runtime against the provided schema.
  * The TypeScript type is inferred from the schema using {@link InferObjectSchema}.
  *
- * Can be set to nullable via decorator props.
+ * **Object attributes are never nullable.** DynamoDB cannot update nested document paths
+ * (e.g. `address.geo.lat`) if the parent object does not exist, which causes:
+ * `ValidationException: The document path provided in the update expression is invalid for update`.
+ * To prevent this, `@ObjectAttribute` fields must always exist as at least an empty object `{}`.
+ * Similarly, nested object fields within the schema cannot be nullable.
  *
  * **Supported field types within the schema:**
- * - `"string"`, `"number"`, `"boolean"` — primitives
- * - `"enum"` — string literal unions, validated at runtime via `z.enum()`
- * - `"object"` — nested objects (arbitrarily deep)
- * - `"array"` — lists of any field type
+ * - `"string"`, `"number"`, `"boolean"` — primitives (support `nullable: true`)
+ * - `"enum"` — string literal unions (support `nullable: true`)
+ * - `"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)
  *
- * All field types support `nullable: true` to remove them
+ * 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
+ * are not supported.
  *
  * @template T The class type that the decorator is applied to
  * @template S The ObjectSchema type used for validation and type inference
  * @template K The inferred TypeScript type from the schema
  * @template P The decorator options type
- * @param props An {@link ObjectAttributeOptions} object providing the `schema` and optional `alias` and `nullable` configuration.
+ * @param props An {@link ObjectAttributeOptions} object providing the `schema` and optional `alias`.
  * @returns A class field decorator function
  *
  * Usage example:
@@ -113,9 +151,6 @@ function fieldDefToZod(fieldDef) {
  * class MyEntity extends MyTable {
  *   @ObjectAttribute({ alias: 'Address', schema: addressSchema })
  *   public address: InferObjectSchema<typeof addressSchema>;
- *
- *   @ObjectAttribute({ alias: 'Meta', schema: metaSchema, nullable: true })
- *   public meta?: InferObjectSchema<typeof metaSchema>;
  * }
  *
  * // TypeScript infers:
@@ -123,6 +158,22 @@ function fieldDefToZod(fieldDef) {
  * // address.geo.accuracy → "precise" | "approximate"
  * ```
  *
+ * **Partial updates:** When updating an entity, `@ObjectAttribute` fields support partial
+ * updates — only the fields you provide are modified, omitted fields are preserved. Under
+ * the hood, dyna-record generates DynamoDB document path expressions
+ * (e.g., `SET #address.#street = :address_street`) instead of replacing the entire map.
+ * Nested objects are recursively merged. Arrays within objects are full replacement.
+ * Setting a nullable field within an object to `null` generates a `REMOVE` expression
+ * for that specific field.
+ *
+ * ```typescript
+ * // Only updates street — city, zip, geo are preserved
+ * await MyEntity.update("id", { address: { street: "456 Oak Ave" } });
+ *
+ * // Remove a nullable field within the object
+ * await MyEntity.update("id", { address: { zip: null } });
+ * ```
+ *
  * Object attributes support filtering in queries using dot-path notation for nested fields
  * and the {@link ContainsFilter | $contains} operator for List membership checks.
  *
@@ -142,12 +193,15 @@ function ObjectAttribute(props) {
             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(),
-                    nullable: props?.nullable,
                     type: zodSchema,
+                    partialType: partialZodSchema,
                     serializers,
+                    nullable: false,
+                    objectSchema: schema,
                     ...restProps
                 });
             });

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

@@ -1,5 +1,5 @@
 import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb";
-import type { ObjectSchema } from "./types";
+import type { ObjectSchema, FieldDef } from "./types";
 import type { Serializers } from "../../metadata/types";
 /**
  * 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.
@@ -29,6 +29,7 @@ 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>;
+export declare function convertFieldToTableItem(fieldDef: FieldDef, val: unknown): unknown;
 /**
  * Recursively walks an {@link ObjectSchema} and converts a DynamoDB table item
  * back to its entity representation.

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,EAAY,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;6BACA,oBAAoB;6BAMpB,IAAI;CAC9B,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;AAiBD;;;;;;;;;;;;;;;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;6BAMpB,IAAI;CAC9B,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"}

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dateSerializer = void 0;
 exports.objectToTableItem = objectToTableItem;
+exports.convertFieldToTableItem = convertFieldToTableItem;
 exports.tableItemToObject = tableItemToObject;
 exports.createObjectSerializer = createObjectSerializer;
 /**

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

@@ -45,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 = {
@@ -52,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;
@@ -63,8 +73,6 @@ export interface ObjectFieldDef {
     type: "object";
     /** The nested {@link ObjectSchema} describing the object's shape. */
     fields: ObjectSchema;
-    /** When `true`, the field becomes optional. */
-    nullable?: boolean;
 }
 /**
  * A schema field definition for an array/list type.
@@ -214,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 (`T | undefined`)
+ * - Object fields are always required because DynamoDB cannot update nested document paths
+ *   if an intermediate object does not exist
  *
  * @example
  * ```typescript
@@ -239,8 +249,12 @@ export type InferFieldDef<F extends FieldDef> = F extends ArrayFieldDef ? Array<
  * ```
  */
 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]>;
+    [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;;;;;;;;;;;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;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,QAAQ,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;IACrB,+CAA+C;IAC/C,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,+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;CACF,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

@@ -13,12 +13,14 @@ type NullableProperties<T> = {
  * Recursively resolves the value type for `AllowNullForNullable`.
  *
  * For plain object types (not `Date`, arrays, primitives, or functions),
- * recurses via {@link AllowNullForNullable} so that nullable fields within
- * object schemas (e.g. `@ObjectAttribute`) also receive `| null` during updates.
+ * 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> ? AllowNullForNullable<T> : T;
+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.
  *
@@ -33,13 +35,21 @@ type AllowNullForNullable<T> = {
     [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;;;;;;;;GAQG;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,oBAAoB,CAAC,CAAC,CAAC,GACvB,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;;;;;;;;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

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

@@ -0,0 +1,19 @@
+import type { ObjectSchema } from "../../decorators/attributes/types";
+import type { DocumentPathOperation } from "./types";
+/**
+ * Flattens a partial object value into document path operations for DynamoDB
+ * update expressions.
+ *
+ * For each field in the partial value:
+ * - `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
+ *
+ * @param parentPath Path segments leading to this object (e.g. ["address"] or ["address", "geo"])
+ * @param schema The ObjectSchema describing the object shape
+ * @param partialValue The partial object value to flatten
+ * @returns Array of DocumentPathOperation for use in expressionBuilder
+ */
+export declare function flattenObjectForUpdate(parentPath: string[], schema: ObjectSchema, partialValue: Record<string, unknown>): DocumentPathOperation[];
+//# sourceMappingURL=flattenObjectForUpdate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flattenObjectForUpdate.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/flattenObjectForUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,mCAAmC,CAAC;AAEhF,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"}

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

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenObjectForUpdate = flattenObjectForUpdate;
+const serializers_1 = require("../../decorators/attributes/serializers");
+/**
+ * Flattens a partial object value into document path operations for DynamoDB
+ * update expressions.
+ *
+ * For each field in the partial value:
+ * - `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
+ *
+ * @param parentPath Path segments leading to this object (e.g. ["address"] or ["address", "geo"])
+ * @param schema The ObjectSchema describing the object shape
+ * @param partialValue The partial object value to flatten
+ * @returns Array of DocumentPathOperation for use in expressionBuilder
+ */
+function flattenObjectForUpdate(parentPath, schema, partialValue) {
+    const ops = [];
+    for (const [key, val] of Object.entries(partialValue)) {
+        const fieldDef = schema[key];
+        if (fieldDef === undefined)
+            continue;
+        const fieldPath = [...parentPath, key];
+        if (val === undefined) {
+            continue;
+        }
+        if (val === null) {
+            ops.push({ type: "remove", path: fieldPath });
+            continue;
+        }
+        if (fieldDef.type === "object") {
+            // Recurse into nested objects
+            const nestedOps = flattenObjectForUpdate(fieldPath, fieldDef.fields, val);
+            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 });
+    }
+    return ops;
+}

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

@@ -1,4 +1,6 @@
 export * from "./expressionBuilder";
+export * from "./flattenObjectForUpdate";
+export * from "./mergePartialObjectAttributes";
 export * from "./types";
 export * from "./utils";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC"}

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

@@ -15,5 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./expressionBuilder"), exports);
+__exportStar(require("./flattenObjectForUpdate"), exports);
+__exportStar(require("./mergePartialObjectAttributes"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./utils"), exports);

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

@@ -0,0 +1,8 @@
+import type { AttributeMetadataStorage } from "../../metadata";
+/**
+ * Deep merges partial ObjectAttribute updates into the target object.
+ * For ObjectAttribute fields: recursively merges using the schema, removing null fields.
+ * For regular fields: shallow assigns (existing behavior).
+ */
+export declare function mergePartialObjectAttributes(target: Record<string, unknown>, partial: Record<string, unknown>, entityAttrs: AttributeMetadataStorage): void;
+//# sourceMappingURL=mergePartialObjectAttributes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mergePartialObjectAttributes.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/mergePartialObjectAttributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAG/D;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,WAAW,EAAE,wBAAwB,GACpC,IAAI,CAiBN"}

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

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergePartialObjectAttributes = mergePartialObjectAttributes;
+/**
+ * Deep merges partial ObjectAttribute updates into the target object.
+ * For ObjectAttribute fields: recursively merges using the schema, removing null fields.
+ * For regular fields: shallow assigns (existing behavior).
+ */
+function mergePartialObjectAttributes(target, partial, entityAttrs) {
+    for (const [key, val] of Object.entries(partial)) {
+        const attrMeta = entityAttrs[key];
+        if (attrMeta?.objectSchema !== undefined) {
+            // Deep merge for ObjectAttribute (objects are never nullable)
+            const existing = target[key] ?? {};
+            target[key] = deepMergeObject(existing, val, attrMeta.objectSchema);
+        }
+        else {
+            target[key] = val;
+        }
+    }
+}
+/**
+ * Recursively deep merges a partial object into an existing object using the schema
+ * to determine which fields are nested objects (and should be recursed) vs leaf values
+ * (which should be overwritten).
+ * - null values cause the key to be deleted
+ * - object-type fields per the schema are recursed
+ * - everything else (primitives, arrays, dates, enums) is overwritten
+ */
+function deepMergeObject(existing, partial, schema) {
+    const result = {};
+    // Copy existing keys, skipping those being nulled
+    for (const [key, val] of Object.entries(existing)) {
+        if (partial[key] !== null) {
+            result[key] = val;
+        }
+    }
+    // Apply updates in a single pass
+    for (const [key, val] of Object.entries(partial)) {
+        if (val === null || val === undefined) {
+            continue;
+        }
+        const fieldDef = schema[key];
+        if (fieldDef?.type === "object" && typeof existing[key] === "object") {
+            result[key] = deepMergeObject(existing[key] ?? {}, val, fieldDef.fields);
+        }
+        else {
+            result[key] = val;
+        }
+    }
+    return result;
+}

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

@@ -18,4 +18,20 @@ export interface UpdateRemoveExpression {
  * Represents either an update expression for setting new or modifying existing attributes of an item (UpdateSetExpression) or an update expression for removing attributes from an item (UpdateRemoveExpression) in DynamoDB.
  */
 export type UpdateExpression = UpdateSetExpression | UpdateRemoveExpression;
+/**
+ * Represents a single document path operation for partial ObjectAttribute updates.
+ * Used to build DynamoDB document path expressions like `SET #addr.#street = :addr_street`
+ * or `REMOVE #addr.#zip`.
+ */
+export type DocumentPathOperation = {
+    type: "set";
+    /** Path segments, e.g. ["address", "street"] or ["address", "geo", "lat"] */
+    path: string[];
+    /** The serialized value */
+    value: unknown;
+} | {
+    type: "remove";
+    /** Path segments, e.g. ["address", "zip"] */
+    path: string[];
+};
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,EAAE,WAAW,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACtE,wBAAwB,EAAE,WAAW,CACnC,kBAAkB,CAAC,0BAA0B,CAAC,CAC/C,CAAC;IACF,yBAAyB,EAAE,WAAW,CACpC,kBAAkB,CAAC,2BAA2B,CAAC,CAChD,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,WAAW,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACtE,wBAAwB,EAAE,WAAW,CACnC,kBAAkB,CAAC,0BAA0B,CAAC,CAC/C,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/operations/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,EAAE,WAAW,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACtE,wBAAwB,EAAE,WAAW,CACnC,kBAAkB,CAAC,0BAA0B,CAAC,CAC/C,CAAC;IACF,yBAAyB,EAAE,WAAW,CACpC,kBAAkB,CAAC,2BAA2B,CAAC,CAChD,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,WAAW,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACtE,wBAAwB,EAAE,WAAW,CACnC,kBAAkB,CAAC,0BAA0B,CAAC,CAC/C,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAE5E;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,6EAA6E;IAC7E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC"}

package/package.json

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