Skip to content

Cache values in your Web Extension and clear them on expiration. Also includes a memoize-like API to cache any function results automatically

License

Notifications You must be signed in to change notification settings

fregante/webext-storage-cache

Repository files navigation

webext-storage-cache

Cache values in your Web Extension and clear them on expiration. Also includes a memoize-like API to cache any function results automatically.

  • Browsers: Chrome, Firefox, and Safari
  • Manifest: v2 and v3
  • Context: They can be called from any context that has access to the chrome.storage APIs
  • Permissions: (with attached "reasons" for submission to the Chrome Web Store)
    • storage: "The extension caches some values into the local storage"
    • alarms: "The extension automatically clears its expired storage at certain intervals"

Install

You can download the standalone bundle and include it in your manifest.json.

Or use npm:

npm install webext-storage-cache

Usage

This module requires the storage permission and it’s suggested to also use alarms to safely schedule cache purging:

/* manifest.json */
{
	"permissions": [
		"storage",
		"alarms"
	],
	"background": {
		"scripts": [
			/* Remember to include/import it in the background to enable expired cache purging */
			"webext-storage-cache.js"
		]
	}
}
import {CachedValue} from 'webext-storage-cache';

const item = new CachedValue('unique', {
	maxAge: {
		days: 3,
	},
});

(async () => {
	if (!(await item.isCached())) {
		const cachableItem = await someFunction();
		await item.set(cachableItem);
	}

	console.log(await item.get());
})();

The same code could also be written more effectively with CachedFunction:

import {CachedFunction} from 'webext-storage-cache';

const cachedFunction = new CachedFunction('unique', {
	updater: someFunction,
	maxAge: {
		days: 3,
	},
});

(async () => {
	console.log(await cachedFunction());
})();

API

  • CachedValue - A simple API getter/setter
  • CachedFunction - A memoize-like API to cache your function calls without manually calling isCached/get/set
  • globalCache - Global helpers, documented below
  • legacy - The previous Map-like API, documented below, deprecated

globalCache.clear()

Clears the cache. This is a special method that acts on the entire cache of the extension.

import {globalCache} from 'webext-storage-cache';

document.querySelector('.options .clear-cache').addEventListener('click', async () => {
	await globalCache.clear()
})

legacy API

The API used until v5 has been deprecated and you should migrate to:

  • CachedValue for simple cache.get/cache.set calls. This API makes more sense in a typed context because the type is preserved/enforced across calls.
  • CachedFunction for cache.function. It behaves in a similar fashion, but it also has extra methods like getCached and getFresh

You can:

  • Migrate from v5 to v6, or
  • Keep using the legacy API (except cache.function) by importing webext-storage-cache/legacy.js (until v7 is published)
import cache from "webext-storage-cache/legacy.js";

await cache.get('my-url');
await cache.set('my-url', 'https://example.com');

The documentation for the legacy API can be found on the v5 version of this readme.

Related

License

MIT © Federico Brigante

About

Cache values in your Web Extension and clear them on expiration. Also includes a memoize-like API to cache any function results automatically

Resources

License

Stars

Watchers

Forks

Contributors 4

  •  
  •  
  •  
  •