Refactor types again

Author: jdesrosiers

src/hyperjump/embedded.test.js

@@ -6,7 +6,7 @@ import { fromJref } from "../jref/index.js";
 import { toJson } from "../json/jsonast-util.js";
 
 /**
- * @import { DocumentNode } from "./index.js"
+ * @import { JrefJrefNode } from "../jref/jref-ast.js"
  */
 
 
@@ -17,8 +17,27 @@ describe("JSON Browser", () => {
     const testMediaType = "application/prs.hyperjump-embedded-test";
 
     beforeAll(() => {
-      /** @type (uri: string, text: string, embedded?: Record<string, DocumentNode>) => DocumentNode */
+      /**
+       * @typedef {{
+       *   type: "embedded-document";
+       *   children: JrefJrefNode[];
+       *   uri: string;
+       *   fragmentKind: "json-pointer";
+       *   embedded?: Record<string, EmbeddedDocumentNode>;
+       * }} EmbeddedDocumentNode
+       */
+
+      /** @type (uri: string, text: string, embedded?: Record<string, EmbeddedDocumentNode>) => EmbeddedDocumentNode */
       const parseToDocument = (uri, text, embedded = {}) => {
+        /** @type EmbeddedDocumentNode */
+        const embeddedDocument = {
+          type: "embedded-document",
+          children: [],
+          uri: uri,
+          fragmentKind: "json-pointer",
+          embedded: embedded
+        };
+
         const rootNode = fromJref(text, uri, (node, key) => {
           if (key === "$embedded" && node.jsonType === "object") {
             for (const propertyNode of node.children) {
@@ -32,13 +51,11 @@ describe("JSON Browser", () => {
           }
         });
 
-        return {
-          type: "embedded-document",
-          children: [rootNode],
-          uri: uri,
-          fragmentKind: "json-pointer",
-          embedded: embedded
-        };
+        if (rootNode) {
+          embeddedDocument.children.push(rootNode);
+        }
+
+        return embeddedDocument;
       };
       hyperjump.addMediaTypePlugin({
         mediaType: testMediaType,

src/hyperjump/hyperjump.d.ts

@@ -1,5 +1,5 @@
 import type { JsonNode } from "../json/jsonast.d.ts";
-import type { JrefNode, JrefJrefNode } from "../jref/jref-ast.d.ts";
+import type { JrefJrefNode } 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";
 import type { jsonObjectHas, jsonObjectKeys, jsonValue } from "../json/jsonast-util.js";
@@ -11,8 +11,7 @@ export type GetOptions = {
   referencedFrom?: string;
 };
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export class Hyperjump<T extends JrefNode<any> = JrefJrefNode> {
+export class Hyperjump<T extends JrefNode<{}> = JrefJrefNode> {
   constructor(config?: HyperjumpConfig);
 
   /**
@@ -30,7 +29,7 @@ export class Hyperjump<T extends JrefNode<any> = JrefJrefNode> {
    * @throws {@link RetrievalError}
    * @throws {@link json.JsonPointerError}
    */
-  get: (uri: string, options?: GetOptions) => Promise<T & JsonNode<T>>;
+  get: (uri: string, options?: GetOptions) => Promise<JsonNode<T>>;
 
   /**
    * Add support for a
@@ -72,7 +71,7 @@ export class Hyperjump<T extends JrefNode<any> = JrefJrefNode> {
    * {@link hyperjump.JsonMediaTypePlugin | `JSON`} media types are enabled by
    * default.
    */
-  addMediaTypePlugin: <T extends DocumentNode>(plugin: MediaTypePlugin<T>) => void;
+  addMediaTypePlugin: <A extends DocumentNode<T>>(plugin: MediaTypePlugin<A>) => void;
 
   /**
    * This is mostly useful for disabling a scheme that's enabled by default.
@@ -94,27 +93,27 @@ export class Hyperjump<T extends JrefNode<any> = JrefJrefNode> {
    * 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: JsonNode<T>) => Promise<T & JsonNode<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: JsonNode<T>) => AsyncGenerator<T & JsonNode<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: JsonNode<T>) => AsyncGenerator<T & JsonNode<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: JsonNode<T>) => AsyncGenerator<[string, T & JsonNode<T>], void, unknown>;
+  entries: (node: JsonNode<T>) => AsyncGenerator<[string, JsonNode<T>], void, unknown>;
 }
 
 export class RetrievalError extends Error {

src/hyperjump/hyperjump.js

@@ -21,20 +21,20 @@ import { mimeMatch } from "./utilities.js";
 // TODO: Support filters
 
 /**
- * @template {JrefNode<any>} [T=JrefJrefNode]
+ * @template {JrefNode<unknown>} [T=JrefJrefNode]
  * @implements API.Hyperjump<T>
  */
 export class Hyperjump {
   // TODO: Add config to enable schemes and media types
   #config;
 
-  /** @type Record<string, DocumentNode> */
+  /** @type Record<string, DocumentNode<T>> */
   #cache;
 
   /** @type Record<string, UriSchemePlugin> */
   #uriSchemePlugins;
 
-  /** @type Record<string, MediaTypePlugin<DocumentNode>> */
+  /** @type Record<string, MediaTypePlugin<DocumentNode<T>>> */
   #mediaTypePlugins;
 
   /** @type API.GetOptions */
@@ -91,14 +91,13 @@ export class Hyperjump {
     }
     const cursor = document.fragmentKind === "json-pointer" ? fragment : "";
 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-    const node = /** @type T */ (pointerGet(cursor ?? "", document.children[0], document.uri));
+    const node = pointerGet(cursor ?? "", document.children[0], document.uri);
     return await this.#followReferences(node);
   }
 
-  /** @type (node: T) => Promise<JsonNode<T>> */
+  /** @type (node: JrefNode<T>) => Promise<JsonNode<T>> */
   async #followReferences(node) {
-    if ("jrefType" in node) {
+    if (node.jrefType === "reference") {
       return this.get(node.href, { referencedFrom: toAbsoluteIri(node.location) });
     } else {
       return /** @type JsonNode<T> */ (node);
@@ -182,7 +181,7 @@ export class Hyperjump {
     this.#mediaTypePlugins[contentType].quality = quality;
   }
 
-  /** @type (response: Response) => Promise<DocumentNode> */
+  /** @type (response: Response) => Promise<DocumentNode<T>> */
   #parseResponse(response) {
     const contentTypeText = response.headers.get("content-type");
     if (contentTypeText === null) {
@@ -204,7 +203,7 @@ export class Hyperjump {
 
   /** @type API.Hyperjump<T>["step"] */
   async step(key, node) {
-    return await this.#followReferences(/** @type T */ (pointerStep(key, node)));
+    return await this.#followReferences(pointerStep(key, node));
   }
 
   /** @type API.Hyperjump<T>["iter"] */

src/hyperjump/media-types/media-type-plugin.d.ts

@@ -1,17 +1,14 @@
-import type { JrefNode } from "../../jref/jrefast.d.ts";
-
-
-export type DocumentNode = {
+export type DocumentNode<A> = {
   type: string;
-  children: JrefNode[];
+  children: A[];
   uri?: string;
-  embedded?: Record<string, DocumentNode>;
+  embedded?: Record<string, DocumentNode<A>>;
   anchors?: Record<string, string>;
   fragmentKind?: string;
 };
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface MediaTypePlugin<T extends DocumentNode> {
+export interface MediaTypePlugin<T extends DocumentNode<unknown>> {
   mediaType: string;
   /**
    * Extensions start with `.` (Example: `.jref`).

src/jref/jref-ast.d.ts

@@ -1,74 +1,20 @@
 import type { Data } from "unist";
-import {
-  JsonArrayNode,
-  JsonBooleanNode,
-  JsonNullNode,
-  JsonNumberNode,
-  JsonObjectNode,
-  JsonStringNode
-} from "../json/jsonast.d.ts";
+import type { JsonNode } from "../json/jsonast.d.ts";
 
+export type JrefNode<A> = JsonNode<A & (
+  {
+    jrefType: "json";
+  } | {
+    jrefType: "reference";
+    href: string;
+  }
+)>;
 
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefReferenceNode {
-  jrefType: "jref-reference";
-  href: string;
-};
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefJsonNullNode extends JsonNullNode {
-  type: "jref";
-};
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefJsonBooleanNode extends JsonBooleanNode {
-  type: "jref";
-};
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefJsonNumberNode extends JsonNumberNode {
-  type: "jref";
-};
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefJsonStringNode extends JsonStringNode {
-  type: "jref";
-};
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefJsonArrayNode extends JsonArrayNode<JrefJrefNode> {
-  type: "jref";
-};
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefJsonObjectNode extends JsonObjectNode<JrefJrefNode> {
-  type: "jref";
-};
-
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-export interface JrefJrefReferenceNode extends JrefReferenceNode, JsonObjectNode<JrefJrefNode> {
-  type: "jref";
-};
-
-export type JrefNode<A> = JsonObjectNode<A>
-  | JsonArrayNode<A>
-  | JsonStringNode
-  | JsonNumberNode
-  | JsonBooleanNode
-  | JsonNullNode
-  | (JrefReferenceNode & JsonObjectNode<A>);
-
-export type JrefJrefNode = JrefJsonObjectNode
-  | JrefJsonArrayNode
-  | JrefJsonStringNode
-  | JrefJsonNumberNode
-  | JrefJsonBooleanNode
-  | JrefJsonNullNode
-  | JrefJrefReferenceNode;
+export type JrefJrefNode = JrefNode<{ type: "jref" }>;
 
 export type JrefDocumentNode = {
   type: "jref-document";
-  children: JrefJrefNode[];
+  children: JrefNode<{}>[];
   uri: string;
   fragmentKind: "json-pointer";
   data?: Data;

src/jref/jref-parse.d.ts

@@ -4,7 +4,7 @@ import { Reviver } from "./jref-util.js";
 
 
 export type JrefParseOptions = {
-  reviver?: Reviver<JrefJrefNode>;
+  reviver?: Reviver<JrefJrefNode, JrefJrefNode>;
 };
 
 /**

src/jref/jref-util.d.ts

@@ -1,14 +1,35 @@
-import { JrefJrefNode, JrefNode } from "./jref-ast.d.ts";
+import type {
+  JsonArrayNode,
+  JsonBooleanNode,
+  JsonNullNode,
+  JsonNumberNode,
+  JsonObjectNode,
+  JsonStringNode
+} from "../json/jsonast.js";
+import type { JrefNode } from "./jref-ast.d.ts";
 
+export type ParsedJrefNode<A> = {
+  type: "jref";
+} & (
+  {
+    jrefType: "json";
+  } | {
+    jrefType: "reference";
+    href: string;
+  }
+) & (
+  JsonObjectNode<JrefNode<A>>
+  | JsonArrayNode<JrefNode<A>>
+  | JsonStringNode
+  | JsonNumberNode
+  | JsonBooleanNode
+  | JsonNullNode
+);
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type Reviver<T = JrefNode<any> | undefined> = <A>(node: JrefNode<JrefNode<A>>, key?: string) => T;
+export type Reviver<A, R extends JrefNode<A> | undefined> = (node: ParsedJrefNode<A>, key?: string) => R;
 
 /**
  * Parse a JRef string into a JRef AST. Includes a reviver option similar to
  * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse}.
  */
-export const fromJref: {
-  (json: string, uri: string): JrefJrefNode;
-  <R extends Reviver | undefined>(jref: string, uri: string, reviver: R): R extends undefined ? JrefJrefNode : ReturnType<R>;
-};
+export const fromJref: <A = { type: "jref" }, R = JrefNode<A>>(json: string, uri: string, reviver?: Reviver<A, R>) => R;