Merge pull request #188 from oliver-oloughlin/add-module-docs

Add module docs

README.md

@@ -91,8 +91,8 @@ _Supported Deno verisons:_ **^1.40.0**
     - [flat()](#flat)
   - [Extensions](#extensions)
     - [Zod](#zod)
-      - [zodModel()](#zodmodel)
-      - [Kv-Schemas](#kv-schemas)
+      - [`zodModel()`](#zodmodel)
+      - [Schemas](#schemas)
     - [Migrate](#migrate)
       - [Script](#script)
       - [Function](#function)
@@ -1241,7 +1241,7 @@ some dependenices to enhance integration. All extensions are found in the
 
 ### Zod
 
-#### zodModel()
+#### `zodModel()`
 
 Provides additional compatibility when using zod schemas as models. While zod
 schemas can be used as models directly, `zodModel()` properly parses a model
@@ -1275,10 +1275,10 @@ const result = await db.users_zod.add({
 })
 ```
 
-#### Kv-Schemas
+#### Schemas
 
 The zod extension provides schemas for some of the Kv-types, such as KvId,
-KvValue, KvObject and Kvarray. This makes it easier to properly build your
+KvValue, KvObject and KvArray. This makes it easier to properly build your
 schemas.
 
 ```ts

deno.json

@@ -12,7 +12,6 @@
     "bench": "deno bench --unstable-kv",
     "prep": "deno task check && deno fmt && deno lint && deno publish --dry-run && deno task test"
   },
-  "lock": false,
   "fmt": {
     "semiColons": false
   },

ext/migrate.ts

@@ -1,4 +1,38 @@
-import { parseArgs } from "jsr:@std/[email protected]/parse_args"
+/**
+ * @module # Migrate
+ *
+ * A utility script and function for migrating entries from a source KV instance to
+ * a target KV instance. Only migrates `kvdex` entries by default, but optionally
+ * allows for migrating all entries.
+ *
+ * ## Script
+ *
+ * Run the migrate script and provide --source and --target arguments. Optionally
+ * pass --all to migrate all entries.
+ *
+ * ```console
+ * deno run -A --unstable-kv jsr:@olli/kvdex/ext/migrate --source=./source.sqlite3 --target=./target.sqlite3
+ * ```
+ *
+ * ## Function
+ *
+ * Use the migrate function and pass a source KV instance and a target KV instance.
+ * Optionally pass `all: true` to migrate all entries.
+ *
+ * ```ts
+ * import { migrate } from "jsr:@olli/kvdex/ext/migrate"
+ *
+ * const source = await Deno.openKv("./source.sqlite3")
+ * const target = await Deno.openKv("./target.sqlite3")
+ *
+ * await migrate({
+ *   source,
+ *   target
+ * })
+ * ```
+ */
+
+import { parseArgs } from "jsr:@std/cli@^0.217/parse_args"
 import { KVDEX_KEY_PREFIX } from "../src/constants.ts"
 
 if (import.meta.main) {

ext/zod.ts

@@ -1,4 +1,65 @@
-import { z } from "npm:zod@3"
+/**
+ * @module # Zod
+ *
+ * Extended support for Zod. Includes a model parser and schemas for some KV-types.
+ *
+ * ## `zodModel()`
+ *
+ * Provides additional compatibility when using zod schemas as models. While zod
+ * schemas can be used as models directly, `zodModel()` properly parses a model
+ * from a zod schema, recognizing default fields as optional.
+ *
+ * ```ts
+ * import { z } from "npm:zod"
+ * import { zodModel } from "jsr:@olli/kvdex/ext/zod"
+ * import { collection, kvdex } from "jsr:@olli/kvdex"
+ *
+ * const UserSchema = z.object({
+ *   username: z.string(),
+ *   gender: z.string().default("not given"),
+ * })
+ *
+ * const kv = await Deno.openKv()
+ *
+ * const db = kvdex(kv, {
+ *   users_basic: collection(UserSchema),
+ *   users_zod: collection(zodModel(UserSchema)),
+ * })
+ *
+ * // Produces a type error for missing "gender" field.
+ * const result = await db.users_basic.add({
+ *   username: "oliver",
+ * })
+ *
+ * // No type error for missing "gender" field.
+ * const result = await db.users_zod.add({
+ *   username: "oliver",
+ * })
+ * ```
+ *
+ * ## Schemas
+ *
+ * The zod extension provides schemas for some of the Kv-types, such as KvId,
+ * KvValue, KvObject and KvArray. This makes it easier to properly build your
+ * schemas.
+ *
+ * ```ts
+ * import { z } from "npm:zod"
+ * import { KvIdSchema } from "jsr:@olli/kvdex/ext/zod"
+ *
+ * const UserSchema = z.object({
+ *   username: z.string(),
+ *   postIds: z.array(KvIdSchema),
+ * })
+ *
+ * const PostSchema = z.object({
+ *   text: z.string(),
+ *   userId: KvIdSchema,
+ * })
+ * ```
+ */
+
+import { z } from "npm:zod@^3.22"
 import type { KvArray, KvId, KvObject, KvValue, Model } from "../src/types.ts"
 
 /*******************/

src/collection.ts

@@ -1,5 +1,4 @@
 import type {
-  AtomicListOptions,
   BuilderFn,
   CheckKeyOf,
   CollectionKeys,
@@ -8,7 +7,7 @@ import type {
   EnqueueOptions,
   FindManyOptions,
   FindOptions,
-  HandleManyOptions,
+  HandleOneOptions,
   HistoryEntry,
   IdempotentListener,
   IdGenerator,
@@ -36,6 +35,7 @@ import type {
   SetOptions,
   UpdateData,
   UpdateManyOptions,
+  UpdateOneOptions,
   UpdateOptions,
   UpdateStrategy,
   UpsertOptions,
@@ -568,39 +568,6 @@ export class Collection<
     return await this.setDocument(id, data, options)
   }
 
-  /**
-   * Write a document to the KV store.
-   *
-   * 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.
-   *
-   * @deprecated
-   * This method is deprecated and will be removed in a future release.
-   *
-   * Please use `set()` with the option `overwrite: true` instead.
-   *
-   * @example
-   * ```ts
-   * const result = await db.users.write("anders", {
-   *   username: "andy",
-   *   age: 24
-   * })
-   * ```
-   *
-   * @param id - Document id.
-   * @param value - Document value.
-   * @param options - Set options, optional.
-   * @returns Promise resolving to a CommitResult or CommitError.
-   */
-  async write(
-    id: KvId,
-    value: ParseInputType<TInput, TOutput>,
-    options?: SetOptions,
-  ): Promise<CommitResult<TOutput> | Deno.KvCommitError> {
-    return await this.setDocument(id, value, { ...options, overwrite: true })
-  }
-
   /**
    * Deletes one or more documents with the given ids from the KV store.
    *
@@ -1041,7 +1008,7 @@ export class Collection<
    * @returns Promise resolving to either a commit result or commit error object.
    */
   async updateOne<
-    const T extends UpdateManyOptions<Document<TOutput>>,
+    const T extends UpdateOneOptions<Document<TOutput>>,
   >(
     data: UpdateData<TOutput, T["strategy"]>,
     options?: T,
@@ -1084,7 +1051,7 @@ export class Collection<
    * @returns Promise resolving to either a commit result or commit error object.
    */
   async updateOneBySecondaryIndex<
-    const T extends UpdateManyOptions<Document<TOutput>>,
+    const T extends UpdateOneOptions<Document<TOutput>>,
     const K extends SecondaryIndexKeys<TOutput, TOptions>,
   >(
     index: K,
@@ -1193,7 +1160,7 @@ export class Collection<
    * @returns A promise that resovles to an object containing the iterator cursor
    */
   async deleteMany(
-    options?: AtomicListOptions<Document<TOutput>>,
+    options?: ListOptions<Document<TOutput>>,
   ): Promise<Pagination> {
     // Perform quick delete if all documents are to be deleted
     if (selectsAll(options)) {
@@ -1297,7 +1264,7 @@ export class Collection<
    * @returns A promise that resovles to the retreived document
    */
   async getOne(
-    options?: ListOptions<Document<TOutput>>,
+    options?: HandleOneOptions<Document<TOutput>>,
   ): Promise<Document<TOutput> | null> {
     // Get result list with limit of one item
     const { result } = await this.handleMany(
@@ -1339,7 +1306,7 @@ export class Collection<
   >(
     index: K,
     value: CheckKeyOf<K, TOutput>,
-    options?: ListOptions<Document<TOutput>>,
+    options?: HandleOneOptions<Document<TOutput>>,
   ): Promise<Document<TOutput> | null> {
     // Create prefix key
     const prefixKey = createSecondaryIndexKeyPrefix(
@@ -2219,7 +2186,7 @@ export class Collection<
   private async handleMany<const T>(
     prefixKey: KvKey,
     fn: (doc: Document<TOutput>) => T,
-    options: HandleManyOptions<Document<TOutput>> | undefined,
+    options: ListOptions<Document<TOutput>> | undefined,
   ) {
     // Create list iterator with given options
     const selector = createListSelector(prefixKey, options)

src/deps.ts

@@ -1,7 +1,7 @@
 export { brotliCompressSync, brotliDecompressSync, constants } from "node:zlib"
-export { ulid } from "jsr:@std/[email protected]"
-export { concat } from "jsr:@std/[email protected]/concat"
+export { ulid } from "jsr:@std/ulid@^0.217"
+export { concat } from "jsr:@std/bytes@^0.217/concat"
 export {
   deepMerge,
   type DeepMergeOptions,
-} from "jsr:@std/[email protected]/deep_merge"
+} from "jsr:@std/collections@^0.217/deep_merge"