SX3 Database

This is a migration based wrapper around the IndexedDB API.

• Installation
• Usage
  • Readwrite
  • Multiple storages
  • Native APIs are available
  • Delete database
  • Cursors
    • Iterate over the entire store
    • Iterate over with query
    • Iterate over index
  • Migrations
    • Async migrations
  • Errors

Installation

npm install @sx3/database

Usage

Readwrite

Read:

import { Database } from "@sx3/database";

const db = await new Database("mydb").open();

const users = await db.transaction("users").store().getAll();

Write:

const db = await new Database("mydb").open();

const userStore = db.transaction("users", "readwrite").store();

const id = await userStore.add({ name: "SX3", age: 99 });

Delete:

const db = await new Database("mydb").open();

const userStore = db.transaction("users", "readwrite").store();

await userStore.delete(1);

Multiple storages

const db = await new Database("mydb").open();
const trx = db.transaction(["users", "posts"], "readwrite");

const usersStore = trx.store("users");
const postsStore = trx.store("posts");

// Some actions ...

trx.commit(); // not necessarily

Native APIs are available

const db = new Database("mydb");
await db.open();

db.addEventListener("abort", () => {});
db.deleteObjectStore("users");
db.close();
// etc..

const trx = db.transaction("users");
trx.objectStore("users");
trx.addEventListener("complete", () => {});
// etc..

Delete database

new Database("mydb").delete();

Cursors

Iterate over the entire store

import { Database } from "@sx3/database";

const db = new Database("mydb");
await db.open();

const usersStore = db.transaction("users").store();
for await (const cursor of usersStore) {
  console.log(cursor.value);
}

Iterate over with query

const db = new Database("mydb");
await db.open();

const usersStore = db.transaction("users").store();
const range = IDBKeyRange.bound(20, 30);
for await (const cursor of usersStore.iterate(range)) {
  console.log(cursor.value);
}

Iterate over index.

Iterating over an index is similar to iterating over a store

const db = new Database("mydb");
await db.open();

const usersStore = db.transaction("users").store();
const index = usersStore.index("age");
for await (const cursor of index) {
  console.log(cursor.value);
}

Database migrations

DB migrations are an array of schemas:

import { MigrationSchema, Database } from "@sx3/database";

const postsSchema: MigrationSchema = {
  1: builder => builder.create("posts").index("id"),
};

const commentsSchema: MigrationSchema = {
  2: builder =>
    builder.create("comments").index("entity", ["entity_name", "entity_id"]),
};

// Version calculated from migrations
const db = new Database("mydb", { migrations: [postsSchema, commentsSchema] });

Async migrations

Async migrations allow lazy loading while opening a connection to the database:

import { MigrationSchema, Database } from "@sx3/database";

const asyncSchema = () =>
  new Promise<MigrationSchema>(resolve => {
    resolve({
      1: builder => builder.create("users").index("id"),
    });
  });

const db = await new Database("mydb", { migrations: [asyncSchema] }).open();

You can also load migrations from other files, for example your project structure might look like this:

modules
├─ moduleA
│  └─ store
│     ├─ posts.ts
│     └─ comments.ts
└─ moduleB
   └─ store
      ├─ cart.ts
      └─ wishlist.ts

This code imports migration schemas from all your module stores:

import { MigrationSchema, Database } from "@sx3/database";

const schemas = import.meta.glob<MigrationSchema>("./modules/**/store/*.ts", {
  import: "migrations",
});

const db = new Database("mydb", {
  migrations: Object.values(schemas),
});

Errors

Within this library, 3 new errors have been introduced:

• NotOpenedError - Database is not open
• BlockedError - Database is locked
• NoStoreProvidedError - No store provided for transaction

import {
	Database,
	NotOpenedError,
	BlockedError,
	NoStoreProvidedError,
} from "@sx3/database";

const db = new Database("mydb");

try {
	await db.open();
} catch (error: unknown) {
	if (error instanceof BlockedError) {
		// Do something
	}
}