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:
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");Read the tree as it’s written
Section titled “Read the tree as it’s written”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:
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:
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)); }}homeworld https://swapi.hyperjump.io/api/planets/1jrefHref 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.
Follow a reference
Section titled “Follow a reference”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:
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.
Load references in parallel
Section titled “Load references in parallel”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:
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:
# 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.
Carry on past a reference that fails
Section titled “Carry on past a reference that fails”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:
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}`); }}Read a tree you parsed
Section titled “Read a tree you parsed”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:
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:
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.