dev-react-microstore 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OhadBaehr
+
+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,183 @@
+# react-microstore
+
+A minimal global state manager for React with fine-grained subscriptions.
+
+## Installation
+
+```bash
+npm install react-microstore
+```
+
+## Usage
+
+```tsx
+import { createStoreState, useStoreSelector } from 'react-microstore';
+
+const counterStore = createStoreState({ count: 0 });
+
+function Counter() {
+  const { count } = useStoreSelector(counterStore, ['count']);
+
+  return (
+    <div>
+      <p>{count}</p>
+      <button onClick={() => counterStore.set({ count: count + 1 })}>
+        Increment
+      </button>
+    </div>
+  );
+}
+```
+
+## Custom Comparison Function
+
+```tsx
+import { createStoreState, useStoreSelector } from 'react-microstore';
+
+const taskStore = createStoreState({
+  tasks: [
+    { id: 1, title: 'Learn React', completed: false, priority: 'high' },
+    { id: 2, title: 'Build app', completed: false, priority: 'medium' }
+  ],
+  filters: {
+    showCompleted: true,
+    priorityFilter: null
+  }
+});
+
+function TaskList() {
+  // Only re-render when task completion status changes
+  const { tasks } = useStoreSelector(taskStore, [
+    { tasks: (prev, next) => 
+      prev.some(t => t.completed) !== next.some(t => t.completed) 
+    }
+  ]);
+  
+  const toggleTask = (id) => {
+    const currentTasks = taskStore.get().tasks;
+    const updatedTasks = currentTasks.map(task => 
+      task.id === id ? { ...task, completed: !task.completed } : task
+    );
+    
+    taskStore.set({ tasks: updatedTasks });
+  };
+  
+  return (
+    <ul>
+      {tasks.map(task => (
+        <li key={task.id}>
+          {task.title} - {task.completed ? 'Done' : 'Pending'}
+          <button onClick={() => toggleTask(task.id)}>
+            Toggle
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Example of setting store from outside components
+
+```tsx
+import { createStoreState, useStoreSelector } from 'react-microstore';
+
+// Create store
+const userStore = createStoreState({
+  user: null,
+  isLoading: false,
+  error: null
+});
+
+// Function to update store from anywhere
+export async function fetchUserData(userId) {
+  // Update loading state
+  userStore.set({ isLoading: true, error: null });
+  
+  try {
+    // API call
+    const response = await fetch(`/api/users/${userId}`);
+    const userData = await response.json();
+    
+    // Update store with fetched data
+    userStore.set({ 
+      user: userData,
+      isLoading: false 
+    });
+    
+    return userData;
+  } catch (error) {
+    // Update store with error
+    userStore.set({ 
+      error: error.message,
+      isLoading: false 
+    });
+    
+    throw error;
+  }
+}
+
+// Components can use the store
+function UserProfile() {
+  const { user, isLoading, error } = useStoreSelector(userStore, ['user', 'isLoading', 'error']);
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+  if (!user) return <div>No user data</div>;
+  
+  return (
+    <div>
+      <h2>{user.name}</h2>
+      <p>Email: {user.email}</p>
+    </div>
+  );
+}
+
+// Can call the function from anywhere
+// fetchUserData('123');
+```
+
+## Features
+
+- Extremely lightweight (less than 2KB minified)
+- Fine-grained subscriptions to minimize re-renders
+- Custom comparison functions for complex state updates
+- Fully Type-safe
+- No dependencies other than React
+- Update store from anywhere in your application
+
+## Development Tools
+
+### ESLint Plugin
+
+[eslint-plugin-react-microstore](https://www.npmjs.com/package/eslint-plugin-react-microstore) provides ESLint rules to help you write with react-microstore.
+
+#### Installation
+
+```bash
+npm install --save-dev eslint-plugin-react-microstore
+```
+
+#### Usage
+
+ESLint configuration:
+
+```json
+{
+  "plugins": ["react-microstore"],
+  "rules": {
+    "react-microstore/no-unused-selector-keys": "warn"
+  }
+}
+```
+
+ `react-microstore/no-unused-selector-keys`  
+  Warns when you select keys in `useStoreSelector` but don't destructure or use them.
+
+```tsx
+// ❌ This will trigger the rule
+const { a } = useStoreSelector(store, ['a', 'b']); // 'b' is unused
+
+// ✅ This is fine
+const { a, b } = useStoreSelector(store, ['a', 'b']);
+```

package/dist/index.d.mts

@@ -0,0 +1,21 @@
+type StoreListener = () => void;
+declare function createStoreState<T>(initialState: T): {
+    get: () => T;
+    set: (next: Partial<T>) => void;
+    subscribe: (keys: (keyof T)[], listener: StoreListener) => (() => void);
+};
+type StoreType<T> = ReturnType<typeof createStoreState<T>>;
+type PrimitiveKey<T> = keyof T;
+type CompareFn<V> = (prev: V, next: V) => boolean;
+type KeySelector<T> = PrimitiveKey<T>;
+type CustomSelector<T> = {
+    [K in keyof T]?: CompareFn<T[K]>;
+};
+type SelectorInput<T> = ReadonlyArray<KeySelector<T> | CustomSelector<T>>;
+type ExtractSelectorKeys<T, S extends SelectorInput<T>> = {
+    [K in S[number] extends infer Item ? Item extends keyof T ? Item : keyof Item : never]: T[K];
+};
+type Picked<T, S extends SelectorInput<T>> = ExtractSelectorKeys<T, S>;
+declare function useStoreSelector<T, S extends SelectorInput<T>>(store: StoreType<T>, selector: S): Picked<T, S>;
+
+export { createStoreState, useStoreSelector };

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+type StoreListener = () => void;
+declare function createStoreState<T>(initialState: T): {
+    get: () => T;
+    set: (next: Partial<T>) => void;
+    subscribe: (keys: (keyof T)[], listener: StoreListener) => (() => void);
+};
+type StoreType<T> = ReturnType<typeof createStoreState<T>>;
+type PrimitiveKey<T> = keyof T;
+type CompareFn<V> = (prev: V, next: V) => boolean;
+type KeySelector<T> = PrimitiveKey<T>;
+type CustomSelector<T> = {
+    [K in keyof T]?: CompareFn<T[K]>;
+};
+type SelectorInput<T> = ReadonlyArray<KeySelector<T> | CustomSelector<T>>;
+type ExtractSelectorKeys<T, S extends SelectorInput<T>> = {
+    [K in S[number] extends infer Item ? Item extends keyof T ? Item : keyof Item : never]: T[K];
+};
+type Picked<T, S extends SelectorInput<T>> = ExtractSelectorKeys<T, S>;
+declare function useStoreSelector<T, S extends SelectorInput<T>>(store: StoreType<T>, selector: S): Picked<T, S>;
+
+export { createStoreState, useStoreSelector };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var l=Object.defineProperty;var P=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames,g=Object.getOwnPropertySymbols;var h=Object.prototype.hasOwnProperty,I=Object.prototype.propertyIsEnumerable;var x=(r,e,t)=>e in r?l(r,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):r[e]=t,k=(r,e)=>{for(var t in e||(e={}))h.call(e,t)&&x(r,t,e[t]);if(g)for(var t of g(e))I.call(e,t)&&x(r,t,e[t]);return r};var C=(r,e)=>{for(var t in e)l(r,t,{get:e[t],enumerable:!0})},V=(r,e,t,a)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of v(e))!h.call(r,s)&&s!==t&&l(r,s,{get:()=>e[s],enumerable:!(a=P(e,s))||a.enumerable});return r};var F=r=>V(l({},"__esModule",{value:!0}),r);var R={};C(R,{createStoreState:()=>j,useStoreSelector:()=>O});module.exports=F(R);var f=require("react");function j(r){let e=r,t=new Map;return{get:()=>e,set:T=>{var n;let i=!1,o=[];for(let c in T)Object.is(e[c],T[c])||(i=!0,o.push(c));if(i){e=k(k({},e),T);for(let c of o)(n=t.get(c))==null||n.forEach(b=>b())}},subscribe:(T,i)=>{for(let o of T)t.has(o)||t.set(o,new Set),t.get(o).add(i);return()=>{var o;for(let n of T)(o=t.get(n))==null||o.delete(i)}}}}function O(r,e){let t=(0,f.useRef)(r.get()),a=(0,f.useRef)({}),s=e.flatMap(o=>typeof o=="string"?[{key:o}]:Object.entries(o).map(([n,c])=>({key:n,compare:c}))),m=()=>{let o=r.get(),n=t.current;if(!(!a.current||Object.keys(a.current).length===0||s.some(({key:y,compare:p})=>{let u=n[y],S=o[y];return p?p(u,S):!Object.is(u,S)})))return a.current;t.current=o;let d={};for(let{key:y,compare:p}of s){let u=a.current[y],S=o[y],K=p?p(u,S):!Object.is(u,S);d[y]=K?S:u}return a.current=d,d},T=(()=>{let o=r.get();return s.reduce((n,{key:c})=>(n[c]=o[c],n),{})})();return(0,f.useSyncExternalStore)(o=>r.subscribe(s.map(n=>n.key),o),m,()=>T)}0&&(module.exports={createStoreState,useStoreSelector});

package/dist/index.mjs

@@ -0,0 +1 @@
+var h=Object.defineProperty;var m=Object.getOwnPropertySymbols;var K=Object.prototype.hasOwnProperty,P=Object.prototype.propertyIsEnumerable;var b=(o,r,t)=>r in o?h(o,r,{enumerable:!0,configurable:!0,writable:!0,value:t}):o[r]=t,l=(o,r)=>{for(var t in r||(r={}))K.call(r,t)&&b(o,t,r[t]);if(m)for(var t of m(r))P.call(r,t)&&b(o,t,r[t]);return o};import{useRef as g,useSyncExternalStore as v}from"react";function V(o){let r=o,t=new Map;return{get:()=>r,set:c=>{var n;let T=!1,e=[];for(let s in c)Object.is(r[s],c[s])||(T=!0,e.push(s));if(T){r=l(l({},r),c);for(let s of e)(n=t.get(s))==null||n.forEach(k=>k())}},subscribe:(c,T)=>{for(let e of c)t.has(e)||t.set(e,new Set),t.get(e).add(T);return()=>{var e;for(let n of c)(e=t.get(n))==null||e.delete(T)}}}}function F(o,r){let t=g(o.get()),a=g({}),S=r.flatMap(e=>typeof e=="string"?[{key:e}]:Object.entries(e).map(([n,s])=>({key:n,compare:s}))),d=()=>{let e=o.get(),n=t.current;if(!(!a.current||Object.keys(a.current).length===0||S.some(({key:i,compare:p})=>{let y=n[i],u=e[i];return p?p(y,u):!Object.is(y,u)})))return a.current;t.current=e;let f={};for(let{key:i,compare:p}of S){let y=a.current[i],u=e[i],x=p?p(y,u):!Object.is(y,u);f[i]=x?u:y}return a.current=f,f},c=(()=>{let e=o.get();return S.reduce((n,{key:s})=>(n[s]=e[s],n),{})})();return v(e=>o.subscribe(S.map(n=>n.key),e),d,()=>c)}export{V as createStoreState,F as useStoreSelector};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "dev-react-microstore",
+  "version": "1.0.0",
+  "description": "A minimal global state manager for React with fine-grained subscriptions.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --minify",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "react",
+    "state",
+    "store",
+    "microstore",
+    "selector",
+    "hook",
+    "tiny",
+    "minimal"
+  ],
+  "author": "Ohad Baehr",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+import { useRef, useSyncExternalStore } from 'react';
+type StoreListener = () => void;
+
+export function createStoreState<T>(initialState: T) {
+  let state = initialState;
+
+  // Map from key to set of subscribers interested in that key
+  const keyListeners = new Map<keyof T, Set<StoreListener>>();
+
+  const get = () => state;
+
+  const set = (next: Partial<T>) => {
+    let changed = false;
+    const updatedKeys: (keyof T)[] = [];
+
+    for (const key in next) {
+      if (!Object.is(state[key], next[key])) {
+        changed = true;
+        updatedKeys.push(key);
+      }
+    }
+
+    if (!changed) return;
+
+    state = { ...state, ...next };
+
+    for (const key of updatedKeys) {
+      keyListeners.get(key)?.forEach(listener => listener());
+    }
+  };
+
+  const subscribe = (keys: (keyof T)[], listener: StoreListener): (() => void) => {
+    for (const key of keys) {
+      if (!keyListeners.has(key)) {
+        keyListeners.set(key, new Set());
+      }
+      keyListeners.get(key)!.add(listener);
+    }
+
+    return () => {
+      for (const key of keys) {
+        keyListeners.get(key)?.delete(listener);
+      }
+    };
+  };
+
+  return { get, set, subscribe };
+}
+
+type StoreType<T> = ReturnType<typeof createStoreState<T>>;
+type PrimitiveKey<T> = keyof T;
+type CompareFn<V> = (prev: V, next: V) => boolean;
+
+type KeySelector<T> = PrimitiveKey<T>;
+type CustomSelector<T> = { [K in keyof T]?: CompareFn<T[K]> };
+type SelectorInput<T> = ReadonlyArray<KeySelector<T> | CustomSelector<T>>;
+
+type ExtractSelectorKeys<T, S extends SelectorInput<T>> = {
+  [K in S[number] extends infer Item
+    ? Item extends keyof T
+      ? Item
+      : keyof Item
+    : never]: T[K];
+};
+
+type Picked<T, S extends SelectorInput<T>> = ExtractSelectorKeys<T, S>;
+
+type NormalizedSelector<T> = {
+  key: keyof T;
+  compare?: CompareFn<T[keyof T]>;
+};
+
+export function useStoreSelector<T, S extends SelectorInput<T>>(
+  store: StoreType<T>,
+  selector: S
+): Picked<T, S> {
+  const lastState = useRef(store.get());
+  const lastSelected = useRef<Partial<T>>({});
+
+  const normalized = selector.flatMap((item): NormalizedSelector<T>[] => {
+    if (typeof item === 'string') {
+      return [{ key: item as keyof T }];
+    }
+    return Object.entries(item).map(([key, compare]) => ({
+      key: key as keyof T,
+      compare: compare as CompareFn<T[keyof T]>,
+    }));
+  });
+
+  const getSnapshot = () => {
+    const current = store.get();
+    const prev = lastState.current;
+
+    const isFirstRun = !lastSelected.current || Object.keys(lastSelected.current).length === 0;
+
+    const changed = isFirstRun || normalized.some(({ key, compare }) => {
+      const prevVal = prev[key];
+      const nextVal = current[key];
+      return compare ? compare(prevVal, nextVal) : !Object.is(prevVal, nextVal);
+    });
+
+    if (!changed) {
+      return lastSelected.current as Picked<T, S>;
+    }
+
+    lastState.current = current;
+
+    const nextSelected: Partial<T> = {};
+
+    for (const { key, compare } of normalized) {
+      const prevVal = lastSelected.current[key];
+      const nextVal = current[key];
+      const hasChanged = compare
+        ? compare(prevVal as T[keyof T], nextVal as T[keyof T])
+        : !Object.is(prevVal, nextVal);
+
+      nextSelected[key] = hasChanged ? nextVal : prevVal;
+    }
+
+    lastSelected.current = nextSelected;
+
+    return nextSelected as Picked<T, S>;
+  };
+
+  const staticSnapshot = (() => {
+    const current = store.get();
+    return normalized.reduce((acc, { key }) => {
+      acc[key] = current[key];
+      return acc;
+    }, {} as Partial<T>) as Picked<T, S>;
+  })();
+  
+  const subscribe = (onStoreChange: () => void) =>
+    store.subscribe(normalized.map(sel => sel.key), onStoreChange);
+  return useSyncExternalStore(subscribe, getSnapshot, () => staticSnapshot);
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "target": "ES6",
+        "module": "ES6",
+        "declaration": true,
+        "outDir": "dist",
+        "strict": true,
+        "esModuleInterop": true,
+        "lib": ["ES2019", "DOM"],
+        "moduleResolution": "node"
+    },
+    "include": [
+        "src"
+    ]
+}