Zenon
๐ฆ A minimalist, Zustand-inspired state manager for Vue 3
ยท English ยท Korean
---
## โจ Features
- ๐ **Vue 3 Composition API** - Modern reactive state management
- โก๏ธ **Zustand-like DX** - Familiar API with `set`, `get`, and selectors
- ๐งโ๐ป **Full TypeScript Support** - Complete type safety and inference
- ๐ **Lightweight** - Minimal bundle size, zero dependencies (except Vue)
- ๐ฏ **Selector-based Subscriptions** - Optimize rendering with partial updates
- ๐ **Pluggable Middleware** - Logger, Persist, ErrorBoundary, and more
- ๐งฉ **Composable** - Chain or compose multiple middlewares
- ๐ฆ **Tree-shakeable** - Import only what you need
- โ
**Production Ready** - Fully tested with 30+ test cases
## ๐พ Installation
```bash
pnpm add zenon
# or
npm install zenon
# or
yarn add zenon
```
## ๐ Quick Start
### Basic Usage
```ts
// stores/counter.ts
import { createStore } from "zenon";
export const useCounter = () =>
createStore((set, get) => ({
count: 0,
increment: () => set({ count: get().count + 1 }, "increment"),
decrement: () => set({ count: get().count - 1 }, "decrement"),
reset: () => set({ count: 0 }, "reset"),
}));
```
```vue
Count: {{ count }}
```
### With Middleware
```ts
import { createStore, compose } from "zenon";
import { withLogger, withPersist, withErrorBoundary } from "zenon/plugins";
export const useCounter = () =>
createStore(
compose(
withLogger({ store: "counter", timestamp: true }),
withPersist("zenon-counter", {
storage: window.localStorage,
version: 1,
}),
withErrorBoundary({
onError: (error, actionName) => {
console.error(`Error in ${actionName}:`, error);
},
})
)((set, get) => ({
count: 0,
increment: () => set({ count: get().count + 1 }, "increment"),
reset: () => set({ count: 0 }, "reset"),
}))
);
```
## ๐งฉ Middleware Plugins
Zenon provides three powerful middleware plugins that can be composed together:
### withLogger
Logs all state changes to the console with timestamps.
```ts
import { withLogger } from "zenon/plugins";
withLogger({
store: "counter", // Store name for logging
timestamp: true, // Include timestamps (default: false)
expanded: false, // Auto-expand logs (default: false)
});
```
### withPersist
Persists store state to localStorage or sessionStorage.
```ts
import { withPersist } from "zenon/plugins";
withPersist("zenon-counter", {
storage: window.localStorage, // default: localStorage
version: 1, // Version for migration control
partialKeys: ["count"], // Persist only specific keys
serialize: JSON.stringify, // Custom serializer
deserialize: JSON.parse, // Custom deserializer
onError: (error) => console.error(error), // Error handler
merge: (persisted, current) => ({ ...current, ...persisted }), // Merge strategy
});
```
### withErrorBoundary
Catches and handles errors in store actions.
```ts
import { withErrorBoundary } from "zenon/plugins";
withErrorBoundary({
onError: (error, actionName) => {
// Handle error (e.g., send to error tracking service)
console.error(`Error in ${actionName}:`, error);
},
preventRollback: false, // Prevent state rollback on error (default: false)
rethrow: false, // Rethrow error after handling (default: false)
});
```
### Composing Multiple Plugins
```ts
import { createStore, compose } from "zenon";
import { withLogger, withPersist, withErrorBoundary } from "zenon/plugins";
// Compose style (recommended)
export const useStore = () =>
createStore(
compose(
withLogger({ store: "app" }),
withPersist("app-state"),
withErrorBoundary({ onError: console.error })
)((set, get) => ({
// Your store implementation
}))
);
// Or chain style
export const useStore = () =>
createStore(
withLogger({ store: "app" })(
withPersist("app-state")(
withErrorBoundary({ onError: console.error })((set, get) => ({
// Your store implementation
}))
)
)
);
```
## ๐ API Reference
### createStore
Creates a new store with reactive state management.
```ts
function createStore(
initializer: (set: SetFunction, get: GetFunction) => T
): StoreApi;
```
**Returns:** `StoreApi` with the following methods:
- `useSelector(selector: (state: T) => U): ComputedRef` - Subscribe to partial state
- `subscribe(listener: Listener): () => void` - Subscribe to all state changes
- `setSilent(patch: Partial)` - Update state without triggering subscribers
- `getState(): T` - Get current state snapshot
- Plus all store actions defined in your initializer
### useSelector
Subscribe to a specific part of the store state. Only triggers re-renders when the selected value changes.
```ts
const store = useCounter();
const count = store.useSelector((s) => s.count); // Subscribe only to count
const double = store.useSelector((s) => s.count * 2); // Derived values work too
```
### subscribe
Subscribe to all state changes with a callback function.
```ts
const unsubscribe = store.subscribe((state, prevState) => {
console.log("State changed:", { state, prevState });
});
// Cleanup
unsubscribe();
```
### setSilent
Update state without notifying subscribers. Useful for batch updates or internal state changes.
```ts
store.setSilent({ count: 10 }); // Updates state without triggering listeners
```
## ๏ฟฝ TypeScript Support
Zenon is written in TypeScript and provides full type safety out of the box.
```ts
import { createStore, StoreApi, SetFunction, GetFunction } from "zenon";
// Type your store
type CounterState = {
count: number;
increment: () => void;
decrement: () => void;
};
export const useCounter = (): StoreApi =>
createStore((set, get) => ({
count: 0,
increment: () => set({ count: get().count + 1 }, "increment"),
decrement: () => set({ count: get().count - 1 }, "decrement"),
}));
```
**Exported Types:**
- `StoreApi` - Store instance type
- `SetFunction` - State setter function type
- `GetFunction` - State getter function type
- `Listener` - Subscribe callback type
- `StoreMiddleware` - Middleware function type
## ๐งช Testing
Zenon is thoroughly tested with 30+ test cases covering all features:
- โ
Core store functionality (reactivity, subscriptions, selectors)
- โ
All middleware plugins (logger, persist, error boundary)
- โ
Error handling and edge cases
- โ
TypeScript type safety
Run tests:
```bash
pnpm test
```
## ๏ฟฝ๐ License
MIT
## โญ๏ธ Star & Contribute
Ideas, PRs, and feedback are all welcome!