Socket
Socket
Sign inDemoInstall

@hyperjump/browser

Package Overview
Dependencies
Maintainers
1
Versions
30
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@hyperjump/browser - npm Package Compare versions

Comparing version 0.19.0 to 1.0.0

lib/browser/browser.js
lib/browser/context-uri.browser.js
lib/browser/context-uri.js
lib/index.browser.js
lib/index.d.ts
lib/jref/index.d.ts
lib/jref/index.js
lib/media-types/jref-media-type-plugin.js
lib/media-types/media-types.js
lib/uri-schemes/file-scheme-plugin.js
lib/uri-schemes/http-scheme-plugin.js
lib/uri-schemes/uri-schemes.js
LICENCE

38

lib/index.js

@@ -1,9 +0,35 @@

const Hyperjump = require("./core");
const JRef = require("./json-reference/core");
const Json = require("./json/core");
import { addMediaTypePlugin } from "./media-types/media-types.js";
import { jrefMediaTypePlugin } from "./media-types/jref-media-type-plugin.js";
import { addUriSchemePlugin } from "./uri-schemes/uri-schemes.js";
import { httpSchemePlugin } from "./uri-schemes/http-scheme-plugin.js";
import { fileSchemePlugin } from "./uri-schemes/file-scheme-plugin.js";
Hyperjump.addContentType("application/reference+json", JRef);
Hyperjump.addContentType("application/json", Json);
addMediaTypePlugin("application/reference+json", jrefMediaTypePlugin);
module.exports = Hyperjump;
addUriSchemePlugin("http", httpSchemePlugin);
addUriSchemePlugin("https", httpSchemePlugin);
addUriSchemePlugin("file", fileSchemePlugin);
export {
get,
value,
step,
iter,
keys,
values,
entries,
RetrievalError
} from "./browser/browser.js";
export {
addMediaTypePlugin,
removeMediaTypePlugin,
setMediaTypeQuality
} from "./media-types/media-types.js";
export {
addUriSchemePlugin,
removeUriSchemePlugin,
retrieve
} from "./uri-schemes/uri-schemes.js";

72

package.json
{
"name": "@hyperjump/browser",
"version": "0.19.0",
"description": "A generic hypermedia client",
"main": "lib/index.js",
"version": "1.0.0",
"description": "Browse JSON-compatible data with hypermedia references",
"type": "module",
"main": "./lib/index.js",
"exports": {
".": "./lib/index.js",
"./jref": "./lib/jref/index.js"
},
"browser": {
"./lib/fetch.js": "./lib/fetch.browser.js"
"./lib/index.js": "./lib/index.browser.js",
"./lib/browser/context-uri.js": "./lib/browser/context-uri.browser.js"
},
"scripts": {
"clean": "xargs -a .gitignore rm -rf",
"lint": "eslint .",
"test": "mocha 'lib/**/*.spec.js'"
"lint": "eslint lib",
"test": "mocha 'lib/**/*.spec.ts'"
},
"repository": "github:jdesrosiers/hyperjump-browser",
"repository": {
"type": "git",
"url": "git+https://github.com/hyperjump-io/browser.git"
},
"keywords": [
"Hyperjump",
"JSON Reference",
"JRef",
"hypermedia",
"generic client"
"json",
"reference",
"jref",
"hypermedia"
],
"author": "Jason Desrosiers <jdesrosi@gmail.com>",
"license": "MIT",
"funding": {
"type": "github",
"url": "https://github.com/sponsors/jdesrosiers"
},
"devDependencies": {
"chai": "^4.2.0",
"eslint": "^4.19.1",
"eslint-import-resolver-node": "^0.3.2",
"eslint-plugin-import": "^2.18.0",
"mocha": "^5.2.0",
"nock": "^9.6.1",
"rollup": "^1.17.0",
"rollup-plugin-commonjs": "^10.0.1",
"rollup-plugin-node-resolve": "^5.2.0",
"rollup-plugin-terser": "^5.1.1"
"@types/chai": "*",
"@types/mocha": "*",
"@typescript-eslint/eslint-plugin": "*",
"@typescript-eslint/parser": "*",
"chai": "*",
"eslint": "*",
"eslint-import-resolver-node": "*",
"eslint-import-resolver-typescript": "*",
"eslint-plugin-import": "*",
"mocha": "*",
"ts-node": "*",
"typescript": "*",
"yaml": "*"
},
"engines": {
"node": ">=18.0.0"
},
"dependencies": {
"@hyperjump/json-pointer": "^0.3.1",
"content-type": "^1.0.4",
"just-curry-it": "^3.1.0",
"make-fetch-happen": "^4.0.2",
"url-resolve-browser": "^1.1.0"
"@hyperjump/json-pointer": "^1.0.1",
"@hyperjump/uri": "^1.2.0",
"content-type": "^1.0.5",
"just-curry-it": "^5.3.0",
"undici": "^5.23.0"
}
}

284

README.md

@@ -1,153 +0,233 @@

# Hyperjump Browser
# Hyperjump - Browser
The Hyperjump browser is an experimental generic hypermedia client. It aims to
provide a uniform interface for working with hypermedia enabled media types.
When you use a web browser, you don't interact with HTML, you interact with the
UI that the HTML represents. The Hyperjump browser aims to do the same except
with data. It abstracts away the hypermedia so you can work data as if it's just
plain JSON data without having to leave the browser.
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.
The Hyperjump browser allows you to plug in support for different media types,
but it comes with support for and was initially designed for [JSON Reference][jref]
(JRef). The Hyperjump browser also has support for JSON, but you won't get
support for the interesting things the browser supports.
## Install
## Installation
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.
### Node.js
```bash
npm install @hyperjump/browser --save
npm install @hyperjump/browser
```
## Contributing
### Browser
### Tests
When in a browser context, this library is designed to use the browser's `fetch`
implementation instead of a node.js fetch clone. The Webpack bundler does this
properly without any extra configuration, but if you are using the Rollup
bundler you will need to include the `browser: true` option in your Rollup
configuration.
Run the tests
```bash
npm test
```javascript
plugins: [
resolve({
browser: true
})
]
```
Run the tests with a continuous test runner
## JRef Browser
```bash
npm test -- --watch
This example uses the API at
[https://swapi.hyperjump.io](https://explore.hyperjump.io#https://swapi.hyperjump.io/api/films/1).
It's a variation of the [Star Wars API (SWAPI)](https://swapi.dev) implemented
using the [JRef] media type.
```javascript
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.
}
```
## Bundlers
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.
When using with the [Rollup][rollup] bundler, you will need to include the
`browser: true` config option.
```javascript
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
```
plugins: [
resolve({
browser: true
}),
commonjs()
]
```
## Usage
### API
The following is short demo. See the [API](#api) section below to see all of the
things you can do.
* get(uri: string, document?: Document): Promise\<Document>
This example uses the API at https://swapi.hyperjump.io. It's a variation of the
[Star Wars API (SWAPI)](https://www.swapi.co) implemented using the [JRef][jref]
media type.
Retrieve a document located at the given URI. Support for [JRef] is built
in. See the [Media Types](#media-type) 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](#uri-schemes) section for information on
how to support other URI schemes.
* value(document: Document) => Json
[Hyperjump Pact][pact] is used to apply standard higher-order functions that
work with promises.
Get the JSON compatible value the document represents. Any references will
have been followed so you'll never receive a `Reference` type.
* step(key: string | number, document: Document) => Promise\<Document>
```javascript
const Hyperjump = require("@hyperjump/browser");
const Pact = require("@hyperjump/pact");
Move the document cursor by the given "key" value. This is analogous to
indexing into an object or array (`foo[key]`). This function supports
curried application.
* **Schema.iter**: (document: Document) => AsyncGenerator\<Document>
Iterate over the items in the array that the Document represents.
* **Schema.entries**: (document: Document) => AsyncGenerator\<[string, Document]>
const characterHomeworlds = Pact.map(async (character) => {
const name = await character.name;
const homeworld = await character.homeworld.name;
Similar to `Object.entries`, but yields Documents for values.
* **Schema.values**: (document: Document) => AsyncGenerator\<Document>
return `${name} is from ${homeworld}`;
});
Similar to `Object.values`, but yields Documents for values.
* **Schema.keys**: (document: Document) => Generator\<string>
const ladies = Pact.pipeline([
Pact.filter(async (character) => (await character.gender) === "female"),
Pact.map((character) => character.name)
]);
Similar to `Object.keys`.
const mass = Pact.reduce(async (acc, character) => {
return acc + (parseInt(await character.mass, 10) || 0);
}, 0);
## Media Types
(async function () {
const film = Hyperjump.fetch("https://swapi.hyperjump.io/api/films/1");
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.
await film.title; // --> A New Hope
await characterHomeworlds(film.characters); // --> [ 'Luke Skywalker is from Tatooine',
// --> 'C-3PO is from Tatooine',
// --> 'R2-D2 is from Naboo',
// --> ... ]
await ladies(film.characters); // --> [ 'Leia Organa', 'Beru Whitesun lars' ]
await mass(film.characters); // --> 1290
}());
```javascript
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 {
documentValue: YAML.parse(await response.text(), (key, value) => {
return value !== null && typeof value.$href === "string"
? new Reference(value.$href)
: value;
});
};
}
});
// 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");
```
Except for all the promises, this looks exactly like it might if you were
working with a normal in-memory data structure.
### API
## API
* addMediaTypePlugin(contentType: string, plugin: MediaTypePlugin): void
### nil
`Document`
Add support for additional media types.
The nil document. This is like the blank page you see when you first open your
browser.
* type MediaTypePlugin
* parse: (content: string) => Document
* [quality](https://developer.mozilla.org/en-US/docs/Glossary/Quality_values):
number (defaults to `1`)
* removeMediaTypePlugin(contentType: string): void
### get
`(Url, Document|Promise<Document>, Options?) => Promise<Document>`
Removed support or a media type.
* setMediaTypeQuality(contentType: string, quality: number): void;
Retrieve a document with respect to a context document. Options can be passed to
set custom headers. If the value of the document is a link, it will be followed.
Set the
[quality](https://developer.mozilla.org/en-US/docs/Glossary/Quality_values)
that will be used in the
[Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept)
header of requests to indicate to servers what media types are preferred
over others.
### fetch
`(Url, Options?) => Hyperjump`
## URI Schemes
Retrieve a document. Options can be passed to set custom headers. If the value
of the document is a link, it will be followed.
By default, `http(s):` and `file:` URIs are supported. You can add support for
additional URI schemes using plugins.
### value
`(Document|any) => any`
```javascript
import { addUriSchemePlugin, removeUriSchemePlugin, retrieve } from "@hyperjump/browser";
The value of a document.
// Add support for the `urn:` scheme
addUriSchemePlugin("urn", {
parse: (urn, document) => {
let { nid, nss, query, fragment } = parseUrn(urn);
nid = nid.toLowerCase();
### source
`(Document) => string`
if (!mappings[nid]?.[nss]) {
throw Error(`Not Found -- ${urn}`);
}
The raw source of a document.
let uri = mappings[nid][nss];
uri += query ? "?" + query : "";
uri += fragment ? "#" + fragment : "";
### step
`(string, Document|Promise<Document>, Options) => Promise<Document|any>`
return retrieve(uri, document);
}
});
Step into a document using the key given.
// Only support `urn:` by removing default plugins
removeUriSchemePlugin("http");
removeUriSchemePlugin("https");
removeUriSchemePlugin("file");
```
### construct
`(Url, Headers, string) => Document`
### API
* addUriSchemePlugin(scheme: string, plugin: UriSchemePlugin): void
Construct a document given a URL, headers, and body. For internal use.
Add support for additional URI schemes.
### extend
`(Document, Object) => Document`
* type UriSchemePlugin
* retrieve: (uri: string, document: Document) => Promise\<{ response: Response, fragment: string }>
* removeUriSchemePlugin(scheme: string): void
Modify or add fields to a document. For internal use.
Remove support for a URI scheme.
* retrieve(uri: string, document: Document) => Promise\<{ response: Response, fragment: string }>
### addContentType
`(string, ContentTypeHandler) => void`
This is used internally, but you may need it if mapping names to locators
such as in the example above.
Add support for a new content type. The `ContentTypeHandler` is an object with
three functions: `get`, `value`, and `step`.
## JRef
[jref]: https://github.com/jdesrosiers/hyperjump-browser/blob/master/json-reference/README.md
[pact]: https://github.com/jdesrosiers/hyperjump-pact
[rollup]: https://rollupjs.org
Parse and stringify [JRef] values using the same API as the `JSON` built-in
functions including reviver and replacer functions.
```javascript
import { parse, stringify, Reference } from "@hyperjump/browser/jref";
const blogPostJref = `{
"title": "Working with JRef",
"author": { "$href": "/author/jdesrosiers" },
"content": "lorem ipsum dolor sit amet",
}`;
const blogPost = parse(blogPostJref);
blogPost.author instanceof Reference; // => true
blogPost.author.href; // => "/author/jdesrosiers"
stringify(blogPost, null, " ") === blogPostJref // => true
```
## Contributing
### Tests
Run the tests
```bash
npm test
```
Run the tests with a continuous test runner
```bash
npm test -- --watch
```
[JRef]: https://github.com/hyperjump-io/browser/blob/main/lib/jref/SPECIFICATION.md
lib/common.js
lib/core.js
lib/fetch.browser.js
lib/fetch.js
lib/json-reference/core.js
lib/json-reference/README.md
lib/json/core.js
LICENSE
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc