hyper connect

hyper-connect is the client access library for hyper, built for Javascript and Typescript. hyper-connect uses Promises and the fetch specification, as a base layer for interacting with hyper's REST API. You will find this approach creates intuitive usability.

import { connect } from 'hyper-connect'
const hyper = connect(process.env.HYPER)

const result = hyper.data.query({type: 'game'})
if (result.ok) {
    console.log(result.docs)
}

Install

NodeJS

To install hyper-connect in your NodeJS project, use npm or yarn

npm install hyper-connect
export HYPER=cloud://key:secret@cloud.hyper.io/app

import { connect } from "hyper-connect";
const hyper = connect(process.env.HYPER);

const result = await hyper.data.list({limit: 2})

console.log(result)

Deno

To install hyper-connect in your Deno project, you can use nest.land or pull directly from Github

export HYPER=cloud://key:secret@cloud.hyper.io/app

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

const hyper = connect(Deno.env.get('HYPER'))

const result = await hyper.data.list({limit: 2})

console.log(result)

Usage

API

The hyper-connect API is intuitive. Promises are returned. This makes composition easy. The API is split into five sections: data, cache, search, storage, and queue.

Data Service Methods

Data Service Example

import { connect } from 'hyper-connect'

const hyper = connect(process.env['HYPER'])

// Data Service Commands
let doc = {_id: "character-1", type: "character", name: "Mario"}
// create document
await hyper.data.add(doc)
// retreive document
doc = await hyper.data.get("character-1")
// update document
doc.description = 'Main character of mario universe'
await hyper.data.update("character-1", doc)
// remove document
await hyper.data.remove("character-1")

// list all documents
await hyper.data.list()

// query documents that are type charater
await hyper.data.query({type: 'character'})

// bulk load documents
await hyper.data.bulk([
  {
    "_id": "character-1",
    "type": "character",
    "name": "Mario"
  },
  {
    "_id": "character-2",
    "type": "character",
    "name": "Luigi"
  },
  {
    "_id": "character-3",
    "type": "character",
    "name": "Princess Peach"
  }
])



Cache Service Methods

Cache Service Examples

import { connect } from 'hyper-connect'

const hyper = connect(process.env.HYPER)

// cache key and value
await hyper.cache.add('character-1', {_id: 'character-1', name: 'mario'})
// get value from key
const mario = await hyper.cache.get('character-1')
// set key and value
await hyper.cache.set('character-1', {_id: 'character-1', name: 'mario', type: 'character'})
// remove by key
await hyper.cache.remove('character-1')
// query cache - find all cache items where key starts with character-
await hyper.cache.query('character-*')

Search Service Methods

Search Service Examples

import { connect } from 'hyper-connect'
const hyper = connect(process.env['HYPER'])

await hyper.search.add('game-1', {id: 'game-1', title: 'Donkey Kong', type: 'game'})
await hyper.search.add('game-2', {id: 'game-2', title: 'Pac man', type: 'game'})

const dk = hyper.search.get('game-1')
await hyper.search.update('game-2', {id: 'game-2', title: 'Pac man', type: 'game', year: '1978'})
await hyper.search.update('game-1', {id: 'game-1', title: 'Donkey Kong', type: 'game', year: '1977'})

const result = await hyper.search.query('Pac man')
console.log(result.matches)

Storage Service Methods

Storage Service Examples

import { connect } from 'hyper-connect'
import {createReadStream, createWriteStream} from 'node:fs'
import {pipeline} from 'node:stream'
import {promisify} from 'node:util'

const hyper = connect(process.env.HYPER)

// upload file
await hyper.storage.upload('avatar.png', createReadStream('./avatar.png'))

const streamPipeline = promisify(pipeline)
// download file
await streamPipeline(await hyper.storage.download('avatar.png'), createWriteStream('avatar.png'))

// remove file
await hyper.storage.remove('avatar.png')

Queue Service Methods

Queue Service Examples

import { connect } from 'hyper-connect'
const hyper = connect(process.env.HYPER)

// add job to queue
await hyper.queue.enqueue({type: 'job', title: 'my job'})

// check for queued jobs
await hyper.queue.queued()

// check for errors 
await hyper.queue.errors()

Advanced

Data List Method

The data list method gives the developer the ability to list documents using the document key identifier in a range query approach. This approach can save the need for complex queries and indexes, since the key is already indexed. A great strategy is to use the document type and a cuid collision unique identifier combined. This gives you the ability to use the list method to find all documents of a certain type and created by a certain timestamp, which will always be ordered by the create date. hyper.data.add({_id: `${type}-${cuid()}`,...})

keys - is a property on the list options object that allows the developer to list specific keys that they want to return back from the data store.

const result = await hyper.data.list({keys: ['character-1', 'character-3', 'character-5']})
console.log(result.docs)

startkey, endkey - are a couple of properties that can be used to get a range of documents, you can use the startkey to find all the documents that include the value of the startkey or come after the key. With the endkey, you can use the list method to return all the documents that come before the value of the endkey. You can use these options together to create a range of documents. For example, if you want to return all the character documents:

const result = await hyper.data.list({startkey: 'character-', endkey: 'character-z'})
console.log(result.docs)

This list method will return all the documents with the prefix of 'character-'.

descending - is an optional attribute that will reverse the result set based on the identifier.

limit - in an optional attribute that will return a limited amount of documents, the default is 25

Data Query Method

selector

The selector for the query is where the power of hyper data services exist. You can use many operators to describe your query filter criteria.

dot notation for child properties

If you want to add child properties to your selector you can use 'dot notation'. For example, if you have a document that has child nodes, like:

{
    "type": "character",
    "name": "mario",
    "attributes": {
      "hat": true
    }
}

Then you can reference the hat attribute in your selector like: { "attributes.hat": true } - using dot notation.

selector operators

options

When using the hyper.data.query function, you can pass an optional argument that is known as the options object, this object can contain the following properties/keys: fields, sort, limit, and useIndex.

fields option

This option allows you to narrow the result set in your returned data set. For example, if you have a query to return back documents that contain just the _id, and title, but no other document information, you would do the following:

hyper.data.query({type: 'movies'}, {fields: ['_id', 'title']})

const result = await hyper.data.query({type:'movie', {fields: ['_id', 'title']}})
console.log(result.docs)

sort option

Using the sort option, you can specify the order of the returning documents, the sort option takes an array of objects, where each object contains a key which would be the document property name, and value which would be either 'ASC' for ascending or 'DESC' for descending. You can add multiple sort objects to the array and they are sorted in a left to right order.

hyper.data.query({ type: 'game', { sort: [{ year: 'DESC' }, { title: 'DESC' }] })

const result = await hyper.data.query({ type: 'game', { sort: [{ year: 'DESC' }, { title: 'DESC' }] })
console.log(result.docs)

limit option

The limit option limits the number of documents that should be returned in a result set, if you do not specify a limit, the default limit is 25.

hyper.data.query({type: 'game'}, { limit: 2 })

const result = await hyper.data.query({type: 'game', { limit: 2 }})

console.log(result.docs)

useIndex option

The useIndex option allows the developer to specify the index they wish to use for this specific query, the data service tries to determine which index, but it is helpful to specify the index for complex queries.

hyper.data.query({type: 'character', year: { $gt: '2000' }}, {useIndex: 'idx-type-date'})

Search Query Method

When using the hyper.search.query function, you can pass an optional options argument that accepts two properties/keys: fields and filter.

fields option

The fields option allows you to select which fields in your search index you would like to specifically search against. For example, if you have multiple fields in your search index such as a title field and a year field. You can use the fields object to narrow the matches down to match the criteria to only year entries:

hyper.search.query('1984', { fields: ['year']})

const result = await hyper.search.query('1984', {
    fields: ['year']
})

console.log(result.matches)

filter option

The filter option allows you to instruct the search engine to filter matched documents based on a key-value pair. For example, let's say you are storing multiple document types, a movie, game, and song. If you only wanted to search for songs that matched specific criteria, your query may look like this:

hyper.search.query('Sweet child of mine', { filter: {type: 'song'}})

const result = await hyper.search.query('Sweet child of mine', {
    filter: {type: 'song'}
})
console.log(result.matches)