41min

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.

What's New

As of version 0.1.9, we support NodeJS version >=14 and Deno version >=1.17

JS
|

Install

NodeJS

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

Shell
|
Node
|

Deno

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

Shell
|
Deno
|

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

Method

Description

Example

hyper.data.add

creates a document

hyper.data.add({...})

hyper.data.get

retrieves a document by id

hyper.data.get(_id)

hyper.data.update

updates a document

hyper.data.update(_id, {...})

hyper.data.remove

removes a document

hyper.data.remove(_id)

hyper.data.list

lists documents

hyper.data.list()

hyper.data.query

queries documents with a mongo style selector

hyper.data.query({ year: { $gt: '1984' } }, [options])

hyper.data.bulk

inserts, updates and deletes documents using an array of documents

hyper.data.bulk([...])

hyper.data.index

creates an index for the data service that can be used to optimize transactional queries

hyper.data.index('idx-type-year', ['type', 'year'])

Data Service Example

JS
|

ο»Ώ

Cache Service Methods

Method

Description

Example

hyper.cache.add

cachesa document

hyper.cache.add(key, value, [ttl])

hyper.cache.get

retrieves a cache value by key

hyper.cache.get(key)

hyper.cache.set

updates a value

hyper.cache.set(key, {...}, [ttl])

hyper.cache.remove

removes a value

hyper.cache.remove(key)

hyper.cache.query

lists cache values by pattern

hyper.cache.query("*")

Cache Service Examples

JS
|

Search Service Methods

Method

Description

Example

hyper.search.add

indexes a document

hyper.search.add(key, {...})

hyper.search.get

retrieves an indexed doc by id

hyper.search.get(key)

hyper.search.update

updates a document

hyper.search.update(key, {...})

hyper.search.remove

removes a document

hyper.search.remove(key)

hyper.search.query

queries documents with a mongo style selector

hyper.search.query(criteria, [options])

hyper.search.load

inserts search documents using an array of documents

hyper.search.load([...])

Search Service Examples

Use the hyper cloud dashboard to create a search index

If your hyper application only needs one search service, you may name the search index default if you want to use the same connect session as your data and cache sessions.

JS
|

Storage Service Methods

Method

Description

Example

hyper.storage.upload

uploads object/file to storage bucket

hyper.storage.upload(name:string, file: buffer)

hyper.storage.download

downloads object/file from storage bucket

hyper.storage.download(name: string)

hyper.storage.remove

removes object/file from storage bucket

hyper.storage.remove(name: string)

Storage Service Examples

JS
|

Queue Service Methods

Method

Description

Example

hyper.queue.enqueue

add object to queue for processing

hyper.queue.enqueue(job : object)

hyper.queue.errors

returns jobs that have errored out

hyper.queue.errors()

hyper.queue.queued

returns jobs that are still queued

hyper.queue.queued()

Queue Service Examples

JS
|

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.

JS
|

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:

JS
|

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:

JS
|

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

selector operators

Selector

Description

Example *

$eq

Equals, match when property equals this value

{ "title": { "$eq": "Ghostbusters"}}

$ne

The property does not equal the value

{ "title": {"$ne": "Groundhog Day"}}

$lt

The property value is less than the value

{ "year": {"$lt": "1990"}}

$lte

The property value is less than or equal to the value

{ "year": { "$lte": "1990"}}

$gte

The property value is greater than or equal to the value

{ "year": {"$gte": "2000"}}

$gt

The property value is greater than

{ "year": {"gt": "2000"}}

$exists

Check whether the property exists

{ "type": {"$exists": true}}

$type

Check the properites type, valid values are "null", "boolean", "number", "string", "array", "object"

{ "title": {"$type": "string"}}

$in

The document property must exist in the list of values provided.

{ "title": {"$in": ["Star Wars", "Star Trek"]}}

$nin

The document property must not exist in the list of values provided.

{ "title": {"$nin": ["Superman", "Spiderman"]}}

$mod

The document property value modulus a divisor that equals a remainder. eg [Divisor, Remainer]

{ "total": {"$mod": [2, 0]}} // even numbers

$regex

The document property must be a string and the regex expression matches all documents that match the regex

{ "title": {"$regex": "^Star" }}

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']})

JS
|

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' }] })

JS
|

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 })

JS
|

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']})

JS
|

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'}})

JS
|

ο»Ώ

ο»Ώ

Updated 10 May 2022
Did this page help?
Yes
No