repository·main·Indexed 43 days ago
https://github.com/saasquatch/bunshiA tiny, fast, and dependency-free dependency injection and state management library (v2.2.0). It allows developers to create state stores and manage dependencies by lifting state up or pushing state down across React, Vue, and vanilla JS environments. It integrates with state management solutions such as jotai, valtio, zustand, nanostores, and vue reactive.
Bunshi is a lightweight (3kb), dependency-free library designed for creating state stores and managing dependencies. It enables developers to lift state up or push state down across different environments.
Bunshi is framework-agnostic and works with:
It is designed to integrate seamlessly with existing state management solutions, including:
Bunshi (formerly jotai-molecules) is a tiny (1.18kb minified/gzipped), dependency-free library designed for creating state stores and managing dependencies. It acts as a general-purpose dependency injection tool that allows you to 'lift state up' or 'push state down'.
It is compatible with various state management libraries, including:
Key technical characteristics:
WeakMap to prevent memory leaks.When using Bunshi with Vue, you can follow these best practices to maintain a clean architecture:
ref, reactive) for the actual state storage..vue components.Bunshi supports a parent-child injector hierarchy. Child injectors inherit all bindings from their parent, but can also define their own bindings or override existing parent bindings.
const parentInjector = createInjector({
bindings: [[ApiClientInterface, ProductionApiClientMolecule]]
});
const childInjector = createInjector({
parent: parentInjector,
bindings: [[CacheInterface, MemoryCacheMolecule]]
});
// childInjector can resolve both ApiClientInterface (from parent) and CacheInterface (local)const parentInjector = createInjector({
bindings: [[ApiClientInterface, ProductionApiClientMolecule]]
});
const childInjector = createInjector({
parent: parentInjector,
bindings: [[CacheInterface, MemoryCacheMolecule]]
});By default, molecules are shared globally. To provide a unique instance of a molecule for every component instance, use the use(ComponentScope) pattern inside the molecule definition. This allows you to push or pull state without changing the component's implementation.
import { ComponentScope, molecule, use } from "bunshi";
import { atom } from "jotai/vanilla";
export const CountMolecule = molecule(() => {
// Because scope is used here, this molecule is component scoped
use(ComponentScope);
return atom(0);
});Molecules are the core abstraction in Bunshi. They are functions that return a value. When a molecule is used, the returned value is memoized and cached, allowing it to be shared across your application.
import { molecule } from "bunshi";
import { atom } from "jotai/vanilla";
export const CountMolecule = molecule(() => atom(0));.vue imports, use vue-tsc instead of the standard tsc CLI for type checking in your projects.Using Bunshi alongside Zag provides several architectural advantages:
Bunshi enables you to use Jotai atoms for both local component state and global application state within the same logic. This allows you to create derived values that depend on both scopes simultaneously—a pattern that is difficult to achieve with standard Jotai Provider or useStore implementations alone.
In a typical Bunshi setup:
// Example concept: A multiplier combining global and local state
// molecules.ts
import { atom } from 'jotai';
// Global atom
export const globalMultiplierAtom = atom(2);
// Local atom (scoped via Bunshi)
export const localCountAtom = atom(0);
// Derived atom combining both
export const combinedAtom = atom((get) => {
const multiplier = get(globalMultiplierAtom);
const count = get(localCountAtom);
return count * multiplier;
});Scopes are ideal for managing state that should survive for the lifecycle of a specific component, such as a form. By creating a scope for every form and making molecules depend on that scope, a new instance of the molecules is created for each unique scope instance.
createScope to define the scope.molecule definition, call scope(yourScope) to make the molecule scoped. This ensures the state (e.g., a nanostore or Jotai atom) is unique to that scope.provideScope at the top level of your form component tree.useMolecule in child components to access the scoped state.import { createScope } from "bunshi";
// 1. Create scope
export const formScope = createScope<unknown>(undefined);
import { molecule } from "bunshi";
import { atom } from "nanostores";
// 2. Depend on scope in a molecule
export const FormErrors = molecule((mol, scope) => {
// Calling `scope` makes `FormErrors` a *scoped* molecule
scope(formScope);
const errors = atom<string[]>([]);
function addError(error: string) {
errors.set([...errors.get(), error]);
}
return {
addError,
errors,
};
});Molecules are the core building blocks of Bunshi. They are functions that return a value. When a molecule is used, its value is memoized and cached, meaning it will always return the same value for subsequent calls within the same context.
Key characteristics:
import { molecule } from "bunshi";
export const RandomMolecule = molecule(() => Math.random());While Nanostores can be used with simple global variables for state that is always global and never lazy, Bunshi provides several advantages for managing Nanostores: