Oustate 🌀

Welcome to Oustate – your new best friend for managing state in React applications! Making state management a breeze, focused on simplicity and scalability for real-world scenarios.

🚀 Features

• Easy State Creation: Kickstart your state management with simple and intuitive APIs.
• Selectors & Merges: Grab exactly what you need from your state and combine multiple states seamlessly.
• Deep Nesting Support: Handle complex state structures without breaking a sweat.
• Optimized Rendering: Prevent unnecessary re-renders with smart equality checks.
• Concurrency Handling: Stay cool under pressure with robust concurrency support.
• TypeScript Ready: Fully typed for maximum developer sanity.

📦 Installation

bun add oustate
# or
yarn add oustate
# or
npm install oustate

📝 Quick Start

import { create } from 'oustate'

const useCounter = create(0)

function Counter() {
  const counter = useCounter()
  return <div onClick={() => useCounter.setState((prev) => prev + 1)}>{counter}</div>
}

Selecting parts of the state globally

import { create } from 'oustate'

const useUser = create({ name: 'John', age: 30 })

const useName = useUser.select((user) => user.name)
const useAge = useUser.select((user) => user.age)

function Counter() {
  const name = useName()
  return <div onClick={() => useUser.setState((prev) => ({ ...prev, name: 'Jane' }))}>{counter}</div>
}

Or lazy

import { create } from 'oustate';
// getter function, it'a lazy state initialization, loaded only when it's accessed
const useCounter = create(() => 0); 

function Counter() {
  const counter = useCounter();
  return (
    <div onClick={() => useCounter.setState((prev) => prev + 1)}>
      {counter}
    </div>
  );
}

Or merge two states

import { create } from 'oustate';
// getter function, it'a lazy state initialization, loaded only when it's accessed
const useName = create(() => 'John');
const useAge = create(() => 30);

const useUser = useName.merge(useAge, (name, age) => ({ name, age }));

function Counter() {
  const {name, age} = useUser();
  return (
    <div onClick={() => useName.setState((prev) => 'Jane')}>
      {counter}
    </div>
  );
}

Promise based state and lifecycle management working with React Suspense

This methods are useful for handling async data fetching and lazy loading via React Suspense.

Immediate Promise resolution

import { create } from 'oustate';
 // state will try to resolve the promise immediately, can hit the suspense boundary
const counterState = create(Promise.resolve(0));

function Counter() {
  const counter = counterState();
  return (
    <div onClick={() => counterState.setState((prev) => prev + 1)}>
      {counter}
    </div>
  );
}

Lazy Promise resolution

import { create } from 'oustate';
// state will lazy resolve the promise on first access, this will hit the suspense boundary if the first access is from component and via `counterState.getState()` method
const counterState = create(() => Promise.resolve(0)); 

function Counter() {
  const counter = counterState();
  return (
    <div onClick={() => counterState.setState((prev) => prev + 1)}>
      {counter}
    </div>
  );
}

🔍 API Reference

create

Creates a basic atom state.

function create<T>(defaultState: T, options?: StateOptions<T>): StateSetter<T>;

Example:

const userState = create({ name: 'John', age: 30 });

select

Selects a slice of an existing state directly or via a selector function.

// userState is ready to use as hook, so you can name it with `use` prefix
const userState = create({ name: 'John', age: 30 });
// Direct selection outside the component, is useful for accessing the slices of the state in multiple components
const userAgeState = userState.select((user) => user.age);

// Selection via selector in hook function
const userNameState = select(userState, (user) => user.name);

function select<T, S>(state: StateGetter<T>, selector: (value: T) => S, isEqual?: IsEqual<S>): StateGetter<S>;

Example:

const userAgeState = select(userState, (user) => user.age);

merge

Merges two states into a single state. But be careful about creating new references on each call, it can lead to maximum call stack exceeded error.

function merge<T1, T2, S>(
  state1: GetterState<T1>,
  state2: GetterState<T2>,
  selector: (value1: T1, value2: T2) => S,
  isEqual?: IsEqual<S>
): GetterState<S>

Access from outside the component

:warning: Avoid using this method for state management in React Server Components, especially in Next.js 13+. It may cause unexpected behavior or privacy concerns.

const userState = create({ name: 'John', age: 30 });
const user = userState.getState();

Slicing new references

:warning: Slicing data with new references can lead to maximum call stack exceeded error. It's recommended to not use new references for the state slices, if you need so, use shallow or other custom equality checks.

import { state, shallow } from 'oustate';
const userState = create({ name: 'John', age: 30 });
// this slice will create new reference object on each call
const useName = userState.select((user) => ({newUser: user.name }), shallow);

🤖 Contributing

Contributions are welcome! Please read the contributing guidelines before submitting a pull request.

🧪 Testing

Oustate comes with a robust testing suite. Check out the state.test.tsx for examples on how to write your own tests.

📜 License

Oustate is MIT licensed.