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/[email protected]/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.