dyna-record 0.5.3 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # Dyna-Record
 
-[API Documentation](https://dyna-record.com/)
+[API Documentation](https://docs.dyna-record.com/)
 
 [Medium Article](https://medium.com/@drewdavis888/unlock-relational-data-modeling-in-dynamodb-with-dyna-record-5b9cce27c3ce)
 
@@ -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)
@@ -50,9 +51,9 @@ Entities in Dyna-Record represent your DynamoDB table structure and relationship
 
 ### Table
 
-[Docs](https://dyna-record.com/functions/Table.html)
+[Docs](https://docs.dyna-record.com/functions/Table.html)
 
-Create a table class that extends [DynaRecord base class](https://dyna-record.com/classes/default.html) and is decorated with the [Table decorator](https://dyna-record.com/functions/Table.html). At a minimum, the table class must define the [PartitionKeyAttribute](https://dyna-record.com/functions/PartitionKeyAttribute.html) and [SortKeyAttribute](https://dyna-record.com/functions/SortKeyAttribute.html).
+Create a table class that extends [DynaRecord base class](https://docs.dyna-record.com/classes/default.html) and is decorated with the [Table decorator](https://docs.dyna-record.com/functions/Table.html). At a minimum, the table class must define the [PartitionKeyAttribute](https://docs.dyna-record.com/functions/PartitionKeyAttribute.html) and [SortKeyAttribute](https://docs.dyna-record.com/functions/SortKeyAttribute.html).
 
 #### Basic usage
 
@@ -107,56 +108,64 @@ abstract class MyTable extends DynaRecord {
 
 ### Entity
 
-[Docs](https://dyna-record.com/functions/Entity.html)
+[Docs](https://docs.dyna-record.com/functions/Entity.html)
 
 Each entity must extend the Table class. To support single table design patterns, they must extend the same tables class.
 
-By default, each entity will have [default attributes](https://dyna-record.com/types/_internal_.DefaultFields.html)
+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://docs.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
-- [updatedAt](https://dyna-record.com/classes/default.html#updatedAt) - Timestamp of when the entity was updated last
+- [id](https://docs.dyna-record.com/classes/default.html#id) - The id for the model. This will be an autogenerated uuid unless [IdAttribute](<(https://docs.dyna-record.com/functions/IdAttribute.html)>) is set on a non-nullable entity attribute.
+- [type](https://docs.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://docs.dyna-record.com/classes/default.html#createdAt) - The timestamp of when the entity was created
+- [updatedAt](https://docs.dyna-record.com/classes/default.html#updatedAt) - Timestamp of when the entity was updated last
 
 ```typescript
 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.
 
 - Attribute decorators
 
-  - [@StringAttribute](https://dyna-record.com/functions/StringAttribute.html)
-  - [@NumberAttribute](https://dyna-record.com/functions/NumberAttribute.html)
-  - [@BooleanAttribute](https://dyna-record.com/functions/BooleanAttribute.html)
-  - [@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)
+  - [@StringAttribute](https://docs.dyna-record.com/functions/StringAttribute.html)
+  - [@NumberAttribute](https://docs.dyna-record.com/functions/NumberAttribute.html)
+  - [@BooleanAttribute](https://docs.dyna-record.com/functions/BooleanAttribute.html)
+  - [@DateAttribute](https://docs.dyna-record.com/functions/DateAttribute.html)
+  - [@EnumAttribute](https://docs.dyna-record.com/functions/EnumAttribute.html)
+  - [@IdAttribute](https://docs.dyna-record.com/functions/IdAttribute.html)
+  - [@ObjectAttribute](https://docs.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.
+- The [alias](https://docs.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
-- Attempting to remove a non-nullable attribute will result in a [NullConstrainViolationError](https://dyna-record.com/classes/NullConstraintViolationError.html)
+- Attempting to remove a non-nullable attribute will result in a [NullConstrainViolationError](https://docs.dyna-record.com/classes/NullConstraintViolationError.html)
 
 ```typescript
 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>;
 }
@@ -240,11 +251,11 @@ The schema must be declared with `as const satisfies ObjectSchema` so TypeScript
 
 ### 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.
+Define foreign keys in order to support [@BelongsTo](https://docs.dyna-record.com/functions/BelongsTo.html) relationships. A foreign key is required for [@HasOne](https://docs.dyna-record.com/functions/HasOne.html) and [@HasMany](https://docs.dyna-record.com/functions/HasMany.html) relationships.
 
-- 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.
+- The [alias](https://docs.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 foreign key attributes as optional for optimal type safety
-- Attempting to remove an entity from a non-nullable foreign key will result in a [NullConstrainViolationError](https://dyna-record.com/classes/NullConstraintViolationError.html)
+- Attempting to remove an entity from a non-nullable foreign key will result in a [NullConstrainViolationError](https://docs.dyna-record.com/classes/NullConstraintViolationError.html)
 - Always provide the referenced entity class to `@ForeignKeyAttribute` (for example `@ForeignKeyAttribute(() => Customer)`); this allows DynaRecord to enforce referential integrity even when no relationship decorator is defined.
 - `Create` and `Update` automatically add DynamoDB condition checks for standalone foreign keys (those without a relationship decorator) to ensure the referenced entity exists, enabling referential integrity even when no denormalised access pattern is required.
 
@@ -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
 
@@ -278,16 +293,16 @@ class Course extends MyTable {
 
 ### Relationships
 
-Dyna-Record supports defining relationships between entities such as [@HasOne](https://dyna-record.com/functions/HasOne.html), [@HasMany](https://dyna-record.com/functions/HasMany.html), [@BelongsTo](https://dyna-record.com/functions/BelongsTo.html) and [@HasAndBelongsToMany](https://dyna-record.com/functions/HasAndBelongsToMany.html). It does this by de-normalizing records to each of its related entities partitions.
+Dyna-Record supports defining relationships between entities such as [@HasOne](https://docs.dyna-record.com/functions/HasOne.html), [@HasMany](https://docs.dyna-record.com/functions/HasMany.html), [@BelongsTo](https://docs.dyna-record.com/functions/BelongsTo.html) and [@HasAndBelongsToMany](https://docs.dyna-record.com/functions/HasAndBelongsToMany.html). It does this by de-normalizing records to each of its related entities partitions.
 
-A relationship can be defined as nullable or non-nullable. Non-nullable relationships will be enforced via transactions and violations will result in [NullConstraintViolationError](https://dyna-record.com/classes/NullConstraintViolationError.html)
+A relationship can be defined as nullable or non-nullable. Non-nullable relationships will be enforced via transactions and violations will result in [NullConstraintViolationError](https://docs.dyna-record.com/classes/NullConstraintViolationError.html)
 
-- [@ForeignKeyAttribute](https://dyna-record.com/functions/ForeignKeyAttribute.html) is used to define a foreign key that links to another entity
-- Relationship decorators ([@HasOne](#hasone), [@HasMany](#hasmany), [@BelongsTo](https://dyna-record.com/functions/BelongsTo.html), [@HasAndBelongsToMany](#hasandbelongstomany)) define how entities relate to each other.
+- [@ForeignKeyAttribute](https://docs.dyna-record.com/functions/ForeignKeyAttribute.html) is used to define a foreign key that links to another entity
+- Relationship decorators ([@HasOne](#hasone), [@HasMany](#hasmany), [@BelongsTo](https://docs.dyna-record.com/functions/BelongsTo.html), [@HasAndBelongsToMany](#hasandbelongstomany)) define how entities relate to each other.
 
 #### HasOne
 
-[Docs](https://dyna-record.com/functions/HasOne.html)
+[Docs](https://docs.dyna-record.com/functions/HasOne.html)
 
 ```typescript
 import {
@@ -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>;
 
@@ -318,13 +337,15 @@ class Grade extends MyTable {
 
 ### HasMany
 
-[Docs](https://dyna-record.com/functions/HasMany.html)
+[Docs](https://docs.dyna-record.com/functions/HasMany.html)
 
 ```typescript
 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
 }
@@ -364,9 +391,9 @@ class Course extends MyTable {
 
 ### HasAndBelongsToMany
 
-[Docs](https://dyna-record.com/functions/HasAndBelongsToMany.html)
+[Docs](https://docs.dyna-record.com/functions/HasAndBelongsToMany.html)
 
-HasAndBelongsToMany relationships require a [JoinTable](https://dyna-record.com/classes/JoinTable.html) class. This represents a virtual table to support the relationship
+HasAndBelongsToMany relationships require a [JoinTable](https://docs.dyna-record.com/classes/JoinTable.html) class. This represents a virtual table to support the relationship
 
 ```typescript
 import {
@@ -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" })
@@ -404,9 +435,9 @@ class Student extends OtherTable {
 
 ### Create
 
-[Docs](https://dyna-record.com/classes/default.html#create)
+[Docs](https://docs.dyna-record.com/classes/default.html#create)
 
-The create method is used to insert a new record into a DynamoDB table. This method automatically handles key generation (using UUIDs or custom id field if [IdAttribute](<(https://dyna-record.com/functions/IdAttribute.html)>) is set), timestamps for [createdAt](https://dyna-record.com/classes/default.html#createdAt) and [updatedAt](https://dyna-record.com/classes/default.html#updatedAt) fields, and the management of relationships between entities. It leverages AWS SDK's [TransactWriteCommand](https://www.google.com/search?q=aws+transact+write+command&oq=aws+transact+write+command&gs_lcrp=EgZjaHJvbWUyBggAEEUYOTIGCAEQRRg7MgYIAhBFGDvSAQgzMjAzajBqN6gCALACAA&sourceid=chrome&ie=UTF-8) for transactional integrity, ensuring either complete success or rollback in case of any failure. The method handles conditional checks to ensure data integrity and consistency during creation. If a foreignKey is set on create, dyna-record will de-normalize the data required in order to support the relationship
+The create method is used to insert a new record into a DynamoDB table. This method automatically handles key generation (using UUIDs or custom id field if [IdAttribute](<(https://docs.dyna-record.com/functions/IdAttribute.html)>) is set), timestamps for [createdAt](https://docs.dyna-record.com/classes/default.html#createdAt) and [updatedAt](https://docs.dyna-record.com/classes/default.html#updatedAt) fields, and the management of relationships between entities. It leverages AWS SDK's [TransactWriteCommand](https://www.google.com/search?q=aws+transact+write+command&oq=aws+transact+write+command&gs_lcrp=EgZjaHJvbWUyBggAEEUYOTIGCAEQRRg7MgYIAhBFGDvSAQgzMjAzajBqN6gCALACAA&sourceid=chrome&ie=UTF-8) for transactional integrity, ensuring either complete success or rollback in case of any failure. The method handles conditional checks to ensure data integrity and consistency during creation. If a foreignKey is set on create, dyna-record will de-normalize the data required in order to support the relationship
 
 To use the create method, call it on the model class you wish to create a new record for. Pass the properties of the new record as an object argument to the method. Only attributes defined on the model can be configured, and will be enforced via types and runtime schema validation.
 
@@ -451,20 +482,20 @@ const grade: Grade = await Grade.create(
 
 #### Error handling
 
-The method is designed to throw errors under various conditions, such as transaction cancellation due to failed conditional checks. For instance, if you attempt to create a `Grade` for an `Assignment` that already has one, the method throws a [TransactionWriteFailedError](https://dyna-record.com/classes/TransactionWriteFailedError.html).
+The method is designed to throw errors under various conditions, such as transaction cancellation due to failed conditional checks. For instance, if you attempt to create a `Grade` for an `Assignment` that already has one, the method throws a [TransactionWriteFailedError](https://docs.dyna-record.com/classes/TransactionWriteFailedError.html).
 
 #### Notes
 
-- Automatic Timestamp Management: The [createdAt](https://dyna-record.com/classes/default.html#createdAt) and [updatedAt](https://dyna-record.com/classes/default.html#updatedAt) fields are managed automatically and reflect the time of creation and the last update, respectively.
-- Automatic ID Generation: Each entity created gets a unique [id](https://dyna-record.com/classes/default.html#id) generated by the uuidv4 method.
-  - This can be customized [IdAttribute](<(https://dyna-record.com/functions/IdAttribute.html)>) to support custom id attributes
+- Automatic Timestamp Management: The [createdAt](https://docs.dyna-record.com/classes/default.html#createdAt) and [updatedAt](https://docs.dyna-record.com/classes/default.html#updatedAt) fields are managed automatically and reflect the time of creation and the last update, respectively.
+- Automatic ID Generation: Each entity created gets a unique [id](https://docs.dyna-record.com/classes/default.html#id) generated by the uuidv4 method.
+  - This can be customized [IdAttribute](<(https://docs.dyna-record.com/functions/IdAttribute.html)>) to support custom id attributes
 - Relationship Management: The ORM manages entity relationships through DynamoDB's single-table design patterns, creating and maintaining the necessary links between related entities.
 - Conditional Checks: To ensure data integrity, the create method performs various conditional checks, such as verifying the existence of entities that new records relate to.
 - Error Handling: Errors during the creation process are handled gracefully, with specific errors thrown for different failure scenarios, such as conditional check failures or transaction cancellations.
 
 ### FindById
 
-[Docs](https://dyna-record.com/classes/default.html#findById)
+[Docs](https://docs.dyna-record.com/classes/default.html#findById)
 
 Retrieve a single record by its primary key.
 
@@ -498,7 +529,7 @@ const course = await Course.findById("123", {
 
 ### Query
 
-[Docs](https://dyna-record.com/classes/default.html#query)
+[Docs](https://docs.dyna-record.com/classes/default.html#query)
 
 The query method is a versatile tool for querying data from DynamoDB tables using primary key conditions and various optional filters. This method enables fetching multiple items that match specific criteria, making it ideal for situations where more than one item needs to be retrieved based on attributes of the primary key (partition key and sort key).
 
@@ -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.
@@ -648,7 +835,7 @@ const result = await Customer.query(
 
 ### Update
 
-[Docs](https://dyna-record.com/classes/default.html#update)
+[Docs](https://docs.dyna-record.com/classes/default.html#update)
 
 The update method enables modifications to existing items in a DynamoDB table. It supports updating simple attributes, handling nullable fields, and managing relationships between entities, including updating and removing foreign keys. Only attributes defined on the model can be updated, and will be enforced via types and runtime schema validation.
 
@@ -663,7 +850,7 @@ await Customer.update("123", {
 
 #### Removing attributes
 
-Note: Attempting to remove a non nullable attribute will result in a [NullConstraintViolationError](https://dyna-record.com/classes/NullConstraintViolationError.html)
+Note: Attempting to remove a non nullable attribute will result in a [NullConstraintViolationError](https://docs.dyna-record.com/classes/NullConstraintViolationError.html)
 
 ```typescript
 await ContactInformation.update("123", {
@@ -686,7 +873,7 @@ await PaymentMethod.update("123", {
 
 Nullable foreign key references can be removed by setting them to null
 
-Note: Attempting to remove a non nullable foreign key will result in a [NullConstraintViolationError](https://dyna-record.com/classes/NullConstraintViolationError.html)
+Note: Attempting to remove a non nullable foreign key will result in a [NullConstraintViolationError](https://docs.dyna-record.com/classes/NullConstraintViolationError.html)
 
 ```typescript
 await Pet.update("123", {
@@ -780,7 +967,7 @@ const updatedInstance = await paymentMethodInstance.update(
 
 ### Delete
 
-[Docs](https://dyna-record.com/classes/default.html#delete)
+[Docs](https://docs.dyna-record.com/classes/default.html#delete)
 
 The delete method is used to remove an entity from a DynamoDB table, along with handling the deletion of associated items in relationships (like HasMany, HasOne, BelongsTo) to maintain the integrity of the database schema.
 
@@ -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