@nice-code/state 0.7.0 → 0.9.0

package/build/Store-PjfFkZ2I.js

@@ -0,0 +1,349 @@
+import { deepEqual } from "fast-equals";
+import { applyPatches, enablePatches, produce, produceWithPatches } from "immer";
+//#region src/core/Store.ts
+enablePatches();
+/**
+* @internal
+*
+* Builds the per-emission runner for a selector subscription.
+*
+* Change detection follows the "Fast-Path" rule: Immer's structural sharing
+* means an untouched branch keeps its exact reference, so a strict `===` check
+* resolves the overwhelmingly common "nothing changed" case in 0ms. Only when
+* the reference actually changes do we pay for a `deepEqual` traversal to
+* confirm the change is structural and not just a new-but-equal reference.
+*/
+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);
+	};
+}
+/**
+* @internal
+*
+* Builds a reaction creator. Reactions follow the same Fast-Path rule as
+* subscriptions, then run their recipe inside Immer to derive further state.
+*/
+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);
+			}
+		};
+	};
+}
+/**
+* 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.
+*/
+var Store = class {
+	currentState;
+	createInitialState;
+	ssr = false;
+	/** Plain pub/sub listeners — a Set both dedupes and dispatches fast. */
+	listeners = /* @__PURE__ */ new Set();
+	reactionCreators = [];
+	reactions = [];
+	clientSubscriptions = [];
+	/**
+	* @internal
+	*/
+	_patchListeners = [];
+	constructor(initialState) {
+		if (initialState instanceof Function) {
+			this.createInitialState = initialState;
+			this.currentState = initialState();
+		} else {
+			this.createInitialState = () => initialState;
+			this.currentState = initialState;
+		}
+	}
+	get state() {
+		return Object.freeze(this.currentState);
+	}
+	/**
+	* @internal
+	*/
+	_setInternalOptions({ ssr, reactionCreators = [] }) {
+		this.ssr = ssr;
+		this.reactionCreators = reactionCreators;
+		this.reactions = reactionCreators.map((rc) => rc(this));
+	}
+	/**
+	* @internal
+	*/
+	_getReactionCreators() {
+		return this.reactionCreators;
+	}
+	/**
+	* @internal
+	*/
+	_instantiateReactions() {
+		this.reactions = this.reactionCreators.map((rc) => rc(this));
+	}
+	/**
+	* @internal
+	*/
+	_getInitialState() {
+		return this.createInitialState();
+	}
+	/**
+	* @internal
+	*/
+	_hasPatchListeners() {
+		return this._patchListeners.length > 0;
+	}
+	/**
+	* @internal
+	*/
+	_emitPatches(patches, inversePatches) {
+		for (const listener of this._patchListeners) listener(patches, inversePatches);
+	}
+	/**
+	* @internal
+	*
+	* Writes a new state value without running reactions. Used by reactions
+	* themselves to avoid re-entrancy.
+	*/
+	_updateStateWithoutReaction(nextState) {
+		this.currentState = nextState;
+	}
+	/**
+	* @internal
+	*
+	* Commits a new root state, runs reactions, then dispatches to all
+	* subscribers. Callers are responsible for the `nextState !== currentState`
+	* reference guard before invoking this.
+	*/
+	_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();
+	}
+	/**
+	* 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() {
+		return this.currentState;
+	}
+	/**
+	* 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) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/**
+	* 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(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);
+		};
+	}
+	/**
+	* 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(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);
+		};
+	}
+	/**
+	* Subscribe to the Immer patches produced by each update.
+	*
+	* @returns An unsubscribe function.
+	*/
+	listenToPatches(patchListener) {
+		this._patchListeners.push(patchListener);
+		return () => {
+			this._patchListeners = this._patchListeners.filter((f) => f !== patchListener);
+		};
+	}
+	/**
+	* 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, patchesCallback) {
+		update(this, updater, patchesCallback);
+	}
+	/**
+	* Replace the store's state entirely with a new state value.
+	*/
+	replace(newState) {
+		if (newState !== this.currentState) this._updateState(newState);
+	}
+	/**
+	* Replace the store's state by mapping from the current state.
+	*/
+	replaceFromCurrent(replacer) {
+		const nextState = replacer(this.currentState);
+		if (nextState !== this.currentState) this._updateState(nextState);
+	}
+	/**
+	* Apply a set of Immer patches to the store.
+	*/
+	applyPatches(patches) {
+		applyPatchesToStore(this, patches);
+	}
+};
+/**
+* Apply Immer patches to a store, committing only if the root reference changes.
+*/
+function applyPatchesToStore(store, patches) {
+	const currentState = store.getRawState();
+	const nextState = applyPatches(currentState, patches);
+	if (nextState !== currentState) store._updateState(nextState);
+}
+/**
+* @internal
+*
+* Runs an updater (or array of updaters) through Immer, collecting patches.
+*/
+function applyUpdaterWithPatches(currentState, updater) {
+	if (typeof updater === "function") {
+		const [next, patches, inversePatches] = produceWithPatches(currentState, (draft) => {
+			updater(draft, currentState);
+		});
+		return [
+			next,
+			patches,
+			inversePatches
+		];
+	}
+	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
+	];
+}
+/**
+* @internal
+*
+* Runs an updater (or array of updaters) through Immer without tracking patches.
+*/
+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);
+}
+/**
+* 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.
+*/
+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);
+}
+//#endregion
+export { applyPatchesToStore as n, update as r, Store as t };
+
+//# sourceMappingURL=Store-PjfFkZ2I.js.map

package/build/Store-PjfFkZ2I.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Store-PjfFkZ2I.js","names":[],"sources":["../src/core/Store.ts"],"sourcesContent":["import { deepEqual } from \"fast-equals\";\r\nimport {\r\n  applyPatches,\r\n  type Draft,\r\n  enablePatches,\r\n  type Patch,\r\n  type PatchListener,\r\n  produce,\r\n  produceWithPatches,\r\n} from \"immer\";\r\n\r\n// Immer emits JSON patches for `produceWithPatches`, which the store exposes via\r\n// `listenToPatches`. This must run once, before any patch-producing update.\r\nenablePatches();\r\n\r\n/**\r\n * A plain pub/sub listener. Fired (in the order added) every time the store's\r\n * root state reference changes. This is the vanilla integration point that any\r\n * ecosystem — including the React adapter's `useSyncExternalStore` — builds on.\r\n */\r\nexport type TUpdateListener = () => void;\r\n\r\n/**\r\n * @typeParam S  The store's state\r\n * @param draft     The mutable draft to change during this update (Immer proxy).\r\n * @param original  A readonly snapshot of the state as it was before this update.\r\n */\r\nexport type TUpdateFunction<S> = (draft: Draft<S>, original: S) => void;\r\n\r\n/**\r\n * A selector that derives a watched slice `T` from the full store state `S`.\r\n */\r\nexport type TStoreWatch<S extends object, T> = (state: S) => T;\r\n\r\n/**\r\n * Fired by {@link Store.watch} whenever the watched slice changes structurally.\r\n */\r\nexport type TStoreSubscriptionListener<S extends object, T> = (\r\n  watched: T,\r\n  allState: S,\r\n  previousWatched: T,\r\n) => void;\r\n\r\n/**\r\n * Runs inside an Immer `produce` whenever a watched slice changes, letting the\r\n * store derive further state from its own mutations.\r\n */\r\nexport type TReactionFunction<S extends object, T> = (\r\n  watched: T,\r\n  draft: Draft<S>,\r\n  original: S,\r\n  previousWatched: T,\r\n) => void;\r\n\r\nexport type TStoreActionUpdate<S extends object> = (\r\n  updater: TUpdateFunction<S> | TUpdateFunction<S>[],\r\n  patchesCallback?: TPatchesCallback,\r\n) => void;\r\n\r\nexport type TStoreAction<S extends object> = (update: TStoreActionUpdate<S>) => void;\r\n\r\nexport type TPatchesCallback = (patches: Patch[], inversePatches: Patch[]) => void;\r\n\r\n/**\r\n * @internal\r\n * Drives a registered reaction. `forceRun` bypasses the change-detection\r\n * fast-path (used when a reaction is created with `runNow`).\r\n */\r\ntype TRunReactionFunction = (forceRun?: boolean) => void;\r\n\r\n/**\r\n * @internal\r\n * Drives a registered selector subscription on every store emission.\r\n */\r\ntype TRunSubscriptionFunction = () => void;\r\n\r\n/**\r\n * @internal\r\n * Binds a reaction definition to a concrete store instance.\r\n */\r\ntype TReactionCreator<S extends object> = (store: Store<S>) => TRunReactionFunction;\r\n\r\nexport interface IStoreInternalOptions<S extends object> {\r\n  ssr: boolean;\r\n  reactionCreators?: TReactionCreator<S>[];\r\n}\r\n\r\nexport interface ICreateReactionOptions {\r\n  runNow?: boolean;\r\n  runNowWithSideEffects?: boolean;\r\n}\r\n\r\n/**\r\n * @internal\r\n *\r\n * Builds the per-emission runner for a selector subscription.\r\n *\r\n * Change detection follows the \"Fast-Path\" rule: Immer's structural sharing\r\n * means an untouched branch keeps its exact reference, so a strict `===` check\r\n * resolves the overwhelmingly common \"nothing changed\" case in 0ms. Only when\r\n * the reference actually changes do we pay for a `deepEqual` traversal to\r\n * confirm the change is structural and not just a new-but-equal reference.\r\n */\r\nfunction makeSubscriptionFunction<S extends object, T>(\r\n  store: Store<S>,\r\n  watch: TStoreWatch<S, T>,\r\n  listener: TStoreSubscriptionListener<S, T>,\r\n): TRunSubscriptionFunction {\r\n  let lastWatchState: T = watch(store.getRawState());\r\n\r\n  return () => {\r\n    const currentState = store.getRawState();\r\n    const nextWatchState = watch(currentState);\r\n\r\n    // Fast-path: reference is identical → the watched branch was never touched.\r\n    if (nextWatchState === lastWatchState) {\r\n      return;\r\n    }\r\n\r\n    // Reference changed — fall back to deep equality to confirm real change.\r\n    if (deepEqual(nextWatchState, lastWatchState)) {\r\n      // Structurally equal: adopt the new reference so the fast-path stays hot,\r\n      // but do not notify — nothing the watcher cares about actually changed.\r\n      lastWatchState = nextWatchState;\r\n      return;\r\n    }\r\n\r\n    const previousWatched = lastWatchState;\r\n    lastWatchState = nextWatchState;\r\n    listener(nextWatchState, currentState, previousWatched);\r\n  };\r\n}\r\n\r\n/**\r\n * @internal\r\n *\r\n * Builds a reaction creator. Reactions follow the same Fast-Path rule as\r\n * subscriptions, then run their recipe inside Immer to derive further state.\r\n */\r\nfunction makeReactionFunctionCreator<S extends object, T>(\r\n  watch: TStoreWatch<S, T>,\r\n  reaction: TReactionFunction<S, T>,\r\n): TReactionCreator<S> {\r\n  return (store) => {\r\n    let lastWatchState: T = watch(store.getRawState());\r\n\r\n    return (forceRun = false) => {\r\n      const currentState = store.getRawState();\r\n      const nextWatchState = watch(currentState);\r\n\r\n      if (!forceRun) {\r\n        // Fast-path: identical reference → skip entirely.\r\n        if (nextWatchState === lastWatchState) {\r\n          return;\r\n        }\r\n\r\n        // New reference but structurally equal → adopt and skip the recipe.\r\n        if (deepEqual(nextWatchState, lastWatchState)) {\r\n          lastWatchState = nextWatchState;\r\n          return;\r\n        }\r\n      }\r\n\r\n      const previousWatched = lastWatchState;\r\n      lastWatchState = nextWatchState;\r\n\r\n      // Reactions mutate via Immer but must not re-enter the reaction loop, so\r\n      // they write back through the no-reaction update path.\r\n      if (store._hasPatchListeners()) {\r\n        const [nextState, patches, inversePatches] = produceWithPatches(\r\n          currentState,\r\n          (draft: Draft<S>) => {\r\n            reaction(nextWatchState, draft, currentState, previousWatched);\r\n          },\r\n        );\r\n\r\n        store._updateStateWithoutReaction(nextState);\r\n\r\n        if (patches.length > 0) {\r\n          store._emitPatches(patches, inversePatches);\r\n        }\r\n      } else {\r\n        const nextState = produce(currentState, (draft: Draft<S>) => {\r\n          reaction(nextWatchState, draft, currentState, previousWatched);\r\n        });\r\n        store._updateStateWithoutReaction(nextState);\r\n      }\r\n    };\r\n  };\r\n}\r\n\r\n/**\r\n * A framework-agnostic, Immer-backed state container.\r\n *\r\n * The store owns a single immutable state value and a `Set` of plain\r\n * listeners. Every mutation runs through Immer's `produce`, and listeners are\r\n * only notified when the resulting root reference actually changes — making\r\n * \"no-op\" updates genuinely free for subscribers.\r\n *\r\n * @typeParam S  Your store's state interface.\r\n */\r\nexport class Store<S extends object = object> {\r\n  private currentState: S;\r\n  private readonly createInitialState: () => S;\r\n  private ssr = false;\r\n\r\n  /** Plain pub/sub listeners — a Set both dedupes and dispatches fast. */\r\n  private readonly listeners = new Set<TUpdateListener>();\r\n\r\n  private reactionCreators: TReactionCreator<S>[] = [];\r\n  private reactions: TRunReactionFunction[] = [];\r\n  private clientSubscriptions: TRunSubscriptionFunction[] = [];\r\n\r\n  /**\r\n   * @internal\r\n   */\r\n  public _patchListeners: PatchListener[] = [];\r\n\r\n  constructor(initialState: S | (() => S)) {\r\n    if (initialState instanceof Function) {\r\n      this.createInitialState = initialState;\r\n      this.currentState = initialState();\r\n    } else {\r\n      this.createInitialState = () => initialState;\r\n      this.currentState = initialState;\r\n    }\r\n  }\r\n\r\n  get state(): S {\r\n    return Object.freeze(this.currentState);\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   */\r\n  _setInternalOptions({ ssr, reactionCreators = [] }: IStoreInternalOptions<S>) {\r\n    this.ssr = ssr;\r\n    this.reactionCreators = reactionCreators;\r\n    this.reactions = reactionCreators.map((rc) => rc(this));\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   */\r\n  _getReactionCreators(): TReactionCreator<S>[] {\r\n    return this.reactionCreators;\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   */\r\n  _instantiateReactions() {\r\n    this.reactions = this.reactionCreators.map((rc) => rc(this));\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   */\r\n  _getInitialState(): S {\r\n    return this.createInitialState();\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   */\r\n  _hasPatchListeners(): boolean {\r\n    return this._patchListeners.length > 0;\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   */\r\n  _emitPatches(patches: Patch[], inversePatches: Patch[]) {\r\n    for (const listener of this._patchListeners) {\r\n      listener(patches, inversePatches);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   *\r\n   * Writes a new state value without running reactions. Used by reactions\r\n   * themselves to avoid re-entrancy.\r\n   */\r\n  _updateStateWithoutReaction(nextState: S) {\r\n    this.currentState = nextState;\r\n  }\r\n\r\n  /**\r\n   * @internal\r\n   *\r\n   * Commits a new root state, runs reactions, then dispatches to all\r\n   * subscribers. Callers are responsible for the `nextState !== currentState`\r\n   * reference guard before invoking this.\r\n   */\r\n  _updateState(nextState: S) {\r\n    this.currentState = nextState;\r\n\r\n    // Reactions run first and may derive further state (without re-triggering).\r\n    for (const runReaction of this.reactions) {\r\n      runReaction();\r\n    }\r\n\r\n    if (this.ssr) {\r\n      return;\r\n    }\r\n\r\n    for (const runSubscription of this.clientSubscriptions) {\r\n      runSubscription();\r\n    }\r\n\r\n    for (const listener of this.listeners) {\r\n      listener();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Returns the raw state object contained within this store at this moment.\r\n   *\r\n   * ---\r\n   * ** WARNING **\r\n   *\r\n   * Most of the time, if you're using this in your app, there's probably a\r\n   * better way to do it (a selector subscription or the React adapter).\r\n   * ---\r\n   */\r\n  getRawState(): S {\r\n    return this.currentState;\r\n  }\r\n\r\n  /**\r\n   * Subscribe a plain listener to store mutations. The listener fires once per\r\n   * committed update (root reference change) and receives no arguments — read\r\n   * the latest value with {@link getRawState}.\r\n   *\r\n   * This is the low-level primitive that vanilla code and framework adapters\r\n   * (e.g. React's `useSyncExternalStore`) build upon.\r\n   *\r\n   * @returns An unsubscribe function.\r\n   */\r\n  subscribe(listener: TUpdateListener): () => void {\r\n    this.listeners.add(listener);\r\n    return () => {\r\n      this.listeners.delete(listener);\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Subscribe to a derived slice of state. The `listener` only fires when the\r\n   * watched value changes structurally (per the Fast-Path rule).\r\n   *\r\n   * @returns An unsubscribe function.\r\n   */\r\n  watch<T>(watch: TStoreWatch<S, T>, listener: TStoreSubscriptionListener<S, T>): () => void {\r\n    if (this.ssr) {\r\n      return () => {\r\n        console.warn(\r\n          `@nice-code/state: Subscriptions made on the server side are not registered, so this unsubscribe call does nothing.`,\r\n        );\r\n      };\r\n    }\r\n\r\n    const run = makeSubscriptionFunction(this, watch, listener);\r\n    this.clientSubscriptions.push(run);\r\n\r\n    return () => {\r\n      this.clientSubscriptions = this.clientSubscriptions.filter((f) => f !== run);\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Register a reaction: when the watched slice changes, the `reaction` recipe\r\n   * runs inside Immer to derive further state on the same store.\r\n   *\r\n   * @returns A function that removes the reaction.\r\n   */\r\n  createReaction<T>(\r\n    watch: TStoreWatch<S, T>,\r\n    reaction: TReactionFunction<S, T>,\r\n    { runNow = false, runNowWithSideEffects = false }: ICreateReactionOptions = {},\r\n  ): () => void {\r\n    const creator = makeReactionFunctionCreator(watch, reaction);\r\n    this.reactionCreators.push(creator);\r\n\r\n    const run = creator(this);\r\n    this.reactions.push(run);\r\n\r\n    if (runNow || runNowWithSideEffects) {\r\n      run(true);\r\n\r\n      if (runNowWithSideEffects && !this.ssr) {\r\n        this._updateState(this.currentState);\r\n      }\r\n    }\r\n\r\n    return () => {\r\n      this.reactions = this.reactions.filter((f) => f !== run);\r\n      this.reactionCreators = this.reactionCreators.filter((f) => f !== creator);\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Subscribe to the Immer patches produced by each update.\r\n   *\r\n   * @returns An unsubscribe function.\r\n   */\r\n  listenToPatches(patchListener: PatchListener): () => void {\r\n    this._patchListeners.push(patchListener);\r\n    return () => {\r\n      this._patchListeners = this._patchListeners.filter((f) => f !== patchListener);\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Mutate the store via one or more Immer update functions.\r\n   *\r\n   * @param updater          A single update function, or an array applied in order.\r\n   * @param patchesCallback  Optional callback receiving the patches for this update.\r\n   */\r\n  update(updater: TUpdateFunction<S> | TUpdateFunction<S>[], patchesCallback?: TPatchesCallback) {\r\n    update(this, updater, patchesCallback);\r\n  }\r\n\r\n  /**\r\n   * Replace the store's state entirely with a new state value.\r\n   */\r\n  replace(newState: S) {\r\n    if (newState !== this.currentState) {\r\n      this._updateState(newState);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Replace the store's state by mapping from the current state.\r\n   */\r\n  replaceFromCurrent(replacer: (state: S) => S) {\r\n    const nextState = replacer(this.currentState);\r\n    if (nextState !== this.currentState) {\r\n      this._updateState(nextState);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Apply a set of Immer patches to the store.\r\n   */\r\n  applyPatches(patches: Patch[]) {\r\n    applyPatchesToStore(this, patches);\r\n  }\r\n}\r\n\r\n/**\r\n * Apply Immer patches to a store, committing only if the root reference changes.\r\n */\r\nexport function applyPatchesToStore<S extends object = object>(store: Store<S>, patches: Patch[]) {\r\n  const currentState = store.getRawState();\r\n  const nextState = applyPatches(currentState, patches);\r\n  if (nextState !== currentState) {\r\n    store._updateState(nextState);\r\n  }\r\n}\r\n\r\n/**\r\n * @internal\r\n *\r\n * Runs an updater (or array of updaters) through Immer, collecting patches.\r\n */\r\nfunction applyUpdaterWithPatches<S extends object>(\r\n  currentState: S,\r\n  updater: TUpdateFunction<S> | TUpdateFunction<S>[],\r\n): [S, Patch[], Patch[]] {\r\n  if (typeof updater === \"function\") {\r\n    const [next, patches, inversePatches] = produceWithPatches(currentState, (draft: Draft<S>) => {\r\n      updater(draft, currentState);\r\n    });\r\n    return [next, patches, inversePatches];\r\n  }\r\n\r\n  let state = currentState;\r\n  const patches: Patch[] = [];\r\n  const inversePatches: Patch[] = [];\r\n\r\n  for (const single of updater) {\r\n    const [next, p, ip] = produceWithPatches(state, (draft: Draft<S>) => {\r\n      single(draft, state);\r\n    });\r\n    state = next;\r\n    patches.push(...p);\r\n    inversePatches.push(...ip);\r\n  }\r\n\r\n  return [state, patches, inversePatches];\r\n}\r\n\r\n/**\r\n * @internal\r\n *\r\n * Runs an updater (or array of updaters) through Immer without tracking patches.\r\n */\r\nfunction applyUpdater<S extends object>(\r\n  currentState: S,\r\n  updater: TUpdateFunction<S> | TUpdateFunction<S>[],\r\n): S {\r\n  if (typeof updater === \"function\") {\r\n    return produce(currentState, (draft: Draft<S>) => {\r\n      updater(draft, currentState);\r\n    });\r\n  }\r\n\r\n  return updater.reduce<S>(\r\n    (previousState, single) =>\r\n      produce(previousState, (draft: Draft<S>) => {\r\n        single(draft, previousState);\r\n      }),\r\n    currentState,\r\n  );\r\n}\r\n\r\n/**\r\n * Mutate a store via one or more Immer update functions.\r\n *\r\n * Patches are only computed when there's a consumer for them (a registered\r\n * patch listener or a `patchesCallback`), keeping the common path allocation-free.\r\n * Listeners are notified only when the root reference actually changes.\r\n *\r\n * @param store            The store to update.\r\n * @param updater          A single update function, or an array applied in order.\r\n * @param patchesCallback  Optional callback receiving the patches for this update.\r\n */\r\nexport function update<S extends object = object>(\r\n  store: Store<S>,\r\n  updater: TUpdateFunction<S> | TUpdateFunction<S>[],\r\n  patchesCallback?: TPatchesCallback,\r\n) {\r\n  const currentState = store.getRawState();\r\n\r\n  let nextState: S;\r\n\r\n  if (store._hasPatchListeners() || patchesCallback != null) {\r\n    const [next, patches, inversePatches] = applyUpdaterWithPatches(currentState, updater);\r\n\r\n    if (patches.length > 0) {\r\n      if (patchesCallback != null) {\r\n        patchesCallback(patches, inversePatches);\r\n      }\r\n      store._emitPatches(patches, inversePatches);\r\n    }\r\n\r\n    nextState = next;\r\n  } else {\r\n    nextState = applyUpdater(currentState, updater);\r\n  }\r\n\r\n  // Reference guard: an updater that mutated nothing yields the same reference,\r\n  // so we skip the dispatch entirely.\r\n  if (nextState !== currentState) {\r\n    store._updateState(nextState);\r\n  }\r\n}\r\n"],"mappings":"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"}

package/build/devtools/browser/index.d.ts

@@ -0,0 +1,120 @@
+import { r as Store } from "../../Store-B65MojT2.js";
+import { Patch } from "immer";
+//#region ../nice-devtools-shared/src/components/PanelChrome.d.ts
+/** Where a devtools panel is docked. */
+type TDevtoolsPosition = "dock-bottom" | "dock-top" | "dock-left" | "dock-right";
+//#endregion
+//#region src/devtools/core/StateDevtools.types.d.ts
+/**
+ * How a recorded change came to be. `update` is the normal Immer-patch path,
+ * `replace` is a whole-state swap with no patches, and the two `devtools-*`
+ * sources are writes the devtools itself made (manual edits / reverts) so they
+ * can be visually distinguished from real app traffic.
+ */
+type TStateChangeSource = "update" | "replace" | "devtools-edit" | "devtools-revert";
+/**
+ * A single committed mutation of a registered store. Captures both the Immer
+ * patches (when available) and full before/after snapshots so the panel can
+ * render a precise diff and offer a one-click revert.
+ */
+interface IDevtoolsStateChange {
+  cuid: string;
+  storeId: string;
+  storeLabel: string;
+  timestamp: number;
+  patches: Patch[];
+  inversePatches: Patch[];
+  prevSnapshot: unknown;
+  snapshot: unknown;
+  source: TStateChangeSource;
+}
+/**
+ * Live summary of a registered store, refreshed on every commit so the panel's
+ * tabs and state inspector always reflect the current value.
+ */
+interface IDevtoolsStoreInfo {
+  id: string;
+  label: string;
+  currentState: unknown;
+  changeCount: number;
+  lastChangeTime?: number;
+}
+interface IStateDevtoolsSnapshot {
+  stores: IDevtoolsStoreInfo[];
+  /** Most-recent-first across all registered stores. */
+  changes: IDevtoolsStateChange[];
+  paused: boolean;
+}
+type TStateDevtoolsListener = (snapshot: IStateDevtoolsSnapshot) => void;
+//#endregion
+//#region src/devtools/core/StateDevtoolsCore.d.ts
+interface IStateDevtoolsCoreOptions {
+  /** Cap on retained changes across all stores (oldest dropped first). */
+  maxChanges?: number;
+}
+/**
+ * Framework-agnostic collector for nice-state stores.
+ *
+ * Register any {@link Store} and the core hooks its patch + update streams,
+ * pairing the two so each committed mutation becomes a single
+ * {@link IDevtoolsStateChange} with patches and full before/after snapshots.
+ * The browser panel ({@link NiceStateDevtools}) renders whatever this exposes.
+ *
+ * Registering a store attaches a patch listener, which makes Immer compute
+ * patches for that store's updates — a negligible dev-time cost. Keep this out
+ * of production bundles (the panel is dev-gated, but the core is not).
+ */
+declare class StateDevtoolsCore {
+  private readonly _stores;
+  private _changes;
+  private readonly _listeners;
+  private readonly _maxChanges;
+  private _paused;
+  private _cuidCounter;
+  private _sourceOverride;
+  constructor(options?: IStateDevtoolsCoreOptions);
+  /**
+   * Start observing a store under a human-readable label. Returns an
+   * unregister function. If the label collides with an existing store, a numeric
+   * suffix is appended to keep ids unique.
+   */
+  registerStore(label: string, store: Store<any>): () => void;
+  unregisterStore(id: string): void;
+  /**
+   * Replace a registered store's state wholesale — the primary "edit directly
+   * for testing" entry point. The resulting change is tagged `devtools-edit`.
+   */
+  applyEdit(storeId: string, newState: unknown): void;
+  /**
+   * Undo a change by applying its inverse patches. Cleanest for the most recent
+   * change of a store; older reverts may not apply if later changes touched the
+   * same paths. The resulting change is tagged `devtools-revert`.
+   */
+  revertChange(change: IDevtoolsStateChange): void;
+  setPaused(paused: boolean): void;
+  togglePaused(): void;
+  /** Drop the recorded timeline; registered stores and their state remain. */
+  clear(): void;
+  getSnapshot(): IStateDevtoolsSnapshot;
+  subscribe(listener: TStateDevtoolsListener): () => void;
+  private _recordChange;
+  private _uniqueId;
+  private _buildSnapshot;
+  private _notify;
+}
+//#endregion
+//#region src/devtools/browser/NiceStateDevtools.d.ts
+interface INiceStateDevtoolsProps {
+  core: StateDevtoolsCore;
+  position?: TDevtoolsPosition;
+  initialOpen?: boolean;
+  /** Show the panel even when NODE_ENV is not "development". */
+  forceEnable?: boolean;
+}
+declare function NiceStateDevtools({
+  forceEnable,
+  ...props
+}: INiceStateDevtoolsProps): import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+export { type IDevtoolsStateChange, type IDevtoolsStoreInfo, type INiceStateDevtoolsProps, type IStateDevtoolsCoreOptions, type IStateDevtoolsSnapshot, NiceStateDevtools, StateDevtoolsCore, type TDevtoolsPosition, type TStateChangeSource, type TStateDevtoolsListener };
+//# sourceMappingURL=index.d.ts.map