Skip to main content

Atek Database API

atek.cloud/adb-api

npm install @atek-cloud/adb-api
import adb from '@atek-cloud/adb-api'import cats from 'example-cats-table'
// get or create a database under the 'mydb' aliasconst db = adb.db('mydb')
// use the cats tableawait cats(db).create({id: 'kit', name: 'Kit'})await cats(db).list() // => {records: [{key: 'kit', value: {id: 'kit', name: 'Kit', createdAt: '2021-09-07T01:06:07.487Z'}}]}await cats(db).get('kit') // => {key: 'kit', value: {id: 'kit', name: 'Kit', createdAt: '2021-09-07T01:06:07.487Z'}}await cats(db).put('kit', {id: 'kit', name: 'Kitty'})await cats(db).delete('kit')

See The Atek DB Guide to learn how to use ADB.

Default export properties#

NameType
apiAdbApi & AtekRpcClient
db(dbId: string | DbConfig, opts?: DbConfig) => AdbDatabase

Use the .db() method to create AdbDatabase instances. You may pass a Hypercore 64-character hex-string key or an arbitrary string (which will be a local alias).

import adb from '@atek-cloud/adb-api'
// get or create a database under the 'mydb' alias// - the 'mydb' alias will be stored under this application for easy future accessconst db = adb.db('mydb')
// get a database under its Hypercore key// - if the database does not exist locally, its content will be fetched from the p2p networkconst db2 = adb.db('97396e81e407e5ae7a64b375cc54c1fc1a0d417a5a72e2169b5377506e1e3163')

The .api is the RPC interface which will be used by .db().

Exported Functions#

defineSchema#

defineSchema<T>(path, opts?): (db: AdbDatabase) => any

Parameters#

NameType
pathstring | string[]
opts?AdbSchemaOpts

Returns#

fn

▸ (db): any

Use this function to create reusable record schemas.

import adb, { defineSchema } from '@atek-cloud/adb-api`
interface CatRecord {  id: string  name: string  createdAt: string}
const cats = defineSchema<CatRecord>('example.com/cats', {  pkey: '/id',  jsonSchema: {    type: 'object',    required: ['id', 'name']    properties: {      id: {type: 'string'},      name: {type: 'string'},      createdAt: {type: 'string', format: 'date-time'}    }  }})
await cats(adb.db('mydb')).create({  id: 'kit',  name: 'Kit the Cat'})

createClient#

createClient(): AdbApi & AtekRpcClient

Returns#

AdbApi & AtekRpcClient

Creates an AdbApi instance. You can typically use the .api exported on the default object, but if you need to configure a separate API instance you can use this function.


createServer#

createServer(handlers): AtekRpcServer

Parameters#

NameType
handlersany

Returns#

AtekRpcServer

Creates an AtekRpcServer server. You would only ever need this if creating your own ADB server (perhaps for test mocking).

Class: AdbDatabase#

Constructor#

new AdbDatabase(api, dbId, opts?)

Parameters#

NameType
apiAdbApi
dbIdstring
opts?DbConfig

Properties#

isReady#

isReady: Promise<any>


api#

api: AdbApi


dbId#

dbId: string

Methods#

describe#

describe(): Promise<DbInfo>

desc Get metadata and information about the database.

Returns#

Promise<DbInfo>


list#

list(path, opts?): Promise<Object>

desc List records in a table.

Parameters#
NameType
pathstring | string[]
opts?ListOpts
Returns#

Promise<Object>


get#

get(path): Promise<Record<object>>

desc Get a record in a table.

Parameters#
NameType
pathstring | string[]
Returns#

Promise<Record<object>>


put#

put(path, value): Promise<Record<object>>

desc Write a record to a table.

Parameters#
NameType
pathstring | string[]
valueobject
Returns#

Promise<Record<object>>


delete#

delete(path): Promise<void>

desc Delete a record from a table.

Parameters#
NameType
pathstring | string[]
Returns#

Promise<void>

Class: AdbSchema<T>#

Type parameters#

NameType
Textends object

Constructor#

new AdbSchema<T>(db, path, opts?)

Type parameters#

NameType
Textends object

Parameters#

NameType
dbAdbDatabase
pathstring | string[]
opts?AdbSchemaOpts

Properties#

path#

path: string[]


isReady#

isReady: Promise<any>


pkey#

Optional pkey: string | string[]


pkeyFn#

pkeyFn: PkeyFunction


jsonSchema#

Optional jsonSchema: object


validator#

Optional validator: Validator


db#

db: AdbDatabase

Methods#

list#

list(opts?): Promise<Object>

desc List records in the schema.

Parameters#
NameType
opts?ListOpts
Returns#

Promise<Object>


get#

get(key, opts?): Promise<undefined | Record<T>>

desc Get a record in the schema space.

Parameters#
NameType
keystring
opts?ValidationOpts
Returns#

Promise<undefined | Record<T>>


create#

create(value, opts?): Promise<undefined | Record<T>>

desc Add a record to the schema space.

Parameters#
NameType
valueT
opts?ValidationOpts
Returns#

Promise<undefined | Record<T>>


put#

put(key, value, opts?): Promise<undefined | Record<T>>

desc Write a record to the schema space.

Parameters#
NameType
keystring
valueT
opts?ValidationOpts
Returns#

Promise<undefined | Record<T>>


delete#

delete(key): Promise<void>

desc Delete a record from the schema space.

Parameters#
NameType
keystring
Returns#

Promise<void>

Interface: AdbSchemaOpts#

Properties#

pkey#

Optional pkey: string | string[]


jsonSchema#

Optional jsonSchema: object