Frequently Asked Questions

General

What is SoulState?

SoulState is a fine-grained reactive state management library for React. It provides a Zustand-compatible API with built-in computed values, glitch-free updates, and surgical reactivity that scales to 100K+ subscribers.

How does SoulState differ from Zustand?

Feature	Zustand	SoulState
Updates	Global broadcast (O(N))	Surgical (O(M))
Computed	External library	Built-in
Glitch-free	Not guaranteed	Guaranteed
Scalability	Good	Excellent (100K+)

When should I use SoulState?

Use SoulState when you need:

• Fine-grained reactivity with many subscribers
• Built-in computed/derived state
• Glitch-free updates
• High-performance at scale
• Zustand-compatible API

Is SoulState production-ready?

Yes. SoulState is used in production applications and has been battle-tested with:

• 100K+ subscribers
• Deep computed chains (50+ levels)
• High-churn subscription scenarios
• Concurrent updates

API

How do I create a store?

import { createStore } from 'soulstate';

// With initial state object
const store = createStore({
  count: 0,
  name: 'World'
});

// Or with creator function (Zustand-style)
const store = createStore((setState, getState) => ({
  count: 0,
  increment: () => setState((state) => ({ count: state.count + 1 })),
}));

How do I subscribe to state changes?

const unsubscribe = store.subscribe(
  (state) => state.count,
  (count, prevCount) => {
    console.log('Count changed from', prevCount, 'to', count);
  }
);

// Cleanup
unsubscribe();

How do I create computed values?

const doubleCount = store.computed((state) => state.count * 2);

// Access computed value
console.log(doubleCount.value); // 2

// Destroy when no longer needed
// doubleCount.destroy();

How do I use transactions?

// Batch multiple updates atomically
store.beginTransaction();
store.setState({ count: 1 });
store.setState({ name: 'updated' });
store.commitTransaction();

// With rollback on error
store.beginTransaction();
store.setState({ count: 1 });
store.setState({ name: 'updated' });
if (error) {
  store.rollbackTransaction();
} else {
  store.commitTransaction();
}

Performance

How does SoulState achieve high performance?

1. Surgical Updates: Only affected subscribers are notified
2. Proxy-Based Tracking: Reusable proxy-based dependency detection
3. Bitmask Fast Paths: O(1) key lookup for small state objects
4. Microtask Batching: Automatic update batching
5. Equality Fast-Path: Skips propagation when values don't change

How many subscribers can SoulState handle?

SoulState scales to 100K+ subscribers with stable performance. Benchmark results show:

• 10K subscribers: ~50ms propagation
• 100K subscribers: ~500ms propagation
• 100K irrelevant updates: 914x faster than Zustand

Does SoulState support server-side rendering?

Yes. SoulState works with SSR frameworks like Next.js. The store can be serialized and hydrated on the client.

Is SoulState tree-shakeable?

Yes. SoulState uses ES modules and has sideEffects: false in package.json, enabling effective tree-shaking.

React Integration

How do I use SoulState with React?

import { createStore } from 'soulstate';
import { useStore } from 'soulstate/react';

const store = createStore({
  count: 0
});

// Define actions separately
const actions = {
  increment: () => store.setState(s => ({ count: s.count + 1 })),
};

function Counter() {
  const count = useStore(store, (state) => state.count);
  return (
    <button onClick={actions.increment}>
      {count}
    </button>
  );
}

How do I prevent unnecessary re-renders?

Use the shallow equality function for object selections:

import { shallow } from 'soulstate/utils';

const { a, b } = useStore(
  store,
  (state) => ({ a: state.a, b: state.b }),
  shallow
);

How do I use SoulState with Next.js?

SoulState works with Next.js out of the box:

// pages/_app.tsx
import { createStore } from 'soulstate';
import { Provider } from 'soulstate/react';

const store = createStore({
  count: 0,
});

export default function App({ Component, pageProps }) {
  return (
    <Provider store={store}>
      <Component {...pageProps} />
    </Provider>
  );
}

Middleware

Does SoulState support Redux DevTools?

Yes. Use the devtools middleware:

import { createStore } from 'soulstate';
import { middleware } from 'soulstate';
const { devtools } = middleware;

const store = createStore(
  devtools({ name: 'My Store' })((set) => ({
    count: 0,
  }))
);

Does SoulState support persistence?

Yes. Use the persist middleware:

import { createStore } from 'soulstate';
import { middleware } from 'soulstate';
const { persist } = middleware;

const store = createStore(
  persist({ key: 'my-store', storage: localStorage })((set) => ({
    count: 0,
  }))
);

Can I create custom middleware?

Yes. Middleware is a function that wraps the store:

function loggerMiddleware(config) {
  return (set, get, store) => {
    const loggedSet = (...args) => {
      console.log('Setting state:', args);
      set(...args);
    };
    return config(loggedSet, get, store);
  };
}

TypeScript

Does SoulState support TypeScript?

Yes. SoulState is written in TypeScript and provides full type inference:

const store = createStore({
  count: 0,
  name: 'World',
});

// TypeScript knows the type of count
const count = useStore(store, (state) => state.count); // number

How do I type my store?

Define explicit types for your state and actions:

interface MyState {
  count: number;
  name: string;
}

const store = createStore<MyState>({
  count: 0,
  name: 'World',
});

Migration

How do I migrate from Zustand?

See the Migration Guide for detailed instructions.

How do I migrate from Redux?

See the Migration Guide for detailed instructions.

Community

Where can I get help?

• Documentation
• GitHub Issues
• Discussions

How do I contribute?

See CONTRIBUTING.md.

Is SoulState actively maintained?

Yes. SoulState is actively maintained with regular updates and bug fixes.