@mfeflow/storage 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @mfeflow/storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser storage namespaced per micro-frontend. Keys are stored as `<mfe>:<key>`, so two remotes cannot overwrite each other. It falls back to memory when Web Storage is missing (SSR, sandboxed iframes), keeps tabs in sync and has a React hook.
+
+## Install
+
+```sh
+pnpm add @mfeflow/storage
+```
+
+`react` (19) is an optional peer dependency, needed only for `@mfeflow/storage/react`.
+
+## Usage
+
+```ts
+import { createStorage } from '@mfeflow/storage';
+
+const storage = createStorage('cart'); // 'local' by default; { area: 'session' | 'memory' } also works
+storage.set('items', ['a', 'b']);
+const items = storage.get('items', [] as string[], Array.isArray);
+const stop = storage.subscribe('items', (value) => console.log(value)); // this tab and other tabs
+```
+
+```tsx
+import { useStoredState } from '@mfeflow/storage/react';
+
+const [open, setOpen] = useStoredState(storage, 'drawer-open', false);
+```
+
+## Module Federation sharing
+
+Bucket: **stateless**. Its listeners live on a page global, so separate copies in different remotes still see each other's writes and no copy is required to be the only one. `@mfeflow/rsbuild` shares it as a singleton by default anyway, which keeps one copy on the page; sharing is not required for correctness.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/** Where values live. `memory` is used automatically when no Web Storage exists (SSR, sandboxed iframes). */
+export type StorageArea = 'local' | 'session' | 'memory';
+export interface CreateStorageOptions {
+    /** Default `local`. */
+    area?: StorageArea;
+    /** Use this Storage instead of the browser's (tests, custom adapters). */
+    backend?: Storage;
+}
+/** Called with the new value (already parsed), or `undefined` when the key was removed. */
+export type Listener = (value: unknown) => void;
+/** Narrows an untrusted stored value. */
+export type Guard<T> = (value: unknown) => value is T;
+export interface MfeStorage {
+    /** The micro-frontend this storage belongs to. Keys are stored as `<mfe>:<key>`. */
+    readonly mfe: string;
+    /** The stored value, or `undefined`. Returns the same reference until the value changes. */
+    read(key: string): unknown;
+    /** The stored value if `guard` accepts it, otherwise `fallback`. */
+    get<T>(key: string, fallback: T, guard?: Guard<T>): T;
+    set(key: string, value: unknown): void;
+    remove(key: string): void;
+    /** Keys owned by this micro-frontend, without the prefix. */
+    keys(): string[];
+    /** Called on changes from this tab and from other tabs. Returns an unsubscribe function. */
+    subscribe(key: string, listener: Listener): () => void;
+}
+type Bus = WeakMap<Storage, Map<string, Set<Listener>>>;
+declare global {
+    var mfeflowStorageBus: Bus | undefined;
+}
+/**
+ * Storage for one micro-frontend. Every key is prefixed with the MFE's name,
+ * so two remotes can both use `theme` or `filters` without overwriting each other.
+ */
+export declare function createStorage(mfe: string, options?: CreateStorageOptions): MfeStorage;
+export {};

package/dist/index.js

@@ -0,0 +1,131 @@
+const MFE_NAME = /^[a-z0-9][a-z0-9_-]*$/i;
+class MemoryStorage {
+    #map = new Map();
+    get length() {
+        return this.#map.size;
+    }
+    clear() {
+        this.#map.clear();
+    }
+    getItem(key) {
+        return this.#map.get(key) ?? null;
+    }
+    key(index) {
+        return [
+            ...this.#map.keys()
+        ][index] ?? null;
+    }
+    removeItem(key) {
+        this.#map.delete(key);
+    }
+    setItem(key, value) {
+        this.#map.set(key, value);
+    }
+}
+function browserStorage(area) {
+    if ('memory' === area || "u" < typeof window) return;
+    try {
+        const s = 'session' === area ? window.sessionStorage : window.localStorage;
+        const probe = '__mfeflow_probe__';
+        s.setItem(probe, probe);
+        s.removeItem(probe);
+        return s;
+    } catch  {
+        return;
+    }
+}
+function listenersFor(backend, fullKey) {
+    globalThis.mfeflowStorageBus ??= new WeakMap();
+    const bus = globalThis.mfeflowStorageBus;
+    let byKey = bus.get(backend);
+    if (!byKey) {
+        byKey = new Map();
+        bus.set(backend, byKey);
+    }
+    let set = byKey.get(fullKey);
+    if (!set) {
+        set = new Set();
+        byKey.set(fullKey, set);
+    }
+    return set;
+}
+function parse(raw) {
+    if (null === raw) return;
+    try {
+        const value = JSON.parse(raw);
+        return value;
+    } catch  {
+        return;
+    }
+}
+function createStorage(mfe, options = {}) {
+    if (!MFE_NAME.test(mfe)) throw new Error(`createStorage: invalid micro-frontend name "${mfe}" (use letters, digits, - and _)`);
+    const area = options.area ?? 'local';
+    const backend = options.backend ?? browserStorage(area) ?? new MemoryStorage();
+    const prefix = `${mfe}:`;
+    const cache = new Map();
+    let subscriptions = 0;
+    const notify = (key, value)=>{
+        for (const l of listenersFor(backend, prefix + key))l(value);
+    };
+    const onStorageEvent = (e)=>{
+        if (e.storageArea !== backend || null === e.key || !e.key.startsWith(prefix)) return;
+        notify(e.key.slice(prefix.length), parse(e.newValue));
+    };
+    const read = (key)=>{
+        const raw = backend.getItem(prefix + key);
+        const hit = cache.get(key);
+        if (hit?.raw === raw) return hit.value;
+        const value = parse(raw);
+        cache.set(key, {
+            raw,
+            value
+        });
+        return value;
+    };
+    return {
+        mfe,
+        read,
+        get (key, fallback, guard) {
+            const value = read(key);
+            if (void 0 === value) return fallback;
+            if (guard) return guard(value) ? value : fallback;
+            if (typeof value !== typeof fallback || Array.isArray(value) !== Array.isArray(fallback)) return fallback;
+            return value;
+        },
+        set (key, value) {
+            try {
+                backend.setItem(prefix + key, JSON.stringify(value));
+            } catch  {}
+            notify(key, value);
+        },
+        remove (key) {
+            backend.removeItem(prefix + key);
+            notify(key, void 0);
+        },
+        keys () {
+            const out = [];
+            for(let i = 0; i < backend.length; i++){
+                const k = backend.key(i);
+                if (k?.startsWith(prefix)) out.push(k.slice(prefix.length));
+            }
+            return out;
+        },
+        subscribe (key, listener) {
+            const set = listenersFor(backend, prefix + key);
+            const l = (value)=>{
+                listener(value);
+            };
+            set.add(l);
+            if (0 === subscriptions++ && "u" > typeof window) window.addEventListener('storage', onStorageEvent);
+            let active = true;
+            return ()=>{
+                if (!active) return;
+                active = false;
+                set.delete(l);
+                if (0 === --subscriptions && "u" > typeof window) window.removeEventListener('storage', onStorageEvent);
+            };
+        }
+    };
+}
+export { createStorage };

package/dist/react.d.ts

@@ -0,0 +1,8 @@
+import type { Guard, MfeStorage } from './index.js';
+type Next<T> = T | ((prev: T) => T);
+/**
+ * React state backed by an `MfeStorage` key. Stays in sync across components,
+ * remotes using the same storage, and browser tabs.
+ */
+export declare function useStoredState<T>(storage: MfeStorage, key: string, initial: T, guard?: Guard<T>): [T, (next: Next<T>) => void];
+export {};

package/dist/react.js

@@ -0,0 +1,31 @@
+import { useCallback, useSyncExternalStore } from "react";
+function isUpdater(next) {
+    return 'function' == typeof next;
+}
+function useStoredState(storage, key, initial, guard) {
+    const subscribe = useCallback((onChange)=>storage.subscribe(key, onChange), [
+        storage,
+        key
+    ]);
+    const getSnapshot = useCallback(()=>storage.read(key), [
+        storage,
+        key
+    ]);
+    const getServerSnapshot = useCallback(()=>void 0, []);
+    useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const value = storage.get(key, initial, guard);
+    const set = useCallback((next)=>{
+        const resolved = isUpdater(next) ? next(storage.get(key, initial, guard)) : next;
+        storage.set(key, resolved);
+    }, [
+        storage,
+        key,
+        initial,
+        guard
+    ]);
+    return [
+        value,
+        set
+    ];
+}
+export { useStoredState };

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@mfeflow/storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Browser storage namespaced per micro-frontend, SSR-safe, with cross-tab sync and a React hook.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "localstorage",
+    "react",
+    "hook",
+    "rsbuild"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/storage"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "stateless"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }