@jucie-reactive/reactive-jucie-state

Integrate fine-grained reactivity with Jucie State - connect reactive signals and computed values with your state management.

Installation

npm install @jucie-reactive/reactive-jucie-state @jucie-state/core

Note: Requires both @jucie-state/core and @jucie-reactive/core as peer dependencies.

What It Does

This plugin bridges the reactive system with Jucie State, enabling:

• Automatic reactivity for state changes
• Fine-grained tracking at the property level
• Computed values that update when state changes
• Subscribers for side effects on state changes

Quick Start

Install the Plugin

import { createState } from '@jucie-state/core';
import { ReactiveJucieState } from '@jucie-reactive/reactive-jucie-state';

const state = createState({
  count: 0,
  user: {
    name: 'John',
    email: '[email protected]'
  }
}).install(ReactiveJucieState);

Create Reactive Computations

// Create a computed value that tracks state
const doubled = state.createComputed(() => {
  return state.get(['count']) * 2;
});

console.log(doubled()); // 0

state.set(['count'], 5);
console.log(doubled()); // 10

Subscribe to State Changes

// Run side effects when state changes
state.createSubscriber(
  (s) => s.get(['user', 'name']),
  (name) => {
    console.log('User name changed:', name);
  }
);

state.set(['user', 'name'], 'Jane');
// Logs: "User name changed: Jane"

Examples

Computed Values from Multiple State Properties

import { createState } from '@jucie-state/core';
import { ReactiveJucieState } from '@jucie-reactive/reactive-jucie-state';

const state = createState({
  firstName: 'John',
  lastName: 'Doe',
  age: 30
}).install(ReactiveJucieState);

// Computed full name
const fullName = state.createComputed(() => {
  const first = state.get(['firstName']);
  const last = state.get(['lastName']);
  return `${first} ${last}`;
});

console.log(fullName()); // "John Doe"

state.set(['firstName'], 'Jane');
console.log(fullName()); // "Jane Doe"

Async Computed Values

const state = createState({
  userId: 1
}).install(ReactiveJucieState);

const userData = state.createComputed(async () => {
  const id = state.get(['userId']);
  const response = await fetch(`/api/users/${id}`);
  return response.json();
});

// Returns a promise
const user = await userData();
console.log(user);

// Changing userId triggers new fetch
state.set(['userId'], 2);
const newUser = await userData();

Nested State Tracking

const state = createState({
  cart: {
    items: [],
    total: 0
  }
}).install(ReactiveJucieState);

// Tracks nested property
const itemCount = state.createComputed(() => {
  const items = state.get(['cart', 'items']);
  return items.length;
});

state.set(['cart', 'items'], [{ id: 1 }, { id: 2 }]);
console.log(itemCount()); // 2

Batched Updates

const state = createState({
  x: 0,
  y: 0
}).install(ReactiveJucieState);

let computeCount = 0;
const sum = state.createComputed(() => {
  computeCount++;
  return state.get(['x']) + state.get(['y']);
});

// Batch multiple updates
state.batch(() => {
  state.set(['x'], 10);
  state.set(['y'], 20);
});

// Only computes once for both changes
console.log(sum()); // 30
console.log(computeCount); // 1 (not 2!)

Side Effects with Subscribers

const state = createState({
  theme: 'light',
  notifications: []
}).install(ReactiveJucieState);

// Update UI when theme changes
state.createSubscriber(
  (s) => s.get(['theme']),
  (theme) => {
    document.body.className = theme;
  }
);

// Log new notifications
state.createSubscriber(
  (s) => s.get(['notifications']),
  (notifications) => {
    const latest = notifications[notifications.length - 1];
    if (latest) {
      console.log('New notification:', latest);
    }
  }
);

Child Property Tracking

const state = createState({
  settings: {
    audio: { volume: 50, muted: false },
    video: { quality: 'HD', autoplay: true }
  }
}).install(ReactiveJucieState);

// Tracks entire settings object
const settingsWatcher = state.createComputed(() => {
  return state.get(['settings']);
});

// Subscribe gets called for ANY change in settings
state.createSubscriber(
  () => state.get(['settings']),
  (settings) => {
    console.log('Settings changed:', settings);
  }
);

// This triggers the subscriber
state.set(['settings', 'audio', 'volume'], 75);

API

Plugin Installation

const state = createState(initialState).install(ReactiveJucieState);

Plugin Actions

state.createComputed(fn, config)

Create a computed value that tracks state dependencies.

const computed = state.createComputed(() => {
  return state.get(['path', 'to', 'value']);
}, {
  debounce: 100,     // Debounce updates
  immediate: true    // Compute immediately
});

state.createSubscriber(getter, callback, config)

Subscribe to state changes and run side effects.

const unsubscribe = state.createSubscriber(
  (state) => state.get(['path']),
  (value) => {
    console.log('Value changed:', value);
  },
  {
    debounce: 50  // Debounce callback
  }
);

// Later: cleanup
unsubscribe();

How It Works

The plugin integrates with Jucie State's lifecycle hooks:

1. Dependency Tracking: When a computed accesses state via state.get(), it's automatically tracked
2. Change Detection: When state changes via state.set(), the plugin marks dependent computeds as dirty
3. Batching: Changes are batched and computeds are updated efficiently
4. Fine-Grained: Only computeds that depend on changed paths are recomputed

Performance

• Path-based tracking: Only tracks the specific paths accessed
• Batched updates: Multiple state changes trigger single computed update
• Lazy evaluation: Computed values only update when accessed
• WeakRef cleanup: Automatic cleanup of destroyed computeds

License and Usage

This software is provided under the MIT License with Commons Clause.

✅ What You Can Do

• Use this library freely in personal or commercial projects
• Include it in your paid products and applications
• Modify and fork for your own use
• View and learn from the source code

❌ What You Cannot Do

• Sell this library as a standalone product or competing state management solution
• Offer it as a paid service (SaaS) where the primary value is this library
• Create a commercial fork that competes with this project

⚠️ No Warranty or Support

This software is provided "as-is" without any warranty, support, or guarantees:

• No obligation to provide support or answer questions
• No obligation to accept or implement feature requests
• No obligation to review or merge pull requests
• No obligation to fix bugs or security issues
• No obligation to maintain or update the software

You are welcome to submit issues and pull requests, but there is no expectation they will be addressed. Use this software at your own risk.

See the LICENSE file for complete terms.

Made with ⚡ by Adrian Miller