maxwebdb

A simpler API for IndexedDB.

• Promises: async/await for all CRUD operations.
• Easy Fast Queries: Auto-selects best index for performance.
• Auto schema sync: Automatically handles schema changes and database upgrades.
• Zero dependencies: Single file, native performance, gzipped about 1.6kb.

await DB.users.insert();
await DB.products.findMany({query});
await DB.example.delete();
...

import { setupDb } from "maxwebdb";

const DB = await setupDb({
  name: "db1",
  stores: [
    { name: "users", indexes: ["email", "role"] }
  ]
});

const id = await DB.users.insert({
  name: "peter",
  email: "[email protected]",
  role: "admin"
});

const user = await DB.users.get(id);
console.log(user);

Comparison

| Feature | maxwebdb | idb | localForage | Dexie | |---|---|---|---|---| | Primary Use Case | Simple local DB | Raw Wrapper | Key-value storage | Advanced local DB | | Size (min+gzip) | ~1.4kb | ~1.4kb | ~8.5kb | ~30.3kb | | Auto schema sync | ✅ | ❌ | ➖ | ❌ | | Zero manual migrations | ✅ | ❌ | ✅ | ❌ | | Object queries and filtering | ✅ | ❌ | ❌ | ✅ | | Auto index selection | ✅ | ❌ | ❌ | ❌ | | Observable / Live queries | ❌ | ❌ | ❌ | ✅ |

Install

npm install maxwebdb

Setup

import { setupDb } from "maxwebdb";

const config = {
  name: "db1",
  stores: [
    { name: "users", indexes: ["email", "role"] },
    { name: "products", indexes: ["category", ["category", "status"]] }
  ]
};

const DB = await setupDb(config);

Unlike with idb or Dexie, you don't have to update schemas manually.

Just define your desired config what stores and indexes are needed.
setupDb() compares the config with the current database schema and handles schema updates and version upgrades automatically.

Insert

If the object has no id, auto generates.

// Single: returns inserted id
const id = await DB.users.insert({ name: "Alex" });

// Bulk: returns array of ids [id1, id2...]
const ids = await DB.users.insert([{ name: "A" }, { name: "B" }]);

Put

Insert, replace if already exists
For bulk request - pass array of objects.

const id = await DB.users.put({});

Get

Get one item by id

const id = await DB.users.get(id);
const ids = await DB.users.getAll();

Delete and clear

await DB.exampleStore.delete(key)
await DB.exampleStore.clear()

Queries

const item = await DB.example.findOne(QueryObject, cb); 
const items = await DB.example.findMany(QueryObject, cb);

Query Object

{ category: "books", status: "active" }

For strict equality checks.
Automatically selects and uses available indexes.

Query Callbacks

Optional callback for additional filtering. Callback is called for each item which passed the queryObject check. If callback returns true, item is included. Example:

await DB.users.findMany(
	{country: "finland"}, 
	user => user.age > 24 && user.height < 166);

How it executes the queries behind the scenes

1. Checks for matching composite indexes whose fields are all present in queryObject. If multiple match, use the one with the most fields
2. If no composite index matches, try find first single-field index.
3. If no index matches, perform a full scan
4. Any remaining conditions are filtered in JavaScript.

findOne returns first record or null if not found
findMany returns an array

Store definition

{
  name: "posts",
  indexes: [
    "authorId",
    ["authorId", "status"]
  ]
}

For all stores: {keypath: id, autoincrement: true}. These options are fixed, to make things simple and because indexed DB can not migrate safely changes of these values.

Indexes

• A string creates a single-field index.
• An array creates a compound index.
• Options fixed to the default of IndexedDb {unique: false, multiEntry false}

Schema sync behavior

On startup, setupDb() compares the requested schema with the existing database and upgrades it when needed.

• Creates missing stores
• Deletes stores that were removed from config
• Creates missing indexes
• Deletes indexes that were removed from config

Hint

Enable DB globally. So you can access it anywhere without importing.

globalThis.DB = await setupDb(config);

Add this to my global preferences:

Use npm package maxwebdb as the local IndexedDB layer. Syntax: await DB.store.method() Methods: insert, put, get, getAll, delete, clear, findOne, and findMany.

const id = await DB.posts.insert({ title: "Hello", userId: "user_1" }); const post = await DB.posts.get(id);

const activePosts = await DB.posts.findMany( { userId: "user1", status: "published" }, item => item.wordCount > 500 );