dyna-record 0.4.9 → 0.4.11

package/README.md

@@ -20,6 +20,7 @@ Note: ACID compliant according to DynamoDB [limitations](https://docs.aws.amazon
   - [Create](#create)
   - [FindById](#findbyid)
   - [Query](#query)
+    - [Filtering on Object Attributes](#filtering-on-object-attributes)
   - [Update](#update)
   - [Delete](#delete)
 - [Type Safety Features](#type-safety-features)
@@ -144,6 +145,7 @@ Use the attribute decorators below to define attributes on a model. The decorato
   - [@DateAttribute](https://dyna-record.com/functions/DateAttribute.html)
   - [@EnumAttribute](https://dyna-record.com/functions/EnumAttribute.html)
   - [@IdAttribute](https://dyna-record.com/functions/IdAttribute.html)
+  - [@ObjectAttribute](https://dyna-record.com/functions/ObjectAttribute.html)
 
 - The [alias](https://dyna-record.com/interfaces/AttributeOptions.html#alias) option allows you to specify the attribute name as it appears in the DynamoDB table, different from your class property name.
 - Set nullable attributes as optional for optimal type safety
@@ -165,6 +167,79 @@ class Student extends MyTable {
 }
 ```
 
+#### @ObjectAttribute
+
+Use `@ObjectAttribute` to define structured, typed object attributes on an entity. Objects are validated at runtime and stored as native DynamoDB Map types.
+
+Define the shape using an `ObjectSchema` and derive the TypeScript type with `InferObjectSchema`:
+
+```typescript
+import { Entity, ObjectAttribute } from "dyna-record";
+import type { ObjectSchema, InferObjectSchema } from "dyna-record";
+
+const addressSchema = {
+  street: { type: "string" },
+  city: { type: "string" },
+  zip: { type: "number", nullable: true },
+  tags: { type: "array", items: { type: "string" } },
+  category: { type: "enum", values: ["home", "work", "other"] },
+  createdDate: { type: "date" },
+  geo: {
+    type: "object",
+    fields: {
+      lat: { type: "number" },
+      lng: { type: "number" }
+    }
+  }
+} as const satisfies ObjectSchema;
+
+@Entity
+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
+- **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)
+- **Filtering:** Object attributes support dot-path filtering in queries — see [Filtering on Object Attributes](#filtering-on-object-attributes)
+
+##### Enum fields
+
+Use `{ type: "enum", values: [...] }` to define a field that only accepts specific string values. The TypeScript type is inferred as a union of the provided values, and invalid values are rejected at runtime via Zod validation.
+
+Enum fields can appear at any nesting level — top-level, inside nested objects, or as array items:
+
+```typescript
+const schema = {
+  // Top-level enum: inferred as "active" | "inactive"
+  status: { type: "enum", values: ["active", "inactive"] },
+
+  // Nullable enum: inferred as "home" | "work" | "other" | undefined
+  category: { type: "enum", values: ["home", "work", "other"], nullable: true },
+
+  // Enum inside a nested object
+  geo: {
+    type: "object",
+    fields: {
+      accuracy: { type: "enum", values: ["precise", "approximate"] }
+    }
+  },
+
+  // Array of enum values: inferred as ("admin" | "user")[]
+  roles: { type: "array", items: { type: "enum", values: ["admin", "user"] } }
+} as const satisfies ObjectSchema;
+```
+
+The schema must be declared with `as const satisfies ObjectSchema` so TypeScript preserves the literal string values for type inference. At runtime, providing an invalid value (e.g., `status: "unknown"`) throws a `ValidationError`.
+
 ### Foreign Keys
 
 Define foreign keys in order to support [@BelongsTo](https://dyna-record.com/functions/BelongsTo.html) relationships. A foreign key is required for [@HasOne](https://dyna-record.com/functions/HasOne.html) and [@HasMany](https://dyna-record.com/functions/HasMany.html) relationships.
@@ -496,6 +571,69 @@ const result = await Course.query(
 );
 ```
 
+#### Filtering on Object Attributes
+
+When using `@ObjectAttribute`, you can filter on nested Map fields using **dot-path notation** and check List membership using the **`$contains`** operator.
+
+##### Dot-path filtering on nested fields
+
+Use dot notation to filter on fields within an `@ObjectAttribute`. All standard filter operators work with dot-paths: equality, `$beginsWith`, and `IN` (array of values).
+
+```typescript
+// Equality on a nested field
+const result = await Store.query("123", {
+  filter: { "address.city": "Springfield" }
+});
+
+// $beginsWith on a nested field
+const result = await Store.query("123", {
+  filter: { "address.street": { $beginsWith: "123" } }
+});
+
+// IN on a nested field
+const result = await Store.query("123", {
+  filter: { "address.city": ["Springfield", "Shelbyville"] }
+});
+
+// Deeply nested fields
+const result = await Store.query("123", {
+  filter: { "address.geo.lat": 40 }
+});
+```
+
+##### `$contains` operator
+
+Use `$contains` to check if a List attribute contains a specific element, or if a string attribute contains a substring. Works on both top-level attributes and nested fields via dot-path.
+
+```typescript
+// Check if a List contains an element
+const result = await Store.query("123", {
+  filter: { "address.tags": { $contains: "home" } }
+});
+
+// Check if a top-level string contains a substring
+const result = await Store.query("123", {
+  filter: { name: { $contains: "john" } }
+});
+```
+
+##### Combining dot-path and `$contains` with AND/OR
+
+Dot-path filters and `$contains` work with all existing AND/OR filter combinations.
+
+```typescript
+const result = await Store.query("123", {
+  filter: {
+    "address.city": "Springfield",
+    "address.geo.lat": 40,
+    $or: [
+      { "address.tags": { $contains: "home" } },
+      { name: { $beginsWith: "Main" } }
+    ]
+  }
+});
+```
+
 ### Querying on an index
 
 For querying based on secondary indexes, you can specify the index name in the options.

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

@@ -0,0 +1,97 @@
+import type DynaRecord from "../../DynaRecord";
+import type { AttributeDecoratorContext, AttributeOptions } 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.
+ *
+ * The schema supports all {@link FieldDef} types: primitives, enums, nested objects, and arrays.
+ *
+ * @template S The specific ObjectSchema type used for type inference
+ *
+ * @example
+ * ```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 {
+    /**
+     * The {@link ObjectSchema} defining the structure of the object attribute.
+     *
+     * Must be declared with `as const satisfies ObjectSchema` for accurate type inference.
+     */
+    schema: S;
+}
+/**
+ * A decorator for marking class fields as structured object attributes within the context of a single-table design entity.
+ *
+ * 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.
+ *
+ * **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
+ *
+ * All field types support `nullable: true` to remove them
+ *
+ * @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.
+ * @returns A class field decorator function
+ *
+ * Usage example:
+ * ```typescript
+ * const addressSchema = {
+ *   street: { type: "string" },
+ *   city: { type: "string" },
+ *   zip: { type: "number", nullable: true },
+ *   category: { type: "enum", values: ["home", "work", "other"] },
+ *   geo: {
+ *     type: "object",
+ *     fields: {
+ *       lat: { type: "number" },
+ *       lng: { type: "number" },
+ *       accuracy: { type: "enum", values: ["precise", "approximate"] }
+ *     }
+ *   }
+ * } as const satisfies ObjectSchema;
+ *
+ * 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:
+ * // address.category → "home" | "work" | "other"
+ * // address.geo.accuracy → "precise" | "approximate"
+ * ```
+ *
+ * Object attributes support filtering in queries using dot-path notation for nested fields
+ * and the {@link ContainsFilter | $contains} operator for List membership checks.
+ *
+ * ```typescript
+ * await MyEntity.query("123", {
+ *   filter: { "address.city": "Springfield" }
+ * });
+ *
+ * await MyEntity.query("123", {
+ *   filter: { "address.tags": { $contains: "home" } }
+ * });
+ * ```
+ */
+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;
+export default ObjectAttribute;
+//# sourceMappingURL=ObjectAttribute.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,157 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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 Zod schema for runtime validation.
+ *
+ * @param schema The object schema definition
+ * @returns A ZodType that validates objects matching the schema
+ */
+function objectSchemaToZod(schema) {
+    const shape = {};
+    for (const [key, fieldDef] of Object.entries(schema)) {
+        shape[key] = fieldDefToZod(fieldDef);
+    }
+    return zod_1.z.object(shape);
+}
+/**
+ * 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}
+ * - `"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()`.
+ *
+ * @param fieldDef The field definition to convert
+ * @returns A ZodType that validates values matching the field definition
+ */
+function fieldDefToZod(fieldDef) {
+    let zodType;
+    switch (fieldDef.type) {
+        case "object":
+            zodType = objectSchemaToZod(fieldDef.fields);
+            break;
+        case "array":
+            zodType = zod_1.z.array(fieldDefToZod(fieldDef.items));
+            break;
+        case "string":
+            zodType = zod_1.z.string();
+            break;
+        case "number":
+            zodType = zod_1.z.number();
+            break;
+        case "boolean":
+            zodType = zod_1.z.boolean();
+            break;
+        case "date":
+            zodType = zod_1.z.date();
+            break;
+        case "enum":
+            zodType = zod_1.z.enum(fieldDef.values);
+            break;
+        default: {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const _exhaustiveCheck = fieldDef;
+            throw new Error("Unsupported field type");
+        }
+    }
+    if (fieldDef.nullable === true) {
+        zodType = zodType.optional().nullable();
+    }
+    return zodType;
+}
+/**
+ * A decorator for marking class fields as structured object attributes within the context of a single-table design entity.
+ *
+ * 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.
+ *
+ * **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
+ *
+ * All field types support `nullable: true` to remove them
+ *
+ * @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.
+ * @returns A class field decorator function
+ *
+ * Usage example:
+ * ```typescript
+ * const addressSchema = {
+ *   street: { type: "string" },
+ *   city: { type: "string" },
+ *   zip: { type: "number", nullable: true },
+ *   category: { type: "enum", values: ["home", "work", "other"] },
+ *   geo: {
+ *     type: "object",
+ *     fields: {
+ *       lat: { type: "number" },
+ *       lng: { type: "number" },
+ *       accuracy: { type: "enum", values: ["precise", "approximate"] }
+ *     }
+ *   }
+ * } as const satisfies ObjectSchema;
+ *
+ * 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:
+ * // address.category → "home" | "work" | "other"
+ * // address.geo.accuracy → "precise" | "approximate"
+ * ```
+ *
+ * Object attributes support filtering in queries using dot-path notation for nested fields
+ * and the {@link ContainsFilter | $contains} operator for List membership checks.
+ *
+ * ```typescript
+ * await MyEntity.query("123", {
+ *   filter: { "address.city": "Springfield" }
+ * });
+ *
+ * await MyEntity.query("123", {
+ *   filter: { "address.tags": { $contains: "home" } }
+ * });
+ * ```
+ */
+function ObjectAttribute(props) {
+    return function (_value, context) {
+        if (context.kind === "field") {
+            context.addInitializer(function () {
+                const { schema, ...restProps } = props;
+                const zodSchema = objectSchemaToZod(schema);
+                const serializers = (0, serializers_1.createObjectSerializer)(schema);
+                metadata_1.default.addEntityAttribute(this.constructor.name, {
+                    attributeName: context.name.toString(),
+                    nullable: props?.nullable,
+                    type: zodSchema,
+                    serializers,
+                    ...restProps
+                });
+            });
+        }
+    };
+}
+exports.default = ObjectAttribute;

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

@@ -7,5 +7,8 @@ export { default as BooleanAttribute } from "./BooleanAttribute";
 export { default as NumberAttribute } from "./NumberAttribute";
 export { default as EnumAttribute } from "./EnumAttribute";
 export { default as IdAttribute } from "./IdAttribute";
+export { default as ObjectAttribute } from "./ObjectAttribute";
+export type { ObjectAttributeOptions } from "./ObjectAttribute";
 export * from "./serializers";
+export type { ObjectSchema, InferObjectSchema, FieldDef, PrimitiveFieldDef, ObjectFieldDef, ArrayFieldDef, EnumFieldDef, DateFieldDef } from "./types";
 //# sourceMappingURL=index.d.ts.map

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

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

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

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IdAttribute = exports.EnumAttribute = exports.NumberAttribute = exports.BooleanAttribute = exports.StringAttribute = exports.DateAttribute = exports.ForeignKeyAttribute = exports.SortKeyAttribute = exports.PartitionKeyAttribute = void 0;
+exports.ObjectAttribute = exports.IdAttribute = exports.EnumAttribute = exports.NumberAttribute = exports.BooleanAttribute = exports.StringAttribute = exports.DateAttribute = exports.ForeignKeyAttribute = exports.SortKeyAttribute = exports.PartitionKeyAttribute = void 0;
 var PartitionKeyAttribute_1 = require("./PartitionKeyAttribute");
 Object.defineProperty(exports, "PartitionKeyAttribute", { enumerable: true, get: function () { return __importDefault(PartitionKeyAttribute_1).default; } });
 var SortKeyAttribute_1 = require("./SortKeyAttribute");
@@ -36,4 +36,6 @@ var EnumAttribute_1 = require("./EnumAttribute");
 Object.defineProperty(exports, "EnumAttribute", { enumerable: true, get: function () { return __importDefault(EnumAttribute_1).default; } });
 var IdAttribute_1 = require("./IdAttribute");
 Object.defineProperty(exports, "IdAttribute", { enumerable: true, get: function () { return __importDefault(IdAttribute_1).default; } });
+var ObjectAttribute_1 = require("./ObjectAttribute");
+Object.defineProperty(exports, "ObjectAttribute", { enumerable: true, get: function () { return __importDefault(ObjectAttribute_1).default; } });
 __exportStar(require("./serializers"), exports);

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

@@ -1,4 +1,6 @@
-import type { NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
+import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb";
+import type { ObjectSchema } 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.
  *
@@ -7,7 +9,53 @@ import type { NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
  *
  */
 export declare const dateSerializer: {
-    toEntityAttribute: (val: NativeScalarAttributeValue) => number | bigint | boolean | import("@aws-sdk/util-dynamodb").NumberValue | ArrayBuffer | Blob | DataView<ArrayBufferLike> | Date | null | undefined;
+    toEntityAttribute: (val: NativeAttributeValue) => any;
     toTableAttribute: (val?: Date) => string | 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
+ */
+export declare function objectToTableItem(schema: ObjectSchema, value: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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)
+ */
+export declare function tableItemToObject(schema: ObjectSchema, value: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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
+ */
+export declare function createObjectSerializer(schema: ObjectSchema): Serializers;
 //# sourceMappingURL=serializers.d.ts.map

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,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;6BACA,0BAA0B;6BAM1B,IAAI;CAC9B,CAAC"}
+{"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"}

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

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dateSerializer = void 0;
+exports.objectToTableItem = objectToTableItem;
+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 +20,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)
+    };
+}