Table of contents

• About
• Installation
• Configuration
• API
  • main
  • nexus
• License

About

Lightweight, framework-agnostic state management with optional actions and React bindings. Designed for simplicity and performance with TypeScript support.

Installation

npm install nexus-state

Configuration

The library provides two separate builds:

• **Modern bundlers*use the **ESM*(import) build
• **Node.js*use the **CommonJS*(require) build

Import the entire API via the default export or as individual named imports:

import NXS from "nexus-state";
// or
import { createNexus, createReactNexus, createActs } from "nexus-state";

API

main:

import { createNexus } from "nexus-state";

const nexus = createNexus({
  state: {
    count1: 0,
    count2: 0,
  },

  acts: (get, set) => ({
    increment() {
      set((state) => ({ count1: state.count1 + 1 }));
      this.getState("count1"); // ! calling another action
    },
    getState(value) {
      console.log(`${value}:`, get(value));
    },
  }),
});

export default nexus;

type MyStateT = {
  count1: number;
  count2: number;
};

type MyActionsT = {
  increment: () => void;
  consoleCalling: (text: string) => void;
};

const nexus = createNexus<MyStateT, MyActionsT>({...});

import { createReactNexus } from "nexus-state";

const nexus = createReactNexus({
  state: {
    count1: 0,
    count2: 0,
  },

  acts: (get, set) => ({
    increment() {
      set((state) => ({ count1: state.count1 + 1 }));
      this.getState("count1"); // ! calling another action
    },
    getState(value) {
      console.log(`${value}:`, get(value));
    },
  }),
});

export default nexus;

type MyStateT = {
  count1: number;
  count2: number;
};

type MyActionsT = {
  increment: () => void;
  consoleCalling: (text: string) => void;
};

const nexus = createReactNexus<MyStateT, MyActionsT>({...});

import { ✦create, createActs } from "nexus-state";

const customActions = createActs((get, set) => ({
  increment() {
    set((state) => ({ count1: state.count1 + 1 }));
    this.getState("count1"); // ! calling another action
  },
  getState(value) {
    console.log(`${value}:`, get(value));
  },
}));

// Usage:
const nexus = ✦create({
  state: {...},
  acts: customActions, // ! supports multiple: [myActions, myAnotherActions]
});

export default nexus;

// ✦create - createNexus or createReactNexus

type MyStateT = {...};
type MyActionsT = {...};

const customActions = createActs<MyStateT, MyActionsT>(...);

// ✦ Note:
// use optional chaining (?) when calling other actions via "this"
const incrementAction = createActs<MyStateT, MyActionsT>(() => ({
  increment() {
    this.getState?.("count1"); // ?.
  },
}));

import { ✦create } from "nexus-state";

const nexus1 = ✦create({...});
const nexus2 = ✦create({...});

// ✦create - createNexus or createReactNexus

nexus:

import nexus from "your-nexus-config";

const entireState = nexus.get();
const specificValue = nexus.get("key");

import nexus from "your-nexus-config";

// Direct update:
nexus.set({ count1: 5 });
nexus.set({ count1: 5, count2: 10 }); // multiple

// Functional update:
nexus.set((state) => ({
  count1: state.count1 + 1,
}));

// With context for `middleware`
set({ key: newValue }, { source: "server", meta: { ... } });

// Shortcut equivalent to { source: "server" }
set({ key: newValue }, "server");

import nexus from "your-nexus-config";

nexus.reset(); // reset entire state
nexus.reset("count1", "count2");

import nexus from "your-nexus-config";

const unsubscribe = nexus.subscribe(
  // observer:
  (state) => {
    console.log("count1 changed:", state.count1);
  },
  // dependencies:
  ["count1"]
);

// Unsubscribe
unsubscribe();

import nexus from "your-nexus-config";

nexus.middleware((prev, next, context) => {
  if (context.source === "storage") {
    console.log("Loaded from storage:", next);
  }
  // You can return a modified state or perform side effects
  return next;
});

import nexus from "your-nexus-config";

// Setup Redux DevTools connection
const devtools = window.__REDUX_DEVTOOLS_EXTENSION__?.connect({
  name: "MyStore",
});

devtools?.init(nexus.get());

// Register middleware to send state updates to DevTools
nexus.middleware((_, next) => {
  devtools?.send?.({ type: "UPDATE" }, next);
});

interface ReduxDevToolsConnection {
  send: (action: unknown, state: unknown) => void;
  init: (state: unknown) => void;
}

interface ReduxDevToolsExtension {
  connect(options: { name: string }): ReduxDevToolsConnection;
}

declare global {
  interface Window {
    __REDUX_DEVTOOLS_EXTENSION__?: ReduxDevToolsExtension;
  }
}

Description: object containing custom actions. Usage Example:

import nexus from "your-nexus-config";

nexus.acts.increment();
nexus.acts.consoleCalling("Some text");

// regular function
increment() {
  this.consoleCalling("Increment called"); // working
}

// arrow function
increment: () => this.consoleCalling("Increment called") // not working
// but syntax is compacter

More info: Arrow Functions

import nexus from "your-nexus-config";

const entireState = nexus.use();
const specificValue = nexus.use("key");

✦ Note: Unlike get, *usetriggers a re-render when the state changes.

import nexus from "your-nexus-config";

const total = nexus.useSelector(
  // observer:
  (state) => state.count1 + state.count2,
  // dependencies:
  ["count1", "count2"]
);

import { useCallback } from "react";
import nexus from "your-nexus-config";

const total = nexus.useSelector(
  useCallback((state) => state.count1 + state.count2, []),
  ["count1", "count2"]
);

import nexus from "your-nexus-config";

const updater = nexus.useRerender();
updater(); // force re-render

License

MIT