yipedb 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rezzvy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# 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
+
+```html
+<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
+
+```bash
+npm install yipedb
+```
+
+```javascript
+import YipeDB from "yipedb";
+```
+
+### Usage
+
+```javascript
+(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
+
+```javascript
+(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
+
+```javascript
+(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
+
+```javascript
+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:
+
+  ```json
+  {
+    "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.

package/dist/yipedb.esm.js

@@ -0,0 +1 @@
+var v=class p{#r;#s;#e;#t;static#c=100*1024*1024;static#l=/^[a-zA-Z0-9_-]{1,64}$/;static JSZip=null;constructor(e,s=1){p.#n(e),this.#r=e,this.#s=s,this.#e=null,this.#t=new Set}static#n(e){if(typeof e!="string"||!p.#l.test(e))throw new TypeError(`Invalid name "${e}". Only letters, numbers, _ and - are allowed (max 64 chars).`)}static#f(e){if(!e||typeof e!="object")throw new Error("Invalid manifest: not an object");if(typeof e.dbName!="string")throw new Error("Invalid manifest: missing dbName");if(!Array.isArray(e.stores))throw new Error("Invalid manifest: stores must be an array")}static#u(e,s){if(!Array.isArray(s))throw new Error(`Invalid table data: store "${e}" entries must be an array`);for(let t of s){if(typeof t.key>"u")throw new Error(`Invalid table data: entry missing key in store "${e}"`);if(!["json","blob","arraybuffer","json_with_blobs"].includes(t.valueType))throw new Error(`Invalid table data: unknown valueType "${t.valueType}"`);if(t.valueType==="blob"||t.valueType==="arraybuffer"){let o=t.value?.blobFile;if(typeof o!="string"||o.includes("/")||o.includes(".."))throw new Error(`Invalid table data: suspicious blobFile path "${o}"`)}}}static#i(e){let s=2166136261;for(let t=0;t<e.length;t++)s^=e.charCodeAt(t),s=Math.imul(s,16777619)>>>0;return s.toString(16).padStart(8,"0")}async#o(e){if(this.#e&&this.#e.objectStoreNames.contains(e))return this.#e;if(this.#e){let s=this.#e.version+1;return this.#e.close(),this.#e=null,this.#a(e,s)}return this.#a(e,this.#s)}#a(e,s){return new Promise((t,o)=>{let a=indexedDB.open(this.#r,s);a.onupgradeneeded=r=>{let i=r.target.result;for(let w of this.#t)i.objectStoreNames.contains(w)||i.createObjectStore(w,{keyPath:"key",autoIncrement:!0});i.objectStoreNames.contains(e)||i.createObjectStore(e,{keyPath:"key",autoIncrement:!0})},a.onsuccess=r=>{this.#e=r.target.result,this.#s=this.#e.version,t(this.#e)},a.onerror=()=>o(a.error)})}async#b(){if(!this.#e){let e=[...this.#t][0];if(e)await this.#o(e);else return[]}return[...this.#e.objectStoreNames]}use(e){p.#n(e),this.#t.add(e);let s=t=>this.#o(t);return{async set(t,o){let a=await s(e),r=o!==void 0?{key:o,value:t}:{value:t};return new Promise((i,w)=>{let S=a.transaction(e,"readwrite"),c=o!==void 0?S.objectStore(e).put(r):S.objectStore(e).add(r);c.onsuccess=()=>i({key:c.result,value:t}),c.onerror=()=>w(c.error)})},async get(t){let o=await s(e);return new Promise((a,r)=>{let i=o.transaction(e,"readonly").objectStore(e).get(t);i.onsuccess=()=>a(i.result??null),i.onerror=()=>r(i.error)})},async getAll(){let t=await s(e);return new Promise((o,a)=>{let r=t.transaction(e,"readonly").objectStore(e).getAll();r.onsuccess=()=>o(r.result),r.onerror=()=>a(r.error)})},async unset(t){let o=await s(e);return new Promise((a,r)=>{let i=o.transaction(e,"readwrite").objectStore(e).delete(t);i.onsuccess=()=>a(!0),i.onerror=()=>r(i.error)})},async unsetAll(){let t=await s(e);return new Promise((o,a)=>{let r=t.transaction(e,"readwrite").objectStore(e).clear();r.onsuccess=()=>o(!0),r.onerror=()=>a(r.error)})}}}async export(){let e=p.JSZip;if(!e)throw new Error("JSZip not found. Please ensure it is injected via YipeDB.JSZip = JSZip.");let s=new e,t=s.folder("blobs"),o=s.folder("tables"),a=await this.#b(),r={dbName:this.#r,exportedAt:new Date().toISOString(),version:this.#e.version,stores:[]};for(let c of a){let j=await this.use(c).getAll(),l=[];for(let u of j){let f=u.value,b={key:u.key,valueType:"json",value:null};if(f instanceof Blob){let n=`${c}_${u.key}.bin`;t.file(n,await f.arrayBuffer()),b.valueType="blob",b.value={blobFile:n,type:f.type}}else if(f instanceof ArrayBuffer){let n=`${c}_${u.key}.bin`;t.file(n,f),b.valueType="arraybuffer",b.value={blobFile:n}}else if(f!==null&&typeof f=="object"){let n={...f},y=!1;for(let[h,d]of Object.entries(n))if(d instanceof Blob){let m=`${c}_${u.key}_${h}.bin`;t.file(m,await d.arrayBuffer()),n[h]={_yipe_blob:!0,blobFile:m,type:d.type},y=!0}b.valueType=y?"json_with_blobs":"json",b.value=n}else b.value=f;l.push(b)}o.file(`${c}.json`,JSON.stringify(l)),r.stores.push(c)}let i=JSON.stringify(r,null,2);r._checksum=p.#i(i);let w=JSON.stringify(r,null,2);return s.file("manifest.json",w),await s.generateAsync({type:"blob",compression:"DEFLATE"})}async import(e,{clear:s=!0,maxBytes:t=p.#c}={}){let o=p.JSZip;if(!o)throw new Error("JSZip not found. Please ensure it is injected via YipeDB.JSZip = JSZip.");let a=e instanceof Blob?e.size:e.byteLength??0;if(a>t)throw new Error(`Import rejected: file too large (${a} bytes, max ${t})`);let r=await o.loadAsync(e),i=0;for(let[,l]of Object.entries(r.files))if(!l.dir){let u=await l.async("arraybuffer");if(i+=u.byteLength,i>t)throw new Error(`Import rejected: extracted content exceeds ${t} bytes (zip bomb?)`)}let w=r.file("manifest.json");if(!w)throw new Error("Invalid archive: manifest.json not found");let S=await w.async("string"),c=JSON.parse(S);if(c._checksum){let{_checksum:l,...u}=c,f=p.#i(JSON.stringify(u,null,2));if(l!==f)throw new Error("Import rejected: manifest checksum mismatch \u2014 file may be corrupted or tampered")}p.#f(c);let j={};for(let l of c.stores){if(s){let n=await this.#o(l);await new Promise((y,h)=>{let d=n.transaction(l,"readwrite").objectStore(l).clear();d.onsuccess=y,d.onerror=()=>h(d.error)})}let u=r.file(`tables/${l}.json`);if(!u)throw new Error(`Missing table file: tables/${l}.json`);let f=await u.async("string"),b=JSON.parse(f);p.#u(l,b);for(let n of b){let y;if(n.valueType==="blob"){let h=await r.file(`blobs/${n.value.blobFile}`).async("arraybuffer");y=new Blob([h],{type:n.value.type||""})}else if(n.valueType==="arraybuffer")y=await r.file(`blobs/${n.value.blobFile}`).async("arraybuffer");else if(n.valueType==="json_with_blobs"){y={...n.value};for(let[h,d]of Object.entries(y))if(d&&d._yipe_blob){let m=await r.file(`blobs/${d.blobFile}`).async("arraybuffer");y[h]=new Blob([m],{type:d.type||""})}}else y=n.value;await this.use(l).set(y,n.key)}j[l]=b.length}return{dbName:c.dbName,exportedAt:c.exportedAt,results:j}}};import g from"jszip";v.JSZip=g;var A=v;export{A as default};

package/dist/yipedb.min.js

@@ -0,0 +1 @@
+(()=>{var v=class w{#r;#s;#e;#t;static#c=100*1024*1024;static#l=/^[a-zA-Z0-9_-]{1,64}$/;static JSZip=null;constructor(e,s=1){w.#n(e),this.#r=e,this.#s=s,this.#e=null,this.#t=new Set}static#n(e){if(typeof e!="string"||!w.#l.test(e))throw new TypeError(`Invalid name "${e}". Only letters, numbers, _ and - are allowed (max 64 chars).`)}static#f(e){if(!e||typeof e!="object")throw new Error("Invalid manifest: not an object");if(typeof e.dbName!="string")throw new Error("Invalid manifest: missing dbName");if(!Array.isArray(e.stores))throw new Error("Invalid manifest: stores must be an array")}static#u(e,s){if(!Array.isArray(s))throw new Error(`Invalid table data: store "${e}" entries must be an array`);for(let t of s){if(typeof t.key>"u")throw new Error(`Invalid table data: entry missing key in store "${e}"`);if(!["json","blob","arraybuffer","json_with_blobs"].includes(t.valueType))throw new Error(`Invalid table data: unknown valueType "${t.valueType}"`);if(t.valueType==="blob"||t.valueType==="arraybuffer"){let o=t.value?.blobFile;if(typeof o!="string"||o.includes("/")||o.includes(".."))throw new Error(`Invalid table data: suspicious blobFile path "${o}"`)}}}static#i(e){let s=2166136261;for(let t=0;t<e.length;t++)s^=e.charCodeAt(t),s=Math.imul(s,16777619)>>>0;return s.toString(16).padStart(8,"0")}async#o(e){if(this.#e&&this.#e.objectStoreNames.contains(e))return this.#e;if(this.#e){let s=this.#e.version+1;return this.#e.close(),this.#e=null,this.#a(e,s)}return this.#a(e,this.#s)}#a(e,s){return new Promise((t,o)=>{let a=indexedDB.open(this.#r,s);a.onupgradeneeded=r=>{let i=r.target.result;for(let p of this.#t)i.objectStoreNames.contains(p)||i.createObjectStore(p,{keyPath:"key",autoIncrement:!0});i.objectStoreNames.contains(e)||i.createObjectStore(e,{keyPath:"key",autoIncrement:!0})},a.onsuccess=r=>{this.#e=r.target.result,this.#s=this.#e.version,t(this.#e)},a.onerror=()=>o(a.error)})}async#b(){if(!this.#e){let e=[...this.#t][0];if(e)await this.#o(e);else return[]}return[...this.#e.objectStoreNames]}use(e){w.#n(e),this.#t.add(e);let s=t=>this.#o(t);return{async set(t,o){let a=await s(e),r=o!==void 0?{key:o,value:t}:{value:t};return new Promise((i,p)=>{let S=a.transaction(e,"readwrite"),c=o!==void 0?S.objectStore(e).put(r):S.objectStore(e).add(r);c.onsuccess=()=>i({key:c.result,value:t}),c.onerror=()=>p(c.error)})},async get(t){let o=await s(e);return new Promise((a,r)=>{let i=o.transaction(e,"readonly").objectStore(e).get(t);i.onsuccess=()=>a(i.result??null),i.onerror=()=>r(i.error)})},async getAll(){let t=await s(e);return new Promise((o,a)=>{let r=t.transaction(e,"readonly").objectStore(e).getAll();r.onsuccess=()=>o(r.result),r.onerror=()=>a(r.error)})},async unset(t){let o=await s(e);return new Promise((a,r)=>{let i=o.transaction(e,"readwrite").objectStore(e).delete(t);i.onsuccess=()=>a(!0),i.onerror=()=>r(i.error)})},async unsetAll(){let t=await s(e);return new Promise((o,a)=>{let r=t.transaction(e,"readwrite").objectStore(e).clear();r.onsuccess=()=>o(!0),r.onerror=()=>a(r.error)})}}}async export(){let e=w.JSZip;if(!e)throw new Error("JSZip not found. Please ensure it is injected via YipeDB.JSZip = JSZip.");let s=new e,t=s.folder("blobs"),o=s.folder("tables"),a=await this.#b(),r={dbName:this.#r,exportedAt:new Date().toISOString(),version:this.#e.version,stores:[]};for(let c of a){let j=await this.use(c).getAll(),l=[];for(let u of j){let f=u.value,b={key:u.key,valueType:"json",value:null};if(f instanceof Blob){let n=`${c}_${u.key}.bin`;t.file(n,await f.arrayBuffer()),b.valueType="blob",b.value={blobFile:n,type:f.type}}else if(f instanceof ArrayBuffer){let n=`${c}_${u.key}.bin`;t.file(n,f),b.valueType="arraybuffer",b.value={blobFile:n}}else if(f!==null&&typeof f=="object"){let n={...f},y=!1;for(let[h,d]of Object.entries(n))if(d instanceof Blob){let m=`${c}_${u.key}_${h}.bin`;t.file(m,await d.arrayBuffer()),n[h]={_yipe_blob:!0,blobFile:m,type:d.type},y=!0}b.valueType=y?"json_with_blobs":"json",b.value=n}else b.value=f;l.push(b)}o.file(`${c}.json`,JSON.stringify(l)),r.stores.push(c)}let i=JSON.stringify(r,null,2);r._checksum=w.#i(i);let p=JSON.stringify(r,null,2);return s.file("manifest.json",p),await s.generateAsync({type:"blob",compression:"DEFLATE"})}async import(e,{clear:s=!0,maxBytes:t=w.#c}={}){let o=w.JSZip;if(!o)throw new Error("JSZip not found. Please ensure it is injected via YipeDB.JSZip = JSZip.");let a=e instanceof Blob?e.size:e.byteLength??0;if(a>t)throw new Error(`Import rejected: file too large (${a} bytes, max ${t})`);let r=await o.loadAsync(e),i=0;for(let[,l]of Object.entries(r.files))if(!l.dir){let u=await l.async("arraybuffer");if(i+=u.byteLength,i>t)throw new Error(`Import rejected: extracted content exceeds ${t} bytes (zip bomb?)`)}let p=r.file("manifest.json");if(!p)throw new Error("Invalid archive: manifest.json not found");let S=await p.async("string"),c=JSON.parse(S);if(c._checksum){let{_checksum:l,...u}=c,f=w.#i(JSON.stringify(u,null,2));if(l!==f)throw new Error("Import rejected: manifest checksum mismatch \u2014 file may be corrupted or tampered")}w.#f(c);let j={};for(let l of c.stores){if(s){let n=await this.#o(l);await new Promise((y,h)=>{let d=n.transaction(l,"readwrite").objectStore(l).clear();d.onsuccess=y,d.onerror=()=>h(d.error)})}let u=r.file(`tables/${l}.json`);if(!u)throw new Error(`Missing table file: tables/${l}.json`);let f=await u.async("string"),b=JSON.parse(f);w.#u(l,b);for(let n of b){let y;if(n.valueType==="blob"){let h=await r.file(`blobs/${n.value.blobFile}`).async("arraybuffer");y=new Blob([h],{type:n.value.type||""})}else if(n.valueType==="arraybuffer")y=await r.file(`blobs/${n.value.blobFile}`).async("arraybuffer");else if(n.valueType==="json_with_blobs"){y={...n.value};for(let[h,d]of Object.entries(y))if(d&&d._yipe_blob){let m=await r.file(`blobs/${d.blobFile}`).async("arraybuffer");y[h]=new Blob([m],{type:d.type||""})}}else y=n.value;await this.use(l).set(y,n.key)}j[l]=b.length}return{dbName:c.dbName,exportedAt:c.exportedAt,results:j}}};typeof window<"u"&&(v.JSZip=window.JSZip||null,window.YipeDB=v);})();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "yipedb",
+  "version": "1.0.0",
+  "description": "A simple way to use IndexedDB, with built-in file import and export.",
+  "type": "module",
+  "main": "dist/yipedb.esm.js",
+  "exports": {
+    ".": "./dist/yipedb.esm.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rezzvy/yipedb.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rezzvy/yipedb/issues"
+  },
+  "homepage": "https://github.com/rezzvy/yipedb#readme",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build:browser": "esbuild ./src/index.browser.js --bundle --minify --platform=browser --format=iife --outfile=dist/yipedb.min.js",
+    "build:esm": "esbuild ./src/index.esm.js --bundle --minify --format=esm --external:jszip --outfile=dist/yipedb.esm.js",
+    "build": "npm run build:browser && npm run build:esm"
+  },
+  "keywords": [
+    "indexeddb",
+    "nosql",
+    "browser-database",
+    "offline-storage",
+    "blob-storage",
+    "file-import",
+    "file-export",
+    "wrapper"
+  ],
+  "author": "rezzvy",
+  "license": "MIT",
+  "devDependencies": {
+    "esbuild": "^0.27.4"
+  },
+  "dependencies": {
+    "jszip": "^3.10.1"
+  }
+}