gemel v1.3.3

gemel :deciduous_tree::evergreen_tree::deciduous_tree:

React state management solution for creating global/local stores which can easily (and dynamically) extend eachother. Stores can resemble hierarchies/trees, with different instances tied to varying levels of the React tree, all of which can dynamically build upon eachother. Its API for creating stores is similar-to and inspired-by zustand.

Primary benefits include the ability to create local stores which act similarly to React context (they are localized and can be synchronously tied to component state through a specialized Provider.Sync component or a useSync hook).

These 'contexts' are configured externally, outside of the React tree; however, you can still 'access' a local store inside of another. If this is somewhat confusing, here's an example:

import { local } from "gemel";

const Base = local<{ val: string }>({ val: "" });

const Extended = local<{
  ext: string;
}>(({ join }) => ({
  ext: join(Base)((base) => base.get().val + "-ext"),
  // 'join' will proxy the result of the callback's get() method, and dynamically re-apply state if it's immediately accessed upon initialization.
  //  So 'ext' will be dynamically re-applied, but only when the 'Base' store's 'val' changes.
  //  If you want to avoid this and only apply state extensions on initialization, use 'join.init'.
}));

const useExtendedVal = () => Extended.useStore((s) => s.ext);

const Tree = () => {
  return (
    <>
      <Base.Provider.Sync val="one">
        <Extended.Provider>
          {/* useExtendedVal() === 'one-ext' */}
        </Extended.Provider>
      </Base.Provider.Sync>
      <Base.Provider.Sync val="two">
        <Extended.Provider>
          {/* useExtendedVal() === 'two-ext' */}
        </Extended.Provider>
      </Base.Provider.Sync>
      <Base.Provider.Sync val="three">
        <Base.Provider.Sync val="sub-three">
          <Extended.Provider>
            {/* useExtendedVal() === 'sub-three-ext' <- gemel will automatically extend from the 'closest' instance of the 'Base' store */}
          </Extended.Provider>
        </Base.Provider.Sync>
      </Base.Provider.Sync>
    </>
  );
};

I primarily built this for personal use in my own projects, but might add proper documentation sometime soon. If you want to use gemel, there are currently exports for creating local, global & mixed stores alongside some annotations you might find helpful. Or, you can reach out to me via github with questions. :grin: :thumbsup:

A gemel is a pair of trees which have naturally fused together to form a singular tree. (namesake)