electrodb 2.1.2 → 2.2.0

package/.travis.yml

@@ -12,4 +12,4 @@ node_js:
   - '16'
 
 script:
-  - npm run coverage-coveralls-local
+  - npm run coverage:local:coveralls

package/README.md

@@ -333,7 +333,7 @@ If you're looking to get started right away with ElectroDB, checkout code exampl
 
 # Entities
 
-In ***ElectroDB*** an `Entity` is represents a single business object. For example, in a simple task tracking application, one Entity could represent an Employee and or a Task that is assigned to an employee.
+In ***ElectroDB*** an `Entity` represents a single business object. For example, in a simple task tracking application, one Entity could represent an Employee and or a Task that is assigned to an employee.
 
 Require or import `Entity` from `electrodb`:
 ```javascript  
@@ -1032,7 +1032,7 @@ signature               | behavior
 `(value: T) => void`    | A void or `undefined` value is returned, will be treated as successful, in this scenario you can throw an Error yourself to interrupt the query
 
 ## Indexes
-When using ElectroDB, indexes are referenced by their `AccessPatternName`. This allows you to maintain generic index names on your DynamoDB table, but reference domain specific names while using your ElectroDB Entity. These will often be referenced as _"Access Patterns"_.
+When using ElectroDB, indexes are referenced by their `AccessPatternName`. This allows you to maintain generic index names on your DynamoDB table, but reference domain specific names while using your ElectroDB Entity. These will be referenced as _"Access Patterns"_.
 
 All DynamoDB table start with at least a PartitionKey with an optional SortKey, this can be referred to as the _"Table Index"_. The `indexes` object requires at least the definition of this _Table Index_ **Partition Key** and (if applicable) **Sort Key**.
 
@@ -1045,8 +1045,11 @@ Within these _AccessPatterns_, you define the PartitionKey and (optionally) Sort
 ```typescript
 indexes: {
 	[AccessPatternName]: {
+		index?: string;
+		collection?: string | string[];
+		type?: 'isolated' | 'clustered';
 		pk: {
-			field: string; 
+			field: string;
 			composite: AttributeName[];
 			template?: string;
 		},
@@ -1055,14 +1058,15 @@ indexes: {
 			composite: AttributesName[];
             template?: string;
 		},
-		index?: string
-		collection?: string | string[]
 	}
 }
 ```
 
 | Property       | Type                                   | Required | Description |
 | -------------- | :------------------------------------: | :------: | ----------- |
+| `index`        | `string`                               | no       | Required when the `Index` defined is a *Global/Local Secondary Index*; but is omitted for the table's primary index.
+| `collection`   | `string`, `string[]`                   | no       | Used when models are joined to a `Service`. When two entities share a `collection` on the same `index`, they can be queried with one request to DynamoDB. The name of the collection should represent what the query would return as a pseudo `Entity`. (see [Collections](#collections) below for more on this functionality).
+| `type`         | `isolated`, `clustered`                | no       | Allows you to optimize your index for either [entity isolation](#isolated-indexes) (high volume of records per partition) or (entity relationships)[#clustered-indexes] (high relationship density per partition). When omitted, ElectroDB defaults to `isolation`.
 | `pk`           | `object`                               | yes      | Configuration for the pk of that index or table
 | `pk.composite` | `string[]`                             | yes      | An array that represents the order in which attributes are concatenated to composite attributes the key (see [Composite Attributes](#composite-attributes) below for more on this functionality).
 | `pk.template`  | `string`                               | no       | A string that represents the template in which attributes composed to form a key (see [Composite Attribute Templates](#composite-attribute-templates) below for more on this functionality).
@@ -1073,8 +1077,26 @@ indexes: {
 | `sk.template`  | `string`                               | no       | A string that represents the template in which attributes composed to form a key (see [Composite Attribute Templates](#composite-attribute-templates) below for more on this functionality).
 | `sk.field`     | `string`                               | yes      | The name of the index Sort Key field as it exists in DynamoDB, if named differently in the schema attributes.
 | `pk.casing`    | `default`, `upper`, `lower`, `none`,   | no       | Choose a case for ElectroDB to convert your keys to, to avoid casing pitfalls when querying data. Default: `lower`.
-| `index`        | `string`                               | no       | Required when the `Index` defined is a *Global/Local Secondary Index*; but is omitted for the table's primary index.
-| `collection`   | `string`, `string[]`                   | no       | Used when models are joined to a `Service`. When two entities share a `collection` on the same `index`, they can be queried with one request to DynamoDB. The name of the collection should represent what the query would return as a pseudo `Entity`. (see [Collections](#collections) below for more on this functionality).
+
+
+### Index Types
+ElectroDB helps manage your key structure, and works to abstract out the details of how your keys are created/formatted. Depending on your unique data set, you may need ElectroDB to optimize your index for either [entity isolation](#isolated-indexes) (i.e. high volume of records per partition) or (entity relationships)[#clustered-indexes] (i.e. high relationship density per partition).
+
+This option changes how ElectroDB formats your keys for storage, so it is an important consideration to make early in your modeling phase. As a result, this choice cannot be simply walked back without requiring a migration. The choice between `clustered` and `isolated` depends wholly on your unique dataset and access patterns.
+
+> _NOTE: You can use [Collections](#collections) with both `isolated` and `clustered` indexes. Isolated indexes are limited to only querying across the partition key while Clustered indexes can also leverage the Sort Key_
+
+#### Isolated Indexes
+By default, and when omitted, ElectroDB will create your index as an `isolated` index. Isolated indexes optimizes your index structure for faster and more efficient retrieval of items within an individual Entity.
+
+*Choose* `isolated` if you have strong access pattern requirements to retrieve only records for only your entity on that index. While an `isolated` index is more limited in its ability to be used in a [collection](#collections), it can perform better than a `clustered` index if a collection contains a highly unequal distribution of entities within a collection.
+*Don't choose* `isolated` if the primary use-cases for your index is to query across entities -- this index type does limit the extent to which indexes can be leveraged to improve query efficiency.
+
+#### Clustered Indexes
+When your index type is defined as `clustered`, ElectroDB will optimize your index for relationships within a partition. Clustered indexes optimize your index structure for more homogenous partitions, which allows for more efficient queries across multiple entities.
+
+*Choose* `clustered` if you have a high degree of grouped or similar data that needs to be frequently accessed together. This index works best in [collections](#collections) when member entities are more evenly distributed within a partition.
+*Don't choose* `clustered` if your need to query across entities is secondary to its primary purpose -- this index type limits the efficiency of querying your individual entity.
 
 ### Indexes Without Sort Keys
 When using indexes without Sort Keys, that should be expressed as an index *without* an `sk` property at all. Indexes without an `sk` cannot have a collection, see [Collections](#collections) for more detail.
@@ -1661,7 +1683,7 @@ await TaskApp.collections
 
 ### Collection Queries vs Entity Queries
 
-To query across entities, collection queries make use of ElectroDB's Sort Key structure, which prefixes Sort Key fields with the collection name. Unlike an Entity Query, Collection Queries only leverage [Composite Attributes](#composite-attributes) from an access pattern's Partition Key.  
+To query across entities, collection queries make use of ElectroDB's Sort Key structure, which prefixes Sort Key fields with the collection name. Unlike an Entity Query, Collection queries for [isolated indexes](#isolated-indexes) only leverage [Composite Attributes](#composite-attributes) from an access pattern's Partition Key, while Collection queries for [clustered indexes](#clustered-indexes) allow you to query on both Partition and Sort Keys.
 
 To better explain how Collection Queries are formed, here is a juxtaposition of an Entity Query's parameters vs a Collection Query's parameters:
 
@@ -1740,7 +1762,9 @@ Because the Tasks and Employee Entities both associated their index (`gsi2`) wit
 
 ## Sub-Collections
 
-Sub-Collections are an extension of [Collection](#collections) functionality that allow you to model more advanced access patterns. Collections and Sub-Collections are defined on [Indexes](#indexes) via a property called `collection`, as either a string or string array respectively. 
+Sub-Collections are an extension of [Collection](#collections) functionality that allow you to model more advanced access patterns. Collections and Sub-Collections are defined on [Indexes](#indexes) via a property called `collection`, as either a string or string array respectively.
+
+> _NOTE: Sub-Collections are only supported on ["isolated" index](#isolated-indexes) types _
 
 The following is an example of functionally identical collections, implemented as a string (referred to as a "collection") and then as a string array (referred to as sub-collections):
 
@@ -3624,7 +3648,7 @@ Equivalent DocClient Parameters:
 ### Patch Record
 
 ```javascript
-await entity.update({ attr1: "value1", attr2: "value2" })
+await entity.patch({ attr1: "value1", attr2: "value2" })
   .set({ attr4: "value4" })
   .go();
 ```
@@ -3668,7 +3692,7 @@ For more detail on how to use the `patch()` method, see the section [Update Reco
 
 ### Create Record
 
-In DynamoDB, `put` operations by default will overwrite a record if record being updated does not exist. In **_ElectroDB_**, the `patch` method will utilize the `attribute_not_exists()` parameter dynamically to ensure records are only "created" and not overwritten when inserting new records into the table.
+In DynamoDB, `put` operations by default will overwrite a record if record being updated does not exist. In **_ElectroDB_**, the `create` method will utilize the `attribute_not_exists()` parameter dynamically to ensure records are only "created" and not overwritten when inserting new records into the table.
 
 A Put operation will trigger the `default`, and `set` attribute callbacks when writing to DynamoDB. By default, after writing to DynamoDB, ElectroDB will format and return the record through the same process as a Get/Query, which will invoke the `get` callback on all included attributes. If this behaviour is not desired, use the [Query Option](#query-options) `response:"none"` to return a null value.
 

package/index.d.ts

@@ -24,6 +24,34 @@ export type AllCollectionNames<E extends {[name: string]: Entity<any, any, any,
         : never
 }[keyof E];
 
+export type ClusteredCollectionNames<E extends {[name: string]: Entity<any, any, any, any>}> = {
+    [Name in keyof E]:
+        E[Name] extends Entity<infer A, infer F, infer C, infer S>
+            ? {
+                [Collection in keyof ClusteredEntityCollections<A,F,C,S>]: Collection
+            }[keyof ClusteredEntityCollections<A,F,C,S>]
+            : never
+}[keyof E];
+
+export type IsolatedCollectionNames<E extends {[name: string]: Entity<any, any, any, any>}> = {
+    [Name in keyof E]:
+        E[Name] extends Entity<infer A, infer F, infer C, infer S>
+            ? {
+                [Collection in keyof IsolatedEntityCollections<A,F,C,S>]: Collection
+            }[keyof IsolatedEntityCollections<A,F,C,S>]
+            : never
+}[keyof E];
+
+export type IsolatedCollectionAssociations<E extends {[name: string]: Entity<any, any, any, any>}> = {
+    [Collection in IsolatedCollectionNames<E>]: {
+        [Name in keyof E]: E[Name] extends Entity<infer A, infer F, infer C, infer S>
+            ? Collection extends keyof IsolatedEntityCollections<A,F,C,S>
+                ? Name
+                : never
+            : never
+    }[keyof E];
+}
+
 export type AllEntityAttributeNames<E extends {[name: string]: Entity<any, any, any, any>}> = {
     [Name in keyof E]: {
         [A in keyof E[Name]["schema"]["attributes"]]: A
@@ -48,6 +76,16 @@ export type CollectionAssociations<E extends {[name: string]: Entity<any, any, a
     }[keyof E];
 }
 
+export type ClusteredCollectionAssociations<E extends {[name: string]: Entity<any, any, any, any>}> = {
+    [Collection in ClusteredCollectionNames<E>]: {
+        [Name in keyof E]: E[Name] extends Entity<infer A, infer F, infer C, infer S>
+            ? Collection extends keyof ClusteredEntityCollections<A,F,C,S>
+                ? Name
+                : never
+            : never
+    }[keyof E];
+}
+
 export type CollectionAttributes<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends CollectionAssociations<E>> = {
     [Collection in keyof Collections]: {
         [EntityName in keyof E]: E[EntityName] extends Entity<infer A, infer F, infer C, infer S>
@@ -58,6 +96,26 @@ export type CollectionAttributes<E extends {[name: string]: Entity<any, any, any
     }[keyof E]
 }
 
+export type ClusteredCollectionAttributes<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<E>> = {
+    [Collection in keyof Collections]: {
+        [EntityName in keyof E]: E[EntityName] extends Entity<infer A, infer F, infer C, infer S>
+            ? EntityName extends Collections[Collection]
+                ? keyof S["attributes"]
+                : never
+            : never
+    }[keyof E]
+}
+
+export type IsolatedCollectionAttributes<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends IsolatedCollectionAssociations<E>> = {
+    [Collection in keyof Collections]: {
+        [EntityName in keyof E]: E[EntityName] extends Entity<infer A, infer F, infer C, infer S>
+            ? EntityName extends Collections[Collection]
+                ? keyof S["attributes"]
+                : never
+            : never
+    }[keyof E]
+}
+
 export interface CollectionWhereOperations {
     eq: <T, A extends WhereAttributeSymbol<T>>(attr: A, value: T) => string;
     ne: <T, A extends WhereAttributeSymbol<T>>(attr: A, value: T) => string;
@@ -98,6 +156,28 @@ export type CollectionIndexKeys<Entities extends {[name: string]: Entity<any, an
     }[Collections[Collection]]
 }
 
+export type ClusteredCollectionIndexKeys<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<Entities>> = {
+    [Collection in keyof Collections]: {
+        [EntityResultName in Collections[Collection]]:
+            EntityResultName extends keyof Entities
+                ? Entities[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                ? keyof TableIndexCompositeAttributes<A, F, C, S>
+                : never
+                : never
+    }[Collections[Collection]]
+}
+
+export type IsolatedCollectionIndexKeys<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends IsolatedCollectionAssociations<Entities>> = {
+    [Collection in keyof Collections]: {
+        [EntityResultName in Collections[Collection]]:
+            EntityResultName extends keyof Entities
+                ? Entities[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                ? keyof TableIndexCompositeAttributes<A, F, C, S>
+                : never
+                : never
+    }[Collections[Collection]]
+}
+
 export type CollectionPageKeys<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends CollectionAssociations<Entities>> = {
     [Collection in keyof Collections]: {
         [EntityResultName in Collections[Collection]]:
@@ -113,6 +193,36 @@ export type CollectionPageKeys<Entities extends {[name: string]: Entity<any, any
     }[Collections[Collection]]
 }
 
+export type ClusteredCollectionPageKeys<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<Entities>> = {
+    [Collection in keyof Collections]: {
+        [EntityResultName in Collections[Collection]]:
+        EntityResultName extends keyof Entities
+            ? Entities[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+            ? keyof Parameters<Entities[EntityResultName]["query"][
+                Collection extends keyof ClusteredEntityCollections<A,F,C,S>
+                    ? ClusteredEntityCollections<A,F,C,S>[Collection]
+                    : never
+                ]>[0]
+            : never
+            : never
+    }[Collections[Collection]]
+}
+
+export type IsolatedCollectionPageKeys<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends IsolatedCollectionAssociations<Entities>> = {
+    [Collection in keyof Collections]: {
+        [EntityResultName in Collections[Collection]]:
+        EntityResultName extends keyof Entities
+            ? Entities[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+            ? keyof Parameters<Entities[EntityResultName]["query"][
+                Collection extends keyof IsolatedEntityCollections<A,F,C,S>
+                    ? IsolatedEntityCollections<A,F,C,S>[Collection]
+                    : never
+                ]>[0]
+            : never
+            : never
+    }[Collections[Collection]]
+}
+
 export type CollectionIndexAttributes<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends CollectionAssociations<Entities>> = {
     [Collection in keyof CollectionIndexKeys<Entities, Collections>]: {
         [key in CollectionIndexKeys<Entities, Collections>[Collection]]:
@@ -122,6 +232,24 @@ export type CollectionIndexAttributes<Entities extends {[name: string]: Entity<a
     }
 }
 
+export type ClusteredCollectionIndexAttributes<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<Entities>> = {
+    [Collection in keyof ClusteredCollectionIndexKeys<Entities, Collections>]: {
+        [Key in ClusteredCollectionIndexKeys<Entities, Collections>[Collection]]:
+        Key extends keyof AllEntityAttributes<Entities>
+            ? AllEntityAttributes<Entities>[Key]
+            : never
+    }
+}
+
+export type IsolatedCollectionIndexAttributes<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends IsolatedCollectionAssociations<Entities>> = {
+    [Collection in keyof IsolatedCollectionIndexKeys<Entities, Collections>]: {
+        [Key in IsolatedCollectionIndexKeys<Entities, Collections>[Collection]]:
+        Key extends keyof AllEntityAttributes<Entities>
+            ? AllEntityAttributes<Entities>[Key]
+            : never
+    }
+}
+
 export type CollectionPageAttributes<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends CollectionAssociations<Entities>> = {
     [Collection in keyof CollectionPageKeys<Entities, Collections>]: {
         [key in CollectionPageKeys<Entities, Collections>[Collection]]:
@@ -131,6 +259,24 @@ export type CollectionPageAttributes<Entities extends {[name: string]: Entity<an
     }
 }
 
+export type ClusteredCollectionPageAttributes<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<Entities>> = {
+    [Collection in keyof ClusteredCollectionPageKeys<Entities, Collections>]: {
+        [key in ClusteredCollectionPageKeys<Entities, Collections>[Collection]]:
+        key extends keyof AllEntityAttributes<Entities>
+            ? AllEntityAttributes<Entities>[key]
+            : never
+    }
+}
+
+export type IsolatedCollectionPageAttributes<Entities extends {[name: string]: Entity<any, any, any, any>}, Collections extends IsolatedCollectionAssociations<Entities>> = {
+    [Collection in keyof IsolatedCollectionPageKeys<Entities, Collections>]: {
+        [key in IsolatedCollectionPageKeys<Entities, Collections>[Collection]]:
+        key extends keyof AllEntityAttributes<Entities>
+            ? AllEntityAttributes<Entities>[key]
+            : never
+    }
+}
+
 export type OptionalPropertyNames<T> =
     { [K in keyof T]: undefined extends T[K] ? K : never }[keyof T];
 
@@ -215,6 +361,165 @@ export type CollectionQueries<E extends {[name: string]: Entity<any, any, any, a
     }[keyof E];
 }
 
+type ClusteredCollectionOperations<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<E>, Collection extends keyof Collections, EntityName extends keyof E> =
+    EntityName extends Collections[Collection] ? {
+        go: ServiceQueryRecordsGo<{
+            [EntityResultName in Collections[Collection]]:
+            EntityResultName extends keyof E
+                ? E[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                ? ResponseItem<A,F,C,S>[]
+                : never
+                : never
+        }>;
+        params: ParamRecord;
+        where: {
+            [EntityResultName in Collections[Collection]]: EntityResultName extends keyof E
+                ? E[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                    ? Pick<AllEntityAttributes<E>, Extract<AllEntityAttributeNames<E>, ClusteredCollectionAttributes<E,Collections>[Collection]>> extends Partial<AllEntityAttributes<E>>
+                        ? CollectionWhereClause<E,A,F,C,S,
+                            Pick<AllEntityAttributes<E>, Extract<AllEntityAttributeNames<E>, ClusteredCollectionAttributes<E,Collections>[Collection]>>,
+                            ServiceWhereRecordsActionOptions<E,A,F,C,S,
+                                Pick<AllEntityAttributes<E>, Extract<AllEntityAttributeNames<E>, ClusteredCollectionAttributes<E,Collections>[Collection]>>,
+                                {
+                                    [EntityResultName in Collections[Collection]]:
+                                    EntityResultName extends keyof E
+                                        ? E[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                                        ? ResponseItem<A,F,C,S>[]
+                                        : never
+                                        : never
+                                },
+                                Partial<
+                                    Spread<
+                                        Collection extends keyof ClusteredCollectionPageAttributes<E, Collections>
+                                            ? ClusteredCollectionPageAttributes<E, Collections>[Collection]
+                                            : {},
+                                        Collection extends keyof ClusteredCollectionIndexAttributes<E, Collections>
+                                            ? ClusteredCollectionIndexAttributes<E, Collections>[Collection]
+                                            : {}
+                                        >
+                                    >
+                                >>
+                        : never
+                    : never
+                : never
+        }[Collections[Collection]];
+    } : never
+
+type ClusteredCompositeAttributes<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<E>, Collection extends keyof Collections, EntityName extends keyof E> =
+    EntityName extends Collections[Collection]
+        ? Parameters<
+            E[EntityName]["query"][
+                E[EntityName] extends Entity<infer A, infer F, infer C, infer S>
+                    ? Collection extends keyof ClusteredEntityCollections<A,F,C,S>
+                    ? ClusteredEntityCollections<A,F,C,S>[Collection]
+                    : never
+                    : never
+                ]
+            >[0]
+        : never
+
+type ClusteredCollectionQueryOperations<Param, Result> = {
+    between(skCompositeAttributesStart: Param, skCompositeAttributesEnd: Param): Result;
+    gt(skCompositeAttributes: Param): Result;
+    gte(skCompositeAttributes: Param): Result;
+    lt(skCompositeAttributes: Param): Result;
+    lte(skCompositeAttributes: Param): Result;
+    begins(skCompositeAttributes: Param): Result;
+}
+
+type OptionalPropertyOf<T extends object> = Exclude<{
+    [K in keyof T]: T extends Record<K, T[K]>
+        ? never
+        : K
+}[keyof T], undefined>
+
+type ClusteredCollectionQueryParams<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<E>> = {
+    [Collection in keyof Collections as Collections[Collection] extends keyof E ? Collection : never]: {
+        [EntityName in keyof E]:
+        EntityName extends Collections[Collection]
+            ? ClusteredCompositeAttributes<E, Collections, Collection, EntityName>
+            : never
+    }[keyof E];
+}
+
+export type ClusteredCollectionQueries<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends ClusteredCollectionAssociations<E>> = {
+    [Collection in keyof Collections as Collections[Collection] extends keyof E ? Collection : never]: {
+        [EntityName in keyof E]:
+            EntityName extends Collections[Collection]
+                ? (
+                    params: ClusteredCompositeAttributes<E, Collections, Collection, EntityName>
+                ) =>
+                    ClusteredCollectionOperations<E, Collections, Collection, EntityName> &
+                        ClusteredCollectionQueryOperations<
+                            Pick<ClusteredCompositeAttributes<E, Collections, Collection, EntityName>, OptionalPropertyOf<ClusteredCompositeAttributes<E, Collections, Collection, EntityName>>>,
+                            ClusteredCollectionOperations<E, Collections, Collection, EntityName>
+                        >
+                : never
+    }[keyof E];
+}
+
+export type IsolatedCollectionQueries<E extends {[name: string]: Entity<any, any, any, any>}, Collections extends IsolatedCollectionAssociations<E>> = {
+    [Collection in keyof Collections]: {
+        [EntityName in keyof E]:
+        EntityName extends Collections[Collection]
+            ? (params:
+                   RequiredProperties<
+                       Parameters<
+                           E[EntityName]["query"][
+                               E[EntityName] extends Entity<infer A, infer F, infer C, infer S>
+                                   ? Collection extends keyof IsolatedEntityCollections<A,F,C,S>
+                                   ? IsolatedEntityCollections<A,F,C,S>[Collection]
+                                   : never
+                                   : never
+                           ]
+                       >[0]
+                   >
+            ) => {
+                go: ServiceQueryRecordsGo<{
+                    [EntityResultName in Collections[Collection]]:
+                    EntityResultName extends keyof E
+                        ? E[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                        ? ResponseItem<A,F,C,S>[]
+                        : never
+                        : never
+                }>;
+                params: ParamRecord;
+                where: {
+                    [EntityResultName in Collections[Collection]]: EntityResultName extends keyof E
+                        ? E[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                            ? Pick<AllEntityAttributes<E>, Extract<AllEntityAttributeNames<E>, IsolatedCollectionAttributes<E,Collections>[Collection]>> extends Partial<AllEntityAttributes<E>>
+                                ? CollectionWhereClause<E,A,F,C,S,
+                                    Pick<AllEntityAttributes<E>, Extract<AllEntityAttributeNames<E>, IsolatedCollectionAttributes<E,Collections>[Collection]>>,
+                                    ServiceWhereRecordsActionOptions<E,A,F,C,S,
+                                        Pick<AllEntityAttributes<E>, Extract<AllEntityAttributeNames<E>, IsolatedCollectionAttributes<E,Collections>[Collection]>>,
+                                        {
+                                            [EntityResultName in Collections[Collection]]:
+                                            EntityResultName extends keyof E
+                                                ? E[EntityResultName] extends Entity<infer A, infer F, infer C, infer S>
+                                                ? ResponseItem<A,F,C,S>[]
+                                                : never
+                                                : never
+                                        },
+                                        Partial<
+                                            Spread<
+                                                Collection extends keyof IsolatedCollectionPageAttributes<E, Collections>
+                                                    ? IsolatedCollectionPageAttributes<E, Collections>[Collection]
+                                                    : {},
+                                                Collection extends keyof IsolatedCollectionIndexAttributes<E, Collections>
+                                                    ? IsolatedCollectionIndexAttributes<E, Collections>[Collection]
+                                                    : {}
+                                                >
+                                            >
+                                        >>
+                                : never
+                            : never
+                        : never
+                }[Collections[Collection]];
+            }
+            : never
+    }[keyof E];
+}
+
 export type ElectroDBMethodTypes = "put" | "get" | "query" | "scan" | "update" | "delete" | "remove" | "patch" | "create" | "batchGet" | "batchWrite";
 
 export interface ElectroQueryEvent<P extends any = any> {
@@ -494,9 +799,9 @@ export interface QueryOptions {
     logger?: ElectroEventListener;
     data?: 'raw' | 'includeKeys' | 'attributes';
 
-    /** @depricated use 'data=raw' instead */ 
+    /** @depricated use 'data=raw' instead */
     raw?: boolean;
-    /** @depricated use 'data=includeKeys' instead */ 
+    /** @depricated use 'data=includeKeys' instead */
     includeKeys?: boolean;
     order?: 'asc' | 'desc';
 }
@@ -552,7 +857,7 @@ interface GoBatchGetTerminalOptions<Attributes> {
     raw?: boolean;
     /** @depricated use 'data=raw' instead */
     includeKeys?: boolean;
-    
+
     table?: string;
     limit?: number;
     params?: object;
@@ -649,7 +954,7 @@ type GoGetTerminal<A extends string, F extends string, C extends string, S exten
 
 export type GoQueryTerminal<A extends string, F extends string, C extends string, S extends Schema<A,F,C>, Item> = <Options extends GoQueryTerminalOptions<keyof Item>>(options?: Options) =>
     Options extends GoQueryTerminalOptions<infer Attr>
-        ? Promise<{ 
+        ? Promise<{
             data: Array<{
                 [
                 Name in keyof Item as Name extends Attr
@@ -1148,7 +1453,9 @@ type StaticAttribute = {
 type CustomAttribute<T extends any = any> = {
     readonly type: "custom";
     readonly [CustomAttributeSymbol]: T;
+    readonly required?: boolean;
     readonly hidden?: boolean;
+    readonly readOnly?: boolean;
     readonly get?: (val: T, item: any) => T | undefined | void;
     readonly set?: (val?: T, item?: any) => T | undefined | void;
     readonly default?: T | (() => T);
@@ -1212,6 +1519,7 @@ export interface Schema<A extends string, F extends string, C extends string> {
     readonly indexes: {
         [accessPattern: string]: {
             readonly index?: string;
+            readonly type?: 'clustered' | 'isolated';
             readonly collection?: AccessPatternCollection<C>;
             readonly pk: {
                 readonly casing?: "upper" | "lower" | "none" | "default";
@@ -1238,6 +1546,33 @@ export type IndexCollections<A extends string, F extends string, C extends strin
         : never
 }[keyof S["indexes"]];
 
+export type IndexCollectionsMap<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = {
+    [i in keyof S["indexes"]]: S["indexes"][i]["collection"] extends
+        AccessPatternCollection<infer Name>
+        ? Name
+        : never
+};
+
+type ClusteredIndexNameMap<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = {
+    [I in keyof S["indexes"] as S['indexes'][I] extends { type: 'clustered' } ? I : never]: S["indexes"][I]["collection"] extends
+        AccessPatternCollection<infer Name>
+        ? Name
+        : never
+}
+
+type ThingValues<T> = T[keyof T];
+
+type IsolatedIndexNameMap<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = {
+    [I in keyof S["indexes"] as S['indexes'][I] extends { type: 'clustered' } ? never : I]: S["indexes"][I]["collection"] extends
+        AccessPatternCollection<infer Name>
+        ? Name
+        : never
+}
+
+export type ClusteredIndexCollections<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = ThingValues<ClusteredIndexNameMap<A,F,C,S>>;
+
+export type IsolatedIndexCollections<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = ThingValues<IsolatedIndexNameMap<A,F,C,S>>;
+
 export type EntityCollections<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = {
     [N in IndexCollections<A,F,C,S>]: {
         [i in keyof S["indexes"]]: S["indexes"][i]["collection"] extends AccessPatternCollection<infer Name>
@@ -1248,6 +1583,26 @@ export type EntityCollections<A extends string, F extends string, C extends stri
     }[keyof S["indexes"]];
 }
 
+export type ClusteredEntityCollections<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = {
+    [N in ClusteredIndexCollections<A,F,C,S>]: {
+        [I in keyof S["indexes"]]: S["indexes"][I]["collection"] extends AccessPatternCollection<infer Name>
+            ? Name extends N
+                ? I
+                : never
+            : never
+    }[keyof S["indexes"]];
+}
+
+export type IsolatedEntityCollections<A extends string, F extends string, C extends string, S extends Schema<A,F,C>> = {
+    [N in IsolatedIndexCollections<A,F,C,S>]: {
+        [I in keyof S["indexes"]]: S["indexes"][I]["collection"] extends AccessPatternCollection<infer Name>
+            ? Name extends N
+                ? I
+                : never
+            : never
+    }[keyof S["indexes"]];
+}
+
 declare const SkipSymbol: unique symbol;
 type SkipValue = typeof SkipSymbol;
 
@@ -1893,7 +2248,6 @@ export class Entity<A extends string, F extends string, C extends string, S exte
         data: DataUpdateMethodRecord<A,F,C,S, Item<A,F,C,S,S["attributes"]>, TableIndexCompositeAttributes<A,F,C,S>, ResponseItem<A,F,C,S>>;
     };
 
-
     find(record: Partial<Item<A,F,C,S,S["attributes"]>>): RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], AllTableIndexCompositeAttributes<A,F,C,S>>;
 
     match(record: Partial<Item<A,F,C,S,S["attributes"]>>): RecordsActionOptions<A,F,C,S, ResponseItem<A,F,C,S>[], AllTableIndexCompositeAttributes<A,F,C,S>>;
@@ -1924,6 +2278,9 @@ export class Entity<A extends string, F extends string, C extends string, S exte
         }>, cursor: string | null }
         : { data: Array<ResponseItem<A,F,C,S>>, cursor: string | null }
     setIdentifier(type: "entity" | "version", value: string): void;
+    setTableName(tableName: string): void;
+    getTableName(): string | undefined;
+    setClient(client: DocumentClient): void;
     client: any;
 }
 
@@ -1936,8 +2293,14 @@ export type ServiceConfiguration = {
 
 export class Service<E extends {[name: string]: Entity<any, any, any, any>}> {
     entities: E;
-    collections: CollectionQueries<E, CollectionAssociations<E>>
+    collections:
+        ClusteredCollectionQueries<E, ClusteredCollectionAssociations<E>>
+        & IsolatedCollectionQueries<E, IsolatedCollectionAssociations<E>>
     constructor(entities: E, config?: ServiceConfiguration);
+
+    setTableName(tableName: string): void;
+    getTableName(): string | undefined;
+    setClient(client: DocumentClient): void;
 }
 
 type CustomAttributeDefinition<T> = {