grams v2.0.0

grams

Granular ReActive Management of State

Description

A robust, granular, and well defined state management compatible with SOLID principles. A state manager that is reliable and consistent.

Define state once and utilize it throughout the app without much boilerplate.

Benefits:

• Atomic state
• Compatible with async actions
• Middleware compatibility
• Protected state
• Effect handling
• Structural state management

Supported Frameworks

• React (>=16.8.0)
• React Native (>=0.59)

To install:

yarn add grams

or

npm install grams

or

pnpm install grams

or

bun install grams

Definitions

Gram

State Types

Effects

Internal Functions

Specifications

useStore

useStore() => [state, setState]

A hook that subscribes the component to the state, and returns the value of the state as well as its setter function. (Works similar to useState found in React hooks).

useStoreValue

useStoreValue() => state

A hook that subscribes the component to the state and only returns its value.

useSetStore

useSetStore() => setState

A hook that returns its setter function. It does not subscribe the component to the state.

useStoreProduce

useStoreProduce(produceName: string) => state

A hook that accepts the name of the produce, subscribes the component to the produce (subset) of the state, and returns its mutated value.

useStoreAction

useStoreAction(actionName: string) => setState

A hook that accepts the name of the action, and returns its action function. It does not subscribe the component to the state.

internal

{
    subscribe: (listener) => () => void;
    getState: () => state;
    setState: (newValue | ((prev) => newValue)) => void;
    getStateProduce: (key: string) => value;
    action: (key: string) => (newValue) => void;
}

State internal actions that can be used to manipulate the state without the need of hooks. These can be used to create custom hooks or actions or to run in instances where hooks cannot be used (i.e. query (fetch) functions, side effects etc).

Usage

1. Define the State

...

import { gram } from "grams";

...

const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

...

export const isAuthenticated = gram({
  defaultValue: false,
  type: "boolean",
  stateType: "stateful",
  produce: {
    isUnAuthenticated: (currValue) => !currValue,
  },
  actions: {
    login: () => true,
    logout: () => false,
  },
  effects: {
    onMount: async () => {
      isLoading.internal.setState(true);
      await delay(1000);
      isLoading.internal.setState(false);
      return true;
    },
  },
  middleware: {
    check: () => {
      console.log("auth middleware");
      return true;
    },
  },
});

2. Subscribe to the State or use the Actions

...

import { isAuthenticated } from "./store";

...

const ActionComponent = () => {
  const action = isAuthenticated.useStoreAction("logout");

  return <button onClick={action}>
    Logout
  </button>;
};

...

const ProduceComponent = () => {
  const isUnAuthenticated = isAuthenticated.useStoreProduce("isUnAuthenticated");

  return (
    <h1>Is Unauthenticated: {String(isUnAuthenticated)}</h1>
  );
};

...

const ValueComponent = () => {
  const isAuth = isAuthenticated.useStoreValue();

  return (
    <h1>Is Authenticated: {String(isAuth)}</h1>
  );
};

...

const Component = () => {
  const [isAuth, setIsAuth] = isAuthenticated.useStore();

  return (
    <div>
      <h1>Is Authenticated: {String(isAuth)}</h1>
      <button
        onClick={() => setIsAuth(true)}
      >
        Login
      </button>
    </div>
  );
};

Caveats

• Poor management, could lead to infinite state cycles - example listed below.

  const isAuthenticated = gram({
    defaultValue: false,
    type: "boolean",
    stateType: "stateful",
    ...
    effects: {
      ...
      onUpdate: async () => {
        isAuthenticated.internal.setState(true);
      }
    },
    ...
  });