A tiny (~2 KB), zero-dependency, framework-independent, store based, reactive state library for JavaScript applications. It's very similar to redux in terms of functionality, but it's much simpler to work with immutable objects.
create function to create a store from a class.
run to run effects (similar to effect in signals).
memo to create a computed getter that lets you pass arguments to it and caches the computed result based on stores used in the function and also arguments passed to that function.
computed to create a signals like computed object with value property that has auto computed property. You can also save the store as a version so you can roll back to previous versions.
reset function to reset your stores. That's it.
It creates getters and setters for the store properties to track when they are read or written.
You have to assign new values to the properties in the class to detect the change. Library creates a getter and setter for each and every property in the class after creating an instance to track when they are read or written, so by setting the value through function or from outside, library will know that this value has changed. It treats your store values as immutable. so you will need to reacreate the references for the values at the root level when anything inside the object or array changes. values can be of any type.
import { create, memo, computed, run } from "immu-js";
// 1. Define state as a plain class
class Counter {
count = 0;
address = {
street: "test",
}
// setter functions
incr() { this.count++; }
decr() { this.count--; }
setStreet(street: string){
// need to reassign the object to trigger the change
this.address = { ...this.address, street };
}
// getter functions
getStreet(){
// you can use functions to get values from the store
return this.address.street;
}
}
// 2. Create a reactive store
const store = create(Counter);
// 3. Derive cached values with memo (recomputes only when store or args change)
const doubled = memo((n: number) => store.count * n);
doubled(2); // 0
store.incr();
doubled(2); // 2 (recomputed — store changed)
doubled(2); // 2 (cached — nothing changed)
// 4. Derive cached values with computed (no args, access via .value)
const label = computed(() => `Count is ${store.count}`);
label.value; // "Count is 1"
store.incr();
label.value; // "Count is 2" (recomputed)
label.value; // "Count is 2" (cached)
// 5. React to changes with run (auto-tracks which stores you read)
const dispose = run(() => {
console.log("count changed:", store.count);
});
// logs immediately: "count changed: 2"
store.incr(); // after microtask → logs: "count changed: 3"
dispose(); // stop reacting
// 6. Subscribe to specific property changes
const unsub = store._subscribe(() => console.log("count!", store.count), "count");
store.incr(); // after microtask → logs: "count! 4"
unsub();
// 7. Snapshot & restore state
store._saveVersion("checkpoint");
store.incr();
store.incr();
store.count; // 6
store._loadVersion("checkpoint");
store.count; // 4
// 8. Reset to initial values
store._reset();
store.count; // 0
npm install immu-js
ESM and CJS builds are both included:
import { create, memo, computed, run } from "immu-js"; // ESM
const { create, memo, computed, run } = require("immu-js"); // CJS
import { create, memo, run } from "immu-js";
class Counter {
count = 0;
incr() { this.count++; }
decr() { this.count--; }
}
const store = create(Counter);
// Reactive effect — runs immediately, then re-runs on change
const dispose = run(() => {
console.log("count:", store.count);
});
// logs: "count: 0"
store.incr();
// after microtask flush → logs: "count: 1"
// Memoized derived value
const doubled = memo((multiplier: number) => store.count * multiplier);
doubled(2); // 2 (computes)
doubled(2); // 2 (cached — same args, same store version)
store.incr();
doubled(2); // 4 (recomputes — store changed)
dispose(); // stop reacting
create(Class)Creates a reactive store from a class constructor. All data properties are converted to reactive getters/setters. Methods (both prototype and arrow functions) remain callable and operate on the reactive state.
import { create } from "immu-js";
class TodoStore {
todos: string[] = [];
filter = "all";
addTodo(text: string) {
this.todos = [...this.todos, text];
}
setFilter(f: string) {
this.filter = f;
}
}
const store = create(TodoStore);
store.addTodo("Buy milk");
store.todos; // ["Buy milk"]
Parameters:
| Param | Type | Description |
|---|---|---|
Class | new () => T | A class with a no-arg constructor |
Returns: Store<T> — the class instance augmented with _version, _subscribe, _reset, _saveVersion, and _loadVersion.
Store extras (
_version,_subscribe, etc.) are non-enumerable — they won't appear inObject.keys(),JSON.stringify(), orfor...inloops.
store._versionA read-only integer that increments on every property set. Useful for cache invalidation.
const store = create(Counter);
store._version; // 0
store.incr();
store._version; // 1
store.incr();
store._version; // 2
Each individual property assignment increments the version independently:
class Multi { a = 1; b = 2; }
const store = create(Multi);
store.a = 10; // _version → 1
store.b = 20; // _version → 2
_version is readonly — attempting to set it throws a TypeError.
store._subscribe(cb, prop?)Subscribe to store changes. Returns an unsubscribe function.
const store = create(Counter);
// Subscribe to ALL property changes
const unsub = store._subscribe(() => {
console.log("store changed, count is", store.count);
});
store.incr();
// after flush → "store changed, count is 1"
unsub(); // stop listening
Prop-specific subscriptions — pass a property name to only be notified when that specific property changes:
class Multi { a = 1; b = 2; }
const store = create(Multi);
store._subscribe(() => console.log("a changed!"), "a");
store._subscribe(() => console.log("b changed!"), "b");
store.a = 10; // after flush → "a changed!"
store.b = 20; // after flush → "b changed!"
// Changing `b` does NOT trigger the `a` subscriber, and vice versa.
Parameters:
| Param | Type | Description |
|---|---|---|
cb | () => void | Callback invoked on change |
prop | string (optional) | Only notify when this property changes |
Returns: () => void — call to unsubscribe.
Important: Notifications are asynchronous — they fire on the next microtask via
queueMicrotask, not synchronously on set. Multiple mutations in the same tick are batched into a single notification.
store._reset()Resets all data properties to their initial values by re-instantiating the class internally. Methods are not affected.
const store = create(Counter);
store.incr();
store.incr();
store.count; // 2
store._reset();
store.count; // 0
_version increments.class AddressStore {
address = { city: "Delhi", zip: "110001" };
changeCity(city: string) {
this.address = { ...this.address, city };
}
}
const store = create(AddressStore);
store.changeCity("Mumbai");
store._reset();
store.address.city; // "Delhi"
store._saveVersion(label?)Snapshots the current state. Uses structuredClone for deep copying — saved state is fully independent of the live store.
const store = create(Counter);
store.incr();
store.incr();
store._saveVersion(); // saves under label "default"
store._saveVersion("v1"); // saves under label "v1"
Parameters:
| Param | Type | Default | Description |
|---|---|---|---|
label | string | "default" | Label to identify this snapshot |
store._loadVersion(label?)Restores a previously saved snapshot. Goes through setters, so subscribers are notified and _version increments.
const store = create(Counter);
store.incr();
store.incr();
store._saveVersion(); // count = 2
store.incr();
store.incr();
store.count; // 4
store._loadVersion(); // restores "default"
store.count; // 2
Named versions:
store.incr();
store._saveVersion("v1"); // count = 1
store.incr();
store.incr();
store._saveVersion("v2"); // count = 3
store._loadVersion("v1");
store.count; // 1
store._loadVersion("v2");
store.count; // 3
Parameters:
| Param | Type | Default | Description |
|---|---|---|---|
label | string | "default" | Label of the snapshot to restore |
Throws: Error if no snapshot exists for the given label.
store._loadVersion("nonexistent");
// Error: No saved version found for label "nonexistent"
memo(fn)Creates a memoized function that automatically tracks which stores are accessed during execution. Returns a cached result when neither the arguments nor the tracked store versions have changed.
import { memo } from "immu-js";
const store = create(Counter);
const doubled = memo((multiplier: number) => store.count * multiplier);
doubled(2); // computes → 0
doubled(2); // cached → 0 (same args, same store version)
doubled(3); // computes → 0 (different args)
store.incr();
doubled(2); // recomputes → 2 (store changed)
doubled(2); // cached → 2
Parameters:
| Param | Type | Description |
|---|---|---|
fn | (...args: TArgs) => TReturn | Function to memoize |
Returns: (...args: TArgs) => TReturn — memoized version of fn.
How caching works:
JSON.stringify — if the serialized args string matches, args are considered equal._version is compared — if any store's version changed, the function recomputes.No-argument memo:
const total = memo(() => store.count * 10);
total(); // computes
total(); // cached
Multi-argument memo:
const fmt = memo((a: number, b: string) => `${store.count * a}-${b}`);
fmt(2, "x"); // "0-x"
Multiple stores:
const counter = create(Counter);
const users = create(UserStore);
const summary = memo(() => `${counter.count} users: ${users.users.join(", ")}`);
summary(); // "0 users: "
counter.incr();
summary(); // "1 users: "
users.addUser("Alice");
summary(); // "1 users: Alice"
computed(fn)Creates a lazily-evaluated, cached computed value. Similar to memo but with no arguments — access the result via .value.
import { computed } from "immu-js";
const store = create(Counter);
const doubled = computed(() => store.count * 2);
doubled.value; // 0 (computes)
doubled.value; // 0 (cached)
store.incr();
doubled.value; // 2 (recomputes)
doubled.value; // 2 (cached)
Parameters:
| Param | Type | Description |
|---|---|---|
fn | () => T | Pure function deriving a value from store state |
Returns: Computed<T> — an object with a reactive value getter.
interface Computed<T> {
readonly value: T;
}
Multiple stores:
const storeA = create(Counter);
const storeB = create(Multi);
const combined = computed(() => storeA.count + storeB.a + storeB.b);
combined.value; // 3 (0 + 1 + 2)
storeA.incr();
combined.value; // 4 (1 + 1 + 2)
run(cb, deps?)Runs a callback immediately, then re-runs it reactively whenever tracked stores change. Returns a dispose function to stop the effect.
import { run } from "immu-js";
const store = create(Counter);
const dispose = run(() => {
console.log("count:", store.count);
});
// immediately logs: "count: 0"
store.incr();
// after flush → "count: 1"
store.incr();
// after flush → "count: 2"
dispose(); // stops reacting
store.incr(); // nothing logged
Parameters:
| Param | Type | Description |
|---|---|---|
cb | () => void | Effect callback |
deps | () => unknown[] (optional) | Dependency function for fine-grained control |
Returns: () => void — call to dispose the effect.
Automatic store tracking:
run tracks which stores are accessed inside cb. It only re-runs when those specific stores change — unrelated stores are ignored.
const counter = create(Counter);
const users = create(UserStore);
run(() => {
console.log("count:", counter.count);
// only `counter` is tracked — changes to `users` won't trigger this
});
users.addUser("Alice"); // does NOT re-trigger the effect
counter.incr(); // re-triggers the effect
With deps for fine-grained control:
When deps is provided, the callback only re-runs if the deps array values change (shallow comparison). This lets you decouple "what triggers re-run" from "what the callback reads."
const store = create(Multi);
run(
() => {
console.log("a is", store.a);
},
() => [store.a] // only re-run when `a` changes
);
store.b = 99; // deps unchanged → callback does NOT re-run
store.a = 10; // deps changed → callback re-runs
Deps can track different stores than the callback:
const storeA = create(Counter);
const storeB = create(Counter);
run(
() => console.log("A:", storeA.count),
() => [storeB.count] // re-run is gated on storeB
);
storeB.incr(); // deps changed → callback re-runs
Batching:
Multiple synchronous mutations are batched — the effect fires only once per flush:
const store = create(Counter);
const values: number[] = [];
run(() => values.push(store.count));
// values: [0]
store.incr();
store.incr();
store.incr();
// after flush → values: [0, 3] (NOT [0, 1, 2, 3])
Each create() call produces an independent store. They can be used together in memo, computed, and run:
class AuthStore {
user: string | null = null;
login(name: string) { this.user = name; }
logout() { this.user = null; }
}
class CartStore {
items: string[] = [];
add(item: string) { this.items = [...this.items, item]; }
clear() { this.items = []; }
}
const auth = create(AuthStore);
const cart = create(CartStore);
const summary = memo(() => {
if (!auth.user) return "Not logged in";
return `${auth.user}'s cart: ${cart.items.join(", ") || "(empty)"}`;
});
summary(); // "Not logged in"
auth.login("Alice");
summary(); // "Alice's cart: (empty)"
cart.add("Book");
summary(); // "Alice's cart: Book"
memo and computed support nesting — inner dependencies bubble up to outer computations:
const store = create(Counter);
// Deeply nested chain
const level1 = memo(() => store.count * 2);
const level2 = memo(() => level1() + 10);
const level3 = memo(() => level2() + 100);
level3(); // 110 (0*2 + 10 + 100)
store.incr();
level3(); // 112 (1*2 + 10 + 100)
Mixing computed and memo:
const store = create(Counter);
const c1 = computed(() => store.count + 1);
const m1 = memo(() => c1.value * 2);
const c2 = computed(() => m1() + 100);
c2.value; // 102 → (0+1)*2 + 100
store.incr();
c2.value; // 104 → (1+1)*2 + 100
create walks the full prototype chain, picking up properties and methods from parent classes:
class Base {
baseCount = 0;
baseName = "base";
incrBase() { this.baseCount++; }
}
class Child extends Base {
childCount = 10;
incrChild() { this.childCount++; }
}
class GrandChild extends Child {
grandValue = "hello";
setGrand(val: string) { this.grandValue = val; }
}
const store = create(GrandChild);
store.baseCount; // 0
store.childCount; // 10
store.grandValue; // "hello"
store.incrBase();
store._version; // 1
// _reset restores ALL inherited properties
store._reset();
store.baseCount; // 0
// _saveVersion / _loadVersion includes inherited properties
store.incrBase();
store._saveVersion("snap");
store.incrBase();
store._loadVersion("snap");
store.baseCount; // 1
Always produce new references when updating objects or arrays — the setter only fires when you assign to the property:
class AddressStore {
address = { city: "Delhi", zip: "110001" };
changeCity(city: string) {
// ✅ Correct — creates a new object, triggers setter
this.address = { ...this.address, city };
}
}
class UserStore {
users: string[] = [];
addUser(user: string) {
// ✅ Correct — creates a new array, triggers setter
this.users = [...this.users, user];
}
}
Use _saveVersion and _loadVersion for undo/redo or checkpoint patterns:
const store = create(Counter);
store.incr(); // count = 1
store._saveVersion("step1");
store.incr(); // count = 2
store._saveVersion("step2");
store.incr(); // count = 3
store._saveVersion("step3");
// Undo to step1
store._loadVersion("step1");
store.count; // 1
// Redo to step3
store._loadVersion("step3");
store.count; // 3
Multiple synchronous mutations produce a single subscriber notification per flush:
const store = create(Counter);
const cb = vi.fn();
store._subscribe(cb);
store.incr();
store.incr();
store.incr();
// cb has NOT been called yet (async)
// after microtask flush → cb called exactly once
If you dispose a run effect before the microtask flush, the callback will not re-execute:
const store = create(Counter);
const values: number[] = [];
const dispose = run(() => values.push(store.count));
// values: [0]
store.incr();
dispose(); // dispose before flush
// after flush → values is still [0]
If another subscriber disposes a run effect during the same flush, the disposed effect's callback is skipped:
const store = create(Counter);
let dispose: () => void;
store._subscribe(() => dispose()); // disposes the run effect
dispose = run(() => {
console.log(store.count);
});
store.incr();
// after flush → the run effect does NOT re-execute (disposed by the other subscriber)
Calling dispose() more than once is safe — it's a no-op after the first call:
const dispose = run(() => { void store.count; });
dispose();
dispose(); // no error
Creating a store from a class with no properties works fine:
class Empty {}
const store = create(Empty);
store._version; // 0
Symbol-keyed properties are skipped during reactive setup — they remain on the instance but are not reactive:
const sym = Symbol("test");
class WithSymbol {
count = 0;
[sym] = "symbol-value";
}
const store = create(WithSymbol);
store.count; // 0 (reactive)
(store as any)[sym]; // "symbol-value" (not reactive)
Saving with the same label overwrites the previous snapshot:
const store = create(Counter);
store.incr();
store._saveVersion("x"); // saves count = 1
store.incr();
store.incr();
store._saveVersion("x"); // overwrites → saves count = 3
store._loadVersion("x");
store.count; // 3 (not 1)
Throws an error with a descriptive message:
store._loadVersion("nonexistent");
// Error: No saved version found for label "nonexistent"
Snapshots use structuredClone — saved state is fully independent. Mutating the store after saving doesn't affect the snapshot, and loading doesn't share references:
const store = create(AddressStore);
store.changeCity("Mumbai");
store._saveVersion();
store.changeCity("Kolkata");
store._loadVersion();
store.address.city; // "Mumbai" (not "Kolkata")
Both work. Arrow functions are instance properties (captured this), prototype methods use the instance as this:
class ArrowStore {
count = 0;
incr = () => { this.count++; }; // arrow (instance property)
getCount = () => { return this.count; }; // arrow
}
class ProtoStore {
count = 0;
incr() { this.count++; } // prototype method
}
Both patterns are fully supported by create.
Subscriber callbacks fire on the next microtask (via queueMicrotask), not synchronously when a property is set. If you need to read the updated state immediately after a mutation, read the property directly — don't rely on the subscriber having fired.
store.incr();
// store.count is already updated here ✅
// but subscribers have NOT been called yet ❌
The reactivity system tracks property assignments on the store, not deep mutations. Mutating a nested object in-place will not trigger subscribers or increment _version:
// ❌ WRONG — mutating in place, setter never fires
store.address.city = "Mumbai";
// ✅ CORRECT — assign a new object to trigger the setter
store.address = { ...store.address, city: "Mumbai" };
The same applies to arrays:
// ❌ WRONG — push mutates in place
store.users.push("Alice");
// ✅ CORRECT — spread into a new array
store.users = [...store.users, "Alice"];
memo Uses JSON.stringify for Argument ComparisonArguments are serialized with JSON.stringify. This means:
undefined, and Symbol values are dropped or converted to null during serialization.{a:1, b:2} and {b:2, a:1} produce different strings.// These are treated as different args even though semantically equal:
memo((obj) => obj.x)({ x: 1 }); // computes
memo((obj) => obj.x)({ x: 1 }); // computes again (different object reference → different JSON)
memo Caches Only the Last Callmemo stores a single cached result (the most recent args + store versions). Alternating between different argument sets will cause recomputation every time:
const doubled = memo((n: number) => store.count * n);
doubled(2); // computes
doubled(3); // computes (different args, evicts cache)
doubled(2); // computes again (cache was for args=3)
create calls new Class() with no arguments. If your class requires constructor parameters, it won't work:
// ❌ Won't work
class Store {
constructor(public initialCount: number) {}
}
// ✅ Use default values instead
class Store {
count = 0;
}
_reset Re-Instantiates the Class_reset() creates a new instance of the original class to read fresh default values. If your class constructor has side effects (API calls, timers, etc.), they will execute again on reset.
structuredClone Limitations on Save/Load_saveVersion and _loadVersion use structuredClone. This means:
_version, _subscribe, _reset, _saveVersion, and _loadVersion do not appear in Object.keys(), for...in, JSON.stringify(), or spread operations:
const store = create(Counter);
Object.keys(store); // ["count"] — no _version, _subscribe, etc.
JSON.stringify(store); // '{"count":0}'
run Re-Tracks on Every ExecutionEach time run's callback executes, it re-tracks which stores are accessed. If your callback conditionally accesses stores, the tracked set may change between runs:
run(() => {
if (storeA.flag) {
console.log(storeB.value); // storeB only tracked when flag is true
}
});
The library exports the following types:
import type { Store } from "immu-js";
import type { Computed } from "immu-js";
Store<T> — the store type, which is T augmented with reactive extras:
type Store<T> = T & {
readonly _version: number;
_subscribe: (callback: () => void, prop?: string) => () => void;
_reset: () => void;
_saveVersion: (label?: string) => void;
_loadVersion: (label?: string) => void;
};
Computed<T> — the computed value wrapper:
interface Computed<T> {
readonly value: T;
}
memo fully infers argument types and return types:
const fn = memo((x: number, y: string) => `${x}-${y}`);
// fn: (x: number, y: string) => string
# Build (ESM + CJS + type declarations)
npm run build
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
The test suite enforces 100% code coverage across statements, branches, functions, and lines.
MIT
FAQs
Independent immutable state library for JavaScript/TypeScript
We found that immu-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.
Security News
OpenSSF has issued a high-severity advisory warning open source developers of an active Slack-based campaign using impersonation to deliver malware.