neutrix

Appearance

API Reference ​

Store Creation Functions ​

1. createNeutrixStore (Recommended) ​

typescript
unction createNeutrixStore<T extends State>(
  initialState: T,
  options?: StoreOptions & { provider?: boolean }
):
  | StoreHook<T>          // if provider=false or omitted
  | { store: Store<T>, useStore: Function, Provider: React.FC } // if provider=true

Parameters: ​

  • initialState: Initial state object
  • options: Store configuration (see StoreOptions below)

Behavior: ​

  • If provider is omitted or false, returns a hook-based store (Zustand-like).
  • If provider: true, returns an object with { store, useStore, Provider }.
typescript
// Hook store (simpler)
const useStore = createNeutrixStore({ count: 0 });

// Provider store
const { store, useStore, Provider } = createNeutrixStore({ count: 0 }, { provider: true });

2. createCoreStore (Advanced) ​

typescript
function createCoreStore<T extends State>(
  initialState: T,
  options?: StoreOptions
): Store<T>

Description: ​

  • Low-level store creation with no React hooks.
  • Typically used for SSR or highly customized setups.

StoreOptions ​

typescript
interface StoreOptions {
  name?: string;        // For DevTools/persistence
  devTools?: boolean;   // Enable Redux DevTools
  persist?: boolean | ((state: any) => any); // localStorage persist
  validate?: (state: State) => boolean | string; // validation
  migration?: {
    version: number;
    migrate: (oldState: any) => any;
  };
  concurrency?: boolean; // match final code in createCoreStore
  onDestroy?: () => void;
}

Store Interface ​

get ​

get<K extends keyof T>(path: K | string): T[K]

Gets a value from the store using a path string.

Example:

typescript
const userName = store.get('user.profile.name')

set ​

typescript
set<K extends keyof T>(path: K | string, value: any): void

Sets a value in the store at the given path.

Example:

typescript
store.set('user.profile.name', 'John')

batch ​

typescript
batch(updates: [string, any][]): void

Performs multiple updates atomically.

Example:

typescript
store.batch([
  ['user.name', 'John'],
  ['user.lastLogin', Date.now()]
])

setState ​

typescript
setState<K extends keyof T>(path: K, value: T[K]): void

Shortcut for .set.

replaceState ​

typescript
replaceState(state: T): void

Replace the entire store state at once.

getState ​

typescript
getState(): T

Return the entire current state as a new object copy.

Advanced Features ​

computed ​

typescript
computed<R>(path: string, fn: (state: T) => R): ComputedFn<R>

Creates a computed value that updates when dependencies change.

action ​

typescript
action<Args extends any[], Result>(
  fn: Action<Args, Result>
): (...args: Args) => Promise<Result>

Defines an async operation that can update state. Returns a function that executes your async logic with the store.

suspend ​

typescript
suspend<R>(promise: Promise<R>): R

Used for integrating with React Suspense. Throws a promise if data not yet resolved.

subscribe ​

typescript
subscribe(subscriber: () => void): () => void

Subscribes to store changes. Returns an unsubscribe function.

React Hooks ​

useNeutrixSelector ​

typescript
function useNeutrixSelector<S extends State, R>(
  selector: (store: Store<S>) => R
): R

Select and subscribe to part of the store using a function.

useNeutrixComputed ​

typescript
function useNeutrixComputed<S extends State, R>(
  computeFn: (store: Store<S>) => R
): R

Compute derived values that automatically update when dependencies change.

useNeutrixAction ​

typescript
function useNeutrixAction<S extends State, Args extends any[], R>(
  action: (store: Store<S>, ...args: Args) => Promise<R>
): {
  loading: boolean;
  error: Error | null;
  execute: (...args: Args) => Promise<R>;
}

Wraps async store actions to track loading and error states.

Store Connections ​

connectStores ​

typescript
function connectStores<S extends State, T extends State>(
  connections: StoreConnection<S, T>[]
): () => void

Connects multiple stores together, allowing them to react to each other's changes.

StoreConnection Interface ​

typescript
interface StoreConnection<S extends State = State, T extends State = State> {
  source: Store<S>;
  target: Store<T>;
  when: (source: Store<S>) => boolean;
  then: (target: Store<T>) => void;
  immediate?: boolean;
}

Core Types ​

typescript
type State = Record<string, any>;

interface Middleware {
  onSet?: (path: string, value: any, prevValue: any) => any;
  onGet?: (path: string, value: any) => any;
  onBatch?: (updates: [string, any][]) => [string, any][];
  onError?: (error: Error) => void;
}