tiny-idb 1.0.0 → 1.2.0

package/README.md

@@ -17,13 +17,13 @@ Native IndexedDB requires managing requests, transactions, and version upgrades.
 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.
 
 ### Resource Efficiency
-At only **596 bytes** (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.
+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. This makes it an ideal solution for rapid prototyping, legacy system upgrades, and environments where complex build pipelines are unavailable.
+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
 
@@ -39,7 +39,7 @@ npm install tiny-idb
 </script>
 ```
 
-*   **Minified Module**: `https://unpkg.com/tiny-idb/tiny-idb.min.js` (596 bytes gzipped)
+*   **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
@@ -47,7 +47,7 @@ npm install tiny-idb
 | Feature | localStorage | tiny-idb |
 |---------|--------------|----------|
 | **Execution** | Synchronous (Blocks UI) | Asynchronous (Non-blocking) |
-| **Storage Limit** | ~5-10MB | Disk-limited |
+| **Storage Limit** | ~5-10MB | Virtually unlimited (until disk is full) |
 | **Data Types** | Strings only | Objects, Blobs, Arrays, Numbers |
 | **Data Integrity** | Basic | ACID Compliant |
 | **Race Condition Safety** | None | Atomic `update`/`push`/`merge` |
@@ -56,6 +56,7 @@ npm install tiny-idb
 
 | Method | Description |
 |--------|-------------|
+| `open(db, store?)` | Creates or retrieves a cached instance. `store` defaults to `db` name. |
 | `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. |
@@ -65,7 +66,93 @@ npm install tiny-idb
 | `count()` | Returns the total number of entries. |
 | `update(key, fn)` | Performs an atomic read-modify-write operation. |
 | `push(key, value)` | Atomically appends a value to an array. |
-| `merge(key, object)` | Atomically shallow-merges an object. |
+| `merge(key, patch)` | Atomically shallow-merges an object. |
+
+## Example Use Cases
+
+### User Settings Management
+Easily manage and update partial user preferences without worrying about race conditions.
+```javascript
+import { tinyIDB } from 'tiny-idb';
+
+// Initial setup
+await tinyIDB.set('settings', { theme: 'dark', notifications: true });
+
+// Later, merge new settings
+await tinyIDB.merge('settings', { notifications: false, language: 'en' });
+
+// Result: { theme: 'dark', notifications: false, language: 'en' }
+```
+
+### Persistent Shopping Cart
+Atomically add items to a list, ensuring no items are lost during concurrent updates.
+```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 });
+
+const cart = await tinyIDB.get('cart');
+console.log(`Items in cart: ${cart.length}`);
+```
+
+### Atomic Counters
+Safely increment values using the `update` method.
+```javascript
+await tinyIDB.set('page_views', 0);
+
+// Increment safely
+await tinyIDB.update('page_views', count => (count || 0) + 1);
+```
+
+### 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');
+```
+
+### 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.
+```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');
+```
+
+### Multi-Instance Support
+Use `open` to create isolated storage instances. Instances are cached internally.
+```javascript
+import { tinyIDB } from 'tiny-idb';
+
+// Create isolated storage instances
+const settings = tinyIDB.open('app-db', 'settings');
+const cache = tinyIDB.open('app-db', 'cache');
+
+await settings.set('theme', 'dark');
+await cache.set('temp_data', { id: 1 });
+```
+
+## Development
+
+`tiny-idb` is written in pure vanilla JavaScript. No compilation is required for development.
+
+### Running Tests
+```bash
+npm test
+```
+
+### Running Tests on Minified Build
+```bash
+npm run test:min
+```
+
+### Minification
+Generate the production-ready minified file:
+```bash
+npm run minify
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-idb",
-  "version": "1.0.0",
+  "version": "1.2.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",
@@ -38,6 +38,8 @@
     "terser": "^5.46.1"
   },
   "scripts": {
-    "test": "node test.js"
+    "test": "node test.js",
+    "test:min": "TEST_MIN=1 node test.js",
+    "minify": "terser tiny-idb.js -o tiny-idb.min.js -c toplevel,unsafe -m toplevel --comments false"
   }
 }

package/tiny-idb.js

@@ -6,50 +6,66 @@
  * @license MIT
  */
 
-const DB_NAME = 'tiny-idb', STORE_NAME = 's', VERSION = 1;
-let dbPromise;
-
-const getDB = () => dbPromise || (dbPromise = new Promise((resolve, reject) => {
-  const req = indexedDB.open(DB_NAME, VERSION);
-  req.onupgradeneeded = e => e.target.result.createObjectStore(STORE_NAME);
-  req.onsuccess = e => {
-    const db = e.target.result;
-    db.onversionchange = () => { db.close(); dbPromise = null; };
-    resolve(db);
-  };
-  req.onerror = () => { dbPromise = null; reject(req.error); };
-}));
-
+const instances = new Map();
 const prom = (req) => new Promise((res, rej) => {
   req.onsuccess = () => res(req.result);
   req.onerror = () => rej(req.error);
 });
+const RO = 'readonly', RW = 'readwrite';
 
-const tx = async (mode, cb) => {
-  const db = await getDB();
-  return new Promise((resolve, reject) => {
-    const t = db.transaction(STORE_NAME, mode);
-    let res;
-    try { res = cb(t.objectStore(STORE_NAME)); } catch (e) { t.abort(); return reject(e); }
-    t.oncomplete = () => resolve(res);
-    t.onerror = () => reject(t.error);
+const getAPI = (dbName = 'tiny-idb', storeName = undefined) => {
+  storeName = storeName || dbName;
+  const key = dbName + '\0' + storeName;
+  if (instances.has(key)) return instances.get(key);
+
+  let dbPromise;
+  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.onsuccess = () => {
+        const db = req.result;
+        db.onversionchange = () => { db.close(); dbPromise = null; };
+        resolve(db);
+      };
+      req.onerror = () => { dbPromise = null; reject(req.error); };
+    })));
+    return new Promise(async (resolve, reject) => {
+      const t = db.transaction(storeName, mode);
+      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);
+      }
+    });
+  };
+
+  const update = async (key, fn) => tx(RW, async s => {
+    const n = await fn(await prom(s.get(key)));
+    return prom(s.put(n, key));
   });
-};
 
-export const tinyIDB = {
-  set: (k, v) => tx('readwrite', s => prom(s.put(v, k))),
-  get: k => tx('readonly', s => prom(s.get(k))),
-  remove: k => tx('readwrite', s => prom(s.delete(k))),
-  clear: () => tx('readwrite', s => prom(s.clear())),
-  keys: () => tx('readonly', s => prom(s.getAllKeys())),
-  values: () => tx('readonly', s => prom(s.getAll())),
-  count: () => tx('readonly', s => prom(s.count())),
-  update: async (k, fn) => tx('readwrite', async s => {
-    const n = await fn(await prom(s.get(k)));
-    return prom(s.put(n, k));
-  }),
-  push: (k, v) => tinyIDB.update(k, c => [...(Array.isArray(c) ? c : []), v]),
-  merge: (k, p) => tinyIDB.update(k, c => ({ ...(c && typeof c === 'object' ? c : {}), ...p }))
+  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: k => tx(RW, s => prom(s.delete(k))),
+    clear: () => tx(RW, s => prom(s.clear())),
+    keys: () => tx(RO, s => prom(s.getAllKeys())),
+    values: () => tx(RO, s => prom(s.getAll())),
+    count: () => tx(RO, s => prom(s.count())),
+    update,
+    push: (key, value) => update(key, c => [...(Array.isArray(c) ? c : []), value]),
+    merge: (key, patch) => update(key, c => ({ ...(c && typeof c === 'object' ? c : {}), ...patch }))
+  };
+
+  ['get', 'set', 'remove'].forEach(m => api[m + 'Item'] = api[m]);
+  instances.set(key, api);
+  return api;
 };
 
+export const tinyIDB = getAPI();
 export default tinyIDB;

package/tiny-idb.min.js

@@ -1 +1 @@
-const DB_NAME="tiny-idb",STORE_NAME="s",VERSION=1;let dbPromise;const getDB=()=>dbPromise||(dbPromise=new Promise((e,r)=>{const t=indexedDB.open(DB_NAME,1);t.onupgradeneeded=e=>e.target.result.createObjectStore("s"),t.onsuccess=r=>{const t=r.target.result;t.onversionchange=()=>{t.close(),dbPromise=null},e(t)},t.onerror=()=>{dbPromise=null,r(t.error)}})),prom=e=>new Promise((r,t)=>{e.onsuccess=()=>r(e.result),e.onerror=()=>t(e.error)}),tx=async(e,r)=>{const t=await getDB();return new Promise((o,n)=>{const s=t.transaction("s",e);let a;try{a=r(s.objectStore("s"))}catch(e){return s.abort(),n(e)}s.oncomplete=()=>o(a),s.onerror=()=>n(s.error)})};export const tinyIDB={set:(e,r)=>tx("readwrite",t=>prom(t.put(r,e))),get:e=>tx("readonly",r=>prom(r.get(e))),remove:e=>tx("readwrite",r=>prom(r.delete(e))),clear:()=>tx("readwrite",e=>prom(e.clear())),keys:()=>tx("readonly",e=>prom(e.getAllKeys())),values:()=>tx("readonly",e=>prom(e.getAll())),count:()=>tx("readonly",e=>prom(e.count())),update:async(e,r)=>tx("readwrite",async t=>{const o=await r(await prom(t.get(e)));return prom(t.put(o,e))}),push:(e,r)=>tinyIDB.update(e,e=>[...Array.isArray(e)?e:[],r]),merge:(e,r)=>tinyIDB.update(e,e=>({...e&&"object"==typeof e?e:{},...r}))};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=void 0)=>{const a=s+"\0"+(c=c||s);if(e.has(a))return e.get(a);let l;const u=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=null},e(t)},r.onerror=()=>{l=null,t(r.error)}})));return new Promise(async(o,n)=>{const s=r.transaction(c,e);s.onabort=s.onerror=()=>n(s.error||new DOMException("Aborted"));try{const e=await t(s.objectStore(c));s.oncomplete=()=>o(e)}catch(e){try{s.abort()}catch{}n(e)}})},i=async(e,r)=>u(o,async o=>{const n=await r(await t(o.get(e)));return t(o.put(n,e))}),y={open:n,set:(e,r)=>u(o,o=>t(o.put(r,e))),get:e=>u(r,r=>t(r.get(e))),remove:e=>u(o,r=>t(r.delete(e))),clear:()=>u(o,e=>t(e.clear())),keys:()=>u(r,e=>t(e.getAllKeys())),values:()=>u(r,e=>t(e.getAll())),count:()=>u(r,e=>t(e.count())),update:i,push:(e,t)=>i(e,e=>[...Array.isArray(e)?e:[],t]),merge:(e,t)=>i(e,e=>({...e&&"object"==typeof e?e:{},...t}))};return["get","set","remove"].forEach(e=>y[e+"Item"]=y[e]),e.set(a,y),y};export const tinyIDB=n();export default tinyIDB;