Understanding `reactive()` - A Beginner's Guide

Quick Start (30 seconds)

Need to build reactive state step-by-step with a fluent API? Here's how:

// Build reactive state with method chaining
const counter = reactive({ count: 0 })
  .computed({
    doubled() {
      return this.state.count * 2;
    }
  })
  .watch({
    count(newVal, oldVal) {
      console.log(`Count: ${oldVal} → ${newVal}`);
    }
  })
  .effect(() => {
    console.log('Count is:', counter.state.count);
  })
  .action('increment', (state) => {
    state.count++;
  })
  .build();

// Use the built object
counter.increment();
console.log(counter.count);   // 1
console.log(counter.doubled); // 2

// Clean up when done
counter.destroy();

That's it! The reactive() function creates a builder that lets you construct reactive state step-by-step using a fluent API!

What is `reactive()`?

reactive() is a builder pattern function for creating reactive state incrementally. Instead of passing a large configuration object, you build up your reactive state piece by piece using method chaining.

A reactive builder:

Starts with initial state
Adds computed properties via .computed()
Adds watchers via .watch()
Adds effects via .effect()
Adds actions via .action() or .actions()
Builds the final object via .build()
Provides a fluent, chainable API

Think of it as a step-by-step constructor - you build your reactive object one feature at a time, and each step returns the builder so you can keep chaining.

Syntax

// Using the shortcut
reactive(initialState)

// Using the full namespace
ReactiveUtils.reactive(initialState)

// Alias: builder()
ReactiveUtils.builder(initialState)

Both styles are valid! Choose whichever you prefer:

Shortcut style (reactive()) - Clean and concise
Namespace style (ReactiveUtils.reactive() or ReactiveUtils.builder()) - Explicit and clear

Parameters:

initialState - An object with initial state properties (required)

Returns:

A builder object with chainable methods

Why Does This Exist?

Two Approaches to Building Reactive Components

The Reactive library offers flexible ways to create complex reactive objects, each suited to different coding preferences.

Configuration Object Style

When you prefer declarative, all-at-once definitions and want to see the complete structure upfront:

javascript

// Configuration-based component
const counter = component({
  state: {
    count: 0,
    step: 1
  },
  computed: {
    doubled() { return this.count * 2; },
    tripled() { return this.count * 3; }
  },
  watch: {
    count(newVal, oldVal) { console.log('Changed:', newVal); }
  },
  effects: {
    logCount() { console.log(this.count); }
  },
  actions: {
    increment(state) { state.count += state.step; },
    decrement(state) { state.count -= state.step; },
    reset(state) { state.count = 0; }
  }
});

This approach is great when you need: ✅ Complete component structure visible at once ✅ Familiar configuration object pattern ✅ All features grouped by type ✅ Single-object definition style

When Step-by-Step Construction Fits Your Style

In scenarios where you prefer incremental, fluent API patterns and want to build components piece by piece, reactive() provides a more direct approach:

javascript

// Builder pattern - construct step by step
const counter = reactive({ count: 0, step: 1 })
  .computed({
    doubled() { return this.state.count * 2; },
    tripled() { return this.state.count * 3; }
  })
  .watch({
    count(newVal, oldVal) { console.log('Changed:', newVal); }
  })
  .effect(() => {
    console.log(counter.state.count);
  })
  .action('increment', (state) => {
    state.count += state.step;
  })
  .action('decrement', (state) => {
    state.count -= state.step;
  })
  .action('reset', (state) => {
    state.count = 0;
  })
  .build();

This method is especially useful when:

Builder Pattern Flow:
┌──────────────────┐
│ reactive({...})  │
└────────┬─────────┘
         │
         ▼
   .computed({...})
         │
         ▼
   .watch({...})
         │
         ▼
   .effect(...)
         │
         ▼
   .build()
         │
         ▼
  ✅ Incremental & clear

Where reactive() shines: ✅ Fluent API preference - Method chaining for readability ✅ Incremental construction - Build features step by step ✅ Conditional features - Easy to add features based on conditions ✅ Top-to-bottom flow - Reads like a sequence of operations ✅ Dynamic composition - Programmatically add features in loops or conditions

The Choice is Yours:

Use component() when you prefer declarative configuration objects
Use reactive() when you prefer fluent builder patterns
Both create the same reactive object with identical capabilities

Benefits of the builder approach: ✅ Chainable methods - Fluent API for step-by-step construction ✅ Flexible composition - Easy to conditionally add features ✅ Linear reading - Top-to-bottom flow matches execution ✅ Progressive building - Start simple, add complexity as needed ✅ Same power - All features of component() available

Mental Model

Think of reactive() like an assembly line:

Large Config (Box of Parts):
┌────────────────────────┐
│   Box with all parts   │
│   ┌──────────────────┐ │
│   │ State            │ │
│   │ Computed         │ │
│   │ Watchers         │ │
│   │ Effects          │ │
│   │ Actions          │ │
│   └──────────────────┘ │
└────────────────────────┘
    Everything at once!
    Assemble yourself!

Builder (Assembly Line):
┌──────────┐      ┌──────────┐      ┌──────────┐
│ Add      │  →   │ Add      │  →   │ Add      │
│ State    │      │ Computed │      │ Watchers │
└──────────┘      └──────────┘      └──────────┘
     │                 │                 │
     ▼                 ▼                 ▼
┌──────────┐      ┌──────────┐      ┌──────────┐
│ Add      │  →   │ Add      │  →   │ Final    │
│ Effects  │      │ Actions  │      │ Product! │
└──────────┘      └──────────┘      └──────────┘
    Step by step!
    Clear process!

Key Insight: Just like an assembly line that builds a product step by step at each station, reactive() builds your reactive object one feature at a time through method chaining.

How Does It Work?

The Magic: Builder Pattern

When you call reactive(), here's what happens behind the scenes:

javascript

// What you write:
const myBuilder = reactive({ count: 0 })
  .computed({ doubled() { return this.state.count * 2; } })
  .action('increment', (state) => { state.count++; })
  .build();

// What actually happens (simplified):
// 1. Create state
const state = createReactive({ count: 0 });

// 2. Create builder object
const builder = {
  state: state,
  cleanups: [],

  computed(defs) {
    computed(state, defs);
    return this; // Return builder for chaining
  },

  action(name, fn) {
    state[name] = function() { return fn(state, ...arguments); };
    return this; // Return builder for chaining
  },

  build() {
    state.destroy = () => this.cleanups.forEach(c => c());
    return state;
  }
};

// 3. Chain methods
builder.computed({ doubled() { return this.count * 2; } });
builder.action('increment', (state) => { state.count++; });

// 4. Build final object
const final = builder.build();

In other words: reactive() creates a builder that:

Stores the reactive state internally
Provides chainable methods for adding features
Each method modifies the state and returns the builder
.build() returns the final reactive state with a destroy() method

Under the Hood

reactive({ count: 0 })
        │
        ▼
┌───────────────────────┐
│  Create Reactive      │
│  State                │
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│  Create Builder       │
│  with state + methods │
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│  .computed()          │
│  Adds to state        │
│  Returns builder      │
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│  .action()            │
│  Adds to state        │
│  Returns builder      │
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│  .build()             │
│  Returns final state  │
└───────────────────────┘

What happens:

1️⃣ Each builder method modifies the internal state 2️⃣ Each builder method returns the builder for chaining 3️⃣ You can chain as many methods as you want 4️⃣ .build() returns the final reactive state object

Basic Usage

Creating a Builder

The simplest way to use reactive():

// Start with reactive()
const builder = reactive({ count: 0 });

// Access the state during building
console.log(builder.state.count); // 0

// Build to get the final object
const state = builder.build();

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

Adding Features Before Building

// Add features before building
const myObject = reactive({ count: 0 })
  .computed({
    doubled() {
      return this.state.count * 2;
    }
  })
  .action('increment', (state) => {
    state.count++;
  })
  .build();

// Use the built object
myObject.increment();
console.log(myObject.count);   // 1
console.log(myObject.doubled); // 2