@widgetic/cache-layer

Shared layered client cache for Widgetic frontends (consumed as a Svelte-aware ESM package via the svelte + exports["."].svelte conditions in package.json).

• L0 — in-memory maps owned by each consuming store (synchronous seed).
• L1 — this package: a single Dexie/IndexedDB database (widgetic_local_v1) with four tables (syncMetadata, listPages, entities, kv), a stale-first read helper, and per-user auth-scoped keys.

Full policy table and auth scoping live in the site docs: Frontend/site/__docs/caching-policy.md.

Usage

import {
	CACHE_POLICIES,
	readStaleFirst,
	revalidateInBackground,
	staleFirstKey,
	writeStaleFirstCache
} from '@widgetic/cache-layer';

const key = staleFirstKey(userId, 'projects.list');

const cached = await readStaleFirst({
	ownerId: userId,
	scope: 'projects.list',
	...CACHE_POLICIES['projects.list'],
	extract: (metadata) => (metadata.projects as Project[] | undefined) ?? null
});

if (!cached || cached.freshness === 'stale') {
	void revalidateInBackground(key, loadProjectsFromApi, async (projects) => {
		await writeStaleFirstCache(userId, 'projects.list', { projects });
	});
}

Rules:

1. Every key embeds the owning user id; never cache data across owners.
2. Schema changes to the database are additive-only (new version repeats the full previous schema).
3. All operations degrade silently when IndexedDB is unavailable.