IDBee :honeybee:

A lightweight, Promise-Based Wrapper designed to simplify the use of JavaScript's IndexedDB, making client-side database operations more intuitive.

Quick Start

Create a new database instance, open a connection, and perform transactions:

import { IDBee } from "idbee";

// Create a new database instance
const mydb = new IDBee();

// Open a connection with default settings
// Defaults: db name "idb", store name "app", store keyPath "id"
await mydb.open();

// Perform transactions
const result = await mydb.transaction(async ({ app }) => {
	await app.add({ value: { todo: "hello world" } });
	return await app.get();
});

console.log(result);
// Outputs: [{todo: 'hello world', id: 1}]

mydb.close();

await mydb.delete();

Installation

To install IDBee, run the following command in your project directory:

npm install idbee

Configuration

Setting the Database Name

Specify the name of your database using the name method.

| Arguments | Type | Default | Required | | --------- | -------- | ------- | -------- | | name | String | | |

mydb.name("mydb");

Specifying the Version

Set the version of your database. IndexedDB uses versions to manage schema changes.

| Arguments | Type | Default | Required | | --------- | -------- | ------- | -------- | | version | Number | 1 | true |

mydb.version(1);

Defining Object Stores and Indexes

Configure object stores with their respective key paths, auto-increment settings, and any indexes.

| Arguments | Type | Default | Required | | -------------------------------- | ---------- | ------- | -------- | | stores | Object[] | [] | | | stores[].name | String | | | | stores[].options | Object | | | | stores[].options.keyPath | String | id | | | stores[].options.autoIncrement | Boolean | true | | | stores[].indexes | Object[] | | | | stores[].indexes[].name | String | | | | stores[].indexes[].unique | Boolean | false | | | stores[].indexes[].multiEntry | Boolean | false | |

mydb.stores([
	{
		name: "users",
		// Defaults: options: { keyPath: "id", autoIncrement: true },
		indexes: [{ name: "firstName" }, { name: "age" }]
	},
	{
		name: "todos",
		options: { keyPath: null, autoIncrement: true },
		indexes: [{ name: "userId" }, { name: "todo" }, { name: "tags", multiEntry: true }]
	}
]);

Connecting to IndexedDB

Establish a connection to your IndexedDB and handle various database events with custom callbacks.

| Arguments | Type | Default | Required | | --------------------------- | ---------- | ------- | -------- | | callbacks | Object | {} | | | callbacks.onsuccess | Function | | | | callbacks.onerror | Function | | | | callbacks.onupgradeneeded | Function | | | | callbacks.onblocked | Function | | |

await mydb.open({
	onsuccess: (event) => {
		console.log("Database connected successfully.");
	},
	onerror: (event) => {
		console.error("An error occurred while connecting to the database.");
	},
	onupgradeneeded: (event) => {
		console.log("Database upgrade is required.");
	},
	onblocked: (event) => {
		console.warn("Database connection is blocked.");
	}
});

Versioning

Update the version and modify the object stores and indexes:

mydb.version(2).stores([
	{
		name: "users",
		indexes: [{ name: "firstName" }, { name: "lastName" }, { name: "age" }]
	},
	{
		name: "todos",
		options: { keyPath: null, autoIncrement: true },
		indexes: [{ name: "userId" }, { name: "tags", multiEntry: true }]
	},
	{ name: "products" }
]);

mydb.version(3).stores([
	{
		name: "users",
		indexes: [{ name: "firstName" }, { name: "lastName" }, { name: "age" }]
	},
	// {
	//   name: "todos",
	//   options: { keyPath: null, autoIncrement: true },
	//   indexes: [{ name: "userId" }, { name: "tags", multiEntry: true }],
	// },
	// This will remove the entire objectStore including its data.
	,
]);

Custom logic for handling a database upgrade:

await mydb.version(4).open({
	onupgradeneeded: (event) => {
		const db = event.target.result;
		db.createObjectStore("todos", { keyPath: "id" });
	}
});

await mydb.version(5).open({
	onupgradeneeded: (event) => {
		const db = event.target.result;
		// db.createObjectStore("todos", { keyPath: "id" });
		// This will remove the entire objectStore including its data.
	}
});

Handling Transactions

Transactions allow you to execute a series of database operations as a single unit.

| Arguments | Type | Default | Required | | ---------- | ---------- | ------- | -------- | | stores | String[] | | | | callback | Function | | true |

const result = await mydb.transaction();
// Outputs: ["users", "todos"]

await mydb.transaction(["users"], async (stores) => {
	const { users } = stores;

	// Your transactional operations here

	return { success: true };
});
// Outputs: { success: true };

Adding Data

Transactions provide a straightforward way to add data to your object stores.

| Arguments | Type | Default | Required | | --------- | -------- | ------- | -------- | | options | Object | {} | | | key | Any | | | | value | Object | | true |

await mydb.transaction(async ({ users, todos }) => {
	const userId = await users.add({
		value: {
			firstName: "John",
			lastName: "Doe",
			age: 50
		}
	});
	// Outputs: The primary key of the new user, e.g., 1

	const todoList = [
		{
			userId: userId,
			todo: "Go for a run",
			tags: ["health", "fitness"]
		},
		{
			userId: userId,
			todo: "Learn a new language",
			tags: ["education", "self-improvement"]
		}
	];

	// Add multiple todo items for the user
	for (const todo of todoList) {
		await todos.add({
			value: todo
		});
	}
});

Demo Data

Users

| # | Key ("id") | Value | | --- | ---------- | -------------------------------------------------------- | | 0 | 1 | { id: 1, firstName: "John", lastName: "Doe", age: 50 } |

Todos

| # | Key | Value | | --- | ---- | -------------------------------------------------------------------------------------- | | 0 | 1 | { userId: 1, todo: "Go for a run", tags: ["health", "fitness"] } | | 1 | 2 | { userId: 1, todo: "Learn a new language", tags: ["education", "self-improvement"] } | | 2 | 3 | { userId: 5, todo: "Cook a new recipe", tags: ["cooking", "food"] } | | 3 | 4 | { userId: 3, todo: "Write a journal entry", tags: ["reflection", "writing"] } | | 4 | 5 | { userId: 5, todo: "Paint a landscape", tags: ["creativity", "art"] } | | 5 | 6 | { userId: 2, todo: "Plan a weekend trip", tags: ["travel", "adventure"] } | | 6 | 7 | { userId: 8, todo: "Visit a museum", tags: ["culture", "learning"] } | | 7 | 8 | { userId: 5, todo: "Start a blog", tags: ["writing", "technology"] } | | 8 | 9 | { userId: 9, todo: "Practice meditation", tags: ["mindfulness", "health"] } | | 9 | 10 | { userId: 4, todo: "Organize a meetup", tags: ["social", "networking"] } |

Retrieving Data

Transactions provide a straightforward way to add data to your object stores.

Get One

| Arguments | Type | Default | Required | | --------------- | -------- | ------- | -------- | | options | Object | {} | | | options.key | Any | | true | | options.index | Any | | |

await mydb.transaction(["todos"], async ({ todos }) => {
	await todos.get({ key: 1 });
	// Outputs: { userId: 1, todo: "Go for a run", tags: ["health", "fitness"] }

	await todos.get({ index: "userId", key: 5 });
	// Outputs: { userId: 5, todo: "Cook a new recipe", tags: ["cooking", "food"] }
});

Get All

| Arguments | Type | Default | Required | | --------------------- | -------- | ------- | -------- | | options | Object | {} | | | options.index | Any | | | | options.query | Object | | | | options.query.start | Any | | | | options.query.end | Any | | | | options.query.only | Any | | | | options.count | Number | | |

await mydb.transaction(["todos"], async ({ todos }) => {
	await todos.get();
	// Outputs: [{ 1 ... 10 }]

	await todos.get({ query: { start: 3 } });
	// Outputs: [{ 3 ... 10 }]

	await todos.get({ index: "userId" });
	// Outputs: [{ 1 ... 10 }] sort by userId

	await todos.get({ index: "userId", query: { start: 7, end: 10 } });
	// Outputs: [
	//   { userId: 8, todo: "Visit a museum", tags: ["culture", "learning"] }
	//   { userId: 9, todo: "Practice meditation", tags: ["mindfulness", "health"] }
	// ]

	await todos.get({ index: "tags", query: { only: "health" } });
	// Outputs: [
	//   { userId: 1, todo: "Go for a run", tags: ["health", "fitness"] }
	//   { userId: 9, todo: "Practice meditation", tags: ["mindfulness", "health"] }
	// ]

	await todos.get({ index: "userId", query: { only: 5 }, count: 2 });
	// Outputs: [
	//   { userId: 5, todo: "Cook a new recipe", tags: ["cooking", "food"] }
	//   { userId: 5, todo: "Paint a landscape", tags: ["creativity", "art"] }
	// ]
});

Get with Cursor

| Arguments | Type | Default | Required | | --------------------- | ---------- | ------- | -------- | | options | Object | {} | | | options.where | Function | | true | | options.index | Any | | | | options.query | Object | | | | options.query.start | Any | | | | options.query.end | Any | | | | options.query.only | Any | | | | options.direction | String | | |

await mydb.transaction(["todos"], async ({ todos }) => {
	await todos.get({
		where: (value) => {
			if (value.userId === 5) {
				return value;
			}
		},
		direction: "prev"
	});
	// Outputs: [
	//   { userId: 5, todo: "Start a blog", tags: ["writing", "technology"] }
	//   { userId: 5, todo: "Paint a landscape", tags: ["creativity", "art"] }
	//   { userId: 5, todo: "Cook a new recipe", tags: ["cooking", "food"] }
	// ]

	await todos.get({
		index: "userId",
		where: (value) => (value.userId === 5 ? value : null),
		direction: "nextunique"
	});
	// Outputs: [
	//   { userId: 5, todo: "Cook a new recipe", tags: ["cooking", "food"] }
	// ]
});

Update Data

Update and Create

| Arguments | Type | Default | Required | | --------------- | -------- | ------- | -------- | | options | Object | {} | | | options.key | Any | | | | options.value | Object | | true |

await mydb.transaction(async ({ users, todos }) => {
	await users.put({
		value: {
			id: 1,
			firstName: "Jane",
			lastName: "Doe",
			age: 50
		}
	});
	// Outputs: 1

	await todos.put({
		key: 2,
		value: {
			userId: 1,
			todo: "Learn Javascript",
			tags: ["education", "self-improvement"]
		}
	});
	// Outputs: 2
});

Update with Cursor

| Arguments | Type | Default | Required | | --------------------- | ---------- | ------- | -------- | | options | Object | {} | | | options.where | Function | | true | | options.index | Any | | | | options.query | Object | | | | options.query.start | Any | | | | options.query.end | Any | | | | options.query.only | Any | | | | options.direction | String | | |

await mydb.transaction(["todos"], async ({ todos }) => {
	await todos.put({
		where: (value) => {
			if (value.userId === 1) {
				value.completed = true;

				return value;
			}
		}
	});
	// Outputs: [1, 2]
});

Delete Data

Delete One

| Arguments | Type | Default | Required | | --------------- | -------- | ------- | -------- | | options | Object | {} | | | options.key | Any | | true | | options.index | Any | | |

await mydb.transaction(async ({ todos }) => {
	await todos.delete({
		key: 4
	});
	// { userId: 3, todo: "Write a journal entry", tags: ["reflection", "writing"] }

	await todos.delete({
		index: "UserId",
		key: 4
	});
	// { userId: 4, todo: "Organize a meetup", tags: ["social", "networking"] }
});

Delete All

| Arguments | Type | Default | Required | | --------------- | -------- | ------- | -------- | | options | Object | {} | | | options.key | Any | | true | | options.index | Any | | |

await mydb.transaction(async ({ users }) => {
	await users.delete();
});

Delete with Cursor

| Arguments | Type | Default | Required | | --------------------- | ---------- | ------- | -------- | | options | Object | {} | | | options.where | Function | | true | | options.index | Any | | | | options.query | Object | | | | options.query.start | Any | | | | options.query.end | Any | | | | options.query.only | Any | | | | options.direction | String | | |

await mydb.transaction(["todos"], async ({ todos }) => {
	await todos.delete({
		where: (value) => {
			if (value.userId === 5) {
				return true;
			}
		}
	});
	// { userId: 5, todo: "Cook a new recipe", tags: ["cooking", "food"] }
	// { userId: 5, todo: "Paint a landscape", tags: ["creativity", "art"] }
	// { userId: 5, todo: "Start a blog", tags: ["writing", "technology"] }
});