Browse to a URL
browse retrieves a document through a Hyperjump session and gives you a target
for the value its URL identifies. A document can refer to values in other
documents, and you don’t follow those references yourself. In a web browser, you
click a link, and the browser resolves its URL, requests it, and shows you the
page it leads to. In a Hyperjump session, you navigate to a reference, and
browse resolves its URL, retrieves the document it leads to, and gives you the
value it refers to.
Luke’s document at https://swapi.hyperjump.io/api/people/1 has his homeworld
as a reference to the planet’s document. Here’s that part of it:
{ "name": "Luke Skywalker", "homeworld": { "$ref": "/api/planets/1" }}When you browse to his homeworld, browse follows the reference, so the name
you select is the planet’s, not Luke’s:
import { Hyperjump, browse, jrefSelect, jrefValue } from "@hyperjump/browser";
const session = new Hyperjump({ allowRetrieval: ["https://swapi.hyperjump.io/"]});
const url = "https://swapi.hyperjump.io/api/people/1#/homeworld";const homeworld = await browse(session, url);const name = await jrefSelect(session, "> [key=name]", homeworld);if (name) { console.log(await jrefValue(session, name)); // Tatooine}You pass a target to the jref functions, which read its value and step into
it. A target knows which document its value is in, so when a jref function
follows a reference under it, the request comes from that document. For more
information, see Read values.
browse resolves a relative URL the way a web browser does. In a browser,
that’s against the page. In Node.js, it’s against the working directory, so
browse(session, "data/film.json") reads a file. With referencedFrom, a
relative URL resolves against the URL of the document that you’re following
the reference from, the way the reference does.
What a URL identifies
Section titled “What a URL identifies”Without a fragment, a URL identifies the root of its document. What a fragment
identifies depends on the document’s media type, which the document says with
its anchors. For more information, see Media types.
| Media type | A fragment identifies |
|---|---|
JRef, which is application/reference+json and .jref files |
The value at that JSON Pointer |
JSON, which is application/json and .json files |
The whole document, because JSON doesn’t define fragments |
In JRef, a fragment is a JSON Pointer to a value in the document:
const homeworld = await browse( session, "https://swapi.hyperjump.io/api/people/1#/homeworld");The pointer applies to the document as it’s written, so it doesn’t follow
references. #/homeworld works because the reference is the last thing the
pointer reaches. browse follows that reference and gives you the homeworld.
#/homeworld/name doesn’t work because the pointer can’t go through the
reference. It looks for name in Luke’s document, which doesn’t have one. To
get the name, get the homeworld first. Then select its name. For more
information, see Read values.
References
Section titled “References”A JRef document is JSON with references such as { "$ref": "../people/1" }.
When the value a URL identifies is a reference, browse retrieves what it refers
to, and it keeps going until it reaches a value that isn’t a reference. The
target is for that value, which can be in another document than the URL’s. In a
JSON document, an object with a $ref property is an ordinary object.
A document can refer to anything, so a Hyperjump session only retrieves the URLs
its allowRetrieval allows, and only a file can refer to a file. For more
information, see What a session can fetch.
A reference as it’s written
Section titled “A reference as it’s written”browse follows a reference unless you tell it not to. With
reference: "manual", it gives you the target the URL identifies as it’s
written, even when it’s a reference. It works like fetch’s
redirect: "manual" option, which gives you a redirect instead of following
it.
The option is only for that call. A jref function that you give the target
follows the reference unless you give it reference: "manual" too:
const url = "https://swapi.hyperjump.io/api/people/1#/homeworld";const homeworld = await browse(session, url, { reference: "manual" });
const ref = await jrefSelect( session, ":scope[type=reference] > [key=$ref]", homeworld, { reference: "manual" });if (ref) { console.log(await jrefValue(session, ref)); // /api/planets/1}
const name = await jrefSelect(session, "> [key=name]", homeworld);if (name) { console.log(await jrefValue(session, name)); // Tatooine}:scope[type=reference] matches only if the target is a reference, so the
first jrefSelect finds the $ref as it’s written in Luke’s document. The
second follows the reference and finds the planet’s name. For more ways to
work with references as they’re written, see
Follow references yourself.
A session keeps its documents
Section titled “A session keeps its documents”A Hyperjump session keeps every document it retrieves, so it fetches and parses each one once, however many references lead to it. Two calls for the same document get the same object, even when the second call comes before the first one finishes. To see a document that changed, create a new session.
The session also keeps a document under the URL its response came from, so a
URL that redirects and the URL it redirects to give you the same document. If a
redirect’s Location has a fragment, browse gives you the value it
identifies, instead of the one your URL’s fragment does, as fetch does.
Priority
Section titled “Priority”browse takes a priority, which works like fetchpriority in a browser. The references that browse follows have the same priority:
await browse(session, url, { priority: "low" });If you ask for a document again while the Hyperjump session is still retrieving
it, its request gets the more urgent of the two priorities. That way an app can
load documents ahead of time at "low" without holding up a document that it
needs now. For more information, see Priorities.
Options
Section titled “Options”browse(session, url, options) takes these options:
| Option | Description |
|---|---|
priority |
"high", "auto", or "low", or a PriorityController’s signal. The references that browse follows have it too. For more information, see Priority. |
reference |
"follow", the default, follows a reference to the value it leads to. "manual" gives you the target as it’s written. For more information, see A reference as it’s written. |
referencedFrom |
The target or the document that has the reference you’re following. browse finds a document that it contains without retrieving it. For more information, see Read a tree you parsed. |
initiator |
The response of the request that caused this one, or its record. Only a file: document can refer to a file: URL. For more information, see File URLs. |
Errors
Section titled “Errors”browse rejects with whatever kept it from giving you a value:
| Error | When |
|---|---|
| A network error | The session can’t fetch the URL. For more information, see Errors. |
An Error whose cause.code is "ERR_HTTP_STATUS" |
The response’s status isn’t a success. The cause.status is the status. |
An Error whose cause.code is "ERR_UNSUPPORTED_MEDIA_TYPE" |
No media type parses the response. For more information, see Media types. |
A SyntaxError whose cause.code is "ERR_SYNTAX" |
The document has a syntax error, or a reference that’s an absolute file: URL. Its cause also has the error’s ruleId and place. |
An Error whose cause.code is "ERR_ABSOLUTE_FILE_URL" |
A document that isn’t a file says it contains a document with a file: URL, or that its own URL is one. For more information, see Media types. |
An Error whose cause.code is "ERR_ANCHOR_NOT_FOUND" |
The fragment isn’t an anchor of the document or a JSON Pointer. The cause.anchor is the fragment. |
An Error whose cause.code starts with "ERR_POINTER_" |
The fragment doesn’t identify a value. For more information, see Parse JSON and JRef. |
An Error whose cause.code is "ERR_REFERENCE_CYCLE" |
Following references leads back to a reference that browse already followed. The cause.chain lists the URLs. |
An Error whose cause.code is "ERR_TOO_MANY_REFERENCES" |
browse would follow more than 20 references in a row, each of which can lead to another document, so a document can’t make the Hyperjump session retrieve documents without end. To change the limit, use the session’s maxReferences option. The cause.chain lists the URLs. |
Every one of these errors has the URL that failed as its url:
try { await browse(session, "https://swapi.hyperjump.io/api/films/99");} catch (error) { const { cause, url } = error as { cause?: { code?: string; status?: number }; url?: string; }; if (cause?.code === "ERR_HTTP_STATUS" && cause.status === 404) { // There's nothing at `url` }}