Read values
browse gives you a target for the value a URL identifies. The jref functions
take a target and read its value or step into, visit, find, and select the
values under it. They give you targets for those values, which you pass to them
in turn. They take a Hyperjump session so they can
follow the references they reach.
Most of the examples on this page read Luke’s document from a Star Wars API. They start from the session and the target that this code makes:
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");Follow references
Section titled “Follow references”Following a reference can mean retrieving a document, so the jref functions
are asynchronous and take the Hyperjump session. One way to step into a target
is with a selector, which Select values covers in full. This
one steps from Luke to his homeworld and then to its name. jrefValue gives you
the name as a string:
import { jrefSelect, jrefValue } from "@hyperjump/browser";
const name = await jrefSelect( session, "> [key=homeworld] > [key=name]", luke);if (name) { await jrefValue(session, name); // "Tatooine"}Luke’s homeworld is a reference to the planet’s document, but the code doesn’t
need to know that. A reference only means something in the document it’s in,
and a target knows which document its value is in. So when a jref function
reaches a reference, it knows where to follow it from.
None of the jref functions give you a reference. Each one follows any
reference it reaches and gives you the referenced value instead. If that value
is another reference, the function follows that one too.
To read the tree as it’s written, pass reference: "manual". The jref
function then gives you a target for a reference without following it. For
more information, see
Follow references yourself. If you
pass a target for a reference to a jref function, it starts from the value
the reference leads to. Without reference: "manual", a target from browse
or a jref function is never for a reference.
Step one level at a time
Section titled “Step one level at a time”jrefStep gives you the member of a target at a key, which is a property name
or an array index. Like a selector, it follows a reference to get there:
import { jrefStep, jrefValue } from "@hyperjump/browser";
const homeworld = await jrefStep(session, "homeworld", luke);const name = await jrefStep(session, "name", homeworld);await jrefValue(session, name); // "Tatooine"jrefValue gives you the value of a string, number, boolean, or null as plain
JavaScript. It throws an error whose cause.code is "ERR_STRUCTURED_VALUE"
for an object or an array, because their values could be in other documents.
Step into those instead. jrefJsonType gives you the kind of JSON value a
target is, such as "string" or "object", so you know which to do.
jrefArrayIter, jrefObjectValues, and jrefObjectEntries are async iterators
over the members of an array or an object. The Hyperjump session follows each
member when the loop reaches it, so a loop that stops early retrieves less:
import { jrefArrayIter, jrefJsonType, jrefObjectEntries } from "@hyperjump/browser";
const films = await jrefStep(session, "films", luke);for await (const film of jrefArrayIter(session, films)) { console.log(await jrefValue(session, await jrefStep(session, "title", film)));}
for await (const [key, value] of jrefObjectEntries(session, luke)) { const jsonType = await jrefJsonType(session, value); if (jsonType === "object" || jsonType === "array") { console.log(key, jsonType); } else { console.log(key, await jrefValue(session, value)); }}jrefObjectKeys gives you an object’s property names as an async iterator, and
jrefObjectHas says whether it has one. Neither follows the members, because
reading a name doesn’t need them.
Use these functions when your code decides what to step into and builds a
result from what comes back, like a function that turns a document into
something else one property at a time. To reach a value by a path, a selector
is shorter. To do something at every value, use jrefVisit.
Walk a document
Section titled “Walk a document”jrefVisit, jrefFind, jrefFindAll, jrefSelect, and jrefSelectAll walk
a document. A document is a unist tree,
the kind of syntax tree that the unified ecosystem
uses for Markdown and HTML, and each of its values is a node. The walks are the
unist utilities unist-util-visit and unist-util-select for a tree with its
references followed, so if you know those, you know how these work.
You don’t read a node yourself, but tests and selectors match a value by the properties of its node:
| Property | Description |
|---|---|
type |
"json" for a JSON or JRef value, or "reference" for a reference that a walk with reference: "manual" reaches. A media type can have types of its own. |
jsonType |
The kind of JSON value: "object", "array", "string", "number", "boolean", or "null" |
value |
The value of a string, number, boolean, or null |
For more information about the trees, see Parse JSON and JRef.
Visit every value
Section titled “Visit every value”jrefVisit walks a target and every value under it depth first in document
order, following references along the way. Its visitor returns the same
CONTINUE, SKIP, and EXIT values as unist-util-visit’s.
A walk follows every reference under the target, and on the Star Wars API everything under Luke is the whole API, because his films refer to their characters and planets, and those refer to more. Walks are for documents whose references don’t lead that far, like this team, where people refer to each other:
{ "lead": { "$ref": "#/people/0" }, "people": [ { "name": "Grace", "manager": { "$ref": "#/people/0" } } ]}The file isn’t on the Star Wars API, so this Hyperjump session has the default
allowRetrieval, which allows the files in the working directory. The visitor
gets each value’s target with the key it’s at, the target that has it, and its
depth below the target you started from. This prints an outline of the team
without going into anyone’s manager:
import { CONTINUE, jrefVisit, SKIP } from "@hyperjump/browser";
const files = new Hyperjump();const team = await browse(files, "./team.jref");await jrefVisit(files, team, (target, key, parent, depth) => { console.log(`${" ".repeat(depth)}${key ?? "team"}`); return key === "manager" ? SKIP : CONTINUE;});team lead name email people 0 name email 1 name email managerThe session follows a reference just before the visitor gets its value, so
returning SKIP keeps the session from retrieving the documents under that
value. That’s also how you stop at a depth: return SKIP when depth is as
deep as you want to go. If a reference leads back to a value that the walk is
inside, like a recursive definition, the visitor gets that value but not the
values inside it again, so the walk ends.
To visit only some values, put a test before the visitor like you would with
unist-util-visit. A string matches a node’s type, an object matches nodes
with the same properties, a function gets the target and matches the ones it
returns true for, and an array matches what any test in it matches. In
TypeScript, a test narrows the visitor’s target to what can match it. A function
test gets the same target, key, and parent as the visitor, so this prints every
name:
const isName = (target: unknown, key?: string) => key === "name";
await jrefVisit(files, team, isName, async (target) => { console.log(await jrefValue(files, target));});AdaAdaGraceAdaThe visitor gets Ada’s name each time the walk reaches her, through lead,
people, and Grace’s manager. The walk still goes through the values
that don’t match and follows their references to find what’s under them.
Find values
Section titled “Find values”jrefFind gives you the first value under a target that passes a test, or
undefined if none does. jrefFindAll gives you every value that passes. They
take the same tests as jrefVisit and look in the same order it visits, so
they follow references along the way. They’re for searching a document when
you don’t know where the values are. This finds every email in the team:
import { jrefFindAll } from "@hyperjump/browser";
const emails = await jrefFindAll(files, team, (target, key) => key === "email");for (const email of emails) { console.log(await jrefValue(files, email));}A visit gets Ada’s email three times, but jrefFindAll gives you each value
once, even if more than one reference leads to it. jrefFind stops at the first value that passes, so the Hyperjump session
doesn’t retrieve anything after it. To reach values by their path, use a
selector.
Select values
Section titled “Select values”jrefSelect and jrefSelectAll find values with a selector like select and
selectAll from unist-util-select do, following references along the way.
jrefSelect gives you the first value that matches, or undefined if none
does. jrefSelectAll gives you all of them in the order it reaches them.
import { jrefSelect, jrefSelectAll } from "@hyperjump/browser";
const film = await browse(session, "https://swapi.hyperjump.io/api/films/1");
const director = await jrefSelect(session, "> [key=director]", film);const names = await jrefSelectAll( session, "> [key=characters] > * > [key=name]", film);Each character is a reference to another document. The second selector steps into each one and gets its name.
| Selector | Matches |
|---|---|
[key=name] |
The value of the property name, or the item at index name of an array, such as [key=0] |
[property=value] |
A value whose property has that value, such as [value="George Lucas"]. They’re compared as text, so [value=42] matches 42 and "42". |
[value] |
A value that has the property. Strings, numbers, booleans, and null have a value. |
json or * |
A value whose type is json, or any value |
:root or :scope |
The value you start from |
a b |
A b anywhere under an a |
a > b |
A b directly in an a |
> b |
A b directly in the value you start from |
a, b |
An a or a b |
Quote a value that has characters other than letters, digits, _, -, and
$, such as [key="first name"]. A selector that isn’t one of these, such as
:has() or a + b, throws a SyntaxError that says what’s supported.
TypeScript knows what kind of value a selector selects from a
[jsonType=...] in its last part, after its last > or space.
> [key=director][jsonType=string] gives you a target for a string, so
jrefValue gives you a string. Without one, jrefValue gives you a
string | number | boolean | null.
const director = await jrefSelect( session, "> [key=director][jsonType=string]", film);if (director) { await jrefValue(session, director); // "George Lucas"}The Hyperjump session only follows a reference if the selector could match the
value it leads to or something inside it. > [key=director] doesn’t retrieve
any characters because none of them can be the film’s director, and
jrefSelect stops at the first match. A selector without > like [key=name]
can match at any depth, so it follows every reference under the value you start
from. On an API like this one that could be the whole API, so start a selector
with > unless you mean to search everything.
A selector follows the references it reaches one at a time. To load the documents it needs in parallel, see Load references in parallel.
How deep a walk goes
Section titled “How deep a walk goes”jrefVisit, jrefFind, jrefFindAll, jrefSelect, and jrefSelectAll can’t
go more than 1000 levels below the value you start from. If one would, it
throws an error whose cause.code is "ERR_MAX_DEPTH", so references that lead
to new documents without end, like a next link on every page of results,
can’t keep it going.
The error’s url is the value it would go inside. If you expect a walk to go
that deep, pass a bigger maxDepth or Infinity as the last argument:
await jrefVisit(session, target, visitor, { maxDepth: 2000 });It’s only an error if the walk would actually go deeper. A value at the limit is fine if the walk skips it, it has nothing inside it, or nothing inside it can match.
The limit is a safeguard, so to stop at a depth on purpose, say so in the walk.
A visitor returns SKIP at the depth it gets as its fourth argument:
await jrefVisit(session, firstPage, (target, key, parent, depth) => { // The first page and the next two return depth === 2 ? SKIP : CONTINUE;});A selector made of > steps only goes as deep as it’s written, like
> [key=next] > [key=next] for the next two pages.
Stop a walk
Section titled “Stop a walk”jrefVisit goes inside a value each time a reference leads to it, so a visit
costs as much as the document would if you replaced every reference with what it
leads to. A document of a few kilobytes whose values each refer to the next one
twice is too big to visit that way, so jrefVisit stops if it visits values
again too many times. It throws an error whose cause.code is
"ERR_MAX_REVISITS", and the error’s url is the value it would visit.
A value that many references lead to is fine however many there are, because
the visit reaches each of those references first. It’s only an error once the
visit has visited values again more than 250,000 times in all, and more than
100 times for each value it has reached. That takes values inside values that
are used over and over, like the levels of that document. If you expect a visit
to do that, pass a bigger maxRevisits or Infinity:
await jrefVisit(session, target, visitor, { maxRevisits: 1_000_000 });A visit with reference: "manual" reads the tree as it’s written, which has
each value once, so it never throws this error.
To give up on a walk for another reason, like taking too long, pass a signal.
This one gives up after a second:
await jrefVisit(session, target, visitor, { signal: AbortSignal.timeout(1000) });When the signal is aborted, the walk rejects with the signal’s reason at the
next value it reaches. The walk lets other tasks run every so often, so a timer
or a request to cancel can stop it even when the Hyperjump session already has
every document it reaches. A document the walk is waiting for isn’t aborted,
because another walk might need it too.
jrefFind, jrefFindAll, jrefSelect, and jrefSelectAll go inside each
value only once, so they don’t take maxRevisits, but they take a signal too.
To visit each value once, skip the ones you’ve already visited:
const visited = new Set();await jrefVisit(session, target, (target) => { if (visited.has(target.node)) { return SKIP; } visited.add(target.node); // ...});The visitor still gets a value it skips, with the key it’s at this time.
Functions
Section titled “Functions”Each target can also be a document, which starts at its root. A target that’s
a reference starts at what it leads to, unless the options have
reference: "manual".
| Function | Description |
|---|---|
jrefStep(session, key, target, options) |
The member at a property name or an array index |
jrefValue(session, target, options) |
The value of a string, number, boolean, or null as JavaScript |
jrefFollow(session, target) |
What a reference leads to, or the target if it isn’t a reference. For more information, see Follow a reference. |
jrefIsReference(target) |
Whether the target is a reference. Only a target from reference: "manual" can be. |
jrefHref(target) |
The URL a reference refers to. It throws a TypeError if the target isn’t a reference. |
jrefLocation(target) |
The URL that identifies the target’s value. For a reference, the URL is where the reference is. |
jrefJsonType(session, target, options) |
The kind of JSON value: "object", "array", "string", "number", "boolean", or "null" |
jrefArrayIter(session, target, options) |
The items of an array, as an async iterator |
jrefObjectValues(session, target, options) |
The values of an object’s properties, as an async iterator |
jrefObjectEntries(session, target, options) |
An object’s property names and values, as an async iterator |
jrefObjectKeys(session, target, options) |
An object’s property names, as an async iterator |
jrefObjectHas(session, key, target, options) |
Whether an object has a property |
jrefVisit(session, target, test, visitor, options) |
Visits the target and every value under it. The test is optional. |
jrefFind(session, target, test, options) |
The first value that passes the test, or undefined |
jrefFindAll(session, target, test, options) |
Every value that passes the test |
jrefSelect(session, selector, target, options) |
The first value that matches the selector, or undefined |
jrefSelectAll(session, selector, target, options) |
Every value that matches the selector |
| Option | Description |
|---|---|
reference |
"follow", the default, follows references. "manual" reads the tree as it’s written. For more information, see Follow references yourself. |
maxDepth |
How many levels below the target a walk can go. The default is 1000. Only jrefVisit, jrefFind, jrefFindAll, jrefSelect, and jrefSelectAll take it. For more information, see How deep a walk goes. |
maxRevisits |
How many times in all a visit can visit values again, unless it has reached more than a hundredth that many values. The default is 250,000. Only jrefVisit takes it. For more information, see Stop a walk. |
signal |
An AbortSignal that stops a walk. Only jrefVisit, jrefFind, jrefFindAll, jrefSelect, and jrefSelectAll take it. For more information, see Stop a walk. |
When these functions follow a reference, they throw what browse throws. For
more information, see Browse to a URL. For the errors of
their own, see Errors.