@digitallinguistics/idb v0.3.5

DLx IndexedDB Client

A client library for storing DLx data in IndexedDB

View the complete documentation for this library here.

NOTE: This library requires dlx-js as a peer dependency. Make sure you include the dlx-js library in your page before idb.

Installation

If using npm:

npm i --save @digitallinguistics/idb

If using yarn:

yarn add @digitallinguistics/idb

You can also link to the DLx CDN:

<script src=https://cdn.digitallinguistics.io/scripts/idb.js></script>

Or download the script manually:

curl https://cdn.digitallinguistics.io/scripts/idb.js -o idb.js

Including the Script on Your Page

The idb library may be used either as a module (all module types are supported, including ES6) or a regular script. If using the library as a regular script, DLxIDB will be made available as a global variable, and the IndexedDB client constructor will be available on DLxIDB.default.

First, include the dlx-js library:

<script src=dlx.js></script>

Then import the IndexedDB library into your script.

Using ES6 modules:

import IDBClient from './idb.js';

Using CommonJS modules:

const IDBClient = require('./idb.js');

As a regular script:

<script src=dlx.js></script>
<script src=idb.js></script>
<script>
  const IDBClient = DLxIDB.default;
</script>

Initializing the Database

To create a new IndexedDB client, simply create a new instance of the IDBClient class:

const idb = new IDBClient;

You can also specify the name to use for the IndexedDB database using the name option. By default, the database will be called dlx:

const idb = new IDBClient({ name: 'mydatabase' });

You can then connect to the database by calling .open() or .connect(), which returns a Promise when the database is connected. You can then begin making calls to the database:

idb.open() // open the database
.then(() => idb.getLanguages()) // then begin performing operations on the database
.then(languages => { /* do something with results */ })
.catch(/* handle errors here */);

Making Requests to the Database

Once the database is connected, your application may begin making requests to the database. The IndexedDB client has methods for each type of operation, and each type of database object. For example, each of the following methods is available for Language objects, which are stored in the languages table in IndexedDB:

• addLanguage()
• deleteLanguage()
• getLanguage()
• getLanguages()
• updateLanguage()
• upsertLanguage()

Each method returns a Promise that resolves to the database response.

You can also use the more generic add(), delete(), get(), getAll(), update(), and upsert() methods if you wish.

View the documentation for a complete list of methods available on the database client. (Click on Modules at the top of the page, and then IDBClient.)

The IDBClient also provides access to the underlying IndexedDBDatabase Object (as the client property) if you need to access it directly. This is useful for making other, custom requests to IndexedDB. You can also use this to add a generic listener for database errors or close events:

idb.client.onclose = ev => { console.error(ev.target); };
idb.client.onerror = ev => { console.error(ev.target); };

Want to Contribute?

Check out DLx's general contributing guidelines.

Maintainers

This repo is maintained by:

• Daniel W. Hieber (dhieber@umail.ucsb.edu)