SDK

DB.HT has a JavaScript SDK that makes it easy to interact with the DB.HT API from your JavaScript app.

Installation

To get the DB.HT SDK from NPM, run:

npm install db.ht

yarn add db.ht

Then, import and initialize the SDK into your project:

import { DB } from 'db.ht'
const db = DB('https://vc.db.ht')

For databases on a DB.HT subdomain, you can also use the abbreviated syntax:

import { DB } from 'db.ht'
const db = DB('vc')

And for databases on a custom domain name, you can use the full URL:

import { DB } from 'db.ht'
const db = DB('https://api.builder.domains')

Alternatively, if your environment supports URL-based imports, you can import from the CDN:

import { db } from 'https://vc.db.ht/sdk.js'

Which also has support for custom domain names:

import { db } from 'https://api.builder.domains/sdk.js'

Listing Types

To list all types in a database, use the db.list() method:

const types = await db.list()

Listing Documents

To list all documents of a type, use the db.list() method:

const users = await db.users.list()

By default, the list() method returns the first 100 documents. To get more documents, use the page and pageSize options:

const users = await db.users.list({ page: 2, pageSize: 250 })

Also by default, the list() method returns the documents in ascending order. To get the documents in descending order, use the sort option:

const users = await db.users.list({ sortBy: '_createdAt', sort: 'desc' })

Additionally, the list is lightly loaded by default. It for each object, it only returns the _id and _name fields:

const users = await db.users.list()
console.log(users)
// [
//   { _id: 'john@example', _name: 'John Doe' },
//   { _id: 'jane@example', _name: 'Jane Doe' }
// ]

To get the full document, use the getList method:

const users = await db.users.getList()

Searching Documents

To query documents of a type, use the db.find() method:

const users = await db.users.find({ _name: 'John Doe' })

You can also use regex to search for documents:

const users = await db.users.find({ _name: /Doe/ })

Full-text search is also supported:

const users = await db.users.search('jon')

Counting Documents

To count documents of a type, use the db.count() method:

const count = await db.users.count()

Get Documents

To get a document by _id, use the get() method:

const user = await db.users.get('[email protected]')

Create or Update Documents

To create or update a document, use the set() method:

await db.users.set('[email protected]', { _name: 'John Doe' })

You can also embed the document _id in the document itself:

await db.users.set({ _id: '[email protected]', _name: 'John Doe' })

You can create or update multiple documents, but the _id is required to be in the document:

await db.users.set([
  { _id: '[email protected]', _name: 'John Doe' },
  { _id: '[email protected]', _name: 'Jane Doe' }
])

Increment & Decrement Properties

To increment or decrement a property, use the increment() and decrement() methods:

await db.users.increment('[email protected]', 'visits')

You can also increment or decrement by a specific amount:

await db.users.increment('[email protected]', 'points', 10)

Linking Documents

You can link documents together by using an arbitrary method as a relationships:

user.get('[email protected]').invites('[email protected]')

You can also link documents of different types like:

user.get('[email protected]').subscribes('app/MyApp', 'subscribers')

Or even any external URI like:

user.get('[email protected]').visits('https://example.com')

user.get('[email protected]').visits('https://example.com', 'analytics.visitors')

Delete Documents

To delete a document by _id, use the delete() method:

await db.users.delete('[email protected]')

You can also delete multiple documents by _id:

await db.users.delete(['[email protected]', '[email protected]'])

And you can delete all documents of a type:

await db.users.deleteAll()

API Examples