Security News
tea.xyz Spam Plagues npm and RubyGems Package Registries
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
@hyperjump/browser
Advanced tools
Readme
The Hyperjump Browser is a generic client for traversing JSON Reference (JRef) and other JRef-compatible media types in a way that abstracts the references without loosing information.
This module is designed for node.js (ES Modules, TypeScript) and browsers. It should work in Bun and Deno as well, but the test runner doesn't work in these environments, so this module may be less stable in those environments.
npm install @hyperjump/browser
This example uses the API at https://swapi.hyperjump.io. It's a variation of the Star Wars API (SWAPI) implemented using the JRef media type.
import { get, step, value, iter } from "@hyperjump/browser";
const aNewHope = await get("https://swapi.hyperjump.io/api/films/1");
const characters = await get("#/characters", aNewHope); // Or
const characters = await step("characters", aNewHope);
for await (const character of iter(characters)) {
const name = await step("name", character);
value(name); // => Luke Skywalker, etc.
}
You can also work with files on the file system. When working with files, media
types are determined by file extensions. The JRef media type uses the .jref
extension.
import { get, value } from "@hyperjump/browser";
const lukeSkywalker = await get("./api/people/1.jref"); // Paths resolve relative to the current working directory
const name = await step("name", lukeSkywalker);
value(name); // => Luke Skywalker
get(uri: string, browser?: Browser): Promise<Browser>
Retrieve a document located at the given URI. Support for JRef is built
in. See the Media Types section for information on how
to support other media types. Support for http(s):
and file:
URI schemes
are built in. See the Uri Schemes section for information on
how to support other URI schemes.
value(browser: Browser) => JRef
Get the JRef compatible value the document represents.
typeOf(browser: Browser) => JRefType
Works the same as the typeof
keyword. It will return one of the JSON types
(null, boolean, number, string, array, object) or "reference". If the value
is not one of these types, it will throw an error.
has(key: string, browser: Browser) => boolean
Returns whether or not a property is present in the object that the browser represents.
length(browser: Browser) => number
Get the length of the array that the browser represents.
step(key: string | number, browser: Browser) => Promise<Browser>
Move the browser cursor by the given "key" value. This is analogous to
indexing into an object or array (foo[key]
). This function supports
curried application.
iter(browser: Browser) => AsyncGenerator<Browser>
Iterate over the items in the array that the document represents.
entries(browser: Browser) => AsyncGenerator<[string, Browser]>
Similar to Object.entries
, but yields Browsers for values.
values(browser: Browser) => AsyncGenerator<Browser>
Similar to Object.values
, but yields Browsers for values.
keys(browser: Browser) => Generator<string>
Similar to Object.keys
.
Support for the JRef media type is included by default, but you can add support for any media type you like as long as it can be represented in a JRef-compatible way.
import { addMediaTypePlugin, removeMediaTypePlugin, setMediaTypeQuality } from "@hyperjump/browser";
import YAML from "yaml";
// Add support for YAML version of JRef (YRef)
addMediaTypePlugin("application/reference+yaml", {
parse: async (response) => {
return {
baseUri: response.url,
root: (response) => YAML.parse(await response.text(), (key, value) => {
return value !== null && typeof value.$ref === "string"
? new Reference(value.$ref)
: value;
},
anchorLocation: (fragment) => decodeUri(fragment ?? "");
};
},
fileMatcher: (path) => path.endsWith(".jref")
});
// Prefer "YRef" over JRef by reducing the quality for JRef.
setMediaTypeQuality("application/reference+json", 0.9);
// Only support YRef by removing JRef support.
removeMediaTypePlugin("application/reference+json");
addMediaTypePlugin(contentType: string, plugin: MediaTypePlugin): void
Add support for additional media types.
1
)removeMediaTypePlugin(contentType: string): void
Removed support or a media type.
setMediaTypeQuality(contentType: string, quality: number): void;
Set the quality that will be used in the Accept header of requests to indicate to servers what media types are preferred over others.
acceptableMediaTypes(): string;
Build an Accept
request header from the registered media type plugins.
This function is used internally. You would only need it if you're writing a
custom http(s):
URI scheme plugin.
By default, http(s):
and file:
URIs are supported. You can add support for
additional URI schemes using plugins.
import { addUriSchemePlugin, removeUriSchemePlugin, retrieve } from "@hyperjump/browser";
// Add support for the `urn:` scheme
addUriSchemePlugin("urn", {
parse: (urn, baseUri) => {
let { nid, nss, query, fragment } = parseUrn(urn);
nid = nid.toLowerCase();
if (!mappings[nid]?.[nss]) {
throw Error(`Not Found -- ${urn}`);
}
let uri = mappings[nid][nss];
uri += query ? "?" + query : "";
uri += fragment ? "#" + fragment : "";
return retrieve(uri, baseUri);
}
});
// Only support `urn:` by removing default plugins
removeUriSchemePlugin("http");
removeUriSchemePlugin("https");
removeUriSchemePlugin("file");
addUriSchemePlugin(scheme: string, plugin: UriSchemePlugin): void
Add support for additional URI schemes.
removeUriSchemePlugin(scheme: string): void
Remove support for a URI scheme.
retrieve(uri: string, baseUri?: string) => Promise<Response>
This is used internally, but you may need it if mapping names to locators such as in the example above.
parse
and stringify
JRef values using the same API as the JSON
built-in
functions including reviver
and replacer
functions.
import { parse, stringify, jrefTypeOf } from "@hyperjump/browser/jref";
const blogPostJref = `{
"title": "Working with JRef",
"author": { "$ref": "/author/jdesrosiers" },
"content": "lorem ipsum dolor sit amet",
}`;
const blogPost = parse(blogPostJref);
jrefTypeOf(blogPost.author) // => "reference"
blogPost.author.href; // => "/author/jdesrosiers"
stringify(blogPost, null, " ") === blogPostJref // => true
export type Replacer = (key: string, value: unknown) => unknown;
parse: (jref: string, reviver?: (key: string, value: unknown) => unknown) => JRef;
Same as JSON.parse
, but converts { "$ref": "..." }
to Reference
objects.
stringify: (value: JRef, replacer?: (string | number)[] | null | Replacer, space?: string | number) => string;
Same as JSON.stringify
, but converts Reference
objects to { "$ref": "... " }
jrefTypeOf: (value: unknown) => "object" | "array" | "string" | "number" | "boolean" | "null" | "reference" | "undefined";
Run the tests
npm test
Run the tests with a continuous test runner
npm test -- --watch
FAQs
Browse JSON-compatible data with hypermedia references
The npm package @hyperjump/browser receives a total of 1,819 weekly downloads. As such, @hyperjump/browser popularity was classified as popular.
We found that @hyperjump/browser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.