Merge pull request #83 from oliver-oloughlin/patch/readme-update

updated README and documentation

Author: oliver-oloughlin

README.md

@@ -2,17 +2,17 @@
 
 `kvdex` is a high level abstraction layer for Deno KV with zero third-party
 dependencies. It's purpose is to enhance the experience of using Deno's KV store
-through additional features such as indexing, and strongly typed collections,
-and cron jobs, while maintaining as much of the native functionality as
-possible, like atomic operations and queue listeners.
+through additional features such as indexing, strongly typed collections, and
+cron jobs, while maintaining as much of the native functionality as possible,
+like atomic operations and queue listeners.
 
 ## Highlights
 
 - CRUD operations for selected and ranged documents with strong typing.
 - Primary (unique) and secondary (non-unique) indexing.
 - Segmented storage for large objects that exceed the native size limit.
 - Support for pagination and filtering.
-- Repeating cron jobs.
+- Create repeating cron jobs.
 - Message queues at database and collection level with topics.
 - Support for atomic operations.
 
@@ -575,7 +575,7 @@ if you believe your document values will exceed size limit.
 ## Database Methods
 
 These are methods which can be found at the top level of your database object,
-and perform operations across multiple collections.
+and perform operations across multiple collections or unrelated to collections.
 
 ### countAll()
 
@@ -626,7 +626,7 @@ can be used to set the topic.
 // Prints the data to console when recevied
 db.listenQueue((data) => console.log(data))
 
-// Sends post request when data is received
+// Sends post request when data is received in the "posts" topic
 db.listenQueue(async (data) => {
   const dataBody = JSON.stringify(data)
 
@@ -675,7 +675,7 @@ db.cron(() => Math.random(), {
 
 ### atomic()
 
-Initiate an atomic operation. The method takes a selection function as argument
+Initiate an atomic operation. The method takes a selector function as argument
 for selecting the initial collection context.
 
 ```ts

src/atomic_builder.ts

@@ -438,6 +438,34 @@ export class AtomicBuilder<
     return this
   }
 
+  /**
+   * Add data to the collection queue to be delivered to the queue listener
+   * via ``db.collection.listenQueue()``. The data will only be received by queue
+   * listeners on the specified collection and topic. The method takes an optional options
+   * argument that can be used to set a delivery delay and topic.
+   *
+   * @example
+   * ```ts
+   * // Immediate delivery
+   * await db
+   *   .atomic(schema => schema.users)
+   *   .enqueue("soem data")
+   *   .commit()
+   *
+   * // Delay of 2 seconds before delivery, sent to the "food" topic
+   * await db
+   *   .atomic(schema => schema.users)
+   *   .enqueue("cake", {
+   *     delay: 2_000,
+   *     topic: "food"
+   *   })
+   *   .commit()
+   * ```
+   *
+   * @param data - Data to be added to the collection queue.
+   * @param options - Enqueue options, optional.
+   * @returns - Promise resolving to Deno.KvCommitResult.
+   */
   enqueue(data: QueueValue, options?: EnqueueOptions) {
     // Prepare and add enqueue operation
     const prep = prepareEnqueue(

src/collection.ts

@@ -532,17 +532,18 @@ export class Collection<
   /**
    * Add data to the collection queue to be delivered to the queue listener
    * via ``db.collection.listenQueue()``. The data will only be received by queue
-   * listeners on the specified collection. The method takes an optional options
-   * argument that can be used to set a delivery delay.
+   * listeners on the specified collection and topic. The method takes an optional options
+   * argument that can be used to set a delivery delay and topic.
    *
    * @example
    * ```ts
    * // Immediate delivery
    * await db.users.enqueue("some data")
    *
-   * // Delay of 2 seconds before delivery
-   * await db.users.enqueue("some data", {
-   *   delay: 2_000
+   * // Delay of 2 seconds before delivery, sent to the "food" topic
+   * await db.users.enqueue("cake", {
+   *   delay: 2_000,
+   *   topic: "food"
    * })
    * ```
    *
@@ -572,7 +573,7 @@ export class Collection<
    * // Prints the data to console when recevied
    * db.users.listenQueue((data) => console.log(data))
    *
-   * // Sends post request when data is received
+   * // Sends post request when data is received in the "posts" topic
    * db.users.listenQueue(async (data) => {
    *   const dataBody = JSON.stringify(data)
    *
@@ -582,7 +583,7 @@ export class Collection<
    *   })
    *
    *   console.log("POSTED:", dataBody, res.ok)
-   * })
+   * }, { topic: "posts" })
    * ```
    *
    * @param handler - Message handler function.

src/kvdex.ts

@@ -63,16 +63,21 @@ export function kvdex<const T extends SchemaDefinition>(
   kv: Deno.Kv,
   schemaDefinition: T,
 ) {
+  // Set listener activated flag and queue handlers map
   let listenerIsActivated = false
   const queueHandlers = new Map<string, QueueMessageHandler<QueueValue>[]>()
 
+  // Create idempotent listener activator
   const idempotentListener = () => {
+    // If listener is already activated, cancel
     if (listenerIsActivated) {
       return
     }
 
+    // Set listener activated flag
     listenerIsActivated = true
 
+    // Add queue listener
     kv.listenQueue(async (msg) => {
       const parsed = parseQueueMessage(msg)
       if (!parsed.ok) {
@@ -86,15 +91,18 @@ export function kvdex<const T extends SchemaDefinition>(
     })
   }
 
+  // Create schema
   const schema = _createSchema(
     schemaDefinition,
     kv,
     queueHandlers,
     idempotentListener,
   ) as Schema<T>
 
+  // Create KvDex object
   const db = new KvDex(kv, schema, queueHandlers, idempotentListener)
 
+  // Return schema and db combination
   return Object.assign(db, schema)
 }
 
@@ -170,17 +178,18 @@ export class KvDex<const T extends Schema<SchemaDefinition>> {
   /**
    * Add data to the database queue to be delivered to the queue listener
    * via ``db.listenQueue()``. The data will only be received by queue
-   * listeners on the database queue. The method takes an optional options
-   * argument that can be used to set a delivery delay.
+   * listeners on the database queue and specified topic. The method takes an optional options
+   * argument that can be used to set a delivery delay and topic.
    *
    * @example
    * ```ts
    * // Immediate delivery
    * await db.enqueue("some data")
    *
    * // Delay of 2 seconds before delivery
-   * await db.enqueue("some data", {
-   *   delay: 2_000
+   * await db.enqueue("cake", {
+   *   delay: 2_000,
+   *  topic: "food"
    * })
    * ```
    *
@@ -206,7 +215,7 @@ export class KvDex<const T extends Schema<SchemaDefinition>> {
    * // Prints the data to console when recevied
    * db.listenQueue((data) => console.log(data))
    *
-   * // Sends post request when data is received
+   * // Sends post request when data is received in the "posts" topic
    * db.listenQueue(async (data) => {
    *   const dataBody = JSON.stringify(data)
    *
@@ -216,7 +225,7 @@ export class KvDex<const T extends Schema<SchemaDefinition>> {
    *   })
    *
    *   console.log("POSTED:", dataBody, res.ok)
-   * })
+   * }, { topic: "posts" })
    * ```
    *
    * @param handler - Message handler function.