Add support for silent state updates and immediate events

Author: yatish1606

.npmignore

@@ -1,2 +1,3 @@
 dist/
-node_modules/
+node_modules/
+CHANGELOG.md

.prettierrc

@@ -5,7 +5,7 @@
   "insertPragma": false,
   "jsxBracketSameLine": false,
   "jsxSingleQuote": true,
-  "printWidth": 80,
+  "printWidth": 100,
   "proseWrap": "always",
   "quoteProps": "as-needed",
   "requirePragma": false,

CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[keep a changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.0.7] - 2025-08-30
+
+#### Added
+
+- Include `CHANGELOG.md` as part of Github push, exclude from npm push.
+- Added support for silent state updates via `options.silent` for setter, and support for firing a
+  state update event directly via `options.fireImmediately` during subscription.
+- Separated type definitions into `StoreSetOptions` and `StoreSubscriptionOptions`
+
+#### Changes
+
+- Renamed `useBeacon` to `useValue`
+
+## [1.0.6] - 2025-08-27
+
+#### Changed
+
+- Renamed library to `react-orba`
+- Modify README.md
+- 🟡 **TODO**: Rename `useBeacon` and it's implementations.
+
+## [1.0.5] - 2025-08-26 [open-sourced]
+
+#### Added
+
+- Added .npmignore
+
+## [1.0.4] - 2025-07-14
+
+#### Added
+
+- Prettier for linting
+
+#### Changed
+
+- Prepare command `"prepare": "npx prettier . --write && npm run build",` now formats before build.
+- Fixed issue with `useBeacon` that would break for non-primitive types.
+
+## [1.0.3] - 2025-06-10
+
+#### Added
+
+- Helper function `mapSelectedStateToGlobalState<T, U>` added to map updated state slices with
+  global state.
+
+#### Changed
+
+- `useBeacon` uses a state setter to merge updated states along with `unstable_batchedUpdates`.
+- 🔴 **VERSION DEPENDENCY**: React 18+
+
+## [1.0.2] - 2025-05-28
+
+#### Added
+
+- Hook now uses `useSyncExternalStore` for batched updates.
+
+#### Changed
+
+- `useGlobalState` renamed to `useBeacon`
+- `useBeacon` returns a tuple, with current state and updater function.
+
+## [1.0.1] - 2025-04-19
+
+#### Added
+
+- README.md added along with basic usage for primitives.
+- 🟡 **TODO**: README requires detailed examples, along with usage of complex data types.
+
+## [1.0.0] - 2025-01-22
+
+#### Added
+
+- Initial release with core pub-sub and minimal TypeScript types.

README.md

@@ -1,9 +1,9 @@
-## react-orba
+# react-orba
 
-A simple, lightweight state management library for React applications. Works
-over the pub-sub model and batches state updates.
+A simple, lightweight state management library for React applications. Works over the pub-sub model
+and batches state updates.
 
-### Usage
+## Usage
 
 1. At the root of your app or a module, create a store.
 
@@ -29,8 +29,7 @@ const initialParams: AppState = {
 const appStore = createStore<AppState>(initialParams);
 ```
 
-2. In your component, slice out your state variable(s) using the `useBeacon`
-   hook.
+2. In your component, slice out your state variable(s) using the `useBeacon` hook.
 
 ```tsx
 import { appStore } from '../App';
@@ -44,7 +43,7 @@ const [theme, setTheme] = useBeacon(appStore, (state) => state.theme);
 <button onClick={() => setTheme('light')}>Toggle theme</button>
 ```
 
-### Running on local
+## Running on local
 
 1. Clone the repo
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-orba",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "A global state manager for React applications, minus the ceremony",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",

src/core/store.ts

@@ -1,5 +1,5 @@
 import { unstable_batchedUpdates as batch } from 'react-dom';
-import { Listener } from '../types';
+import { Listener, StoreSetOptions, StoreSubscriptionOptions } from '../types';
 
 function createStore<T>(initialState: T) {
   let state: T = initialState;
@@ -9,19 +9,22 @@ function createStore<T>(initialState: T) {
     return state;
   }
 
-  function set(next: T | ((prev: T) => T)) {
+  function set(next: T | ((prev: T) => T), options?: StoreSetOptions) {
     const prev: T = state;
     state = typeof next === 'function' ? (next as any)(prev) : next;
 
-    if (Object.is(prev, state)) return;
+    if (Object.is(prev, state) || options?.silent) return;
 
     batch(() => {
       listeners.forEach((listener) => listener(state, prev));
     });
   }
 
-  function subscribe(listener: Listener<T>) {
+  function subscribe(listener: Listener<T>, options?: StoreSubscriptionOptions) {
     listeners.add(listener);
+    if (options?.fireImmediately) {
+      listener(state, state);
+    }
     return () => listeners.delete(listener);
   }
 

src/core/useBeacon.ts

@@ -2,27 +2,19 @@ import { useSyncExternalStore, useCallback } from 'react';
 import { Store } from '../types';
 import { unstable_batchedUpdates } from 'react-dom';
 
-function useBeacon<T, U>(
+function useValue<T, U>(
   store: Store<T>,
   selector: (state: T) => U,
 ): [U, (updater: (previousState: U) => U) => void] {
-  const getSnapshot = useCallback(
-    () => selector(store.get()),
-    [store, selector],
-  );
-  const state: U = useSyncExternalStore(
-    store.subscribe,
-    getSnapshot,
-    getSnapshot,
-  );
+  const getSnapshot = useCallback(() => selector(store.get()), [store, selector]);
+  const state: U = useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
 
   const setState = useCallback(
     (updater: (prevState: U) => U) => {
       unstable_batchedUpdates(() => {
         store.set((prevState) => {
           const selectedState = selector(prevState);
-          const newState =
-            typeof updater === 'function' ? updater(selectedState) : updater;
+          const newState = typeof updater === 'function' ? updater(selectedState) : updater;
           return {
             ...prevState,
             ...mapSelectedStateToGlobalState(selector, newState, prevState),
@@ -48,23 +40,19 @@ function mapSelectedStateToGlobalState<T, U>(
         return { [key]: newState } as Partial<T>;
       }
     }
-    throw new Error(
-      'Could not map primitive selected state back to global state.',
-    );
+    throw new Error('Could not map primitive selected state back to global state.');
   }
 
   const selectedKeys = Object.keys(selector(prevState) as Object);
   const updates: Partial<T> = {};
 
   selectedKeys.forEach((key) => {
     if (key in (newState as Object)) {
-      updates[key as keyof T] = newState[
-        key as keyof U
-      ] as unknown as T[keyof T];
+      updates[key as keyof T] = newState[key as keyof U] as unknown as T[keyof T];
     }
   });
 
   return updates;
 }
 
-export default useBeacon;
+export default useValue;

src/index.ts

@@ -1,4 +1,4 @@
-import useBeacon from './core/useBeacon';
+import useValue from './core/useBeacon';
 import createStore from './core/store';
 
-export { createStore, useBeacon };
+export { createStore, useValue };

src/types.ts

@@ -1,13 +1,18 @@
 type Listener<T> = (state: T, prev: T) => void;
 type EqualityFn<T> = (first: T, second: T) => boolean;
 
+type StoreSetOptions = {
+  silent?: boolean;
+};
+
+type StoreSubscriptionOptions = {
+  fireImmediately?: boolean;
+};
+
 type Store<T> = {
   get: () => T;
-  set: (next: T | ((prev: T) => T), opts?: { silent?: boolean }) => void;
-  subscribe: (
-    listener: Listener<T>,
-    options?: { fireImmediately?: boolean },
-  ) => () => void;
+  set: (next: T | ((prev: T) => T), options?: StoreSetOptions) => void;
+  subscribe: (listener: Listener<T>, options?: StoreSubscriptionOptions) => () => void;
 };
 
-export { Listener, EqualityFn, Store };
+export { EqualityFn, Listener, Store, StoreSetOptions, StoreSubscriptionOptions };