cachel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geet Trivedi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# cachel
+
+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.
+
+---
+
+## Install
+
+```bash
+npm install cachel
+```
+
+---
+
+## Usage
+
+```javascript
+import Cachel from 'cachel';
+
+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
+```
+
+---
+
+## API
+
+### `new Cachel(name?)`
+
+Creates a new cachel instance. `name` is used as the IndexedDB database name, prefixed internally as `cachel:<name>`.
+
+```javascript
+const cache = new Cachel('my-app'); // opens "cachel:my-app" in IndexedDB
+```
+
+Defaults to `'idb'` if no name is provided.
+
+---
+
+### `cache.load(url)`
+
+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');
+```
+
+Supported content types: `image/*`, `video/*`, `audio/*`, `font/*`
+
+Throws if the fetch fails or the content type is not supported.
+
+---
+
+### `cache.get(url)`
+
+Retrieves a cached asset and returns it as an object URL. Returns `null` if not found.
+
+```javascript
+const url = await cache.get('https://example.com/hero.jpg');
+if (url) img.src = url;
+```
+
+---
+
+### `cache.remove(url)`
+
+Removes a single cached asset.
+
+```javascript
+await cache.remove('https://example.com/hero.jpg');
+```
+
+---
+
+### `cache.keys()`
+
+Returns an array of all cached URLs.
+
+```javascript
+const cached = await cache.keys();
+console.log(cached); // ['https://example.com/logo.png', ...]
+```
+
+---
+
+### `cache.clear()`
+
+Removes all cached assets from the store but keeps the database intact.
+
+```javascript
+await cache.clear();
+```
+
+---
+
+### `cache.delete()`
+
+Drops the entire IndexedDB database.
+
+```javascript
+await cache.delete();
+```
+
+---
+
+## Framework Usage
+
+### Angular
+
+```typescript
+@Directive({ selector: '[cachel]' })
+export class CachelDirective implements OnInit, OnDestroy {
+  @Input() cachel: string;
+  private objectUrl: 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;
+  }
+
+  ngOnDestroy() {
+    if (this.objectUrl) URL.revokeObjectURL(this.objectUrl);
+  }
+
+  constructor(private el: ElementRef) {}
+}
+```
+
+```html
+<img cachel="https://example.com/logo.png" />
+```
+
+### React
+
+```javascript
+const cache = new Cachel('my-app');
+
+export function useCachedAsset(url) {
+  const [src, setSrc] = useState(null);
+
+  useEffect(() => {
+    cache.load(url).then(() => cache.get(url)).then(setSrc);
+    return () => { if (src) URL.revokeObjectURL(src); };
+  }, [url]);
+
+  return src;
+}
+
+// usage
+const src = useCachedAsset('https://example.com/logo.png');
+<img src={src} />
+```
+
+---
+
+## Browser Compatibility
+
+cachel uses IndexedDB which is supported in all modern browsers since 2015.
+
+| Browser | Support |
+|---|---|
+| Chrome | 23+ |
+| Firefox | 10+ |
+| Safari | 10+ |
+| Edge | 79+ |
+| iOS Safari | 10+ |
+
+No service worker required. Works in any browser context.
+
+---
+
+## License
+
+MIT

package/cachel.js

@@ -0,0 +1,61 @@
+import Idb from "./lib/idb.js";
+import convertToBlob from './utils/blob.js';
+
+class Cachel {
+    
+    #idb;
+
+    constructor(name = 'idb'){
+        this.#idb = new Idb(name);
+    }
+
+    async load(url){
+        if(typeof url !== 'string') return;
+        url = url.trim();
+        if(!url) return;
+        if(await this.#idb.has(url)) return;
+        const blob = await convertToBlob(url);
+        if(!blob){
+            throw new Error(`cachel: caching failed for the requested resource - ${url}`);
+        }
+        try{
+            const result = await this.#idb.set(url, blob);
+            return result;
+        }
+        catch(err){
+            console.error(`cachel: error occurred while saving ${url} - ${err.message}`);
+            return null;
+        }
+    }
+
+    async get(url){
+        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);
+    }
+
+    async keys() {
+        return this.#idb.keys();
+    }
+
+    async delete() {
+        return this.#idb.delete();
+    }
+
+    async remove(url){
+        if(typeof url !== 'string') return;
+        url = url.trim();
+        if(!url) return;
+        return this.#idb.remove(url);
+    }
+
+    async clear(){
+        return this.#idb.clear();
+    }
+
+}
+
+export default Cachel;

package/lib/idb.js

@@ -0,0 +1,121 @@
+import promisify from "../utils/promisify.js";
+
+class Idb {
+    #name = null;
+    #db = null;
+    #storeName = 'assets';
+    #ready = null;
+
+    constructor(idbName){
+        this.#name = `cachel:${idbName}`;
+        this.#ready = this.#init();
+    }
+
+    async #init(){
+        try {
+            const request = indexedDB.open(this.#name, 1);
+            request.onupgradeneeded = e => {
+                const db = e.target.result;
+                if(!db.objectStoreNames.contains(this.#storeName)){
+                    db.createObjectStore(this.#storeName, { keyPath: 'url' });
+                }
+            };
+            this.#db = await promisify(request);
+        }
+        catch(err) {
+            console.warn(`cachel: failed to initialise IndexedDB - ${err.message}`);
+        }
+    }
+
+    async #isReady(){
+        await this.#ready;
+        return !!this.#db;
+    }
+
+    #getStoreRef(permission = 'readonly'){
+        return this.#db.transaction(this.#storeName, permission).objectStore(this.#storeName);
+    }
+
+    async set(url, blob){
+        if(!await this.#isReady()) return;
+        const store = this.#getStoreRef('readwrite');
+        return promisify(store.put({ url, blob }));
+    }
+
+    async get(url){
+        if(!await this.#isReady()) return null;
+        try{
+            const store = this.#getStoreRef();
+            const record = await promisify(store.get(url));
+            return record ? record.blob : null;
+        }
+        catch(err){
+            console.error(err.message);
+            return null;
+        }
+    }
+
+    async has(url) {
+        if(!await this.#isReady()) return false;
+        try{
+            const store = this.#getStoreRef();
+            const record = await promisify(store.get(url));
+            return !!record;
+        }
+        catch(err){
+            console.error(`cachel: failed to access ${url} - ${err.message}`);
+            return false;
+        }
+    }
+
+    async remove(url){
+        if(!await this.#isReady()) return;
+        try{
+            const store = this.#getStoreRef('readwrite');
+            return await promisify(store.delete(url));
+        }
+        catch(err){
+            console.error(`cachel: failed to remove ${url} - ${err.message}`);
+            return null;
+        }
+    }
+
+    async clear() {
+        if(!await this.#isReady()) return;
+        try{
+            const store = this.#getStoreRef('readwrite');
+            return await promisify(store.clear());
+        }
+        catch(err){
+            console.error(`cachel: failed to clear - ${err.message}`);
+            return null;
+        }
+    }
+
+    async delete(){
+        if(!await this.#isReady()) return;
+        try{
+            this.#db.close();
+            return await promisify(indexedDB.deleteDatabase(this.#name));
+        }
+        catch(err){
+            console.error(`cachel: failed to delete ${this.#name} - ${err.message}`);
+            return null;
+        }
+    }
+
+    async keys(){
+        if(!await this.#isReady()) return [];
+        try{
+            const store = this.#getStoreRef();
+            return await promisify(store.getAllKeys());
+        }
+        catch(err){
+            console.error(`cachel: failed to get keys - ${err.message}`);
+            return [];
+        }
+    }
+    
+}
+
+export default Idb;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "cachel",
+  "version": "1.0.0",
+  "main": "cachel.js",
+  "files": [ "cachel.js", "lib/", "utils/", "README.md", "LICENSE" ],
+  "scripts": {
+    "dev": "live-server"
+  },
+  "keywords": ["cache", "indexeddb", "offline", "pwa", "blob", "assets"],
+  "author": {
+    "name": "Geet Trivedi",
+    "url": "https://www.geettrivedi.com"
+  },
+  "type": "module",
+  "license": "MIT",
+  "description": "Offline-first asset caching via IndexedDB",
+  "devDependencies": {
+    "live-server": "^1.2.2"
+  }
+}

package/utils/blob.js

@@ -0,0 +1,25 @@
+const convertToBlob = async url => {
+    try{
+        const response = await fetch(url);
+
+        if(!response.ok){
+            throw new Error(`cachel: failed to fetch [${url}] - ${response.status} | ${response.statusText}`);
+        }
+
+        const contentType = response.headers.get('content-type');
+        const allowedContentTypes = ['image/', 'video/', 'audio/', 'font/'];
+        const isContentTypeAllowed = allowedContentTypes.some(type => contentType.startsWith(type));
+
+        if(!isContentTypeAllowed){
+            throw new Error(`cachel: content type ${contentType} is not supported for ${url}`);
+        }
+
+        return await response.blob();
+    }
+    catch(err){
+        console.error(err.message);
+        return null;
+    }
+}
+
+export default convertToBlob;

package/utils/promisify.js

@@ -0,0 +1,5 @@
+const promisify = (request) => new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+});
+export default promisify;