Make Hyperjump generic

Author: jdesrosiers

src/hyperjump/hyperjump.d.ts

@@ -11,7 +11,7 @@ export type GetOptions = {
   referencedFrom?: string;
 };
 
-export class Hyperjump {
+export class Hyperjump<T extends JrefNode = JrefNode> {
   constructor(config?: HyperjumpConfig);
 
   /**
@@ -29,7 +29,7 @@ export class Hyperjump {
    * @throws {@link RetrievalError}
    * @throws {@link json.JsonPointerError}
    */
-  get: (uri: string, options?: GetOptions) => Promise<JsonCompatible<JrefNode>>;
+  get: (uri: string, options?: GetOptions) => Promise<JsonCompatible<T>>;
 
   /**
    * Add support for a
@@ -94,27 +94,27 @@ export class Hyperjump {
    * 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<JrefNode>) => Promise<JsonCompatible<JrefNode>>;
+  step: (key: string, node: JsonCompatible<T>) => Promise<JsonCompatible<T>>;
 
   /**
    * Iterate over an array node. It will follow any references it encounters so
    * it always yields JSON compatible values.
    */
-  iter: (node: JsonCompatible<JrefNode>) => AsyncGenerator<JsonCompatible<JrefNode>, void, unknown>;
+  iter: (node: JsonCompatible<T>) => AsyncGenerator<JsonCompatible<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<JrefNode>) => AsyncGenerator<JsonCompatible<JrefNode>, void, unknown>;
+  values: (node: JsonCompatible<T>) => AsyncGenerator<JsonCompatible<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<JrefNode>) => AsyncGenerator<[string, JsonCompatible<JrefNode>], void, unknown>;
+  entries: (node: JsonCompatible<T>) => AsyncGenerator<[string, JsonCompatible<T>], void, unknown>;
 }
 
 export class RetrievalError extends Error {

src/hyperjump/hyperjump.js

@@ -21,6 +21,10 @@ import { mimeMatch } from "./utilities.js";
 // TODO: Support fetch options in get
 // TODO: Support filters
 
+/**
+ * @template {JrefNode} [T=JrefNode]
+ * @implements API.Hyperjump<T>
+ */
 export class Hyperjump {
   // TODO: Add config to enable schemes and media types
   #config;
@@ -59,7 +63,7 @@ export class Hyperjump {
     this.addMediaTypePlugin(new JsonMediaTypePlugin());
   }
 
-  /** @type API.Hyperjump["get"] */
+  /** @type API.Hyperjump<T>["get"] */
   async get(uri, options = this.#defaultGetOptions) {
     uri = resolveIri(uri, contextUri());
     const id = toAbsoluteIri(uri);
@@ -89,32 +93,32 @@ export class Hyperjump {
     const cursor = document.fragmentKind === "json-pointer" ? fragment : "";
 
     // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-    const node = pointerGet(cursor ?? "", document.children[0], document.uri);
+    const node = /** @type T */ (pointerGet(cursor ?? "", document.children[0], document.uri));
     return await this.#followReferences(node);
   }
 
-  /** @type (node: JrefNode) => Promise<JsonCompatible<JrefNode>> */
+  /** @type (node: T) => Promise<JsonCompatible<T>> */
   async #followReferences(node) {
     if (node?.type === "jref-reference") {
       return this.get(node.value, { referencedFrom: node.documentUri });
     } else {
-      return node;
+      return /** @type JsonCompatible<T> */ (node);
     }
   }
 
-  /** @type API.Hyperjump["addUriSchemePlugin"] */
+  /** @type API.Hyperjump<T>["addUriSchemePlugin"] */
   addUriSchemePlugin(plugin) {
     for (const scheme of plugin.schemes) {
       this.#uriSchemePlugins[scheme] = plugin;
     }
   }
 
-  /** @type API.Hyperjump["removeUriSchemePlugin"] */
+  /** @type API.Hyperjump<T>["removeUriSchemePlugin"] */
   removeUriSchemePlugin(scheme) {
     delete this.#uriSchemePlugins[scheme];
   }
 
-  /** @type API.Hyperjump["retrieve"] */
+  /** @type API.Hyperjump<T>["retrieve"] */
   async retrieve(uri, options) {
     const { scheme } = parseIri(uri);
 
@@ -125,7 +129,7 @@ export class Hyperjump {
     return this.#uriSchemePlugins[scheme].retrieve(uri, options);
   }
 
-  /** @type API.Hyperjump["acceptableMediaTypes"] */
+  /** @type API.Hyperjump<T>["acceptableMediaTypes"] */
   acceptableMediaTypes() {
     let accept = "";
 
@@ -149,7 +153,7 @@ export class Hyperjump {
     return accept;
   }
 
-  /** @type API.Hyperjump["getMediaType"] */
+  /** @type API.Hyperjump<T>["getMediaType"] */
   getMediaType(uri) {
     for (const contentType in this.#mediaTypePlugins) {
       for (const extension of this.#mediaTypePlugins[contentType].extensions) {
@@ -164,17 +168,17 @@ export class Hyperjump {
     throw new UnknownMediaTypeError(`The media type of the file at '${uri}' could not be determined. Use the 'addMediaTypePlugin' function to add support for this media type.`);
   }
 
-  /** @type API.Hyperjump["addMediaTypePlugin"] */
+  /** @type API.Hyperjump<T>["addMediaTypePlugin"] */
   addMediaTypePlugin(plugin) {
     this.#mediaTypePlugins[plugin.mediaType] = plugin;
   }
 
-  /** @type API.Hyperjump["removeMediaTypePlugin"] */
+  /** @type API.Hyperjump<T>["removeMediaTypePlugin"] */
   removeMediaTypePlugin(contentType) {
     delete this.#mediaTypePlugins[contentType];
   }
 
-  /** @type API.Hyperjump["setMediaTypeQuality"] */
+  /** @type API.Hyperjump<T>["setMediaTypeQuality"] */
   setMediaTypeQuality(contentType, quality) {
     this.#mediaTypePlugins[contentType].quality = quality;
   }
@@ -200,12 +204,12 @@ export class Hyperjump {
   typeOf = jsonTypeOf;
   has = jsonObjectHas;
 
-  /** @type API.Hyperjump["step"] */
+  /** @type API.Hyperjump<T>["step"] */
   async step(key, node) {
-    return await this.#followReferences(pointerStep(key, node));
+    return await this.#followReferences(/** @type T */ (pointerStep(key, node)));
   }
 
-  /** @type API.Hyperjump["iter"] */
+  /** @type API.Hyperjump<T>["iter"] */
   async* iter(node) {
     if (node.jsonType === "array") {
       for (const itemNode of node.children) {
@@ -216,7 +220,7 @@ export class Hyperjump {
 
   keys = jsonObjectKeys;
 
-  /** @type API.Hyperjump["values"] */
+  /** @type API.Hyperjump<T>["values"] */
   async* values(node) {
     if (node.jsonType === "object") {
       for (const propertyNode of node.children) {
@@ -225,11 +229,14 @@ export class Hyperjump {
     }
   }
 
-  /** @type API.Hyperjump["entries"] */
+  /** @type API.Hyperjump<T>["entries"] */
   async* entries(node) {
     if (node.jsonType === "object") {
       for (const propertyNode of node.children) {
-        yield [propertyNode.children[0].value, await this.#followReferences(propertyNode.children[1])];
+        yield [
+          propertyNode.children[0].value,
+          await this.#followReferences(propertyNode.children[1])
+        ];
       }
     }
   }

src/hyperjump/uri-schemes/file-scheme-plugin.d.ts

@@ -6,7 +6,8 @@ import { Hyperjump } from "../hyperjump.js";
  * Supports the `file:` URI scheme. Media type is determined by file extensions.
  */
 export class FileUriSchemePlugin implements UriSchemePlugin {
-  constructor(hyperjump: Hyperjump);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(hyperjump: Hyperjump<any>);
   schemes: string[];
   retrieve: UriSchemePlugin["retrieve"];
 }

src/hyperjump/uri-schemes/file-scheme-plugin.js

@@ -15,7 +15,7 @@ export class FileUriSchemePlugin {
   #hyperjump;
 
   /**
-   * @param {Hyperjump} hyperjump
+   * @param {Hyperjump<any>} hyperjump
    */
   constructor(hyperjump) {
     this.schemes = ["file"];

src/hyperjump/uri-schemes/http-scheme-plugin.d.ts

@@ -7,7 +7,8 @@ import { UriSchemePlugin } from "./uri-scheme-plugin.d.ts";
  * representng all registered media types.
  */
 export class HttpUriSchemePlugin implements UriSchemePlugin {
-  constructor(hyperjump: Hyperjump);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(hyperjump: Hyperjump<any>);
 
   schemes: string[];
 

src/hyperjump/uri-schemes/http-scheme-plugin.js

@@ -1,6 +1,5 @@
 /**
  * @import { Hyperjump } from "../index.js"
- * @import { UriSchemePlugin } from "./uri-scheme-plugin.js"
  * @import * as API from "./http-scheme-plugin.d.ts"
  */
 
@@ -11,7 +10,7 @@ export class HttpUriSchemePlugin {
   #successStatus;
 
   /**
-   * @param {Hyperjump} hyperjump
+   * @param {Hyperjump<any>} hyperjump
    */
   constructor(hyperjump) {
     this.schemes = ["http", "https"];

src/jref/jref-parse.js

@@ -3,7 +3,6 @@ import { VFileMessage } from "vfile-message";
 import { fromJref } from "./jref-util.js";
 
 /**
- * @import { VFile } from "vfile"
  * @import { Options } from "vfile-message"
  * @import { JrefDocumentNode } from "./jref-ast.js"
  * @import * as API from "./jref-parse.d.ts"
@@ -12,7 +11,6 @@ import { fromJref } from "./jref-util.js";
 
 /** @type API.jrefParse */
 export function jrefParse(options) {
-  /** @type (document: string, file: VFile) => JrefDocumentNode */
   this.parser = function (document, file) {
     try {
       const uri = pathToFileURL(file.path).toString();

src/jref/jref-stringify.js

@@ -1,15 +1,13 @@
 import { toJref } from "./jref-util.js";
 
 /**
- * @import { Node } from "unist"
  * @import { JrefDocumentNode } from "./jref-ast.js"
  * @import * as API from "./jref-stringify.d.ts"
  */
 
 
 /** @type API.jrefStringify */
 export function jrefStringify(options) {
-  /** @type (tree: Node) => string */
   this.compiler = (tree) => {
     const jrefDocument = /** @type JrefDocumentNode */ (tree);
     return toJref(jrefDocument.children[0], jrefDocument.uri, options?.replacer, options?.space) + "\n";

src/json/rejson-parse.js

@@ -2,7 +2,6 @@ import { VFileMessage } from "vfile-message";
 import { fromJson } from "./jsonast-util.js";
 
 /**
- * @import { VFile } from "vfile"
  * @import { Options } from "vfile-message"
  * @import { JsonDocumentNode } from "./jsonast.js"
  * @import * as API from "./rejson-parse.d.ts"
@@ -11,7 +10,6 @@ import { fromJson } from "./jsonast-util.js";
 
 /** @type API.rejsonParse */
 export function rejsonParse(options) {
-  /** @type (document: string, file: VFile) => JsonDocumentNode */
   this.parser = function (document, file) {
     try {
       /** @type JsonDocumentNode */

src/json/rejson-stringify.js

@@ -1,15 +1,13 @@
 import { toJson } from "./jsonast-util.js";
 
 /**
- * @import { Node } from "unist"
  * @import { JsonDocumentNode } from "./jsonast.js"
  * @import * as API from "./rejson-stringify.d.ts"
  */
 
 
 /** @type API.rejsonStringify */
 export function rejsonStringify(options) {
-  /** @type (tree: Node) => string */
   this.compiler = (tree) => {
     return toJson(/** @type JsonDocumentNode */ (tree).children[0], options?.replacer, options?.space) + "\n";
   };

tsconfig.json

@@ -9,6 +9,7 @@
     "strictNullChecks": true,
     "checkJs": true,
     "skipLibCheck": true,
-    "allowImportingTsExtensions": true
+    "allowImportingTsExtensions": true,
+    "noEmit": true
   }
 }