Refactor type model in an attempt to make extension easier

Author: jdesrosiers

src/hyperjump/embedded.test.js

@@ -2,12 +2,11 @@ import { describe, test, beforeEach, afterEach, expect, beforeAll, afterAll } fr
 import { MockAgent, setGlobalDispatcher } from "undici";
 import { toAbsoluteIri } from "@hyperjump/uri";
 import { Hyperjump } from "./index.js";
-import { fromJref, toJref } from "../jref/index.js";
+import { fromJref } from "../jref/index.js";
+import { toJson } from "../json/jsonast-util.js";
 
 /**
  * @import { DocumentNode } from "./index.js"
- * @import { JrefNode } from "../jref/index.js"
- * @import { Reviver } from "../jref/index.js"
  */
 
 
@@ -20,23 +19,22 @@ describe("JSON Browser", () => {
     beforeAll(() => {
       /** @type (uri: string, text: string, embedded?: Record<string, DocumentNode>) => DocumentNode */
       const parseToDocument = (uri, text, embedded = {}) => {
-        /** @type Reviver<JrefNode | undefined> */
-        const embeddedReviver = (node, key) => {
-          if (key === "$embedded" && node.type === "json" && node.jsonType === "object") {
+        const rootNode = fromJref(text, uri, (node, key) => {
+          if (key === "$embedded" && node.jsonType === "object") {
             for (const propertyNode of node.children) {
               const embeddedUri = toAbsoluteIri(propertyNode.children[0].value);
-              const embeddedJref = toJref(propertyNode.children[1], uri);
+              const embeddedJref = toJson(propertyNode.children[1]);
               embedded[embeddedUri] = parseToDocument(embeddedUri, embeddedJref, embedded);
             }
             return;
           } else {
             return node;
           }
-        };
+        });
 
         return {
           type: "embedded-document",
-          children: [fromJref(text, uri, embeddedReviver)],
+          children: [rootNode],
           uri: uri,
           fragmentKind: "json-pointer",
           embedded: embedded
@@ -81,7 +79,7 @@ describe("JSON Browser", () => {
       const uri = `${testDomain}/main#/foo`;
       const subject = await hyperjump.get(uri);
 
-      expect(toJref(subject, uri)).to.equal(`42`);
+      expect(toJson(subject)).to.equal(`42`);
     });
 
     test("getting the main document from an embedded document", async () => {
@@ -100,7 +98,7 @@ describe("JSON Browser", () => {
       const uri = `${testDomain}/main#/foo`;
       const subject = await hyperjump.get(uri);
 
-      expect(toJref(subject, uri)).to.equal(`42`);
+      expect(toJson(subject)).to.equal(`42`);
     });
 
     test("getting an embedded document from an embedded document", async () => {
@@ -119,7 +117,7 @@ describe("JSON Browser", () => {
       const uri = `${testDomain}/main#/foo`;
       const subject = await hyperjump.get(uri);
 
-      expect(toJref(subject, uri)).to.equal(`42`);
+      expect(toJson(subject)).to.equal(`42`);
     });
 
     test("a cached document takes precence over an embedded document", async () => {
@@ -148,7 +146,7 @@ describe("JSON Browser", () => {
       const uri = `${testDomain}/main#/foo`;
       const subject = await hyperjump.get(uri);
 
-      expect(toJref(subject, uri)).to.equal(`42`);
+      expect(toJson(subject)).to.equal(`42`);
     });
   });
 });

src/hyperjump/generators.test.js

@@ -1,12 +1,7 @@
 import { describe, test, beforeEach, afterEach, expect } from "vitest";
 import { MockAgent, setGlobalDispatcher } from "undici";
 import { Hyperjump } from "./index.js";
-import { toJref } from "../jref/index.js";
-
-/**
- * @import { JrefNode } from "../jref/index.js"
- * @import { JsonCompatible } from "../json/index.js"
- */
+import { toJson } from "../json/jsonast-util.js";
 
 
 describe("JSON Browser", () => {
@@ -44,11 +39,11 @@ describe("JSON Browser", () => {
       const generator = hyperjump.iter(subject);
 
       const first = await generator.next();
-      expect(toJref(/** @type NonNullable<any> */ (first.value), uri)).to.equal(`1`);
+      expect(first.value && toJson(first.value)).to.equal(`1`);
       const second = await generator.next();
-      expect(toJref(/** @type NonNullable<any> */ (second.value), uri)).to.equal(`2`);
+      expect(second.value && toJson(second.value)).to.equal(`2`);
       const third = await generator.next();
-      expect(toJref(/** @type NonNullable<any> */ (third.value), uri)).to.equal(`2`);
+      expect(third.value && toJson(third.value)).to.equal(`2`);
       expect((await generator.next()).done).to.equal(true);
     });
 
@@ -95,11 +90,11 @@ describe("JSON Browser", () => {
       const generator = hyperjump.values(subject);
 
       const first = await generator.next();
-      expect(toJref(/** @type NonNullable<any> */ (first.value), uri)).to.equal(`1`);
+      expect(first.value && toJson(first.value)).to.equal(`1`);
       const second = await generator.next();
-      expect(toJref(/** @type NonNullable<any> */ (second.value), uri)).to.equal(`2`);
+      expect(second.value && toJson(second.value)).to.equal(`2`);
       const third = await generator.next();
-      expect(toJref(/** @type NonNullable<any> */ (third.value), uri)).to.equal(`2`);
+      expect(third.value && toJson(third.value)).to.equal(`2`);
       expect((await generator.next()).done).to.equal(true);
     });
 
@@ -124,17 +119,17 @@ describe("JSON Browser", () => {
       const subject = await hyperjump.get(uri);
       const generator = hyperjump.entries(subject);
 
-      const a = /** @type [string, JsonCompatible<JrefNode>] */ ((await generator.next()).value);
-      expect(a[0]).to.equal("a");
-      expect(toJref(a[1], uri)).to.equal(`1`);
+      const a = await generator.next();
+      expect(a.value && a.value[0]).to.equal("a");
+      expect(a.value && toJson(a.value[1])).to.equal(`1`);
 
-      const b = /** @type [string, JsonCompatible<JrefNode>] */ ((await generator.next()).value);
-      expect(b[0]).to.equal("b");
-      expect(toJref(b[1], uri)).to.equal(`2`);
+      const b = await generator.next();
+      expect(b.value && b.value[0]).to.equal("b");
+      expect(b.value && toJson(b.value[1])).to.equal(`2`);
 
-      const c = /** @type [string, JsonCompatible<JrefNode>] */ ((await generator.next()).value);
-      expect(c[0]).to.equal("c");
-      expect(toJref(c[1], uri)).to.equal(`2`);
+      const c = await generator.next();
+      expect(c.value && c.value[0]).to.equal("c");
+      expect(c.value && toJson(c.value[1])).to.equal(`2`);
 
       expect((await generator.next()).done).to.equal(true);
     });

src/hyperjump/get.test.js

@@ -1,7 +1,7 @@
 import { describe, test, beforeEach, afterEach, expect } from "vitest";
 import { MockAgent, setGlobalDispatcher } from "undici";
 import { Hyperjump } from "./index.js";
-import { toJref } from "../jref/index.js";
+import { toJson } from "../json/jsonast-util.js";
 
 
 describe("JSON Browser", () => {
@@ -41,7 +41,7 @@ describe("JSON Browser", () => {
       const browser = new Hyperjump();
       const subject = await browser.get(uri);
 
-      expect(toJref(subject, uri, undefined, "  ")).to.eql(jref);
+      expect(toJson(subject, undefined, "  ")).to.eql(jref);
     });
 
     test("follow fragment-only reference", async () => {
@@ -63,7 +63,7 @@ describe("JSON Browser", () => {
       const browser = new Hyperjump();
       const subject = await browser.get(`${uri}#/bar`);
 
-      expect(toJref(subject, uri)).to.eql(`42`);
+      expect(toJson(subject)).to.eql(`42`);
     });
 
     test("follow reference to another document", async () => {
@@ -87,7 +87,7 @@ describe("JSON Browser", () => {
       const browser = new Hyperjump();
       const subject = await browser.get(uri);
 
-      expect(toJref(subject, uri)).to.eql(`"bar"`);
+      expect(toJson(subject)).to.eql(`"bar"`);
     });
 
     test("follow a reference to another document with a fragment", async () => {
@@ -113,7 +113,7 @@ describe("JSON Browser", () => {
       const browser = new Hyperjump();
       const subject = await browser.get(uri);
 
-      expect(toJref(subject, uri)).to.eql(`24`);
+      expect(toJson(subject)).to.eql(`24`);
     });
   });
 });

src/hyperjump/hyperjump.d.ts

@@ -1,4 +1,4 @@
-import type { JsonCompatible } from "../json/jsonast.d.ts";
+import type { JsonNode } from "../json/jsonast.d.ts";
 import type { JrefNode } from "../jref/jref-ast.d.ts";
 import type { UriSchemePlugin } from "./uri-schemes/uri-scheme-plugin.d.ts";
 import type { DocumentNode, MediaTypePlugin } from "./media-types/media-type-plugin.d.ts";
@@ -29,7 +29,7 @@ export class Hyperjump<T extends JrefNode = JrefNode> {
    * @throws {@link RetrievalError}
    * @throws {@link json.JsonPointerError}
    */
-  get: (uri: string, options?: GetOptions) => Promise<JsonCompatible<T>>;
+  get: (uri: string, options?: GetOptions) => Promise<JsonNode<T>>;
 
   /**
    * Add support for a
@@ -93,27 +93,27 @@ export class Hyperjump<T extends JrefNode = JrefNode> {
    * This is like indexing into an object or array. It will follow any
    * references it encounters so it always returns a JSON compatible value.
    */
-  step: (key: string, node: JsonCompatible<T>) => Promise<JsonCompatible<T>>;
+  step: (key: string, node: JsonNode<T>) => Promise<JsonNode<T>>;
 
   /**
    * Iterate over an array node. It will follow any references it encounters so
    * it always yields JSON compatible values.
    */
-  iter: (node: JsonCompatible<T>) => AsyncGenerator<JsonCompatible<T>, void, unknown>;
+  iter: (node: JsonNode<T>) => AsyncGenerator<JsonNode<T>, void, unknown>;
 
   keys: typeof jsonObjectKeys;
 
   /**
    * Iterate over the values of an object. It will follow any references it
    * encounters so it always yields JSON compatible values.
    */
-  values: (node: JsonCompatible<T>) => AsyncGenerator<JsonCompatible<T>, void, unknown>;
+  values: (node: JsonNode<T>) => AsyncGenerator<JsonNode<T>, void, unknown>;
 
   /**
    * Iterate over key/value pairs of an object. It will follow any references it
    * encounters so it always yields JSON compatible values.
    */
-  entries: (node: JsonCompatible<T>) => AsyncGenerator<[string, JsonCompatible<T>], void, unknown>;
+  entries: (node: JsonNode<T>) => AsyncGenerator<[string, JsonNode<T>], void, unknown>;
 }
 
 export class RetrievalError extends Error {

src/hyperjump/hyperjump.js

@@ -5,13 +5,12 @@ import { HttpUriSchemePlugin } from "./uri-schemes/http-scheme-plugin.js";
 import { FileUriSchemePlugin } from "./uri-schemes/file-scheme-plugin.js";
 import { JsonMediaTypePlugin } from "./media-types/json-media-type-plugin.js";
 import { JrefMediaTypePlugin } from "./media-types/jref-media-type-plugin.js";
-import { pointerGet, pointerStep } from "../jref/jref-util.js";
-import { jsonObjectHas, jsonObjectKeys, jsonValue } from "../json/jsonast-util.js";
+import { jsonObjectHas, jsonObjectKeys, jsonValue, pointerGet, pointerStep } from "../json/jsonast-util.js";
 import { mimeMatch } from "./utilities.js";
 
 /**
- * @import { JrefNode } from "../jref/jref-ast.js"
- * @import { JsonCompatible } from "../json/jsonast.js"
+ * @import { JrefJrefNode, JrefNode } from "../jref/jref-ast.js"
+ * @import { JsonNode } from "../json/jsonast.js"
  * @import { UriSchemePlugin } from "./uri-schemes/uri-scheme-plugin.js"
  * @import { DocumentNode, MediaTypePlugin } from "./media-types/media-type-plugin.js"
  * @import * as API from "./hyperjump.d.ts"
@@ -22,7 +21,7 @@ import { mimeMatch } from "./utilities.js";
 // TODO: Support filters
 
 /**
- * @template {JrefNode} [T=JrefNode]
+ * @template {JrefNode<any>} [T=JrefJrefNode]
  * @implements API.Hyperjump<T>
  */
 export class Hyperjump {
@@ -72,7 +71,7 @@ export class Hyperjump {
     // TODO: How should cache work?
 
     const cachedDocument = this.#cache[id];
-    const embeddedDocument = options?.referencedFrom ? this.#cache[options.referencedFrom].embedded?.[id] : undefined;
+    const embeddedDocument = options.referencedFrom ? this.#cache[options.referencedFrom]?.embedded?.[id] : undefined;
     let document = cachedDocument ?? embeddedDocument;
 
     if (!document) {
@@ -97,12 +96,12 @@ export class Hyperjump {
     return await this.#followReferences(node);
   }
 
-  /** @type (node: T) => Promise<JsonCompatible<T>> */
+  /** @type (node: T) => Promise<JsonNode<T>> */
   async #followReferences(node) {
-    if (node?.type === "jref-reference") {
-      return this.get(node.value, { referencedFrom: node.documentUri });
+    if ("jrefType" in node) {
+      return this.get(node.href, { referencedFrom: node.documentUri });
     } else {
-      return /** @type JsonCompatible<T> */ (node);
+      return /** @type JsonNode<T> */ (node);
     }
   }
 

src/hyperjump/node-functions.test.js

@@ -3,8 +3,8 @@ import { MockAgent, setGlobalDispatcher } from "undici";
 import { Hyperjump } from "./index.js";
 
 /**
- * @import { JsonCompatible } from "../json/index.js"
- * @import { JrefNode } from "../jref/index.js"
+ * @import { JsonNode } from "../json/index.js"
+ * @import { JrefJrefNode } from "../jref/index.js"
  */
 
 
@@ -26,7 +26,7 @@ describe("JSON Browser", () => {
   describe("object has property", () => {
     const hyperjump = new Hyperjump();
 
-    /** @type JsonCompatible<JrefNode> */
+    /** @type JsonNode<JrefJrefNode> */
     let node;
 
     beforeEach(async () => {

src/hyperjump/step.test.js

@@ -1,7 +1,7 @@
 import { describe, test, beforeEach, afterEach, expect } from "vitest";
 import { MockAgent, setGlobalDispatcher } from "undici";
 import { Hyperjump } from "./index.js";
-import { toJref } from "../jref/index.js";
+import { toJson } from "../json/jsonast-util.js";
 
 
 describe("JSON Browser", () => {
@@ -34,7 +34,7 @@ describe("JSON Browser", () => {
       const subject = await hyperjump.get(uri);
       const foo = await hyperjump.step("foo", subject);
 
-      expect(toJref(foo, uri)).to.eql(`42`);
+      expect(toJson(foo)).to.eql(`42`);
     });
 
     test("local reference to value", async () => {
@@ -53,7 +53,7 @@ describe("JSON Browser", () => {
       const subject = await hyperjump.get(uri);
       const foo = await hyperjump.step("bar", subject);
 
-      expect(toJref(foo, uri)).to.eql(`42`);
+      expect(toJson(foo)).to.eql(`42`);
     });
 
     test("local reference to local reference to value", async () => {
@@ -73,7 +73,7 @@ describe("JSON Browser", () => {
       const subject = await hyperjump.get(uri);
       const foo = await hyperjump.step("baz", subject);
 
-      expect(toJref(foo, uri)).to.eql(`42`);
+      expect(toJson(foo)).to.eql(`42`);
     });
 
     test("local reference to external reference to value", async () => {
@@ -99,7 +99,7 @@ describe("JSON Browser", () => {
       const subject = await hyperjump.get(uri);
       const foo = await hyperjump.step("baz", subject);
 
-      expect(toJref(foo, uri)).to.eql(`42`);
+      expect(toJson(foo)).to.eql(`42`);
     });
 
     test("external reference to value", async () => {
@@ -125,7 +125,7 @@ describe("JSON Browser", () => {
 
       const foo = await hyperjump.step("bar", subject);
 
-      expect(toJref(foo, uri)).to.eql(`42`);
+      expect(toJson(foo)).to.eql(`42`);
     });
 
     test("external reference to local reference to value", async () => {
@@ -154,7 +154,7 @@ describe("JSON Browser", () => {
 
       const foo = await hyperjump.step("baz", subject);
 
-      expect(toJref(foo, uri)).to.eql(`42`);
+      expect(toJson(foo)).to.eql(`42`);
     });
   });
 });