dyna-record 0.5.3 → 0.6.0

package/README.md

@@ -21,6 +21,7 @@ Note: ACID compliant according to DynamoDB [limitations](https://docs.aws.amazon
   - [FindById](#findbyid)
   - [Query](#query)
     - [Filtering on Object Attributes](#filtering-on-object-attributes)
+    - [Typed Query Filters](#typed-query-filters)
   - [Update](#update)
     - [Updating Object Attributes](#updating-object-attributes)
   - [Delete](#delete)
@@ -111,13 +112,15 @@ abstract class MyTable extends DynaRecord {
 
 Each entity must extend the Table class. To support single table design patterns, they must extend the same tables class.
 
+Each entity **must** declare its `type` property as a string literal matching the class name. This enables compile-time type safety for query filters and return types. Omitting this declaration will produce a compile error at the `@Entity` decorator.
+
 By default, each entity will have [default attributes](https://dyna-record.com/types/_internal_.DefaultFields.html)
 
 - The partition key defined on the [table](#table) class
 - The sort key defined on the [table](#table) class
 - [id](https://dyna-record.com/classes/default.html#id) - The id for the model. This will be an autogenerated uuid unless [IdAttribute](<(https://dyna-record.com/functions/IdAttribute.html)>) is set on a non-nullable entity attribute.
-- [type](https://dyna-record.com/classes/default.html#type) - The type of the entity. Value is the entity class name
-- [createdAt](https://dyna-record.com/classes/default.html#updatedAt) - The timestamp of when the entity was created
+- [type](https://dyna-record.com/classes/default.html#type) - The type of the entity. Value is the entity class name. Must be declared as a string literal via `declare readonly type: "ClassName"`.
+- [createdAt](https://dyna-record.com/classes/default.html#createdAt) - The timestamp of when the entity was created
 - [updatedAt](https://dyna-record.com/classes/default.html#updatedAt) - Timestamp of when the entity was updated last
 
 ```typescript
@@ -125,15 +128,19 @@ import { Entity } from "dyna-record";
 
 @Entity
 class Student extends MyTable {
+  declare readonly type: "Student";
   // ...
 }
 
 @Entity
 class Course extends MyTable {
-  /// ...
+  declare readonly type: "Course";
+  // ...
 }
 ```
 
+> **Note:** `declare readonly type` is a pure TypeScript type annotation with zero runtime impact. The ORM sets `type` to the class name automatically. The declaration simply tells TypeScript the exact literal type, enabling typed query filters and return type narrowing.
+
 ### Attributes
 
 Use the attribute decorators below to define attributes on a model. The decorator maps class properties to DynamoDB table attributes.
@@ -157,6 +164,8 @@ import { Entity, Attribute } from "dyna-record";
 
 @Entity
 class Student extends MyTable {
+  declare readonly type: "Student";
+
   @StringAttribute({ alias: "Username" }) // Sets alias if field in Dynamo is different then on the model
   public username: string;
 
@@ -196,6 +205,8 @@ const addressSchema = {
 
 @Entity
 class Store extends MyTable {
+  declare readonly type: "Store";
+
   @ObjectAttribute({ alias: "Address", schema: addressSchema })
   public readonly address: InferObjectSchema<typeof addressSchema>;
 }
@@ -259,6 +270,8 @@ import {
 
 @Entity
 class Assignment extends MyTable {
+  declare readonly type: "Assignment";
+
   @ForeignKeyAttribute(() => Course)
   public readonly courseId: ForeignKey<Course>;
 
@@ -268,6 +281,8 @@ class Assignment extends MyTable {
 
 @Entity
 class Course extends MyTable {
+  declare readonly type: "Course";
+
   @ForeignKeyAttribute(() => Teacher, { nullable: true })
   public readonly teacherId?: NullableForeignKey<Teacher>; // Set as optional
 
@@ -300,6 +315,8 @@ import {
 
 @Entity
 class Assignment extends MyTable {
+  declare readonly type: "Assignment";
+
   // 'assignmentId' must be defined on associated model
   @HasOne(() => Grade, { foreignKey: "assignmentId" })
   public readonly grade: Grade;
@@ -307,6 +324,8 @@ class Assignment extends MyTable {
 
 @Entity
 class Grade extends MyTable {
+  declare readonly type: "Grade";
+
   @ForeignKeyAttribute(() => Assignment)
   public readonly assignmentId: ForeignKey<Assignment>;
 
@@ -325,6 +344,8 @@ import { Entity, NullableForeignKey, BelongsTo, HasMany } from "dyna-record";
 
 @Entity
 class Teacher extends MyTable {
+  declare readonly type: "Teacher";
+
   // 'teacherId' must be defined on associated model
   @HasMany(() => Course, { foreignKey: "teacherId" })
   public readonly courses: Course[];
@@ -332,6 +353,8 @@ class Teacher extends MyTable {
 
 @Entity
 class Course extends MyTable {
+  declare readonly type: "Course";
+
   @ForeignKeyAttribute(() => Teacher, { nullable: true })
   public readonly teacherId?: NullableForeignKey<Teacher>; // Mark as optional
 
@@ -350,6 +373,8 @@ import { Entity, NullableForeignKey, BelongsTo, HasMany } from "dyna-record";
 
 @Entity
 class Teacher extends MyTable {
+  declare readonly type: "Teacher";
+
   // 'teacherId' must be defined on associated model
   @HasMany(() => Course, { foreignKey: "teacherId", uniDirectional: true })
   public readonly courses: Course[];
@@ -357,6 +382,8 @@ class Teacher extends MyTable {
 
 @Entity
 class Course extends MyTable {
+  declare readonly type: "Course";
+
   @ForeignKeyAttribute(() => Teacher, { nullable: true })
   public readonly teacherId?: NullableForeignKey<Teacher>; // Mark as optional
 }
@@ -383,6 +410,8 @@ class StudentCourse extends JoinTable<Student, Course> {
 
 @Entity
 class Course extends MyTable {
+  declare readonly type: "Course";
+
   @HasAndBelongsToMany(() => Student, {
     targetKey: "courses",
     through: () => ({ joinTable: StudentCourse, foreignKey: "courseId" })
@@ -392,6 +421,8 @@ class Course extends MyTable {
 
 @Entity
 class Student extends OtherTable {
+  declare readonly type: "Student";
+
   @HasAndBelongsToMany(() => Course, {
     targetKey: "students",
     through: () => ({ joinTable: StudentCourse, foreignKey: "studentId" })
@@ -528,7 +559,7 @@ const result = await Customer.query("123", {
 
 ##### Query by primary key
 
-To be more precise to the underlying data, you can specify the partition key and sort key directly. The keys here will be the partition and sort keys defined on the [table](#table) class.
+To be more precise to the underlying data, you can specify the partition key and sort key directly. The keys here will be the partition and sort keys defined on the [table](#table) class. The `sk` value is typed to only accept valid entity names from the partition.
 
 ```typescript
 const orders = await Customer.query({
@@ -556,9 +587,8 @@ const result = await Course.query(
           updatedAt: { $beginsWith: "2023-02-15" }
         },
         {
-          type: ["science", "math"],
-          createdAt: { $beginsWith: "2021-09-15T" },
-          type: "Assignment"
+          type: "Assignment",
+          createdAt: { $beginsWith: "2021-09-15T" }
         },
         {
           id: "123"
@@ -632,6 +662,163 @@ const result = await Store.query("123", {
 });
 ```
 
+#### Typed Query Filters
+
+Query filters are strongly typed based on the entities in the queried partition. A partition includes the entity itself plus all entities reachable through its declared relationships (`@HasMany`, `@HasOne`, `@BelongsTo`, `@HasAndBelongsToMany`). For example, if `Customer` has `@HasMany(() => Order)` and `@HasOne(() => ContactInformation)`, then Customer's partition entities are `Customer`, `Order`, and `ContactInformation`.
+
+The type system validates:
+
+- **Filter attribute keys**: Only attributes that exist on the entity or its related entities are accepted. Relationship property names, partition keys, and sort keys are excluded.
+- **`type` field values**: The `type` field only accepts entity names from the partition — the entity itself and its declared relationships. Entities from other tables or unrelated entities on the same table are rejected.
+- **Sort key values**: Both `skCondition` and the `sk` property in key conditions only accept entity names from the partition. This matches dyna-record's single-table design where sort key values always start with an entity class name.
+- **`type` narrowing in `$or`**: Each `$or` element is independently narrowed. When an `$or` block specifies `type: "Order"`, only Order's attributes are allowed in that block.
+- **Dot-path keys**: Nested `@ObjectAttribute` fields are available as typed filter keys using dot notation (e.g., `"address.city"`).
+
+##### Filter key validation
+
+```typescript
+// Valid: 'name' exists on Customer, 'lastFour' on PaymentMethod
+await Customer.query("123", {
+  filter: { name: "John", lastFour: "1234" }
+});
+
+// Error: 'nonExistent' is not an attribute on any entity in Customer's partition
+await Customer.query("123", {
+  filter: { nonExistent: "value" } // Compile error
+});
+
+// Error: 'orders' is a relationship property, not a filterable attribute
+await Customer.query("123", {
+  filter: { orders: "value" } // Compile error
+});
+```
+
+##### Type field narrowing
+
+```typescript
+// Valid entity names only
+await Customer.query("123", {
+  filter: { type: "Order" } // OK: "Order" is in Customer's partition
+});
+
+await Customer.query("123", {
+  filter: { type: "NonExistent" } // Compile error
+});
+
+// Array form (IN operator) accepts valid entity names
+await Customer.query("123", {
+  filter: { type: ["Order", "PaymentMethod"] }
+});
+```
+
+##### $or element narrowing
+
+Each `$or` element narrows independently based on its own `type` value:
+
+```typescript
+await Customer.query("123", {
+  filter: {
+    $or: [
+      { type: "Order", orderDate: "2023" }, // OK: orderDate is on Order
+      { type: "PaymentMethod", lastFour: "1234" } // OK: lastFour is on PaymentMethod
+    ]
+  }
+});
+
+// Error in $or: lastFour is not an attribute on Order
+await Customer.query("123", {
+  filter: {
+    $or: [
+      { type: "Order", lastFour: "1234" } // Compile error
+    ]
+  }
+});
+```
+
+##### Return type narrowing
+
+When querying a partition with no filter or sort key condition, the return type is a union of the entity itself and all its related entities:
+
+```typescript
+// Return type: Array<EntityAttributesInstance<Customer> | EntityAttributesInstance<Order>
+//   | EntityAttributesInstance<PaymentMethod> | EntityAttributesInstance<ContactInformation>>
+const results = await Customer.query("123");
+```
+
+When the filter specifies a `type` value, the return type automatically narrows to only the matching entities:
+
+```typescript
+// Return type: Array<EntityAttributesInstance<Order>>
+const orders = await Customer.query("123", {
+  filter: { type: "Order" }
+});
+
+orders[0]?.orderDate; // OK: orderDate is accessible
+
+// Return type: Array<EntityAttributesInstance<Order> | EntityAttributesInstance<PaymentMethod>>
+const mixed = await Customer.query("123", {
+  filter: { type: ["Order", "PaymentMethod"] }
+});
+```
+
+##### Sort key validation and narrowing
+
+Sort key values are typed to only accept valid entity names from the partition, matching dyna-record's single-table design where SK values always start with an entity class name. This applies to both the `skCondition` option and the `sk` property in key conditions:
+
+```typescript
+// Both forms validate sort key values against partition entity names
+
+// skCondition option (string form)
+await Customer.query("123", { skCondition: "Order" }); // OK
+await Customer.query("123", { skCondition: "Order#123" }); // OK
+await Customer.query("123", { skCondition: { $beginsWith: "Order" } }); // OK
+await Customer.query("123", { skCondition: "NonExistent" }); // Compile error
+
+// sk property in key conditions (object form)
+await Customer.query({ pk: "Customer#123", sk: "Order" }); // OK
+await Customer.query({ pk: "Customer#123", sk: "Order#001" }); // OK
+await Customer.query({ pk: "Customer#123", sk: { $beginsWith: "Order" } }); // OK
+await Customer.query({ pk: "Customer#123", sk: "NonExistent" }); // Compile error
+```
+
+**Return type narrowing** works with `skCondition` when the value is an exact entity name or `$beginsWith` with an entity name:
+
+```typescript
+// skCondition narrows the return type
+const orders = await Customer.query("123", { skCondition: "Order" });
+// orders is Array<EntityAttributesInstance<Order>>
+
+const orders2 = await Customer.query("123", {
+  skCondition: { $beginsWith: "Order" }
+});
+// orders2 is Array<EntityAttributesInstance<Order>>
+
+// Suffix prevents narrowing (delimiter is configurable)
+const specific = await Customer.query("123", { skCondition: "Order#123" });
+// specific is QueryResults<Customer> (full union)
+```
+
+When using the object key form (`{ pk: "...", sk: "..." }`), sort key values are **validated** but the return type is **not narrowed**. Use `filter: { type: "Order" }` alongside key conditions for return type narrowing:
+
+```typescript
+// sk is validated but does NOT narrow the return type
+const results = await Customer.query({ pk: "Customer#123", sk: "Order" });
+// results is QueryResults<Customer> (full union)
+
+// Combine with filter type for return type narrowing
+const orders = await Customer.query(
+  { pk: "Customer#123", sk: { $beginsWith: "Order" } },
+  { filter: { type: "Order" } }
+);
+// orders is Array<EntityAttributesInstance<Order>>
+```
+
+> **Note:** Return type narrowing applies to the top-level `type` filter field, `type` values within `$or` elements, and to the `skCondition` option. When `$or` elements specify `type` values, the return type narrows to the union of those entity types. The `sk` property in key conditions validates values but does not narrow return types. Index queries (`{ indexName: "..." }`) use untyped filters.
+>
+> **Filter key narrowing:** When no `type` is specified, the return type automatically narrows based on which entities have the filtered attributes. For example, `filter: { orderDate: "2023" }` narrows to `Order` if only `Order` has `orderDate`. In `$or` blocks, each element narrows independently — by `type` if present, or by filter keys otherwise — and the return type is the union across all blocks.
+>
+> **AND intersection:** Since DynamoDB ANDs top-level filter conditions with `$or` blocks, the return type reflects this. When both top-level conditions and `$or` blocks independently narrow to specific entity sets, the return type is their intersection. If no entity satisfies both (e.g., `{ orderDate: "2023", $or: [{ lastFour: "1234" }] }` where `orderDate` is on `Order` and `lastFour` is on `PaymentMethod`), the return type is `never[]` — correctly indicating that no records can match.
+
 ### Querying on an index
 
 For querying based on secondary indexes, you can specify the index name in the options.
@@ -821,9 +1008,13 @@ If deleting an entity or its relationships fails due to database constraints or
 
 Dyna-Record integrates type safety into your DynamoDB interactions, reducing runtime errors and enhancing code quality.
 
+- **Entity Type Declaration**: The `@Entity` decorator enforces that each entity declares `readonly type` as a string literal matching the class name (`declare readonly type: "MyEntity"`). This is required for compile-time query type safety.
 - **Attribute Type Enforcement**: Ensures that the data types of attributes match their definitions in your entities.
 - **Method Parameter Checking**: Validates method parameters against entity definitions, preventing invalid operations.
 - **Relationship Integrity**: Automatically manages the consistency of relationships between entities, ensuring data integrity.
+- **Typed Query Filters**: Query filter keys are validated against the attributes of entities in the partition. Invalid keys, relationship property names, and non-existent attributes produce compile errors. The `type` field only accepts valid entity class names.
+- **Return Type Narrowing**: When a query filter specifies a `type` value, the return type is automatically narrowed to only the matching entity types instead of the full partition union.
+- **`$or` Element Narrowing**: Each element in a `$or` filter array is independently type-checked based on its own `type` field, preventing attribute mismatches.
 
 ## Best Practices
 

package/dist/src/DynaRecord.d.ts

@@ -1,5 +1,5 @@
 import { type TableMetadata } from "./metadata";
-import { type FindByIdOptions, type FindByIdIncludesRes, type EntityKeyConditions, type QueryResults, Create, type CreateOptions, type UpdateOptions, type EntityAttributesInstance, type IncludedAssociations, type IndexKeyConditions, type OptionsWithoutIndex, type OptionsWithIndex } from "./operations";
+import { type FindByIdOptions, type FindByIdIncludesRes, type EntityKeyConditions, type QueryResults, Create, type CreateOptions, type UpdateOptions, type EntityAttributesInstance, type IncludedAssociations, type IndexKeyConditions, type OptionsWithoutIndex, type OptionsWithIndex, type TypedFilterParams, type TypedSortKeyCondition, type InferQueryResults } from "./operations";
 import type { DynamoTableItem, EntityClass, Optional } from "./types";
 interface DynaRecordBase {
     id: string;
@@ -26,7 +26,8 @@ interface DynaRecordBase {
  *
  * @Entity
  * class User extends MyTable {
- *  // User implementation
+ *   declare readonly type: "User";
+ *   // User implementation
  * }
  * ```
  */
@@ -36,7 +37,11 @@ declare abstract class DynaRecord implements DynaRecordBase {
      */
     readonly id: string;
     /**
-     * The type of the Entity
+     * The type of the entity. Set automatically to the class name at runtime.
+     *
+     * Each entity must narrow this field to a string literal matching the class name
+     * via `declare readonly type: "ClassName"`. This enables compile-time type safety
+     * for query filters and return type narrowing.
      */
     readonly type: string;
     /**
@@ -75,88 +80,94 @@ declare abstract class DynaRecord implements DynaRecordBase {
     /**
      * Query an EntityPartition by EntityId (string) or by PartitionKey/SortKey conditions (object).
      * QueryByIndex not supported with this overload. Use Query with keys and indexName option if needed.
-     * @param {string | EntityKeyConditions<T>} key - Entity Id (string) or an object with PartitionKey and optional SortKey conditions.
-     * @param {Object=} options - QueryOptions. Supports filter, consistentRead and skCondition. indexName is not supported
      *
-     * @example By partition key only (string shorthand)
-     * ```typescript
-     * const user = await User.query("123");
-     * ```
+     * **Filter key validation:** Filter keys are strongly typed to only accept valid attribute
+     * names from the entity and its declared relationships (`@HasMany`, `@HasOne`, `@BelongsTo`,
+     * `@HasAndBelongsToMany`). The `type` field only accepts the entity itself or its related
+     * entity names — entities from other tables or unrelated entities are rejected.
+     * When `type` is specified as a single value in a `$or` block, filter keys are narrowed to
+     * that entity's attributes.
      *
-     * @example By partition key and sort key exact match
-     * ```typescript
-     * const user = await User.query("123", { skCondition: "Profile#111" });
-     * ```
+     * **Sort key validation:** Both `skCondition` (string form) and `sk` (object key form) only
+     * accept the entity itself or its related entity names, matching dyna-record's single-table
+     * sort key format where SK values always start with an entity class name. Unrelated entities
+     * and entities from other tables are rejected at compile time.
      *
-     * @example By partition key and sort key begins with
-     * ```typescript
-     * const user = await User.query("123", { skCondition: { $beginsWith: "Profile" } })
-     * ```
+     * **Return type narrowing:** The return type narrows automatically based on:
+     * - Top-level filter `type`: `type: "Order"` → `Array<EntityAttributesInstance<Order>>`
+     * - Top-level filter `type` array: `type: ["Order", "PaymentMethod"]` → union of both
+     * - Top-level filter keys: `{ orderDate: "2023" }` → narrows to entities that have `orderDate`
+     * - `$or` elements: each block narrows by `type` (if present) or by filter keys; return type is the union
+     * - AND intersection: when top-level conditions and `$or` both narrow, the return type is their intersection. Empty intersection → `never[]`.
+     * - `skCondition` option: `skCondition: "Order"` or `skCondition: { $beginsWith: "Order" }` → narrows to Order
+     * - No type/keys/SK specified → union of T and all related entities (e.g., `Customer | Order | PaymentMethod | ContactInformation`)
      *
-     * @example With filter (arbitrary example)
+     * Note: When using the object key form (`{ pk: "...", sk: "Order" }`), the `sk` value is
+     * validated against entity names but does **not** narrow the return type due to a TypeScript
+     * inference limitation. Use `filter: { type: "Order" }` or the `skCondition` option for
+     * return type narrowing.
+     *
+     * @template T - The entity type being queried.
+     * @template F - The inferred filter type, captured via `const` generic for literal type inference.
+     * @template SK - The inferred sort key condition type, captured via `const` generic for literal type inference.
+     * @param {string | EntityKeyConditions<T>} key - Entity Id (string) or an object with PartitionKey and optional SortKey conditions.
+     * @param {Object=} options - QueryOptions. Supports typed filter, consistentRead and skCondition. indexName is not supported.
+     * @param {TypedFilterParams<T>=} options.filter - Typed filter conditions. Keys are validated against partition entity attributes. The `type` field accepts valid entity class names.
+     * @param {TypedSortKeyCondition<T>=} options.skCondition - Sort key condition. Only accepts valid entity names from the partition. Narrows the return type when matching an exact entity name.
+     * @returns A promise resolving to query results. The return type narrows based on the filter's `type` value or `skCondition`.
+     *
+     * @example By entity ID
      * ```typescript
-     * const user = await User.query("123", {
-     *   filter: {
-     *     type: "Profile",
-     *     createdAt: "2023-11-21T12:31:21.148Z"
-     *    }
-     * });
+     * const results = await Customer.query("123");
      * ```
      *
-     * @example Query as consistent read
+     * @example With skCondition (narrows return type to Order)
      * ```typescript
-     * const user = await User.query("123", { consistentRead: true })
+     * const orders = await Customer.query("123", { skCondition: "Order" });
+     * // orders is Array<EntityAttributesInstance<Order>>
      * ```
      *
-     * @example By partition key only (object form)
+     * @example With skCondition $beginsWith (narrows return type)
      * ```typescript
-     * const user = await User.query({ pk: "User#123" });
+     * const orders = await Customer.query("123", { skCondition: { $beginsWith: "Order" } });
+     * // orders is Array<EntityAttributesInstance<Order>>
      * ```
      *
-     * @example By partition key and sort key exact match (object form)
+     * @example With typed filter (narrows return type)
      * ```typescript
-     * const user = await User.query({ pk: "User#123", sk: "Profile#123" });
+     * const orders = await Customer.query("123", {
+     *   filter: { type: "Order", orderDate: "2023-01-01" }
+     * });
+     * // orders is Array<EntityAttributesInstance<Order>>
      * ```
      *
-     * @example By partition key and sort key begins with (object form)
+     * @example By primary key (sk validated, return type NOT narrowed)
      * ```typescript
-     * const user = await User.query({ pk: "User#123", sk: { $beginsWith: "Profile" } });
+     * const results = await Customer.query({ pk: "Customer#123", sk: "Order" });
+     * // results is QueryResults<Customer> — use filter type for narrowing
      * ```
      *
-     * @example With filter (object form, arbitrary example)
+     * @example By primary key with filter type (narrows return type)
      * ```typescript
-     * const result = await User.query(
-     *  {
-     *    myPk: "User|123"
-     *  },
-     *  {
-     *    filter: {
-     *      type: ["Profile", "Preferences"],
-     *      createdAt: { $beginsWith: "2023" },
-     *      $or: [
-     *        {
-     *         name: "John",
-     *         email: { $beginsWith: "testing" }
-     *        },
-     *        {
-     *          name: "Jane",
-     *          updatedAt: { $beginsWith: "2024" },
-     *        },
-     *       {
-     *         id: "123"
-     *       }
-     *      ]
-     *    }
-     * }
-     *);
+     * const orders = await Customer.query(
+     *   { pk: "Customer#123", sk: { $beginsWith: "Order" } },
+     *   { filter: { type: "Order" } }
+     * );
+     * // orders is Array<EntityAttributesInstance<Order>>
      * ```
      *
-     * @example With a consistent read
+     * @example Query as consistent read
      * ```typescript
-     * const user = await User.query({ pk: "User#123", consistentRead: true });
+     * const results = await Customer.query("123", { consistentRead: true });
      * ```
      */
-    static query<T extends DynaRecord>(this: EntityClass<T>, key: string | EntityKeyConditions<T>, options?: OptionsWithoutIndex): Promise<QueryResults<T>>;
+    static query<T extends DynaRecord, const F extends TypedFilterParams<T> = TypedFilterParams<T>, const SK extends TypedSortKeyCondition<T> = TypedSortKeyCondition<T>>(this: EntityClass<T>, key: string, options?: OptionsWithoutIndex<T> & {
+        filter?: F;
+        skCondition?: SK;
+    }): Promise<InferQueryResults<T, F, SK>>;
+    static query<T extends DynaRecord, const F extends TypedFilterParams<T> = TypedFilterParams<T>>(this: EntityClass<T>, key: EntityKeyConditions<T>, options?: Omit<OptionsWithoutIndex<T>, "skCondition"> & {
+        filter?: F;
+    }): Promise<InferQueryResults<T, F>>;
     /**
      * Query by PartitionKey and optional SortKey/Filter/Index conditions with an index
      * When querying on an index, any of the entities attributes can be part of the key condition
@@ -167,7 +178,7 @@ declare abstract class DynaRecord implements DynaRecordBase {
      * ```typescript
      *  const result = await User.query(
      *    {
-     *      name: "SomeName" // An attribute that is part of the key condition on an iondex
+     *      name: "SomeName" // An attribute that is part of the key condition on an index
      *    },
      *    { indexName: "myIndex" }
      *  );

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

@@ -91,7 +91,8 @@ const utils_2 = require("./utils");
  *
  * @Entity
  * class User extends MyTable {
- *  // User implementation
+ *   declare readonly type: "User";
+ *   // User implementation
  * }
  * ```
  */
@@ -126,7 +127,11 @@ let DynaRecord = (() => {
          */
         id = __runInitializers(this, _id_initializers, void 0);
         /**
-         * The type of the Entity
+         * The type of the entity. Set automatically to the class name at runtime.
+         *
+         * Each entity must narrow this field to a string literal matching the class name
+         * via `declare readonly type: "ClassName"`. This enables compile-time type safety
+         * for query filters and return type narrowing.
          */
         type = (__runInitializers(this, _id_extraInitializers), __runInitializers(this, _type_initializers, void 0));
         /**

package/dist/src/decorators/Entity.d.ts

@@ -4,20 +4,26 @@ import type DynaRecord from "../DynaRecord";
  *
  * IMPORTANT - All entity classes should extend a table class decorated by {@link Table}
  *
- * @template T The class being decorated, which extends from the base `DynaRecord` entity class. This ensures that only classes that are part of the ORM system can be decorated as entities.
- * @param target The constructor function of the class being decorated. This function is used to instantiate objects of the class.
- * @param context The context in which the decorator is applied, provided by the TypeScript runtime. This includes metadata about the class, such as its kind and other relevant information. The decorator uses this context to perform its registration logic.
- * @returns {void} The decorator does not return a value. Instead, it performs side effects by registering the class with the ORM's metadata system.
+ * Entities MUST declare their `type` property as a string literal matching the class name.
+ * This enables compile-time type safety for query filters and return types.
+ *
+ * @template C The constructor of the class being decorated. The class must extend `DynaRecord`
+ * and declare `readonly type` as a string literal (e.g., `declare readonly type: "Order"`).
+ * @param target The constructor function of the class being decorated.
+ * @param context The context in which the decorator is applied, provided by the TypeScript runtime.
+ * @returns {void} The decorator does not return a value.
  *
  * Usage example:
  * ```typescript
  * @Entity
  * class User extends MyTable {
+ *   declare readonly type: "User";
  *   // User entity implementation
  * }
  * ```
- * In this example, the `User` class is marked as an entity using the `@Entity` decorator. This designation registers the `User` class within the ORM's metadata system, making it a recognized entity for the ORM to manage. The registration process involves associating the class with its corresponding table name and any additional metadata required by the ORM to handle instances of this class effectively.
  */
-declare function Entity(target: new () => DynaRecord, _context: ClassDecoratorContext): void;
+declare function Entity<C extends abstract new (...args: never[]) => DynaRecord>(target: C & (string extends InstanceType<C>["type"] ? {
+    __entityTypeError: 'Entity must declare: declare readonly type: "ClassName"';
+} : unknown), _context: ClassDecoratorContext<C>): void;
 export default Entity;
 //# sourceMappingURL=Entity.d.ts.map

package/dist/src/decorators/Entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../../../src/decorators/Entity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,iBAAS,MAAM,CACb,MAAM,EAAE,UAAU,UAAU,EAC5B,QAAQ,EAAE,qBAAqB,GAC9B,IAAI,CAKN;AAED,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../../../src/decorators/Entity.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iBAAS,MAAM,CAAC,CAAC,SAAS,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,UAAU,EACrE,MAAM,EAAE,CAAC,GACP,CAAC,MAAM,SAAS,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GACnC;IACE,iBAAiB,EAAE,yDAAyD,CAAC;CAC9E,GACD,OAAO,CAAC,EACd,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,IAAI,CAKN;AAED,eAAe,MAAM,CAAC"}

package/dist/src/decorators/Entity.js

@@ -9,19 +9,23 @@ const metadata_1 = __importDefault(require("../metadata"));
  *
  * IMPORTANT - All entity classes should extend a table class decorated by {@link Table}
  *
- * @template T The class being decorated, which extends from the base `DynaRecord` entity class. This ensures that only classes that are part of the ORM system can be decorated as entities.
- * @param target The constructor function of the class being decorated. This function is used to instantiate objects of the class.
- * @param context The context in which the decorator is applied, provided by the TypeScript runtime. This includes metadata about the class, such as its kind and other relevant information. The decorator uses this context to perform its registration logic.
- * @returns {void} The decorator does not return a value. Instead, it performs side effects by registering the class with the ORM's metadata system.
+ * Entities MUST declare their `type` property as a string literal matching the class name.
+ * This enables compile-time type safety for query filters and return types.
+ *
+ * @template C The constructor of the class being decorated. The class must extend `DynaRecord`
+ * and declare `readonly type` as a string literal (e.g., `declare readonly type: "Order"`).
+ * @param target The constructor function of the class being decorated.
+ * @param context The context in which the decorator is applied, provided by the TypeScript runtime.
+ * @returns {void} The decorator does not return a value.
  *
  * Usage example:
  * ```typescript
  * @Entity
  * class User extends MyTable {
+ *   declare readonly type: "User";
  *   // User entity implementation
  * }
  * ```
- * In this example, the `User` class is marked as an entity using the `@Entity` decorator. This designation registers the `User` class within the ORM's metadata system, making it a recognized entity for the ORM to manage. The registration process involves associating the class with its corresponding table name and any additional metadata required by the ORM to handle instances of this class effectively.
  */
 function Entity(target, _context) {
     const tableClassName = Object.getPrototypeOf(target).name;

package/dist/src/index.d.ts

@@ -2,6 +2,6 @@ export * from "./decorators";
 export * from "./errors";
 export * from "./relationships";
 export * from "./dynamo-utils/errors";
-export type { EntityAttributesOnly, EntityAttributesInstance as EntityInstance, FindByIdIncludesRes } from "./operations";
+export type { EntityAttributesOnly, EntityAttributesInstance as EntityInstance, FindByIdIncludesRes, TypedFilterParams, TypedSortKeyCondition, InferQueryResults, PartitionEntityNames } from "./operations";
 export type { PartitionKey, SortKey, ForeignKey, NullableForeignKey } from "./types";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AAEtC,YAAY,EACV,oBAAoB,EACpB,wBAAwB,IAAI,cAAc,EAC1C,mBAAmB,EACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,YAAY,EACZ,OAAO,EACP,UAAU,EACV,kBAAkB,EACnB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AAEtC,YAAY,EACV,oBAAoB,EACpB,wBAAwB,IAAI,cAAc,EAC1C,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,YAAY,EACZ,OAAO,EACP,UAAU,EACV,kBAAkB,EACnB,MAAM,SAAS,CAAC"}

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

@@ -1,7 +1,7 @@
 import type DynaRecord from "../../DynaRecord";
-import type { KeyConditions as QueryKeyConditions, QueryOptions as QueryBuilderOptions, SortKeyCondition, BeginsWithFilter } from "../../query-utils";
-import type { PartitionKey, SortKey } from "../../types";
-import type { EntityAttributesInstance } from "../types";
+import type { KeyConditions as QueryKeyConditions, QueryOptions as QueryBuilderOptions, FilterTypes, SortKeyCondition } from "../../query-utils";
+import type { IsAny, PartitionKey, SortKey } from "../../types";
+import type { EntityAttributesInstance, EntityFilterableKeys } from "../types";
 /**
  * Extends the basic query builder options by adding an optional sort key condition for more precise querying capabilities.
  *
@@ -15,9 +15,25 @@ export type QueryOptions = QueryBuilderOptions & {
     skCondition?: SortKeyCondition;
 };
 /**
- * Options for querying without an index
+ * Options for querying without an index.
+ *
+ * Omits `indexName`, `filter`, and `skCondition` from {@link QueryOptions}.
+ * The `filter` property is re-declared using {@link TypedFilterParams} for compile-time
+ * key validation. The `skCondition` property is omitted here and re-added at the query
+ * overload level with a `const SK` generic parameter for literal type inference and
+ * return type narrowing.
+ *
+ * The query overload also re-declares `filter` with a `const F` generic parameter to
+ * enable literal type inference for return type narrowing. Both declarations are required:
+ * this one provides excess property checking on object literals, while the generic
+ * provides literal type capture for return type inference.
+ *
+ * @template T - The entity type being queried. Defaults to `DynaRecord` for backward
+ * compatibility in generic contexts.
  */
-export type OptionsWithoutIndex = Omit<QueryOptions, "indexName">;
+export type OptionsWithoutIndex<T extends DynaRecord = DynaRecord> = Omit<QueryOptions, "indexName" | "filter" | "skCondition"> & {
+    filter?: TypedFilterParams<T>;
+};
 /**
  *  Options for querying on an index. Consistent reads are not allowed
  */
@@ -28,15 +44,16 @@ export type OptionsWithIndex = QueryBuilderOptions & {
 /**
  * Defines key conditions for querying entities based on their keys.
  *
- * PartitionKey is required, SortKey is optional.
+ * PartitionKey is required, SortKey is optional. The SortKey value is typed
+ * to only accept valid entity names from the partition (or entity name prefixes),
+ * matching dyna-record's single-table sort key format.
  *
  * @template T - The type of the entity being queried, extending `DynaRecord`.
- * @property {KeyConditions} - Conditions applied to entity keys. Each key in the entity can have conditions such as equality, range conditions, or begins with conditions.
  */
-export type EntityKeyConditions<T> = {
+export type EntityKeyConditions<T extends DynaRecord = DynaRecord> = {
     [K in keyof T as T[K] extends PartitionKey ? K : never]-?: string;
 } & {
-    [K in keyof T as T[K] extends SortKey ? K : never]?: string | BeginsWithFilter;
+    [K in keyof T as T[K] extends SortKey ? K : never]?: TypedSortKeyCondition<T>;
 };
 /**
  * Key conditions when querying on an index. Can be any attribute on the entity but must be the keys of the given index
@@ -96,5 +113,283 @@ export type QueryResult<T extends DynaRecord> = QueryResults<T>[number];
  * When querying the main table this will enforce that the keys are the PartitionKey and SortKey from the table
  * When querying an index, this can be any key on the table, but must be the keys for that index
  */
-export type EntityQueryKeyConditions<T> = EntityKeyConditions<T> | IndexKeyConditions<T>;
+export type EntityQueryKeyConditions<T extends DynaRecord = DynaRecord> = EntityKeyConditions<T> | IndexKeyConditions<T>;
+/**
+ * Union of T itself and all entity types reachable through its declared relationships
+ * (`@HasMany`, `@HasOne`, `@BelongsTo`, `@HasAndBelongsToMany`).
+ *
+ * This defines which entities can appear in a partition query's `type` filter,
+ * `skCondition`, and `sk` key conditions. Only the entity itself and its direct
+ * relationships are included — entities from other tables or unrelated entities
+ * on the same table are excluded.
+ *
+ * E.g. for Customer with HasMany Order/PaymentMethod and HasOne ContactInformation:
+ * `Customer | Order | PaymentMethod | ContactInformation`
+ */
+export type PartitionEntities<T extends DynaRecord> = T | RelationshipEntities<T>;
+/**
+ * Union of entity name string literals for the entity and its related entities.
+ * These are the only valid values for the `type` filter field, `skCondition`, and
+ * the `sk` property in key conditions.
+ *
+ * Falls back to `string` if any entity lacks `declare readonly type`.
+ */
+export type PartitionEntityNames<T extends DynaRecord> = PartitionEntities<T>["type"];
+/**
+ * Union of EntityFilterableKeys<E> for each entity E in PartitionEntities<T>.
+ * This is the full set of valid filter keys when no `type` narrowing is applied.
+ */
+export type AllPartitionFilterableKeys<T extends DynaRecord> = PartitionEntities<T> extends infer E ? E extends DynaRecord ? EntityFilterableKeys<E> : never : never;
+/**
+ * Maps a union of string keys to an optional FilterTypes record.
+ * Shared helper for building filter records from key unions.
+ *
+ * @template Keys - The union of string keys to include in the record.
+ */
+type FilterRecord<Keys extends string> = {
+    [K in Keys]?: FilterTypes;
+};
+/**
+ * Filter record scoped to a single entity's attributes.
+ *
+ * @template E - The entity type whose attributes form the record keys.
+ */
+export type EntityFilterRecord<E extends DynaRecord> = FilterRecord<EntityFilterableKeys<E>>;
+/**
+ * Filter record for all entities in a partition (union of all filter keys).
+ *
+ * @template T - The root entity whose partition defines the filter keys.
+ */
+type FullPartitionFilterRecord<T extends DynaRecord> = FilterRecord<AllPartitionFilterableKeys<T>>;
+/**
+ * Discriminated union enabling per-block `type` narrowing.
+ * When type is a single string literal, only that entity's attributes are allowed.
+ * When type is an array or absent, all partition attributes are allowed.
+ * The `type` field is handled separately from other filter keys to enable narrowing.
+ */
+export type TypedAndFilter<T extends DynaRecord> = (PartitionEntities<T> extends infer E ? E extends DynaRecord ? {
+    type: E["type"];
+} & EntityFilterRecord<E> : never : never) | ({
+    type: PartitionEntityNames<T>[];
+} & FullPartitionFilterRecord<T>) | ({
+    type?: never;
+} & FullPartitionFilterRecord<T>);
+/**
+ * Typed `$or` filter block for partition queries.
+ * Each `$or` element is independently narrowed: when a block specifies
+ * `type: "Order"`, only Order's attributes are accepted in that block.
+ *
+ * @template T - The root entity whose partition defines valid filter keys and type values.
+ */
+export type TypedOrFilter<T extends DynaRecord> = {
+    $or?: TypedAndFilter<T>[];
+};
+/**
+ * Top-level filter combining AND and OR.
+ */
+export type TypedFilterParams<T extends DynaRecord> = TypedAndFilter<T> & TypedOrFilter<T>;
+/**
+ * Typed sort key condition for querying within an entity's partition.
+ *
+ * In dyna-record's single-table design, sort key values always start with an entity
+ * class name — either the entity itself or one of its declared relationships
+ * (`@HasMany`, `@HasOne`, `@BelongsTo`, `@HasAndBelongsToMany`):
+ * - Self/HasOne records: `SK = "EntityName"` (exact entity name)
+ * - HasMany records: `SK = "EntityName#id"` (entity name + delimiter + id)
+ *
+ * This type restricts `skCondition` and the `sk` key condition to only accept the
+ * entity's own name or its related entity names (or prefixes thereof). Unrelated
+ * entities and entities from other tables are rejected at compile time.
+ *
+ * @template T - The entity type being queried.
+ */
+export type TypedSortKeyCondition<T extends DynaRecord> = PartitionEntityNames<T> | `${PartitionEntityNames<T>}${string}` | {
+    $beginsWith: PartitionEntityNames<T> | `${PartitionEntityNames<T>}${string}`;
+};
+/**
+ * Extracts the entity name from a typed sort key condition for return type narrowing.
+ *
+ * Narrows when:
+ * - SK is an exact entity name: `"Order"` → `"Order"`
+ * - SK is `{ $beginsWith: "Order" }` → `"Order"`
+ *
+ * Does not narrow when:
+ * - SK is a prefixed string like `"Order#123"` (can't parse the delimiter at type level)
+ * - SK is `{ $beginsWith: "Order#..." }` (specific prefix, not just entity name)
+ *
+ * @template T - The entity type being queried.
+ * @template SK - The inferred sort key condition literal type.
+ */
+export type ExtractEntityFromSK<T extends DynaRecord, SK> = SK extends {
+    $beginsWith: infer V extends PartitionEntityNames<T>;
+} ? V : SK extends PartitionEntityNames<T> ? SK : never;
+/**
+ * Extracts string values from a type that may be a string or an array of strings.
+ * Returns the literal string if single value, array element types if array, or `never`.
+ *
+ * @template V - The value to extract strings from.
+ */
+type ExtractStringOrArrayStrings<V> = V extends string ? V : V extends Array<infer U extends string> ? U : never;
+/**
+ * Extracts the `type` value from a filter object.
+ * Returns the literal string if single value, array element types if array, or `never`.
+ *
+ * @template F - The filter object to extract from.
+ */
+export type ExtractTypeFromFilter<F> = F extends {
+    type: infer V;
+} ? ExtractStringOrArrayStrings<V> : never;
+/**
+ * Maps entity name string → entity type.
+ *
+ * @template T - The root entity being queried.
+ * @template Name - The entity name string literal to resolve.
+ */
+export type ResolveEntityByName<T extends DynaRecord, Name extends string> = Extract<PartitionEntities<T>, {
+    type: Name;
+}>;
+/**
+ * Distributes EntityAttributesInstance over a union of DynaRecord types.
+ */
+type DistributeEntityAttributes<E> = E extends DynaRecord ? EntityAttributesInstance<E> : never;
+/**
+ * Narrows query results to specific entity types identified by name.
+ * Falls back to QueryResults<T> if names don't resolve to known entities.
+ *
+ * @template T - The root entity being queried.
+ * @template Names - Union of entity name string literals to narrow to.
+ */
+type NarrowByNames<T extends DynaRecord, Names extends string> = [
+    ResolveEntityByName<T, Names>
+] extends [never] ? QueryResults<T> : Array<DistributeEntityAttributes<ResolveEntityByName<T, Names>>>;
+/**
+ * Narrows query results based on the `type` value extracted from a filter object.
+ * If the filter's `type` resolves to specific entity names, returns an array of
+ * those entity attribute types. Otherwise falls back to the full `QueryResults<T>` union.
+ *
+ * @template T - The root entity being queried.
+ * @template F - The filter object from which `type` is extracted.
+ */
+export type NarrowedQueryResults<T extends DynaRecord, F> = ExtractTypeFromFilter<F> extends infer Names extends string ? NarrowByNames<T, Names> : QueryResults<T>;
+/**
+ * Extracts non-special filter keys from a filter object (excludes `type` and `$or`).
+ *
+ * @template F - The filter object to extract keys from.
+ */
+type FilterKeysOf<F> = Exclude<keyof F & string, "type" | "$or">;
+/**
+ * Finds partition entities that have ALL the specified filter keys as filterable attributes.
+ * Returns the full `PartitionEntities` when Keys is `never` (no filter keys specified).
+ *
+ * @template T - The root entity being queried.
+ * @template Keys - Union of filter key strings that must all be present on the entity.
+ */
+type EntitiesWithAllKeys<T extends DynaRecord, Keys extends string> = [
+    Keys
+] extends [never] ? PartitionEntities<T> : PartitionEntities<T> extends infer E ? E extends DynaRecord ? [Keys] extends [EntityFilterableKeys<E>] ? E : never : never : never;
+/**
+ * Resolves the entity name strings for entities that have ALL the specified filter keys.
+ *
+ * @template T - The root entity being queried.
+ * @template Keys - Union of filter key strings.
+ */
+type EntityNamesFromKeys<T extends DynaRecord, Keys extends string> = EntitiesWithAllKeys<T, Keys>["type"];
+/**
+ * Resolves a single filter block to entity name strings.
+ * If the block has a `type` field with specific entity names, uses those.
+ * Otherwise, narrows by finding entities that have ALL the block's non-special filter keys.
+ *
+ * @template T - The root entity being queried.
+ * @template Block - The filter block object.
+ */
+type ResolveBlockEntityNames<T extends DynaRecord, Block> = IsAny<ExtractTypeFromFilter<Block>> extends true ? EntityNamesFromKeys<T, FilterKeysOf<Block>> : [ExtractTypeFromFilter<Block>] extends [never] ? EntityNamesFromKeys<T, FilterKeysOf<Block>> : ExtractTypeFromFilter<Block>;
+/**
+ * Resolves `$or` blocks to entity name strings. For each `$or` element, resolves
+ * to entity names by `type` (if present) or by filter keys (if no `type`).
+ * Returns the union of entity names across all `$or` blocks.
+ *
+ * @template T - The root entity being queried.
+ * @template F - The filter object containing `$or`.
+ */
+type ResolveOrBlockEntityNames<T extends DynaRecord, F> = F extends {
+    $or?: Array<infer OrElement>;
+} ? OrElement extends infer Block extends object ? ResolveBlockEntityNames<T, Block> : never : never;
+/**
+ * Determines whether `Names` represents a meaningful narrowing of the partition.
+ * Returns `true` if `Names` is a specific subset of partition entity names,
+ * `false` otherwise.
+ *
+ * A narrowing is meaningful when `Names` is:
+ * - Not `any` (from AWS SDK's `NativeAttributeValue` propagation)
+ * - Not `never` (no resolution)
+ * - Not the full partition union (no narrowing effect)
+ *
+ * This guard is shared across the inference chain to avoid duplicating the
+ * three-check pattern (IsAny / never / full-union) at each fallback level.
+ *
+ * @template T - The root entity being queried.
+ * @template Names - The resolved entity name union to check.
+ */
+type ShouldNarrow<T extends DynaRecord, Names> = IsAny<Names> extends true ? false : [Names] extends [never] ? false : [Names] extends [string] ? [PartitionEntityNames<T>] extends [Names] ? false : true : false;
+/**
+ * Falls back to SK narrowing, then to full union.
+ */
+type FallbackToSK<T extends DynaRecord, SK> = ExtractEntityFromSK<T, SK> extends infer Names ? ShouldNarrow<T, Names> extends true ? NarrowByNames<T, Names & string> : QueryResults<T> : QueryResults<T>;
+/**
+ * Narrows by names, but returns `never[]` when names resolve to no known entities.
+ * Unlike {@link NarrowByNames} which falls back to `QueryResults<T>` when names
+ * don't resolve, this returns an empty array type — used when an intersection of
+ * AND-combined narrowing signals is empty (no entity can satisfy all conditions).
+ */
+type StrictNarrowByNames<T extends DynaRecord, Names extends string> = [
+    ResolveEntityByName<T, Names>
+] extends [never] ? never[] : Array<DistributeEntityAttributes<ResolveEntityByName<T, Names>>>;
+/**
+ * When top-level filter keys narrow to `KeyNames`, also checks if `$or` blocks
+ * narrow independently. Since DynamoDB ANDs top-level conditions with `$or`,
+ * a record must satisfy both — so the matching entities are the intersection.
+ *
+ * - If `$or` also narrows → intersect with `KeyNames`. Empty intersection → `never[]`.
+ * - If `$or` does not narrow → use `KeyNames` alone.
+ */
+type IntersectKeysWithOr<T extends DynaRecord, KeyNames extends string, F> = ResolveOrBlockEntityNames<T, F> extends infer OrNames ? ShouldNarrow<T, OrNames> extends true ? StrictNarrowByNames<T, Extract<KeyNames, OrNames & string>> : NarrowByNames<T, KeyNames> : NarrowByNames<T, KeyNames>;
+/**
+ * Falls back to `$or` block resolution (by type or filter keys), then SK, then full union.
+ */
+type FallbackToOrBlocks<T extends DynaRecord, F, SK> = ResolveOrBlockEntityNames<T, F> extends infer Names ? ShouldNarrow<T, Names> extends true ? NarrowByNames<T, Names & string> : FallbackToSK<T, SK> : FallbackToSK<T, SK>;
+/**
+ * Falls back to top-level filter key resolution, then `$or`, then SK, then full union.
+ *
+ * When top-level keys narrow, also intersects with `$or` block narrowing (if any)
+ * because DynamoDB ANDs them — a record must satisfy both the top-level filter
+ * and at least one `$or` block.
+ */
+type FallbackToFilterKeys<T extends DynaRecord, F, SK> = EntityNamesFromKeys<T, FilterKeysOf<F>> extends infer Names ? ShouldNarrow<T, Names> extends true ? IntersectKeysWithOr<T, Names & string, F> : FallbackToOrBlocks<T, F, SK> : FallbackToOrBlocks<T, F, SK>;
+/**
+ * When a top-level `type` filter narrows, also checks if `$or` blocks narrow
+ * to a disjoint set. Since DynamoDB ANDs them, the result is the intersection.
+ */
+type IntersectTypeWithOr<T extends DynaRecord, F> = ResolveOrBlockEntityNames<T, F> extends infer OrNames ? ShouldNarrow<T, OrNames> extends true ? StrictNarrowByNames<T, Extract<ExtractTypeFromFilter<F> & string, OrNames & string>> : NarrowedQueryResults<T, F> : NarrowedQueryResults<T, F>;
+/**
+ * Infers query results from filter and SK for the non-index query overload.
+ *
+ * Narrowing strategy (respects DynamoDB's AND semantics):
+ * 1. If the filter specifies a top-level `type` value, narrow by that — then intersect
+ *    with `$or` narrowing if present (since DynamoDB ANDs them).
+ * 2. Otherwise, if top-level filter keys narrow to specific entities, use that — then
+ *    intersect with `$or` narrowing if present.
+ * 3. Otherwise, if `$or` blocks resolve to specific entities (by type or keys), use that.
+ * 4. Otherwise, if `skCondition` matches an exact entity name or `$beginsWith` an entity name, narrow by that.
+ * 5. Otherwise, return the full `QueryResults<T>` union.
+ *
+ * When both top-level (type or keys) and `$or` narrow to different entity sets,
+ * the intersection is taken. An empty intersection produces `never[]`, reflecting
+ * that no DynamoDB record can satisfy both AND-combined conditions.
+ *
+ * @template T - The root entity being queried.
+ * @template F - The inferred filter type (captured via `const` generic).
+ * @template SK - The inferred sort key condition type.
+ */
+export type InferQueryResults<T extends DynaRecord, F, SK = unknown> = ExtractTypeFromFilter<F> extends infer Names ? ShouldNarrow<T, Names> extends true ? IntersectTypeWithOr<T, F> : FallbackToFilterKeys<T, F, SK> : FallbackToFilterKeys<T, F, SK>;
+export {};
 //# sourceMappingURL=types.d.ts.map

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

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

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

@@ -66,4 +66,47 @@ export type EntityAttributeDefaultFields = Pick<DynaRecord, Extract<keyof DynaRe
  *   - Functions defined on the entity
  */
 export type EntityDefinedAttributes<T extends DynaRecord> = Omit<ForeignKeyToValue<T>, keyof DynaRecord | RelationshipAttributeNames<T> | FunctionFields<T> | PartitionKeyAttribute<T> | SortKeyAttribute<T>>;
+/**
+ * Types that terminate dot-path recursion. These are considered leaf types
+ * that should not be recursed into when generating filter key paths.
+ */
+export type NonRecursiveLeaf = Date | unknown[] | DynaRecord | ((...args: never[]) => unknown);
+/**
+ * Maximum recursion depth for {@link DotPathKeys}.
+ * Set to 5 to cover realistic DynamoDB Map attribute nesting (typically 2-3 levels)
+ * while staying well below TypeScript's internal instantiation depth limit of 50.
+ * Higher values risk combinatorial explosion with wide object schemas.
+ */
+type MaxDotPathDepth = 5;
+/**
+ * Recursively generates dot-separated key paths for plain object types.
+ * Stops recursion at {@link NonRecursiveLeaf} types and at {@link MaxDotPathDepth} levels
+ * to prevent "Type instantiation is excessively deep" errors.
+ *
+ * @template T - The object type to generate paths for.
+ * @template Depth - Internal depth counter (tuple). Do not provide externally.
+ */
+export type DotPathKeys<T, Depth extends unknown[] = []> = Depth["length"] extends MaxDotPathDepth ? never : T extends NonRecursiveLeaf ? never : T extends object ? {
+    [K in keyof T & string]: K | (DotPathKeys<T[K], [...Depth, unknown]> extends infer D extends string ? `${K}.${D}` : never);
+}[keyof T & string] : never;
+/**
+ * For a given entity, produces all dot-path keys for its ObjectAttribute fields.
+ * Checks each property: if it's a plain object (not a {@link NonRecursiveLeaf}),
+ * generates "propName.nestedKey" paths.
+ */
+export type ObjectDotPaths<T extends DynaRecord> = {
+    [K in keyof T & string]: Exclude<T[K], undefined> extends infer V ? V extends NonRecursiveLeaf ? never : V extends object ? DotPathKeys<V> extends infer D extends string ? `${K}.${D}` : never : never : never;
+}[keyof T & string];
+/**
+ * Union of: non-relationship/non-function/non-key attribute names + ObjectDotPaths.
+ * This is the complete set of valid filter keys for a single entity.
+ *
+ * Excludes:
+ * - Relationship properties (via {@link EntityAttributesOnly})
+ * - Function fields (via {@link EntityAttributesOnly})
+ * - PartitionKeyAttribute and SortKeyAttribute
+ * - `type` (handled separately by {@link TypedAndFilter} for discriminated union narrowing)
+ */
+export type EntityFilterableKeys<T extends DynaRecord> = Exclude<keyof EntityAttributesOnly<T> & string, PartitionKeyAttribute<T> | SortKeyAttribute<T> | "type"> | ObjectDotPaths<T>;
+export {};
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/operations/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,QAAQ,EACR,YAAY,EACZ,OAAO,EACR,MAAM,UAAU,CAAC;AAElB;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;KACpC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,YAAY,GAAG,CAAC,GAAG,KAAK;CACtD,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;KAC/B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,GAAG,KAAK;CACjD,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;KAC7B,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK;CACvE,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;KAChC,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,kBAAkB,GAC3C,QAAQ,CAAC,MAAM,CAAC,GAChB,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,GACrB,MAAM,GACN,CAAC,CAAC,CAAC,CAAC;CACX,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;KACzC,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,SAAS,UAAU,GAAG,UAAU,EAAE,GACtE,CAAC,GACD,KAAK;CACV,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,UAAU,IAAI,IAAI,CAC/D,CAAC,EACD,0BAA0B,CAAC,CAAC,CAAC,CAC9B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,UAAU,IAAI,IAAI,CAC3D,CAAC,EACD,0BAA0B,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAClD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAC7C,UAAU,EACV,OAAO,CAAC,MAAM,UAAU,EAAE,aAAa,CAAC,CACzC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,UAAU,IAAI,IAAI,CAC9D,iBAAiB,CAAC,CAAC,CAAC,EAClB,MAAM,UAAU,GAChB,0BAA0B,CAAC,CAAC,CAAC,GAC7B,cAAc,CAAC,CAAC,CAAC,GACjB,qBAAqB,CAAC,CAAC,CAAC,GACxB,gBAAgB,CAAC,CAAC,CAAC,CACtB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/operations/types.ts"],"names":[],"mappings":"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"}

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,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;IAgBtC;;;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;IAkCpB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA0BvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAehB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;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"}
+{"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;IAgBtC;;;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;IAkCpB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IAkCvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAehB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAUnB;;;;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

@@ -190,6 +190,10 @@ class QueryBuilder {
     resolveAttrPath(key) {
         const segments = key.split(".");
         const topLevelKey = segments[0];
+        if (!(topLevelKey in this.#attributeMetadata)) {
+            throw new Error(`Invalid filter key "${key}": attribute "${topLevelKey}" does not exist on this entity. ` +
+                `Valid attributes are: ${Object.keys(this.#attributeMetadata).join(", ")}`);
+        }
         const tableKey = this.#attributeMetadata[topLevelKey].alias;
         const names = { [`#${tableKey}`]: tableKey };
         if (segments.length === 1) {

package/dist/src/types.d.ts

@@ -69,7 +69,16 @@ export interface RelationshipMetaObj {
  */
 export type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 /**
- * Represents an instance of a class decorated with the `Entity` decorator in DynaRecord, encapsulating entity logic.
+ * Detects the `any` type. Resolves to `true` when T is `any`, `false` otherwise.
+ * Used internally to guard against `any` propagation from AWS SDK's `NativeAttributeValue`.
+ */
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * Represents the constructor type of a class decorated with the `@Entity` decorator.
+ *
+ * The `@Entity` decorator enforces at compile time that each entity declares
+ * `readonly type` as a string literal matching the class name. If the declaration
+ * is missing, the decorator produces a type error. See {@link Entity} for details.
  */
 export type EntityClass<T> = (new () => T) & typeof DynaRecord;
 /**

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,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"}
+{"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;;;GAGG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAEtD;;;;;;GAMG;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/package.json

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