⚡️ hyper-connect ⚡️

hyper-connect is a client for hyper

---

- Table of Contents
- Install
- NodeJS
- Getting Started
- NodeJS (TypeScript)
- NodeJS (ESM)
- NodeJS (CJS)
- A Note for NodeJS
- Node 18 and localhost
- Deno
- Examples
- How to add a document to hyper data?
- How to get all the documents of type 'movie'?
- How to add a cache key/value pair to hyper cache?
- Documentation
- data
- cache
- search
- storage
- queue
- Verify Signature
- Contributing
- License

Table of Contents

- Install
- Getting Started
- Examples
- Documentation
- Contributing
- License
- Support

---

Install

$3

``sh
npm install hyper-connect
`

hyper-connect constructs a
Request Object and sends it to the hyper
server using fetch. hyper-connect wraps your hyper app's REST API, generating short-lived JWTs
using the provided connection string.

Getting Started

> New Experimental Feature: hyper Queue worker support, see below

$3

`ts
import { connect } from 'hyper-connect'

const hyper = connect(process.env.HYPER as string)

await hyper.data.add({ id: 'game-1', type: 'game', name: 'Donkey Kong' })
await hyper.data.add({ id: 'game-2', type: 'game', name: 'Pac Man' })
await hyper.data.add({ id: 'game-3', type: 'game', name: 'Galaga' })

const results = await hyper.data.query({ type: 'game' })
`

$3

`js
import { connect } from 'hyper-connect'

const hyper = connect(process.env.HYPER)

await hyper.data.add({ id: 'game-1', type: 'game', name: 'Donkey Kong' })
await hyper.data.add({ id: 'game-2', type: 'game', name: 'Pac Man' })
await hyper.data.add({ id: 'game-3', type: 'game', name: 'Galaga' })

const results = await hyper.data.query({ type: 'game' })
`

$3

`js
const { connect } = require('hyper-connect')

const hyper = connect(process.env.HYPER)

await hyper.data.add({ id: 'game-1', type: 'game', name: 'Donkey Kong' })
await hyper.data.add({ id: 'game-2', type: 'game', name: 'Pac Man' })
await hyper.data.add({ id: 'game-3', type: 'game', name: 'Galaga' })

const results = await hyper.data.query({ type: 'game' })
`

$3

For Node environments, starting with v0.5.0, hyper-connect's Storage service api returns a Web
ReadableStream instead of a
NodeJS.ReadableStream. If you'd like a NodeJS.ReadableStream, follow one of the approaches
below.

If you're using node>=17, you can use Node's built in fromWeb to get a Node stream:

`js
import { createReadStream } from 'node:fs'
import { Readable } from 'node:stream'

// Convert the ReadableStream to a NodeJS.ReadableStream
await hyper.storage.download('foo.png')
.then((res) => {
if (!res.ok) throw res
return Readable.fromWeb(res.object)
})

// Or convert to a ReadbleStream from a NodeJS.ReadableStream
await hyper.storage.upload('foo.png', Readable.toWeb(createReadStream('foo.png')))
`

Otherwise, you will need to use v0.4.0 or less of hyper-connect. Node 18 will be in LTS soon,
and we recommend upgrading to Node 18 LTS as soon as possible, to take advantage of the new Web
Standards centric features, like global fetch and WebStreams.

#### Node 18 and localhost

Starting with Node 17, Node has changed how it resolves localhost, when using global fetch and
fetch from libraries like undici. This may cause requests to localhost not to resolve
correctly and fail. To get around this, you can use 127.0.0.1 or 0.0.0.0, in lieu of
localhost. For more info, See this issue

$3

`js
import { connect } from 'https://x.nest.land/hyper-connect@VERSION/deno/mod.ts'

const HYPER = Deno.env.get('HYPER') // connect string: cloud://key:secret@cloud.hyper.io/:app

const hyper = connect(HYPER)()

await hyper.data.add({ id: 'game-1', type: 'game', name: 'Donkey Kong' })
await hyper.data.add({ id: 'game-2', type: 'game', name: 'Pac Man' })
await hyper.data.add({ id: 'game-3', type: 'game', name: 'Galaga' })

const results = await hyper.data.query({ type: 'game' })
`

With hyper-connect, you can access all of the hyper services. hyper-connect uses the fetch library
to execute REST requests for you.

Examples

$3

`js
const doc = {
id: 'movie-1',
type: 'movie',
title: 'Dune',
year: '2021',
}

const result = await hyper.data.add(doc)
console.log(result) // {ok: true, id: "movie-1"}
`

$3

`js
const result = await hyper.data.query({ type: 'movie' })
console.log(result) // {ok: true, docs: [...]}
`

$3

`js
const result = await hyper.cache.add('key', { counter: 1 })
console.log(result) // {ok: true}
`

Documentation

hyper is a suite of service apis, with hyper connect you can specify the api you want to connect
with and the action you want to perform. hyper.[service].[action] - with each service there are a
different set of actions to call. This table breaks down the service and action with description of
the action.

$3

| Service | Action | Description |
| ------- | ------ | ------------------------------------------------------------------- |
| data | add | creates a json document in the hyper data store |
| data | list | lists the documents given a start,stop,limit range |
| data | get | retrieves a document by id |
| data | update | updates a given document by id |
| data | remove | removes a document from the store |
| data | query | queries the store for a set of documents based on selector criteria |
| data | index | creates an index for the data store |
| data | bulk | inserts, updates, and removed document via a batch of documents |

$3

| Service | Action | Description |
| ------- | ------ | ------------------------------------------------------------------- |
| cache | add | creates a json document in the hyper cache store with a key |
| cache | get | retrieves a document by key |
| cache | set | sets a given document by key |
| cache | remove | removes a document from the cache |
| cache | query | queries the cache for a set of documents based on a pattern matcher |

$3

| Service | Action | Description |
| ------- | ------ | ------------------------------------------------- |
| search | add | indexes a json document in the hyper search index |
| search | get | retrieves a document from index |
| search | remove | removes a document from the index |
| search | query | searches index by text |
| search | load | loads a batch of documents |

$3

| Service | Action | Description |
| ------- | -------- | ---------------------------------------- |
| storage | upload | adds object/file to hyper storage bucket |
| storage | download | retrieves a object/file from bucket |
| storage | remove | removes a object/file from the bucket |

$3

| Service | Action | Description |
| ------- | ------- | ---------------------------------------------------------- |
| queue | enqueue | posts object to queue |
| queue | errors | gets list of errors occured with queue |
| queue | queued | gets list of objects that are queued and ready to be sent. |

---

$3

hyper Queue allows you to create a target web hook endpoint to receive jobs, in order to secure that
endpoint to only receive jobs from hyper, you can implement a secret, this secret using sha256 to
encode a nounce timestamp and a signature of the job payload. We created a function on
hyper-connect to make it easier to implement your own middleware to validate these incoming jobs
in a secure way.

`js
import { createHyperVerify } from 'hyper-connect'

const signatureVerify = createHyperVerify(process.env.QUEUE_SECRET, '1m')

export const validateSignature(req, res, next) {
const result = signatureVerify(req.headers.get('x-hyper-signature'), req.body))
if (!result.ok) {
return res.setStatus(result.status).send({msg: result.msg})
}
next()
}
`

$3

- deno task test to run unit tests
- deno task test:integration` to run integration tests. This ensures the Deno code is properly
transformed into Node code. See the Node test harness for more info.

---

$3

Apache 2.0