Merge pull request #144 from oliver-oloughlin/feature/watch

Feature/watch

README.md

@@ -4,9 +4,9 @@
 dependencies. It's purpose is to enhance the experience of using Deno's KV store
 through additional features such as indexing, strongly typed collections and
 serialization/compression, while maintaining as much of the native functionality
-as possible, like atomic operations and queue listeners.
+as possible, like watch, atomic operations and queue listeners.
 
-_Supported Deno verisons:_ **^1.37.2**
+_Supported Deno verisons:_ **^1.38.5**
 
 ## Highlights
 
@@ -37,7 +37,6 @@ _Supported Deno verisons:_ **^1.37.2**
     - [add()](#add)
     - [addMany()](#addmany)
     - [set()](#set)
-    - [write()](#write)
     - [update()](#update)
     - [updateByPrimaryIndex()](#updatebyprimaryindex)
     - [updateBySecondaryIndex()](#updatebysecondaryindex)
@@ -57,6 +56,8 @@ _Supported Deno verisons:_ **^1.37.2**
     - [countBySecondaryIndex()](#countbysecondaryindex)
     - [enqueue()](#enqueue)
     - [listenQueue()](#listenqueue)
+    - [watch()](#watch)
+    - [watchMany()](#watchmany)
   - [Serialized Collections](#serialized-collections)
   - [Database Methods](#database-methods)
     - [countAll()](#countall)
@@ -305,34 +306,20 @@ await result = await db.users.addMany([
 
 ### set()
 
-Add a new document to the KV store with a given id of type KvId. Upon
+Set a document entry in the KV store with a given id of type KvId. Upon
 completion, a CommitResult object will be returned with the document id,
-versionstamp and ok flag. If a document with a matching id already exists in the
-collection, the operation will fail.
+versionstamp and ok flag.
 
 ```ts
-const result = await db.numbers.set("id_1", 2048)
-
-if (result.ok) {
-  console.log(result.id) // id_1
-}
-```
-
-### write()
+// Add a new document if the id is not already in use
+const result1 = await db.numbers.set("id", 1024)
 
-Write a document to the KV store with a given id of type KvId. Sets a new
-document entry if no document already exists, overwrites an existing entry if it
-does. Upon completion, a CommitResult object will be returned with the document
-id, verisonstamp and ok flag. Contrary to update(), this method will only
-perform full overwrites, no partial updates. This method will not fail whether
-an existing id already exists or not.
+// Overwrite any existing document with the same id
+const result2 = await db.numbers.set("id", 2048, { overwrite: true })
 
-```ts
-const result1 = await db.numbers.write("id_1", 1024)
-const result2 = await db.numbers.write("id_1", 2048)
-const doc = await db.numbers.find("id_1")
-
-console.log(doc?.value) // 2048
+if (result1.ok) {
+  console.log(result.id) // id
+}
 ```
 
 ### update()
@@ -682,6 +669,40 @@ db.users.listenQueue(async (data) => {
 }, { topic: "posts" })
 ```
 
+### watch()
+
+Listen for live changes to a single document by id.
+
+```ts
+// Updates the document value every second
+setInterval(() => db.numbers.set("id", Math.random()), 1_000)
+
+// Listen for any updates to the document value
+db.numbers.watch("id", (doc) => {
+  // Document will be null if the latest update was a delete operation
+  console.log(doc?.value)
+})
+```
+
+### watchMany()
+
+Listen for live changes to an array of specified documents by id.
+
+```ts
+// Delayed setting of document values
+setTimeout(() => db.numbers.set("id1", 10), 1_000)
+setTimeout(() => db.numbers.set("id2", 20), 2_000)
+setTimeout(() => db.numbers.set("id3", 30), 3_000)
+
+// Listen for any updates to the document values
+db.numbers.watchMany(["id1", "id2", "id3"], (docs) => {
+  // Prints for each update to any of the documents
+  console.log(docs[0]?.value) // 10, 10, 10
+  console.log(docs[1]?.value) // null, 20, 20
+  console.log(docs[2]?.value) // null, null, 30
+})
+```
+
 ## Serialized Collections
 
 Serialized collections can store much larger sized data by serializaing,