@model-ts/dynamodb 4.0.0 → 4.2.0

package/src/__test__/in-memory.spec.test.ts

@@ -0,0 +1,230 @@
+import * as t from "io-ts"
+import { model } from "@model-ts/core"
+import { Client } from "../client"
+import { getProvider } from "../provider"
+import { createSandbox, Sandbox } from "../sandbox"
+import { NotSupportedError } from "../errors"
+import { IN_MEMORY_SPEC } from "../in-memory/spec"
+
+const CODEC = t.type({
+  id: t.string,
+  group: t.string,
+  value: t.number,
+})
+
+const withInMemory = async <T>(
+  run: (ctx: {
+    client: Client
+    sandbox: Sandbox
+    Item: any
+  }) => Promise<T>
+): Promise<T> => {
+  const previous = process.env.EXPERIMENTAL_DYNAMODB_IN_MEMORY
+  process.env.EXPERIMENTAL_DYNAMODB_IN_MEMORY = "1"
+
+  const client = new Client({ tableName: "table" })
+  const provider = getProvider(client)
+
+  class Item extends model("Item", CODEC, provider) {
+    get PK() {
+      return `PK#${this.group}`
+    }
+
+    get SK() {
+      return `SK#${String(this.value).padStart(3, "0")}`
+    }
+
+    get GSI2PK() {
+      return `GSI2PK#${this.group}`
+    }
+
+    get GSI2SK() {
+      return `GSI2SK#${this.id}`
+    }
+  }
+
+  const sandbox = await createSandbox(client)
+
+  try {
+    return await run({ client, sandbox, Item })
+  } finally {
+    await sandbox.destroy()
+
+    if (typeof previous === "undefined")
+      delete process.env.EXPERIMENTAL_DYNAMODB_IN_MEMORY
+    else process.env.EXPERIMENTAL_DYNAMODB_IN_MEMORY = previous
+  }
+}
+
+describe("in-memory spec", () => {
+  test("locks projection and index scope", () => {
+    expect(IN_MEMORY_SPEC.projection).toBe("ALL")
+    expect(IN_MEMORY_SPEC.excludedIndexes).toEqual(["GSI1"])
+    expect(IN_MEMORY_SPEC.indexes.includes("primary")).toBe(true)
+    expect(IN_MEMORY_SPEC.indexes.includes("GSI2")).toBe(true)
+    expect(IN_MEMORY_SPEC.indexes.includes("GSI19")).toBe(true)
+    expect(IN_MEMORY_SPEC.indexes.includes("GSI1" as any)).toBe(false)
+  })
+
+  test("throws deterministic NotSupportedError for unsupported method", async () => {
+    await withInMemory(async ({ client }) => {
+      await expect(
+        (client.documentClient as any).transactGet({}).promise()
+      ).rejects.toMatchObject({
+        name: "NotSupportedError",
+        code: "NotSupportedError",
+        method: "transactGet",
+        featurePath: "transactGet",
+      })
+    })
+  })
+
+  test("rejects GSI1 with deterministic NotSupportedError", async () => {
+    await withInMemory(async ({ client, Item }) => {
+      await new Item({ id: "1", group: "g", value: 1 }).put()
+
+      await expect(
+        client.documentClient
+          .query({
+            TableName: client.tableName,
+            IndexName: "GSI1",
+            KeyConditionExpression: "PK = :pk",
+            ExpressionAttributeValues: { ":pk": "PK#g" },
+          })
+          .promise()
+      ).rejects.toMatchObject({
+        name: "NotSupportedError",
+        code: "NotSupportedError",
+        method: "query",
+        featurePath: "query.IndexName",
+      })
+    })
+  })
+
+  test("keeps GSI membership in sync after update/removal", async () => {
+    await withInMemory(async ({ client, Item }) => {
+      const item = await new Item({ id: "42", group: "test", value: 42 }).put()
+
+      const before = await client.documentClient
+        .query({
+          TableName: client.tableName,
+          IndexName: "GSI2",
+          KeyConditionExpression: "GSI2PK = :pk",
+          ExpressionAttributeValues: { ":pk": "GSI2PK#test" },
+        })
+        .promise()
+
+      expect(before.Count).toBe(1)
+
+      await Item.updateRaw(
+        { PK: item.PK, SK: item.SK },
+        { GSI2PK: null, GSI2SK: null } as any
+      )
+
+      const after = await client.documentClient
+        .query({
+          TableName: client.tableName,
+          IndexName: "GSI2",
+          KeyConditionExpression: "GSI2PK = :pk",
+          ExpressionAttributeValues: { ":pk": "GSI2PK#test" },
+        })
+        .promise()
+
+      expect(after.Count).toBe(0)
+    })
+  })
+
+  test("supports if_not_exists in update expressions", async () => {
+    await withInMemory(async ({ client, Item }) => {
+      const item = await new Item({ id: "100", group: "expr", value: 1 }).put()
+
+      const first = await client.documentClient
+        .update({
+          TableName: client.tableName,
+          Key: { PK: item.PK, SK: item.SK },
+          UpdateExpression: "SET #count = if_not_exists(#count, :zero) + :inc",
+          ExpressionAttributeNames: { "#count": "count" },
+          ExpressionAttributeValues: { ":zero": 0, ":inc": 2 },
+          ReturnValues: "ALL_NEW",
+        })
+        .promise()
+
+      expect(first.Attributes?.count).toBe(2)
+
+      const second = await client.documentClient
+        .update({
+          TableName: client.tableName,
+          Key: { PK: item.PK, SK: item.SK },
+          UpdateExpression: "SET #count = if_not_exists(#count, :zero) + :inc",
+          ExpressionAttributeNames: { "#count": "count" },
+          ExpressionAttributeValues: { ":zero": 0, ":inc": 3 },
+          ReturnValues: "ALL_NEW",
+        })
+        .promise()
+
+      expect(second.Attributes?.count).toBe(5)
+    })
+  })
+
+  test("supports list_append and filter functions", async () => {
+    await withInMemory(async ({ client, Item }) => {
+      const item = await new Item({ id: "200", group: "expr", value: 2 }).put()
+
+      await client.documentClient
+        .update({
+          TableName: client.tableName,
+          Key: { PK: item.PK, SK: item.SK },
+          UpdateExpression:
+            "SET #tags = list_append(if_not_exists(#tags, :empty), :more)",
+          ExpressionAttributeNames: { "#tags": "tags" },
+          ExpressionAttributeValues: { ":empty": [], ":more": ["a", "b"] },
+          ReturnValues: "ALL_NEW",
+        })
+        .promise()
+
+      const filtered = await client.documentClient
+        .scan({
+          TableName: client.tableName,
+          FilterExpression:
+            "contains(#tags, :tag) and attribute_type(#id, :t) and size(#id) > :min",
+          ExpressionAttributeNames: { "#tags": "tags", "#id": "id" },
+          ExpressionAttributeValues: { ":tag": "a", ":t": "S", ":min": 1 },
+        })
+        .promise()
+
+      expect(filtered.Count).toBe(1)
+      expect(filtered.Items?.[0]?.id).toBe("200")
+    })
+  })
+
+  test("is deterministic for repeated seeded runs", async () => {
+    const execute = async () =>
+      withInMemory(async ({ client, sandbox, Item }) => {
+        const order = [7, 1, 9, 2, 8, 3, 6, 4, 5, 0]
+
+        await Promise.all(
+          order.map((value) =>
+            new Item({ id: String(value), group: "det", value }).put()
+          )
+        )
+
+        const page = await client.documentClient
+          .query({
+            TableName: client.tableName,
+            KeyConditionExpression: "PK = :pk",
+            ExpressionAttributeValues: { ":pk": "PK#det" },
+          })
+          .promise()
+
+        return {
+          snapshot: await sandbox.snapshot(),
+          queryKeys: (page.Items ?? []).map((entry) => `${entry.PK}::${entry.SK}`),
+        }
+      })
+
+    const first = await execute()
+    const second = await execute()
+
+    expect(second).toEqual(first)
+  })
+})

package/src/__test__/rollback.test.ts

@@ -0,0 +1,279 @@
+import * as t from "io-ts"
+import { model } from "@model-ts/core"
+import { Sandbox, createSandbox } from "../sandbox"
+import { Client } from "../client"
+import { getProvider } from "../provider"
+
+const client = new Client({ tableName: "table" })
+const provider = getProvider(client)
+
+const SIMPLE_CODEC = t.type({
+  foo: t.string,
+  bar: t.number,
+})
+
+class Simple extends model("Simple", SIMPLE_CODEC, provider) {
+  get PK() {
+    return `PK#${this.foo}`
+  }
+
+  get SK() {
+    return `SK#${this.bar}`
+  }
+}
+
+describe("rollback", () => {
+  let sandbox: Sandbox
+
+  beforeAll(async () => {
+    sandbox = await createSandbox(client)
+    await sandbox.seed(
+      new Simple({ foo: "seeded1", bar: 1 }),
+      new Simple({ foo: "seeded2", bar: 2 })
+    )
+  })
+
+  afterAll(async () => {
+    await sandbox.destroy()
+  })
+
+  test("rolls back newly added items", async () => {
+    sandbox.startTracking()
+
+    await new Simple({ foo: "new-item", bar: 99 }).put()
+    expect(await sandbox.get("PK#new-item", "SK#99")).not.toBeNull()
+
+    await sandbox.rollback()
+
+    expect(await sandbox.get("PK#new-item", "SK#99")).toBeNull()
+    expect(await sandbox.get("PK#seeded1", "SK#1")).not.toBeNull()
+    expect(await sandbox.get("PK#seeded2", "SK#2")).not.toBeNull()
+  })
+
+  test("rolls back updated items", async () => {
+    sandbox.startTracking()
+
+    await Simple.updateRaw(
+      { PK: "PK#seeded1", SK: "SK#1" },
+      { foo: "modified" }
+    )
+
+    const modified = await sandbox.get("PK#seeded1", "SK#1")
+    expect(modified.foo).toBe("modified")
+
+    await sandbox.rollback()
+
+    const restored = await sandbox.get("PK#seeded1", "SK#1")
+    expect(restored.foo).toBe("seeded1")
+  })
+
+  test("rolls back deleted items", async () => {
+    sandbox.startTracking()
+
+    await Simple.delete({ PK: "PK#seeded1", SK: "SK#1" })
+    expect(await sandbox.get("PK#seeded1", "SK#1")).toBeNull()
+
+    await sandbox.rollback()
+
+    const restored = await sandbox.get("PK#seeded1", "SK#1")
+    expect(restored).not.toBeNull()
+    expect(restored.foo).toBe("seeded1")
+  })
+
+  test("rolls back soft-deleted items", async () => {
+    sandbox.startTracking()
+
+    const item = new Simple({ foo: "seeded1", bar: 1 })
+    // @ts-ignore - _docVersion needed for softDelete encoding
+    item._docVersion = 0
+    await client.softDelete(item)
+
+    // Original should be gone, deleted version should exist
+    expect(await sandbox.get("PK#seeded1", "SK#1")).toBeNull()
+    expect(
+      await sandbox.get("$$DELETED$$PK#seeded1", "$$DELETED$$SK#1")
+    ).not.toBeNull()
+
+    await sandbox.rollback()
+
+    // Original should be restored, deleted version should be gone
+    expect(await sandbox.get("PK#seeded1", "SK#1")).not.toBeNull()
+    expect(
+      await sandbox.get("$$DELETED$$PK#seeded1", "$$DELETED$$SK#1")
+    ).toBeNull()
+  })
+
+  test("rolls back mixed operations", async () => {
+    sandbox.startTracking()
+
+    // Add a new item
+    await new Simple({ foo: "brand-new", bar: 50 }).put()
+
+    // Update an existing item
+    await Simple.updateRaw(
+      { PK: "PK#seeded1", SK: "SK#1" },
+      { foo: "changed" }
+    )
+
+    // Delete an existing item
+    await Simple.delete({ PK: "PK#seeded2", SK: "SK#2" })
+
+    // Verify all changes took effect
+    expect(await sandbox.get("PK#brand-new", "SK#50")).not.toBeNull()
+    expect((await sandbox.get("PK#seeded1", "SK#1")).foo).toBe("changed")
+    expect(await sandbox.get("PK#seeded2", "SK#2")).toBeNull()
+
+    await sandbox.rollback()
+
+    // New item should be gone
+    expect(await sandbox.get("PK#brand-new", "SK#50")).toBeNull()
+    // Updated item should be restored
+    expect((await sandbox.get("PK#seeded1", "SK#1")).foo).toBe("seeded1")
+    // Deleted item should be back
+    expect(await sandbox.get("PK#seeded2", "SK#2")).not.toBeNull()
+  })
+
+  test("supports multiple tracking/rollback cycles", async () => {
+    // Cycle 1
+    sandbox.startTracking()
+    await new Simple({ foo: "cycle1", bar: 10 }).put()
+    await sandbox.rollback()
+    expect(await sandbox.get("PK#cycle1", "SK#10")).toBeNull()
+
+    // Cycle 2
+    sandbox.startTracking()
+    await new Simple({ foo: "cycle2", bar: 20 }).put()
+    await sandbox.rollback()
+    expect(await sandbox.get("PK#cycle2", "SK#20")).toBeNull()
+
+    // Cycle 3 - modify seeded data
+    sandbox.startTracking()
+    await Simple.updateRaw(
+      { PK: "PK#seeded1", SK: "SK#1" },
+      { foo: "cycle3-mod" }
+    )
+    await sandbox.rollback()
+    expect((await sandbox.get("PK#seeded1", "SK#1")).foo).toBe("seeded1")
+
+    // Seeded data is intact throughout
+    expect(await sandbox.get("PK#seeded1", "SK#1")).not.toBeNull()
+    expect(await sandbox.get("PK#seeded2", "SK#2")).not.toBeNull()
+  })
+
+  test("does not track writes before startTracking", async () => {
+    // Write without tracking
+    await new Simple({ foo: "untracked", bar: 77 }).put()
+
+    // Now start tracking and immediately rollback
+    sandbox.startTracking()
+    await sandbox.rollback()
+
+    // The untracked write should still be there
+    expect(await sandbox.get("PK#untracked", "SK#77")).not.toBeNull()
+
+    // Clean up manually for subsequent tests
+    sandbox.startTracking()
+    await Simple.delete({ PK: "PK#untracked", SK: "SK#77" })
+    await sandbox.rollback()
+  })
+
+  test("tracks the same key modified multiple times", async () => {
+    sandbox.startTracking()
+
+    // Update the same item twice
+    await Simple.updateRaw(
+      { PK: "PK#seeded1", SK: "SK#1" },
+      { foo: "first-update" }
+    )
+    await Simple.updateRaw(
+      { PK: "PK#seeded1", SK: "SK#1" },
+      { foo: "second-update" }
+    )
+
+    expect((await sandbox.get("PK#seeded1", "SK#1")).foo).toBe("second-update")
+
+    await sandbox.rollback()
+
+    // Should restore to original, not to the intermediate state
+    expect((await sandbox.get("PK#seeded1", "SK#1")).foo).toBe("seeded1")
+  })
+})
+
+describe("rollback with beforeEach/afterEach pattern", () => {
+  let sandbox: Sandbox
+
+  beforeAll(async () => {
+    sandbox = await createSandbox(client)
+    await sandbox.seed(
+      new Simple({ foo: "a", bar: 1 }),
+      new Simple({ foo: "b", bar: 2 })
+    )
+  })
+
+  beforeEach(() => {
+    sandbox.startTracking()
+  })
+
+  afterEach(async () => {
+    await sandbox.rollback()
+  })
+
+  afterAll(async () => {
+    await sandbox.destroy()
+  })
+
+  test("test A: add an item", async () => {
+    await new Simple({ foo: "from-test-a", bar: 100 }).put()
+    expect(await sandbox.get("PK#from-test-a", "SK#100")).not.toBeNull()
+  })
+
+  test("test B: item from test A does not exist", async () => {
+    expect(await sandbox.get("PK#from-test-a", "SK#100")).toBeNull()
+  })
+
+  test("test C: modify seeded data", async () => {
+    await Simple.updateRaw({ PK: "PK#a", SK: "SK#1" }, { foo: "modified-a" })
+    expect((await sandbox.get("PK#a", "SK#1")).foo).toBe("modified-a")
+  })
+
+  test("test D: seeded data is back to original", async () => {
+    expect((await sandbox.get("PK#a", "SK#1")).foo).toBe("a")
+  })
+
+  test("test E: delete seeded data", async () => {
+    await Simple.delete({ PK: "PK#b", SK: "SK#2" })
+    expect(await sandbox.get("PK#b", "SK#2")).toBeNull()
+  })
+
+  test("test F: deleted seeded data is back", async () => {
+    expect(await sandbox.get("PK#b", "SK#2")).not.toBeNull()
+    expect((await sandbox.get("PK#b", "SK#2")).foo).toBe("b")
+  })
+})
+
+describe("existing sandbox semantics still work", () => {
+  let sandbox: Sandbox
+
+  beforeEach(async () => {
+    sandbox = await createSandbox(client)
+  })
+
+  afterEach(async () => {
+    await sandbox.destroy()
+  })
+
+  test("create and destroy per test still works", async () => {
+    await sandbox.seed(new Simple({ foo: "per-test", bar: 1 }))
+
+    const item = await sandbox.get("PK#per-test", "SK#1")
+    expect(item).not.toBeNull()
+    expect(item.foo).toBe("per-test")
+  })
+
+  test("snapshot and diff still work", async () => {
+    const before = await sandbox.snapshot()
+    await new Simple({ foo: "diffed", bar: 1 }).put()
+    const diffResult = await sandbox.diff(before)
+    expect(diffResult).toContain("PK#diffed")
+  })
+})

package/src/client.ts

@@ -44,6 +44,7 @@ import {
   PaginationResult,
 } from "./pagination"
 import { GSI, GSI_NAMES, GSIPK, GSISK } from "./gsi"
+import { createInMemoryDocumentClient } from "./in-memory"
 
 export type QueryParams = Omit<
   DocumentClient.QueryInput,
@@ -110,7 +111,18 @@ export class Client {
     this.tableName = props?.tableName
     this.cursorEncryptionKey = props?.cursorEncryptionKey
     this.paginationOptions = props?.paginationOptions
-    this.documentClient = new DocumentClient(props)
+
+    const inMemoryRequested = process.env.EXPERIMENTAL_DYNAMODB_IN_MEMORY === "1"
+    if (inMemoryRequested && process.env.NODE_ENV !== "test") {
+      throw new Error(
+        `EXPERIMENTAL_DYNAMODB_IN_MEMORY=1 is only allowed when NODE_ENV is "test" (received "${process.env.NODE_ENV ?? "undefined"}").`
+      )
+    }
+
+    this.documentClient =
+      inMemoryRequested
+        ? (createInMemoryDocumentClient() as any as DocumentClient)
+        : new DocumentClient(props)
     this.dataLoader = new DataLoader<
       GetOperation<Decodable>,
       DynamoDBModelInstance,
@@ -160,6 +172,7 @@ export class Client {
     M extends DynamoDBModelConstructor<T>
   >({
     _model,
+    _operation,
     _deleted,
     item,
     IgnoreExistence,
@@ -200,6 +213,7 @@ export class Client {
 
   async get<M extends Decodable>({
     _model,
+    _operation,
     key,
     ...params
   }: GetOperation<M>): Promise<DecodableInstance<M>> {
@@ -272,7 +286,7 @@ export class Client {
   async updateRaw<M extends DynamoDBModelConstructor<any>>(
     operation: UpdateRawOperation<M>
   ): Promise<InstanceType<M>> {
-    const { _model, key, attributes, ...params } = operation
+    const { _model, _operation, key, attributes, ...params } = operation
 
     const {
       UpdateExpression,
@@ -831,8 +845,7 @@ export class Client {
   ): DocumentClient.TransactWriteItem => {
     switch (operation._operation) {
       case "put": {
-        const { _model, _deleted, item, IgnoreExistence, ...params } = operation
-        debugger
+        const { _model, _operation, _deleted, item, IgnoreExistence, ...params } = operation
         const encoded = (_model as M & DynamoDBInternals<M>).__dynamoDBEncode(
           item
         )

package/src/errors.ts

@@ -45,6 +45,29 @@ export class PaginationError extends Error {
   name = "PaginationError"
 }
 
+export class NotSupportedError extends Error {
+  name = "NotSupportedError"
+  code = "NotSupportedError"
+  method: string
+  featurePath: string
+  reason: string
+
+  constructor({
+    method,
+    featurePath,
+    reason,
+  }: {
+    method: string
+    featurePath: string
+    reason: string
+  }) {
+    super(reason)
+    this.method = method
+    this.featurePath = featurePath
+    this.reason = reason
+  }
+}
+
 export type DynamoDBError =
   | KeyExistsError
   | ItemNotFoundError
@@ -52,3 +75,4 @@ export type DynamoDBError =
   | BulkWriteTransactionError
   | BulkWriteRollbackError
   | PaginationError
+  | NotSupportedError