@model-ts/dynamodb 2.0.0 → 3.0.1

package/src/__test__/client.test.ts

@@ -134,6 +134,10 @@ beforeEach(async () => {
   sandbox = await createSandbox(client)
 })
 
+afterEach(async () => {
+  await sandbox.destroy()
+})
+
 describe("put", () => {
   describe("via instance", () => {
     test("it inserts a simple model", async () => {
@@ -2135,6 +2139,56 @@ describe("paginate", () => {
       expect(page1.edges[0].node.c).toBe("0")
       expect(page1.edges[49].node.c).toBe("49")
     })
+
+    test("it respects custom pagination default", async () => {
+      client.paginationOptions = {
+        default: 40,
+      }
+
+      const items = Array.from({ length: 50 }).map(
+        (_, i) =>
+          new C({ pk: "PK", sk: String(i).padStart(3, "0"), c: String(i) })
+      )
+
+      await sandbox.seed(...items)
+
+      const page = await client.paginate(
+        C,
+        {},
+        {
+          KeyConditionExpression: "PK = :pk",
+          ExpressionAttributeValues: { ":pk": "PK" },
+        }
+      )
+      expect(page.edges.length).toBe(40)
+
+      delete client.paginationOptions
+    })
+
+    test("it respects custom pagination limit", async () => {
+      client.paginationOptions = {
+        limit: 100,
+      }
+
+      const items = Array.from({ length: 120 }).map(
+        (_, i) =>
+          new C({ pk: "PK", sk: String(i).padStart(3, "0"), c: String(i) })
+      )
+
+      await sandbox.seed(...items)
+
+      const page = await client.paginate(
+        C,
+        { first: 110 },
+        {
+          KeyConditionExpression: "PK = :pk",
+          ExpressionAttributeValues: { ":pk": "PK" },
+        }
+      )
+      expect(page.edges.length).toBe(100)
+
+      delete client.paginationOptions
+    })
   })
 
   describe("model", () => {
@@ -2301,6 +2355,54 @@ describe("paginate", () => {
       expect(page1.edges[0].node.c).toBe("0")
       expect(page1.edges[49].node.c).toBe("49")
     })
+
+    test("it respects custom pagination default", async () => {
+      client.paginationOptions = {
+        default: 40,
+      }
+
+      const items = Array.from({ length: 50 }).map(
+        (_, i) =>
+          new C({ pk: "PK", sk: String(i).padStart(3, "0"), c: String(i) })
+      )
+
+      await sandbox.seed(...items)
+
+      const page = await C.paginate(
+        {},
+        {
+          KeyConditionExpression: "PK = :pk",
+          ExpressionAttributeValues: { ":pk": "PK" },
+        }
+      )
+      expect(page.edges.length).toBe(40)
+
+      delete client.paginationOptions
+    })
+
+    test("it respects custom pagination limit", async () => {
+      client.paginationOptions = {
+        limit: 100,
+      }
+
+      const items = Array.from({ length: 120 }).map(
+        (_, i) =>
+          new C({ pk: "PK", sk: String(i).padStart(3, "0"), c: String(i) })
+      )
+
+      await sandbox.seed(...items)
+
+      const page = await C.paginate(
+        { first: 110 },
+        {
+          KeyConditionExpression: "PK = :pk",
+          ExpressionAttributeValues: { ":pk": "PK" },
+        }
+      )
+      expect(page.edges.length).toBe(100)
+
+      delete client.paginationOptions
+    })
   })
 
   describe("union", () => {
@@ -2470,5 +2572,71 @@ describe("paginate", () => {
       expect(page1.edges[0].node.SK).toBe("000")
       expect(page1.edges[49].node.SK).toBe("049")
     })
+
+    test("it respects custom pagination default", async () => {
+      client.paginationOptions = {
+        default: 40,
+      }
+
+      const items = Array.from({ length: 50 }).map((_, i) =>
+        i > 30
+          ? new C({
+              pk: "PK",
+              sk: String(i).padStart(3, "0"),
+              c: String(i),
+            })
+          : new D({
+              pk: "PK",
+              sk: String(i).padStart(3, "0"),
+              d: String(i),
+            })
+      )
+
+      await sandbox.seed(...items)
+
+      const page = await Union.paginate(
+        {},
+        {
+          KeyConditionExpression: "PK = :pk",
+          ExpressionAttributeValues: { ":pk": "PK" },
+        }
+      )
+      expect(page.edges.length).toBe(40)
+
+      delete client.paginationOptions
+    })
+
+    test("it respects custom pagination limit", async () => {
+      client.paginationOptions = {
+        limit: 100,
+      }
+
+      const items = Array.from({ length: 110 }).map((_, i) =>
+        i > 30
+          ? new C({
+              pk: "PK",
+              sk: String(i).padStart(3, "0"),
+              c: String(i),
+            })
+          : new D({
+              pk: "PK",
+              sk: String(i).padStart(3, "0"),
+              d: String(i),
+            })
+      )
+
+      await sandbox.seed(...items)
+
+      const page = await Union.paginate(
+        { first: 110 },
+        {
+          KeyConditionExpression: "PK = :pk",
+          ExpressionAttributeValues: { ":pk": "PK" },
+        }
+      )
+      expect(page.edges.length).toBe(100)
+
+      delete client.paginationOptions
+    })
   })
 })

package/src/__test__/pagination.test.ts

@@ -0,0 +1,300 @@
+import crypto from "crypto"
+import { encodeDDBCursor, decodeDDBCursor } from "../pagination"
+import { PaginationError } from "../errors"
+
+describe("encodeDDBCursor", () => {
+  describe("basic encoding without encryption", () => {
+    it("should encode basic PK and SK", () => {
+      const result = encodeDDBCursor({
+        PK: "USER#123",
+        SK: "PROFILE#456",
+      })
+
+      expect(result).toMatchInlineSnapshot(
+        `"eyJQSyI6IlVTRVIjMTIzIiwiU0siOiJQUk9GSUxFIzQ1NiJ9"`
+      )
+    })
+
+    it("should encode with GSI2 values", () => {
+      const result = encodeDDBCursor({
+        PK: "USER#123",
+        SK: "PROFILE#456",
+        GSI2PK: "GSI2PK#user123",
+        GSI2SK: "GSI2SK#profile456",
+      })
+
+      expect(result).toMatchInlineSnapshot(
+        `"eyJQSyI6IlVTRVIjMTIzIiwiU0siOiJQUk9GSUxFIzQ1NiIsIkdTSTJQSyI6IkdTSTJQSyN1c2VyMTIzIiwiR1NJMlNLIjoiR1NJMlNLI3Byb2ZpbGU0NTYifQ=="`
+      )
+    })
+
+    it("should encode with multiple GSI values", () => {
+      const result = encodeDDBCursor({
+        PK: "USER#123",
+        SK: "PROFILE#456",
+        GSI2PK: "GSI2PK#user123",
+        GSI2SK: "GSI2SK#profile456",
+        GSI3PK: "GSI3PK#fixed",
+        GSI3SK: "GSI3SK#value",
+      })
+
+      expect(result).toMatchInlineSnapshot(
+        `"eyJQSyI6IlVTRVIjMTIzIiwiU0siOiJQUk9GSUxFIzQ1NiIsIkdTSTJQSyI6IkdTSTJQSyN1c2VyMTIzIiwiR1NJMlNLIjoiR1NJMlNLI3Byb2ZpbGU0NTYiLCJHU0kzUEsiOiJHU0kzUEsjZml4ZWQiLCJHU0kzU0siOiJHU0kzU0sjdmFsdWUifQ=="`
+      )
+    })
+  })
+
+  describe("encoding with encryption", () => {
+    const encryptionKey = crypto.randomBytes(32)
+
+    it("should encrypt the cursor when encryption key is provided", () => {
+      const result = encodeDDBCursor(
+        {
+          PK: "USER#123",
+          SK: "PROFILE#456",
+        },
+        encryptionKey
+      )
+
+      // The result should be encrypted and different from the unencrypted version
+      expect(result).not.toBe(
+        "eyJQSyI6IlVTRVIjMTIzIiwiU0siOiJQUk9GSUxFIzQ1NiJ9"
+      )
+      expect(result).toMatch(/^[A-Za-z0-9+/=]+$/) // Base64 format
+    })
+
+    it("should produce consistent encrypted results for same input", () => {
+      const input = {
+        PK: "USER#123",
+        SK: "PROFILE#456",
+      }
+
+      const result1 = encodeDDBCursor(input, encryptionKey)
+      const result2 = encodeDDBCursor(input, encryptionKey)
+
+      expect(result1).toBe(result2)
+    })
+
+    it("should encrypt with GSI values", () => {
+      const result = encodeDDBCursor(
+        {
+          PK: "USER#123",
+          SK: "PROFILE#456",
+          GSI2PK: "GSI2PK#user123",
+          GSI2SK: "GSI2SK#profile456",
+        },
+        encryptionKey
+      )
+
+      expect(result).toMatch(/^[A-Za-z0-9+/=]+$/)
+    })
+  })
+})
+
+describe("decodeDDBCursor", () => {
+  describe("basic decoding without encryption", () => {
+    it("should decode basic PK and SK", () => {
+      const encoded = "eyJQSyI6IlVTRVIjMTIzIiwiU0siOiJQUk9GSUxFIzQ1NiJ9"
+      const result = decodeDDBCursor(encoded)
+
+      expect(result).toMatchInlineSnapshot(`
+        Object {
+          "PK": "USER#123",
+          "SK": "PROFILE#456",
+        }
+      `)
+    })
+
+    it("should decode with GSI2 values", () => {
+      const encoded =
+        "eyJQSyI6IlVTRVIjMTIzIiwiU0siOiJQUk9GSUxFIzQ1NiIsIkdTSTJQSyI6IkdTSTJQSyN1c2VyMTIzIiwiR1NJMlNLIjoiR1NJMlNLI3Byb2ZpbGU0NTYifQ=="
+      const result = decodeDDBCursor(encoded, "GSI2")
+
+      expect(result).toMatchInlineSnapshot(`
+        Object {
+          "GSI2PK": "GSI2PK#user123",
+          "GSI2SK": "GSI2SK#profile456",
+          "PK": "USER#123",
+          "SK": "PROFILE#456",
+        }
+      `)
+    })
+
+    it("should decode with GSI3 values", () => {
+      const encoded =
+        "eyJQSyI6IlVTRVIjMTIzIiwiU0siOiJQUk9GSUxFIzQ1NiIsIkdTSTJQSyI6IkdTSTJQSyN1c2VyMTIzIiwiR1NJMlNLIjoiR1NJMlNLI3Byb2ZpbGU0NTYiLCJHU0kzUEsiOiJHU0kzUEsjZml4ZWQiLCJHU0kzU0siOiJHU0kzU0sjdmFsdWUifQ=="
+      const result = decodeDDBCursor(encoded, "GSI3")
+
+      expect(result).toMatchInlineSnapshot(`
+        Object {
+          "GSI3PK": "GSI3PK#fixed",
+          "GSI3SK": "GSI3SK#value",
+          "PK": "USER#123",
+          "SK": "PROFILE#456",
+        }
+      `)
+    })
+  })
+
+  describe("decoding with encryption", () => {
+    const encryptionKey = crypto.randomBytes(32)
+
+    it("should decode encrypted cursor", () => {
+      const input = {
+        PK: "USER#123",
+        SK: "PROFILE#456",
+      }
+      const encoded = encodeDDBCursor(input, encryptionKey)
+      const result = decodeDDBCursor(encoded, undefined, encryptionKey)
+
+      expect(result).toMatchInlineSnapshot(`
+        Object {
+          "PK": "USER#123",
+          "SK": "PROFILE#456",
+        }
+      `)
+    })
+
+    it("should decode encrypted cursor with GSI values", () => {
+      const input = {
+        PK: "USER#123",
+        SK: "PROFILE#456",
+        GSI2PK: "GSI2PK#user123",
+        GSI2SK: "GSI2SK#profile456",
+      }
+      const encoded = encodeDDBCursor(input, encryptionKey)
+      const result = decodeDDBCursor(encoded, "GSI2", encryptionKey)
+
+      expect(result).toMatchInlineSnapshot(`
+        Object {
+          "GSI2PK": "GSI2PK#user123",
+          "GSI2SK": "GSI2SK#profile456",
+          "PK": "USER#123",
+          "SK": "PROFILE#456",
+        }
+      `)
+    })
+
+    it("should throw PaginationError when decryption fails", () => {
+      const wrongKey = crypto.randomBytes(32)
+      const input = {
+        PK: "USER#123",
+        SK: "PROFILE#456",
+      }
+      const encoded = encodeDDBCursor(input, encryptionKey)
+
+      expect(() => {
+        decodeDDBCursor(encoded, undefined, wrongKey)
+      }).toThrow(PaginationError)
+      expect(() => {
+        decodeDDBCursor(encoded, undefined, wrongKey)
+      }).toThrow("Couldn't decode cursor")
+    })
+  })
+
+  describe("error handling", () => {
+    it("should throw PaginationError for invalid base64", () => {
+      expect(() => {
+        decodeDDBCursor("invalid-base64")
+      }).toThrow(PaginationError)
+      expect(() => {
+        decodeDDBCursor("invalid-base64")
+      }).toThrow("Couldn't decode cursor")
+    })
+
+    it("should throw PaginationError for invalid JSON", () => {
+      const invalidJson = Buffer.from("invalid json").toString("base64")
+      expect(() => {
+        decodeDDBCursor(invalidJson)
+      }).toThrow(PaginationError)
+    })
+
+    it("should throw PaginationError when PK is missing", () => {
+      const invalidData = Buffer.from(
+        JSON.stringify({ SK: "PROFILE#456" })
+      ).toString("base64")
+      expect(() => {
+        decodeDDBCursor(invalidData)
+      }).toThrow(PaginationError)
+    })
+
+    it("should throw PaginationError when SK is missing", () => {
+      const invalidData = Buffer.from(
+        JSON.stringify({ PK: "USER#123" })
+      ).toString("base64")
+      expect(() => {
+        decodeDDBCursor(invalidData)
+      }).toThrow(PaginationError)
+    })
+
+    it("should throw PaginationError when PK is not a string", () => {
+      const invalidData = Buffer.from(
+        JSON.stringify({ PK: 123, SK: "PROFILE#456" })
+      ).toString("base64")
+      expect(() => {
+        decodeDDBCursor(invalidData)
+      }).toThrow(PaginationError)
+    })
+
+    it("should throw PaginationError when SK is not a string", () => {
+      const invalidData = Buffer.from(
+        JSON.stringify({ PK: "USER#123", SK: 456 })
+      ).toString("base64")
+      expect(() => {
+        decodeDDBCursor(invalidData)
+      }).toThrow(PaginationError)
+    })
+  })
+
+  describe("round-trip encoding and decoding", () => {
+    it("should round-trip basic values", () => {
+      const input = {
+        PK: "USER#123",
+        SK: "PROFILE#456",
+      }
+      const encoded = encodeDDBCursor(input)
+      const decoded = decodeDDBCursor(encoded)
+
+      expect(decoded).toEqual(input)
+    })
+
+    it("should round-trip with GSI values", () => {
+      const input = {
+        PK: "USER#123",
+        SK: "PROFILE#456",
+        GSI2PK: "GSI2PK#user123",
+        GSI2SK: "GSI2SK#profile456",
+        GSI3PK: "GSI3PK#fixed",
+        GSI3SK: "GSI3SK#value",
+      }
+      const encoded = encodeDDBCursor(input)
+      const decoded = decodeDDBCursor(encoded, "GSI2")
+
+      expect(decoded).toEqual({
+        PK: input.PK,
+        SK: input.SK,
+        GSI2PK: input.GSI2PK,
+        GSI2SK: input.GSI2SK,
+      })
+    })
+
+    it("should round-trip with encryption", () => {
+      const encryptionKey = crypto.randomBytes(32)
+      const input = {
+        PK: "USER#123",
+        SK: "PROFILE#456",
+        GSI2PK: "GSI2PK#user123",
+        GSI2SK: "GSI2SK#profile456",
+      }
+      const encoded = encodeDDBCursor(input, encryptionKey)
+      const decoded = decodeDDBCursor(encoded, "GSI2", encryptionKey)
+
+      expect(decoded).toEqual({
+        PK: input.PK,
+        SK: input.SK,
+        GSI2PK: input.GSI2PK,
+        GSI2SK: input.GSI2SK,
+      })
+    })
+  })
+})

package/src/client.ts

@@ -40,8 +40,10 @@ import {
   encodeDDBCursor,
   PaginationDirection,
   PaginationInput,
+  PaginationOptions,
   PaginationResult,
 } from "./pagination"
+import { GSI, GSI_NAMES, GSIPK, GSISK } from "./gsi"
 
 export type QueryParams = Omit<
   DocumentClient.QueryInput,
@@ -85,6 +87,11 @@ export interface ClientProps
    * Must be a 32 character string, 256 bits.
    */
   cursorEncryptionKey?: Buffer
+
+  /**
+   * Defaults for pagination.
+   */
+  paginationOptions?: PaginationOptions
 }
 
 export interface Key {
@@ -97,10 +104,12 @@ export class Client {
   documentClient: DocumentClient
   dataLoader: DataLoader<GetOperation<Decodable>, DynamoDBModelInstance, string>
   cursorEncryptionKey?: Buffer
+  paginationOptions?: PaginationOptions
 
   constructor(props: ClientProps) {
     this.tableName = props?.tableName
     this.cursorEncryptionKey = props?.cursorEncryptionKey
+    this.paginationOptions = props?.paginationOptions
     this.documentClient = new DocumentClient(props)
     this.dataLoader = new DataLoader<
       GetOperation<Decodable>,
@@ -525,7 +534,10 @@ export class Client {
     args: PaginationInput,
     params: PaginationParams
   ): Promise<PaginationResult<DecodableInstance<M>>> {
-    const { cursor, limit, direction } = decodePagination(args)
+    const { cursor, limit, direction } = decodePagination(
+      args,
+      this.paginationOptions
+    )
 
     const { results } = await this.query(
       {
@@ -537,7 +549,7 @@ export class Client {
               cursor,
               // GSI1 is the inverse index and uses PK and SK (switched around)
               params.IndexName && params.IndexName !== "GSI1"
-                ? (params.IndexName as "GSI2" | "GSI3" | "GSI4" | "GSI5")
+                ? (params.IndexName as GSI)
                 : undefined,
               this.cursorEncryptionKey
             )
@@ -888,15 +900,8 @@ export class Client {
     T extends {
       PK: string
       SK: string
-      GSI2PK?: string
-      GSI2SK?: string
-      GSI3PK?: string
-      GSI3SK?: string
-      GSI4PK?: string
-      GSI4SK?: string
-      GSI5PK?: string
-      GSI5SK?: string
-    }
+    } & { [key in GSIPK]?: string } &
+      { [key in GSISK]?: string }
   >(item: T): T {
     const prefix = "$$DELETED$$"
 
@@ -908,14 +913,10 @@ export class Client {
       ...item,
       PK: maybeWithPrefix(item.PK),
       SK: maybeWithPrefix(item.SK),
-      GSI2PK: maybeWithPrefix(item.GSI2PK),
-      GSI2SK: maybeWithPrefix(item.GSI2SK),
-      GSI3PK: maybeWithPrefix(item.GSI3PK),
-      GSI3SK: maybeWithPrefix(item.GSI3SK),
-      GSI4PK: maybeWithPrefix(item.GSI4PK),
-      GSI4SK: maybeWithPrefix(item.GSI4SK),
-      GSI5PK: maybeWithPrefix(item.GSI5PK),
-      GSI5SK: maybeWithPrefix(item.GSI5SK),
+      ...GSI_NAMES.map((GSI) => ({
+        [`${GSI}PK`]: maybeWithPrefix(item[`${GSI}PK` as const]),
+        [`${GSI}SK`]: maybeWithPrefix(item[`${GSI}SK` as const]),
+      })).reduce((acc, cur) => Object.assign(acc, cur), {}),
     }
   }
 }

package/src/dynamodb-model.ts

@@ -1,4 +1,5 @@
 import { ModelInstance, ModelConstructor, Union } from "@model-ts/core"
+import { GSIPK, GSISK } from "./gsi"
 
 export interface DynamoDBModelInstance extends ModelInstance<string, any> {
   /**
@@ -7,15 +8,8 @@ export interface DynamoDBModelInstance extends ModelInstance<string, any> {
   keys(): {
     PK: string
     SK: string
-    GSI2PK?: string
-    GSI2SK?: string
-    GSI3PK?: string
-    GSI3SK?: string
-    GSI4PK?: string
-    GSI4SK?: string
-    GSI5PK?: string
-    GSI5SK?: string
-  }
+  } & { [key in GSIPK]?: string } &
+    { [key in GSISK]?: string }
 
   PK: string
   SK: string
@@ -27,6 +21,34 @@ export interface DynamoDBModelInstance extends ModelInstance<string, any> {
   GSI4SK?: string
   GSI5PK?: string
   GSI5SK?: string
+  GSI6PK?: string
+  GSI6SK?: string
+  GSI7PK?: string
+  GSI7SK?: string
+  GSI8PK?: string
+  GSI8SK?: string
+  GSI9PK?: string
+  GSI9SK?: string
+  GSI10PK?: string
+  GSI10SK?: string
+  GSI11PK?: string
+  GSI11SK?: string
+  GSI12PK?: string
+  GSI12SK?: string
+  GSI13PK?: string
+  GSI13SK?: string
+  GSI14PK?: string
+  GSI14SK?: string
+  GSI15PK?: string
+  GSI15SK?: string
+  GSI16PK?: string
+  GSI16SK?: string
+  GSI17PK?: string
+  GSI17SK?: string
+  GSI18PK?: string
+  GSI18SK?: string
+  GSI19PK?: string
+  GSI19SK?: string
 }
 
 // export interface DynamoDBModel {}

package/src/gsi.ts

@@ -0,0 +1,25 @@
+export const GSI_NAMES = [
+  "GSI2",
+  "GSI3",
+  "GSI4",
+  "GSI5",
+  "GSI6",
+  "GSI7",
+  "GSI8",
+  "GSI9",
+  "GSI10",
+  "GSI11",
+  "GSI12",
+  "GSI13",
+  "GSI14",
+  "GSI15",
+  "GSI16",
+  "GSI17",
+  "GSI18",
+  "GSI19",
+] as const
+
+export type GSI = typeof GSI_NAMES[number]
+
+export type GSIPK = `${GSI}PK`
+export type GSISK = `${GSI}SK`

package/src/operations.ts

@@ -6,6 +6,7 @@ import {
   Decodable,
 } from "./dynamodb-model"
 import { Key } from "./client"
+import { GSIPK, GSISK } from "./gsi"
 
 export type Operation<
   T extends DynamoDBModelInstance,
@@ -57,16 +58,9 @@ export interface UpdateRawOperation<M extends DynamoDBModelConstructor<any>>
   _operation: "updateRaw"
   _model: M
   key: Key
-  attributes: Partial<TypeOf<M>> & {
-    GSI2PK?: string | null
-    GSI2SK?: string | null
-    GSI3PK?: string | null
-    GSI3SK?: string | null
-    GSI4PK?: string | null
-    GSI4SK?: string | null
-    GSI5PK?: string | null
-    GSI5SK?: string | null
-  }
+  attributes: Partial<TypeOf<M>> &
+    { [key in GSIPK]?: string | null } &
+    { [key in GSISK]?: string | null }
 }
 
 // -------------------------------------------------------------------------------------