dyna-record 0.4.9 → 0.4.10

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,78 @@ 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"] },
+  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"`, `"enum"` (via `values`), nested `"object"` (via `fields`), and `"array"` (via `items`)
+- **Nullable fields:** Set `nullable: true` on individual fields within the schema to allow `null` values
+- **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" | null | 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 +570,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 allow `null` values.
+ *
+ * @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;AAEzE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,YAAY,CAC5D,SAAQ,gBAAgB;IACxB;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;CACX;AAsED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,UAgBjE;AAED,eAAe,eAAe,CAAC"}

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

@@ -0,0 +1,151 @@
+"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"));
+/**
+ * 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 `.nullable().optional()`.
+ *
+ * @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 "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.nullable().optional();
+    }
+    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 allow `null` values.
+ *
+ * @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);
+                metadata_1.default.addEntityAttribute(this.constructor.name, {
+                    attributeName: context.name.toString(),
+                    nullable: props?.nullable,
+                    type: zodSchema,
+                    ...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 } 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,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,4 @@
-import type { NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
+import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb";
 /**
  * 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 +7,7 @@ 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;
 };
 //# 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;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;6BACA,oBAAoB;6BAMpB,IAAI;CAC9B,CAAC"}

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

@@ -0,0 +1,223 @@
+/**
+ * Maps schema type strings to their corresponding TypeScript types.
+ *
+ * Used by {@link InferFieldDef} to resolve primitive field types at the type level.
+ *
+ * | Schema type | TypeScript type |
+ * |-------------|-----------------|
+ * | `"string"`  | `string`        |
+ * | `"number"`  | `number`        |
+ * | `"boolean"` | `boolean`       |
+ */
+export interface PrimitiveTypeMap {
+    string: string;
+    number: number;
+    boolean: boolean;
+}
+/**
+ * The allowed primitive type strings for object schema fields.
+ *
+ * Derived from the keys of {@link PrimitiveTypeMap}: `"string" | "number" | "boolean"`.
+ */
+export type PrimitiveFieldType = keyof PrimitiveTypeMap;
+/**
+ * A schema field definition for a primitive type (`"string"`, `"number"`, or `"boolean"`).
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   name: { type: "string" },
+ *   age: { type: "number", nullable: true },
+ *   active: { type: "boolean" }
+ * } as const satisfies ObjectSchema;
+ * ```
+ */
+export interface PrimitiveFieldDef {
+    /** The primitive type — `"string"`, `"number"`, or `"boolean"`. */
+    type: PrimitiveFieldType;
+    /** When `true`, the field accepts `null` and becomes optional (`T | null | undefined`). */
+    nullable?: boolean;
+}
+/**
+ * A schema field definition for a nested object type.
+ *
+ * The `fields` property is itself an {@link ObjectSchema}, enabling arbitrarily deep nesting.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   geo: {
+ *     type: "object",
+ *     fields: {
+ *       lat: { type: "number" },
+ *       lng: { type: "number" }
+ *     }
+ *   }
+ * } as const satisfies ObjectSchema;
+ * ```
+ */
+export interface ObjectFieldDef {
+    /** Must be `"object"` to indicate a nested object field. */
+    type: "object";
+    /** The nested {@link ObjectSchema} describing the object's shape. */
+    fields: ObjectSchema;
+    /** When `true`, the field accepts `null` and becomes optional. */
+    nullable?: boolean;
+}
+/**
+ * A schema field definition for an array/list type.
+ *
+ * The `items` property describes the element type — primitives, enums, objects, or nested arrays.
+ * Inferred as `Array<InferFieldDef<items>>`.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   tags: { type: "array", items: { type: "string" } },
+ *   matrix: { type: "array", items: { type: "array", items: { type: "number" } } }
+ * } as const satisfies ObjectSchema;
+ * ```
+ */
+export interface ArrayFieldDef {
+    /** Must be `"array"` to indicate a list/array field. */
+    type: "array";
+    /** A {@link FieldDef} describing the type of each array element. */
+    items: FieldDef;
+    /** When `true`, the field accepts `null` and becomes optional. */
+    nullable?: boolean;
+}
+/**
+ * A schema field definition for an enum type.
+ *
+ * The `values` tuple defines the allowed string literals, used for both
+ * TypeScript type inference (`values[number]` → string literal union) and
+ * Zod runtime validation (`z.enum(values)`).
+ *
+ * Enum fields can appear at any nesting level: top-level, inside nested objects,
+ * or as array items.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   // Top-level enum
+ *   status: { type: "enum", values: ["active", "inactive"] },
+ *
+ *   // Nullable enum
+ *   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
+ *   roles: { type: "array", items: { type: "enum", values: ["admin", "user", "guest"] } }
+ * } as const satisfies ObjectSchema;
+ *
+ * type T = InferObjectSchema<typeof schema>;
+ * // {
+ * //   status: "active" | "inactive";
+ * //   category?: "home" | "work" | "other" | null;
+ * //   geo: { accuracy: "precise" | "approximate" };
+ * //   roles: ("admin" | "user" | "guest")[];
+ * // }
+ * ```
+ */
+export interface EnumFieldDef {
+    /** Must be `"enum"` to indicate an enum field. */
+    type: "enum";
+    /**
+     * A non-empty readonly tuple of allowed string values.
+     *
+     * At the type level, `values[number]` produces the union of allowed string literals.
+     * At runtime, this is passed to `z.enum()` for validation.
+     *
+     * Must contain at least one value (enforced by the `[string, ...string[]]` tuple type).
+     */
+    values: readonly [string, ...string[]];
+    /** When `true`, the field accepts `null` and becomes optional. */
+    nullable?: boolean;
+}
+/**
+ * A field definition within an {@link ObjectSchema}.
+ *
+ * This is the union of all supported field types:
+ * - {@link PrimitiveFieldDef} — `"string"`, `"number"`, `"boolean"`
+ * - {@link ObjectFieldDef} — nested objects via `fields`
+ * - {@link ArrayFieldDef} — arrays/lists via `items`
+ * - {@link EnumFieldDef} — string literal enums via `values`
+ *
+ * Each variant is discriminated by the `type` property.
+ */
+export type FieldDef = PrimitiveFieldDef | ObjectFieldDef | ArrayFieldDef | EnumFieldDef;
+/**
+ * Declarative schema for describing the shape of an object attribute.
+ *
+ * Used with `@ObjectAttribute` to provide both runtime validation (via Zod) and
+ * compile-time TypeScript type inference (via {@link InferObjectSchema}).
+ *
+ * Each key maps to a {@link FieldDef} describing the field's type, nesting, and nullability.
+ *
+ * **Important:** Always declare schemas with `as const satisfies ObjectSchema` to preserve
+ * literal types for accurate type inference.
+ *
+ * @example
+ * ```typescript
+ * const mySchema = {
+ *   name: { type: "string" },
+ *   score: { type: "number" },
+ *   status: { type: "enum", values: ["active", "inactive"] }
+ * } as const satisfies ObjectSchema;
+ * ```
+ */
+export type ObjectSchema = Record<string, FieldDef>;
+/**
+ * Infers the TypeScript type of a single {@link FieldDef}.
+ *
+ * Used internally by {@link InferObjectSchema} and for recursive array item inference.
+ *
+ * Resolution order:
+ * 1. {@link ArrayFieldDef} → `Array<InferFieldDef<items>>`
+ * 2. {@link ObjectFieldDef} → `InferObjectSchema<fields>`
+ * 3. {@link EnumFieldDef} → `values[number]` (string literal union)
+ * 4. {@link PrimitiveFieldDef} → `PrimitiveTypeMap[type]`
+ */
+export type InferFieldDef<F extends FieldDef> = F extends ArrayFieldDef ? Array<InferFieldDef<F["items"]>> : F extends ObjectFieldDef ? InferObjectSchema<F["fields"]> : F extends EnumFieldDef ? F["values"][number] : F extends PrimitiveFieldDef ? PrimitiveTypeMap[F["type"]] : never;
+/**
+ * Infers the TypeScript type from an {@link ObjectSchema} definition.
+ *
+ * - 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`
+ * - Array fields become `T[]` where `T` is inferred from `items`
+ * - Fields with `nullable: true` become optional and accept `null` (`T | null | undefined`)
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   name: { type: "string" },
+ *   age: { type: "number", nullable: true },
+ *   status: { type: "enum", values: ["active", "inactive"] },
+ *   tags: { type: "array", items: { type: "string" } },
+ *   geo: { type: "object", fields: { lat: { type: "number" }, lng: { type: "number" } } }
+ * } as const satisfies ObjectSchema;
+ *
+ * type MyType = InferObjectSchema<typeof schema>;
+ * // {
+ * //   name: string;
+ * //   status: "active" | "inactive";
+ * //   tags: string[];
+ * //   geo: { lat: number; lng: number };
+ * //   age?: number | null;
+ * // }
+ * ```
+ */
+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]["nullable"] extends true ? K : never]?: InferFieldDef<S[K]> | null;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/decorators/attributes/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,gBAAgB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,IAAI,EAAE,kBAAkB,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,IAAI,EAAE,QAAQ,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,IAAI,EAAE,OAAO,CAAC;IACd,oEAAoE;IACpE,KAAK,EAAE,QAAQ,CAAC;IAChB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACvC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAChB,iBAAiB,GACjB,cAAc,GACd,aAAa,GACb,YAAY,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,QAAQ,IAAI,CAAC,SAAS,aAAa,GACnE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAChC,CAAC,SAAS,cAAc,GACtB,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAC9B,CAAC,SAAS,YAAY,GACpB,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GACnB,CAAC,SAAS,iBAAiB,GACzB,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAC3B,KAAK,CAAC;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,YAAY,IAAI;KACrD,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,GAAG,aAAa,CACxE,CAAC,CAAC,CAAC,CAAC,CACL;CACF,GAAG;KACD,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,aAAa,CACzE,CAAC,CAAC,CAAC,CAAC,CACL,GAAG,IAAI;CACT,CAAC"}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,4 +1,4 @@
-import type { NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
+import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb";
 import type { AttributeMetadata, BelongsToRelationship, EntityMetadata, JoinTableMetadata, OwnedByRelationship, RelationshipMetadata, TableMetadata } from ".";
 import type DynaRecord from "../DynaRecord";
 import type { EntityClass, MakeOptional } from "../types";
@@ -61,11 +61,11 @@ export type KeysAttributeMetadataOptions = MakeOptional<Omit<AttributeMetadataOp
 /**
  * Function that takes a attribute from a Dynamo table item, and serialize it to a non-Dynamo native type (EX: Date)
  */
-export type EntitySerializer = (param: NativeScalarAttributeValue) => any;
+export type EntitySerializer = (param: NativeAttributeValue) => any;
 /**
  * Function that takes a attribute from an Entity which is not a native Dynamo type and serializes it a type that is supported by Dynamo
  */
-export type TableSerializer = (param: any) => NativeScalarAttributeValue;
+export type TableSerializer = (param: any) => NativeAttributeValue;
 /**
  * Functions for serializing attribute types that are not native to Dynamo from table item -> entity and entity -> table item
  * EX: See DateAttribute decorator

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/query-utils/QueryBuilder.d.ts

@@ -3,7 +3,7 @@ import type { QueryCommandProps } from "./types";
 /**
  * Constructs and formats a DynamoDB query command based on provided key conditions and query options. This class simplifies the creation of complex DynamoDB queries by abstracting the underlying AWS SDK query command structure, particularly handling the construction of key condition expressions, filter expressions, and expression attribute names and values.
  *
- * Utilizing metadata about the entity and its attributes, `QueryBuilder` generates the necessary DynamoDB expressions to perform precise queries, including support for conditional operators like '=', 'begins_with', and 'IN', as well as logical 'AND' and 'OR' operations.
+ * Utilizing metadata about the entity and its attributes, `QueryBuilder` generates the necessary DynamoDB expressions to perform precise queries, including support for conditional operators like '=', 'begins_with', 'contains', and 'IN', as well as logical 'AND' and 'OR' operations. Supports dot-path notation for filtering on nested Map attributes.
  */
 declare class QueryBuilder {
     #private;
@@ -29,8 +29,8 @@ declare class QueryBuilder {
      * Creates the filters
      *
      * Supports 'AND' and 'OR'
-     * Currently only works for '=', 'begins_with' or 'IN' operands
-     * Does not support operations like 'contains' etc yet
+     * Supports '=', 'begins_with', 'contains', and 'IN' operands
+     * Supports dot-path notation for nested Map attributes (e.g., 'address.city')
      *
      * @param filter
      * @returns
@@ -49,12 +49,25 @@ declare class QueryBuilder {
      */
     private andFilter;
     /**
-     * Creates an AND condition
-     * @param attr
+     * Creates an AND condition.
+     * Supports equality, begins_with, contains, and IN operators.
+     * Supports dot-path notation for nested Map attributes.
+     * @param attr - The attribute key, optionally using dot notation for nested paths
      * @param value
      * @returns
      */
     private andCondition;
+    /**
+     * Resolves an attribute key (potentially a dot-path) into its DynamoDB expression components.
+     *
+     * For simple keys (e.g., "name"), resolves via metadata alias.
+     * For dot-paths (e.g., "address.city"), resolves the first segment via metadata alias
+     * and uses remaining segments as literal Map sub-keys.
+     *
+     * @param key - The attribute key, optionally using dot notation
+     * @returns The resolved expression path, attribute names, and placeholder key
+     */
+    private resolveAttrPath;
     /**
      * Builds an OR filter
      * @param filter
@@ -73,6 +86,12 @@ declare class QueryBuilder {
      * @returns
      */
     private isBeginsWithFilter;
+    /**
+     * Type guard to check if its a ContainsFilter
+     * @param filter
+     * @returns
+     */
+    private isContainsFilter;
     /**
      * Type guard to check if its a AndOrFilter
      * @param filter

package/dist/src/query-utils/QueryBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/query-utils/QueryBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAO/D,OAAO,KAAK,EASV,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAGjB;;;;GAIG;AACH,cAAM,YAAY;;gBASJ,KAAK,EAAE,iBAAiB;IAmBpC;;;OAGG;IACI,KAAK,IAAI,iBAAiB;IAwBjC;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAetC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAgChC;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;IAWpB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IASnB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAejB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAyBpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAehB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAanB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAGnB;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/query-utils/QueryBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAO/D,OAAO,KAAK,EAUV,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAgBjB;;;;GAIG;AACH,cAAM,YAAY;;gBASJ,KAAK,EAAE,iBAAiB;IAmBpC;;;OAGG;IACI,KAAK,IAAI,iBAAiB;IAwBjC;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAetC;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAgChC;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;IAWpB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IASnB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAejB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IA6BpB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA0BvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAehB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAanB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAGnB;AAED,eAAe,YAAY,CAAC"}

package/dist/src/query-utils/QueryBuilder.js

@@ -8,7 +8,7 @@ const utils_1 = require("../operations/utils");
 /**
  * Constructs and formats a DynamoDB query command based on provided key conditions and query options. This class simplifies the creation of complex DynamoDB queries by abstracting the underlying AWS SDK query command structure, particularly handling the construction of key condition expressions, filter expressions, and expression attribute names and values.
  *
- * Utilizing metadata about the entity and its attributes, `QueryBuilder` generates the necessary DynamoDB expressions to perform precise queries, including support for conditional operators like '=', 'begins_with', and 'IN', as well as logical 'AND' and 'OR' operations.
+ * Utilizing metadata about the entity and its attributes, `QueryBuilder` generates the necessary DynamoDB expressions to perform precise queries, including support for conditional operators like '=', 'begins_with', 'contains', and 'IN', as well as logical 'AND' and 'OR' operations. Supports dot-path notation for filtering on nested Map attributes.
  */
 class QueryBuilder {
     #props;
@@ -70,8 +70,8 @@ class QueryBuilder {
     expressionAttributeNames() {
         const { filter } = this.#props.options ?? {};
         const accumulator = (obj, key) => {
-            const tableKey = this.#attributeMetadata[key].alias;
-            obj[`#${tableKey}`] = tableKey;
+            const resolved = this.resolveAttrPath(key);
+            Object.assign(obj, resolved.names);
             return obj;
         };
         let expressionAttributeNames = Object.keys(this.#props.key).reduce((acc, key) => accumulator(acc, key), {});
@@ -90,8 +90,8 @@ class QueryBuilder {
      * Creates the filters
      *
      * Supports 'AND' and 'OR'
-     * Currently only works for '=', 'begins_with' or 'IN' operands
-     * Does not support operations like 'contains' etc yet
+     * Supports '=', 'begins_with', 'contains', and 'IN' operands
+     * Supports dot-path notation for nested Map attributes (e.g., 'address.city')
      *
      * @param filter
      * @returns
@@ -136,35 +136,72 @@ class QueryBuilder {
         return params;
     }
     /**
-     * Creates an AND condition
-     * @param attr
+     * Creates an AND condition.
+     * Supports equality, begins_with, contains, and IN operators.
+     * Supports dot-path notation for nested Map attributes.
+     * @param attr - The attribute key, optionally using dot notation for nested paths
      * @param value
      * @returns
      */
     andCondition(attr, value) {
-        const tableKey = this.#attributeMetadata[attr].alias;
+        const resolved = this.resolveAttrPath(attr);
         let condition;
         let values = {};
         if (Array.isArray(value)) {
             const mappings = value.reduce((acc, val) => {
-                const attr = `${tableKey}${++this.#attrCounter}`;
-                values[attr] = val;
-                return acc.concat(`:${attr}`);
+                const placeholder = `${resolved.placeholderKey}${++this.#attrCounter}`;
+                values[placeholder] = val;
+                return acc.concat(`:${placeholder}`);
             }, []);
-            condition = `#${tableKey} IN (${mappings.join()})`;
+            condition = `${resolved.expressionPath} IN (${mappings.join()})`;
         }
         else if (this.isBeginsWithFilter(value)) {
-            const attr = `${tableKey}${++this.#attrCounter}`;
-            condition = `begins_with(#${tableKey}, :${attr})`;
-            values = { [`${attr}`]: value.$beginsWith };
+            const placeholder = `${resolved.placeholderKey}${++this.#attrCounter}`;
+            condition = `begins_with(${resolved.expressionPath}, :${placeholder})`;
+            values = { [placeholder]: value.$beginsWith };
+        }
+        else if (this.isContainsFilter(value)) {
+            const placeholder = `${resolved.placeholderKey}${++this.#attrCounter}`;
+            condition = `contains(${resolved.expressionPath}, :${placeholder})`;
+            values = { [placeholder]: value.$contains };
         }
         else {
-            const attr = `${tableKey}${++this.#attrCounter}`;
-            condition = `#${tableKey} = :${attr}`;
-            values = { [`${attr}`]: value };
+            const placeholder = `${resolved.placeholderKey}${++this.#attrCounter}`;
+            condition = `${resolved.expressionPath} = :${placeholder}`;
+            values = { [placeholder]: value };
         }
         return { expression: `${condition} AND `, values };
     }
+    /**
+     * Resolves an attribute key (potentially a dot-path) into its DynamoDB expression components.
+     *
+     * For simple keys (e.g., "name"), resolves via metadata alias.
+     * For dot-paths (e.g., "address.city"), resolves the first segment via metadata alias
+     * and uses remaining segments as literal Map sub-keys.
+     *
+     * @param key - The attribute key, optionally using dot notation
+     * @returns The resolved expression path, attribute names, and placeholder key
+     */
+    resolveAttrPath(key) {
+        const segments = key.split(".");
+        const topLevelKey = segments[0];
+        const tableKey = this.#attributeMetadata[topLevelKey].alias;
+        const names = { [`#${tableKey}`]: tableKey };
+        if (segments.length === 1) {
+            return {
+                expressionPath: `#${tableKey}`,
+                names,
+                placeholderKey: tableKey
+            };
+        }
+        const subSegments = segments.slice(1);
+        for (const segment of subSegments) {
+            names[`#${segment}`] = segment;
+        }
+        const expressionPath = `#${tableKey}.${subSegments.map(s => `#${s}`).join(".")}`;
+        const placeholderKey = `${tableKey}${subSegments.join("")}`;
+        return { expressionPath, names, placeholderKey };
+    }
     /**
      * Builds an OR filter
      * @param filter
@@ -203,6 +240,14 @@ class QueryBuilder {
     isBeginsWithFilter(filter) {
         return filter.$beginsWith !== undefined;
     }
+    /**
+     * Type guard to check if its a ContainsFilter
+     * @param filter
+     * @returns
+     */
+    isContainsFilter(filter) {
+        return filter.$contains !== undefined;
+    }
     /**
      * Type guard to check if its a AndOrFilter
      * @param filter

package/dist/src/query-utils/types.d.ts

@@ -1,5 +1,5 @@
 import { type QueryCommandInput } from "@aws-sdk/lib-dynamodb";
-import { type NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
+import { type NativeAttributeValue } from "@aws-sdk/util-dynamodb";
 /**
  * Represents conditions used to specify the partition key and sort key (if applicable) for querying items in DynamoDB.
  *
@@ -9,11 +9,11 @@ export type KeyConditions = Omit<QueryCommandInput["KeyConditions"], "undefined"
 /**
  * Defines the structure for a filter expression used in querying items, including the expression string and a record of values associated with the expression placeholders.
  *
- * @property {Record<string, NativeScalarAttributeValue>} values - A mapping of placeholder tokens in the filter expression to their actual values.
+ * @property {Record<string, NativeAttributeValue>} values - A mapping of placeholder tokens in the filter expression to their actual values.
  * @property {string} expression - The filter expression string, using DynamoDB's expression syntax.
  */
 export interface FilterExpression {
-    values: Record<string, NativeScalarAttributeValue>;
+    values: Record<string, NativeAttributeValue>;
     expression: string;
 }
 /**
@@ -21,13 +21,36 @@ export interface FilterExpression {
  *
  * @type {BeginsWithFilter} - A record with "$beginsWith" key pointing to the prefix value.
  */
-export type BeginsWithFilter = Record<"$beginsWith", NativeScalarAttributeValue>;
+export type BeginsWithFilter = Record<"$beginsWith", NativeAttributeValue>;
 /**
- * Defines possible types of values that can be used in a filter condition, including begins with, exact value, or an array for "IN" conditions.
+ * Represents a filter condition specifying that a list contains a given element, or a string contains a given substring.
+ * Maps to the DynamoDB `contains()` function.
  *
- * @type {FilterTypes} - A union of `BeginsWithFilter`, a single scalar value, or an array of scalar values.
+ * Works with both top-level attributes and nested `@ObjectAttribute` fields via dot-path notation.
+ *
+ * @type {ContainsFilter} - A record with "$contains" key pointing to the value to check for.
+ *
+ * @example
+ * ```typescript
+ * // Check if a List attribute contains an element
+ * filter: { tags: { $contains: "vip" } }
+ *
+ * // Check on a nested List via dot-path
+ * filter: { "address.tags": { $contains: "home" } }
+ *
+ * // Check if a string attribute contains a substring
+ * filter: { name: { $contains: "john" } }
+ * ```
+ */
+export type ContainsFilter = Record<"$contains", NativeAttributeValue>;
+/**
+ * Defines possible types of values that can be used in a filter condition, including begins with, contains, exact value, or an array for "IN" conditions.
+ *
+ * Filter keys support dot-path notation for nested `@ObjectAttribute` Map fields (e.g., `"address.city"`).
+ *
+ * @type {FilterTypes} - A union of `BeginsWithFilter`, `ContainsFilter`, a single scalar value, or an array of scalar values.
  */
-export type FilterTypes = BeginsWithFilter | NativeScalarAttributeValue | NativeScalarAttributeValue[];
+export type FilterTypes = BeginsWithFilter | ContainsFilter | NativeAttributeValue | NativeAttributeValue[];
 /**
  * Represents a filter condition using an AND logical operator. All items in this record will be queried with "AND"
  *
@@ -63,7 +86,7 @@ export type AndOrFilter = FilterParams & OrFilter;
  *
  * @type {SortKeyCondition} - A `BeginsWithFilter` or a single scalar value, used for sort key conditions in queries.
  */
-export type SortKeyCondition = BeginsWithFilter | NativeScalarAttributeValue;
+export type SortKeyCondition = BeginsWithFilter | NativeAttributeValue;
 /**
  * Specifies additional options for querying items, including optional consistent read, index name and filter conditions.
  *

package/dist/src/query-utils/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/query-utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,iBAAiB,CAAC,eAAe,CAAC,EAClC,WAAW,CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IACnD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CACnC,aAAa,EACb,0BAA0B,CAC3B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,0BAA0B,GAC1B,0BAA0B,EAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC,GAAG,UAAU,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,0BAA0B,CAAC;AAE7E;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,cAAc,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,aAAa,CAAC;IACnB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/query-utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,iBAAiB,CAAC,eAAe,CAAC,EAClC,WAAW,CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,cAAc,GACd,oBAAoB,GACpB,oBAAoB,EAAE,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEpD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAEhF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC,GAAG,UAAU,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,cAAc,CAAC,EAAE,KAAK,CAAC;CACxB,GACD;IACE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEN;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,aAAa,CAAC;IACnB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB"}

package/dist/src/types.d.ts

@@ -1,4 +1,4 @@
-import { type NativeScalarAttributeValue } from "@aws-sdk/util-dynamodb";
+import { type NativeAttributeValue } from "@aws-sdk/util-dynamodb";
 import type { BelongsToRelationship, RelationshipMetadata } from "./metadata";
 import type DynaRecord from "./DynaRecord";
 /**
@@ -40,7 +40,7 @@ export type ForeignKeyProperty = keyof DynaRecord & ForeignKey;
 /**
  * Defines a general type for items stored in a DynamoDB table, using string keys and native scalar attribute values.
  */
-export type DynamoTableItem = Record<string, NativeScalarAttributeValue>;
+export type DynamoTableItem = Record<string, NativeAttributeValue>;
 /**
  * A utility type for objects with string keys and string values.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,KAAK,CAC/D,MAAM,EACN;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,QAAQ,CAC1E,KAAK,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CACzD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,UAAU,GAAG,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,kBAAkB,CAAC;IACpC,sBAAsB,EAAE,qBAAqB,EAAE,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEtB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;KAC3D,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,KAAK,CAC/D,MAAM,EACN;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,QAAQ,CAC1E,KAAK,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CACzD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,UAAU,GAAG,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnC;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,kBAAkB,CAAC;IACpC,sBAAsB,EAAE,qBAAqB,EAAE,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAEtB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,UAAU,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;KAC3D,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACjB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGzD,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,UAAU,eACvC,UAAU,CAAC,cACZ,OAAO,CAAC,UAAU,CAAC,KAC9B,eAqBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,UAAU,eACvC,UAAU,CAAC,aACb,eAAe,KACzB,CAuBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,UAAU,eACpC,UAAU,CAAC,cACZ,oBAAoB,CAAC,CAAC,CAAC,KAClC,CAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,OACb,MAAM,KACV,GAAG,IAAI,MAAM,UAEf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,UACrB,OAAO,CAAC,UAAU,CAAC,OACtB,GAAG,KACP,GAAG,IAAI,MAAM,CAEf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,MAAM,KAAG,CAAC,EAAE,EAI3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,UAAW,GAAG,KAAG,KAAK,IAAI,MAE9C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,SAAS,oBAAoB,CAAC,UAAU,CAAC,EAChD,IAAI,SAAS,MAAM,OAAO,EAC1B,MAAM,UAEE,OAAO,OACV,IAAI,SACF,MAAM,KACZ,IAEF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAS,OAAO,KAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,CAErE,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,UAAU,eACvC,UAAU,CAAC,cACZ,OAAO,CAAC,UAAU,CAAC,KAC9B,eAqBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,UAAU,eACvC,UAAU,CAAC,aACb,eAAe,KACzB,CAuBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,UAAU,eACpC,UAAU,CAAC,cACZ,oBAAoB,CAAC,CAAC,CAAC,KAClC,CAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,OACb,MAAM,KACV,GAAG,IAAI,MAAM,UAEf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,UACrB,OAAO,CAAC,UAAU,CAAC,OACtB,GAAG,KACP,GAAG,IAAI,MAAM,CAEf,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,MAAM,KAAG,CAAC,EAAE,EAI3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,UAAW,GAAG,KAAG,KAAK,IAAI,MAE9C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,SAAS,oBAAoB,CAAC,UAAU,CAAC,EAChD,IAAI,SAAS,MAAM,OAAO,EAC1B,MAAM,UAEE,OAAO,OACV,IAAI,SACF,MAAM,KACZ,IAEF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAS,OAAO,KAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,CAErE,CAAC"}

package/package.json

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