@reckona/mreact-store

@reckona/mreact-store

@reckona/mreact-store provides global and shared state primitives for mreact. It builds on cell from @reckona/mreact-reactive-core and keeps selectors, actions, transactions, and persistence as small composable pieces.

Basic Usage

import { createStore, shallowEqual } from "@reckona/mreact-store";

const counter = createStore({ count: 0, label: "counter" });

const count = counter.select((state) => state.count);
const snapshot = counter.select((state) => ({ label: state.label }), shallowEqual);

counter.set((state) => ({ count: state.count + 1 }));

Use store.view for reference-stable deep readonly reads and store.snapshot() when an independent mutable copy is required. Readonly views do not freeze the live object, so updates still go through set(), replace(), or update().

const readonlyState = counter.view.get();
const independent = counter.snapshot();
independent.count = 10;

Core APIs

• createStore() creates a store with state and actions.
• store.select() subscribes to a reactive slice of store state and returns a selected cell with dispose() for code that creates selectors outside the framework cleanup lifecycle.
• store.subscribe() observes changes from outside the framework runtime.
• store.view exposes readonly state, selectors, and subscriptions without cloning each read.
• store.snapshot() clones arrays, plain objects, dates, regular expressions, URLs, maps, sets, ArrayBuffers, DataViews, and typed arrays. Functions remain shared references; arbitrary class instances, weak collections, and promises are rejected.
• store.transaction() batches multiple updates into one notification.
• createRequestStoreFactory() creates request-isolated store instances.
• The persist option connects store state to a storage adapter. Pass a callback for write-only persistence, or use { load, save, version, migrate } when the store should hydrate and migrate saved state. Persisted envelopes are version-tagged so ordinary application values shaped like { state, version } remain ordinary state. To read a legacy untagged { state, version } record during migration, set the literal acceptLegacyPersistedState: true; this opt-in prevents domain state from being guessed as an envelope. When the choice comes from a runtime boolean, branch into separate current and legacy option objects so TypeScript can preserve the corresponding load contract.
• store.persistence.ready resolves after initial hydration, while store.persistence.status and store.persistence.error expose load, migrate, or later save failures without producing unhandled promise rejections. A local update made during hydration wins by default; choose hydrationConflict: "replace", "merge", or a resolver when persisted data should take precedence or be combined deliberately.
• Historical persistence can use a distinct schema type: createStore<CurrentState, PersistedState>() types migrate() with the saved shape, while validate() checks the loaded value and validateCurrent() checks the migrated current shape. A configured version mismatch without a migrator keeps the initial state and reports a load error.
• store.transaction() is synchronous. The type and runtime contract reject promises and thenables, roll back synchronous writes detected before notification, and require awaited work to finish before starting a later transaction.

Positioning

Use @reckona/mreact-query for server state, @reckona/mreact-forms for form state, and @reckona/mreact-store for application-wide UI or domain state.