tiny-idb 1.2.0 → 1.3.0

package/README.md

@@ -2,12 +2,23 @@
 
 **A minimalist, high-performance IndexedDB wrapper for modern web applications.**
 
-`tiny-idb` provides a non-blocking, asynchronous alternative to `localStorage`. It is designed for developers who require the durability and capacity of IndexedDB without the complexity of its native API. By focusing on a single-store, key-value architecture, it eliminates the need for database versioning and boilerplate configuration.
+`tiny-idb` provides a non-blocking, asynchronous alternative to `localStorage`. While `localStorage` is capped at ~5-10MB and can be cleared by the browser under memory pressure, `tiny-idb` leverages IndexedDB to offer virtually unlimited storage (up to 80% of disk space) with much higher durability.
+
+It is designed for developers who require the reliability and capacity of IndexedDB without the complexity of its native API. By focusing on a single-store, key-value architecture, it eliminates the need for database versioning and boilerplate configuration.
 
 [![NPM Version](https://img.shields.io/npm/v/tiny-idb.svg)](https://www.npmjs.com/package/tiny-idb)
 [![License](https://img.shields.io/npm/l/tiny-idb.svg)](LICENSE)
 [![Size](https://img.shields.io/bundlephobia/minzip/tiny-idb)](https://bundlephobia.com/package/tiny-idb)
 
+## Why tiny-idb?
+
+There are many IndexedDB wrappers, but `tiny-idb` is built with a specific philosophy: **Smallest possible footprint without sacrificing data integrity.**
+
+-   **Smaller than most icons**: At less than 1KB (gzipped), it's lighter than a 16x16 PNG.
+-   **Atomic Operations**: Built-in `update`, `push`, and `merge` are ACID-compliant and race-condition safe. No more partial updates or data loss.
+-   **Zero dependencies**: Built on pure vanilla JS. No external bloat.
+-   **Drop-in localStorage replacement**: Use the same `getItem`, `setItem`, `removeItem` calls, but with `await`.
+
 ## Core Advantages
 
 ### Architectural Simplicity
@@ -44,13 +55,14 @@ npm install tiny-idb
 
 ## Technical Comparison
 
-| Feature | localStorage | tiny-idb |
+| Feature | `localStorage` | `tiny-idb` |
 |---------|--------------|----------|
 | **Execution** | Synchronous (Blocks UI) | Asynchronous (Non-blocking) |
-| **Storage Limit** | ~5-10MB | Virtually unlimited (until disk is full) |
-| **Data Types** | Strings only | Objects, Blobs, Arrays, Numbers |
+| **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
 
@@ -63,13 +75,24 @@ npm install tiny-idb
 | `clear()` | Removes all data from the store. |
 | `keys()` | Returns an array of all keys. |
 | `values()` | Returns an array of all values. |
+| `entries()` | Returns an array of `[key, value]` pairs. |
 | `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, patch)` | Atomically shallow-merges an object. |
+| `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
 
+### Iterating over Data
+Use `entries()` to easily process all stored key-value pairs.
+```javascript
+const allEntries = await tinyIDB.entries();
+
+for (const [key, value] of allEntries) {
+  console.log(`${key}:`, value);
+}
+```
+
 ### User Settings Management
 Easily manage and update partial user preferences without worrying about race conditions.
 ```javascript
@@ -84,6 +107,19 @@ await tinyIDB.merge('settings', { notifications: false, language: 'en' });
 // Result: { theme: 'dark', notifications: false, language: 'en' }
 ```
 
+### Storing Binary Data (Blobs/Files)
+Unlike `localStorage`, `tiny-idb` can store binary data directly.
+```javascript
+const response = await fetch('/profile-picture.jpg');
+const blob = await response.blob();
+
+await tinyIDB.set('user_avatar', blob);
+
+// Later...
+const avatar = await tinyIDB.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.
 ```javascript
@@ -100,7 +136,7 @@ Safely increment values using the `update` method.
 ```javascript
 await tinyIDB.set('page_views', 0);
 
-// Increment safely
+// Increment safely - even if multiple tabs do it at once
 await tinyIDB.update('page_views', count => (count || 0) + 1);
 ```
 
@@ -134,6 +170,15 @@ await settings.set('theme', 'dark');
 await cache.set('temp_data', { id: 1 });
 ```
 
+## Browser Support
+
+`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)
+
+If you need to support legacy browsers (IE11), you will need to transpile and polyfill.
+
 ## Development
 
 `tiny-idb` is written in pure vanilla JavaScript. No compilation is required for development.
@@ -148,10 +193,10 @@ npm test
 npm run test:min
 ```
 
-### Minification
+### Building & Minification
 Generate the production-ready minified file:
 ```bash
-npm run minify
+npm run build
 ```
 
 ## License

package/index.d.ts

@@ -0,0 +1,78 @@
+/** tiny-idb - MIT © Jelodar */
+
+export interface TinyIDBInstance {
+  /**
+   * Creates or retrieves a cached instance of a database and store.
+   * @param dbName Name of the IndexedDB database.
+   * @param storeName Name of the object store (defaults to dbName).
+   */
+  open(dbName: string, storeName?: string): TinyIDBInstance;
+
+  /**
+   * Persists a value to the store.
+   */
+  set(key: any, value: any): Promise<void>;
+  /** Alias for set() */
+  setItem(key: any, value: any): Promise<void>;
+
+  /**
+   * Retrieves a value; returns undefined if not found.
+   */
+  get<T = any>(key: any): Promise<T | undefined>;
+  /** Alias for get() */
+  getItem<T = any>(key: any): Promise<T | undefined>;
+
+  /**
+   * Deletes a specific key.
+   */
+  remove(key: any): Promise<void>;
+  /** Alias for remove() */
+  removeItem(key: any): Promise<void>;
+
+  /**
+   * Removes all data from the store.
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Returns an array of all keys.
+   */
+  keys(): Promise<any[]>;
+
+  /**
+   * Returns an array of all values.
+   */
+  values<T = any>(): Promise<T[]>;
+
+  /**
+   * Returns an array of [key, value] pairs.
+   */
+  entries<K = any, V = any>(): Promise<[K, V][]>;
+
+  /**
+   * Returns the total number of entries.
+   */
+  count(): Promise<number>;
+
+  /**
+   * 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) 
+   * to prevent the IndexedDB transaction from auto-committing.
+   * @param key The key to update.
+   * @param fn A function that receives the current value and returns the new value.
+   */
+  update<T = any>(key: any, fn: (currentValue: T | undefined) => T | Promise<T>): Promise<void>;
+
+  /**
+   * Atomically appends a value to an array. Initializes as [value] if key doesn't exist.
+   */
+  push(key: any, value: any): Promise<void>;
+
+  /**
+   * Atomically shallow-merges an object. Initializes as patch if key doesn't exist.
+   */
+  merge(key: any, patch: object): Promise<void>;
+}
+
+export const tinyIDB: TinyIDBInstance;
+export default tinyIDB;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "tiny-idb",
-  "version": "1.2.0",
+  "version": "1.3.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",
+  "types": "index.d.ts",
   "type": "module",
   "repository": {
     "type": "git",
@@ -19,7 +20,8 @@
     "browser",
     "persistent",
     "nosql",
-    "key-value"
+    "key-value",
+    "typescript"
   ],
   "author": "Jelodar",
   "license": "MIT",
@@ -30,6 +32,7 @@
   "files": [
     "tiny-idb.js",
     "tiny-idb.min.js",
+    "index.d.ts",
     "LICENSE",
     "README.md"
   ],
@@ -40,6 +43,7 @@
   "scripts": {
     "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"
+    "build": "npm run minify",
+    "minify": "terser tiny-idb.js -o tiny-idb.min.js -c toplevel,unsafe -m toplevel --comments '/tiny-idb/'"
   }
 }

package/tiny-idb.js

@@ -1,10 +1,4 @@
-/**
- * tiny-idb - A super simple, fast, and dependency-free IndexedDB wrapper.
- * Designed as a drop-in replacement for localStorage with durability and performance.
- *
- * @author Jelodar
- * @license MIT
- */
+/** tiny-idb - MIT © Jelodar */
 
 const instances = new Map();
 const prom = (req) => new Promise((res, rej) => {
@@ -43,23 +37,24 @@ const getAPI = (dbName = 'tiny-idb', storeName = undefined) => {
     });
   };
 
-  const update = async (key, fn) => tx(RW, async s => {
-    const n = await fn(await prom(s.get(key)));
-    return prom(s.put(n, key));
-  });
+  const update = (key, fn) => tx(RW, async s => prom(s.put(await fn(await prom(s.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: k => tx(RW, s => prom(s.delete(k))),
+    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())]);
+      return k.map((key, i) => [key, v[i]]);
+    }),
     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 }))
+    push: (key, val) => update(key, (c = []) => [...(Array.isArray(c) ? c : []), val]),
+    merge: (key, obj) => update(key, (c = {}) => ({ ...(c && typeof c === 'object' ? c : {}), ...obj }))
   };
 
   ['get', 'set', 'remove'].forEach(m => api[m + 'Item'] = api[m]);

package/tiny-idb.min.js

@@ -1 +1,2 @@
-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;
+/** 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;