/bxd

📦 Object relational mapping for IndexedDB

Primary LanguageTypeScriptMIT LicenseMIT

bxd

bxd

BoxDB is a promise-based browser ORM for IndexedDB





npm bundle size npm bundle size zero dependency
typescript 
import BoxDB from 'bxd';

const db = new BoxDB('my-database', 1);

// Define your box (Object store)
const User = db.create('user', {
  id: {
    type: BoxDB.Types.NUMBER,
    key: true, // This property is in-line-key
  },
  name: {
    type: BoxDB.Types.STRING,
    index: true, // This property is index
  },
  age: BoxDB.Types.NUMBER,
});

await db.open();

// Basics
await User.add({ id: 1, name: 'Tom', age: 10 });
await User.get(1);
await User.put({ id: 1, name: 'Tommy', age: 12 });
await User.delete(1);

// find(range, ...filters) method using IDBCursor
// Get records
const records = await User.find().get();

// filter & sort & limit
await User.find(
  null,
  (user) => user.id % 2 !== 0,
  (user) => user.age > 10,
  (user) => user.name.includes('y'),
).get(BoxDB.Order.DESC, 10);

// Update records (with filter)
await User
  .find(null, (user) => user.age !== 0)
  .update({ name: 'Timmy' });

// Delete records (with IDBValidKey & IDBRange + IDBIndex)
await User
  .find({
    value: BoxDB.Range.equal('Timmy'),
    index: 'name',
  })
  .delete();

// Do multiple tasks in one transaction
await db.transaction(
  User.$put({ id: 1, name: 'Tim', age: 20 }),
  User.$add({ id: 2, name: 'Jessica', age: 15 }),
  User.$add({ id: 3, name: 'Ellis', age: 13 }),
  User
    .$find({ value: 3 })
    .put({ name: 'Tina' }),
  BoxDB.interrupt(); // You can stop transaction like this!
  User.$delete(2),
  User
    .$find(null, (user) => user.age < 20)
    .put({ name: 'Young' }),
);

// And other IndexedDB API features!
await User.count(); // Get all records count
await User.clear(); // Clear all records

📃 Table of Contents

🌟 Features

  • Promise based ORM
  • User friendly and easy to use
  • Lightweight(< 10kb) IndexedDB wrapper
  • Zero dependency
  • Database and object store version management
  • Data validation and transaction control via model (box)
  • ACID(Atomicity, Consistency, Isolation, Durability) guaranteed with transaction
  • Supports TypeScript
  • Works on Web workers

🌍 Browsers Support

Edge
IE		 Edge
Edge		 Firefox
Firefox		 Chrome
Chrome		 Safari
Safari		 iOS Safari
iOS Safari		 Samsung
Samsung		 Opera
Opera
11 12~ 10~ 23~ 10~ 10~ 4~ 15~
  • Test features in your browser here.
  • Checkout IE11 test here.

🛠 Installation

npm install bxd

In script tag:

<script src="https://cdn.jsdelivr.net/npm/bxd@latest/dist/bxd.min.js"></script>

Looking for IE? Go to this page

📖 Documentation

Go to documentation!

🌱 Example

Example

🔥 Issue

Opening an issue or feature request here

👨‍💻 Development

# Install dependencies
npm install

# Test
npm run test

# Build
npm run build

🎨 Resources

🍀 License

MIT