** The Unbounded database is currently in hiatus. Thank you to everyone that used our service, we hope you'll join us again for our next upgraded iteration.**
This module implements full-featured access to the Unbounded database.
For detailed information on methods and parameters, see the API reference on the Unbounded documentation portal.
npm install @unbounded/unbounded --save
const Unbounded = require('@unbounded/unbounded');
let client = new Unbounded('aws-us-east-2', 'user@domain.com', 'somepassword');
let db = client.database('mydatabase');
(async () => {
let results = await db.add({
property: 'value'
});
let [newid] = results.inserted;
console.log("inserted id: " + newid);
let [obj] = await db.match({id: newid});
console.log("retrieved object: " + JSON.stringify(obj));
})();
The Unbounded web service takes parameters in the form of JSON objects. This module lets you pass
a raw JSON object to the methods query
, insert
, update
and delete
:
client.database('mydatabase').query({match: {}, limit: 1}).then(results => {
// ...
});
However, in normal circumstances it is cleaner to use the "builder" style syntax,
which is available by passing no arguments to the query
, insert
, etc. methods. In this style,
you can chain options together, then end the chain with a call to send
, which returns a Promise:
client.database('mydatabase').query()
.match({})
.limit(1)
.send().then(results => {
// ...
});
Unbounded accepts Javascript functions as JSON strings for various purposes. When
using this module, you have the option to pass actual Javascript code to your calls,
allowing it to be syntax highlighted, linted, etc. The module will automatically convert
the where
argument in a call like this to a string when sending it to the Unbounded
servers:
let db = client.database('mydatabase');
await db.query().where(o => o.someproperty === 1).send();
It's important to note that because functions are converted to strings, attempting to
use a global or lexically scoped variable in a callback will result in
an error when the callback is executed in Unbounded. To re-use a callback with
different variables, you should call the bind
method after adding your function
parameter. bind
accepts any number of values, which will be passed as the first
parameters to your function when it is executed on the server:
const myfunc = (val, o) => o.someproperty === val;
// queries for someproperty === 1
await db.query().where(myfunc).bind(1).send();
Unbounded lets users specify aggregate functions in terms of map
and reduce
functions,
which are analagous to the corresponding calls on the Javascript built-in Array
class. Because
these functions can be more difficult to write than the simple aggregation functions built in to SQL,
this module contains some shortcuts which let you easiy compute various aggregations of a single property.
For example:
await db.query()
.sum('counter')
.send()
Will compute the sum of the counter
properties on the objects in db. This call is shorthand for:
await db.query()
.map(o => ({sum: o.counter}))
.reduce((a, b) => ({sum: a.sum + b.sum}))
.send()
The other built-in aggregation shortcuts are: count
, avg
, min
, max
, some
, and every
.
In Unbounded, any method call can return either a synchronous reply or an asynchronous task. This module abstracts that behavior in the following way:
By default, calling methods on a database or saved query object will always return synchronously (meaning they will complete when their promise resolves or callback parameter completes; this behavior is not related to the inherant async behavior of Javascript). If a method does return an async task, the library hides this by automatically waiting for the task to complete and returning the result.
Note that for large queries that are saved to files, this behavior can result in unwanted resource usage, because the library will attempt to download all the files and concatenate them before returning. For large queries, webhooks are a more performant option than the default file behavior.
Optionally, clients can manage async tasks manually by calling methods on the async
property of a database:
let db = client.database('mydatabase');
let taskobj = await db.async.query().where(o => o.someproperty === 1).send();
This enables users to write to a database and continue processing without waiting for the write to complete. If
desired, the resulting task object can be passed to client.wait
to receive a Promise that resolves when the task
completes:
let db = client.database('mydatabase');
let taskobj = await db.async.query().where(o => o.someproperty === 1).send();
let results = await client.wait(taskobj);
The task object itself can be serialized using JSON, so that if an app terminates or another problem occurs, the task can still be waited on by deserializing it later.
If the task is a query and no webhook was specified, then the files
property of the result object will contain a list
of URLs with query results. This object contains a built-in fetch
method which retrieves the URLs and returns the
concantenated results as an array:
let objs = await results.fetch();
startUpload
is a convenience method which simplifies importing a large number of objects into an Unbounded database.
It accepts the same options as the insert
method (without the values
parameter). startUpload
returns an Uploader
class instance, which has an add
method to add objects to the upload. Call the finish
method after all objects are
added:
let array = [{someproperty: 1}, {someproperty: 2}, ...];
let uploader = client.database('mydatabase').upload();
for (let i in array) {
await uploader.add(array[i]);
}
await uploader.finish();
This module can be used to access Unbounded directly from an app or web browser. You can use it with React/Angular/Vue or any other frontend framework.
The main difference between server-side and browser/frontend usage is authentication. In the example at the top of this page, we created a client object by passing our Unbounded account username and password to the Unbounded() constructor:
let client = new Unbounded('aws-us-east-2', 'user@domain.com', 'somepassword');
However, when accessing the db from a browser, we should never use our account password, as our users will be able to obtain it and gain unfettered access to our account. Rather, we need to use an authentication provider to tie our users to an identity, and then set a signed identity token for Unbounded to uniquely identify our user. Here's an example using Google as our authentication provider:
<!-- sample code taken from https://developers.google.com/identity/sign-in/web/sign-in -->
<head>
<script src="https://apis.google.com/js/platform.js" async defer></script>
<meta name="google-signin-client_id" content="YOUR_CLIENT_ID.apps.googleusercontent.com">
</head>
<body>
<div class="g-signin2" data-onsuccess="onSignIn"></div>
<script>
// pass only your username here, not your password
var client = new Unbounded('aws-us-east-2', 'user@domain.com');
function onSignIn(googleUser) {
var id_token = googleUser.getAuthResponse().id_token;
var token_type = 'google';
// set the signed in Google user as active in the db client
client.setSubToken(id_token, token_type);
// now when we make calls to our client, the authentication will
// use the user's Google account credentials
client.database('mydatabase').match({something: true}).then(...);
}
</script>
</body>
The key here is the call to client.setSubToken
, which will ensure that the Google id_token
is used to authenticate all database queries. If you wish to sign out the user later, you can
remove their user token from the client by calling client.setSubToken(null)
.
In order for this to work, you must configure your database's users
property with your app's
Google client ID. More information (including using other authentication providers) is available
in the Unbounded Frontend Access Guide.
export default class Unbounded {
constructor(region: string, username: string, password: string);
database(name: string): Database;
listDatabases(): Promise<object[]>;
wait(task: Task): Promise<FileResult | object[] | undefined>;
setSubToken(subtoken: string, type: string);
}
class FileResult {
files: string[]
fetch(cb?): object[]
}
class Database {
async: DatabaseAsync;
match(match?: object, options?: object): Promise<object[]>;
query(): QueryBuilder;
query(options: object): Promise<object[]>;
add(values: object | object[], options?: object): Promise;
insert(): InsertBuilder;
insert(options: object): Promise;
update(): UpdateBuilder;
update(options: object): Promise;
delete(): DeleteBuilder;
delete(options: object): Promise;
getKey(): Promise<any>;
setKey(key: string | string[]) : Promise;
getSchema(): Promise<object>;
setSchema(schema: object) : Promise;
getIndexes(): Promise<Array>;
setIndexes(indexes: Array) : Promise;
deleteDatabase() : Promise;
savedQuery(name: string): SavedQuery;
listSavedQueries(): Promise<object[]>;
startUpload(exists?: Function | string, options?: object): Uploader;
}
class DatabaseAsync {
match(match?: object, options?: object): Promise<Task>;
query(): AsyncQueryBuilder;
query(options: object): Promise<Task>;
add(values: object | object[], options?: object): Promise<Task>;
insert(): AsyncInsertBuilder;
insert(options: object): Promise<Task>;
update(): AsyncUpdateBuilder;
update(options: object): Promise<Task>;
delete(): AsyncDeleteBuilder;
delete(options: object): Promise<Task>;
}
class Task {}
class SavedQuery {
async: SavedQueryAsync;
match(match?: object, options?: object): Promise<object[]>;
query(where?: Function | string, options?: object): Promise<object[]>;
deleteSavedQuery(): Promise;
}
class SavedQueryAsync {
match(match?: object, options?: object): Promise<Task>;
query(): AsyncQueryBuilder;
query(options: object): Promise<Task>;
}
class Uploader {
add(value: object) : Promise;
finish(): Promise;
}
class QueryBuilder {
match(props: object): QueryBuilder
where(func: Function | string): QueryBuilder
bind(...args: any[]): QueryBuilder
map(func: Function | string): QueryBuilder
filter(func: Function | string): QueryBuilder
reduce(func: Function | string): QueryBuilder
sort(opts: object): QueryBuilder
limit(count: number): QueryBuilder
single(): QueryBuilder
webhook(url: string): QueryBuilder
count(): QueryBuilder
sum(prop: string): QueryBuilder
avg(prop: string): QueryBuilder
min(prop: string): QueryBuilder
max(prop: string): QueryBuilder
some(prop: string): QueryBuilder
every(prop: string): QueryBuilder
send(): Promise<object[]>
}
class InsertBuilder {
values(data: object | object[]): InsertBuilder
exists(func: Function | string): InsertBuilder
bind(...args: any[]): InsertBuilder
send(): Promise
}
class UpdateBuilder {
match(props: object): UpdateBuilder
where(func: Function | string): UpdateBuilder
set(func: Function | string): UpdateBuilder
bind(...args: any[]): UpdateBuilder
single(): UpdateBuilder
send(): Promise
}
class DeleteBuilder {
match(props: object): DeleteBuilder
where(func: Function | string): DeleteBuilder
bind(...args: any[]): DeleteBuilder
single(): DeleteBuilder
send(): Promise
}