use-state-redux 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# useReduxState
 
-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.
+A small React global state hook built on Redux Toolkit and Redux Persist. Use a
+named state value from multiple components with an API similar to React's
+`useState`:
+
+```tsx
+const [state, setState] = useReduxState("name", initialState);
+```
+
+The hook uses an internal Redux store, so you do not need to add a Redux
+`<Provider>` to your app.
+
+## Installation
+
+Install this package and its peer dependencies:
+
+```sh
+npm install useReduxState @reduxjs/toolkit react react-redux redux-persist
+```
+
+
+## Basic usage
+
+```tsx
+import { useReduxState } from "useReduxState";
+
+function Counter() {
+  const [count, setCount] = useReduxState("count", 0);
+
+  return (
+    <button onClick={() => setCount((current) => current + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+Every component that calls the hook with the same name reads and updates the
+same value:
+
+```tsx
+function CountLabel() {
+  const [count] = useReduxState("count", 0);
+  return <p>{count}</p>;
+}
+
+function ResetCountButton() {
+  const [, setCount] = useReduxState("count", 0);
+  return <button onClick={() => setCount(0)}>Reset count</button>;
+}
+```
+
+The first call for a name supplies its initial value. Later calls with that
+name share the value and ignore their own `initialState` argument. Choose
+distinct names for unrelated state.
+
+The setter accepts either a value or an updater function, like React's
+`useState` setter:
+
+```tsx
+setCount(5);
+setCount((current) => current + 1);
+```
+
+## Persisting state
+
+State is not persisted by default. Set `persist: true` in the third argument to
+save a named value with Redux Persist:
+
+```tsx
+const [theme, setTheme] = useReduxState("theme", "light", {
+  persist: true,
+});
+```
+
+The package uses Redux Persist's web storage adapter, which stores values in
+`localStorage`. Only names that opt into persistence are included in persisted
+state. Persisted values should be JSON-serializable.
+
+Redux Persist rehydrates the store asynchronously. A hook can initially return
+its `initialState`, then update to its restored value when rehydration finishes.
+
+If multiple components use the same name, opting in from any one of them
+enables persistence for that name for the lifetime of the app session. Keep the
+`persist` setting consistent between components that share a name.
+
+## API
+
+### `useReduxState(name, initialState, options?)`
+
+Returns a tuple of the current value and setter:
+
+```ts
+const [state, setState] = useReduxState<T>(name, initialState, options?);
+```
+
+| Argument | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Global name used to share a value between components. |
+| `initialState` | `T` | Value used before the state is set or restored. The first call for a name wins. |
+| `options.persist` | `boolean` | Save this named value across page refreshes. Defaults to `false`. |
+
+### `useRedux(name, initialState, options?)`
+
+Alias for `useReduxState`.
+
+### `setGlobalStateValue(name, value)`
+
+Set a named value outside a component. The matching hook updates when the Redux
+store changes.
+
+```ts
+import { setGlobalStateValue } from "useReduxState";
+
+setGlobalStateValue("count", 10);
+```
+
+### `resetGlobalState(name)`
+
+Restore a registered name to the initial value from its first hook call.
+
+```ts
+import { resetGlobalState } from "useReduxState";
+
+resetGlobalState("count");
+```
+
+### `resetAllGlobalState()`
+
+Reset all named values to their initial values.
+
+### Advanced Redux Persist access
+
+The package also exports `reduxStore` and `reduxPersistor` for integrations that
+need direct access to the internal Redux store or persistor. For example, the
+persistor can be used to flush pending writes or purge persisted data:
+
+```ts
+import { reduxPersistor } from "useReduxState";
+
+await reduxPersistor.flush();
+// To remove the persisted store instead:
+// await reduxPersistor.purge();
+```
+
+## Exports
+
+- `useReduxState` and `useRedux`
+- `setGlobalStateValue`
+- `resetGlobalState` and `resetAllGlobalState`
+- `reduxStore` and `reduxPersistor`
+- `UseReduxOptions` and `GlobalStateSetter` TypeScript types

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './src/index'

package/dist/index.js

@@ -0,0 +1,147 @@
+import { useCallback as f, useSyncExternalStore as R } from "react";
+import { createSlice as E, configureStore as G } from "@reduxjs/toolkit";
+import { persistReducer as w, FLUSH as V, REHYDRATE as P, PAUSE as x, PERSIST as N, PURGE as D, REGISTER as M, persistStore as k } from "redux-persist";
+var p = {}, g = {};
+g.__esModule = !0;
+g.default = $;
+function i(e) {
+  return typeof Symbol == "function" && typeof Symbol.iterator == "symbol" ? i = function(r) {
+    return typeof r;
+  } : i = function(r) {
+    return r && typeof Symbol == "function" && r.constructor === Symbol && r !== Symbol.prototype ? "symbol" : typeof r;
+  }, i(e);
+}
+function d() {
+}
+var A = {
+  getItem: d,
+  setItem: d,
+  removeItem: d
+};
+function O(e) {
+  if ((typeof self > "u" ? "undefined" : i(self)) !== "object" || !(e in self))
+    return !1;
+  try {
+    var t = self[e], r = "redux-persist ".concat(e, " test");
+    t.setItem(r, "test"), t.getItem(r), t.removeItem(r);
+  } catch {
+    return process.env.NODE_ENV !== "production" && console.warn("redux-persist ".concat(e, " test failed, persistence will be disabled.")), !1;
+  }
+  return !0;
+}
+function $(e) {
+  var t = "".concat(e, "Storage");
+  return O(t) ? self[t] : (process.env.NODE_ENV !== "production" && console.error("redux-persist failed to create sync storage. falling back to noop storage."), A);
+}
+p.__esModule = !0;
+p.default = q;
+var U = W(g);
+function W(e) {
+  return e && e.__esModule ? e : { default: e };
+}
+function q(e) {
+  var t = (0, U.default)(e);
+  return {
+    getItem: function(o) {
+      return new Promise(function(a, l) {
+        a(t.getItem(o));
+      });
+    },
+    setItem: function(o, a) {
+      return new Promise(function(l, b) {
+        l(t.setItem(o, a));
+      });
+    },
+    removeItem: function(o) {
+      return new Promise(function(a, l) {
+        a(t.removeItem(o));
+      });
+    }
+  };
+}
+var m = void 0, C = H(p);
+function H(e) {
+  return e && e.__esModule ? e : { default: e };
+}
+var T = (0, C.default)("local");
+m = T;
+const y = E({
+  name: "globalState",
+  initialState: {},
+  reducers: {
+    setGlobalStateValue(e, t) {
+      e[t.payload.name] = t.payload.value;
+    },
+    removeGlobalStateValue(e, t) {
+      delete e[t.payload];
+    },
+    resetGlobalStateValues() {
+      return {};
+    }
+  }
+}), {
+  setGlobalStateValue: v,
+  removeGlobalStateValue: z,
+  resetGlobalStateValues: F
+} = y.actions, L = y.reducer, h = [], S = /* @__PURE__ */ new Set(), c = /* @__PURE__ */ new Set(), Y = w(
+  {
+    key: "useredux",
+    storage: m,
+    // The array is filled as hooks opt into persistence. Other named values
+    // remain in Redux but are excluded from the persisted copy.
+    whitelist: h
+  },
+  L
+), s = G({
+  reducer: Y,
+  middleware: (e) => e({
+    serializableCheck: {
+      ignoredActions: [V, P, x, N, D, M],
+      ignoredPaths: ["_persist"]
+    }
+  })
+}), u = /* @__PURE__ */ new Map(), Z = k(s);
+function B(e, t, r) {
+  u.has(e) || u.set(e, t), r.persist && !S.has(e) && (S.add(e), h.push(e));
+}
+function K(e, t, r = {}) {
+  B(e, t, r);
+  const o = f(() => {
+    const n = s.getState();
+    return Object.prototype.hasOwnProperty.call(n, e) && (S.has(e) || c.has(e)) ? n[e] : u.get(e);
+  }, [e]), a = f(
+    () => u.get(e),
+    [e]
+  ), l = R(
+    s.subscribe,
+    o,
+    a
+  ), b = f(
+    (n) => {
+      const _ = o(), I = typeof n == "function" ? n(_) : n;
+      c.add(e), s.dispatch(v({ name: e, value: I }));
+    },
+    [o, e]
+  );
+  return [l, b];
+}
+function j(e, t) {
+  c.add(e), s.dispatch(v({ name: e, value: t }));
+}
+function ee(e) {
+  u.has(e) ? (c.add(e), s.dispatch(
+    v({ name: e, value: u.get(e) })
+  )) : s.dispatch(z(e));
+}
+function te() {
+  c.clear(), s.dispatch(F());
+}
+export {
+  Z as reduxPersistor,
+  s as reduxStore,
+  te as resetAllGlobalState,
+  ee as resetGlobalState,
+  j as setGlobalStateValue,
+  K as useRedux,
+  K as useReduxState
+};

package/dist/index.umd.cjs

@@ -0,0 +1 @@
+(function(o,n){typeof exports=="object"&&typeof module<"u"?n(exports,require("react"),require("@reduxjs/toolkit"),require("redux-persist")):typeof define=="function"&&define.amd?define(["exports","react","@reduxjs/toolkit","redux-persist"],n):(o=typeof globalThis<"u"?globalThis:o||self,n(o.ReduxUseState={},o.React,o.ReduxToolkit,o.ReduxPersist))})(this,function(o,n,h,u){"use strict";var p={},g={};g.__esModule=!0,g.default=V;function S(e){return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?S=function(r){return typeof r}:S=function(r){return r&&typeof Symbol=="function"&&r.constructor===Symbol&&r!==Symbol.prototype?"symbol":typeof r},S(e)}function b(){}var E={getItem:b,setItem:b,removeItem:b};function w(e){if((typeof self>"u"?"undefined":S(self))!=="object"||!(e in self))return!1;try{var t=self[e],r="redux-persist ".concat(e," test");t.setItem(r,"test"),t.getItem(r),t.removeItem(r)}catch{return process.env.NODE_ENV!=="production"&&console.warn("redux-persist ".concat(e," test failed, persistence will be disabled.")),!1}return!0}function V(e){var t="".concat(e,"Storage");return w(t)?self[t]:(process.env.NODE_ENV!=="production"&&console.error("redux-persist failed to create sync storage. falling back to noop storage."),E)}p.__esModule=!0,p.default=N;var k=M(g);function M(e){return e&&e.__esModule?e:{default:e}}function N(e){var t=(0,k.default)(e);return{getItem:function(s){return new Promise(function(l,d){l(t.getItem(s))})},setItem:function(s,l){return new Promise(function(d,G){d(t.setItem(s,l))})},removeItem:function(s){return new Promise(function(l,d){l(t.removeItem(s))})}}}var m=void 0,T=q(p);function q(e){return e&&e.__esModule?e:{default:e}}var x=(0,T.default)("local");m=x;const _=h.createSlice({name:"globalState",initialState:{},reducers:{setGlobalStateValue(e,t){e[t.payload.name]=t.payload.value},removeGlobalStateValue(e,t){delete e[t.payload]},resetGlobalStateValues(){return{}}}}),{setGlobalStateValue:y,removeGlobalStateValue:A,resetGlobalStateValues:D}=_.actions,O=_.reducer,R=[],v=new Set,f=new Set,P=u.persistReducer({key:"useredux",storage:m,whitelist:R},O),a=h.configureStore({reducer:P,middleware:e=>e({serializableCheck:{ignoredActions:[u.FLUSH,u.REHYDRATE,u.PAUSE,u.PERSIST,u.PURGE,u.REGISTER],ignoredPaths:["_persist"]}})}),i=new Map,C=u.persistStore(a);function U(e,t,r){i.has(e)||i.set(e,t),r.persist&&!v.has(e)&&(v.add(e),R.push(e))}function I(e,t,r={}){U(e,t,r);const s=n.useCallback(()=>{const c=a.getState();return Object.prototype.hasOwnProperty.call(c,e)&&(v.has(e)||f.has(e))?c[e]:i.get(e)},[e]),l=n.useCallback(()=>i.get(e),[e]),d=n.useSyncExternalStore(a.subscribe,s,l),G=n.useCallback(c=>{const z=s(),F=typeof c=="function"?c(z):c;f.add(e),a.dispatch(y({name:e,value:F}))},[s,e]);return[d,G]}function $(e,t){f.add(e),a.dispatch(y({name:e,value:t}))}function W(e){i.has(e)?(f.add(e),a.dispatch(y({name:e,value:i.get(e)}))):a.dispatch(A(e))}function H(){f.clear(),a.dispatch(D())}o.reduxPersistor=C,o.reduxStore=a,o.resetAllGlobalState=H,o.resetGlobalState=W,o.setGlobalStateValue=$,o.useRedux=I,o.useReduxState=I,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})});

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { resetAllGlobalState, resetGlobalState, reduxStore, reduxPersistor, setGlobalStateValue, useRedux, } from './useReduxState.js';
+export type { GlobalStateSetter, UseReduxOptions } from './useReduxState.js';
+export { useRedux as useReduxState } from './useReduxState.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,QAAQ,GACT,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/slice.d.ts

@@ -0,0 +1,9 @@
+export type GlobalState = Record<string, unknown>;
+type SetValuePayload = {
+    name: string;
+    value: unknown;
+};
+export declare const setGlobalStateValue: import('@reduxjs/toolkit').ActionCreatorWithPayload<SetValuePayload, "globalState/setGlobalStateValue">, removeGlobalStateValue: import('@reduxjs/toolkit').ActionCreatorWithPayload<string, "globalState/removeGlobalStateValue">, resetGlobalStateValues: import('@reduxjs/toolkit').ActionCreatorWithoutPayload<"globalState/resetGlobalStateValues">;
+declare const _default: import('redux').Reducer<GlobalState>;
+export default _default;
+//# sourceMappingURL=slice.d.ts.map

package/dist/src/slice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slice.d.ts","sourceRoot":"","sources":["../../src/slice.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElD,KAAK,eAAe,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAkBF,eAAO,MACL,mBAAmB,2GACnB,sBAAsB,qGACtB,sBAAsB,8FACI,CAAC;;AAE7B,wBAAwC"}

package/dist/src/useReduxState.d.ts

@@ -0,0 +1,27 @@
+import { Dispatch, SetStateAction } from 'react';
+import { GlobalState } from './slice.js';
+
+declare const store: import('@reduxjs/toolkit').EnhancedStore<GlobalState & import('redux-persist/es/persistReducer').PersistPartial, import('redux').UnknownAction, import('@reduxjs/toolkit').Tuple<[import('redux').StoreEnhancer<{
+    dispatch: import('redux-thunk').ThunkDispatch<GlobalState & import('redux-persist/es/persistReducer').PersistPartial, undefined, import('redux').UnknownAction>;
+}>, import('redux').StoreEnhancer]>>;
+export declare const reduxPersistor: import('redux-persist').Persistor;
+export interface UseReduxOptions {
+    /** Save this named value between page loads. Defaults to false. */
+    persist?: boolean;
+}
+export type GlobalStateSetter<T> = Dispatch<SetStateAction<T>>;
+/**
+ * Read and update a globally shared state value.
+ * The first call for a name supplies its initial value; later calls with that
+ * name share the same value and ignore their own initial value. Persistence is
+ * enabled for a name when any caller opts in; it stays enabled for that name.
+ */
+export declare function useRedux<T>(name: string, initialState: T, options?: UseReduxOptions): [T, GlobalStateSetter<T>];
+/** Set a named global value outside a React component. */
+export declare function setGlobalStateValue<T>(name: string, value: T): void;
+/** Restore a named value to the initial value supplied to its first hook call. */
+export declare function resetGlobalState(name: string): void;
+/** Reset every named value to its initial value. */
+export declare function resetAllGlobalState(): void;
+export { store as reduxStore };
+//# sourceMappingURL=useReduxState.d.ts.map

package/dist/src/useReduxState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useReduxState.d.ts","sourceRoot":"","sources":["../../src/useReduxState.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAatD,OAA2B,EAIzB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAiBpB,QAAA,MAAM,KAAK;;oCAST,CAAC;AAGH,eAAO,MAAM,cAAc,mCAAsB,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAiBD,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,CAAC,EACf,OAAO,GAAE,eAAoB,GAC5B,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAuC3B;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAGnE;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CASnD;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,IAAI,IAAI,CAG1C;AAED,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,CAAC"}

package/dist/vite.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import('vite').UserConfig;
+export default _default;
+//# sourceMappingURL=vite.config.d.ts.map

package/dist/vite.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.config.d.ts","sourceRoot":"","sources":["../vite.config.ts"],"names":[],"mappings":";AAOA,wBA2BG"}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "use-state-redux",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "A zero-boilerplate Redux wrapper providing a useState-like global hook experience",
+  "type": "module",
+  "main": "./dist/index.umd.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  },
+  "peerDependencies": {
+    "@reduxjs/toolkit": "^1.9.0 || ^2.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-redux": "^8.0.0 || ^9.0.0",
+    "redux-persist": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/react": "^18.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0"
+  },
+  "dependencies": {
+    "@types/redux-persist": "^4.0.0"
+  }
 }