{"id":14156341,"url":"https://github.com/hyperjump-io/browser","last_synced_at":"2026-01-16T06:11:14.965Z","repository":{"id":57117011,"uuid":"140375706","full_name":"hyperjump-io/browser","owner":"hyperjump-io","description":"A generic hypermedia client for JSON Reference","archived":false,"fork":false,"pushed_at":"2025-06-10T19:09:32.000Z","size":291,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-11-23T07:22:55.976Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperjump-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["hyperjump-io"]}},"created_at":"2018-07-10T04:09:17.000Z","updated_at":"2025-06-10T19:09:25.000Z","dependencies_parsed_at":"2024-01-05T13:43:23.060Z","dependency_job_id":"90b13b04-d7c3-4946-b359-42019f7c64c9","html_url":"https://github.com/hyperjump-io/browser","commit_stats":null,"previous_names":["jdesrosiers/json-reference","jdesrosiers/hyperjump-browser"],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/hyperjump-io/browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fbrowser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fbrowser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fbrowser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fbrowser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperjump-io","download_url":"https://codeload.github.com/hyperjump-io/browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperjump-io%2Fbrowser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-17T08:05:23.490Z","updated_at":"2026-01-16T06:11:14.944Z","avatar_url":"https://github.com/hyperjump-io.png","language":"TypeScript","funding_links":["https://github.com/sponsors/hyperjump-io"],"categories":["others"],"sub_categories":[],"readme":"# Hyperjump - Browser\n\nThe Hyperjump Browser is a generic client for traversing JSON Reference ([JRef])\nand other [JRef]-compatible media types in a way that abstracts the references\nwithout loosing information.\n\n## Install\n\nThis module is designed for node.js (ES Modules, TypeScript) and browsers. It\nshould work in Bun and Deno as well, but the test runner doesn't work in these\nenvironments, so this module may be less stable in those environments.\n\n### Node.js\n\n```bash\nnpm install @hyperjump/browser\n```\n\n## JRef Browser\n\nThis example uses the API at\n[https://swapi.hyperjump.io](https://explore.hyperjump.io#https://swapi.hyperjump.io/api/films/1).\nIt's a variation of the [Star Wars API (SWAPI)](https://swapi.dev) implemented\nusing the [JRef] media type.\n\n```javascript\nimport { get, step, value, iter } from \"@hyperjump/browser\";\n\nconst aNewHope = await get(\"https://swapi.hyperjump.io/api/films/1\");\nconst characters = await get(\"#/characters\", aNewHope); // Or\nconst characters = await step(\"characters\", aNewHope);\n\nfor await (const character of iter(characters)) {\n  const name = await step(\"name\", character);\n  value(name); // =\u003e Luke Skywalker, etc.\n}\n```\n\nYou can also work with files on the file system. When working with files, media\ntypes are determined by file extensions. The [JRef] media type uses the `.jref`\nextension.\n\n```javascript\nimport { get, value } from \"@hyperjump/browser\";\n\nconst lukeSkywalker = await get(\"./api/people/1.jref\"); // Paths resolve relative to the current working directory\nconst name = await step(\"name\", lukeSkywalker);\nvalue(name); // =\u003e Luke Skywalker\n```\n\n### API\n\n* get(uri: string, browser?: Browser): Promise\\\u003cBrowser\u003e\n\n    Retrieve a document located at the given URI. Support for [JRef] is built\n    in. See the [Media Types](#media-type) section for information on how\n    to support other media types. Support for `http(s):` and `file:` URI schemes\n    are built in. See the [Uri Schemes](#uri-schemes) section for information on\n    how to support other URI schemes.\n* value(browser: Browser) =\u003e JRef\n\n    Get the JRef compatible value the document represents.\n* typeOf(browser: Browser) =\u003e JRefType\n\n    Works the same as the `typeof` keyword. It will return one of the JSON types\n    (null, boolean, number, string, array, object) or \"reference\". If the value\n    is not one of these types, it will throw an error.\n* has(key: string, browser: Browser) =\u003e boolean\n\n    Returns whether or not a property is present in the object that the browser\n    represents.\n* length(browser: Browser) =\u003e number\n\n    Get the length of the array that the browser represents.\n* step(key: string | number, browser: Browser) =\u003e Promise\\\u003cBrowser\u003e\n\n    Move the browser cursor by the given \"key\" value. This is analogous to\n    indexing into an object or array (`foo[key]`). This function supports\n    curried application.\n* iter(browser: Browser) =\u003e AsyncGenerator\\\u003cBrowser\u003e\n\n    Iterate over the items in the array that the document represents.\n* entries(browser: Browser) =\u003e AsyncGenerator\\\u003c[string, Browser]\u003e\n\n    Similar to `Object.entries`, but yields Browsers for values.\n* values(browser: Browser) =\u003e AsyncGenerator\\\u003cBrowser\u003e\n\n    Similar to `Object.values`, but yields Browsers for values.\n* keys(browser: Browser) =\u003e Generator\\\u003cstring\u003e\n\n    Similar to `Object.keys`.\n\n## Media Types\n\nSupport for the [JRef] media type is included by default, but you can add\nsupport for any media type you like as long as it can be represented in a\n[JRef]-compatible way.\n\n```javascript\nimport { addMediaTypePlugin, removeMediaTypePlugin, setMediaTypeQuality } from \"@hyperjump/browser\";\nimport YAML from \"yaml\";\n\n// Add support for YAML version of JRef (YRef)\naddMediaTypePlugin(\"application/reference+yaml\", {\n  parse: async (response) =\u003e {\n    return {\n      baseUri: response.url,\n      root: (response) =\u003e YAML.parse(await response.text(), (key, value) =\u003e {\n        return value !== null \u0026\u0026 typeof value.$ref === \"string\"\n          ? new Reference(value.$ref)\n          : value;\n      },\n      anchorLocation: (fragment) =\u003e decodeUri(fragment ?? \"\");\n    };\n  },\n  fileMatcher: (path) =\u003e path.endsWith(\".jref\")\n});\n\n// Prefer \"YRef\" over JRef by reducing the quality for JRef.\nsetMediaTypeQuality(\"application/reference+json\", 0.9);\n\n// Only support YRef by removing JRef support.\nremoveMediaTypePlugin(\"application/reference+json\");\n```\n\n### API\n\n* addMediaTypePlugin(contentType: string, plugin: MediaTypePlugin): void\n\n    Add support for additional media types.\n\n  * type MediaTypePlugin\n    * parse: (response: Response) =\u003e Document\n    * [quality](https://developer.mozilla.org/en-US/docs/Glossary/Quality_values):\n      number (defaults to `1`)\n* removeMediaTypePlugin(contentType: string): void\n\n    Removed support or a media type.\n* setMediaTypeQuality(contentType: string, quality: number): void;\n\n    Set the\n    [quality](https://developer.mozilla.org/en-US/docs/Glossary/Quality_values)\n    that will be used in the\n    [Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept)\n    header of requests to indicate to servers what media types are preferred\n    over others.\n* acceptableMediaTypes(): string;\n\n    Build an `Accept` request header from the registered media type plugins.\n    This function is used internally. You would only need it if you're writing a\n    custom `http(s):` URI scheme plugin.\n\n## URI Schemes\n\nBy default, `http(s):` and `file:` URIs are supported. You can add support for\nadditional URI schemes using plugins.\n\n```javascript\nimport { addUriSchemePlugin, removeUriSchemePlugin, retrieve } from \"@hyperjump/browser\";\n\n// Add support for the `urn:` scheme\naddUriSchemePlugin(\"urn\", {\n  parse: (urn, baseUri) =\u003e {\n    let { nid, nss, query, fragment } = parseUrn(urn);\n    nid = nid.toLowerCase();\n\n    if (!mappings[nid]?.[nss]) {\n      throw Error(`Not Found -- ${urn}`);\n    }\n\n    let uri = mappings[nid][nss];\n    uri += query ? \"?\" + query : \"\";\n    uri += fragment ? \"#\" + fragment : \"\";\n\n    return retrieve(uri, baseUri);\n  }\n});\n\n// Only support `urn:` by removing default plugins\nremoveUriSchemePlugin(\"http\");\nremoveUriSchemePlugin(\"https\");\nremoveUriSchemePlugin(\"file\");\n```\n\n### API\n* addUriSchemePlugin(scheme: string, plugin: UriSchemePlugin): void\n\n    Add support for additional URI schemes.\n\n  * type UriSchemePlugin\n    * retrieve: (uri: string, baseUri?: string) =\u003e Promise\\\u003cResponse\u003e\n* removeUriSchemePlugin(scheme: string): void\n\n    Remove support for a URI scheme.\n* retrieve(uri: string, baseUri?: string) =\u003e Promise\\\u003cResponse\u003e\n\n    This is used internally, but you may need it if mapping names to locators\n    such as in the example above.\n\n## JRef\n\n`parse` and `stringify` [JRef] values using the same API as the `JSON` built-in\nfunctions including `reviver` and `replacer` functions.\n\n```javascript\nimport { parse, stringify, jrefTypeOf } from \"@hyperjump/browser/jref\";\n\nconst blogPostJref = `{\n  \"title\": \"Working with JRef\",\n  \"author\": { \"$ref\": \"/author/jdesrosiers\" },\n  \"content\": \"lorem ipsum dolor sit amet\",\n}`;\nconst blogPost = parse(blogPostJref);\njrefTypeOf(blogPost.author) // =\u003e \"reference\"\nblogPost.author.href; // =\u003e \"/author/jdesrosiers\"\n\nstringify(blogPost, null, \"  \") === blogPostJref // =\u003e true\n```\n\n### API\nexport type Replacer = (key: string, value: unknown) =\u003e unknown;\n\n* parse: (jref: string, reviver?: (key: string, value: unknown) =\u003e unknown) =\u003e JRef;\n\n    Same as `JSON.parse`, but converts `{ \"$ref\": \"...\" }` to `Reference`\n    objects.\n* stringify: (value: JRef, replacer?: (string | number)[] | null | Replacer, space?: string | number) =\u003e string;\n\n    Same as `JSON.stringify`, but converts `Reference` objects to `{ \"$ref\":\n    \"... \" }`\n* jrefTypeOf: (value: unknown) =\u003e \"object\" | \"array\" | \"string\" | \"number\" | \"boolean\" | \"null\" | \"reference\" | \"undefined\";\n\n## Contributing\n\n### Tests\n\nRun the tests\n\n```bash\nnpm test\n```\n\nRun the tests with a continuous test runner\n\n```bash\nnpm test -- --watch\n```\n\n[JRef]: https://github.com/hyperjump-io/browser/blob/main/lib/jref/SPECIFICATION.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperjump-io%2Fbrowser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperjump-io%2Fbrowser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperjump-io%2Fbrowser/lists"}