@cascivo/storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 urbanisierung
+
+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,19 @@
+<!-- generated by scripts/readme/generate.ts — edit readme.body.md, not this file -->
+
+# @cascivo/storage
+
+> Persisted signals over localStorage/IndexedDB for cascade — SSR-safe
+
+[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo)
+
+Persisted signals for cascade — sync signal state to `localStorage` or `IndexedDB` with SSR-safe initialisation. Drop-in replacement for plain signals when persistence is needed.
+
+## Install
+
+```sh
+pnpm add @cascivo/storage
+```
+
+---
+
+[cascivo.com](https://cascivo.com) · [Docs](https://docs.cascivo.com) · [Storybook](https://storybook.cascivo.com) · [GitHub](https://github.com/urbanisierung/cascivo) · AI agents: use [`@cascivo/mcp`](https://github.com/urbanisierung/cascivo/tree/main/packages/mcp) and [`registry.json`](https://github.com/urbanisierung/cascivo/blob/main/registry.json) · MIT

package/dist/index.d.mts

@@ -0,0 +1,31 @@
+import { ReadonlySignal, Signal } from "@cascivo/core";
+
+//#region src/drivers.d.ts
+interface StorageDriver {
+  get(key: string): string | null | Promise<string | null>;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+  /** Optional change feed (e.g. the cross-tab `storage` event). */
+  subscribe?(key: string, onChange: (raw: string | null) => void): () => void;
+}
+declare function memoryDriver(): StorageDriver;
+declare function localStorageDriver(): StorageDriver;
+//#endregion
+//#region src/persisted-signal.d.ts
+interface PersistedSignalOptions<T> {
+  driver?: StorageDriver;
+  /** Bump together with `migrate` when the stored shape changes. */
+  version?: number;
+  migrate?: (value: unknown, fromVersion: number) => T;
+}
+type PersistedSignal<T> = Signal<T> & {
+  ready: ReadonlySignal<boolean>;
+};
+declare function persistedSignal<T>(key: string, initial: T, options?: PersistedSignalOptions<T>): PersistedSignal<T>;
+//#endregion
+//#region src/indexed-db.d.ts
+/** Minimal key-value driver over indexedDB — async hydration, no `idb` dependency. */
+declare function indexedDBDriver(dbName?: string, storeName?: string): StorageDriver;
+//#endregion
+export { type PersistedSignal, type PersistedSignalOptions, type StorageDriver, indexedDBDriver, localStorageDriver, memoryDriver, persistedSignal };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/drivers.ts","../src/persisted-signal.ts","../src/indexed-db.ts"],"mappings":";;;UAAiB,aAAA;EACf,GAAA,CAAI,GAAA,2BAA8B,OAAO;EACzC,GAAA,CAAI,GAAA,UAAa,KAAA;EACjB,MAAA,CAAO,GAAA;EAHqB;EAK5B,SAAA,EAAW,GAAA,UAAa,QAAA,GAAW,GAAA;AAAA;AAAA,iBAGrB,YAAA,IAAgB,aAAa;AAAA,iBAa7B,kBAAA,IAAsB,aAAa;;;UCZlC,sBAAA;EACf,MAAA,GAAS,aAAA;EDVmB;ECY5B,OAAA;EACA,OAAA,IAAW,KAAA,WAAgB,WAAA,aAAwB,CAAC;AAAA;AAAA,KAG1C,eAAA,MAAqB,MAAA,CAAO,CAAA;EAAO,KAAA,EAAO,cAAA;AAAA;AAAA,iBAEtC,eAAA,IACd,GAAA,UACA,OAAA,EAAS,CAAA,EACT,OAAA,GAAS,sBAAA,CAAuB,CAAA,IAC/B,eAAA,CAAgB,CAAA;;;;iBCnBH,eAAA,CAAgB,MAAA,WAAoB,SAAA,YAAmB,aAAa"}

package/dist/index.mjs

@@ -0,0 +1,129 @@
+import { effect, signal } from "@cascivo/core";
+//#region src/drivers.ts
+function memoryDriver() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => store.get(key) ?? null,
+		set: (key, value) => {
+			store.set(key, value);
+		},
+		remove: (key) => {
+			store.delete(key);
+		}
+	};
+}
+function localStorageDriver() {
+	if (typeof window === "undefined") return memoryDriver();
+	return {
+		get: (key) => window.localStorage.getItem(key),
+		set: (key, value) => {
+			try {
+				window.localStorage.setItem(key, value);
+			} catch {}
+		},
+		remove: (key) => {
+			window.localStorage.removeItem(key);
+		},
+		subscribe(key, onChange) {
+			const listener = (event) => {
+				if (event.storageArea === window.localStorage && event.key === key) onChange(event.newValue);
+			};
+			window.addEventListener("storage", listener);
+			return () => window.removeEventListener("storage", listener);
+		}
+	};
+}
+//#endregion
+//#region src/persisted-signal.ts
+function persistedSignal(key, initial, options = {}) {
+	const driver = options.driver ?? localStorageDriver();
+	const version = options.version ?? 1;
+	const value = signal(initial);
+	const ready = signal(false);
+	let adopting = false;
+	function decode(raw) {
+		if (raw === null) return void 0;
+		try {
+			const envelope = JSON.parse(raw);
+			if (typeof envelope !== "object" || envelope === null || typeof envelope.v !== "number") return;
+			if (envelope.v !== version) {
+				if (!options.migrate) return void 0;
+				const migrated = options.migrate(envelope.value, envelope.v);
+				driver.set(key, JSON.stringify({
+					v: version,
+					value: migrated
+				}));
+				return migrated;
+			}
+			return envelope.value;
+		} catch {
+			return;
+		}
+	}
+	function adopt(raw) {
+		const decoded = decode(raw);
+		if (decoded !== void 0) {
+			adopting = true;
+			value.value = decoded;
+			adopting = false;
+		}
+	}
+	const raw = driver.get(key);
+	if (raw instanceof Promise) raw.then((resolved) => {
+		adopt(resolved);
+		ready.value = true;
+	});
+	else {
+		adopt(raw);
+		ready.value = true;
+	}
+	effect(() => {
+		const next = value.value;
+		if (!ready.value || adopting) return;
+		driver.set(key, JSON.stringify({
+			v: version,
+			value: next
+		}));
+	});
+	driver.subscribe?.(key, adopt);
+	const persisted = value;
+	persisted.ready = ready;
+	return persisted;
+}
+//#endregion
+//#region src/indexed-db.ts
+/** Minimal key-value driver over indexedDB — async hydration, no `idb` dependency. */
+function indexedDBDriver(dbName = "cascivo", storeName = "kv") {
+	if (typeof indexedDB === "undefined") return memoryDriver();
+	let dbPromise;
+	function open() {
+		dbPromise ??= new Promise((resolve, reject) => {
+			const request = indexedDB.open(dbName, 1);
+			request.onupgradeneeded = () => request.result.createObjectStore(storeName);
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error(`indexedDB open failed: ${dbName}`));
+		});
+		return dbPromise;
+	}
+	async function withStore(mode, run) {
+		const db = await open();
+		return new Promise((resolve, reject) => {
+			const request = run(db.transaction(storeName, mode).objectStore(storeName));
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexedDB request failed"));
+		});
+	}
+	return {
+		get: async (key) => await withStore("readonly", (store) => store.get(key)) ?? null,
+		set: (key, value) => {
+			withStore("readwrite", (store) => store.put(value, key));
+		},
+		remove: (key) => {
+			withStore("readwrite", (store) => store.delete(key));
+		}
+	};
+}
+//#endregion
+export { indexedDBDriver, localStorageDriver, memoryDriver, persistedSignal };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/drivers.ts","../src/persisted-signal.ts","../src/indexed-db.ts"],"sourcesContent":["export interface StorageDriver {\n  get(key: string): string | null | Promise<string | null>\n  set(key: string, value: string): void\n  remove(key: string): void\n  /** Optional change feed (e.g. the cross-tab `storage` event). */\n  subscribe?(key: string, onChange: (raw: string | null) => void): () => void\n}\n\nexport function memoryDriver(): StorageDriver {\n  const store = new Map<string, string>()\n  return {\n    get: (key) => store.get(key) ?? null,\n    set: (key, value) => {\n      store.set(key, value)\n    },\n    remove: (key) => {\n      store.delete(key)\n    },\n  }\n}\n\nexport function localStorageDriver(): StorageDriver {\n  // SSR: no window — persistence becomes a no-op, the signal still works.\n  if (typeof window === 'undefined') return memoryDriver()\n  return {\n    get: (key) => window.localStorage.getItem(key),\n    set: (key, value) => {\n      try {\n        window.localStorage.setItem(key, value)\n      } catch {\n        // Quota exceeded / private mode: persistence is best-effort.\n      }\n    },\n    remove: (key) => {\n      window.localStorage.removeItem(key)\n    },\n    subscribe(key, onChange) {\n      const listener = (event: StorageEvent) => {\n        if (event.storageArea === window.localStorage && event.key === key) {\n          onChange(event.newValue)\n        }\n      }\n      window.addEventListener('storage', listener)\n      return () => window.removeEventListener('storage', listener)\n    },\n  }\n}\n","import { effect, signal } from '@cascivo/core'\nimport type { ReadonlySignal, Signal } from '@cascivo/core'\nimport { localStorageDriver, type StorageDriver } from './drivers'\n\ninterface Envelope {\n  v: number\n  value: unknown\n}\n\nexport interface PersistedSignalOptions<T> {\n  driver?: StorageDriver\n  /** Bump together with `migrate` when the stored shape changes. */\n  version?: number\n  migrate?: (value: unknown, fromVersion: number) => T\n}\n\nexport type PersistedSignal<T> = Signal<T> & { ready: ReadonlySignal<boolean> }\n\nexport function persistedSignal<T>(\n  key: string,\n  initial: T,\n  options: PersistedSignalOptions<T> = {},\n): PersistedSignal<T> {\n  const driver = options.driver ?? localStorageDriver()\n  const version = options.version ?? 1\n  const value = signal(initial)\n  const ready = signal(false)\n  // Suppresses the write-through effect while adopting a value FROM storage.\n  let adopting = false\n\n  function decode(raw: string | null): T | undefined {\n    if (raw === null) return undefined\n    try {\n      const envelope = JSON.parse(raw) as Envelope\n      if (typeof envelope !== 'object' || envelope === null || typeof envelope.v !== 'number') {\n        return undefined\n      }\n      if (envelope.v !== version) {\n        if (!options.migrate) return undefined\n        const migrated = options.migrate(envelope.value, envelope.v)\n        // Persist the migration immediately so old-format data doesn't linger.\n        driver.set(key, JSON.stringify({ v: version, value: migrated } satisfies Envelope))\n        return migrated\n      }\n      return envelope.value as T\n    } catch {\n      return undefined\n    }\n  }\n\n  function adopt(raw: string | null): void {\n    const decoded = decode(raw)\n    if (decoded !== undefined) {\n      adopting = true\n      value.value = decoded\n      adopting = false\n    }\n  }\n\n  const raw = driver.get(key)\n  if (raw instanceof Promise) {\n    void raw.then((resolved) => {\n      adopt(resolved)\n      ready.value = true\n    })\n  } else {\n    adopt(raw)\n    ready.value = true\n  }\n\n  effect(() => {\n    const next = value.value\n    if (!ready.value || adopting) return\n    driver.set(key, JSON.stringify({ v: version, value: next } satisfies Envelope))\n  })\n\n  driver.subscribe?.(key, adopt)\n\n  const persisted = value as PersistedSignal<T>\n  ;(persisted as { ready: ReadonlySignal<boolean> }).ready = ready\n  return persisted\n}\n","import { memoryDriver, type StorageDriver } from './drivers'\n\n/** Minimal key-value driver over indexedDB — async hydration, no `idb` dependency. */\nexport function indexedDBDriver(dbName = 'cascivo', storeName = 'kv'): StorageDriver {\n  if (typeof indexedDB === 'undefined') return memoryDriver()\n\n  let dbPromise: Promise<IDBDatabase> | undefined\n  function open(): Promise<IDBDatabase> {\n    dbPromise ??= new Promise((resolve, reject) => {\n      const request = indexedDB.open(dbName, 1)\n      request.onupgradeneeded = () => request.result.createObjectStore(storeName)\n      request.onsuccess = () => resolve(request.result)\n      request.onerror = () => reject(request.error ?? new Error(`indexedDB open failed: ${dbName}`))\n    })\n    return dbPromise\n  }\n\n  async function withStore<T>(\n    mode: IDBTransactionMode,\n    run: (store: IDBObjectStore) => IDBRequest<T>,\n  ): Promise<T> {\n    const db = await open()\n    return new Promise<T>((resolve, reject) => {\n      const request = run(db.transaction(storeName, mode).objectStore(storeName))\n      request.onsuccess = () => resolve(request.result)\n      request.onerror = () => reject(request.error ?? new Error('indexedDB request failed'))\n    })\n  }\n\n  return {\n    get: async (key) =>\n      ((await withStore('readonly', (store) => store.get(key))) as string | undefined) ?? null,\n    set: (key, value) => {\n      void withStore('readwrite', (store) => store.put(value, key))\n    },\n    remove: (key) => {\n      void withStore('readwrite', (store) => store.delete(key))\n    },\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@cascivo/storage",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Persisted signals over localStorage/IndexedDB for cascade — SSR-safe",
+  "keywords": [
+    "cascivo",
+    "css",
+    "design-system",
+    "indexeddb",
+    "localstorage",
+    "react",
+    "signals",
+    "storage"
+  ],
+  "homepage": "https://github.com/urbanisierung/cascivo/tree/main/packages/storage#readme",
+  "bugs": "https://github.com/urbanisierung/cascivo/issues",
+  "license": "MIT",
+  "author": "urbanisierung",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/urbanisierung/cascivo.git",
+    "directory": "packages/storage"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@cascivo/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@preact/signals-react": "^3",
+    "jsdom": "^29",
+    "typescript": "^5",
+    "vite-plus": "^0.1.24"
+  },
+  "peerDependencies": {
+    "@preact/signals-react": ">=2.0.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "tsc --noEmit",
+    "test": "vp test",
+    "dev": "vp pack --watch"
+  }
+}

package/readme.body.md

@@ -0,0 +1 @@
+Persisted signals for cascade — sync signal state to `localStorage` or `IndexedDB` with SSR-safe initialisation. Drop-in replacement for plain signals when persistence is needed.