🚀 Overview

Zen is a hyper-optimized state management library that delivers signal-like performance across all major frameworks. Through extreme minimalism and architectural excellence, Zen achieves speeds that crush the competition while keeping your bundle microscopic.

Stop settling for framework lock-in. Choose Zen.

⚡ Why Zen?

Unmatched Performance

• 🚀 1.7-7.3x faster than Zustand on core operations
• 🔥 45x faster than Jotai on atom creation
• ⚡ 2.8-8x faster than Nanostores on nested operations
• 💨 10-40% faster than computed() with select() API
• 📦 Just 1.45 kB gzipped - Smaller than most libraries

True Framework Freedom

• 🎯 Write Once, Run Everywhere - React, Vue, Solid, Svelte, Preact
• 🧩 Integrations under 250 bytes - Minimal framework adapters
• 🛡️ Battle-tested - Production-ready architecture
• 📚 Zero Framework Dependencies - Pure JavaScript core
• 🎨 Modern API - Signals-inspired design

Developer Experience

• 💡 Intuitive API - Simple primitives, powerful composition
• 🔒 Type Safe - Full TypeScript support with perfect inference
• ⚙️ Reactive Async - Karma with auto-caching, deduplication, and invalidation
• 🌳 Deep State - Nested paths, maps, computed values
• 🎨 Immutable Updates - Optional Immer-style mutations via zen-craft

Installation

# Using bun (recommended)
bun add @sylphx/zen

# Using npm
npm install @sylphx/zen

# Using pnpm
pnpm add @sylphx/zen

# Using yarn
yarn add @sylphx/zen

Quick Start

Vanilla JavaScript

import { zen, get, set, subscribe } from '@sylphx/zen';

// Create reactive state
const count = zen(0);

// Subscribe to changes
subscribe(count, (value) => {
  console.log('Count:', value);
});

// Update state
set(count, get(count) + 1);

React

import { zen, set } from '@sylphx/zen';
import { useStore } from '@sylphx/zen-react'; // 216 bytes

const count = zen(0);

function Counter() {
  const value = useStore(count);
  return <button onClick={() => set(count, value + 1)}>{value}</button>;
}

Vue

<script setup>
import { zen, set } from '@sylphx/zen';
import { useStore } from '@sylphx/zen-vue'; // ~200 bytes

const count = zen(0);
const value = useStore(count);
</script>

<template>
  <button @click="set(count, value + 1)">{{ value }}</button>
</template>

Solid.js

import { zen, set } from '@sylphx/zen';
import { useStore } from '@sylphx/zen-solid'; // 234 bytes

const count = zen(0);

function Counter() {
  const value = useStore(count);
  return <button onClick={() => set(count, value() + 1)}>{value()}</button>;
}

Svelte

<script>
  import { zen, set } from '@sylphx/zen';
  import { fromZen } from '@sylphx/zen-svelte'; // 167 bytes

  const count = zen(0);
  const value = fromZen(count);
</script>

<button on:click={() => set(count, $value + 1)}>{$value}</button>

API

Core Functions

zen(initialValue)

Create a reactive atom:

import { zen, get, set } from '@sylphx/zen';

const count = zen(0);
const user = zen({ name: 'Alice', age: 25 });

// Read value
console.log(get(count)); // 0

// Update value
set(count, 5);
set(user, { name: 'Bob', age: 30 });

computed(dependencies, computeFn)

Create derived state:

import { zen, computed, set } from '@sylphx/zen';

const count = zen(10);
const doubled = computed([count], (n) => n * 2);

console.log(get(doubled)); // 20
set(count, 15);
console.log(get(doubled)); // 30

select(store, selector)

Optimized single-source derivation (10-40% faster than computed):

import { zen, select, set } from '@sylphx/zen';

const user = zen({ name: 'Alice', age: 25 });
const userName = select(user, (u) => u.name);

console.log(get(userName)); // 'Alice'
set(user, { name: 'Bob', age: 30 });
console.log(get(userName)); // 'Bob'

subscribe(store, listener)

Listen to state changes:

import { zen, set, subscribe } from '@sylphx/zen';

const count = zen(0);

const unsubscribe = subscribe(count, (value) => {
  console.log('Count changed:', value);
});

set(count, 5); // Output: Count changed: 5

unsubscribe(); // Stop listening

Object State

map(initialObject)

Create reactive object with key subscriptions:

import { map, setKey, listenKeys } from '@sylphx/zen';

const user = map({ name: 'Alice', age: 30 });

// Listen to specific keys
listenKeys(user, ['age'], (value) => {
  console.log('Age changed:', value);
});

setKey(user, 'age', 31); // Output: Age changed: 31
setKey(user, 'name', 'Bob'); // No output (not listening to 'name')

Nested State

deepMap(initialObject)

Create reactive object with path subscriptions:

import { deepMap, setPath, listenPaths } from '@sylphx/zen';

const settings = deepMap({
  user: { preferences: { theme: 'light' } },
  data: [10, 20, 30]
});

// Listen to nested paths
listenPaths(settings, [['user', 'preferences', 'theme']], (value) => {
  console.log('Theme:', value);
});

setPath(settings, 'user.preferences.theme', 'dark');
// Output: Theme: dark

setPath(settings, ['data', 1], 25); // Update array element

Async State (Karma)

karma(asyncFunction, options)

Create a fully reactive async store inspired by Riverpod AsyncProvider. Karma provides automatic caching, concurrent request deduplication, and reactive invalidation:

import { karma, runKarma, subscribeToKarma, karmaCache } from '@sylphx/zen';

// Create karma with options
const fetchUser = karma(
  async (id: number) => {
    const res = await fetch(`/api/users/${id}`);
    return res.json();
  },
  {
    cacheKey: (id) => ['user', id],  // Custom cache key
    staleTime: 5000,                  // 5s before stale
    cacheTime: 30000,                 // 30s before auto-dispose
    keepAlive: false                  // Auto-dispose when no listeners
  }
);

// Execute and cache (36x faster on cache hits!)
const user1 = await runKarma(fetchUser, 123);  // Fetches
const user2 = await runKarma(fetchUser, 123);  // Returns cache instantly

// Subscribe to reactive updates
const unsub = subscribeToKarma(fetchUser, [123], (state) => {
  if (state.loading) console.log('Loading...');
  if (state.data) console.log('User:', state.data);
  if (state.error) console.log('Error:', state.error);
});

// Reactive cache control
karmaCache.invalidate(fetchUser, 123);  // Triggers re-fetch for active listeners
karmaCache.set(fetchUser, [123], newData);  // Optimistic update
karmaCache.get(fetchUser, 123);  // Get cached state

Key Features:

• ⚡ 36x faster cache hits (avg ~0.04ms)
• 🎯 Perfect deduplication - 100 concurrent requests → 1 execution
• 🔄 Reactive invalidation - Auto re-fetch for active listeners
• 🗑️ Auto-dispose - Cleans up unused cache entries
• 📡 Stale-while-revalidate - Return cache + background refetch
• 🎨 Per-parameter caching - Each argument combination cached separately

Performance:

• Cache hit: ~0.04ms (O(1) constant time)
• 100 concurrent requests (same args): ~1.3ms (vs 100+ fetches)
• 1000 listeners notification: 4ms (4μs per listener)
• No degradation with 1000+ cache entries

See BENCHMARK_RESULTS.md for detailed benchmarks.

Batch Updates

batch(fn)

Batch multiple updates into a single notification:

import { zen, set, batch, subscribe } from '@sylphx/zen';

const count = zen(0);
const user = zen({ name: 'Alice' });

subscribe(count, () => console.log('Count updated'));

batch(() => {
  set(count, 1);
  set(count, 2);
  set(count, 3);
});
// Output: Count updated (only once)

Advanced Hooks

import { zen, onStart, onStop, onSet, onNotify, onMount } from '@sylphx/zen';

const count = zen(0);

// Called when first subscriber attaches
onStart(count, () => {
  console.log('First subscriber');
});

// Called when last subscriber detaches
onStop(count, () => {
  console.log('No more subscribers');
});

// Called before value changes
onSet(count, (newValue, oldValue) => {
  console.log('Value changing:', oldValue, '->', newValue);
});

// Called after notifications sent
onNotify(count, () => {
  console.log('Subscribers notified');
});

// Called once on store initialization
onMount(count, () => {
  console.log('Store mounted');
});

🎨 Immutable Updates with zen-craft

For complex state updates, use @sylphx/zen-craft - a Zen integration powered by Craft, our in-house high-performance immer replacement:

import { zen } from '@sylphx/zen';
import { craftZen } from '@sylphx/zen-craft';

const todos = zen([
  { id: 1, text: 'Learn Zen', done: false }
]);

// Craft-powered immutable updates with JSON Patches support
craftZen(todos, (draft) => {
  draft[0].done = true;
  draft.push({ id: 2, text: 'Build app', done: false });
});

Why Craft?

• 🚀 1.4-35x faster than immer across all operations
• 📦 2.9 KB gzipped - 39% smaller than immer
• 🎯 100% API compatible - Drop-in replacement
• ⚡ Built by us - Same team, same performance obsession

Learn more about Craft →

🏆 Performance

Zen doesn't just compete - it dominates.

Through extreme minimalism and hyper-optimization, Zen achieves performance that crushes the competition while keeping your bundle microscopic.

📊 Benchmark Results

All results in operations per second (higher is better):

Atom Operations

Zen's atom creation is 45x faster than Jotai and 750x faster than Effector!

Computed Operations

Zen's computed creation is 56x faster than Nanostores and 3,400x faster than Effector!

Nested State Operations

Zen wins across ALL nested state operations!

Benchmarks from latest version on Apple M1 Pro. Results may vary.

📦 Bundle Size Comparison

Zen delivers a complete state management solution with multiple patterns (atoms, maps, deepMaps, computed, karma) in just 1.45 kB - smaller than most libraries' core functionality!

🚀 What Makes Zen Fast?

1. Extreme minimalism - Every byte counts, zero waste
2. Graph coloring algorithm - Lazy pull-based evaluation prevents unnecessary recomputation
3. Optimized subscriber notifications - Array-based listeners with smart batching
4. Efficient dependency tracking - Minimal overhead computed values
5. Native JavaScript - No proxy overhead for basic operations
6. Smart caching - Computed values cached until dependencies change
7. Zero indirection - Direct function calls, no wrappers
8. Hot path optimization - Critical paths inlined for maximum speed

📈 Run Benchmarks Yourself

cd packages/zen
bun run bench

See the difference with your own eyes!

💡 Zen vs The Competition

The Multi-Framework Problem

Framework-specific state solutions lock you in:

// ❌ Solid Signals - Solid.js ONLY
const [count, setCount] = createSignal(0);

// ❌ Vue Reactivity - Vue ONLY
const count = ref(0);

// ❌ Svelte Stores - Svelte ONLY
const count = writable(0);

The Zen Solution: Write Once, Run Everywhere

// ✅ Write your state logic ONCE
// state/counter.ts - Framework agnostic!
import { zen, computed } from '@sylphx/zen';

export const count = zen(0);
export const doubled = computed([count], (n) => n * 2);

Use the same state in ANY framework by swapping one import:

// React
import { useStore } from '@sylphx/zen-react';

// Vue
import { useStore } from '@sylphx/zen-vue';

// Solid.js
import { useStore } from '@sylphx/zen-solid';

// Svelte
import { fromZen } from '@sylphx/zen-svelte';

// Preact
import { useStore } from '@sylphx/zen-preact';

Same logic. Different frameworks. Zero rewrites.

vs Zustand

vs Jotai

vs Nanostores

Why settle for single-pattern libraries when you can have the complete package?

vs TanStack Query / SWR (Async State)

Karma is already included in Zen's 1.45 kB bundle - no extra bytes for async state!

🌟 Ecosystem

Core Packages

Framework Integrations

Routing

Type Safety

Zen has excellent TypeScript support with full type inference:

import { zen, computed, map, set } from '@sylphx/zen';

const count = zen(0); // Inferred as Zen<number>
const user = map({ name: 'Alice', age: 30 }); // Inferred as Map<{name: string, age: number}>

const doubled = computed([count], (n) => n * 2); // n is inferred as number

// Full type safety
set(count, 'invalid'); // ❌ Type error
set(count, 42); // ✅ OK

setKey(user, 'age', '30'); // ❌ Type error (expects number)
setKey(user, 'age', 30); // ✅ OK

How It Works

Zen uses a minimal publish-subscribe architecture with advanced optimizations:

1. Atoms store primitive reactive state
2. Graph coloring algorithm enables lazy pull-based evaluation
3. Computed values track dependencies with 3-state system (CLEAN/GREEN/RED)
4. Subscribers are notified only when their dependencies actually change
5. Batching groups multiple updates into single notifications
6. Array-based listeners for maximum notification speed
7. Structural sharing ensures efficient memory usage

All with zero proxy overhead for basic operations and microscopic bundle size.

Graph Coloring Optimization (Phase 6)

Zen uses a reactive graph coloring algorithm inspired by Reactively for optimal performance:

• CLEAN (0) - Value is definitely clean, no update needed
• GREEN (1) - Potentially affected, needs validation of dependencies
• RED (2) - Definitely dirty, requires recomputation

This approach eliminates redundant updates in diamond dependencies and enables true lazy evaluation where computed values only update when actually accessed.

Development

# Install dependencies
bun install

# Run tests
bun test

# Run tests in watch mode
bun test:watch

# Run benchmarks
bun run bench

# Type checking
bun run typecheck

# Build all packages
bun run build

🌟 Show Your Support

If Zen makes your life easier, give it a ⭐ on GitHub!

📄 License

MIT © Sylph

🙏 Credits

Built with ❤️ for developers who refuse to compromise on performance or framework lock-in.

Powered by Craft for immutable state updates.

Stop settling for framework lock-in. Choose Zen.
_{State management that works everywhere, at lightning speed}