@jucie-reactive/core

Fine-grained reactive programming with signals, computed values, and reactive surfaces.

Features

• Signals: Simple reactive values with automatic dependency tracking
• Reactors: Computed values that update when dependencies change
• Surfaces: Component-like reactive contexts with state management
• Subscribers: Side effects that run when reactive values change
• Async Support: Native support for async computations
• Batched Updates: Efficient change propagation

Installation

npm install @jucie-reactive/core

Quick Start

Signals

Reactive primitive values:

import { createSignal } from '@jucie-reactive/core';

const count = createSignal(0);

console.log(count()); // 0
count(5);
console.log(count()); // 5

// Update based on current value
count(n => n + 1);
console.log(count()); // 6

Reactors (Computed Values)

Automatically computed values:

import { createSignal, createComputed } from '@jucie-reactive/core';

const count = createSignal(0);
const doubled = createComputed(() => count() * 2);

console.log(doubled()); // 0
count(5);
console.log(doubled()); // 10

Surfaces

Declarative reactive components:

import { defineSurface } from '@jucie-reactive/core';

const useCounter = defineSurface(({ value, computed, action }) => ({
  count: value(0),
  doubled: computed((ctx) => ctx.count * 2),
  increment: action((ctx) => ctx.count++),
  decrement: action((ctx) => ctx.count--)
}));

const counter = useCounter();
console.log(counter.count); // 0
console.log(counter.doubled); // 0

counter.increment();
console.log(counter.count); // 1
console.log(counter.doubled); // 2

Subscribers

Side effects for reactive values:

import { createSignal, createSubscriber } from '@jucie-reactive/core';

const count = createSignal(0);

createSubscriber(
  () => count(),
  (value) => console.log('Count changed:', value)
);

count(1); // Logs: "Count changed: 1"
count(2); // Logs: "Count changed: 2"

Advanced Features

Async Reactors

import { createSignal, createComputed } from '@jucie-reactive/core';

const userId = createSignal(1);

const userData = createComputed(async () => {
  const response = await fetch(`/api/users/${userId()}`);
  return response.json();
});

// Returns a promise
const data = await userData();

Surface with Object Configuration

import { defineSurface } from '@jucie-reactive/core';

const useApp = defineSurface({
  state: {
    count: 0,
    message: 'Hello'
  },
  computed: {
    doubled(ctx) {
      return ctx.count * 2;
    }
  },
  actions: {
    increment(ctx) {
      ctx.count++;
    }
  },
  onInit(ctx) {
    console.log('Surface initialized');
  },
  onDestroy(ctx) {
    console.log('Surface destroyed');
  }
});

Effects

import { createSignal, addEffect } from '@jucie-reactive/core';

const count = createSignal(0);

addEffect(count, (value) => {
  console.log('Effect:', value);
});

count(1); // Logs: "Effect: 1"

API Reference

Signals

• createSignal(initialValue) - Create a reactive signal
• destroySignal(signal) - Destroy a signal
• isSignal(value) - Check if value is a signal

Reactors

• createComputed(fn, config) - Create a computed value
• destroyComputed(computed) - Destroy a computed
• isComputed(value) - Check if value is a computed

Surfaces

• defineSurface(setupFn|config, options) - Create a reactive surface
• isSurface(value) - Check if value is a surface
• refreshSurface(surface) - Refresh a surface

Subscribers

• createSubscriber(getter, callback, config) - Create a subscriber
• destroySubscriber(subscriber) - Destroy a subscriber
• isSubscriber(value) - Check if value is a subscriber

Reactive System

• addEffect(getter, callback) - Add effect to reactive value
• removeEffect(getter, callback) - Remove effect
• provideContext(value) - Provide context
• getContext() - Get current context

Configuration Options

Signal/Reactor Config

{
  debounce: 100,        // Debounce updates (ms)
  immediate: true,      // Compute immediately
  effects: [fn],        // Initial effects
  detatched: false,     // Skip dependency tracking
  onAccess: (value) => {} // Callback on access
}

Surface Options

{
  mode: 'development'  // Enable dev features
}

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.

Contributing

While contributions are welcome, please understand there is no obligation to review, accept, or merge them. This project is maintained at the discretion of the author.

Made with ⚡ by Adrian Miller