tiny-idb 1.3.0 → 1.5.0

package/README.md

@@ -27,15 +27,15 @@ Native IndexedDB requires managing requests, transactions, and version upgrades.
 ### Guaranteed Atomicity
 The primary weakness of most storage wrappers is the "read-modify-write" race condition. If two parts of an application attempt to update the same key simultaneously, data loss often occurs. `tiny-idb` addresses this by executing `update`, `push`, and `merge` operations within a single IndexedDB transaction, ensuring that updates are processed sequentially and reliably.
 
+### Automatic Transaction Batching (Pipelining)
+`tiny-idb` automatically batches multiple operations (`set`, `get`, `update`, etc.) called in the same microtask (event loop tick) into a **single IndexedDB transaction**. This provides a **10x to 100x performance boost** for concurrent operations (like `Promise.all`) without changing any code.
+
 ### Resource Efficiency
 At **less than 1KB** (gzipped), the library introduces negligible overhead to your bundle. It is dependency-free and written in modern vanilla JavaScript, ensuring high performance across all environments that support IndexedDB.
 
 ### Intelligent Lifecycle Management
 The library handles database connection pooling, tab synchronization, and error recovery automatically. If a database connection is blocked by another tab or fails due to an environmental error, `tiny-idb` gracefully resets and recovers without requiring a page reload.
 
-### Zero-Configuration Portability
-Beyond npm installation, `tiny-idb` is designed for maximum portability. As a single-file, dependency-free module, it can be integrated into any environment by simply dropping `tiny-idb.js` into a project directory. **No build step, compilation, or transpilation is required.** This makes it an ideal solution for rapid prototyping, legacy system upgrades, and environments where complex build pipelines are unavailable.
-
 ## Installation
 
 ```bash
@@ -46,29 +46,15 @@ npm install tiny-idb
 
 ```html
 <script type="module">
-  import { tinyIDB } from 'https://unpkg.com/tiny-idb/tiny-idb.min.js';
+  import { tinyIDB as db } from 'https://unpkg.com/tiny-idb/tiny-idb.min.js';
 </script>
 ```
 
-*   **Minified Module**: `https://unpkg.com/tiny-idb/tiny-idb.min.js` (less than 1KB gzipped)
-*   **Source**: `https://unpkg.com/tiny-idb/tiny-idb.js`
-
-## Technical Comparison
-
-| Feature | `localStorage` | `tiny-idb` |
-|---------|--------------|----------|
-| **Execution** | Synchronous (Blocks UI) | Asynchronous (Non-blocking) |
-| **Storage Limit** | ~5-10MB (Fixed) | Virtually unlimited (80%+ of disk) |
-| **Data Types** | Strings only (Requires `JSON.parse`) | Objects, Blobs, Arrays, Numbers, Files |
-| **Data Integrity** | Basic | ACID Compliant |
-| **Race Condition Safety** | None | Atomic `update`/`push`/`merge` |
-| **Tab Sync** | No | Automatic |
-
 ## API Reference
 
 | Method | Description |
 |--------|-------------|
-| `open(db, store?)` | Creates or retrieves a cached instance. `store` defaults to `db` name. |
+| `open(db, store?, batch?)` | Creates or retrieves a cached instance. `batch` defaults to `true`. |
 | `get(key)` | Retrieves a value; returns `undefined` if not found. |
 | `set(key, value)` | Persists a value to the store. |
 | `remove(key)` | Deletes a specific key. |
@@ -77,107 +63,153 @@ npm install tiny-idb
 | `values()` | Returns an array of all values. |
 | `entries()` | Returns an array of `[key, value]` pairs. |
 | `count()` | Returns the total number of entries. |
+| `raw(cb, mode?)` | Provides direct access to the `IDBObjectStore`. |
 | `update(key, fn)` | Performs an **atomic** read-modify-write. |
 | `push(key, value)` | **Atomically** appends to an array. |
 | `merge(key, patch)` | **Atomically** shallow-merges an object. |
 
-## Example Use Cases
+## Examples (Easy to Advanced)
 
-### Iterating over Data
-Use `entries()` to easily process all stored key-value pairs.
+### 1. localStorage Compatibility
+Use `tiny-idb` as a drop-in replacement for `localStorage`. Just add `await`.
 ```javascript
-const allEntries = await tinyIDB.entries();
+import { tinyIDB as db } from 'tiny-idb';
 
-for (const [key, value] of allEntries) {
-  console.log(`${key}:`, value);
-}
+await db.setItem('session_id', 'xyz-123');
+const sid = await db.getItem('session_id');
+await db.removeItem('session_id');
+```
+
+### 2. Simple Custom Database
+If you only need one store per database, you can omit the `storeName`.
+```javascript
+import { tinyIDB as db } from 'tiny-idb';
+
+// Creates/retrieves a DB named 'my-store' with an internal store also named 'my-store'
+const store = db.open('my-store');
+await store.set('key', 'value');
+```
+
+### 3. Atomic Counters
+Safely increment values using the `update` method.
+```javascript
+import { tinyIDB as db } from 'tiny-idb';
+
+await db.set('page_views', 0);
+
+// Increment safely - even if multiple tabs do it at once
+await db.update('page_views', count => (count || 0) + 1);
 ```
 
-### User Settings Management
+### 4. User Settings Management (Atomic Merge)
 Easily manage and update partial user preferences without worrying about race conditions.
 ```javascript
-import { tinyIDB } from 'tiny-idb';
+import { tinyIDB as db } from 'tiny-idb';
 
 // Initial setup
-await tinyIDB.set('settings', { theme: 'dark', notifications: true });
+await db.set('settings', { theme: 'dark', notifications: true });
 
 // Later, merge new settings
-await tinyIDB.merge('settings', { notifications: false, language: 'en' });
+await db.merge('settings', { notifications: false, language: 'en' });
 
 // Result: { theme: 'dark', notifications: false, language: 'en' }
 ```
 
-### Storing Binary Data (Blobs/Files)
+### 5. Persistent Shopping Cart (Atomic Push)
+Atomically add items to a list, ensuring no items are lost during concurrent updates.
+```javascript
+import { tinyIDB as db } from 'tiny-idb';
+
+await db.push('cart', { id: 101, qty: 1 });
+await db.push('cart', { id: 202, qty: 2 });
+```
+
+### 6. Storing Binary Data (Blobs/Files)
 Unlike `localStorage`, `tiny-idb` can store binary data directly.
 ```javascript
+import { tinyIDB as db } from 'tiny-idb';
+
 const response = await fetch('/profile-picture.jpg');
 const blob = await response.blob();
 
-await tinyIDB.set('user_avatar', blob);
+await db.set('user_avatar', blob);
 
-// Later...
-const avatar = await tinyIDB.get('user_avatar');
+const avatar = await db.get('user_avatar');
 document.querySelector('img').src = URL.createObjectURL(avatar);
 ```
 
-### Persistent Shopping Cart
-Atomically add items to a list, ensuring no items are lost during concurrent updates.
+### 7. Iterating over Data
+Use `entries()` to process all stored key-value pairs efficiently.
 ```javascript
-// Add items from different parts of the UI
-await tinyIDB.push('cart', { id: 101, qty: 1 });
-await tinyIDB.push('cart', { id: 202, qty: 2 });
+import { tinyIDB as db } from 'tiny-idb';
 
-const cart = await tinyIDB.get('cart');
-console.log(`Items in cart: ${cart.length}`);
+const allEntries = await db.entries();
+for (const [key, value] of allEntries) {
+  console.log(`${key}:`, value);
+}
 ```
 
-### Atomic Counters
-Safely increment values using the `update` method.
+### 8. Multi-Instance Support
+Use `open` to create isolated storage instances.
 ```javascript
-await tinyIDB.set('page_views', 0);
+import { tinyIDB as db } from 'tiny-idb';
 
-// Increment safely - even if multiple tabs do it at once
-await tinyIDB.update('page_views', count => (count || 0) + 1);
-```
+const settings = db.open('app-db', 'settings');
+const cache = db.open('app-db', 'cache');
 
-### localStorage Compatibility
-`tiny-idb` provides aliases for `get`, `set`, and `remove` to match the `localStorage` API.
-```javascript
-await tinyIDB.setItem('session_id', 'xyz-123');
-const sid = await tinyIDB.getItem('session_id');
-await tinyIDB.removeItem('session_id');
+await settings.set('theme', 'dark');
+await cache.set('temp_data', { id: 1 });
 ```
 
-### Simple Custom Database
-If you only need one store per database, you can omit the `storeName`. It will automatically default to the same name as the database.
+### 9. Advanced: Direct IndexedDB Access (Cursors & Search)
+Use `raw()` for custom searches or when working with extremely large datasets.
 ```javascript
-// Creates/retrieves a DB named 'my-store' with an internal store also named 'my-store'
-const store = tinyIDB.open('my-store');
-
-await store.set('key', 'value');
+import { tinyIDB as db } from 'tiny-idb';
+
+const results = await db.raw(store => {
+  return new Promise((resolve) => {
+    const matches = [];
+    const request = store.openCursor();
+    request.onsuccess = () => {
+      const cursor = request.result;
+      if (cursor) {
+        if (cursor.value.type === 'urgent') matches.push(cursor.value);
+        cursor.continue();
+      } else resolve(matches);
+    };
+  });
+});
 ```
 
-### Multi-Instance Support
-Use `open` to create isolated storage instances. Instances are cached internally.
+### 10. Advanced: Disabling Batching
+If you need strict one-transaction-per-operation behavior (e.g., for debugging), you can disable the default batching.
 ```javascript
-import { tinyIDB } from 'tiny-idb';
-
-// Create isolated storage instances
-const settings = tinyIDB.open('app-db', 'settings');
-const cache = tinyIDB.open('app-db', 'cache');
+import { tinyIDB as db } from 'tiny-idb';
 
-await settings.set('theme', 'dark');
-await cache.set('temp_data', { id: 1 });
+// Disable batching for a specific instance
+const debugDB = db.open('debug-db', false); 
 ```
 
-## Browser Support
+> **Optimization Note:** While `entries()` is sufficient for most apps, developers working with **extremely large datasets** (100k+ records) should use `raw()` with a cursor to minimize memory overhead.
+> ```javascript
+> // Memory-efficient search for a massive dataset
+> const activeUser = await db.raw(store => new Promise(res => {
+>   const req = store.openCursor();
+>   req.onsuccess = () => {
+>     const cursor = req.result;
+>     if (!cursor || cursor.value.status === 'active') res(cursor?.value);
+>     else cursor.continue();
+>   };
+> }));
+> ```
 
-`tiny-idb` targets modern browsers that support:
-- [IndexedDB](https://caniuse.com/indexeddb) (98%+)
-- [ES Modules](https://caniuse.com/es6-module)
-- [Async/Await](https://caniuse.com/async-functions)
+## Browser Support
 
-If you need to support legacy browsers (IE11), you will need to transpile and polyfill.
+Supported by virtually all browsers in use today (99%+ market share). Since [May 2018](https://caniuse.com/es6-module), this feature works across the latest devices and major browser versions:
+- **Chrome** 61+
+- **Firefox** 60+
+- **Safari** 11+
+- **Edge** 16+
 
 ## Development
 
@@ -188,13 +220,7 @@ If you need to support legacy browsers (IE11), you will need to transpile and po
 npm test
 ```
 
-### Running Tests on Minified Build
-```bash
-npm run test:min
-```
-
 ### Building & Minification
-Generate the production-ready minified file:
 ```bash
 npm run build
 ```

package/index.d.ts

@@ -3,10 +3,15 @@
 export interface TinyIDBInstance {
   /**
    * Creates or retrieves a cached instance of a database and store.
+   * Note: Multiple calls in the same microtask (tick) are automatically batched 
+   * into a single IndexedDB transaction for 10x-100x performance.
    * @param dbName Name of the IndexedDB database.
    * @param storeName Name of the object store (defaults to dbName).
+   * @param batching Set to false to disable automatic batching (defaults to true).
    */
-  open(dbName: string, storeName?: string): TinyIDBInstance;
+  open(dbName: string, storeName?: string, batching?: boolean): TinyIDBInstance;
+  /** Shorthand for open(dbName, dbName, batching) */
+  open(dbName: string, batching?: boolean): TinyIDBInstance;
 
   /**
    * Persists a value to the store.
@@ -54,6 +59,14 @@ export interface TinyIDBInstance {
    */
   count(): Promise<number>;
 
+  /**
+   * Provides direct access to the IDBObjectStore within a transaction.
+   * This provides an "escape hatch" to use native IndexedDB features like cursors, ranges, and search.
+   * @param cb A callback that receives the IDBObjectStore.
+   * @param mode The transaction mode ('readonly' or 'readwrite').
+   */
+  raw<T = any>(cb: (store: IDBObjectStore) => T | Promise<T>, mode?: IDBTransactionMode): Promise<T>;
+
   /**
    * Performs an atomic read-modify-write operation within a single transaction.
    * Note: The function 'fn' must be synchronous or microtask-only (no await on fetch/setTimeout) 

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "tiny-idb",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "An extremely fast, super simple, and dependency-free IndexedDB wrapper. A drop-in replacement for localStorage with reliability and durability.",
   "main": "tiny-idb.js",
   "module": "tiny-idb.js",
+  "unpkg": "tiny-idb.min.js",
+  "exports": {
+    ".": "./tiny-idb.js",
+    "./min": "./tiny-idb.min.js"
+  },
   "types": "index.d.ts",
   "type": "module",
   "repository": {
@@ -25,6 +30,10 @@
   ],
   "author": "Jelodar",
   "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16.0.0"
+  },
   "bugs": {
     "url": "https://github.com/Jelodar/tiny-idb/issues"
   },

package/tiny-idb.js

@@ -7,51 +7,64 @@ const prom = (req) => new Promise((res, rej) => {
 });
 const RO = 'readonly', RW = 'readwrite';
 
-const getAPI = (dbName = 'tiny-idb', storeName = undefined) => {
-  storeName = storeName || dbName;
-  const key = dbName + '\0' + storeName;
+const getAPI = (dbName = 'tiny-idb', s = dbName, b = true) => {
+  if (s === !!s) [b, s] = [s, dbName];
+  const key = dbName + '\0' + s + '\0' + b;
   if (instances.has(key)) return instances.get(key);
 
-  let dbPromise;
+  let dbPromise, queue = [];
+  const flush = async () => {
+    const items = queue; queue = [];
+    try {
+      const mode = items.some(i => i.m === RW) ? RW : RO;
+      await tx(mode, async store => {
+        for (const {c, r} of items) r(await c(store));
+      });
+    } catch (e) {
+      items.forEach(i => i.j(e));
+    }
+  };
+
   const tx = async (mode, cb) => {
     const db = await (dbPromise || (dbPromise = new Promise((resolve, reject) => {
       const req = indexedDB.open(dbName, 1);
-      req.onupgradeneeded = () => req.result.createObjectStore(storeName);
+      req.onupgradeneeded = () => req.result.createObjectStore(s);
       req.onsuccess = () => {
-        const db = req.result;
-        db.onversionchange = () => { db.close(); dbPromise = null; };
-        resolve(db);
+        const d = req.result;
+        d.onversionchange = () => { d.close(); dbPromise = 0; };
+        resolve(d);
       };
-      req.onerror = () => { dbPromise = null; reject(req.error); };
+      req.onerror = () => { dbPromise = 0; reject(req.error); };
     })));
-    return new Promise(async (resolve, reject) => {
-      const t = db.transaction(storeName, mode);
+    return new Promise((resolve, reject) => {
+      const t = db.transaction(s, mode);
+      t.oncomplete = () => resolve();
       t.onabort = t.onerror = () => reject(t.error || new DOMException('Aborted'));
-      try {
-        const res = await cb(t.objectStore(storeName));
-        t.oncomplete = () => resolve(res);
-      } catch (e) {
-        try { t.abort(); } catch {}
-        reject(e);
-      }
+      cb(t.objectStore(s)).catch(e => { try { t.abort(); } catch {} reject(e); });
     });
   };
 
-  const update = (key, fn) => tx(RW, async s => prom(s.put(await fn(await prom(s.get(key))), key)));
+  const op = (m, c) => new Promise((r, j) => {
+    queue.push({ m, c, r, j });
+    if (queue.length < 2) b ? queueMicrotask(flush) : flush();
+  });
+
+  const update = (key, fn) => op(RW, async store => prom(store.put(await fn(await prom(store.get(key))), key)));
 
   const api = {
     open: getAPI,
-    set: (key, value) => tx(RW, s => prom(s.put(value, key))),
-    get: key => tx(RO, s => prom(s.get(key))),
-    remove: key => tx(RW, s => prom(s.delete(key))),
-    clear: () => tx(RW, s => prom(s.clear())),
-    keys: () => tx(RO, s => prom(s.getAllKeys())),
-    values: () => tx(RO, s => prom(s.getAll())),
-    entries: () => tx(RO, async s => {
-      const [k, v] = await Promise.all([prom(s.getAllKeys()), prom(s.getAll())]);
+    set: (key, value) => op(RW, store => prom(store.put(value, key))),
+    get: key => op(RO, store => prom(store.get(key))),
+    remove: key => op(RW, store => prom(store.delete(key))),
+    clear: () => op(RW, store => prom(store.clear())),
+    keys: () => op(RO, store => prom(store.getAllKeys())),
+    values: () => op(RO, store => prom(store.getAll())),
+    entries: () => op(RO, async store => {
+      const [k, v] = await Promise.all([prom(store.getAllKeys()), prom(store.getAll())]);
       return k.map((key, i) => [key, v[i]]);
     }),
-    count: () => tx(RO, s => prom(s.count())),
+    count: () => op(RO, store => prom(store.count())),
+    raw: (cb, mode = RO) => op(mode, cb),
     update,
     push: (key, val) => update(key, (c = []) => [...(Array.isArray(c) ? c : []), val]),
     merge: (key, obj) => update(key, (c = {}) => ({ ...(c && typeof c === 'object' ? c : {}), ...obj }))

package/tiny-idb.min.js

@@ -1,2 +1,2 @@
 /** tiny-idb - MIT © Jelodar */
-const e=new Map,t=e=>new Promise((t,r)=>{e.onsuccess=()=>t(e.result),e.onerror=()=>r(e.error)}),r="readonly",o="readwrite",n=(s="tiny-idb",a=void 0)=>{const c=s+"\0"+(a=a||s);if(e.has(c))return e.get(c);let l;const i=async(e,t)=>{const r=await(l||(l=new Promise((e,t)=>{const r=indexedDB.open(s,1);r.onupgradeneeded=()=>r.result.createObjectStore(a),r.onsuccess=()=>{const t=r.result;t.onversionchange=()=>{t.close(),l=null},e(t)},r.onerror=()=>{l=null,t(r.error)}})));return new Promise(async(o,n)=>{const s=r.transaction(a,e);s.onabort=s.onerror=()=>n(s.error||new DOMException("Aborted"));try{const e=await t(s.objectStore(a));s.oncomplete=()=>o(e)}catch(e){try{s.abort()}catch{}n(e)}})},u=(e,r)=>i(o,async o=>t(o.put(await r(await t(o.get(e))),e))),y={open:n,set:(e,r)=>i(o,o=>t(o.put(r,e))),get:e=>i(r,r=>t(r.get(e))),remove:e=>i(o,r=>t(r.delete(e))),clear:()=>i(o,e=>t(e.clear())),keys:()=>i(r,e=>t(e.getAllKeys())),values:()=>i(r,e=>t(e.getAll())),entries:()=>i(r,async e=>{const[r,o]=await Promise.all([t(e.getAllKeys()),t(e.getAll())]);return r.map((e,t)=>[e,o[t]])}),count:()=>i(r,e=>t(e.count())),update:u,push:(e,t)=>u(e,(e=[])=>[...Array.isArray(e)?e:[],t]),merge:(e,t)=>u(e,(e={})=>({...e&&"object"==typeof e?e:{},...t}))};return["get","set","remove"].forEach(e=>y[e+"Item"]=y[e]),e.set(c,y),y};export const tinyIDB=n();export default tinyIDB;
+const e=new Map,t=e=>new Promise((t,r)=>{e.onsuccess=()=>t(e.result),e.onerror=()=>r(e.error)}),r="readonly",o="readwrite",n=(s="tiny-idb",c=s,a=!0)=>{c===!!c&&([a,c]=[c,s]);const i=s+"\0"+c+"\0"+a;if(e.has(i))return e.get(i);let l,u=[];const y=async()=>{const e=u;u=[];try{const t=e.some(e=>e.m===o)?o:r;await p(t,async t=>{for(const{c:r,r:o}of e)o(await r(t))})}catch(t){e.forEach(e=>e.j(t))}},p=async(e,t)=>{const r=await(l||(l=new Promise((e,t)=>{const r=indexedDB.open(s,1);r.onupgradeneeded=()=>r.result.createObjectStore(c),r.onsuccess=()=>{const t=r.result;t.onversionchange=()=>{t.close(),l=0},e(t)},r.onerror=()=>{l=0,t(r.error)}})));return new Promise((o,n)=>{const s=r.transaction(c,e);s.oncomplete=()=>o(),s.onabort=s.onerror=()=>n(s.error||new DOMException("Aborted")),t(s.objectStore(c)).catch(e=>{try{s.abort()}catch{}n(e)})})},m=(e,t)=>new Promise((r,o)=>{u.push({m:e,c:t,r:r,j:o}),u.length<2&&(a?queueMicrotask(y):y())}),w=(e,r)=>m(o,async o=>t(o.put(await r(await t(o.get(e))),e))),g={open:n,set:(e,r)=>m(o,o=>t(o.put(r,e))),get:e=>m(r,r=>t(r.get(e))),remove:e=>m(o,r=>t(r.delete(e))),clear:()=>m(o,e=>t(e.clear())),keys:()=>m(r,e=>t(e.getAllKeys())),values:()=>m(r,e=>t(e.getAll())),entries:()=>m(r,async e=>{const[r,o]=await Promise.all([t(e.getAllKeys()),t(e.getAll())]);return r.map((e,t)=>[e,o[t]])}),count:()=>m(r,e=>t(e.count())),raw:(e,t=r)=>m(t,e),update:w,push:(e,t)=>w(e,(e=[])=>[...Array.isArray(e)?e:[],t]),merge:(e,t)=>w(e,(e={})=>({...e&&"object"==typeof e?e:{},...t}))};return["get","set","remove"].forEach(e=>g[e+"Item"]=g[e]),e.set(i,g),g};export const tinyIDB=n();export default tinyIDB;