@plasius/react-state 1.0.1

package/src/create-scoped-store.tsx

@@ -0,0 +1,87 @@
+import { createContext, useContext, useRef, useSyncExternalStore } from "react";
+import type { IState, IAction, Store } from "./store.js";
+import { createStore } from "./store.js";
+
+function shallowEqual(a: any, b: any) {
+  if (Object.is(a, b)) return true;
+  if (
+    typeof a !== "object" ||
+    a === null ||
+    typeof b !== "object" ||
+    b === null
+  )
+    return false;
+  const ak = Object.keys(a),
+    bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (let i = 0; i < ak.length; i++) {
+    const k = ak[i] as string;
+    if (
+      !Object.prototype.hasOwnProperty.call(b, k) ||
+      !Object.is((a as any)[k], (b as any)[k])
+    )
+      return false;
+  }
+  return true;
+}
+
+export function createScopedStoreContext<S extends IState, A extends IAction>(
+  reducer: (state: S, action: A) => S,
+  initialState: S
+) {
+  const Context = createContext<Store<S, A> | null>(null);
+
+  const store = createStore(reducer, initialState);
+
+  const Provider = ({ children }: { children: React.ReactNode }) => (
+    <Context.Provider value={store}>{children}</Context.Provider>
+  );
+
+  const useStore = (): S => {
+    const ctx = useContext(Context);
+    if (!ctx) throw new Error("Store not found in context");
+    return useSyncExternalStore(ctx.subscribe, ctx.getState, ctx.getState);
+  };
+
+  const useDispatch = (): ((action: A) => void) => {
+    const ctx = useContext(Context);
+    if (!ctx) throw new Error("Dispatch not found in context");
+    return (action: A) => ctx.dispatch(action);
+  };
+
+  function useSelector<T>(
+    selector: (state: S) => T,
+    isEqual: (a: T, b: T) => boolean = shallowEqual
+  ): T {
+    const ctx = useContext(Context);
+    if (!ctx) throw new Error("Store not found in context");
+
+    // Subscribe to the raw state snapshot (stable reference until a dispatch)
+    const state = useSyncExternalStore(
+      ctx.subscribe,
+      ctx.getState,
+      ctx.getState
+    );
+
+    // Cache the selected slice per state snapshot to avoid returning fresh objects during render
+    const lastRef = useRef<{ state: S; selected: T } | null>(null);
+    const last = lastRef.current;
+    const nextSelected = selector(state);
+
+    if (last && last.state === state && isEqual(last.selected, nextSelected)) {
+      return last.selected; // return cached reference to satisfy getSnapshot caching
+    }
+
+    lastRef.current = { state, selected: nextSelected };
+    return nextSelected;
+  }
+
+  return {
+    store,
+    Context,
+    Provider,
+    useStore,
+    useDispatch,
+    useSelector,
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./create-scoped-store.js";
+export * from "./store.js";
+export * from "./provider.js";
+export * from "./metadata-store.js";

package/src/metadata-store.ts

@@ -0,0 +1,24 @@
+// metadata-store.ts
+export class MetadataStore<T extends object, Meta extends object> {
+  private readonly symbol: symbol;
+
+  constructor(description: string) {
+    this.symbol = Symbol(description);
+  }
+
+  set(target: T, meta: Meta) {
+    Object.defineProperty(target, this.symbol as PropertyKey, {
+      value: meta,
+      writable: false,
+      enumerable: false,
+    });
+  }
+
+  get(target: T): Meta | undefined {
+    return (target as Record<PropertyKey, Meta>)[this.symbol as PropertyKey];
+  }
+
+  has(target: T): boolean {
+    return (this.symbol as PropertyKey) in target;
+  }
+}

package/src/provider.tsx

@@ -0,0 +1,52 @@
+import React, { createContext, useContext, useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import type { Store, IState, IAction } from "./store.js";
+
+const StoreContext = createContext<Store<IState, IAction> | undefined>(undefined);
+
+function useStoreInstance<S extends IState, A extends IAction>(): Store<S, A> {
+  const store = useContext(StoreContext) as Store<S, A> | undefined;
+  if (!store) {
+    throw new Error(
+      "StoreProvider is missing in the React tree. Wrap your app with <StoreProvider store={...}>."
+    );
+  }
+  return store;
+}
+
+interface StoreProviderProps<S extends IState, A extends IAction> {
+  store: Store<S, A>;
+  children: ReactNode;
+}
+
+export function StoreProvider<S extends IState, A extends IAction>({
+  store,
+  children,
+}: StoreProviderProps<S, A>) {
+  return (
+    <StoreContext.Provider value={store as unknown as Store<IState, IAction>}>
+      {children}
+    </StoreContext.Provider>
+  );
+}
+
+export function useStore<S extends IState>(): S {
+  const store = useStoreInstance<S, IAction>();
+  const [state, setState] = useState<S>(() => store.getState());
+
+  useEffect(() => {
+    // Subscribe to store changes and update local state.
+    const unsubscribe = store.subscribe(() => {
+      setState(store.getState());
+    });
+    return unsubscribe;
+  }, [store]);
+
+  return state;
+}
+
+export function useDispatch<A extends IAction>(): Store<IState, A>["dispatch"] {
+  const store = useStoreInstance<IState, A>();
+  // Return the store's dispatch directly; consumers can call dispatch(action).
+  return store.dispatch as Store<IState, A>["dispatch"];
+}

package/src/store.ts

@@ -0,0 +1,131 @@
+import type { Reducer, Listener } from "./types.js";
+
+// Allow narrower parameter types for callbacks without fighting variance
+type BivariantListener<T> = {
+  bivarianceHack(value: T): void;
+}["bivarianceHack"];
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface IState {}
+export interface IAction {
+  type: string;
+}
+
+export interface Store<S extends IState, A extends IAction> {
+  getState(): S;
+  dispatch(action: A): void;
+  /**
+   * Subscribe to all state changes.
+   */
+  subscribe(listener: Listener): () => void;
+  /**
+   * Subscribe to changes of a specific key in the state.
+   */
+  subscribeToKey<K extends keyof S>(
+    key: K,
+    listener: (value: S[K]) => void
+  ): () => void;
+  /**
+   * Subscribe to changes in a selected value from the state.
+   */
+  subscribeWithSelector<T>(
+    selector: (state: S) => T,
+    listener: (selected: T) => void
+  ): () => void;
+}
+
+export function createStore<S extends IState, A extends IAction>(
+  reducer: Reducer<S, A>,
+  initialState: S
+): Store<S, A> {
+  let state = initialState;
+  const listeners = new Set<Listener>();
+  const keyListeners = new Map<keyof S, Set<BivariantListener<S[keyof S]>>>();
+
+  interface SelectorEntry<T> {
+    selector: (state: S) => T;
+    listener: BivariantListener<T>;
+    lastValue: T;
+  }
+  const selectorListeners = new Set<SelectorEntry<unknown>>();
+
+  const getState = () => state;
+
+  const dispatch = (action: A) => {
+    const prevState = state;
+    const nextState = reducer(state, action);
+
+    // Distinct-until-changed: if the reducer returns the same reference,
+    // skip all notifications (prevents unnecessary re-renders).
+    if (Object.is(prevState, nextState)) {
+      state = nextState; // keep any identity guarantees from reducer
+      return;
+    }
+
+    state = nextState;
+
+    // Notify global listeners (iterate over a snapshot so unsubscribe during
+    // notify does not skip the next listener)
+    for (const listener of [...listeners]) listener();
+
+    // Notify key listeners only when that key actually changed (Object.is)
+    for (const [key, set] of keyListeners.entries()) {
+      if (!Object.is(prevState[key], state[key])) {
+        for (const listener of [...set]) listener(state[key]);
+      }
+    }
+
+    // Notify selector listeners only when selected value changed (Object.is)
+    selectorListeners.forEach((entry) => {
+      const nextValue = (entry.selector as (s: S) => unknown)(state);
+      if (!Object.is(entry.lastValue, nextValue)) {
+        entry.lastValue = nextValue as unknown;
+        (entry.listener as (v: unknown) => void)(nextValue);
+      }
+    });
+  };
+
+  const subscribe = (listener: Listener) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+
+  const subscribeToKey = <K extends keyof S>(
+    key: K,
+    listener: (value: S[K]) => void
+  ) => {
+    const set =
+      keyListeners.get(key) ?? new Set<BivariantListener<S[keyof S]>>();
+    set.add(listener as unknown as BivariantListener<S[keyof S]>);
+    keyListeners.set(key, set);
+    return () => {
+      set.delete(listener as unknown as BivariantListener<S[keyof S]>);
+      if (set.size === 0) keyListeners.delete(key);
+    };
+  };
+
+  const subscribeWithSelector = <T>(
+    selector: (state: S) => T,
+    listener: (selected: T) => void
+  ) => {
+    const entry: SelectorEntry<T> = {
+      selector,
+      listener: listener as BivariantListener<T>,
+      lastValue: selector(state),
+    };
+    selectorListeners.add(entry as unknown as SelectorEntry<unknown>);
+    return () => {
+      selectorListeners.delete(entry as unknown as SelectorEntry<unknown>);
+    };
+  };
+
+  return {
+    getState,
+    dispatch,
+    subscribe,
+    subscribeToKey,
+    subscribeWithSelector,
+  };
+}

package/src/types.ts

@@ -0,0 +1,3 @@
+export type Reducer<S, A> = (state: S, action: A) => S;
+export type Listener = () => void;
+export type Unsubscribe = () => void;

package/tests/scoped.store.test.tsx

@@ -0,0 +1,75 @@
+import React from "react"; // tests/setup.ts
+import "@testing-library/jest-dom";
+import { render, fireEvent } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { createScopedStoreContext } from "../src";
+
+describe("scoped store", () => {
+  const initialState = { count: 0 };
+  const reducer = (
+    state: typeof initialState,
+    action: { type: string; payload?: number }
+  ) => {
+    switch (action.type) {
+      case "inc":
+        return { count: state.count + 1 };
+      case "dec":
+        return { count: state.count - 1 };
+      case "set":
+        return { count: action.payload ?? state.count };
+      default:
+        return state;
+    }
+  };
+
+  const store = createScopedStoreContext(reducer, initialState);
+
+  const Counter = () => {
+    const state = store.useStore();
+    const dispatch = store.useDispatch();
+
+    return (
+      <div>
+        <button id="counter-inc" onClick={() => dispatch({ type: "inc" })}>
+          +
+        </button>
+        <button id="counter-dec" onClick={() => dispatch({ type: "dec" })}>
+          -
+        </button>
+        <input
+          aria-label="Counter value"
+          title=""
+          id="counter-set"
+          type="number"
+          value={state.count}
+          onChange={(e) =>
+            dispatch({ type: "set", payload: Number(e.target.value) })
+          }
+        />
+      </div>
+    );
+  };
+
+  it("increments, decrements, and sets the counter correctly", () => {
+    const { getByText, getByLabelText } = render(
+      <store.Provider>
+        <Counter />
+      </store.Provider>
+    );
+
+    const incButton = getByText("+");
+    const decButton = getByText("-");
+    const input = getByLabelText("Counter value") as HTMLInputElement;
+
+    expect(input.value).toBe("0");
+
+    fireEvent.click(incButton);
+    expect(input.value).toBe("1");
+
+    fireEvent.click(decButton);
+    expect(input.value).toBe("0");
+
+    fireEvent.change(input, { target: { value: "5" } });
+    expect(input.value).toBe("5");
+  });
+});

package/tests/store.core.test.ts

@@ -0,0 +1,295 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  createStore,
+  type Store,
+  type IState,
+  type IAction,
+} from "../src/store";
+
+type S = { count: number; meta?: { tag: string } };
+type A =
+  | { type: "inc" }
+  | { type: "set"; value: number }
+  | { type: "setMeta"; tag: string }
+  | { type: "noop" };
+
+const reducer = (s: S, a: A): S => {
+  switch (a.type) {
+    case "inc":
+      return { ...s, count: s.count + 1 };
+    case "set":
+      return { ...s, count: a.value };
+    case "setMeta":
+      return { ...s, meta: { tag: a.tag } };
+    case "noop":
+      return s; // return same reference to simulate no-change dispatch
+    default:
+      return s;
+  }
+};
+
+const initial: S = { count: 0, meta: { tag: "a" } };
+
+describe("createStore – basics", () => {
+  it("getState returns initial; dispatch updates", () => {
+    const store = createStore<S, A>(reducer, initial);
+    expect(store.getState()).toEqual(initial);
+    store.dispatch({ type: "inc" });
+    expect(store.getState().count).toBe(1);
+  });
+});
+
+describe("subscribe (global)", () => {
+  it("fires only when state reference changes (distinct-until-changed)", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const cb = vi.fn();
+    const un = store.subscribe(cb);
+
+    store.dispatch({ type: "noop" }); // same reference → no notify
+    store.dispatch({ type: "inc" });  // changed       → notify once
+
+    expect(cb).toHaveBeenCalledTimes(1);
+    un();
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("subscribeToKey (per-key)", () => {
+  it("notifies only when that key changes", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const cb = vi.fn();
+    const un = store.subscribeToKey("count", cb);
+
+    store.dispatch({ type: "setMeta", tag: "b" }); // different key
+    expect(cb).not.toHaveBeenCalled();
+
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenLastCalledWith(1);
+
+    un();
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes empty key sets when last listener unsubscribes", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const cb1 = vi.fn();
+    const cb2 = vi.fn();
+
+    const un1 = store.subscribeToKey("count", cb1);
+    const un2 = store.subscribeToKey("count", cb2);
+
+    un1();
+    un2();
+    // We can't directly inspect keyListeners map, but we can assert no leaks by re-subscribing and ensuring it still works.
+    const cb3 = vi.fn();
+    const un3 = store.subscribeToKey("count", cb3);
+    store.dispatch({ type: "inc" });
+    expect(cb3).toHaveBeenCalledTimes(1);
+    un3();
+  });
+});
+
+describe("subscribeWithSelector (derived changes)", () => {
+  it("does not call immediately; calls when selected value changes", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const sel = (s: S) => s.count;
+    const cb = vi.fn();
+
+    const un = store.subscribeWithSelector(sel, cb);
+    expect(cb).not.toHaveBeenCalled();
+
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenLastCalledWith(1);
+
+    un();
+  });
+
+  it("does not call if selector result is referentially equal", () => {
+    const store = createStore<S, A>(reducer, { count: 0, meta: { tag: "x" } });
+    const sel = (s: S) => s.meta?.tag; // primitive equality
+    const cb = vi.fn();
+
+    const un = store.subscribeWithSelector(sel, cb);
+    store.dispatch({ type: "setMeta", tag: "x" }); // new object, same tag
+    expect(cb).not.toHaveBeenCalled();
+
+    store.dispatch({ type: "setMeta", tag: "y" });
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenLastCalledWith("y");
+    un();
+  });
+});
+
+describe("notification order", () => {
+  it("global → key → selector", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const calls: string[] = [];
+
+    const unG = store.subscribe(() => calls.push("global"));
+    const unK = store.subscribeToKey("count", () => calls.push("key"));
+    const unS = store.subscribeWithSelector(
+      (s) => s.count,
+      () => calls.push("selector")
+    );
+
+    store.dispatch({ type: "inc" });
+
+    expect(calls).toEqual(["global", "key", "selector"]);
+    unG();
+    unK();
+    unS();
+  });
+});
+
+describe("mutation during iteration (edge case)", () => {
+  it("unsubscribing within a global listener may skip the next listener (document current behavior)", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const log: string[] = [];
+
+    let un1: () => void = () => {};
+    const l1 = () => {
+      log.push("l1");
+      un1();
+    }; // removes itself during dispatch
+    const l2 = () => {
+      log.push("l2");
+    };
+
+    un1 = store.subscribe(l1);
+    store.subscribe(l2);
+
+    store.dispatch({ type: "inc" });
+
+    // Depending on Array#forEach semantics with splice, l2 might be skipped.
+    // Document current behavior so a future change (copy-before-iterate) can flip this expectation.
+    expect(log.length === 1 || log.length === 2).toBe(true);
+  });
+});
+
+describe("no-change dispatch side-effects", () => {
+  it("global does not fire; key/selector do not", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const g = vi.fn();
+    const k = vi.fn();
+    const s = vi.fn();
+
+    store.subscribe(g);
+    store.subscribeToKey("count", k);
+    store.subscribeWithSelector((st) => st.count, s);
+
+    store.dispatch({ type: "noop" }); // same reference returned → no notifications
+
+    expect(g).toHaveBeenCalledTimes(0);
+    expect(k).not.toHaveBeenCalled();
+    expect(s).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Additional coverage for core store semantics
+
+describe("state identity & no-op behavior", () => {
+  it("returns the same state reference after a no-op and a new reference after a change", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const s1 = store.getState();
+    store.dispatch({ type: "noop" });
+    const s2 = store.getState();
+    expect(s2).toBe(s1); // identity equal on no-op
+
+    store.dispatch({ type: "inc" });
+    const s3 = store.getState();
+    expect(s3).not.toBe(s2); // new object on change
+  });
+});
+
+describe("unsubscribe semantics", () => {
+  it("global unsubscribe stops further notifications", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const cb = vi.fn();
+    const un = store.subscribe(cb);
+
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+    un();
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("per-key unsubscribe stops further notifications", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const cb = vi.fn();
+    const un = store.subscribeToKey("count", cb);
+
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+    un();
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("selector unsubscribe stops further notifications", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const cb = vi.fn();
+    const un = store.subscribeWithSelector((s) => s.count, cb);
+
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+    un();
+    store.dispatch({ type: "inc" });
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("multiple subscribers", () => {
+  it("notifies all global subscribers once per change", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const a = vi.fn();
+    const b = vi.fn();
+    store.subscribe(a);
+    store.subscribe(b);
+
+    store.dispatch({ type: "inc" });
+
+    expect(a).toHaveBeenCalledTimes(1);
+    expect(b).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("mutation during iteration – per-key/selector", () => {
+  it("unsubscribing within a per-key listener may skip the next listener (document current behavior)", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const log: string[] = [];
+
+    let un1: () => void = () => {};
+    const l1 = () => { log.push("k1"); un1(); };
+    const l2 = () => { log.push("k2"); };
+
+    un1 = store.subscribeToKey("count", l1);
+    store.subscribeToKey("count", l2);
+
+    store.dispatch({ type: "inc" });
+
+    // Depending on iteration strategy, l2 may be skipped when l1 unsubscribes.
+    expect(log.length === 1 || log.length === 2).toBe(true);
+  });
+
+  it("unsubscribing within a selector listener may skip the next listener (document current behavior)", () => {
+    const store = createStore<S, A>(reducer, initial);
+    const log: string[] = [];
+
+    let un1: () => void = () => {};
+    const l1 = () => { log.push("s1"); un1(); };
+    const l2 = () => { log.push("s2"); };
+
+    un1 = store.subscribeWithSelector((s) => s.count, l1);
+    store.subscribeWithSelector((s) => s.count, l2);
+
+    store.dispatch({ type: "inc" });
+
+    expect(log.length === 1 || log.length === 2).toBe(true);
+  });
+});

package/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "NodeNext",
+    "lib": ["ESNext", "DOM"],
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "types": ["node", "vitest"],
+    "declaration": true,
+    "sourceMap": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "resolveJsonModule": true,
+    "outDir": "dist",
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}