@uhd_kr/vanilla-state NPM

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

Best Practices

Listener Cleanup: Always remove listeners when they're no longer needed to prevent memory leaks.
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

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