use-idb-storage 0.0.2 → 0.0.4

package/README.md

@@ -4,3 +4,277 @@
 ![npm downloads](https://img.shields.io/npm/dm/use-idb-storage)
 ![License](https://img.shields.io/npm/l/use-idb-storage)
 ![Tests](https://github.com/sohanemon/idb/actions/workflows/test.yml/badge.svg)
+
+A modern, developer-friendly IndexedDB library for React and vanilla JavaScript with both hook-based and class-based APIs.
+
+## Features
+
+- 🚀 **Simple API**: Easy-to-use hooks and classes
+- 🔄 **Reactive**: React hooks with automatic re-renders
+- 🏪 **Multi-store**: Support for multiple object stores
+- 📦 **Batch operations**: Efficient bulk operations
+- 🔧 **TypeScript**: Full type safety
+- 🎯 **Promise-based**: Modern async/await support
+
+## Installation
+
+```bash
+npm install use-idb-storage
+```
+
+## Quick Start
+
+### Default Instance (Simplest)
+
+```typescript
+import { idb } from 'use-idb-storage';
+
+// Use default store immediately
+await idb.store.set('user', { name: 'John' });
+const user = await idb.store.get('user');
+
+// Use custom store
+const customStore = await idb.get('settings');
+await customStore.set('theme', 'dark');
+```
+
+### React Hook (Recommended for React apps)
+
+```tsx
+import { useIDBStorage, IDBConfig } from 'use-idb-storage';
+
+function App() {
+  return (
+    <IDBConfig database="my-app" version={1} store="data">
+      <MyComponent />
+    </IDBConfig>
+  );
+}
+
+function MyComponent() {
+  const [user, setUser, removeUser] = useIDBStorage({
+    key: 'current-user',
+    defaultValue: { name: '', email: '' }
+  });
+
+  return (
+    <div>
+      <input
+        value={user.name}
+        onChange={e => setUser({ ...user, name: e.target.value })}
+      />
+      <button onClick={() => removeUser()}>Clear</button>
+    </div>
+  );
+}
+```
+
+### Class-based API (For advanced use cases)
+
+```tsx
+import { IDBStorage } from 'use-idb-storage';
+
+// Create storage instance
+const db = new IDBStorage({
+  database: 'my-app',
+  version: 1,
+  store: 'data'
+});
+
+// Get a store
+const store = await db.get('my-store');
+// Or use default store
+const defaultStore = await db.store; // Convenience getter
+
+// Basic operations
+await store.set('user', { name: 'John', age: 30 });
+const user = await store.get('user');
+await store.delete('user');
+
+// Batch operations
+await store.setMany([
+  ['key1', 'value1'],
+  ['key2', 'value2']
+]);
+const values = await store.getMany(['key1', 'key2']);
+
+// Advanced operations
+await store.update('counter', (val) => (val || 0) + 1);
+const allKeys = await store.keys();
+await store.clear();
+```
+
+## API Reference
+
+### Default Instance
+
+```typescript
+import { idb } from 'use-idb-storage';
+```
+
+A pre-configured `IDBStorage` instance using global defaults. Perfect for quick usage without setup.
+
+- `idb.store: Promise<IDBStore>` - Default store instance
+- `idb.get(storeName: string): Promise<IDBStore>` - Get a specific store
+- `idb.drop(storeName: string): Promise<void>` - Clear a store
+- `idb.close(): void` - Close the database connection
+
+### IDBStorage Class
+
+Main entry point for database operations.
+
+#### Constructor
+
+```typescript
+new IDBStorage(config: IDBConfigValues)
+```
+
+#### Properties
+
+- `store: Promise<IDBStore>` - Default store instance (convenience getter)
+
+#### Methods
+
+- `get(storeName: string): Promise<IDBStore>` - Get a store instance
+- `getStore(): Promise<IDBStore>` - Get the default store instance
+- `drop(storeName: string): Promise<void>` - Clear a store (IndexedDB doesn't support dropping stores after creation)
+- `close(): void` - Close the database connection
+
+### IDBStore Class
+
+Provides operations for a specific object store.
+
+#### Methods
+
+**Single Operations:**
+- `get<T>(key: string): Promise<T | undefined>`
+- `set<T>(key: string, value: T): Promise<void>`
+- `delete(key: string): Promise<void>`
+
+**Batch Operations:**
+- `getMany<T>(keys: string[]): Promise<(T | undefined)[]>`
+- `setMany<T>(entries: [string, T][]): Promise<void>`
+- `deleteMany(keys: string[]): Promise<void>`
+
+**Utility Operations:**
+- `update<T>(key: string, updater: (value: T | undefined) => T): Promise<void>`
+- `clear(): Promise<void>`
+- `keys(): Promise<string[]>`
+- `values<T>(): Promise<T[]>`
+- `entries<T>(): Promise<[string, T][]>`
+
+### useIDBStorage Hook
+
+React hook for reactive IndexedDB state management.
+
+```typescript
+const [value, setValue, removeValue] = useIDBStorage(options);
+```
+
+#### Parameters
+
+```typescript
+interface IDBStorageOptions<T> {
+  key: string;
+  defaultValue: T;
+  database?: string;
+  version?: number;
+  store?: string;
+}
+```
+
+#### Returns
+
+- `value: T` - Current stored value
+- `setValue: (value: T | ((prev: T) => T)) => Promise<void>` - Update function
+- `removeValue: () => Promise<void>` - Remove function
+
+### IDBConfig Provider
+
+React context provider for default configuration.
+
+```tsx
+<IDBConfig database="my-app" version={1} store="data">
+  <App />
+</IDBConfig>
+```
+
+### Configuration
+
+```typescript
+interface IDBConfigValues {
+  database: string;    // IndexedDB database name
+  version?: number;    // Database version (default: 1)
+  store: string;       // Default object store name
+}
+```
+
+## Advanced Usage
+
+### Custom Stores
+
+```typescript
+const db = new IDBStorage({ database: 'my-app', store: 'default' });
+
+// Different stores for different data types
+const users = await db.get('users');
+const settings = await db.get('settings');
+
+await users.set('user-1', { name: 'John' });
+await settings.set('theme', 'dark');
+```
+
+### Batch Operations
+
+```typescript
+const store = await db.getStore();
+
+// Set multiple values
+await store.setMany([
+  ['user1', { name: 'Alice' }],
+  ['user2', { name: 'Bob' }],
+  ['user3', { name: 'Charlie' }]
+]);
+
+// Get multiple values
+const users = await store.getMany(['user1', 'user2']);
+```
+
+### Reactive Updates
+
+```typescript
+const [counter, setCounter] = useIDBStorage({
+  key: 'clicks',
+  defaultValue: 0
+});
+
+// This will automatically persist to IndexedDB
+const increment = () => setCounter(count => count + 1);
+```
+
+### Migration Strategy
+
+For database migrations, increment the version number:
+
+```typescript
+// Version 1
+<IDBConfig database="my-app" version={1} store="data">
+  <App />
+</IDBConfig>
+
+// Version 2 (with new features)
+<IDBConfig database="my-app" version={2} store="data">
+  <App />
+</IDBConfig>
+```
+
+## Browser Support
+
+- Chrome 24+
+- Firefox 16+
+- Safari 10+
+- Edge 12+
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -1,25 +1,124 @@
-//#region src/config.d.ts
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/types.d.ts
 /**
- * Configure global defaults for IDBStorage.
+ * Database and store configuration values.
  */
-declare function configureIDBStorage(config: {
-  database?: string;
-  store?: string;
-}): void;
-//#endregion
-//#region src/types.d.ts
+interface IDBConfigValues {
+  /** The name of the IndexedDB database */
+  database: string;
+  /** The version of the IndexedDB database */
+  version: number;
+  /** The name of the object store */
+  store: string;
+}
 /**
  * Configuration options for IDBStorage.
  */
-interface IDBStorageOptions<T extends Record<string, any>> {
+interface IDBStorageOptions<T> extends Partial<IDBConfigValues> {
   /** The key for the stored value */
   key: string;
   /** The default value if no value is found in IndexedDB */
   defaultValue: T;
-  /** The name of the IndexedDB database (optional, defaults to global config) */
-  database?: string;
-  /** The name of the object store (optional, defaults to global config) */
-  store?: string;
+}
+/**
+ * Props for the IDBConfig component.
+ */
+interface IDBConfigProps extends Partial<IDBConfigValues> {
+  /** The children to render */
+  children: React.ReactNode;
+}
+/**
+ * Return type of the useIDBStorage hook
+ */
+type UseIDBStorageReturn<T> = [T, (value: T | ((prevState: T) => T)) => Promise<void>, () => Promise<void>];
+//#endregion
+//#region src/idb-storage.d.ts
+/**
+ * IDBStore provides key-value operations for a specific IndexedDB object store.
+ * Inspired by idb-keyval but with store-specific operations and better error handling.
+ */
+declare class IDBStore {
+  private db;
+  private storeName;
+  constructor(db: IDBDatabase, storeName: string);
+  /**
+   * Get a value by key
+   */
+  get<T>(key: string): Promise<T | undefined>;
+  /**
+   * Set a value for a key
+   */
+  set<T>(key: string, value: T): Promise<void>;
+  /**
+   * Delete a key-value pair
+   */
+  delete(key: string): Promise<void>;
+  /**
+   * Get multiple values by keys
+   */
+  getMany<T>(keys: string[]): Promise<(T | undefined)[]>;
+  /**
+   * Set multiple key-value pairs
+   */
+  setMany<T>(entries: [string, T][]): Promise<void>;
+  /**
+   * Delete multiple keys
+   */
+  deleteMany(keys: string[]): Promise<void>;
+  /**
+   * Update a value using a transformer function
+   */
+  update<T>(key: string, updater: (value: T | undefined) => T): Promise<void>;
+  /**
+   * Clear all key-value pairs in the store
+   */
+  clear(): Promise<void>;
+  /**
+   * Get all keys in the store
+   */
+  keys(): Promise<string[]>;
+  /**
+   * Get all values in the store
+   */
+  values<T>(): Promise<T[]>;
+  /**
+   * Get all entries in the store
+   */
+  entries<T>(): Promise<[string, T][]>;
+}
+/**
+ * IDBStorage provides access to IndexedDB with multiple stores.
+ * Main entry point for database operations.
+ */
+declare class IDBStorage {
+  private config;
+  private db;
+  private dbPromise;
+  constructor(config?: Partial<IDBConfigValues>);
+  /**
+   * Get or create the database connection
+   */
+  private getDB;
+  /**
+   * Get a store instance by name
+   */
+  get(storeName: string): Promise<IDBStore>;
+  /**
+   * Get the default store instance
+   */
+  get store(): Promise<IDBStore>;
+  /**
+   * Drop/delete a specific store
+   * Note: IndexedDB doesn't support dropping stores after creation
+   * This would require a version upgrade with store deletion
+   * For now, we'll clear the store instead
+   */
+  drop(storeName: string): Promise<void>;
+  /**
+   * Close the database connection
+   */
+  close(): void;
 }
 //#endregion
 //#region src/hook.d.ts
@@ -31,17 +130,20 @@ interface IDBStorageOptions<T extends Record<string, any>> {
  *
  * @example
  * ```tsx
- * // Configure global defaults (optional)
- * configureIDBStorage({
- *   database: 'myApp',
- *   store: 'data'
- * });
+ * // Option 1: Using the provider (recommended)
+ * <IDBConfig database="myApp" store="data">
+ *   <App />
+ * </IDBConfig>
+ *
+ * // Option 2: Global config
+ * configureIDBStorage({ database: 'myApp', version: 2, store: 'data' });
  *
  * const [userData, setUserData, removeUserData] = useIDBStorage({
  *   key: 'currentUser',
  *   defaultValue: { name: '', email: '' },
- *   // database: 'myApp', // optional, uses global default
- *   // store: 'users' // optional, uses global default
+ *   // database: 'myApp', // optional, uses context or global default
+ *   // version: 2, // optional, uses context or global default (increment for upgrades)
+ *   // store: 'users' // optional, uses context or global default
  * });
  *
  * // Update data
@@ -50,7 +152,44 @@ interface IDBStorageOptions<T extends Record<string, any>> {
  * // Remove data
  * await removeUserData();
  * ```
+ *
+ * @note The version parameter is used for IndexedDB database versioning.
+ * When you increment the version, it triggers database upgrades. You cannot
+ * "downgrade" to a lower version once a database exists with a higher version.
+ */
+declare function useIDBStorage<T>(options: IDBStorageOptions<T>): UseIDBStorageReturn<T>;
+//#endregion
+//#region src/idb-context.d.ts
+/**
+ * Provider component to configure default IDBStorage settings.
+ * This is optional - if not used, the hook will fall back to global config.
+ *
+ * @param props - Configuration props containing database, store, and children
+ * @returns The provider component wrapping children
+ *
+ * @example
+ * ```tsx
+ * <IDBConfig database="myApp" store="data">
+ *   <App />
+ * </IDBConfig>
+ * ```
  */
-declare function useIDBStorage<T extends Record<string, any>>(options: IDBStorageOptions<T>): [T, (value: T | ((prevState: T) => T)) => Promise<void>, () => Promise<void>];
+declare function IDBConfig({
+  children,
+  ...conf
+}: IDBConfigProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/config.d.ts
+/**
+ * Configure global defaults for IDBStorage.
+ */
+declare function configureIDBStorage(config: Partial<IDBConfigValues>): void;
+/**
+ * Get the current global configuration.
+ */
+declare function getGlobalConfig(): IDBConfigValues;
+//#endregion
+//#region src/index.d.ts
+declare const idb: IDBStorage;
 //#endregion
-export { configureIDBStorage, useIDBStorage };
+export { IDBConfig, type IDBConfigProps, type IDBConfigValues, IDBStorage, type IDBStorageOptions, IDBStore, type UseIDBStorageReturn, configureIDBStorage, getGlobalConfig, idb, useIDBStorage };

package/dist/index.js

@@ -1 +1 @@
-import*as e from"react";let t={database:`sohanemon-idb`,store:`default`};function n(e){t={...t,...e}}function r(){return{...t}}const i=(e,t,n=1)=>new Promise((r,i)=>{let a=indexedDB.open(e,n);a.onerror=()=>i(a.error),a.onsuccess=()=>r(a.result),a.onupgradeneeded=e=>{let n=e.target.result;n.objectStoreNames.contains(t)||n.createObjectStore(t)}});function a(e,t,n){return new Promise((r,i)=>{let a=e.transaction([t],`readonly`).objectStore(t).get(n);a.onerror=()=>i(a.error),a.onsuccess=()=>r(a.result)})}const o=(e,t,n,r)=>new Promise((i,a)=>{let o=e.transaction([t],`readwrite`).objectStore(t).put(r,n);o.onerror=()=>a(o.error),o.onsuccess=()=>i()}),s=(e,t,n)=>new Promise((r,i)=>{let a=e.transaction([t],`readwrite`).objectStore(t).delete(n);a.onerror=()=>i(a.error),a.onsuccess=()=>r()});function c(t){let{key:n,defaultValue:c,database:l=r().database,store:u=r().store}=t,[d,f]=e.useState(c),[p,m]=e.useState(null);return e.useEffect(()=>{let e=!0;return(async()=>{try{let t=await i(l,u);e&&m(t)}catch(e){console.error(`Failed to open IndexedDB:`,e)}})(),()=>{e=!1}},[l,u]),e.useEffect(()=>{p&&(async()=>{try{let e=await a(p,u,n);e!==void 0&&f(e)}catch(e){console.error(`Failed to load value from IndexedDB:`,e)}})()},[p,u,n]),[d,e.useCallback(async e=>{if(!p)return;let t=typeof e==`function`?e(d):e;f(t);try{await o(p,u,n,t)}catch(e){console.error(`Failed to save value to IndexedDB:`,e)}},[p,u,n,d]),e.useCallback(async()=>{if(p){f(c);try{await s(p,u,n)}catch(e){console.error(`Failed to remove value from IndexedDB:`,e)}}},[p,u,n,c])]}export{n as configureIDBStorage,c as useIDBStorage};
+import*as e from"react";import{Fragment as t,jsx as n}from"react/jsx-runtime";const r=new Map;function i(){return typeof indexedDB<`u`}function a(e,t,n=1,a){if(!i())throw Error(`IndexedDB is not available in this environment`);let s=`${e}:${n}:${t}`;if(r.has(s))return r.get(s);let c=o(e,t,n,a);return r.set(s,c),c}function o(e,t,n,i){return new Promise((a,s)=>{let c=indexedDB.open(e,n);c.onerror=()=>{r.delete(`${e}:${n}:${t}`),s(c.error)},c.onupgradeneeded=e=>{let n=e.target.result;n.objectStoreNames.contains(t)||n.createObjectStore(t)},c.onsuccess=()=>{let s=c.result;if(!s.objectStoreNames.contains(t)){s.close(),r.delete(`${e}:${n}:${t}`),a(o(e,t,n+1,i));return}s.onversionchange=()=>{s.close();for(let[t]of r)t.startsWith(`${e}:`)&&r.delete(t);i?.()},a(s)}})}function s(e,t,n){return new Promise((r,i)=>{try{let a=e.transaction([t],`readonly`).objectStore(t).get(n);a.onerror=()=>i(a.error),a.onsuccess=()=>r(a.result)}catch(e){i(e)}})}function c(e,t,n,r){return new Promise((i,a)=>{try{let o=e.transaction([t],`readwrite`).objectStore(t).put(r,n);o.onerror=()=>a(o.error),o.onsuccess=()=>i()}catch(e){a(e)}})}function l(e,t,n){return new Promise((r,i)=>{try{let a=e.transaction([t],`readwrite`).objectStore(t).delete(n);a.onerror=()=>i(a.error),a.onsuccess=()=>r()}catch(e){i(e)}})}var u=class{db;storeName;constructor(e,t){this.db=e,this.storeName=t}async get(e){try{return await s(this.db,this.storeName,e)}catch(t){throw console.error(`Failed to get value for key "${e}":`,t),t}}async set(e,t){try{await c(this.db,this.storeName,e,t)}catch(t){throw console.error(`Failed to set value for key "${e}":`,t),t}}async delete(e){try{await l(this.db,this.storeName,e)}catch(t){throw console.error(`Failed to delete key "${e}":`,t),t}}async getMany(e){try{let t=e.map(e=>this.get(e));return await Promise.all(t)}catch(e){throw console.error(`Failed to get multiple values:`,e),e}}async setMany(e){try{let t=this.db.transaction([this.storeName],`readwrite`).objectStore(this.storeName),n=e.map(([e,n])=>new Promise((r,i)=>{let a=t.put(n,e);a.onerror=()=>i(a.error),a.onsuccess=()=>r()}));await Promise.all(n)}catch(e){throw console.error(`Failed to set multiple values:`,e),e}}async deleteMany(e){try{let t=this.db.transaction([this.storeName],`readwrite`).objectStore(this.storeName),n=e.map(e=>new Promise((n,r)=>{let i=t.delete(e);i.onerror=()=>r(i.error),i.onsuccess=()=>n()}));await Promise.all(n)}catch(e){throw console.error(`Failed to delete multiple keys:`,e),e}}async update(e,t){try{let n=t(await this.get(e));await this.set(e,n)}catch(t){throw console.error(`Failed to update value for key "${e}":`,t),t}}async clear(){try{let e=this.db.transaction([this.storeName],`readwrite`).objectStore(this.storeName).clear();await new Promise((t,n)=>{e.onerror=()=>n(e.error),e.onsuccess=()=>t()})}catch(e){throw console.error(`Failed to clear store:`,e),e}}async keys(){try{let e=this.db.transaction([this.storeName],`readonly`).objectStore(this.storeName).getAllKeys();return await new Promise((t,n)=>{e.onerror=()=>n(e.error),e.onsuccess=()=>t(Array.from(e.result))})}catch(e){throw console.error(`Failed to get keys:`,e),e}}async values(){try{let e=this.db.transaction([this.storeName],`readonly`).objectStore(this.storeName).getAll();return await new Promise((t,n)=>{e.onerror=()=>n(e.error),e.onsuccess=()=>t(e.result)})}catch(e){throw console.error(`Failed to get values:`,e),e}}async entries(){try{let e=this.db.transaction([this.storeName],`readonly`).objectStore(this.storeName).openCursor(),t=[];return new Promise((n,r)=>{e.onerror=()=>r(e.error),e.onsuccess=()=>{let r=e.result;r?(t.push([r.key,r.value]),r.continue()):n(t)}})}catch(e){throw console.error(`Failed to get entries:`,e),e}}},d=class{config;db=null;dbPromise=null;constructor(e){this.config={database:`sohanemon-idb`,version:1,store:`default`,...e},this.config.version=Math.max(1,Math.floor(this.config.version))}async getDB(){return this.db?this.db:this.dbPromise?this.dbPromise:(this.dbPromise=a(this.config.database,this.config.store,this.config.version,()=>{this.db=null,this.dbPromise=null}),this.db=await this.dbPromise,this.dbPromise=null,this.db)}async get(e){return new u(await this.getDB(),e)}get store(){return this.get(this.config.store)}async drop(e){await(await this.get(e)).clear()}close(){this.db&&=(this.db.close(),null)}};let f={database:`sohanemon-idb`,version:1,store:`default`};function p(e){f={...f,...e}}function m(){return{...f}}function h(t){let{key:n,defaultValue:r,...a}=t,o={...m(),...a};o.version=Math.max(1,Math.floor(o.version||1));let[s,c]=e.useState(r),[l,u]=e.useState(null),[f,p]=e.useState(!1),h=e.useRef(null),g=e.useRef(null),_=e.useRef([]);return e.useEffect(()=>{let e=!0;return(async()=>{try{if(!i()){console.warn(`IndexedDB is not available, using default values only`);return}u(null),h.current&&(h.current.close(),h.current=null,g.current=null);let t=new d(o),r=await t.get(o.store);if(!e)return;h.current=t,g.current=r;let a=await r.get(n);if(e&&a!==void 0&&c(a),e){p(!0);let e=_.current;_.current=[];for(let t of e)t().catch(e=>{console.error(`Failed to process pending update:`,e)})}}catch(t){e&&(u(t instanceof Error?t:Error(`Failed to load from IndexedDB`)),console.error(`Failed to initialize IDBStorage:`,t))}})(),()=>{e=!1,h.current&&(h.current.close(),h.current=null,g.current=null)}},[o.database,o.version,o.store,n]),[s,e.useCallback(async e=>{if(l){console.warn(`Cannot update value due to previous error:`,l);return}let t=typeof e==`function`?e(s):e;c(t);let r=async()=>{if(g.current)await g.current.set(n,t);else throw Error(`Store not initialized`)};if(f)try{await r()}catch(e){throw c(s),u(e instanceof Error?e:Error(`Failed to save to IndexedDB`)),console.error(`Failed to save value to IndexedDB:`,e),e}else _.current.push(r)},[s,n,l,f]),e.useCallback(async()=>{if(l){console.warn(`Cannot remove value due to previous error:`,l);return}c(r);let e=async()=>{if(g.current)await g.current.delete(n);else throw Error(`Store not initialized`)};if(f)try{await e()}catch(e){throw c(s),u(e instanceof Error?e:Error(`Failed to remove from IndexedDB`)),console.error(`Failed to remove value from IndexedDB:`,e),e}else _.current.push(e)},[s,n,r,l,f])]}function g({children:r,...i}){return e.useEffect(()=>{p(i)},[i.database,i.version,i.store]),n(t,{children:r})}const _=new d;export{g as IDBConfig,d as IDBStorage,u as IDBStore,p as configureIDBStorage,m as getGlobalConfig,_ as idb,h as useIDBStorage};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-idb-storage",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "author": "Sohan Emon <sohanemon@outlook.com>",
   "description": "",
   "type": "module",
@@ -19,6 +19,8 @@
     "test:list": "vitest list",
     "test:log": "vitest run --reporter verbose",
     "test:ui": "vitest --ui",
+    "build:playground": "vite build --config playground/vite.config.ts",
+    "playground": "tsdown && vite build --config playground/vite.config.ts && vite --config playground/vite.config.ts",
     "check": "biome check .",
     "fix": "biome check --diagnostic-level=error --write .",
     "lint": "biome lint .",
@@ -53,6 +55,7 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/ui": "^4.0.14",
+    "fake-indexeddb": "^6.2.5",
     "jsdom": "^27.2.0",
     "tsdown": "^0.16.4",
     "typescript": "^5.9.3",