cachel 1.1.2 → 1.2.0

package/README.md

@@ -5,7 +5,6 @@ Offline-first asset caching for the browser, powered by IndexedDB.
 Fetch remote assets once, serve them forever from local cache. Works with any framework or none at all.
 
 ![npm](https://img.shields.io/npm/v/cachel)
-![bundle size](https://img.shields.io/badge/gzip-1.37kB-brightgreen)
 ![license](https://img.shields.io/npm/l/cachel)
 
 ---
@@ -16,6 +15,8 @@ Fetch remote assets once, serve them forever from local cache. Works with any fr
 - Batch cache multiple assets with controlled concurrency via `loadMany`
 - Serve cached assets as object URLs, works fully offline
 - Skips network requests for already cached assets
+- Attach custom metadata to any cached asset
+- Observable cache via `onChange`, react to any mutation
 - Singleton per database name
 - Supports images, videos, audio and fonts
 - Failed assets in batch processing are bypassed, successful ones are always cached
@@ -42,9 +43,9 @@ const cache = new Cachel('my-app');
 // fetch and cache a remote asset
 await cache.load('https://example.com/logo.png');
 
-// retrieve cached asset as an object URL
-const url = await cache.get('https://example.com/logo.png');
-img.src = url; // works offline
+// retrieve cached asset
+const { path, meta } = await cache.get('https://example.com/logo.png');
+img.src = path; // works offline
 ```
 
 ---
@@ -65,18 +66,26 @@ Defaults to `'idb'` if no name is provided.
 
 ---
 
-### `cache.load(url)`
+### `cache.load(url, options?)`
 
 Fetches a remote asset and stores it in IndexedDB as a blob. If the asset is already cached, the network request is skipped.
 
 ```javascript
 await cache.load('https://example.com/hero.jpg');
+
+// with optional metadata
+await cache.load('https://example.com/hero.jpg', { meta: { category: 'nature', tags: ['landscape'] } });
 ```
 
 Supported content types: `image/*`, `video/*`, `audio/*`, `font/*`
 
 Throws if the resource cannot be fetched or the content type is not supported.
 
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `meta` | `object` | `null` | Any metadata to associate with the cached asset |
+| `silent` | `boolean` | `false` | Suppress `onChange` notifications |
+
 ---
 
 ### `cache.loadMany(urls, chunkSize?)`
@@ -109,15 +118,67 @@ await cache.loadMany(urls, 4); // 4 parallel fetches per round
 
 ### `cache.get(url)`
 
-Retrieves a cached asset and returns it as an object URL. Returns `null` if not found.
+Retrieves a cached asset. Returns `null` if not found.
 
 ```javascript
-const url = await cache.get('https://example.com/hero.jpg');
-if (url) img.src = url;
+const record = await cache.get('https://example.com/hero.jpg');
+if (record) {
+    img.src = record.path;       // object URL, ready to use
+    console.log(record.meta);    // metadata attached on load
+    console.log(record.url);     // original URL
+}
 ```
 
 ---
 
+### `cache.updateRecord(url, meta)`
+
+Updates the metadata of an already cached asset without re-fetching the blob. Merges with existing metadata.
+
+```javascript
+await cache.updateRecord('https://example.com/hero.jpg', { category: 'updated' });
+```
+
+---
+
+### `cache.onChange(callback)`
+
+Registers a listener that fires whenever the cache is mutated. Returns an unsubscribe function.
+
+```javascript
+const unsubscribe = cache.onChange(({ version, timestamp }) => {
+    console.log(`cache updated, version ${version} at ${timestamp}`);
+});
+
+// cleanup
+unsubscribe();
+```
+
+Fires on: `load`, `loadMany`, `remove`, `clear`, `updateRecord`.
+
+---
+
+### `cache.checkStorage()`
+
+Returns storage usage information for the current origin.
+
+```javascript
+const info = await cache.checkStorage();
+console.log(info);
+// {
+//   quota: 123456789,       // total available bytes
+//   usage: 12345,           // total used bytes across all storage types
+//   free: 123444444,        // available bytes
+//   percentUsed: 0.01,      // percentage used
+//   percentFree: 99.99,     // percentage free
+//   indexedDBUsage: 8192    // bytes used by IndexedDB specifically (Chrome only)
+// }
+```
+
+Note: `indexedDBUsage` is Chrome-only via the non-standard `usageDetails` API. Returns `0` in other browsers.
+
+---
+
 ### `cache.remove(url)`
 
 Removes a single cached asset.
@@ -167,17 +228,18 @@ await cache.delete();
 @Directive({ selector: '[cachel]' })
 export class CachelDirective implements OnInit, OnDestroy {
   @Input() cachel: string;
-  private objectUrl: string;
+  private path: string;
   private cache = new Cachel('my-app');
 
   async ngOnInit() {
     await this.cache.load(this.cachel);
-    this.objectUrl = await this.cache.get(this.cachel);
-    this.el.nativeElement.src = this.objectUrl;
+    const record = await this.cache.get(this.cachel);
+    if (record) this.el.nativeElement.src = record.path;
+    this.path = record?.path;
   }
 
   ngOnDestroy() {
-    if (this.objectUrl) URL.revokeObjectURL(this.objectUrl);
+    if (this.path) URL.revokeObjectURL(this.path);
   }
 
   constructor(private el: ElementRef) {}
@@ -194,19 +256,19 @@ export class CachelDirective implements OnInit, OnDestroy {
 const cache = new Cachel('my-app');
 
 export function useCachedAsset(url) {
-  const [src, setSrc] = useState(null);
+  const [record, setRecord] = useState(null);
 
   useEffect(() => {
-    cache.load(url).then(() => cache.get(url)).then(setSrc);
-    return () => { if (src) URL.revokeObjectURL(src); };
+    cache.load(url).then(() => cache.get(url)).then(setRecord);
+    return () => { if (record?.path) URL.revokeObjectURL(record.path); };
   }, [url]);
 
-  return src;
+  return record;
 }
 
 // usage
-const src = useCachedAsset('https://example.com/logo.png');
-<img src={src} />
+const record = useCachedAsset('https://example.com/logo.png');
+<img src={record?.path} />
 ```
 
 ---

package/cachel.js

@@ -6,6 +6,8 @@ class Cachel {
     static #instances = {};
     #idb;
     #defaultChunkSize = 8;
+    #version = 0;
+    #listeners = new Set();
 
     constructor(name = 'idb'){
         if(Cachel.#instances[name]) return Cachel.#instances[name];
@@ -13,7 +15,7 @@ class Cachel {
         Cachel.#instances[name] = this;
     }
 
-    async load(url){
+    async load(url, { silent = false, meta = null } = {}){
         if(typeof url !== 'string') return;
         url = url.trim();
         if(!url) return;
@@ -23,7 +25,8 @@ class Cachel {
             throw new Error(`cachel: caching failed for the requested resource - ${url}`);
         }
         try{
-            const result = await this.#idb.set(url, blob);
+            const result = await this.#idb.set(url, blob, meta);
+            !silent && this.#bump();
             return result;
         }
         catch(err){
@@ -36,9 +39,13 @@ class Cachel {
         if(typeof url !== 'string') return;
         url = url.trim();
         if(!url) return;
-        const blob = await this.#idb.get(url);
-        if(!blob) return null;
-        return URL.createObjectURL(blob);
+        const record = await this.#idb.get(url);
+        if(!record) return null;
+        const { blob, ...rest } = record;
+        return {
+            ...rest,
+            path: URL.createObjectURL(blob)
+        };
     }
 
     async keys() {
@@ -53,11 +60,27 @@ class Cachel {
         if(typeof url !== 'string') return;
         url = url.trim();
         if(!url) return;
-        return this.#idb.remove(url);
+        let result = null;
+        try{
+            result = await this.#idb.remove(url);
+            this.#bump();
+        } catch(err){
+            console.error(`cachel: failed to remove ${url} - ${err.message}`);
+        } finally{
+            return result;
+        }
     }
 
     async clear(){
-        return this.#idb.clear();
+        let result = null;
+        try{
+            result = await this.#idb.clear();
+            this.#bump();
+        } catch(err){
+            console.error(`cachel: failed to clear - ${err.message}`);
+        } finally {
+            return result;
+        }
     }
 
     async loadMany(urls, chunkSize = this.#defaultChunkSize){
@@ -70,7 +93,7 @@ class Cachel {
         const results = [];
         const startTime = performance.now();
         for(const chunk of chunks){
-            const chunkResults = await Promise.allSettled(chunk.map(url => this.load(url)));
+            const chunkResults = await Promise.allSettled(chunk.map(url => this.load(url, { silent: true })));
             results.push(...chunkResults);
         }
         const timeElapsed = (performance.now() - startTime);
@@ -81,9 +104,67 @@ class Cachel {
             failed: results.length - success,
             timeElapsed
         }
+        success && this.#bump();
         return status;
     }
 
+    #bump() {
+        this.#version++;
+        this.#notify();
+    }
+
+    onChange(callback){
+        this.#listeners.add(callback);
+        return () => this.#listeners.delete(callback);
+    }
+
+    #notify(){
+        this.#listeners.forEach(callback => callback({
+            version: this.#version, 
+            timestamp: Date.now()
+        }));
+    }
+
+    async updateRecord(url, meta){
+        if(typeof url !== 'string') return;
+        url = url.trim();
+        if(!url) return;
+        let result = null;
+        try{
+            result = await this.#idb.update(url, meta);
+            this.#bump();
+        } catch(err){
+            console.error(`cachel: failed to update ${url} - ${err.message}`);
+        } finally {
+            return result;
+        }
+    }
+
+    async checkStorage(){
+        const { storage } = window.navigator || {};
+        if(!storage) {
+            console.error(`cachel: no storage found.`);
+            return;
+        }
+        let result = null;
+        try{
+            const { quota, usage, usageDetails } = await storage.estimate();
+            const percentUsed = +((usage/quota)*100).toFixed(2);
+            result = {
+                quota,
+                usage,
+                free: quota - usage,
+                percentUsed,
+                percentFree: 100 - percentUsed,
+                indexedDBUsage: usageDetails?.indexedDB || 0
+            }
+        } catch(err){
+            console.error(`cachel: failed to get the storage information - ${err.message}`);
+        } finally {
+            return result;
+        }
+    }
+
 }
 
 export default Cachel;

package/lib/idb.js

@@ -36,10 +36,19 @@ class Idb {
         return this.#db.transaction(this.#storeName, permission).objectStore(this.#storeName);
     }
 
-    async set(url, blob){
+    async set(url, blob, meta = null){
         if(!await this.#isReady()) return;
         const store = this.#getStoreRef('readwrite');
-        return promisify(store.put({ url, blob }));
+        return promisify(store.put({ url, blob, meta }));
+    }
+
+    async update(key, updatedMeta){
+        if(!await this.#isReady()) return;
+        const record = await this.get(key);
+        if(!record) return null;
+        const meta = { ...record.meta, ...updatedMeta };
+        const store = this.#getStoreRef('readwrite');
+        return promisify(store.put({ ...record, meta }));
     }
 
     async get(url){
@@ -47,7 +56,7 @@ class Idb {
         try{
             const store = this.#getStoreRef();
             const record = await promisify(store.get(url));
-            return record ? record.blob : null;
+            return record || null;
         }
         catch(err){
             console.error(err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cachel",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "main": "cachel.js",
   "files": [
     "cachel.js",