Docs and 0.3.0 release

CHANGELOG.md

@@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0]
 
 ### Changed
 

deno.json

@@ -6,7 +6,7 @@
     "test": "deno test --allow-env --allow-read --allow-write --allow-net",
     "reload": "deno cache --reload **/*.ts jsr:@check/deps",
     "check": "deno check **/*.ts",
-    "lint": "deno lint",
+    "lint": "deno lint && deno doc --lint **/*.ts",
     "ok": "deno fmt && deno task lint && deno task check && deno task test && deno publish --dry-run --allow-dirty",
     "outdated": "deno run --allow-read=. --allow-net=jsr.io,registry.npmjs.org jsr:@check/deps",
     "lock": "rm -f deno.lock && deno task check"
@@ -26,12 +26,13 @@
   ],
   "imports": {
     "@cross/env": "jsr:@cross/env@^1.0.2",
-    "@jollytoad/store": "jsr:@jollytoad/store@^0.2.0",
-    "@jollytoad/store-common": "jsr:@jollytoad/store-common@^0.2.0",
-    "@jollytoad/store-deno-fs": "jsr:@jollytoad/store-deno-fs@^0.2.0",
-    "@jollytoad/store-deno-kv": "jsr:@jollytoad/store-deno-kv@^0.2.0",
-    "@jollytoad/store-deno-kv-fs": "jsr:@jollytoad/store-deno-kv-fs@^0.2.0",
-    "@jollytoad/store-web-storage": "jsr:@jollytoad/store-web-storage@^0.2.0",
+    "@jollytoad/store": "jsr:@jollytoad/store@^0.3.0",
+    "@jollytoad/store-common": "jsr:@jollytoad/store-common@^0.3.0",
+    "@jollytoad/store-deno-fs": "jsr:@jollytoad/store-deno-fs@^0.3.0",
+    "@jollytoad/store-deno-kv": "jsr:@jollytoad/store-deno-kv@^0.3.0",
+    "@jollytoad/store-deno-kv-fs": "jsr:@jollytoad/store-deno-kv-fs@^0.3.0",
+    "@jollytoad/store-web-storage": "jsr:@jollytoad/store-web-storage@^0.3.0",
+    "@jollytoad/store-no-op": "jsr:@jollytoad/store-no-op@^0.3.0",
     "@std/assert": "jsr:@std/assert@^1.0.0-rc.3",
     "@std/fs": "jsr:@std/fs@^1.0.0-rc.3",
     "@std/path": "jsr:@std/path@^1.0.0-rc.3"

store-common/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@jollytoad/store-common",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "exports": {
     "./key-utils": "./key-utils.ts",
     "./test-storage-module": "./test-storage-module.ts",

store-common/test-storage-module.ts

@@ -6,6 +6,9 @@ import {
 } from "@std/assert";
 import type { StorageModule } from "./types.ts";
 
+/**
+ * Test the url() function of the given storage module.
+ */
 export async function testUrl(
   t: Deno.TestContext,
   { url }: StorageModule,
@@ -18,6 +21,9 @@ export async function testUrl(
   });
 }
 
+/**
+ * Test the isWriteable() function of the given storage module.
+ */
 export async function testIsWriteable(
   t: Deno.TestContext,
   { isWritable }: StorageModule,
@@ -28,6 +34,9 @@ export async function testIsWriteable(
   });
 }
 
+/**
+ * Test the setItem() function of the given storage module.
+ */
 export async function testSetItem(
   t: Deno.TestContext,
   { setItem }: StorageModule,
@@ -45,6 +54,10 @@ export async function testSetItem(
   });
 }
 
+/**
+ * Test the hasItem() function of the given storage module,
+ * this must be called after `testSetItem`.
+ */
 export async function testHasItem(
   t: Deno.TestContext,
   { hasItem }: StorageModule,
@@ -62,6 +75,10 @@ export async function testHasItem(
   });
 }
 
+/**
+ * Test the getItem() function of the given storage module,
+ * this must be called after `testSetItem`.
+ */
 export async function testGetItem(
   t: Deno.TestContext,
   { getItem }: StorageModule,
@@ -79,6 +96,10 @@ export async function testGetItem(
   });
 }
 
+/**
+ * Test the listItems() function of the given storage module,
+ * this must be called after `testSetItem`.
+ */
 export async function testListItems(
   t: Deno.TestContext,
   { listItems }: StorageModule,
@@ -101,6 +122,10 @@ export async function testListItems(
   });
 }
 
+/**
+ * Test the removeItem() function of the given storage module,
+ * this must be called after `testSetItem`.
+ */
 export async function testRemoveItem(
   t: Deno.TestContext,
   { removeItem, listItems, setItem, hasItem }: StorageModule,
@@ -134,6 +159,9 @@ export async function testRemoveItem(
   });
 }
 
+/**
+ * Test the clearItems() function of the given storage module.
+ */
 export async function testClearItems(
   t: Deno.TestContext,
   { clearItems, setItem, hasItem, listItems }: StorageModule,
@@ -163,6 +191,11 @@ export async function testClearItems(
   });
 }
 
+/**
+ * Test the storage module list items ordered by key,
+ * and supports listing in reverse.
+ * This test is optional for a storage module.
+ */
 export async function testOrdering(
   t: Deno.TestContext,
   { setItem, listItems, removeItem }: StorageModule,
@@ -191,11 +224,13 @@ export async function testOrdering(
   });
 }
 
+/**
+ * Ensure that the underlying storage has been opened and is empty
+ */
 export async function open(
   _t: Deno.TestContext,
   { hasItem, clearItems }: StorageModule,
 ) {
-  // Just ensure that the underlying storage has been opened and is empty
   await hasItem(["store"]);
   await clearItems([]);
 }

store-common/types.ts

@@ -1,3 +1,11 @@
+/**
+ * A key for an item in a store.
+ *
+ * An array of string, number or boolean.
+ * This may be translated to a format compatible with the underlying storage mechanism,
+ * often a single string delimited by slashes `/`, and where numbers and booleans are
+ * converted directly to string format.
+ */
 export type StorageKey = readonly (string | number | boolean)[];
 
 /**
@@ -46,6 +54,7 @@ export interface StorageModule<T = unknown> {
 
   /**
    * Close all associated resources.
+   * This isn't generally required in most situations, it's main use is within test cases.
    */
   close(): Promise<void>;
 
@@ -60,7 +69,7 @@ export interface StorageModule<T = unknown> {
  */
 export interface DelegatedStore {
   /**
-   * Set the store to which to delegate all function calls
+   * Set the storage module to which all function calls are delegated
    *
    * @param storageModule may be the store, promise of the store, or undefined to remove any delegate store
    */

store-deno-fs/README.md

@@ -15,3 +15,18 @@ JSON file.
 eg: `["one", "two", "three"]` -> `.store/one/two/three.json`
 
 Import mapping: `"$store": "jsr:@jollytoad/store-deno-fs"`
+
+**Example**
+
+```ts
+import * as store from "jsr:@jollytoad/store-deno-fs";
+import { assertEquals } from "jsr:@std/assert";
+
+await store.setItem(["foo", "hello"], "world");
+
+assertEquals(await store.hasItem(["foo", "hello"]), true);
+assertEquals(await store.getItem(["foo", "hello"]), "world");
+
+await store.clearItems(["foo"]);
+assertEquals(await store.hasItem(["foo", "hello"]), false);
+```

store-deno-fs/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@jollytoad/store-deno-fs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "exports": {
     ".": "./mod.ts"
   }

store-deno-fs/mod.ts

@@ -22,10 +22,16 @@ export type { StorageKey, StorageModule };
   url,
 }) satisfies StorageModule;
 
+/**
+ * Returns the `import.meta.url` of the module.
+ */
 export function url(): Promise<string> {
   return Promise.resolve(import.meta.url);
 }
 
+/**
+ * Check for filesystem write permission at directory for the given key.
+ */
 export async function isWritable(key: StorageKey = []): Promise<boolean> {
   if (Deno.env.get("DENO_DEPLOYMENT_ID")) {
     return false;
@@ -36,10 +42,16 @@ export async function isWritable(key: StorageKey = []): Promise<boolean> {
   })).state === "granted";
 }
 
+/**
+ * Determine whether a value is set for the given key.
+ */
 export function hasItem(key: StorageKey): Promise<boolean> {
   return exists(filepath(key), { isFile: true });
 }
 
+/**
+ * Get a value for the given key.
+ */
 export async function getItem<T>(key: StorageKey): Promise<T | undefined> {
   try {
     return JSON.parse(await Deno.readTextFile(filepath(key)));
@@ -52,12 +64,18 @@ export async function getItem<T>(key: StorageKey): Promise<T | undefined> {
   }
 }
 
+/**
+ * Set a value for the given key.
+ */
 export async function setItem<T>(key: StorageKey, value: T): Promise<void> {
   const path = filepath(key);
   await ensureDir(dirname(path));
   await Deno.writeTextFile(path, JSON.stringify(value));
 }
 
+/**
+ * Remove the value with the given key.
+ */
 export async function removeItem(key: StorageKey): Promise<void> {
   let path = filepath(key);
   if (await exists(path, { isFile: true })) {
@@ -76,7 +94,10 @@ export async function removeItem(key: StorageKey): Promise<void> {
   }
 }
 
-// TODO: Support reverse ordering
+/**
+ * List all items beneath the given key prefix.
+ * At present ordering is not guaranteed and reverse support is optional.
+ */
 export async function* listItems<T>(
   keyPrefix: StorageKey = [],
   _reverse = false,
@@ -105,6 +126,9 @@ export async function* listItems<T>(
   }
 }
 
+/**
+ * Delete item and sub items recursively and clean up.
+ */
 export async function clearItems(keyPrefix: StorageKey): Promise<void> {
   await removeItem(keyPrefix);
   try {
@@ -118,6 +142,10 @@ export async function clearItems(keyPrefix: StorageKey): Promise<void> {
   }
 }
 
+/**
+ * Close all associated resources.
+ * This isn't generally required in most situations, it's main use is within test cases.
+ */
 export function close(): Promise<void> {
   return Promise.resolve();
 }

store-deno-fs/store.test.ts

@@ -33,7 +33,7 @@ Deno.test("store-deno-fs", async (t) => {
   }
 });
 
-export async function testDirectoryPurge(
+async function testDirectoryPurge(
   t: Deno.TestContext,
   { setItem, removeItem }: StorageModule,
 ) {

store-deno-kv-fs/README.md

@@ -12,3 +12,18 @@ unless the env var `STORE_PRIMARY` is set to `kv`, in which case the KV always
 overrides filesystem values.
 
 Import mapping: `"$store": "jsr:@jollytoad/store-deno-kv-fs"`
+
+**Example**
+
+```ts
+import * as store from "jsr:@jollytoad/store-deno-kv-fs";
+import { assertEquals } from "jsr:@std/assert";
+
+await store.setItem(["foo", "hello"], "world");
+
+assertEquals(await store.hasItem(["foo", "hello"]), true);
+assertEquals(await store.getItem(["foo", "hello"]), "world");
+
+await store.clearItems(["foo"]);
+assertEquals(await store.hasItem(["foo", "hello"]), false);
+```

store-deno-kv-fs/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@jollytoad/store-deno-kv-fs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "exports": {
     ".": "./mod.ts"
   }