feat: Add support for index in query

src/nodes/indexNode.ts

@@ -0,0 +1,5 @@
+export type IndexNode = {
+  readonly kind: "IndexNode";
+  readonly index: string;
+};
+

src/nodes/queryNode.ts

@@ -1,6 +1,7 @@
 import { AttributesNode } from "./attributesNode";
 import { ConsistentReadNode } from "./consistentReadNode";
 import { ExpressionNode } from "./expressionNode";
+import { IndexNode } from "./indexNode";
 import { KeyConditionNode } from "./keyConditionNode";
 import { LimitNode } from "./limitNode";
 import { ScanIndexForwardNode } from "./scanIndexForwardNode";
@@ -14,5 +15,6 @@ export type QueryNode = {
   readonly consistentRead?: ConsistentReadNode;
   readonly scanIndexForward?: ScanIndexForwardNode;
   readonly limit?: LimitNode;
+  readonly index?: IndexNode;
   readonly attributes?: AttributesNode;
 };

src/queryBuilders/__snapshots__/queryQueryBuilder.integration.test.ts.snap

@@ -1,5 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`QueryQueryBuilder > fails a query with non-existent index 1`] = `[ValidationException: The table does not have the specified index: nonExistentIndex]`;
+
 exports[`QueryQueryBuilder > handles a FilterExpression that takes attributes from cats array 1`] = `
 [
   {
@@ -363,6 +365,77 @@ exports[`QueryQueryBuilder > handles a query with a simple KeyCondition 1`] = `
 ]
 `;
 
+exports[`QueryQueryBuilder > handles a query with index 1`] = `
+[
+  {
+    "dataTimestamp": 333,
+    "someBoolean": false,
+    "somethingElse": 10,
+    "userId": "123",
+  },
+  {
+    "dataTimestamp": 999,
+    "nested": {
+      "nestedBoolean": true,
+      "nestedString": "key",
+    },
+    "someBoolean": false,
+    "somethingElse": 0,
+    "userId": "123",
+  },
+  {
+    "dataTimestamp": 996,
+    "nested": {
+      "nestedBoolean": true,
+      "nestedNested": {
+        "nestedNestedBoolean": true,
+      },
+      "nestedString": "llol",
+    },
+    "someBoolean": false,
+    "somethingElse": -9,
+    "userId": "123",
+  },
+  {
+    "dataTimestamp": 222,
+    "someBoolean": true,
+    "somethingElse": 2,
+    "userId": "123",
+  },
+  {
+    "dataTimestamp": 111,
+    "nested": {
+      "nestedBoolean": false,
+      "nestedString": "koy",
+    },
+    "someBoolean": true,
+    "somethingElse": -5,
+    "userId": "123",
+  },
+]
+`;
+
+exports[`QueryQueryBuilder > handles a query with limit 1`] = `
+[
+  {
+    "dataTimestamp": 111,
+    "nested": {
+      "nestedBoolean": false,
+      "nestedString": "koy",
+    },
+    "someBoolean": true,
+    "somethingElse": -5,
+    "userId": "123",
+  },
+  {
+    "dataTimestamp": 222,
+    "someBoolean": true,
+    "somethingElse": 2,
+    "userId": "123",
+  },
+]
+`;
+
 exports[`QueryQueryBuilder > handles a query with multiple expressions 1`] = `
 [
   {

src/queryBuilders/queryQueryBuilder.integration.test.ts

@@ -188,4 +188,34 @@ describe("QueryQueryBuilder", () => {
 
     expect(data).toMatchSnapshot();
   });
+
+  it("handles a query with limit", async () => {
+    const data = await tsynamoClient
+      .query("myTable")
+      .keyCondition("userId", "=", "123")
+      .limit(2)
+      .execute();
+
+    expect(data).toHaveLength(2);
+    expect(data).toMatchSnapshot();
+  })
+
+  it("handles a query with index", async () => {
+    const data = await tsynamoClient
+      .query("myTable")
+      .keyCondition("userId", "=", "123")
+      .index("myIndex")
+      .execute();
+
+    expect(data).toMatchSnapshot();
+  })
+
+  it("fails a query with non-existent index", async () => {
+    await expect(tsynamoClient
+      .query("myTable")
+      .keyCondition("userId", "=", "123")
+      .index("nonExistentIndex")
+      .execute()
+    ).rejects.toThrowErrorMatchingSnapshot();
+  })
 });

src/queryBuilders/queryQueryBuilder.ts

@@ -114,6 +114,8 @@ export interface QueryQueryBuilderInterface<DDB, Table extends keyof DDB, O> {
 
   limit(value: number): QueryQueryBuilderInterface<DDB, Table, O>;
 
+  index(index: string): QueryQueryBuilderInterface<DDB, Table, O>;
+
   scanIndexForward(enabled: boolean): QueryQueryBuilderInterface<DDB, Table, O>;
 
   consistentRead(enabled: boolean): QueryQueryBuilderInterface<DDB, Table, O>;
@@ -265,6 +267,19 @@ export class QueryQueryBuilder<
     });
   }
 
+  index(index: string): QueryQueryBuilderInterface<DDB, Table, O> {
+    return new QueryQueryBuilder<DDB, Table, O>({
+      ...this.#props,
+      node: {
+        ...this.#props.node,
+        index: {
+          kind: "IndexNode",
+          index,
+        },
+      },
+    });
+  }
+
   scanIndexForward(
     enabled: boolean
   ): QueryQueryBuilderInterface<DDB, Table, O> {

src/queryCompiler/queryCompiler.ts

@@ -104,6 +104,7 @@ export class QueryCompiler {
       filterExpression: filterExpressionNode,
       keyConditions: keyConditionsNode,
       limit: limitNode,
+      index: indexNode,
       scanIndexForward: scanIndexForwardNode,
       consistentRead: consistentReadNode,
       attributes: attributesNode,
@@ -135,6 +136,7 @@ export class QueryCompiler {
         ? compiledFilterExpression
         : undefined,
       Limit: limitNode?.limit,
+      IndexName: indexNode?.index,
       ExpressionAttributeValues: {
         ...Object.fromEntries(keyConditionAttributeValues),
         ...Object.fromEntries(filterExpressionAttributeValues),

test/testFixture.ts

@@ -71,6 +71,17 @@ export const setupTestDDB = async (client: DynamoDBDocumentClient) => {
         },
       ],
       BillingMode: "PAY_PER_REQUEST",
+      GlobalSecondaryIndexes: [
+        {
+          IndexName: "myIndex",
+          KeySchema: [
+            { AttributeName: "userId", KeyType: "HASH" },
+          ],
+          Projection: {
+            ProjectionType: "ALL",
+          },
+        },
+      ],
     })
   );