# useS: React Hook for State Management

## About use-s-react

name = use-s-react
description = "React hook for simple, scalable and powerful local and global state management"
version = "2.x"
npm: https://www.npmjs.com/package/use-s-react
github: https://github.com/ChristBM/use-s
docs: https://use-s-react.christbm.dev/docs

## API

Docs: https://use-s-react.christbm.dev/docs/api

Hook: "useS" for local and global state management
Function: "debugGlobalStore" to inspect in the console what is in the global status

useS(initialValue: T): Local State
useS({ value: T; key: string; persist?: boolean; }): Global State (share the value between components using the same key).
debugGlobalStore(options?):

### Optional Configuration

useS(initialValue: T || { value: T; key: string; persist?: boolean; },
  {
    mutableIn?: boolean;
    mutableOut?: boolean;
    forceUpdate?: boolean;
  }
)

- persist: defaults to false. Allows you to save the state in local Storage for that key and read it initially. Ensures the persistence of information in the browser.
- mutableIn: defaults to false. This ensures immutability on input.
- mutableOut: defaults to false. This ensures immutability on output.
- forceUpdate: defaults to false. This means that inside setState, useS validates the new value, and if it’s an object, it treats it as a partial of the previous value and merges it accordingly.

## Usage

Docs: https://use-s-react.christbm.dev/docs/getting-started

- Installation: npm i use-s-react
- Import: import { useS } from "use-s-react";

### Using Local State

export default function LocalCounter() {
  const [count, setCount] = useS(0);

  return (
    <button onClick={() => setCount((prev) => prev + 1)}>
      You clicked {count} times
    </button>
  );
}

### Using Global State

export default function GlobalCounter() {
  const [count, setCount] = useS({ value: 0, key: "global-counter" });

  return (
    <button onClick={() => setCount((prev) => prev + 1)}>
      You clicked {count} times
    </button>
  );
}

## Debug (Development Mode)

Docs: https://use-s-react.christbm.dev/docs/debug

Import: import { debugGlobalStore } from "use-s-react";
Inspect all global states: debugGlobalStore();
Inspect a specific key: debugGlobalStore({ filterKey: "a-key" });
Enable `console.log` formatting: debugGlobalStore({ consoleLog: true });

This is a handy tool for development and debugging. For production apps, avoid calling `debugGlobalStore()` unless explicitly needed.

## Derived state

Docs: https://use-s-react.christbm.dev/docs/derived-state

Deriving the state is the technique of calculating one state from another and the result is a state derived from another.

## Example of derived state

1- Import: import { useS } from "use-s-react";
2- InitialValue:
type CartType = {
  cart: number[];
  total: (cart: number[]) => number;
  thanks: (total: number) => string;
};

const initialValue: CartType = {
  cart: [1, 2, 3, 4],
  total: function (cart: number[]) {
    return cart.reduce((sum: number, item: number) => sum + item, 0);
  },
  thanks: function (total: number) {
    return `Thanks for your purchase of: ${total}`;
  },
};

3- Use in a component or hook:
export default function Component() {
  const [{ cart, total, thanks }, setState] = useS(initialValue);

  return (
    <div>
      <h1>Total: {total(cart)}</h1>
      <h3>{thanks(total(cart))}</h3>

      <ul>
        <p>cart:</p>
        {cart.map((i, index) => (
          <li key={i + index + "key"}>{i}</li>
        ))}
      </ul>

      <button
        onClick={() =>
          setState((prev) => ({ cart: [...prev.cart, prev.cart.length + 1] }))
        }
      >
        + 1 Price
      </button>
    </div>
  );
}

### How It Works

- `total` is a function that derives value from `cart`
- `thanks` is a function that uses the result of `total`
- React automatically re-renders when state changes, and the functions respond accordingly
- No unnecessary re-renderings

## Global Storage (Best Practice)

Docs: https://use-s-react.christbm.dev/docs/global-store

To stay organized, it’s best practice to centralize your global state config objects { value, key } in a store.ts file.

1- Create a store.ts file:

export type StoreType = {
  globalCounter: {
    value: number;
    key: string;
  };
};

export const store: StoreType = {
  globalCounter: {
    value: 0,
    key: "global-counter",
  },
} as const;

2- Import into your component or hook: import { store } from "./store";
3- Pass the value to useS: const [state, setState] = useS(store.globalCounter);

Any component using: useS(store.globalCounter) will now share the same state.