YipeDB

A simple way to use IndexedDB, with built-in file import and export.

Overview

YipeDB simplifies working with IndexedDB Web API by removing its complexity.

• Store JSON, objects, and binary data (Blob / ArrayBuffer)
• Export entire database as a ZIP archive
• Import database from a ZIP archive
• Auto-increment or custom keys
• No schema setup required

Installation & Usage

Installation

Browser

<script src="https://cdn.jsdelivr.net/npm/jszip@3.10.1/dist/jszip.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/rezzvy/yipedb@056f5d2/dist/yipedb.min.js"></script>

Node

npm install yipedb

import YipeDB from "yipedb";

Usage

(async () => {
  const db = new YipeDB("MyAppData");

  await db.use("users").set({ name: "Alice", role: "Admin" });

  const users = await db.use("users").getAll();
  console.log(users);
})();

Examples

Auto-increment key vs custom key

(async () => {
  const db = new YipeDB("TestDB");

  // auto key
  await db.use("users").set({ name: "Nurul" });

  // custom key
  await db.use("users").set({ name: "Trisha" }, "user_2");
})();

Export database as downloadable file

(async () => {
  const db = new YipeDB("MyAppData");
  await db.use("test").set("Hello!");

  const zipBlob = await db.export();
  const url = URL.createObjectURL(zipBlob);
  const a = document.createElement("a");
  a.href = url;
  a.download = "backup.zip";
  a.click();
})();

Import database from file

const db = new YipeDB("MyAppData");
const input = document.querySelector("input[type=file]");

input.addEventListener("change", async () => {
  const file = input.files[0];
  const result = await db.import(file);
});

Documentation

API Reference

new YipeDB(dbName, version?)

Creates a new database instance.

Parameter	Type	Description
dbName	string	Database name (max 64 chars, alphanumeric, _, -)
version	number	Database version (default: 1)

db.use(tableName)

Access or create a table (object store).

Parameter	Type	Description
tableName	string	Table name

Returns: An object containing the following table operation methods.

Note

All table methods are async and return a Promise.

Method	Description	Returns
set(value, id?)	Insert or update data	Promise<{ key: any, value: any }> The inserted key and value.
get(id)	Get single entry	Promise<any | null> The stored entry object, or null if not found.
getAll()	Get all entries	Promise<Array<any>> An array of all stored entry objects.
unset(id)	Delete entry	Promise<boolean> Resolves to true upon successful deletion.
unsetAll()	Clear table	Promise<boolean> Resolves to true upon successful clearing.

db.export()

Exports the entire database.

Returns	Description
Promise<Blob>	ZIP file containing all data

db.import(file, options?)

Imports a database from a ZIP file.

Parameter	Type	Default	Description
file	Blob | ArrayBuffer	-	ZIP archive
options.clear	boolean	true	Clear existing data before import
options.maxBytes	number	100MB	Maximum allowed size

Returns:

Property	Type	Description
dbName	string	Name of the imported database
exportedAt	string	ISO Timestamp of when the data was originally exported
results	object	Object containing the number of successfully imported rows per table (e.g., { "users": 15 })

Export / Import Details

Export structure

The generated ZIP file contains:

manifest.json
tables/
  *.json
blobs/
  *.bin

• manifest.json Contains metadata, store list, version, timestamp, and checksum.

• tables/*.json Each table is exported as structured entries:

  {
    "key": 1,
    "valueType": "json | blob | arraybuffer | json_with_blobs",
    "value": ...
  }

• blobs/ Binary data extracted and stored separately for safety and portability.

Supported value types

Type	Description
json	Plain JSON values
blob	Stored as binary file
arraybuffer	Stored as binary file
json_with_blobs	Object containing embedded Blob fields

Import behavior

• Validates ZIP structure and manifest
• Verifies checksum (basic integrity check)
• Prevents zip bomb attacks via size limits
• Restores all tables and binary data correctly

Contributing

There's always room for improvement. Feel free to contribute!

Licensing

The project is licensed under the MIT License. Check the license file for more details.