Add browser utility functions

Author: jdesrosiers

README.md

@@ -77,6 +77,18 @@ value(name); // => Luke Skywalker
 
     Get the JSON compatible value the document represents. Any references will
     have been followed so you'll never receive a `Reference` type.
+* typeof(browser: Browser) => JRefType
+
+    Works the same as the `typeof` keyword. It will return one of the JSON types
+    (null, boolean, number, string, array, object) or "reference". If the value
+    is not one of these types, it will throw an error.
+* has(key: string, browser: Browser) => boolean
+
+    Returns whether or not a property is present in the object that the browser
+    represents.
+* length(browser: Browser) => number
+
+    Get the length of the array that the browser represents.
 * step(key: string | number, browser: Browser) => Promise\<Browser>
 
     Move the browser cursor by the given "key" value. This is analogous to

lib/browser/browser.js

@@ -47,6 +47,10 @@ const followReferences = (browser) => jrefTypeOf(value(browser)) === "reference"
 
 export const value = (browser) => browser._value;
 
+export const typeOf = (browser) => jrefTypeOf(browser._value);
+export const has = (key, browser) => key in browser._value;
+export const length = (browser) => browser._value.length;
+
 export const step = curry((key, browser) => {
   return followReferences({
     ...browser,

lib/browser/utility-functions.spec.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { MockAgent, setGlobalDispatcher } from "undici";
+import { get, has, length, typeOf } from "../index.js";
+
+import type { Browser } from "../index.js";
+
+
+describe("JSON Browser", () => {
+  const testDomain = "https://example.com";
+  let mockAgent: MockAgent;
+
+  beforeEach(() => {
+    mockAgent = new MockAgent();
+    mockAgent.disableNetConnect();
+    setGlobalDispatcher(mockAgent);
+  });
+
+  afterEach(async () => {
+    await mockAgent.close();
+  });
+
+  describe("object has property", () => {
+    let browser: Browser;
+
+    beforeEach(async () => {
+      const jref = `{
+        "foo": 42
+      }`;
+
+      mockAgent.get(testDomain)
+        .intercept({ method: "GET", path: "/foo" })
+        .reply(200, jref, { headers: { "content-type": "application/reference+json" } });
+
+      browser = await get(`${testDomain}/foo`);
+    });
+
+    test("true", () => {
+      expect(has("foo", browser)).to.eql(true);
+    });
+
+    test("false", () => {
+      expect(has("bar", browser)).to.eql(false);
+    });
+  });
+
+  test("length of array", async () => {
+    const jref = `[42]`;
+
+    mockAgent.get(testDomain)
+      .intercept({ method: "GET", path: "/foo" })
+      .reply(200, jref, { headers: { "content-type": "application/reference+json" } });
+
+    const uri = `${testDomain}/foo`;
+    const browser = await get(uri);
+
+    expect(length(browser)).to.eql(1);
+  });
+
+  describe("object has property", () => {
+    beforeEach(() => {
+      const jref = `{
+        "null": null,
+        "true": true,
+        "false": false,
+        "number": 42,
+        "string": "foo",
+        "array": [],
+        "object": {}
+      }`;
+
+      mockAgent.get(testDomain)
+        .intercept({ method: "GET", path: "/foo" })
+        .reply(200, jref, { headers: { "content-type": "application/reference+json" } });
+    });
+
+    test("null", async () => {
+      const browser = await get(`${testDomain}/foo#/null`);
+      expect(typeOf(browser)).to.eql("null");
+    });
+
+    test("true", async () => {
+      const browser = await get(`${testDomain}/foo#/true`);
+      expect(typeOf(browser)).to.eql("boolean");
+    });
+
+    test("false", async () => {
+      const browser = await get(`${testDomain}/foo#/false`);
+      expect(typeOf(browser)).to.eql("boolean");
+    });
+
+    test("number", async () => {
+      const browser = await get(`${testDomain}/foo#/number`);
+      expect(typeOf(browser)).to.eql("number");
+    });
+
+    test("string", async () => {
+      const browser = await get(`${testDomain}/foo#/string`);
+      expect(typeOf(browser)).to.eql("string");
+    });
+
+    test("array", async () => {
+      const browser = await get(`${testDomain}/foo#/array`);
+      expect(typeOf(browser)).to.eql("array");
+    });
+
+    test("object", async () => {
+      const browser = await get(`${testDomain}/foo#/object`);
+      expect(typeOf(browser)).to.eql("object");
+    });
+  });
+});

lib/index.browser.js

@@ -12,6 +12,9 @@ addUriSchemePlugin("https", httpSchemePlugin);
 export {
   get,
   value,
+  typeOf,
+  has,
+  length,
   step,
   iter,
   keys,

lib/index.d.ts

@@ -1,5 +1,5 @@
 import type { Response } from "undici";
-import type { JRef } from "./jref/index.js";
+import type { JRef, JRefType } from "./jref/index.js";
 
 
 // Browser
@@ -17,12 +17,15 @@ export type Document = {
 };
 
 export const get: <T extends Document>(uri: string, browser?: Browser) => Promise<Browser<T>>;
-export const value: (browser: Browser) => unknown;
-export const step: <T extends Document>(key: string, browser: Browser) => Promise<Browser<T>>;
-export const iter: <T extends Document>(browser: Browser) => AsyncGenerator<Browser<T>>;
+export const value: <T>(browser: Browser) => T;
+export const typeOf: (browser: Browser) => JRefType;
+export const has: (key: string, browser: Browser) => boolean;
+export const length: (browser: Browser) => number;
+export const step: (key: string, browser: Browser) => Promise<Browser>;
+export const iter: (browser: Browser) => AsyncGenerator<Browser>;
 export const keys: (browser: Browser) => Generator<string>;
-export const values: (browser: Browser) => AsyncGenerator<string>;
-export const entries: <T extends Document>(browser: Browser) => AsyncGenerator<[string, Browser<T>]>;
+export const values: (browser: Browser) => AsyncGenerator<Browser>;
+export const entries: (browser: Browser) => AsyncGenerator<[string, Browser]>;
 
 export class RetrievalError extends Error {
   public constructor(message: string, cause: Error);
@@ -36,7 +39,7 @@ export type MediaTypePlugin<T extends Document = Document> = {
   quality?: number;
 };
 
-export const addMediaTypePlugin: <T extends Document>(contentType: string, plugin: MediaTypePlugin<T>) => void;
+export const addMediaTypePlugin: (contentType: string, plugin: MediaTypePlugin) => void;
 export const removeMediaTypePlugin: (contentType: string) => void;
 export const setMediaTypeQuality: (contentType: string, quality: number) => void;
 

lib/index.js

@@ -14,6 +14,9 @@ addUriSchemePlugin("file", fileSchemePlugin);
 export {
   get,
   value,
+  typeOf,
+  has,
+  length,
   step,
   iter,
   keys,