@efficimo/storage-react 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 efficimo
+
+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 OF OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -18,21 +18,24 @@ Built on [`@efficimo/observable`](https://www.npmjs.com/package/@efficimo/observ
 
 ## Installation
 
+`@efficimo/observable` is a **peer dependency** — it must resolve to a single instance shared
+with the rest of your app, so install it explicitly:
+
 ```bash
 # core only
-npm install @efficimo/storage
+npm install @efficimo/storage @efficimo/observable
 
 # with React hook
-npm install @efficimo/storage @efficimo/storage-react
+npm install @efficimo/storage @efficimo/storage-react @efficimo/observable
 ```
 
 ## Quick start
 
 ```typescript
-import { BaseStorage } from '@efficimo/storage';
+import { BaseStorage, NativeStorageAdapter } from '@efficimo/storage';
 
 type Keys = 'auth.token' | 'user.theme';
-const store = new BaseStorage<Keys>(localStorage);
+const store = new BaseStorage<Keys>(new NativeStorageAdapter(localStorage));
 
 // reactive subscription
 store.getObservable('auth.token').subscribe(token => {
@@ -90,10 +93,41 @@ const prefs = LocalStorage.getSerializedObservable('user.prefs', schema, { theme
 
 prefs.subscribe(v => console.log(v)); // { theme: 'light', lang: 'en' }
 
-await prefs.next({ theme: 'dark', lang: 'fr' });
+prefs.next({ theme: 'dark', lang: 'fr' });
 // localStorage now holds '{"theme":"dark","lang":"fr"}'
 ```
 
+## Cookies
+
+`CookieStorage` is a singleton backed by `CookieStorageAdapter`, which uses the
+[Cookie Store API](https://developer.mozilla.org/en-US/docs/Web/API/CookieStore).
+Keys are typed through the `DefaultCookieStorageKeys` interface, like the other singletons:
+
+```typescript
+import { CookieStorage } from '@efficimo/storage';
+
+declare module '@efficimo/storage' {
+  interface DefaultCookieStorageKeys {
+    'consent.analytics': true;
+  }
+}
+
+CookieStorage.getObservable('consent.analytics').subscribe(v => console.log(v));
+CookieStorage.set('consent.analytics', 'granted');
+```
+
+Use `CookieStorageAdapter` directly to set cookie attributes (`path`, `domain`, `maxAge`, `sameSite`):
+
+```typescript
+import { BaseStorage, CookieStorageAdapter } from '@efficimo/storage';
+
+const cookies = new BaseStorage(
+  new CookieStorageAdapter({ path: '/', sameSite: 'lax', maxAge: 60 * 60 * 24 * 365 }),
+);
+```
+
+External cookie changes are picked up through `cookieStore.onchange` when the browser supports it.
+
 ## Cross-tab sync
 
 `BaseStorage` listens to the browser `storage` event automatically. Any change made in another tab propagates to all active observables in the current tab — no extra setup required.
@@ -120,7 +154,7 @@ Implements `ObservableValueInterface<string | null>` from `@efficimo/observable`
 |---|---|
 | `getValue()` | Returns the current storage value. |
 | `subscribe(fn)` | Registers subscriber and immediately calls it with the current value. |
-| `next(value \| setter)` | Updates the value. Supports async setter `(prev) => newValue`. No-op if unchanged. |
+| `next(value \| setter)` | Updates the value. Supports a setter function `(prev) => newValue`. No-op if unchanged. |
 
 ---
 

package/dist/cjs/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./useStorageObservable";
-export * from "./useStorageSerializedObservable";
+export * from "./useStorageObservable.ts";
+export * from "./useStorageSerializedObservable.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qCAAqC,CAAC"}

package/dist/cjs/index.js

@@ -14,6 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./useStorageObservable"), exports);
-__exportStar(require("./useStorageSerializedObservable"), exports);
+__exportStar(require("./useStorageObservable.js"), exports);
+__exportStar(require("./useStorageSerializedObservable.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,mEAAiD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,sEAAoD"}

package/dist/cjs/useStorageObservable.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStorageObservable.js","sourceRoot":"","sources":["../../src/useStorageObservable.ts"],"names":[],"mappings":";;AAOA,oDAWC;AAjBD,iCAA4C;AAE5C;;;GAGG;AACH,SAAgB,oBAAoB,CAClC,GAAyB;IAEzB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAgB,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAExE,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"useStorageObservable.js","sourceRoot":"","sources":["../../src/useStorageObservable.ts"],"names":[],"mappings":";;;AACA,iCAA4C;AAE5C;;;GAGG;AACH,8BACE,GAAyB;IAEzB,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAgB,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAExE,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC"}

package/dist/cjs/useStorageSerializedObservable.js.map

@@ -1 +1 @@
-{"version":3,"file":"useStorageSerializedObservable.js","sourceRoot":"","sources":["../../src/useStorageSerializedObservable.ts"],"names":[],"mappings":";;AAOA,wEAWC;AAjBD,iCAA4C;AAE5C;;;GAGG;AACH,SAAgB,8BAA8B,CAC5C,GAAoC;IAEpC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAW,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEnE,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"useStorageSerializedObservable.js","sourceRoot":"","sources":["../../src/useStorageSerializedObservable.ts"],"names":[],"mappings":";;;AACA,iCAA4C;AAE5C;;;GAGG;AACH,wCACE,GAAoC;IAEpC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAW,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEnE,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;IAC1C,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEV,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC"}

package/dist/esm/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./useStorageObservable";
-export * from "./useStorageSerializedObservable";
+export * from "./useStorageObservable.ts";
+export * from "./useStorageSerializedObservable.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qCAAqC,CAAC"}

package/dist/esm/index.js

@@ -1,3 +1,3 @@
-export * from "./useStorageObservable";
-export * from "./useStorageSerializedObservable";
+export * from "./useStorageObservable.js";
+export * from "./useStorageSerializedObservable.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qCAAqC,CAAC"}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@efficimo/storage-react",
-  "version": "0.2.0",
-  "description": "React bindings for @efficimo/storage: hooks for localStorage and sessionStorage observables.",
+  "version": "0.3.1",
+  "description": "React bindings for @efficimo/storage: hooks for localStorage, sessionStorage and cookie observables.",
   "author": "efficimo",
   "license": "MIT",
   "keywords": [
     "storage",
     "localstorage",
     "sessionstorage",
+    "cookies",
     "observable",
     "react",
     "hooks",
@@ -15,7 +16,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/efficimo/storage.git"
+    "url": "git+https://github.com/efficimo/storage.git"
   },
   "bugs": {
     "url": "https://github.com/efficimo/storage/issues"
@@ -24,6 +25,8 @@
   "engines": {
     "node": ">=18"
   },
+  "type": "commonjs",
+  "sideEffects": false,
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
@@ -40,7 +43,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -52,14 +56,16 @@
     "prepublishOnly": "npm run build && npm run typecheck"
   },
   "peerDependencies": {
-    "@efficimo/storage": ">=0.1.0",
+    "@efficimo/observable": ">=0.5.0",
+    "@efficimo/storage": ">=0.3.0",
     "react": ">=18.0.0"
   },
   "devDependencies": {
+    "@efficimo/observable": "^0.5.1",
     "@efficimo/storage": "file:../core",
-    "@types/node": "^25.0.0",
-    "@types/react": "^18.0.0",
-    "react": "^18.0.0",
-    "typescript": "^5.0.0"
+    "@types/node": "^25.9.7",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.0",
+    "typescript": "^7.0.2"
   }
 }

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./useStorageObservable.ts";
+export * from "./useStorageSerializedObservable.ts";

package/src/useStorageObservable.ts

@@ -0,0 +1,19 @@
+import type { StorageObservable } from "@efficimo/storage";
+import { useEffect, useState } from "react";
+
+/**
+ * Subscribes to a StorageObservable and returns a [value, setter] tuple,
+ * re-rendering the component whenever the storage value changes.
+ */
+export function useStorageObservable<K extends string>(
+  obs: StorageObservable<K>,
+): [string | null, (value: string | null) => void] {
+  const [value, setValue] = useState<string | null>(() => obs.getValue());
+
+  useEffect(() => {
+    const subscription = obs.subscribe((v) => setValue(v));
+    return () => subscription.unsubscribe();
+  }, [obs]);
+
+  return [value, (v) => obs.next(v)];
+}

package/src/useStorageSerializedObservable.ts

@@ -0,0 +1,19 @@
+import type { JsonSerializeObservableValue } from "@efficimo/observable";
+import { useEffect, useState } from "react";
+
+/**
+ * Subscribes to a JsonSerializeObservableValue (from BaseStorage.getSerializedObservable)
+ * and returns a typed [value, setter] tuple.
+ */
+export function useStorageSerializedObservable<T>(
+  obs: JsonSerializeObservableValue<T>,
+): [T | null, (value: T | null) => void] {
+  const [value, setValue] = useState<T | null>(() => obs.getValue());
+
+  useEffect(() => {
+    const subscription = obs.subscribe((v) => setValue(v));
+    return () => subscription.unsubscribe();
+  }, [obs]);
+
+  return [value, (v) => obs.next(v)];
+}