tiny-persistent-store 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arie Steinberg
+
+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,97 @@
+# tiny-persistent-store
+
+A tiny React external store with optional `localStorage` persistence.
+
+It is built around a simple idea:
+
+- keep the current value in memory
+- notify subscribers when the value changes
+- optionally persist the value to `localStorage`
+- connect React components with `useSyncExternalStore`
+
+```bash
+npm install tiny-persistent-store
+```
+
+## Why
+
+`localStorage` can save data between page refreshes, but it does not notify
+React when that data changes.
+
+This package gives you a small external store API for cases where you want a
+simple global value without setting up a larger state-management solution.
+
+## Usage
+
+```ts
+// stores/counterStore.ts
+import { createStorageStore } from "tiny-persistent-store";
+
+// Pass a key to persist to localStorage.
+export const counterStore = createStorageStore("counter", 0);
+```
+
+```tsx
+// components/Counter.tsx
+import { useStore } from "tiny-persistent-store";
+import { counterStore } from "../stores/counterStore";
+
+export function Counter() {
+  const count = useStore(counterStore);
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => counterStore.update((current) => current + 1)}>
+        +
+      </button>
+      <button onClick={() => counterStore.clear()}>Reset</button>
+    </div>
+  );
+}
+```
+
+Any component that calls `useStore(counterStore)` will re-render when the value
+changes.
+
+## In-memory only store
+
+Pass `null` as the key if you do not want persistence:
+
+```ts
+import { createStorageStore } from "tiny-persistent-store";
+
+export const modalStore = createStorageStore(null, false);
+```
+
+## API
+
+### `createStorageStore(key, initialValue)`
+
+Creates a store.
+
+- `key: string | null` — `localStorage` key. Pass `null` to disable persistence.
+- `initialValue: T` — the initial value for the store.
+
+Returns:
+
+- `getSnapshot()` — returns the current value for React's external store API
+- `get()` — returns the current value manually
+- `set(value)` — replaces the current value
+- `update(fn)` — updates the value based on the current value
+- `clear()` — resets to `initialValue` and removes the persisted value
+- `subscribe(listener)` — subscribes to changes and returns an unsubscribe function
+
+### `useStore(store)`
+
+React hook that subscribes a component to a store and returns the latest value.
+
+## Notes
+
+This is not intended to replace Redux or other full state-management libraries
+in large applications. It is a small utility for simple global state and for
+learning how external stores work in React.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,122 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createStorageStore: () => createStorageStore,
+  useStore: () => useStore
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/createStorageStore.ts
+function canUseLocalStorage() {
+  return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+}
+function readFromStorage(key, initialValue) {
+  if (!canUseLocalStorage()) {
+    return initialValue;
+  }
+  try {
+    const savedValue = window.localStorage.getItem(key);
+    if (savedValue === null) {
+      return initialValue;
+    }
+    return JSON.parse(savedValue);
+  } catch {
+    return initialValue;
+  }
+}
+function writeToStorage(key, value) {
+  if (!canUseLocalStorage()) {
+    return;
+  }
+  try {
+    window.localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function removeFromStorage(key) {
+  if (!canUseLocalStorage()) {
+    return;
+  }
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+  }
+}
+function createStorageStore(key, initialValue) {
+  let state = key === null ? initialValue : readFromStorage(key, initialValue);
+  const listeners = /* @__PURE__ */ new Set();
+  function getSnapshot() {
+    return state;
+  }
+  function get() {
+    return state;
+  }
+  function notify() {
+    listeners.forEach((listener) => listener());
+  }
+  function set(value) {
+    state = value;
+    if (key !== null) {
+      writeToStorage(key, state);
+    }
+    notify();
+  }
+  function update(updater) {
+    set(updater(state));
+  }
+  function clear() {
+    state = initialValue;
+    if (key !== null) {
+      removeFromStorage(key);
+    }
+    notify();
+  }
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  return {
+    getSnapshot,
+    get,
+    set,
+    update,
+    clear,
+    subscribe
+  };
+}
+
+// src/useStore.ts
+var import_react = require("react");
+function useStore(store) {
+  return (0, import_react.useSyncExternalStore)(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createStorageStore,
+  useStore
+});

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+type Listener = () => void;
+type StorageStore<T> = {
+    getSnapshot: () => T;
+    get: () => T;
+    set: (value: T) => void;
+    update: (updater: (current: T) => T) => void;
+    clear: () => void;
+    subscribe: (listener: Listener) => () => void;
+};
+/**
+ * Creates a tiny reactive store that can optionally persist its value to
+ * localStorage. The returned store is React-agnostic; use the `useStore`
+ * hook from this package to read it inside React components.
+ *
+ * @param key - localStorage key. Pass `null` to disable persistence.
+ * @param initialValue - value used before anything is read from storage.
+ */
+declare function createStorageStore<T>(key: string | null, initialValue: T): StorageStore<T>;
+
+/**
+ * Connects a store created by `createStorageStore` to React.
+ * Subscribes to changes and returns the latest snapshot,
+ * triggering a re-render whenever the store updates.
+ */
+declare function useStore<T>(store: StorageStore<T>): T;
+
+export { type StorageStore, createStorageStore, useStore };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+type Listener = () => void;
+type StorageStore<T> = {
+    getSnapshot: () => T;
+    get: () => T;
+    set: (value: T) => void;
+    update: (updater: (current: T) => T) => void;
+    clear: () => void;
+    subscribe: (listener: Listener) => () => void;
+};
+/**
+ * Creates a tiny reactive store that can optionally persist its value to
+ * localStorage. The returned store is React-agnostic; use the `useStore`
+ * hook from this package to read it inside React components.
+ *
+ * @param key - localStorage key. Pass `null` to disable persistence.
+ * @param initialValue - value used before anything is read from storage.
+ */
+declare function createStorageStore<T>(key: string | null, initialValue: T): StorageStore<T>;
+
+/**
+ * Connects a store created by `createStorageStore` to React.
+ * Subscribes to changes and returns the latest snapshot,
+ * triggering a re-render whenever the store updates.
+ */
+declare function useStore<T>(store: StorageStore<T>): T;
+
+export { type StorageStore, createStorageStore, useStore };

package/dist/index.js

@@ -0,0 +1,94 @@
+// src/createStorageStore.ts
+function canUseLocalStorage() {
+  return typeof window !== "undefined" && typeof window.localStorage !== "undefined";
+}
+function readFromStorage(key, initialValue) {
+  if (!canUseLocalStorage()) {
+    return initialValue;
+  }
+  try {
+    const savedValue = window.localStorage.getItem(key);
+    if (savedValue === null) {
+      return initialValue;
+    }
+    return JSON.parse(savedValue);
+  } catch {
+    return initialValue;
+  }
+}
+function writeToStorage(key, value) {
+  if (!canUseLocalStorage()) {
+    return;
+  }
+  try {
+    window.localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+  }
+}
+function removeFromStorage(key) {
+  if (!canUseLocalStorage()) {
+    return;
+  }
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+  }
+}
+function createStorageStore(key, initialValue) {
+  let state = key === null ? initialValue : readFromStorage(key, initialValue);
+  const listeners = /* @__PURE__ */ new Set();
+  function getSnapshot() {
+    return state;
+  }
+  function get() {
+    return state;
+  }
+  function notify() {
+    listeners.forEach((listener) => listener());
+  }
+  function set(value) {
+    state = value;
+    if (key !== null) {
+      writeToStorage(key, state);
+    }
+    notify();
+  }
+  function update(updater) {
+    set(updater(state));
+  }
+  function clear() {
+    state = initialValue;
+    if (key !== null) {
+      removeFromStorage(key);
+    }
+    notify();
+  }
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  return {
+    getSnapshot,
+    get,
+    set,
+    update,
+    clear,
+    subscribe
+  };
+}
+
+// src/useStore.ts
+import { useSyncExternalStore } from "react";
+function useStore(store) {
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot
+  );
+}
+export {
+  createStorageStore,
+  useStore
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "tiny-persistent-store",
+  "version": "0.1.0",
+  "description": "A tiny React external store with optional localStorage persistence.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "react",
+    "state",
+    "state-management",
+    "store",
+    "localStorage",
+    "persistence",
+    "external-store",
+    "useSyncExternalStore"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}