Skip to content

Follow references yourself

The jref functions follow every reference they reach, which is what you want to read values. Some code needs the references themselves: to list what a document refers to, to report every reference that’s broken, or to follow the references in a tree that the Hyperjump session didn’t retrieve. These examples use this session:

TypeScript
import { Hyperjump, browse } from "@hyperjump/browser";
const session = new Hyperjump({
allowRetrieval: ["https://swapi.hyperjump.io/"]
});
const luke = await browse(session, "https://swapi.hyperjump.io/api/people/1");

Every jref function takes reference: "manual" as its last argument, like browse does. With it, the function doesn’t follow references, so it reads the tree as it’s written and a reference is a target like any other. This lists what a film refers to. jrefHref gives you the URL that a reference refers to:

TypeScript
import { browse, jrefFindAll, jrefHref } from "@hyperjump/browser";
const url = "https://swapi.hyperjump.io/api/films/1";
const film = await browse(session, url, { reference: "manual" });
const references = await jrefFindAll(session, film, "reference", {
reference: "manual"
});
for (const reference of references) {
console.log(jrefHref(reference));
}

Without reference: "manual", a walk follows every reference it reaches, so it never reaches one. A test or a selector that matches only references, like "reference" or [type=reference], can’t find anything then, so the function throws a TypeError instead of walking.

jrefStep and the iterators take it too, so jrefStep(session, "homeworld", luke, { reference: "manual" }) is the reference to Luke’s homeworld and not the homeworld.

A step can give you a reference or a value, so jrefIsReference says which one you have. In TypeScript, it also narrows the target to a reference for jrefHref. This lists which of Luke’s properties are references:

TypeScript
import { jrefHref, jrefIsReference, jrefObjectEntries } from "@hyperjump/browser";
const manual = { reference: "manual" } as const;
for await (const [key, value] of jrefObjectEntries(session, luke, manual)) {
if (jrefIsReference(value)) {
console.log(key, jrefHref(value));
}
}
Output
homeworld https://swapi.hyperjump.io/api/planets/1

jrefHref throws a TypeError for a target that isn’t a reference. A test like "reference" only finds references, so the first example doesn’t need to check.

jrefFollow gives you the value that a reference leads to. If that value is another reference, it follows that one too. For a target that isn’t a reference, it gives you the target:

TypeScript
import { jrefFollow, jrefStep } from "@hyperjump/browser";
const written = await jrefStep(session, "homeworld", luke, {
reference: "manual"
});
const homeworld = await jrefFollow(session, written);

It follows the reference from the document that the reference is in, like the other jref functions do. That document causes the request, so the Hyperjump session knows whether it may refer to a file, and a reference finds a document that its document contains without retrieving it.

The jref functions follow each reference when they reach it, and wait for it before they go on. That’s what lets a walk that stops early, or a selector that can’t match under a value, skip retrieving the rest. It also means the documents that a walk reaches load one after another. To load them all at once, find the references as they’re written, follow them together with jrefFollow, and then walk:

TypeScript
import { browse, jrefFollow, jrefSelectAll } from "@hyperjump/browser";
const film = await browse(session, "https://swapi.hyperjump.io/api/films/1");
const characters = await jrefSelectAll(
session,
"> [key=characters] > *",
film,
{ reference: "manual" }
);
await Promise.all(
characters.map((character) => jrefFollow(session, character))
);
const names = await jrefSelectAll(
session,
"> [key=characters] > * > [key=name]",
film
);

The Hyperjump session keeps every document it retrieves, so the walk finds each character’s document without retrieving it again. For more information, see Browse to a URL. In Node.js, the default stack limits how many requests go to a server at once, so some of them wait for a slot:

Output
# url source stat 0ms 833ms
1 swapi.hyperjump.io/api/films/1 network 200 |█████████████████████ |
2 ↳ swapi.hyperjump.io/api/people/1 network 200 | ██████ |
3 ↳ swapi.hyperjump.io/api/people/2 network 200 | ██████ |
4 ↳ swapi.hyperjump.io/api/people/3 network 200 | ██████ |
5 ↳ swapi.hyperjump.io/api/people/4 network 200 | █████ |
6 ↳ swapi.hyperjump.io/api/people/5 network 200 | ██████ |
7 ↳ swapi.hyperjump.io/api/people/6 network 200 | ██████ |
8 ↳ swapi.hyperjump.io/api/people/7 network 200 | ░░░░████████████ |
9 ↳ swapi.hyperjump.io/api/people/8 network 200 | ░░░░░███████████ |
...

With the 18 characters of this film, the walk on its own took about two seconds, and loading them first took under one. For more information about limits and waiting, see Priorities.

Loading ahead of a walk retrieves everything you find, even what the walk wouldn’t have reached. Find only the references that you know the walk needs.

A walk that can’t follow a reference throws what browse throws, such as a network error or an ERR_HTTP_STATUS error. To report every broken reference instead of stopping at the first, find the references as they’re written, and follow each one with jrefFollow. jrefLocation gives you the URL of where a reference is:

TypeScript
import { jrefFindAll, jrefFollow, jrefLocation } from "@hyperjump/browser";
const references = await jrefFindAll(session, film, "reference", {
reference: "manual"
});
for (const reference of references) {
try {
await jrefFollow(session, reference);
} catch (error) {
console.log(`${jrefLocation(reference)}: ${(error as Error).message}`);
}
}

A document that you parsed yourself, such as with fromJref, isn’t one the Hyperjump session retrieved, so browse never gave you a target for it. Pass the document to a jref function instead of a target, and it starts from the document’s root. A reference in the document finds the document itself and the documents that it contains, without retrieving them:

TypeScript
import { fromJref, hasStatus, jrefSelect } from "@hyperjump/browser";
const { document } = fromJref(
`{ "luke": { "$ref": "/api/people/1" } }`,
"https://swapi.hyperjump.io/mine"
);
if (hasStatus(document, "success")) {
const luke = await jrefSelect(session, "> [key=luke]", document);
}

A document that you parse can have syntax errors, so check its status first. In TypeScript, hasStatus also narrows the document’s type, so a document with the status "success" has no error nodes.

A reference that the session retrieves comes from the document’s URL, so only a document whose URL is a file: URL can refer to a file. For more information, see Documents from the web.

The tree in a unified pipeline is a document too. A transformer reads it as it’s written with the ecosystem’s utilities, which give it nodes. To follow a reference that one of them finds, pass the tree as referencedFrom:

TypeScript
import {
browse,
type Hyperjump,
type JrefDocumentNode
} from "@hyperjump/browser";
import { visit } from "unist-util-visit";
const followReferences = (session: Hyperjump) =>
async (tree: JrefDocumentNode) => {
const hrefs: string[] = [];
visit(tree, "reference", (reference) => {
hrefs.push(reference.href);
});
for (const href of hrefs) {
await browse(session, href, { referencedFrom: tree });
}
};

A tree can have any parse status. The jref functions read what a tree whose parse failed has: they leave out a value that’s missing, and a value that the parser couldn’t parse is a json-invalid node.

The jref functions don’t take a node on its own, because a node doesn’t say which document it’s in. To read a value inside a tree, start at the tree and step or select to the value.