Reactive proxies for objects, arrays, Set, and Map. Subscriptions do not retain the target. Updates fire only when the value actually changes.

core · uniform
 └── fest/object      ← you are here
      └── lure · veela · icon · image · fl-ui

Install

npm install @fest-lib/core @fest-lib/uniform @fest-lib/object

Peers: @fest-lib/core, @fest-lib/uniform (>=0.1.0). ESM, Node 20+.

import { observe, affected, ref, computed } from "@fest-lib/object";

const state = observe({ count: 0, user: { name: "Ada" } });
const stop = affected(state, (value, prop) => {
    console.log("changed:", prop, value[prop as keyof typeof value]);
});
state.count = 1;
stop?.();

Features

• Non-intrusive subscriptions (disposer from affected).
• observe adapts Set / Map so iteration changes notify.
• Primitive refs with coercion (numberRef, stringRef, booleanRef).
• computed / derivate / conditional / propRef.
• bindBy / assign / link for shape sync.
• safe() for JSON (cycles, WeakRef).

Primitive refs

import { numberRef, stringRef, booleanRef, autoRef, promised } from "@fest-lib/object";

const n = numberRef(0);
const s = stringRef("hello");
const b = booleanRef(false);
n.value++;
s.value = `${s}!`;
b.value = 1;                    // truthy → true

const later = promised(fetch("/api").then((r) => r.status));

autoRef(true) / autoRef(42) / autoRef("hi") pick the matching primitive ref.

Collections

const list = observe([1, 2, 3]);
const bag = observe(new Set(["a", "b"]));
const map = observe(new Map([["x", 1]]));

affected(list, (_v, prop) => console.log("list", prop));
affected([observe({ name: "Ada" }), "name"], (v) => console.log("name:", v));

observableBySet / observableByMap expose a reactive array view. iterated subscribes to iteration.

Derived & bind

const source = observe({ x: 1, y: 2 });
const total = computed(source, (s) => s.x + s.y);
const view = derivate(source, (s) => ({ sum: s.x + s.y }));

const target = { x: 0, y: 0 };
bindBy(target, source);         // two-way by shape
source.x = 3;                   // target.x === 3

const cond = booleanRef(true);
const pick = conditional(cond, "yes", "no");
cond.value = false;             // pick.value === "no"

const obj = observe({ nested: { value: 42 } });
const deep = propRef(obj, "nested.value");

API map

| Group | Exports | | --- | --- | | Reactivity | observe, affected, isObservable, recoverReactive, makeArrayObservable | | Refs | ref, numberRef, stringRef, booleanRef, autoRef, promised, propRef | | Derived | computed, derivate, conditional, remap, unified | | Bind | bindBy, assign, link | | Collections | observableBySet, observableByMap, iterated | | Timing | triggerWithDelay, delayedBehavior, delayedOrInstantBehavior | | Utils | safe, deref, unwrap, unaffected | | Legacy | createReactive, createReactiveMap, createReactiveSet (deprecated) |

affected(obj, cb) or affected([obj, key], cb) → unsubscribe function. Keep it and call it.

Sources: src/core/Mainline.ts (subscribe), Primitives.ts, Assigned.ts, Subscript.ts, src/wrap/*.

Workspace

cd modules/projects/object.ts
npm test                 # node + deno + browser
npm run build
npm run publish

License: MIT.