From e3c642166206457ca2a7a438b4b4f9074e65d317 Mon Sep 17 00:00:00 2001
From: Mark Gibson <mgibson@adaptavist.com>
Date: Thu, 4 Jul 2024 17:28:42 +0100
Subject: [PATCH] improve docs

---
 store-common/README.md       | 50 ++++++++++++++++++++++++++++++++++
 store-deno-kv/README.md      | 53 ++++++++++++++++++++++++++++++++----
 store-deno-kv/get-deno-kv.ts |  9 ++++++
 3 files changed, 107 insertions(+), 5 deletions(-)

diff --git a/store-common/README.md b/store-common/README.md
index 586c24a..82450e7 100644
--- a/store-common/README.md
+++ b/store-common/README.md
@@ -8,3 +8,53 @@ utility function for use by implementations.
 - [the interface](./types.ts)
 - [key conversion utils](./key-utils.ts)
 - [test utils](./test-storage-module.ts)
+
+## StorageModule
+
+If you need to reference the interface for a storage module:
+
+```ts
+import type { StorageModule } from "jsr:@jollytoad/store-common/types";
+```
+
+## Test Utils
+
+If you want to implement your own storage modules the test utils can help you
+get started with some standard tests...
+
+**Example test case**
+
+```ts
+import {
+  open,
+  testClearItems,
+  testGetItem,
+  testHasItem,
+  testIsWriteable,
+  testListItems,
+  testOrdering,
+  testRemoveItem,
+  testSetItem,
+  testUrl,
+} from "@jollytoad/store-common/test-storage-module";
+
+// This is your custom storage module
+import * as store from "./mod.ts";
+
+Deno.test("store-my-custom-storage", async (t) => {
+  try {
+    await open(t, store);
+    await testUrl(t, store, "store-my-custom-storage");
+    await testIsWriteable(t, store);
+    await testSetItem(t, store);
+    await testHasItem(t, store);
+    await testGetItem(t, store);
+    await testListItems(t, store);
+    await testRemoveItem(t, store);
+    await testClearItems(t, store);
+    await testOrdering(t, store);
+  } finally {
+    await store.close();
+  }
+});
+```
diff --git a/store-deno-kv/README.md b/store-deno-kv/README.md
index c3ce708..d4c023e 100644
--- a/store-deno-kv/README.md
+++ b/store-deno-kv/README.md
@@ -8,11 +8,6 @@ Uses the [Deno KV](https://deno.land/manual/runtime/kv) API for storage.
 
 Import mapping: `"$store": "jsr:@jollytoad/store-deno-kv"`
 
-## Get out of jail free
-
-This package also supplies a utility function to obtained the actual `Deno.Kv`
-of any store backed by it (that exports a `getDenoKv` function).
-
 **Example**
 
 ```ts
@@ -27,3 +22,51 @@ assertEquals(await store.getItem(["foo", "hello"]), "world");
 await store.clearItems(["foo"]);
 assertEquals(await store.hasItem(["foo", "hello"]), false);
 ```
+
+## Get out of jail free
+
+This package also supplies a utility function to obtained the actual `Deno.Kv`
+of any store backed by it (that exports a `getDenoKv` function).
+
+**Examples**
+
+Using `getDenoKv()` with a store that uses `Deno.Kv`:
+
+```ts
+import * as store from "jsr:@jollytoad/store";
+import { getDenoKv } from "jsr:@jollytoad/store-deno-kv/get-deno-kv";
+import { assertEquals, assertInstanceOf } from "jsr:@std/assert";
+
+// Set store-deno-kv
+store.setStore(import("jsr:@jollytoad/store-deno-kv"));
+
+// Get the actual Deno.Kv store
+const kv = await getDenoKv(store, ["foo"]);
+
+assertInstanceOf(kv, Deno.Kv);
+
+await kv.atomic()
+  .set(["foo", "hello"], "world")
+  .commit();
+
+assertEquals(await store.hasItem(["foo", "hello"]), true);
+assertEquals(await store.getItem(["foo", "hello"]), "world");
+
+await store.clearItems(["foo"]);
+```
+
+Or with a store that doesn't use `Deno.Kv`:
+
+```ts
+import * as store from "jsr:@jollytoad/store";
+import { getDenoKv } from "jsr:@jollytoad/store-deno-kv/get-deno-kv";
+import { assertStrictEquals } from "jsr:@std/assert";
+
+// Set store-deno-kv
+store.setStore(import("jsr:@jollytoad/store-deno-fs"));
+
+// Attempt to get the actual Deno.Kv store
+const kv = await getDenoKv(store, ["foo"]);
+
+assertStrictEquals(kv, undefined);
+```
diff --git a/store-deno-kv/get-deno-kv.ts b/store-deno-kv/get-deno-kv.ts
index aaf8046..5b3b6b0 100644
--- a/store-deno-kv/get-deno-kv.ts
+++ b/store-deno-kv/get-deno-kv.ts
@@ -1,3 +1,9 @@
+/**
+ * This module provides the {@linkcode getDenoKv} function, to aid
+ * obtaining of `Deno.Kv` from any storage module if it's available.
+ *
+ * @module
+ */
 import type {
   DelegatedStore,
   StorageKey,
@@ -13,6 +19,9 @@ import type { ExposeDenoKv } from "./types.ts";
  * import { getDenoKv } from "jsr:@jollytoad/store-deno-kv/get-deno-kv";
  * import * as store from "jsr:@jollytoad/store";
  *
+ * // Set the delegate store, try changing this to "jsr:@jollytoad/store-deno-fs"
+ * store.setStore(import("jsr:@jollytoad/store-deno-kv"));
+ *
  * const kv = await getDenoKv(store, ["foo"]);
  *
  * const key = ["foo", "counter"];