refactored tests for improved structure and perfromance

Author: oliver-oloughlin

.github/workflows/test.yml

@@ -16,7 +16,7 @@ on:
 
 permissions:
   contents: read
-
+ 
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -37,4 +37,4 @@ jobs:
         run: deno lint
 
       - name: Run tests
-        run: deno task test
+        run: deno test -A --unstable

README.md

@@ -59,8 +59,8 @@ much of the native functionality as possible, such as atomic operations.
   - [Atomic Operations](#atomic-operations)
     - [Without checking](#without-checking)
     - [With checking](#with-checking)
-  - [Utils](#utils)
-    - [flatten()](#flatten)
+  - [Document Methods](#document-methods)
+    - [flat()](#flat)
   - [Development](#development)
   - [License](#license)
 
@@ -750,22 +750,20 @@ while (!result || !result.ok) {
 }
 ```
 
-## Utils
+## Document Methods
 
-Additional utility functions.
+Document functions.
 
-### flatten()
+### flat()
 
-Flatten documents with a value of type Model. Only flattens the first layer of
-the document, meaning the result will be an object containing: id, versionstamp
-and all the entries in the document value.
+Flatten top layer of document data. Returns an object containing the id,
+versionstamp and value entries for documents of type Model, else simply returns
+the document data.
 
 ```ts
-import { flatten } from "https://deno.land/x/kvdex/mod.ts"
-
 // We assume the document exists in the KV store
 const doc = await db.users.find(123n)
-const flattened = flatten(doc)
+const flattened = doc.flat()
 
 // Document:
 // {

deno.jsonc

@@ -7,6 +7,6 @@
     "semiColons": false
   },
   "test": {
-    "include": ["./test/tests"]
+    "include": ["./tests"]
   }
 }

mod.ts

@@ -1,6 +1,5 @@
-// Expose kvdex, collection builders and utils functions
-export { kvdex } from "./src/db.ts"
-export * from "./src/utils.ts"
+// Expose kvdex and collection builders
+export { kvdex } from "./src/kvdex.ts"
 export {
   collection,
   indexableCollection,
@@ -12,6 +11,10 @@ export { Collection } from "./src/collection.ts"
 export { IndexableCollection } from "./src/indexable_collection.ts"
 export { LargeCollection } from "./src/large_collection.ts"
 export { AtomicBuilder } from "./src/atomic_builder.ts"
+export { Document } from "./src/document.ts"
+
+// Expose errors
+export * from "./src/errors.ts"
 
 // Expose types
 export type * from "./src/types.ts"

src/atomic_builder.ts

@@ -25,7 +25,7 @@ import {
   keyEq,
   prepareEnqueue,
   setIndices,
-} from "./utils.internal.ts"
+} from "./utils.ts"
 
 /**
  * Builder object for creating and executing atomic operations in the KV store.
@@ -58,7 +58,9 @@ export class AtomicBuilder<
   ) {
     // Check for large collection
     if (collection instanceof LargeCollection) {
-      throw new InvalidAtomicBuilderCollectionError()
+      throw new InvalidAtomicBuilderCollectionError(
+        "Atomic operations are not supported for LargeCollection",
+      )
     }
 
     // Set kv and schema
@@ -281,6 +283,60 @@ export class AtomicBuilder<
     return this
   }
 
+  /**
+   * Sets the document value to the minimum of the existing and the given value.
+   *
+   * min only works for documents of type Deno.KvU64 and will throw an error for documents of any other type.
+   *
+   * @example
+   * ```ts
+   * db
+   *  .atomic(schema => schema.u64s) // Select collection of Deno.KvU64 values
+   *  .min("num1", 100n)
+   * ```
+   *
+   * @param id - Id of document that contains the value to be updated.
+   * @param value - The value to compare with the existing value.
+   * @returns Current AtomicBuilder instance.
+   */
+  min(id: KvId, value: T2 extends Deno.KvU64 ? bigint : never) {
+    // Create id key from id and collection id key
+    const idKey = extendKey(this.collection._keys.idKey, id)
+
+    // Add min operation to atomic ops list
+    this.operations.atomic.min(idKey, value)
+
+    // Return current AtomicBuilder
+    return this
+  }
+
+  /**
+   * Sets the document value to the maximum of the existing and the given value.
+   *
+   * max only works for documents of type Deno.KvU64 and will throw an error for documents of any other type.
+   *
+   * @example
+   * ```ts
+   * db
+   *  .atomic(schema => schema.u64s) // Select collection of Deno.KvU64 values
+   *  .max("num1", 100n)
+   * ```
+   *
+   * @param id - Id of document that contains the value to be updated.
+   * @param value - The value to compare with the existing value.
+   * @returns Current AtomicBuilder instance.
+   */
+  max(id: KvId, value: T2 extends Deno.KvU64 ? bigint : never) {
+    // Create id key from id and collection id key
+    const idKey = extendKey(this.collection._keys.idKey, id)
+
+    // Add max operation to atomic ops list
+    this.operations.atomic.max(idKey, value)
+
+    // Return current AtomicBuilder
+    return this
+  }
+
   /**
    * Specifies atomic mutations to be formed on documents.
    *

src/collection.ts

@@ -1,14 +1,13 @@
 import {
-  COLLECTION_ID_KEY_SUFFIX,
+  ID_KEY_PREFIX,
   KVDEX_KEY_PREFIX,
-  UNDELIVERED_KEY_SUFFIX,
+  UNDELIVERED_KEY_PREFIX,
 } from "./constants.ts"
 import type {
   CollectionKeys,
   CollectionOptions,
   CommitResult,
   CountOptions,
-  Document,
   EnqueueOptions,
   FindManyOptions,
   FindOptions,
@@ -34,7 +33,8 @@ import {
   kvGetMany,
   parseQueueMessage,
   prepareEnqueue,
-} from "./utils.internal.ts"
+} from "./utils.ts"
+import { Document } from "./document.ts"
 
 /**
  * Represents a collection of documents stored in the KV store.
@@ -74,7 +74,7 @@ export class Collection<
       idKey: extendKey(
         [KVDEX_KEY_PREFIX],
         ...key,
-        COLLECTION_ID_KEY_SUFFIX,
+        ID_KEY_PREFIX,
       ),
     }
   }
@@ -105,15 +105,12 @@ export class Collection<
       return null
     }
 
-    // Create the document
-    const doc: Document<T1> = {
+    // Return document
+    return new Document<T1>({
       id,
       versionstamp: result.versionstamp,
       value: result.value,
-    }
-
-    // Return the document
-    return doc
+    })
   }
 
   /**
@@ -153,11 +150,13 @@ export class Collection<
       }
 
       // Add document to result list
-      result.push({
-        id,
-        versionstamp,
-        value,
-      })
+      result.push(
+        new Document<T1>({
+          id,
+          versionstamp,
+          value,
+        }),
+      )
     }
 
     // Return result list
@@ -210,6 +209,8 @@ export class Collection<
    *
    * Sets a new document entry if no matching id already exists, overwrites the exisiting entry if it exists.
    *
+   * Does not overwrite existing entries if there is a primary index collision.
+   *
    * @example
    * ```ts
    * const result = await db.users.write("anders", {
@@ -613,23 +614,20 @@ export class Collection<
     options?: FindOptions,
   ) {
     // Create document key, get document entry
-    const key = extendKey(this._keys.idKey, UNDELIVERED_KEY_SUFFIX, id)
+    const key = extendKey(this._keys.baseKey, UNDELIVERED_KEY_PREFIX, id)
     const result = await this.kv.get<T>(key, options)
 
     // If no entry exists, return null
     if (result.value === null || result.versionstamp === null) {
       return null
     }
 
-    // Create the document
-    const doc: Document<T> = {
+    // Return document
+    return new Document<T>({
       id,
       versionstamp: result.versionstamp,
       value: result.value,
-    }
-
-    // Return the document
-    return doc
+    })
   }
 
   /** PROTECTED METHODS */
@@ -659,11 +657,11 @@ export class Collection<
       }
 
       // Create document
-      const doc: Document<T1> = {
+      const doc = new Document<T1>({
         id,
         versionstamp,
         value: value,
-      }
+      })
 
       // Filter document and add to documents list
       if (!options?.filter || options.filter(doc)) {

src/constants.ts

@@ -1,17 +1,17 @@
-// Key constants
+// Key prefixes
 export const KVDEX_KEY_PREFIX = "__kvdex__"
 
-export const COLLECTION_ID_KEY_SUFFIX = "__id__"
+export const ID_KEY_PREFIX = "__id__"
 
-export const COLLECTION_PRIMARY_INDEX_KEY_SUFFIX = "__index_primary__"
+export const PRIMARY_INDEX_KEY_PREFIX = "__index_primary__"
 
-export const COLLECTION_SECONDARY_INDEX_KEY_SUFFIX = "__index_secondary__"
+export const SECONDARY_INDEX_KEY_PREFIX = "__index_secondary__"
 
-export const COLLECTION_SEGMENT_KEY_SUFFIX = "__segment__"
+export const SEGMENT_KEY_PREFIX = "__segment__"
 
-export const UNDELIVERED_KEY_SUFFIX = "__undelivered__"
+export const UNDELIVERED_KEY_PREFIX = "__undelivered__"
 
-// Limit constants
+// Fixed limits
 export const ATOMIC_OPERATION_MUTATION_LIMIT = 20
 
 export const GET_MANY_KEY_LIMIT = 10

src/document.ts

@@ -0,0 +1,70 @@
+import type {
+  DocumentData,
+  FlatDocumentData,
+  KvId,
+  KvObject,
+  KvValue,
+  KvVersionstamp,
+} from "./types.ts"
+import { isKvObject } from "./utils.ts"
+
+export class Document<T extends KvValue> {
+  readonly id: KvId
+  readonly versionstamp: KvVersionstamp<T>
+  readonly value: T
+
+  constructor({
+    id,
+    versionstamp,
+    value,
+  }: DocumentData<T>) {
+    this.id = id
+    this.versionstamp = versionstamp
+    this.value = value
+  }
+
+  /**
+   * Flatten top layer of document data. Returns an object containing the id,
+   * versionstamp and value entries for documents of type Model, else simply returns
+   * the document data.
+   *
+   * @example
+   * ```ts
+   * // We assume the document exists in the KV store
+   * const doc = await db.users.find(123n)
+   * const flattened = doc.flat()
+   *
+   * // Document:
+   * // {
+   * //   id,
+   * //   versionstamp,
+   * //   value
+   * // }
+   *
+   * // Flattened:
+   * // {
+   * //   id,
+   * //   versionstamp,
+   * //   ...value
+   * // }
+   * ```
+   *
+   * @returns Object containing the id, versionstamp and value entries
+   * for documents of type Model, else simply returns the document data.
+   */
+  flat(): FlatDocumentData<T> {
+    if (isKvObject(this.value)) {
+      return {
+        id: this.id,
+        versionstamp: this.versionstamp,
+        ...this.value as KvObject,
+      } as unknown as FlatDocumentData<T>
+    }
+
+    return {
+      id: this.id,
+      versionstamp: this.versionstamp,
+      value: this.value,
+    } as unknown as FlatDocumentData<T>
+  }
+}

src/errors.ts

@@ -1,5 +1,11 @@
 export class InvalidAtomicBuilderCollectionError extends Error {
-  constructor(options?: ErrorOptions) {
-    super("Atomic operations are not supported for large collections", options)
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options)
+  }
+}
+
+export class CorruptedDocumentDataError extends Error {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options)
   }
 }