feat: added upsert by id/index + passing tests

Author: oliver-oloughlin

src/collection.ts

@@ -11,6 +11,7 @@ import type {
   HistoryEntry,
   IdempotentListener,
   IdGenerator,
+  IdUpsertInput,
   IndexDataEntry,
   KvId,
   KvKey,
@@ -22,6 +23,7 @@ import type {
   ParseInputType,
   PossibleCollectionOptions,
   PrimaryIndexKeys,
+  PrimaryIndexUpsertInput,
   QueueHandlers,
   QueueListenerOptions,
   QueueMessageHandler,
@@ -33,6 +35,8 @@ import type {
   UpdateData,
   UpdateManyOptions,
   UpdateOptions,
+  UpsertInput,
+  UpsertOptions,
   WatchOptions,
 } from "./types.ts"
 import {
@@ -830,6 +834,57 @@ export class Collection<
     )
   }
 
+  async upsert<
+    const TIndex extends PrimaryIndexKeys<TOutput, TOptions>,
+  >(
+    input: UpsertInput<TInput, TOutput, TIndex>,
+    options?: UpsertOptions,
+  ) {
+    // Check if is id or primary index upsert
+    if ((input as any).index !== undefined) {
+      const inp = input as PrimaryIndexUpsertInput<TInput, TOutput, TIndex>
+
+      // First attempt update
+      const updateCr = await this.updateByPrimaryIndex(
+        ...inp.index,
+        inp.update,
+        options,
+      )
+
+      if (updateCr.ok) {
+        return updateCr
+      }
+
+      // If id is present, set new entry with given id
+      if (inp.id) {
+        return await this.set(inp.id, inp.set, {
+          ...options,
+          overwrite: false,
+        })
+      }
+
+      // If no id, set new entry with generated id
+      return await this.add(inp.set, {
+        ...options,
+        overwrite: false,
+      })
+    } else {
+      // First attempt update
+      const id = (input as IdUpsertInput<TInput, TOutput>).id
+      const updateCr = await this.update(id, input.update, options)
+
+      if (updateCr.ok) {
+        return updateCr
+      }
+
+      // Set new entry with given id
+      return await this.set(id, input.set, {
+        ...options,
+        overwrite: false,
+      })
+    }
+  }
+
   /**
    * Update the value of multiple existing documents in the collection.
    *

src/types.ts

@@ -351,9 +351,9 @@ export type SetOptions = NonNullable<Parameters<Deno.Kv["set"]>["2"]> & {
 
 export type ListOptions<T> = Deno.KvListOptions & {
   /**
-   * Filter documents based on predicate.
+   * Filter based on predicate.
    *
-   * @param doc - Document.
+   * @param value - Input value.
    * @returns true or false.
    */
   filter?: (value: T) => boolean
@@ -415,6 +415,33 @@ export type QueueListenerOptions = {
 
 export type WatchOptions = NonNullable<Parameters<Deno.Kv["watch"]>[1]>
 
+export type IdUpsertInput<TInput, TOutput extends KvValue> = {
+  id: KvId
+  set: ParseInputType<TInput, TOutput>
+  update: UpdateData<TOutput>
+}
+
+export type PrimaryIndexUpsertInput<
+  TInput,
+  TOutput extends KvValue,
+  TIndex,
+> = {
+  id?: KvId
+  index: [TIndex, CheckKeyOf<TIndex, TOutput>]
+  set: ParseInputType<TInput, TOutput>
+  update: UpdateData<TOutput>
+}
+
+export type UpsertInput<
+  TInput,
+  TOutput extends KvValue,
+  TIndex,
+> =
+  | IdUpsertInput<TInput, TOutput>
+  | PrimaryIndexUpsertInput<TInput, TOutput, TIndex>
+
+export type UpsertOptions = UpdateOptions
+
 /********************/
 /*                  */
 /*   SCHEMA TYPES   */

tests/collection/upsert.test.ts

@@ -0,0 +1,44 @@
+import { assert } from "../deps.ts"
+import { mockUser1, mockUser2, mockUser3 } from "../mocks.ts"
+import { useDb } from "../utils.ts"
+
+Deno.test("collection - upsert", async (t) => {
+  await t.step("Should set new doucment entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr = await db.users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr.ok)
+
+      const doc = await db.users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser2.username)
+    })
+  })
+
+  await t.step("Should update existing document entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr1 = await db.users.set(id, mockUser1)
+      assert(cr1.ok)
+
+      const cr2 = await db.users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr2.ok)
+
+      const doc = await db.users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser3.username)
+    })
+  })
+})

tests/indexable_collection/upsert.test.ts

@@ -0,0 +1,81 @@
+import { assert } from "../deps.ts"
+import { mockUser1, mockUser2, mockUser3 } from "../mocks.ts"
+import { useDb } from "../utils.ts"
+
+Deno.test("indexable_collection - upsert", async (t) => {
+  await t.step("Should set new doucment entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr = await db.i_users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr.ok)
+
+      const doc = await db.i_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser2.username)
+    })
+  })
+
+  await t.step("Should set new doucment entry by index", async () => {
+    await useDb(async (db) => {
+      const cr = await db.i_users.upsert({
+        index: ["username", mockUser1.username],
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr.ok)
+
+      const doc = await db.i_users.find(cr.id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser2.username)
+    })
+  })
+
+  await t.step("Should update existing document entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr1 = await db.i_users.set(id, mockUser1)
+      assert(cr1.ok)
+
+      const cr2 = await db.i_users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr2.ok)
+
+      const doc = await db.i_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser3.username)
+    })
+  })
+
+  await t.step("Should update existing document entry by index", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr1 = await db.i_users.set(id, mockUser1)
+      assert(cr1.ok)
+
+      const cr2 = await db.i_users.upsert({
+        index: ["username", mockUser1.username],
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr2.ok)
+
+      const doc = await db.i_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser3.username)
+    })
+  })
+})

tests/serialized_collection/upsert.test.ts

@@ -0,0 +1,44 @@
+import { assert } from "../deps.ts"
+import { mockUser1, mockUser2, mockUser3 } from "../mocks.ts"
+import { useDb } from "../utils.ts"
+
+Deno.test("serialized_collection - upsert", async (t) => {
+  await t.step("Should set new doucment entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr = await db.s_users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr.ok)
+
+      const doc = await db.s_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser2.username)
+    })
+  })
+
+  await t.step("Should update existing document entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr1 = await db.s_users.set(id, mockUser1)
+      assert(cr1.ok)
+
+      const cr2 = await db.s_users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr2.ok)
+
+      const doc = await db.s_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser3.username)
+    })
+  })
+})

tests/serialized_indexable_collection/upsert.test.ts

@@ -0,0 +1,81 @@
+import { assert } from "../deps.ts"
+import { mockUser1, mockUser2, mockUser3 } from "../mocks.ts"
+import { useDb } from "../utils.ts"
+
+Deno.test("serialized_indexable_collection - upsert", async (t) => {
+  await t.step("Should set new doucment entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr = await db.is_users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr.ok)
+
+      const doc = await db.is_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser2.username)
+    })
+  })
+
+  await t.step("Should set new doucment entry by index", async () => {
+    await useDb(async (db) => {
+      const cr = await db.is_users.upsert({
+        index: ["username", mockUser1.username],
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr.ok)
+
+      const doc = await db.is_users.find(cr.id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser2.username)
+    })
+  })
+
+  await t.step("Should update existing document entry by id", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr1 = await db.is_users.set(id, mockUser1)
+      assert(cr1.ok)
+
+      const cr2 = await db.is_users.upsert({
+        id: id,
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr2.ok)
+
+      const doc = await db.is_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser3.username)
+    })
+  })
+
+  await t.step("Should update existing document entry by index", async () => {
+    await useDb(async (db) => {
+      const id = "id"
+
+      const cr1 = await db.is_users.set(id, mockUser1)
+      assert(cr1.ok)
+
+      const cr2 = await db.is_users.upsert({
+        index: ["username", mockUser1.username],
+        set: mockUser2,
+        update: mockUser3,
+      })
+
+      assert(cr2.ok)
+
+      const doc = await db.is_users.find(id)
+      assert(doc !== null)
+      assert(doc.value.username === mockUser3.username)
+    })
+  })
+})