tiny-idb 1.2.1 → 1.4.0

package/README.md

@@ -10,6 +10,15 @@ It is designed for developers who require the reliability and capacity of Indexe
 [![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
@@ -46,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
 
@@ -65,13 +75,43 @@ 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. |
+| `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
 
+### Direct IndexedDB Access (Cursors & Search)
+For large datasets where loading everything via `entries()` is inefficient, use `raw()` to perform cursor-based searches or filtered queries.
+```javascript
+const fruits = await tinyIDB.raw(store => {
+  return new Promise((resolve) => {
+    const matches = [];
+    const request = store.openCursor();
+    request.onsuccess = () => {
+      const cursor = request.result;
+      if (cursor) {
+        if (cursor.value.type === 'fruit') matches.push(cursor.value);
+        cursor.continue();
+      } else resolve(matches);
+    };
+  });
+});
+```
+
+### 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
@@ -86,6 +126,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
@@ -102,7 +155,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);
 ```
 
@@ -136,6 +189,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.
@@ -150,10 +212,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,86 @@
+/** 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>;
+
+  /**
+   * 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) 
+   * 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.1",
+  "version": "1.4.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",
+    "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

@@ -47,7 +47,12 @@ const getAPI = (dbName = 'tiny-idb', storeName = undefined) => {
     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())),
+    raw: (cb, mode = RO) => tx(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",c=void 0)=>{const a=s+"\0"+(c=c||s);if(e.has(a))return e.get(a);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(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)}})},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())),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(a,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",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())),raw:(e,t=r)=>i(t,e),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;