Observable

Interface: observable<T = any>

An extension of the core reactive primitive baseObservable<T>, observable<T> maintains a stateful value alongside reactive subscriptions.

---

Overview

observable<T> supports:

• A callable getter/setter interface: you can read the value by calling with no arguments, or update it by calling with a new value.
• Two-way binding modes (bind.to and bind.from) enabling flexible directional data flows.
• Async update patterns, including an optimistic update strategy allowing immediate UI updates with rollback on failure.

Note: For array-like data requiring fine-grained mutation events, prefer arrayObservable.

---

Type Parameters

Parameter	Description
T	The type of the internal stored value

---

Callable Signature

(newValue?: T): T

• Acts as both getter and setter:

  • If called without arguments, returns the current value.
  • If called with a new value, updates the stored value and returns the updated value.

---

Properties

value: T

• The current stored value.
• Can be accessed or assigned directly via getter/setter.

---

optimistic<R>(updater: (current: T) => T, promise: Promise<R>): Promise<R>

Applies an optimistic update strategy:

1. Calls the synchronous updater function to compute a new immutable value based on the current state.
2. Immediately applies this new value.
3. Returns a promise that, if rejected, rolls back the value to the previous state.

This pattern is ideal for UI updates requiring instant feedback that can revert on async failure (e.g., server update errors).

Parameters:

Name	Type	Description
updater	(current: T) => T	Pure synchronous function producing new value
promise	Promise<R>	Async operation representing eventual result

Returns:

• The same promise, augmented with rollback behavior on rejection.

---

bind

Binding object extending baseObservable<T>.bind with additional properties for two-way data binding:

• __observable__: Internal reference to this observable instance.

• to: Observable that reflects one-way binding from ViewModel → UI (UI updates don’t propagate back).

• from: Observable that reflects one-way binding from UI → ViewModel (ViewModel updates don’t propagate to UI).

---

Example Usage

// Create observable with initial value
const count = observable(0);

// Getter
console.log(count()); // 0
console.log(count.value); // 0

// Setter
count(10);
console.log(count()); // 10

// Optimistic update
const updatePromise = fetch('/api/update', { method: 'POST', body: JSON.stringify({ count: 20 }) });

count.optimistic(
  current => current + 10,
  updatePromise
).catch(() => {
  console.log('Update failed, reverted to previous count:', count());
});

---

Interface: observableConstructor

Constructor interface defining the factory signature and prototype.

---

Call Signature

<T>(initialValue?: T): observable<T>

Creates a new observable instance optionally initialized with initialValue.

---

Properties

Property	Type	Description
prototype	observable	Shared prototype for all instances

---

Factory: observable

A factory function creating a new observable instance.

• Encapsulates an internal stateful value.
• Provides a callable getter/setter wrapper.
• Delegates core reactive logic to baseObservable.

---

Summary

observable<T> is a stateful reactive primitive enabling simple value tracking, two-way bindings, and optimistic async updates with rollback support. It simplifies reactive programming by combining value storage with observable notifications and flexible binding strategies.