npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

nexus-state

v1.6.5

Published

Global state manager✨

Downloads

1,267

Readme

nexus-state ✨

Table of contents

About

A lightweight and flexible state management library for React applications with TypeScript support. With nexus-state, you can easily build complex state structures. While the library works with JavaScript, using TypeScript unlocks the full potential of type inference and autocompletion.

Installation

Install the library using the following command:

npm install nexus-state

InitialStates

Create a file, such as nexusConfig, where you define initialStates:

export const initialStates = {
  strength: 10,
  secretPower: 5,
  // other states...
};

🛠 Configuring TypeScript for nexus-state

For TypeScript, extend the global StatesT interface provided by the library. The simplest way is to use typeof:

type InitialStatesT = typeof initialStates;

declare global {
  interface StatesT extends InitialStatesT {}
}

The nexus-state library comes with the default type _NEXUS_ in StatesT. For more information, see the nexusUpdate section.

🔮 Make sure to configure tsconfig properly.


NexusProvider

Wrap your application with NexusProvider, passing in initialStates:

import { NexusProvider } from "nexus-state";
import { initialStates } from "./nexusConfig";

const App = () => (
  <NexusProvider initialStates={initialStates}>
    <YourComponent />
  </NexusProvider>
);

useNexus

To access a state value, use the useNexus hook:

import { useNexus } from "nexus-state";

const YourComponent = () => {
  const strength = useNexus("strength");

  return <p>`🧙‍♂️ Your strength is ${strength}`</p>;
};

🔮 If you call useNexus empty then you will get all your states. This can be useful for debugging.


useNexusSelect

If you need to calculate derived data from the state, use the useNexusSelect hook:

import { useNexusSelect } from "nexus-state";

const YourComponent = () => {
  const fullPower = useNexusSelect(
    (state) => state.strength + state.secretPower
  );

  return <p>`🧙‍♂️ Your full power is ${fullPower}`</p>;
};

nexusUpdate

To update the state, use the nexusUpdate function. You can transmit values directly:

const levelUp = () => {
  nexusUpdate({
    strength: 15,
  });
};

Or get the previous value and work with it:

const levelUp = () => {
  nexusUpdate({
    strength: (prevState) => prevState + 5,
  });
};

You can also pass as many values as you want, you are limited only by the number of states you have created:

import { nexusUpdate } from "nexus-state";

const levelUp = () => {
  nexusUpdate({
    strength: (prevState) => prevState + 5,
    secretPower: (prevState) => prevState + 1,
  });
};

const YourButton = () => {
  return <button onClick={levelUp}>`🧙‍♂️ Raise the level`</button>;
};

For use in nexusUpdate, it supplies one default type _NEXUS_ to StatesT. It is used to update all user states. This can help you update all the states at one time they are stored remotely:

nexusUpdate({
  _NEXUS_: fetchedData,
});

🎉 Hurray! You already have everything you need to start working with global states. Next are the additional features of nexus-state.


nexusTrigger

Since there are many disadvantages of storing functions in states and the practical impossibility of their further use, nexus-state provides the possibility of creating a storage center for user functions and further calling them via nexusTrigger. To get started with the nexusTrigger, you need to:

1. Define initialFuncs in your config:

export const initialFuncs = {
  playerActions: {
    fData: (payload) => {
      console.log("Current player action:", payload);
    },
  },
  // over funcs
};

For TypeScript, extend the global FuncsT interface in the same way as StatesT:

type InitialStatesT = typeof initialStates;
type InitialFuncsT = typeof initialFuncs;

declare global {
  interface StatesT extends InitialStatesT {}
  interface FuncsT extends InitialFuncsT {}
}

2. Transfer the initialFuncs to the NexusProvider

Wrap your application with NexusProvider, passing in initialStates:

import { NexusProvider } from "nexus-state;
import { initialStates, initialFuncs } from "./nexusConfig";

const App = () => (
  <NexusProvider initialStates={initialStates} initialFuncs={initialFuncs}>
    <YourComponent />
  </NexusProvider>
);

3. Use nexusTrigger

import { nexusTrigger } from "nexus-state";

const actionDefiner = () => {
  nexusTrigger({
    type: "playerActions",
    payload: "The hero waves his sword!",
  });
};

const YourButton = () => {
  return <button onClick={actionDefiner}>`🧙‍♂️ What does the hero do?`</button>;
};

So you can use nexusTrigger, but its true power is shown in using it together with nexusUpdate, as it is also a simple function. This way you can think through complex user logic:

import { nexusUpdate } from "nexus-state";

const powerUp = {
  fData: ({ param, data }) => {
    switch (param) {
      case "strength": {
        nexusUpdate({
          strength: (prevState) => prevState + data,
        });
        return;
      }

      case "secretPower": {
        nexusUpdate({
          secretPower: (prevState) => prevState + data,
        });
        return;
      }

      default:
        return;
    }
  },
};

export const initialFuncs = {
  powerUp,
  // over funcs
};

In this example, we have created a function with a switch case design and the ability to change the desired state. Usage example:

import { nexusTrigger } from "nexus-state";

const powerUpCall = () => {
  nexusTrigger({
    type: "powerUp",
    payload: {
      param: "strength",
      data: 5,
    },
  });
};

const YourButton = () => {
  return (
    <button onClick={powerUpCall}>`🧙‍♂️ Increase the desired parameter`</button>
  );
};

Problems

No-empty-object-type error:

If you use eslint, you might encounter an error about empty object types (@typescript-eslint/no-empty-object-type), but this is easy to fix:

1. Add a rule to eslint:

rules: {
  "@typescript-eslint/no-empty-object-type": "off",
}

2. Define all states manually if there are only a few:

declare global {
  interface StatesT {
    strength: number;
    secretPower: number;
  }
}

3. Simply ignore the warning. 🙌


Motivation

This library came about by chance. I hadn't planned on using a state manager and simply updated states based on a flux-like architecture. Over time, I wanted to isolate state management into a separate component, which led to the creation of this library.

The name "Nexus" was inspired by the game Demon's Souls, where the "Nexus" serves as a safe haven for the player and a starting point. Similarly, with nexus-state, I wanted users to feel connected to a place like the "Nexus" or a bonfire from Dark Souls, where they can start their journey to anywhere. 🔥🗡️

I hope using nexus-state makes your development enjoyable and productive! ✨


API

  • NexusProvider: Provider Component to wrap your application.
  • useNexus: Hook for accessing a state by key.
  • useNexusSelect: Hook for computed or derived state values.
  • nexusUpdate: Function to update your states.
  • nexusTrigger: Function to dispatch actions.