Vanilla State

🚀 A lightweight, proxy-based state management solution in vanilla JavaScript/TypeScript with zero dependencies. Perfect for modern web applications looking for a simple yet powerful state management solution.

English | 한국어

🚨 Important: v3.2.0 Updates

Version 3.2.0 introduces a unified state update API:

• New set function with notification control for both primitive and object states
• Deprecated setWithoutNotify in favor of the enhanced set function with options
• Improved parameter validation and error messages

For those updating from v3.1.0 or earlier, please refer to the Migration Guide for API changes.

Features

• 🚀 Lightweight and Zero Dependencies
• 🔄 Proxy-based Reactivity
• 📦 TypeScript Support
• 🎯 Event-based State Updates
• 💡 Simple and Intuitive API
• 📱 Browser and Node.js Support

Installation

1. NPM

npm install @uhd_kr/vanilla-state
# or
yarn add @uhd_kr/vanilla-state
# or
pnpm add @uhd_kr/vanilla-state

import VnlState from '@uhd_kr/vanilla-state';

2. CDN

<!-- Modern browsers (recommended) -->
<script type="module">
  import VnlState from 'https://unpkg.com/@uhd_kr/vanilla-state/dist/vanilla-state.esm.js';
</script>

<!-- Traditional script tag -->
<script src="https://unpkg.com/@uhd_kr/vanilla-state"></script>

3. Direct Download

Download from the dist folder:

• vanilla-state.min.js - Minified UMD build (browsers)
• vanilla-state.esm.js - ES Module build
• vanilla-state.cjs.js - CommonJS build

Usage

JavaScript

import VnlState from '@uhd_kr/vanilla-state';

// Object state management
const state = new VnlState({
  name: 'Vanilla State',
  version: '3.2.0'
});

// Add state listener - new v3.0.0 API
state.addEventListener('change', (changeInfo) => {
  console.log(`${changeInfo.property} changed to: ${changeInfo.value}`);
});

// Update state
state.name = 'Updated Name'; // Triggers change event

// Primitive state management - new in v3.0.0
const count = new VnlState(0);

count.addEventListener('change', (value) => {
  console.log('Count changed to:', value);
});

// Update primitive state
count.set(count + 1); // Triggers change event

TypeScript

import VnlState from '@uhd_kr/vanilla-state';

// Type-safe event listener with v3.0.0 API
const count = new VnlState(0);

count.addEventListener<number>('change', (value) => {
  console.log('Count changed to:', value.toFixed(0));
});

count.set(count + 1); // Triggers event with number value

Advanced Usage

Silent Updates (New in v3.2.0)

Update state without triggering listeners:

// Object state
state.set('count', 2, { notify: false });

// Primitive state
count.set(5, { notify: false });

Batch Updates

Group multiple state updates and trigger listeners only once at the end:

state.batch((s) => {
  s.count = 1;
  s.user.role = "Admin";
});
// All listeners will be notified only once after all updates are complete

Custom Events (New in v3.0.0)

// Emit a custom event
state.emit('save-completed', { success: true, timestamp: Date.now() });

// Listen for custom events
state.addEventListener('save-completed', (result) => {
  if (result.success) {
    showNotification('Save completed successfully!');
  }
});

Multiple Listeners

// Add multiple listeners
state.addEventListener('count', value => console.log('Listener 1:', value));
state.addEventListener('count', value => console.log('Listener 2:', value));

// Remove specific listener
const listener = value => console.log('Removable:', value);
state.addEventListener('count', listener);
state.removeEventListener('count', listener);

Object Properties

// Objects are supported
state.user = { name: 'John', age: 25 };
state.addEventListener('user', user => {
  console.log('User updated:', user);
});

// Update object
state.user = { ...state.user, age: 26 };

Development

Prerequisites

• Node.js >= 14
• pnpm (recommended) or npm

Setup

# Clone the repository
git clone https://github.com/hwanyong/vanilla-state.git

# Install dependencies
pnpm install

# Build the package
pnpm build

Scripts

• pnpm build: Build the package
• pnpm typecheck: Run TypeScript type checking
• pnpm format: Format code with Prettier
• pnpm changeset: Create a new changeset
• pnpm release: Publish to npm

For more detailed development guidelines, see our Contributing Guide.

Documentation

• Migration Guide
• Deployment Guide
• Changelog

Best Practices

1. Listener Cleanup: Always remove listeners when they're no longer needed to prevent memory leaks.

2. Immutable Updates: When updating objects or arrays, create new references:

// Good
state.items = [...state.items, newItem];

// Bad
state.items.push(newItem); // Won't trigger listeners

3. Silent Updates: Use set with { notify: false } when batching multiple updates:

state.set('loading', true, { notify: false });
state.set('data', newData, { notify: false });
state.loading = false; // Only this update triggers listeners

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Node.js 14+

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Process

1. Fork the repository
2. Create a new branch
3. Make your changes
4. Add tests if applicable
5. Create a changeset (pnpm changeset)
6. Submit a pull request

For more information about deploying new versions, see our Deployment Guide.

License

MIT © Hwanyong Yoo(UHD)