@blackbirdjs/store

A lightweight, high-performance, and fine-grained (surgical) reactive state management for modern JavaScript applications. While it functions as the state core for the BlackbirdJS ecosystem, it is designed to be completely modular and plug-and-play across any web environment (React, Vue, Svelte, or Vanilla JS) with zero external dependencies.

Instead of broadcasting updates globally and forcing your entire application to re-render when a single value shifts, @blackbirdjs/store isolates updates directly to individual state keys for ultra-fast performance.

Features

• Plug-and-Play Reusable Architecture: Zero configurations required. Use it as a universal state engine inside any UI system.
• Fine-grained Reactivity: Subscribe strictly to individual state keys. Updating state.user will never trigger listeners tracking state.theme.
• Immediate Data Hydration: Downstream subscription callbacks execute immediately upon binding to populate UI states instantly without flickering.
• Ultra-High Performance Engine: Uses native JavaScript Set collections for allocation-free, constant-time O(1) subscription cleanups that completely eliminate garbage collection overhead.
• Identity Performance Guard: Automatically short-circuits and skips duplicate mutation loops if the incoming value matches the existing state.
• Secure Encapsulation: Clean API surface boundaries exposing atomic .get(), .set(), and .subscribe() parameters.

Installation

npm install @blackbirdjs/store

Quick Start

Basic Reactive State Management

import { BlackbirdStore } from '@blackbirdjs/store';

// Initialize the store with a default state object literal
const store = new BlackbirdStore({
  counter: 0,
  theme: 'light'
});

// Subscribe and capture the Subscription object
const counterSubscriber = store.subscribe('counter', (currentCount) => {
  console.log(`UI Updated! Current counter is: ${currentCount}`);
});

// Mutate the state key programmatically
store.set('counter', 1);  // Logs: "UI Updated! Current counter is: 1"
store.set('counter', 2);  // Logs: "UI Updated! Current counter is: 2"

// Clean up memory allocation instantly when a component unmounts
counterSubscriber.unsubscribe();

---

Best Practices: Updating Objects & Arrays

JavaScript compares non-primitive types (like Objects and Arrays) by memory reference, rather than by structural value. Because the internal performance guard performs an identity check (===), mutating an object inline will cause the store to ignore the update:

const store = new BlackbirdStore({ user: { name: 'John' } });

const activeUser = store.get('user');
activeUser.name = 'John Doe'; // ❌ Avoid: Mutating object properties inline

store.set('user', activeUser); // Fails to trigger updates because references match!

The Recommended Immutable Pattern

To update arrays or objects cleanly, use the JavaScript spread operator (...) to pass a fresh memory reference. This ensures the reactivity layer executes flawlessly:

const activeUser = store.get('user');

// Pass a new object reference combining existing values with updates
store.set('user', { ...activeUser, name: 'John Doe' }); // Updates cleanly!

---

API Specification

new BlackbirdStore(initialState)

Instantiates a new reactive container. initialState defaults to an empty object {} if omitted.

.get(key)

Returns the current value associated with a specific key identifier.

.set(key, newValue)

Assigns a new value to a specific key. Evaluates mutations against an identity block before executing constant-time Set iterations to notify target callbacks.

.subscribe(key, callback)

Registers a callback worker routine inside a key-specific Set collection. Automatically runs the callback immediately with the existing state payload and returns a Subscription object.

Returns:

• Object: A subscription handle containing:
  • unsubscribe(): Function — Removes the registered callback cleanly from memory.

---

License

Licensed under the Apache-2.0 License.