docs: type check inline documentation

kitsonk · Nov 30, 2024 · deee889 · deee889
1 parent aab2420
commit deee889
Show file tree

Hide file tree

Showing 6 changed files with 65 additions and 52 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -17,11 +17,8 @@ jobs:
         with:
           deno-version: ${{ matrix.version }}
 
-      - name: check format
-        run: deno fmt --check
-
-      - name: check linting
-        run: deno lint
+      - name: run checks
+        run: deno task check
 
       - name: run tests
         run: deno task test:ci

diff --git a/blob.ts b/blob.ts
@@ -31,7 +31,7 @@
  * @example Basic usage
  *
  * ```ts
- * import { get, remove, set } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { get, remove, set } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const data = new TextEncoder().encode("hello deno!");
@@ -45,7 +45,7 @@
  * @example Setting and getting `File`s
  *
  * ```ts
- * import { getAsBlob, remove, set } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { getAsBlob, remove, set } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * // assume this is form data submitted as a `Request`
@@ -230,7 +230,7 @@ function toParts(blob: ArrayBufferLike): string[] {
  * @example
  *
  * ```ts
- * import { remove } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { remove } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * await remove(kv, ["hello"]);
@@ -261,11 +261,13 @@ export function remove(kv: Deno.Kv, key: Deno.KvKey): Promise<void> {
  * @example
  *
  * ```ts
- * import { get } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { get } from "@kitsonk/kv-toolbox/blob";
+ * import { assert } from "@std/assert";
  *
  * const kv = await Deno.openKv();
- * const stream = await get(kv, ["hello"], { stream: true });
- * for await (const chunk of stream) {
+ * const maybeEntry = await get(kv, ["hello"], { stream: true });
+ * assert(maybeEntry.value);
+ * for await (const chunk of maybeEntry.value) {
  *   // do something with chunk
  * }
  * await kv.close();
@@ -294,7 +296,7 @@ export function get(
  * @example
  *
  * ```ts
- * import { get } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { get } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const blob = await get(kv, ["hello"], { blob: true });
@@ -325,7 +327,7 @@ export function get(
  * @example
  *
  * ```ts
- * import { get } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { get } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const ab = await get(kv, ["hello"]);
@@ -381,7 +383,7 @@ export async function get(
  * @example Getting a value
  *
  * ```ts
- * import { getAsBlob } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { getAsBlob } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const blob = await getAsBlob(kv, ["hello"]);
@@ -407,7 +409,7 @@ export async function getAsBlob(
  * @example Getting a value
  *
  * ```ts
- * import { getAsJSON } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { getAsJSON } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const json = JSON.stringify(await getAsJSON(kv, ["hello"]));
@@ -429,7 +431,7 @@ export function getAsJSON(
  * @example Getting meta data
  *
  * ```ts
- * import { getMeta } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { getMeta } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const maybeMeta = await getMeta(kv, ["hello"]));
@@ -551,7 +553,7 @@ export async function getAsResponse(
  * @example Getting a value
  *
  * ```ts
- * import { getAsStream } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { getAsStream } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const stream = await getAsStream(kv, ["hello"]);
@@ -584,7 +586,7 @@ export function getAsStream(
  * @example Setting a `Uint8Array`
  *
  * ```ts
- * import { set } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { set } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const blob = new TextEncoder().encode("hello deno!");
@@ -595,7 +597,7 @@ export function getAsStream(
  * @example Setting a `Blob`
  *
  * ```ts
- * import { set } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { set } from "@kitsonk/kv-toolbox/blob";
  *
  * const kv = await Deno.openKv();
  * const blob = new Blob(
@@ -636,12 +638,14 @@ export async function set(
  * @example Storing and retrieving a blob string
  *
  * ```ts
- * import { getAsBlob, set, toBlob } from "jsr:@kitsonk/kv-toolbox/blob";
+ * import { getAsBlob, set, toBlob } from "@kitsonk/kv-toolbox/blob";
+ * import { assert } from "@std/assert";
  *
  * const kv = await Deno.openKv();
  * const blob = toBlob("some big string");
  * await set(kv, ["hello"], blob);
  * const value = await getAsBlob(kv, ["hello"]);
+ * assert(value);
  * const str = await value.text();
  * await kv.close();
  * ```
@@ -726,7 +730,7 @@ export async function toJSON(
  *
  * const file = toValue({
  *   meta: {
- *     type: "file",
+ *     kind: "file",
  *     lastModified: 1711349710546,
  *     name: "test.bin",
  *     type: "application/octet-stream",
@@ -746,7 +750,7 @@ export function toValue(json: BlobFileJSON): File;
  *
  * const blob = toValue({
  *   meta: {
- *     type: "blob",
+ *     kind: "blob",
  *     type: "application/octet-stream",
  *   },
  *   parts: ["AQID"],
@@ -763,7 +767,10 @@ export function toValue(json: BlobBlobJSON): Blob;
  * ```ts
  * import { toValue } from "jsr:/@kitsonk/kv-toolbox/blob";
  *
- * const u8 = toValue({ parts: ["AQID"] });
+ * const u8 = toValue({
+ *   meta: { kind: "buffer" },
+ *   parts: ["AQID"],
+ * });
  * ```
  */
 export function toValue(json: BlobBufferJSON): Uint8Array;
@@ -776,7 +783,10 @@ export function toValue(json: BlobBufferJSON): Uint8Array;
  * ```ts
  * import { toValue } from "jsr:/@kitsonk/kv-toolbox/blob";
  *
- * const u8 = toValue({ parts: ["AQID"] });
+ * const u8 = toValue({
+ *   meta: { kind: "buffer" },
+ *   parts: ["AQID"],
+ * });
  * ```
  */
 export function toValue(json: BlobJSON): Uint8Array | Blob | File;

diff --git a/crypto.ts b/crypto.ts
@@ -403,7 +403,7 @@ export class CryptoKv {
    * import { generateKey, openCryptoKv } from "jsr:@kitsonk/kv-toolbox/crypto";
    *
    * const kv = await openCryptoKv(generateKey());
-   * const value = await kv.getAsJson(["hello"]);
+   * const value = await kv.getAsJSON(["hello"]);
    * if (value) {
    *  // do something with value
    * }

diff --git a/deno.json b/deno.json
@@ -20,13 +20,15 @@
   },
   "tasks": {
     "bench": "deno bench --allow-read --allow-write --unstable-kv",
+    "check": "deno fmt --check && deno lint && deno check --doc *.ts",
     "coverage": "deno coverage --lcov --output=cov.lcov ./cov",
     "test": "deno test --allow-read --allow-write --unstable-kv --parallel",
     "test:ci": "deno test --allow-read --allow-write --unstable-kv --coverage=./cov --parallel"
   },
   "lock": false,
   "imports": {
     "@deno/kv-utils": "jsr:@deno/kv-utils@^0.1.2",
+    "@std/assert": "jsr:@std/assert@~1",
     "@std/bytes": "jsr:@std/bytes@~1"
   }
 }
diff --git a/keys.ts b/keys.ts
@@ -10,7 +10,7 @@
  * **Example**
  *
  * ```ts
- * import { equals } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { equals } from "@kitsonk/kv-toolbox/keys";
  *
  * const keyA = ["a", "b"];
  * const keyB = ["a", "b"];
@@ -33,7 +33,7 @@
  * **Example**
  *
  * ```ts
- * import { partEquals } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { partEquals } from "@kitsonk/kv-toolbox/keys";
  *
  * const keyA = ["a", "b"];
  * const keyB = ["a", "b"];
@@ -50,7 +50,7 @@
  * **Example**
  *
  * ```ts
- * import { startsWith } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { startsWith } from "@kitsonk/kv-toolbox/keys";
  *
  * const key = ["a", "b"];
  * const prefix = ["a"];
@@ -68,7 +68,7 @@
  *
  * If you had the following keys stored in a datastore:
  *
- * ```ts
+ * ```
  * ["a", "b"]
  * ["a", "b", "c"]
  * ["a", "d", "e"]
@@ -78,7 +78,7 @@
  * And you would get the following results when using `tree()`:
  *
  * ```ts
- * import { unique } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { unique } from "@kitsonk/kv-toolbox/keys";
  *
  * const kv = await Deno.openKv();
  * console.log(await tree(kv, ["a"]));
@@ -112,7 +112,7 @@
  *
  * If you had the following keys stored in a datastore:
  *
- * ```ts
+ * ```
  * ["a", "b"]
  * ["a", "b", "c"]
  * ["a", "d", "e"]
@@ -122,7 +122,7 @@
  * And you would get the following results when using `unique()`:
  *
  * ```ts
- * import { unique } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { unique } from "@kitsonk/kv-toolbox/keys";
  *
  * const kv = await Deno.openKv();
  * console.log(await unique(kv, ["a"]));
@@ -190,7 +190,7 @@ function addOrIncrement(
  * @example
  *
  * ```ts
- * import { partEquals } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { partEquals } from "@kitsonk/kv-toolbox/keys";
  *
  * const keyA = ["a", "b"];
  * const keyB = ["a", "b"];
@@ -220,7 +220,7 @@ export function partEquals(a: Deno.KvKeyPart, b: Deno.KvKeyPart): boolean {
  * @example
  *
  * ```ts
- * import { equals } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { equals } from "@kitsonk/kv-toolbox/keys";
  *
  * const keyA = ["a", "b"];
  * const keyB = ["a", "b"];
@@ -248,7 +248,7 @@ export function equals(a: Deno.KvKey, b: Deno.KvKey): boolean {
  * @example
  *
  * ```ts
- * import { startsWith } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { startsWith } from "@kitsonk/kv-toolbox/keys";
  *
  * const key = ["a", "b"];
  * const prefix = ["a"];
@@ -270,7 +270,7 @@ export function startsWith(key: Deno.KvKey, prefix: Deno.KvKey): boolean {
  * @example
  *
  * ```ts
- * import { keys } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { keys } from "@kitsonk/kv-toolbox/keys";
  *
  * const kv = await Deno.openKv();
  * console.log(await keys(kv, { prefix: ["hello"] }));
@@ -300,7 +300,7 @@ export async function keys(
  *
  * The following keys stored in a datastore:
  *
- * ```ts
+ * ```
  * ["a", "b"]
  * ["a", "b", "c"]
  * ["a", "d", "e"]
@@ -310,7 +310,7 @@ export async function keys(
  * The following results when using `unique()`:
  *
  * ```ts
- * import { unique } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { unique } from "@kitsonk/kv-toolbox/keys";
  *
  * const kv = await Deno.openKv();
  * console.log(await unique(kv, ["a"]));
@@ -372,7 +372,7 @@ export interface UniqueCountElement {
  *
  * If you had the following keys stored in a datastore:
  *
- * ```ts
+ * ```
  * ["a", "b"]
  * ["a", "b", "c"]
  * ["a", "d", "e"]
@@ -382,7 +382,7 @@ export interface UniqueCountElement {
  * And you would get the following results when using `uniqueCount()`:
  *
  * ```ts
- * import { uniqueCount } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { uniqueCount } from "@kitsonk/kv-toolbox/keys";
  *
  * const kv = await Deno.openKv();
  * console.log(await uniqueCount(kv, ["a"]));
@@ -467,7 +467,7 @@ export interface KeyTree {
  *
  * If you had the following keys stored in a datastore:
  *
- * ```ts
+ * ```
  * ["a", "b"]
  * ["a", "b", "c"]
  * ["a", "d", "e"]
@@ -477,7 +477,7 @@ export interface KeyTree {
  * And you would get the following results when using `tree()`:
  *
  * ```ts
- * import { unique } from "jsr:@kitsonk/kv-toolbox/keys";
+ * import { unique } from "@kitsonk/kv-toolbox/keys";
  *
  * const kv = await Deno.openKv();
  * console.log(await tree(kv, ["a"]));