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
To install hyper-connect in your NodeJS project, use npm or yarn
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.
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']) |
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("*") |
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([...]) |
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.
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) |
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() |
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.
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:
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
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.
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:
Then you can reference the hat attribute in your selector like: { "attributes.hat": true } - using dot notation.
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" }} |
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.
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']})
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' }] })
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 })
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'})
When using the hyper.search.query function, you can pass an optional options argument that accepts two properties/keys: fields and filter.
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']})
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'}})
