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

• webext-detect - Detects where the current browser extension code is being run.
• webext-options-sync - Helps you manage and autosave your extension's options.
• webext-base-css - Extremely minimal stylesheet/setup for Web Extensions’ options pages (also dark mode)
• webext-dynamic-content-scripts - Automatically registers your content_scripts on domains added via permission.request
• More…

License

MIT © Federico Brigante