@iadev93/zuno

@iadev93/zuno

The core state engine for Zuno.

Zuno is a universal, event-driven state system designed to keep client, server, and multiple runtimes in sync with strong consistency guarantees.

This package provides the foundation:

• 🌌 Universe: Central coordination for all stores.
• 📦 Store: Versioned, observable state units.
• 🔄 Sync Primitives: SSE and BroadcastChannel transport implementations.
• 🔌 Adapter Ready: Exposes the ZunoReadable contract for UI bindings.

Features

• 🚀 Ultra-Fast: 1000+ snapshots/ms with incremental caching.
• ⚡️ Batching: coalesces multiple updates into single network syncs.
• 🔄 Real-time: SSE and BroadcastChannel for multi-tab/multi-client sync.
• 🛡️ Type-Safe: TypeScript-first design.
• 🔌 Adapters: React, Angular, Express, Elysia.

Install

npm install @iadev93/zuno

Quick Start (Client)

import { createZuno } from "@iadev93/zuno";

const zuno = createZuno({
  // Optional: Enable batching for high-frequency updates
  batchSync: true,
});

const counter = zuno.store(
  "counter", 
  () => 0, 
  undefined, 
  // Optional: Custom equality check
  (a, b) => a === b
);

await counter.set((v) => v + 1);
console.log(counter.get());

Core Concepts

Universe

A Universe is a container for many stores. It is responsible for:

• creating and caching stores by key
• coordinating versioned state events
• providing a stable API for sync/transports

Store

A Store is keyed state.

• get() returns current snapshot
• set(next) updates state (supports functional updates)
• subscribe(cb) notifies on changes

State Events (Versioned)

Zuno sync is driven by versioned state events. Each event includes:

• storeKey
• state
• origin (who produced it)
• baseVersion (what it was based on)
• version (monotonic)
• eventId (optional)

This enables deterministic ordering and protects against stale overwrites.

Client Sync

Zuno supports multi-tab / multi-client synchronization.

1) Same-origin tabs (BroadcastChannel)

import { startBroadcastChannel } from "@iadev93/zuno";

startBroadcastChannel({
  channelName: "zuno-demo"
});

BroadcastChannel works only across the same origin.

2) Multi-client sync (SSE)

import { startSSE } from "@iadev93/zuno";

startSSE({
  url: "/zuno/events",
  // optional: pass shared Maps for version bookkeeping
  // versions,
});

SSE is ideal for:

• low-latency state fanout
• CDN/proxy friendly infra
• avoiding WebSocket lock-in

Adapter Contract (UI / Frameworks)

Zuno exposes a minimal adapter contract that can be consumed by any UI/runtime:

type ZunoReadable<T> = {
  getSnapshot(): T;
  subscribe(onChange: () => void): () => void;
  getServerSnapshot?: () => T;
};

Helper:

import { toReadable } from "@iadev93/zuno";

const readable = toReadable(store);

This contract is used by official adapters:

• @iadev93/zuno-react
• @iadev93/zuno-angular (New!)

Server Usage (Optional Helpers)

If you want to host Zuno sync endpoints yourself (without @iadev93/zuno-express), the core package provides server-side utilities via the @iadev93/zuno/server entry point.

Snapshot handler

The snapshot handler returns the current universe/store snapshot for new clients.

import { /* snapshot handler export */ } from "@iadev93/zuno/server";

SSE connection + state publishing

Zuno’s SSE utilities typically do two jobs:

• register a client connection
• broadcast state events to connected clients

import { createSSEConnection, setUniverseState } from "@iadev93/zuno/server";

Applying incoming events

Incoming events should be validated and applied using the core apply routine.

import { /* apply-state-event export */ } from "@iadev93/zuno/server";

Framework Integration

• React: npm install @iadev93/zuno-react
• Angular: npm install @iadev93/zuno-angular (New!)
• Express: npm install @iadev93/zuno-express

For Express usage:

npm install @iadev93/zuno-express

It wires SSE + snapshot routes cleanly and keeps your core imports tidy.

Public Exports

Core exports are intentionally minimal:

• createZuno, CreateZunoOptions
• startSSE, startBroadcastChannel
• ZunoReadable, ZunoSubscribableStore, toReadable
• (optional) server helpers if you choose to expose them

If you export server helpers from core, consider server-only subpath exports to prevent accidental client bundling.

If you’re using Zuno in a real project, please open an issue and tell us your use case.

License

MIT