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.

Features

• Fetch and cache remote assets in IndexedDB with one call
• 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
• No service worker required
• Zero dependencies

Install

npm install cachel

Usage

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
const { path, meta } = await cache.get('https://example.com/logo.png');
img.src = path; // works offline

API

new Cachel(name?)

Creates a new cachel instance. name is used as the IndexedDB database name, prefixed internally as cachel:<name>.

Multiple calls with the same name return the same instance, no duplicate IndexedDB connections.

const cache = new Cachel('my-app'); // opens "cachel:my-app" in IndexedDB

Defaults to 'idb' if no name is provided.

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.

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.

cache.loadMany(urls, chunkSize?)

Fetches and caches multiple assets in controlled parallel chunks. Returns a status object with results, success count, failed count, and time elapsed in milliseconds.

const status = await cache.loadMany([
    'https://example.com/logo.png',
    'https://example.com/hero.jpg',
    'https://example.com/font.woff2'
]);

console.log(status);
// {
//   results: [...],  // raw Promise.allSettled results
//   success: 2,
//   failed: 1,
//   timeElapsed: 1240  // in milliseconds
// }

chunkSize controls how many assets are fetched in parallel per round. Defaults to 8, clamped to a maximum of 8. Assets already cached are skipped automatically.

await cache.loadMany(urls, 4); // 4 parallel fetches per round

cache.get(url)

Retrieves a cached asset. Returns null if not found.

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.

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.

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.

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.

await cache.remove('https://example.com/hero.jpg');

cache.keys()

Returns an array of all cached URLs.

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.

await cache.clear();

cache.delete()

Drops the entire IndexedDB database.

await cache.delete();

Framework Usage

Angular

@Directive({ selector: '[cachel]' })
export class CachelDirective implements OnInit, OnDestroy {
  @Input() cachel: string;
  private path: string;
  private cache = new Cachel('my-app');

  async ngOnInit() {
    await this.cache.load(this.cachel);
    const record = await this.cache.get(this.cachel);
    if (record) this.el.nativeElement.src = record.path;
    this.path = record?.path;
  }

  ngOnDestroy() {
    if (this.path) URL.revokeObjectURL(this.path);
  }

  constructor(private el: ElementRef) {}
}

<img cachel="https://example.com/logo.png" />

React

const cache = new Cachel('my-app');

export function useCachedAsset(url) {
  const [record, setRecord] = useState(null);

  useEffect(() => {
    cache.load(url).then(() => cache.get(url)).then(setRecord);
    return () => { if (record?.path) URL.revokeObjectURL(record.path); };
  }, [url]);

  return record;
}

// usage
const record = useCachedAsset('https://example.com/logo.png');
<img src={record?.path} />

Browser Compatibility

cachel uses IndexedDB which is supported in all modern browsers since 2015.

No service worker required. Works in any browser context.

License

MIT