@model-ts/dynamodb 1.0.0 → 1.2.0

package/src/__test__/client.test.ts

@@ -8,7 +8,7 @@ import {
   ItemNotFoundError,
   ConditionalCheckFailedError,
   RaceConditionError,
-  BulkWriteTransactionError
+  BulkWriteTransactionError,
 } from "../errors"
 
 const client = new Client({ tableName: "table" })
@@ -16,7 +16,7 @@ const provider = getProvider(client)
 
 const SIMPLE_CODEC = t.type({
   foo: t.string,
-  bar: t.number
+  bar: t.number,
 })
 
 class Simple extends model("Simple", SIMPLE_CODEC, provider) {
@@ -331,7 +331,7 @@ describe("put", () => {
 
       await expect(
         MultiGSI.put(new MultiGSI({ foo: "yes", bar: 42 }), {
-          IgnoreExistence: true
+          IgnoreExistence: true,
         })
       ).resolves.toBeInstanceOf(MultiGSI)
     })
@@ -351,7 +351,7 @@ describe("get", () => {
 
       const result = await Simple.get({
         PK: item.keys().PK,
-        SK: item.keys().SK
+        SK: item.keys().SK,
       })
 
       expect(result.values()).toMatchInlineSnapshot(`
@@ -417,8 +417,8 @@ describe("delete", () => {
         _model: Simple,
         key: {
           PK: item.keys().PK,
-          SK: item.keys().SK
-        }
+          SK: item.keys().SK,
+        },
       })
 
       expect(result).toBeNull()
@@ -451,7 +451,7 @@ describe("delete", () => {
 
       const result = await Simple.delete({
         PK: item.keys().PK,
-        SK: item.keys().SK
+        SK: item.keys().SK,
       })
 
       expect(result).toBeNull()
@@ -826,7 +826,7 @@ describe("query", () => {
       await client.query(
         {
           KeyConditionExpression: `PK = :pk and begins_with(SK, :sk)`,
-          ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT" }
+          ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT" },
         },
         { a: A, b: B, union: Union }
       )
@@ -850,7 +850,7 @@ describe("query", () => {
       await client.query(
         {
           KeyConditionExpression: `PK = :pk and begins_with(SK, :sk)`,
-          ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT#" }
+          ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT#" },
         },
         { a: A, b: B, union: Union }
       )
@@ -886,7 +886,7 @@ describe("query", () => {
     const { a, b, union, _unknown, meta } = await client.query(
       {
         KeyConditionExpression: `PK = :pk and begins_with(SK, :sk)`,
-        ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT#" }
+        ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT#" },
       },
       { a: A, b: B, union: Union }
     )
@@ -894,9 +894,9 @@ describe("query", () => {
     expect({
       meta: meta,
       _unknown: _unknown,
-      a: a.map(item => item.values()),
-      b: b.map(item => item.values()),
-      union: union.map(item => item.values())
+      a: a.map((item) => item.values()),
+      b: b.map((item) => item.values()),
+      union: union.map((item) => item.values()),
     }).toMatchInlineSnapshot(`
       Object {
         "_unknown": Array [
@@ -959,7 +959,7 @@ describe("query", () => {
       {
         KeyConditionExpression: `PK = :pk and begins_with(SK, :sk)`,
         ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT#" },
-        Limit: 30
+        Limit: 30,
       },
       { a: A, b: B }
     )
@@ -974,7 +974,7 @@ describe("query", () => {
         KeyConditionExpression: `PK = :pk and begins_with(SK, :sk)`,
         ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT#" },
         Limit: 30,
-        ExclusiveStartKey: firstPage.meta.lastEvaluatedKey
+        ExclusiveStartKey: firstPage.meta.lastEvaluatedKey,
       },
       { a: A, b: B }
     )
@@ -1002,7 +1002,7 @@ describe("query", () => {
         ExpressionAttributeValues: { ":pk": "abc", ":sk": "SORT#" },
         FetchAllPages: true,
         // You wouldn't set a limit in a real-world use case here to optimize fetching all items.
-        Limit: 10
+        Limit: 10,
       },
       { a: A, b: B }
     )
@@ -1039,16 +1039,16 @@ describe("bulk", () => {
         new B({
           pk: "PK#UPDATE",
           sk: "SK#UPDATE",
-          b: "bar"
+          b: "bar",
         }).operation("update", { b: "baz" }),
         new B({
           pk: "PK#COND",
           sk: "SK#COND",
-          b: "cond"
+          b: "cond",
         }).operation("condition", {
           ConditionExpression: "b = :cond",
-          ExpressionAttributeValues: { ":cond": "cond" }
-        })
+          ExpressionAttributeValues: { ":cond": "cond" },
+        }),
       ])
 
       expect(await sandbox.diff(before)).toMatchInlineSnapshot(`
@@ -1168,7 +1168,7 @@ describe("bulk", () => {
             "updateRaw",
             { PK: "PK#nicetry", SK: "SK#nope" },
             { a: 234 }
-          )
+          ),
         ])
       ).rejects.toBeInstanceOf(BulkWriteTransactionError)
 
@@ -1196,11 +1196,11 @@ describe("bulk", () => {
         new B({
           pk: "PK#UPDATE",
           sk: "SK#UPDATE",
-          b: "bar"
+          b: "bar",
         }).operation("update", { b: "baz" }),
         ...Array.from({ length: 25 }).map((_, i) =>
           new A({ pk: `PK#A${i}`, sk: `SK#A${i}`, a: i }).operation("put")
-        )
+        ),
       ])
 
       //#region snapshot
@@ -1512,7 +1512,7 @@ describe("bulk", () => {
             "condition",
             { PK: "nicetry", SK: "nope" },
             { ConditionExpression: "attribute_exists(PK)" }
-          )
+          ),
         ])
       ).rejects.toBeInstanceOf(BulkWriteTransactionError)
 
@@ -1546,7 +1546,7 @@ describe("batchGet", () => {
         two: A.operation("get", { PK: "PK#2", SK: "SK#2" }),
         three: A.operation("get", { PK: "PK#3", SK: "SK#3" }),
         four: A.operation("get", { PK: "PK#4", SK: "SK#4" }),
-        duplicate: A.operation("get", { PK: "PK#1", SK: "SK#1" })
+        duplicate: A.operation("get", { PK: "PK#1", SK: "SK#1" }),
       })
     ).rejects.toBeInstanceOf(ItemNotFoundError)
   })
@@ -1563,7 +1563,7 @@ describe("batchGet", () => {
         two: A.operation("get", { PK: "PK#2", SK: "SK#2" }),
         duplicate: A.operation("get", { PK: "PK#1", SK: "SK#1" }),
         error: A.operation("get", { PK: "PK#error", SK: "SK#error" }),
-        error2: A.operation("get", { PK: "PK#error2", SK: "SK#error2" })
+        error2: A.operation("get", { PK: "PK#error2", SK: "SK#error2" }),
       },
       { individualErrors: true }
     )
@@ -1587,7 +1587,7 @@ describe("batchGet", () => {
       two: A.operation("get", { PK: "PK#2", SK: "SK#2" }),
       three: A.operation("get", { PK: "PK#3", SK: "SK#3" }),
       four: A.operation("get", { PK: "PK#4", SK: "SK#4" }),
-      duplicate: A.operation("get", { PK: "PK#1", SK: "SK#1" })
+      duplicate: A.operation("get", { PK: "PK#1", SK: "SK#1" }),
     })
 
     expect(
@@ -1640,6 +1640,41 @@ describe("load", () => {
       ).resolves.toBeNull()
     })
 
+    test("it recovers a soft deleted item", async () => {
+      const item = new A({ pk: "PK#1", sk: "SK#1", a: 1 })
+
+      await sandbox.seed(item)
+
+      await item.softDelete()
+
+      const recovered = await client.load(
+        A.operation("get", { PK: "PK#1", SK: "SK#1" }),
+        {
+          recover: true,
+        }
+      )
+
+      expect(recovered).toBeInstanceOf(A)
+      expect(recovered.isDeleted).toBe(true)
+    })
+
+    test("it throws if no item or soft deleted item exists", async () => {
+      await expect(
+        client.load(A.operation("get", { PK: "PK", SK: "SK" }), {
+          recover: true,
+        })
+      ).rejects.toBeInstanceOf(ItemNotFoundError)
+    })
+
+    test("it returns null instead of throwing if no item or soft deleted item exists", async () => {
+      await expect(
+        client.load(A.operation("get", { PK: "PK", SK: "SK" }), {
+          recover: true,
+          null: true,
+        })
+      ).resolves.toBeNull()
+    })
+
     test("it fetches >100 items", async () => {
       const items = Array.from({ length: 234 }).map((_, i) =>
         i < 100
@@ -1730,8 +1765,8 @@ describe("load", () => {
       )
 
       expect(results.length).toBe(234)
-      expect(results.filter(item => item instanceof C).length).toBe(123)
-      expect(results.filter(item => item instanceof D).length).toBe(111)
+      expect(results.filter((item) => item instanceof C).length).toBe(123)
+      expect(results.filter((item) => item instanceof D).length).toBe(111)
       expect(spy).toHaveBeenCalledTimes(3)
 
       spy.mockReset()
@@ -1806,8 +1841,8 @@ describe("loadMany", () => {
       )
 
       expect(results.length).toBe(234)
-      expect(results.filter(item => item instanceof C).length).toBe(123)
-      expect(results.filter(item => item instanceof D).length).toBe(111)
+      expect(results.filter((item) => item instanceof C).length).toBe(123)
+      expect(results.filter((item) => item instanceof D).length).toBe(111)
       expect(spy).toHaveBeenCalledTimes(3)
 
       spy.mockReset()
@@ -1832,7 +1867,7 @@ describe("paginate", () => {
         {},
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page1.pageInfo).toMatchInlineSnapshot(`
@@ -1852,7 +1887,7 @@ describe("paginate", () => {
         { after: page1.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page2.pageInfo).toMatchInlineSnapshot(`
@@ -1872,7 +1907,7 @@ describe("paginate", () => {
         { after: page2.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page3.pageInfo).toMatchInlineSnapshot(`
@@ -1893,7 +1928,7 @@ describe("paginate", () => {
         { before: page3.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage2.pageInfo).toMatchInlineSnapshot(`
@@ -1913,7 +1948,7 @@ describe("paginate", () => {
         { before: backwardsPage2.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage1.pageInfo).toMatchInlineSnapshot(`
@@ -1944,7 +1979,7 @@ describe("paginate", () => {
         {},
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page1.pageInfo).toMatchInlineSnapshot(`
@@ -1964,7 +1999,7 @@ describe("paginate", () => {
         { after: page1.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page2.pageInfo).toMatchInlineSnapshot(`
@@ -1984,7 +2019,7 @@ describe("paginate", () => {
         { after: page2.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page3.pageInfo).toMatchInlineSnapshot(`
@@ -2005,7 +2040,7 @@ describe("paginate", () => {
         { before: page3.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage2.pageInfo).toMatchInlineSnapshot(`
@@ -2025,7 +2060,7 @@ describe("paginate", () => {
         { before: backwardsPage2.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage1.pageInfo).toMatchInlineSnapshot(`
@@ -2055,7 +2090,7 @@ describe("paginate", () => {
         { first: 10 },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page.pageInfo).toMatchInlineSnapshot(`
@@ -2085,7 +2120,7 @@ describe("paginate", () => {
         { first: 60 },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page1.pageInfo).toMatchInlineSnapshot(`
@@ -2116,7 +2151,7 @@ describe("paginate", () => {
         {},
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page1.pageInfo).toMatchInlineSnapshot(`
@@ -2135,7 +2170,7 @@ describe("paginate", () => {
         { after: page1.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page2.pageInfo).toMatchInlineSnapshot(`
@@ -2154,7 +2189,7 @@ describe("paginate", () => {
         { after: page2.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page3.pageInfo).toMatchInlineSnapshot(`
@@ -2174,7 +2209,7 @@ describe("paginate", () => {
         { before: page3.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage2.pageInfo).toMatchInlineSnapshot(`
@@ -2193,7 +2228,7 @@ describe("paginate", () => {
         { before: backwardsPage2.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage1.pageInfo).toMatchInlineSnapshot(`
@@ -2222,7 +2257,7 @@ describe("paginate", () => {
         { first: 10 },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page.pageInfo).toMatchInlineSnapshot(`
@@ -2251,7 +2286,7 @@ describe("paginate", () => {
         { first: 60 },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page1.pageInfo).toMatchInlineSnapshot(`
@@ -2283,7 +2318,7 @@ describe("paginate", () => {
         {},
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page1.pageInfo).toMatchInlineSnapshot(`
@@ -2302,7 +2337,7 @@ describe("paginate", () => {
         { after: page1.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page2.pageInfo).toMatchInlineSnapshot(`
@@ -2321,7 +2356,7 @@ describe("paginate", () => {
         { after: page2.pageInfo.endCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page3.pageInfo).toMatchInlineSnapshot(`
@@ -2341,7 +2376,7 @@ describe("paginate", () => {
         { before: page3.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage2.pageInfo).toMatchInlineSnapshot(`
@@ -2360,7 +2395,7 @@ describe("paginate", () => {
         { before: backwardsPage2.pageInfo.startCursor },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(backwardsPage1.pageInfo).toMatchInlineSnapshot(`
@@ -2390,7 +2425,7 @@ describe("paginate", () => {
         { first: 10 },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page.pageInfo).toMatchInlineSnapshot(`
@@ -2420,7 +2455,7 @@ describe("paginate", () => {
         { first: 60 },
         {
           KeyConditionExpression: "PK = :pk",
-          ExpressionAttributeValues: { ":pk": "PK" }
+          ExpressionAttributeValues: { ":pk": "PK" },
         }
       )
       expect(page1.pageInfo).toMatchInlineSnapshot(`

package/src/client.ts

@@ -79,6 +79,12 @@ export interface ClientProps
     ServiceConfigurationOptions,
     ClientApiVersions {
   tableName: string
+
+  /**
+   * The encryption key used to encrypt cursors using AES-256-CTR.
+   * Must be a 32 character string, 256 bits.
+   */
+  cursorEncryptionKey?: Buffer
 }
 
 export interface Key {
@@ -90,9 +96,11 @@ export class Client {
   tableName: string
   documentClient: DocumentClient
   dataLoader: DataLoader<GetOperation<Decodable>, DynamoDBModelInstance, string>
+  cursorEncryptionKey?: Buffer
 
   constructor(props: ClientProps) {
     this.tableName = props?.tableName
+    this.cursorEncryptionKey = props?.cursorEncryptionKey
     this.documentClient = new DocumentClient(props)
     this.dataLoader = new DataLoader<
       GetOperation<Decodable>,
@@ -189,7 +197,7 @@ export class Client {
     const { Item } = await this.documentClient
       .get({
         TableName: this.tableName,
-        Key: key,
+        Key: { PK: key.PK, SK: key.SK },
         ...params,
       })
       .promise()
@@ -199,15 +207,45 @@ export class Client {
     return (_model as M & DynamoDBInternals<M>).__dynamoDBDecode(Item) as any
   }
 
-  async load<M extends Decodable, Null extends boolean = false>(
+  async load<
+    M extends Decodable,
+    Null extends boolean = false,
+    Recover extends boolean = false
+  >(
     operation: GetOperation<M>,
-    params?: { null?: Null }
+    params?: { null?: Null; recover?: Recover }
   ): Promise<
-    Null extends true ? DecodableInstance<M> | null : DecodableInstance<M>
+    Recover extends true
+      ? Null extends true
+        ? (DecodableInstance<M> & { isDeleted?: true }) | null
+        : DecodableInstance<M> & { isDeleted?: true }
+      : Null extends true
+      ? DecodableInstance<M> | null
+      : DecodableInstance<M>
   > {
     const item = await this.dataLoader.load(operation).catch((e) => {
       // Maybe return null instead of throwing
-      if (e instanceof ItemNotFoundError && params?.null) return null
+      if (e instanceof ItemNotFoundError) {
+        // Try to recover a deleted item
+        if (params?.recover)
+          return this.dataLoader
+            .load({
+              ...operation,
+              key: {
+                PK: `$$DELETED$$${operation.key.PK}`,
+                SK: `$$DELETED$$${operation.key.SK}`,
+              },
+            })
+            .then((item) => Object.assign(item, { isDeleted: true }))
+            .catch((e2) => {
+              if (e2 instanceof ItemNotFoundError && params.null) return null
+
+              // Throw the original error
+              throw e
+            })
+
+        if (params?.null) return null
+      }
 
       throw e
     })
@@ -494,7 +532,16 @@ export class Client {
         ...params,
         // Fetch one additional item to test for a next page
         Limit: limit + 1,
-        ExclusiveStartKey: cursor ? decodeDDBCursor(cursor) : undefined,
+        ExclusiveStartKey: cursor
+          ? decodeDDBCursor(
+              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")
+                : undefined,
+              this.cursorEncryptionKey
+            )
+          : undefined,
         ScanIndexForward: direction === PaginationDirection.FORWARD,
       },
       { results: model }
@@ -509,13 +556,7 @@ export class Client {
     // Build edges
     const edges = slice.map((item: any) => ({
       node: item,
-      cursor: encodeDDBCursor(
-        item,
-        // GSI1 is the inverse index and uses PK and SK (switched around)
-        params.IndexName && params.IndexName !== "GSI1"
-          ? (params.IndexName as "GSI2" | "GSI3")
-          : undefined
-      ),
+      cursor: encodeDDBCursor(item, this.cursorEncryptionKey),
     }))
 
     return {

package/src/dynamodb-model.ts

@@ -11,6 +11,10 @@ export interface DynamoDBModelInstance extends ModelInstance<string, any> {
     GSI2SK?: string
     GSI3PK?: string
     GSI3SK?: string
+    GSI4PK?: string
+    GSI4SK?: string
+    GSI5PK?: string
+    GSI5SK?: string
   }
 
   PK: string