@nice-code/state 0.3.3

package/build/index.js

@@ -0,0 +1,241 @@
+// src/core/Store.ts
+import { deepEqual } from "fast-equals";
+import {
+  applyPatches,
+  enablePatches,
+  produce,
+  produceWithPatches
+} from "immer";
+enablePatches();
+function makeSubscriptionFunction(store, watch, listener) {
+  let lastWatchState = watch(store.getRawState());
+  return () => {
+    const currentState = store.getRawState();
+    const nextWatchState = watch(currentState);
+    if (nextWatchState === lastWatchState) {
+      return;
+    }
+    if (deepEqual(nextWatchState, lastWatchState)) {
+      lastWatchState = nextWatchState;
+      return;
+    }
+    const previousWatched = lastWatchState;
+    lastWatchState = nextWatchState;
+    listener(nextWatchState, currentState, previousWatched);
+  };
+}
+function makeReactionFunctionCreator(watch, reaction) {
+  return (store) => {
+    let lastWatchState = watch(store.getRawState());
+    return (forceRun = false) => {
+      const currentState = store.getRawState();
+      const nextWatchState = watch(currentState);
+      if (!forceRun) {
+        if (nextWatchState === lastWatchState) {
+          return;
+        }
+        if (deepEqual(nextWatchState, lastWatchState)) {
+          lastWatchState = nextWatchState;
+          return;
+        }
+      }
+      const previousWatched = lastWatchState;
+      lastWatchState = nextWatchState;
+      if (store._hasPatchListeners()) {
+        const [nextState, patches, inversePatches] = produceWithPatches(currentState, (draft) => {
+          reaction(nextWatchState, draft, currentState, previousWatched);
+        });
+        store._updateStateWithoutReaction(nextState);
+        if (patches.length > 0) {
+          store._emitPatches(patches, inversePatches);
+        }
+      } else {
+        const nextState = produce(currentState, (draft) => {
+          reaction(nextWatchState, draft, currentState, previousWatched);
+        });
+        store._updateStateWithoutReaction(nextState);
+      }
+    };
+  };
+}
+
+class Store {
+  currentState;
+  createInitialState;
+  ssr = false;
+  listeners = new Set;
+  reactionCreators = [];
+  reactions = [];
+  clientSubscriptions = [];
+  _patchListeners = [];
+  constructor(initialState) {
+    if (initialState instanceof Function) {
+      this.createInitialState = initialState;
+      this.currentState = initialState();
+    } else {
+      this.createInitialState = () => initialState;
+      this.currentState = initialState;
+    }
+  }
+  _setInternalOptions({ ssr, reactionCreators = [] }) {
+    this.ssr = ssr;
+    this.reactionCreators = reactionCreators;
+    this.reactions = reactionCreators.map((rc) => rc(this));
+  }
+  _getReactionCreators() {
+    return this.reactionCreators;
+  }
+  _instantiateReactions() {
+    this.reactions = this.reactionCreators.map((rc) => rc(this));
+  }
+  _getInitialState() {
+    return this.createInitialState();
+  }
+  _hasPatchListeners() {
+    return this._patchListeners.length > 0;
+  }
+  _emitPatches(patches, inversePatches) {
+    for (const listener of this._patchListeners) {
+      listener(patches, inversePatches);
+    }
+  }
+  _updateStateWithoutReaction(nextState) {
+    this.currentState = nextState;
+  }
+  _updateState(nextState) {
+    this.currentState = nextState;
+    for (const runReaction of this.reactions) {
+      runReaction();
+    }
+    if (this.ssr) {
+      return;
+    }
+    for (const runSubscription of this.clientSubscriptions) {
+      runSubscription();
+    }
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+  getRawState() {
+    return this.currentState;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  watch(watch, listener) {
+    if (this.ssr) {
+      return () => {
+        console.warn(`@nice-code/state: Subscriptions made on the server side are not registered, so this unsubscribe call does nothing.`);
+      };
+    }
+    const run = makeSubscriptionFunction(this, watch, listener);
+    this.clientSubscriptions.push(run);
+    return () => {
+      this.clientSubscriptions = this.clientSubscriptions.filter((f) => f !== run);
+    };
+  }
+  createReaction(watch, reaction, { runNow = false, runNowWithSideEffects = false } = {}) {
+    const creator = makeReactionFunctionCreator(watch, reaction);
+    this.reactionCreators.push(creator);
+    const run = creator(this);
+    this.reactions.push(run);
+    if (runNow || runNowWithSideEffects) {
+      run(true);
+      if (runNowWithSideEffects && !this.ssr) {
+        this._updateState(this.currentState);
+      }
+    }
+    return () => {
+      this.reactions = this.reactions.filter((f) => f !== run);
+      this.reactionCreators = this.reactionCreators.filter((f) => f !== creator);
+    };
+  }
+  listenToPatches(patchListener) {
+    this._patchListeners.push(patchListener);
+    return () => {
+      this._patchListeners = this._patchListeners.filter((f) => f !== patchListener);
+    };
+  }
+  update(updater, patchesCallback) {
+    update(this, updater, patchesCallback);
+  }
+  replace(newState) {
+    if (newState !== this.currentState) {
+      this._updateState(newState);
+    }
+  }
+  replaceFromCurrent(replacer) {
+    const nextState = replacer(this.currentState);
+    if (nextState !== this.currentState) {
+      this._updateState(nextState);
+    }
+  }
+  applyPatches(patches) {
+    applyPatchesToStore(this, patches);
+  }
+}
+function applyPatchesToStore(store, patches) {
+  const currentState = store.getRawState();
+  const nextState = applyPatches(currentState, patches);
+  if (nextState !== currentState) {
+    store._updateState(nextState);
+  }
+}
+function applyUpdaterWithPatches(currentState, updater) {
+  if (typeof updater === "function") {
+    const [next, patches2, inversePatches2] = produceWithPatches(currentState, (draft) => {
+      updater(draft, currentState);
+    });
+    return [next, patches2, inversePatches2];
+  }
+  let state = currentState;
+  const patches = [];
+  const inversePatches = [];
+  for (const single of updater) {
+    const [next, p, ip] = produceWithPatches(state, (draft) => {
+      single(draft, state);
+    });
+    state = next;
+    patches.push(...p);
+    inversePatches.push(...ip);
+  }
+  return [state, patches, inversePatches];
+}
+function applyUpdater(currentState, updater) {
+  if (typeof updater === "function") {
+    return produce(currentState, (draft) => {
+      updater(draft, currentState);
+    });
+  }
+  return updater.reduce((previousState, single) => produce(previousState, (draft) => {
+    single(draft, previousState);
+  }), currentState);
+}
+function update(store, updater, patchesCallback) {
+  const currentState = store.getRawState();
+  let nextState;
+  if (store._hasPatchListeners() || patchesCallback != null) {
+    const [next, patches, inversePatches] = applyUpdaterWithPatches(currentState, updater);
+    if (patches.length > 0) {
+      if (patchesCallback != null) {
+        patchesCallback(patches, inversePatches);
+      }
+      store._emitPatches(patches, inversePatches);
+    }
+    nextState = next;
+  } else {
+    nextState = applyUpdater(currentState, updater);
+  }
+  if (nextState !== currentState) {
+    store._updateState(nextState);
+  }
+}
+export {
+  update,
+  applyPatchesToStore,
+  Store
+};

package/build/react/index.js

@@ -0,0 +1,315 @@
+// src/react/useStoreState.ts
+import { useCallback, useRef, useSyncExternalStore } from "react";
+function strictEqual(a, b) {
+  return a === b;
+}
+function useStoreState(store, getSubState, equalityFn = strictEqual) {
+  const selectorRef = useRef(getSubState);
+  const equalityRef = useRef(equalityFn);
+  selectorRef.current = getSubState;
+  equalityRef.current = equalityFn;
+  const cacheRef = useRef(null);
+  const getSnapshot = useCallback(() => {
+    const rawState = store.getRawState();
+    const selector = selectorRef.current;
+    const nextValue = selector ? selector(rawState) : rawState;
+    const cache = cacheRef.current;
+    if (cache === null) {
+      cacheRef.current = { value: nextValue };
+      return nextValue;
+    }
+    const lastValue = cache.value;
+    if (nextValue === lastValue) {
+      return lastValue;
+    }
+    if (equalityRef.current(lastValue, nextValue)) {
+      return lastValue;
+    }
+    cache.value = nextValue;
+    return nextValue;
+  }, [store]);
+  const subscribe = useCallback((onStoreChange) => store.subscribe(onStoreChange), [store]);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+// src/react/InjectStoreState.ts
+function InjectStoreState({
+  store,
+  on,
+  equalityFn,
+  children
+}) {
+  const state = useStoreState(store, on ?? ((s) => s), equalityFn);
+  return children(state);
+}
+// src/react/useLocalStore.ts
+import { useRef as useRef2 } from "react";
+
+// src/core/Store.ts
+import { deepEqual } from "fast-equals";
+import {
+  applyPatches,
+  enablePatches,
+  produce,
+  produceWithPatches
+} from "immer";
+enablePatches();
+function makeSubscriptionFunction(store, watch, listener) {
+  let lastWatchState = watch(store.getRawState());
+  return () => {
+    const currentState = store.getRawState();
+    const nextWatchState = watch(currentState);
+    if (nextWatchState === lastWatchState) {
+      return;
+    }
+    if (deepEqual(nextWatchState, lastWatchState)) {
+      lastWatchState = nextWatchState;
+      return;
+    }
+    const previousWatched = lastWatchState;
+    lastWatchState = nextWatchState;
+    listener(nextWatchState, currentState, previousWatched);
+  };
+}
+function makeReactionFunctionCreator(watch, reaction) {
+  return (store) => {
+    let lastWatchState = watch(store.getRawState());
+    return (forceRun = false) => {
+      const currentState = store.getRawState();
+      const nextWatchState = watch(currentState);
+      if (!forceRun) {
+        if (nextWatchState === lastWatchState) {
+          return;
+        }
+        if (deepEqual(nextWatchState, lastWatchState)) {
+          lastWatchState = nextWatchState;
+          return;
+        }
+      }
+      const previousWatched = lastWatchState;
+      lastWatchState = nextWatchState;
+      if (store._hasPatchListeners()) {
+        const [nextState, patches, inversePatches] = produceWithPatches(currentState, (draft) => {
+          reaction(nextWatchState, draft, currentState, previousWatched);
+        });
+        store._updateStateWithoutReaction(nextState);
+        if (patches.length > 0) {
+          store._emitPatches(patches, inversePatches);
+        }
+      } else {
+        const nextState = produce(currentState, (draft) => {
+          reaction(nextWatchState, draft, currentState, previousWatched);
+        });
+        store._updateStateWithoutReaction(nextState);
+      }
+    };
+  };
+}
+
+class Store {
+  currentState;
+  createInitialState;
+  ssr = false;
+  listeners = new Set;
+  reactionCreators = [];
+  reactions = [];
+  clientSubscriptions = [];
+  _patchListeners = [];
+  constructor(initialState) {
+    if (initialState instanceof Function) {
+      this.createInitialState = initialState;
+      this.currentState = initialState();
+    } else {
+      this.createInitialState = () => initialState;
+      this.currentState = initialState;
+    }
+  }
+  _setInternalOptions({ ssr, reactionCreators = [] }) {
+    this.ssr = ssr;
+    this.reactionCreators = reactionCreators;
+    this.reactions = reactionCreators.map((rc) => rc(this));
+  }
+  _getReactionCreators() {
+    return this.reactionCreators;
+  }
+  _instantiateReactions() {
+    this.reactions = this.reactionCreators.map((rc) => rc(this));
+  }
+  _getInitialState() {
+    return this.createInitialState();
+  }
+  _hasPatchListeners() {
+    return this._patchListeners.length > 0;
+  }
+  _emitPatches(patches, inversePatches) {
+    for (const listener of this._patchListeners) {
+      listener(patches, inversePatches);
+    }
+  }
+  _updateStateWithoutReaction(nextState) {
+    this.currentState = nextState;
+  }
+  _updateState(nextState) {
+    this.currentState = nextState;
+    for (const runReaction of this.reactions) {
+      runReaction();
+    }
+    if (this.ssr) {
+      return;
+    }
+    for (const runSubscription of this.clientSubscriptions) {
+      runSubscription();
+    }
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+  getRawState() {
+    return this.currentState;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  watch(watch, listener) {
+    if (this.ssr) {
+      return () => {
+        console.warn(`@nice-code/state: Subscriptions made on the server side are not registered, so this unsubscribe call does nothing.`);
+      };
+    }
+    const run = makeSubscriptionFunction(this, watch, listener);
+    this.clientSubscriptions.push(run);
+    return () => {
+      this.clientSubscriptions = this.clientSubscriptions.filter((f) => f !== run);
+    };
+  }
+  createReaction(watch, reaction, { runNow = false, runNowWithSideEffects = false } = {}) {
+    const creator = makeReactionFunctionCreator(watch, reaction);
+    this.reactionCreators.push(creator);
+    const run = creator(this);
+    this.reactions.push(run);
+    if (runNow || runNowWithSideEffects) {
+      run(true);
+      if (runNowWithSideEffects && !this.ssr) {
+        this._updateState(this.currentState);
+      }
+    }
+    return () => {
+      this.reactions = this.reactions.filter((f) => f !== run);
+      this.reactionCreators = this.reactionCreators.filter((f) => f !== creator);
+    };
+  }
+  listenToPatches(patchListener) {
+    this._patchListeners.push(patchListener);
+    return () => {
+      this._patchListeners = this._patchListeners.filter((f) => f !== patchListener);
+    };
+  }
+  update(updater, patchesCallback) {
+    update(this, updater, patchesCallback);
+  }
+  replace(newState) {
+    if (newState !== this.currentState) {
+      this._updateState(newState);
+    }
+  }
+  replaceFromCurrent(replacer) {
+    const nextState = replacer(this.currentState);
+    if (nextState !== this.currentState) {
+      this._updateState(nextState);
+    }
+  }
+  applyPatches(patches) {
+    applyPatchesToStore(this, patches);
+  }
+}
+function applyPatchesToStore(store, patches) {
+  const currentState = store.getRawState();
+  const nextState = applyPatches(currentState, patches);
+  if (nextState !== currentState) {
+    store._updateState(nextState);
+  }
+}
+function applyUpdaterWithPatches(currentState, updater) {
+  if (typeof updater === "function") {
+    const [next, patches2, inversePatches2] = produceWithPatches(currentState, (draft) => {
+      updater(draft, currentState);
+    });
+    return [next, patches2, inversePatches2];
+  }
+  let state = currentState;
+  const patches = [];
+  const inversePatches = [];
+  for (const single of updater) {
+    const [next, p, ip] = produceWithPatches(state, (draft) => {
+      single(draft, state);
+    });
+    state = next;
+    patches.push(...p);
+    inversePatches.push(...ip);
+  }
+  return [state, patches, inversePatches];
+}
+function applyUpdater(currentState, updater) {
+  if (typeof updater === "function") {
+    return produce(currentState, (draft) => {
+      updater(draft, currentState);
+    });
+  }
+  return updater.reduce((previousState, single) => produce(previousState, (draft) => {
+    single(draft, previousState);
+  }), currentState);
+}
+function update(store, updater, patchesCallback) {
+  const currentState = store.getRawState();
+  let nextState;
+  if (store._hasPatchListeners() || patchesCallback != null) {
+    const [next, patches, inversePatches] = applyUpdaterWithPatches(currentState, updater);
+    if (patches.length > 0) {
+      if (patchesCallback != null) {
+        patchesCallback(patches, inversePatches);
+      }
+      store._emitPatches(patches, inversePatches);
+    }
+    nextState = next;
+  } else {
+    nextState = applyUpdater(currentState, updater);
+  }
+  if (nextState !== currentState) {
+    store._updateState(nextState);
+  }
+}
+
+// src/react/useLocalStore.ts
+function shallowEqualDeps(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a == null || b == null || a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0;i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+function useLocalStore(initialState, deps) {
+  const storeRef = useRef2(null);
+  const depsRef = useRef2(deps);
+  if (storeRef.current === null) {
+    storeRef.current = new Store(initialState);
+  } else if (deps !== undefined && !shallowEqualDeps(depsRef.current, deps)) {
+    storeRef.current = new Store(initialState);
+    depsRef.current = deps;
+  }
+  return storeRef.current;
+}
+export {
+  useStoreState,
+  useLocalStore,
+  InjectStoreState
+};

package/build/types/core/Store.d.ts

@@ -0,0 +1,135 @@
+import { type Draft, type Patch, type PatchListener } from "immer";
+/**
+ * A plain pub/sub listener. Fired (in the order added) every time the store's
+ * root state reference changes. This is the vanilla integration point that any
+ * ecosystem — including the React adapter's `useSyncExternalStore` — builds on.
+ */
+export type TUpdateListener = () => void;
+/**
+ * @typeParam S  The store's state
+ * @param draft     The mutable draft to change during this update (Immer proxy).
+ * @param original  A readonly snapshot of the state as it was before this update.
+ */
+export type TUpdateFunction<S> = (draft: Draft<S>, original: S) => void;
+/**
+ * A selector that derives a watched slice `T` from the full store state `S`.
+ */
+export type TStoreWatch<S extends object, T> = (state: S) => T;
+/**
+ * Fired by {@link Store.watch} whenever the watched slice changes structurally.
+ */
+export type TStoreSubscriptionListener<S extends object, T> = (watched: T, allState: S, previousWatched: T) => void;
+/**
+ * Runs inside an Immer `produce` whenever a watched slice changes, letting the
+ * store derive further state from its own mutations.
+ */
+export type TReactionFunction<S extends object, T> = (watched: T, draft: Draft<S>, original: S, previousWatched: T) => void;
+export type TStoreActionUpdate<S extends object> = (updater: TUpdateFunction<S> | TUpdateFunction<S>[], patchesCallback?: TPatchesCallback) => void;
+export type TStoreAction<S extends object> = (update: TStoreActionUpdate<S>) => void;
+export type TPatchesCallback = (patches: Patch[], inversePatches: Patch[]) => void;
+export interface IStoreInternalOptions<S extends object> {
+    ssr: boolean;
+    reactionCreators?: TReactionCreator<S>[];
+}
+export interface ICreateReactionOptions {
+    runNow?: boolean;
+    runNowWithSideEffects?: boolean;
+}
+/**
+ * A framework-agnostic, Immer-backed state container.
+ *
+ * The store owns a single immutable state value and a `Set` of plain
+ * listeners. Every mutation runs through Immer's `produce`, and listeners are
+ * only notified when the resulting root reference actually changes — making
+ * "no-op" updates genuinely free for subscribers.
+ *
+ * @typeParam S  Your store's state interface.
+ */
+export declare class Store<S extends object = object> {
+    private currentState;
+    private readonly createInitialState;
+    private ssr;
+    /** Plain pub/sub listeners — a Set both dedupes and dispatches fast. */
+    private readonly listeners;
+    private reactionCreators;
+    private reactions;
+    private clientSubscriptions;
+    constructor(initialState: S | (() => S));
+    /**
+     * Returns the raw state object contained within this store at this moment.
+     *
+     * ---
+     * ** WARNING **
+     *
+     * Most of the time, if you're using this in your app, there's probably a
+     * better way to do it (a selector subscription or the React adapter).
+     * ---
+     */
+    getRawState(): S;
+    /**
+     * Subscribe a plain listener to store mutations. The listener fires once per
+     * committed update (root reference change) and receives no arguments — read
+     * the latest value with {@link getRawState}.
+     *
+     * This is the low-level primitive that vanilla code and framework adapters
+     * (e.g. React's `useSyncExternalStore`) build upon.
+     *
+     * @returns An unsubscribe function.
+     */
+    subscribe(listener: TUpdateListener): () => void;
+    /**
+     * Subscribe to a derived slice of state. The `listener` only fires when the
+     * watched value changes structurally (per the Fast-Path rule).
+     *
+     * @returns An unsubscribe function.
+     */
+    watch<T>(watch: TStoreWatch<S, T>, listener: TStoreSubscriptionListener<S, T>): () => void;
+    /**
+     * Register a reaction: when the watched slice changes, the `reaction` recipe
+     * runs inside Immer to derive further state on the same store.
+     *
+     * @returns A function that removes the reaction.
+     */
+    createReaction<T>(watch: TStoreWatch<S, T>, reaction: TReactionFunction<S, T>, { runNow, runNowWithSideEffects }?: ICreateReactionOptions): () => void;
+    /**
+     * Subscribe to the Immer patches produced by each update.
+     *
+     * @returns An unsubscribe function.
+     */
+    listenToPatches(patchListener: PatchListener): () => void;
+    /**
+     * Mutate the store via one or more Immer update functions.
+     *
+     * @param updater          A single update function, or an array applied in order.
+     * @param patchesCallback  Optional callback receiving the patches for this update.
+     */
+    update(updater: TUpdateFunction<S> | TUpdateFunction<S>[], patchesCallback?: TPatchesCallback): void;
+    /**
+     * Replace the store's state entirely with a new state value.
+     */
+    replace(newState: S): void;
+    /**
+     * Replace the store's state by mapping from the current state.
+     */
+    replaceFromCurrent(replacer: (state: S) => S): void;
+    /**
+     * Apply a set of Immer patches to the store.
+     */
+    applyPatches(patches: Patch[]): void;
+}
+/**
+ * Apply Immer patches to a store, committing only if the root reference changes.
+ */
+export declare function applyPatchesToStore<S extends object = object>(store: Store<S>, patches: Patch[]): void;
+/**
+ * Mutate a store via one or more Immer update functions.
+ *
+ * Patches are only computed when there's a consumer for them (a registered
+ * patch listener or a `patchesCallback`), keeping the common path allocation-free.
+ * Listeners are notified only when the root reference actually changes.
+ *
+ * @param store            The store to update.
+ * @param updater          A single update function, or an array applied in order.
+ * @param patchesCallback  Optional callback receiving the patches for this update.
+ */
+export declare function update<S extends object = object>(store: Store<S>, updater: TUpdateFunction<S> | TUpdateFunction<S>[], patchesCallback?: TPatchesCallback): void;

package/build/types/core/index.d.ts

@@ -0,0 +1 @@
+export { applyPatchesToStore, type ICreateReactionOptions, type IStoreInternalOptions, Store, type TPatchesCallback, type TReactionFunction, type TStoreAction, type TStoreActionUpdate, type TStoreSubscriptionListener, type TStoreWatch, type TUpdateFunction, type TUpdateListener, update, } from "./Store";

package/build/types/devtools/browser/NiceStateDevtools.d.ts

@@ -0,0 +1,8 @@
+import type { StateDevtoolsCore } from "../core/StateDevtoolsCore";
+import type { TDevtoolsPosition } from "../core/StateDevtools.types";
+export interface INiceStateDevtoolsProps {
+    core: StateDevtoolsCore;
+    position?: TDevtoolsPosition;
+    initialOpen?: boolean;
+}
+export declare function NiceStateDevtools(props: INiceStateDevtoolsProps): import("react/jsx-runtime").JSX.Element | null;

package/build/types/devtools/browser/components/ChangeDetailPanel.d.ts

@@ -0,0 +1,5 @@
+import type { IDevtoolsStateChange } from "../../core/StateDevtools.types";
+export declare function ChangeDetailPanel({ change, onRevert, }: {
+    change: IDevtoolsStateChange;
+    onRevert: (change: IDevtoolsStateChange) => void;
+}): import("react/jsx-runtime").JSX.Element;