Update store documentation and include v4 specific changes (#505)

* Update store documentation and include v4 specific changes * Update docs --------- Co-authored-by: James Bayly <[email protected]>
subquery · Apr 4, 2024 · 8cafde1 · 8cafde1
1 parent 9b16687
commit 8cafde1
Showing 1 changed file with 89 additions and 43 deletions.
diff --git a/docs/build/mapping/store.md b/docs/build/mapping/store.md
@@ -9,30 +9,38 @@ Note that there are additional methods autogenerated with your entities that als
 Following is a summary of the `Store` interface:
 
 ```ts
+export type GetOptions<T> = {
+  offset?: number;
+  limit?: number;
+  /* Order fields are only available in SDK versions >= 4.0.0 */
+  orderBy?: keyof T;
+  orderDirection?: "ASC" | "DESC";
+};
+
 export interface Store {
   get(entity: string, id: string): Promise<Entity | null>;
 
-  getByField(
-    entity: string,
-    field: string,
-    value: any,
-    options?: { limit?: number; offset?: number },
-  ): Promise<Entity[]>;
-
   getByFields<T extends Entity>(
     entity: string,
     filter: [
       field: keyof T,
       operator: "=" | "!=" | "in" | "!in",
-      value: T[keyof T] | Array<T[keyof T]>,
+      value: T[keyof T] | Array<T[keyof T]>
     ][],
-    options?: { offset?: number; limit?: number },
+    options?: GetOptions<T>
   ): Promise<T[]>;
 
-  getOneByField(
+  getByField(
     entity: string,
     field: string,
     value: any,
+    options?: GetOptions<T>
+  ): Promise<Entity[]>;
+
+  getOneByField(
+    entity: string,
+    field: string,
+    value: any
   ): Promise<Entity | null>;
 
   set(entity: string, id: string, data: Entity): Promise<void>;
@@ -42,13 +50,6 @@ export interface Store {
   bulkUpdate(entity: string, data: Entity[], fields?: string[]): Promise<void>;
 
   remove(entity: string, id: string): Promise<void>;
-
-  count(
-    entity: string,
-    field?: string,
-    value?: any,
-    options?: { distinct?: boolean; col?: string },
-  ): Promise<number>;
 }
 ```
 
@@ -63,39 +64,48 @@ const id = block.block.header.hash.toString();
 await store.get(`TransactionEntity`, id);
 ```
 
-## Get Records by a Single Field
-
-`getByField(entity: string, field: string, value: any, options?: { limit?: number; offset?: number }): Promise<Entity[]>;`
-
-This returns matching records for the specific entity that matches an equality comparison. By default it will return the first 100 results.
-The number of results can be changed via the `query-limit` flag for the node or via the options field. If you need more than the number of results provided you can also specify an `offset` and page your results.
+## Get Records by Fields
 
 ```ts
-// Get all records with ChainID == 50
-await store.getByField(`TransactionEntity`, "ChainID", 50);
-```
-
-Please note, the third parameter also accepts array, you can consider this similar like `bulkGet` with OR search.
-To get a list of records with `ChainID` equal to 50, 100 or 150:
-
-```ts
-// Get all records with ChainID == 50 OR ChainID == 100 OR ChainID == 150
-await store.getByField("TransactionEntity", "ChainID", [50, 100, 150]);
-```
-
-## Get Records by Field
+export type GetOptions<T> = {
+  offset?: number;
+  limit?: number;
+  /* Order fields are only available in SDK versions >= 4.0.0 */
+  orderBy?: keyof T;
+  orderDirection?: "ASC" | "DESC";
+};
 
-```ts
-getByFields<T extends Entity>(
+export interface Store {
+  getByFields<T extends Entity>(
     entity: string,
-    filter: [field: keyof T, operator: '=' | '!=' | 'in' | '!in', value: T[keyof T] | Array<T[keyof T]>][],
-    options?: {offset?: number; limit?: number}
+    filter: [
+      field: keyof T,
+      operator: "=" | "!=" | "in" | "!in",
+      value: T[keyof T] | Array<T[keyof T]>
+    ][],
+    options?: GetOptions<T>
   ): Promise<T[]>;
+}
 ```
 
 This returns all matching records for the specific entity that matches the given filter(s). Each entry in the filter is an AND operation. By default it will return the first 100 results.
+
 The number of results can be changed via the `query-limit` flag for the node or via the options field. If you need more than the number of results provided, we recommend you specify an `offset` and paginate through your results.
 
+The store has a cache layer in order to increase performance, because of this the returned results will always return data that is in the cache followed by data that is in the database. This is required to ensure pagination works.
+
+Only fields with an index can be filtered on and an error will be thrown if the fields are not indexed. To add an index the projects graphql schema will need to be updated to include [@index](/build/graphql.html#indexing) decorators.
+
+### Ordering
+
+::: info Note
+Ordering is only available in SDK versions >= 4.0.0
+:::
+
+By default ordering is done by `id` in ascending order.
+
+### Examples
+
 Using the store directly:
 
 ```ts
@@ -120,14 +130,50 @@ It's also possible to match multiple values to a field (in this case an OR opera
 
 ```ts
 // Get all records with ChainID == 50 OR ChainID == 51
-await TransactionEntity.getByFields([["ChainID", "=", [50, 51]]]);
+await TransactionEntity.getByFields([["ChainID", "in", [50, 51]]]);
+```
+
+## Get Records by a Single Field
+
+```ts
+export type GetOptions<T> = {
+  offset?: number;
+  limit?: number;
+  /* Order fields are only available in SDK versions >= 4.0.0 */
+  orderBy?: keyof T;
+  orderDirection?: "ASC" | "DESC";
+};
+
+export interface Store {
+  getByField(
+    entity: string,
+    field: string,
+    value: any,
+    options?: GetOptions
+  ): Promise<Entity[]>;
+}
+```
+
+This is a convenient wrapper for [getByFields](#get-records-by-field) but only accepts a single filter and uses the `=` or `in` operator.
+
+```ts
+// Get all records with ChainID == 50
+await store.getByField(`TransactionEntity`, "ChainID", 50);
+```
+
+Please note, the third parameter also accepts array, you can consider this similar like `bulkGet` with OR search.
+To get a list of records with `ChainID` equal to 50, 100 or 150:
+
+```ts
+// Get all records with ChainID == 50 OR ChainID == 100 OR ChainID == 150
+await store.getByField("TransactionEntity", "ChainID", [50, 100, 150]);
 ```
 
 ## Get First Record by Field
 
-`getOneByField(entity: string, field: string, value: any): Promise<Entity | null>;`
+`getOneByField(entity: string, field: string, value: any): Promise<Entity | undefined>;`
 
-This returns the first matching record for the specific entity that matches a given search.
+This returns the first matching record for the specific entity that matches a given search. This is a convenient wrapper for [getByFields](#get-records-by-field) that allows filtering by a field and returns a single result.
 
 ```ts
 const ChainIDValue = 50;