value-enhancer



Enhance value with plain and explicit reactive wrapper. Think of it as hook-style signals.

Docs:

Install

``bash
npm add value-enhancer
`

Features

- Plain reactivity.
Without the implicit-cast Proxy magic like Vue Reactivity and MobX.
- Single-layer shallow reactivity.
It does not convert the value with Object.defineProperty nor Proxy. Keeping everything as plain JavaScript value makes it easier to work with other libraries and easier for the JavaScript engine to optimize.
- Safe and fast lazy computation.
It solves multi-level derivation issue (like in Svelte Stores>)) with smart lazy value evaluation.
- Weak side effects.
Vals are managed with FinalizationRegistry and WeakRef which means you can create and access derived Val.value without worrying about memory leaks. Disposers returned by subscriptions can also be easily managed with libraries like @wopjs/disposable.
- Explicit.
Reactive objects are easy to tell since their types are different from normal objects. Subscription also requires explicit dependency declaration which reduce the work of repetitive dynamic dependency collection in Proxy/Signal implementations.
- Simple DX.
Designed with ergonomics in mind. No hidden rules for getting or setting values. What you see is what you get.

Sizes

!value-enhancer size

Quick Q&A

Devtools

Usage

Create Writable Val

`js
import { val } from "value-enhancer";

const count$ = val(2);

console.log(count$.value); // 2

count$.set(3);
console.log(count$.value); // 3

count$.value = 4;
console.log(count$.value); // 4
`

Create Readonly Val

`js
import { readonlyVal } from "value-enhancer";

const [count$, setCount] = readonlyVal(2);

console.log(count$.value); // 2

setCount(3);
console.log(count$.value); // 3

count$.value = 4;
console.log(count$.value); // 4
`

Subscribe to value changes

`js
import { val, combine, derive, nextTick } from "value-enhancer";

const count$ = val(3);

// Emit the current value synchronously, then emit the new value when it changes.
const disposeSubscribe = count$.subscribe(count => {
console.log(subscribe: ${count});
}); // printed "subscribe: 3"

// Only emit the new value when it changes.
const disposeReaction = count$.reaction(count => {
console.log(reaction: ${count});
}); // (nothing printed)

// Object.is equality check by default
count$.set(3); // nothing happened

// subscription triggered asynchronously by default
count$.set(4); // nothing happened

await nextTick(); // subscription triggered asynchronously by default

// printed "subscribe: 4"
// printed "reaction: 4"

disposeSubscribe();
disposeReaction();
`

Derive Val

derive a new Val from another Val.

`js
import { val, derive } from "value-enhancer";

const count$ = val(2);

const derived$ = derive(count$, count => count * 3);

console.log(derived$.value); // 6
`

Pipe-able style with functional lib like rubico: (CodeSandbox)

`ts
import { derive, val } from "value-enhancer";
import { pipe, map, filter } from "rubico";

const isOdd = (number: number) => number % 2 == 1;

const square = (number: number) => number ** 2;

const numbers$ = val([1, 2, 3, 4, 5]);

const derived$ = derive(numbers$, pipe([filter(isOdd), map(square)]));

console.log(derived$.value); // [1, 9, 25]

derived$.reaction(numbers => {
console.log("reaction", numbers);
});

numbers$.set([6, 7, 8, 9, 10]);

// reaction [49, 81]
`

Combine Val

combine multiple Vals into a new Val.

`js
import { val, derive, combine } from "value-enhancer";

const count$ = val(2);

const derived$ = derive(count$, count => count * 3);

const combined$ = combine(
[count$, derived$],
([count, derived]) => count + derived
);

console.log(combined$.value); // 8
`

Flatten Val

flatten the inner Val from a Val of Val. This is useful for subscribing to a dynamic Val that is inside another Val.

`js
import { val, flatten } from "value-enhancer";

const itemList$ = val([val(1), val(2), val(3)]);

const firstItem$ = flatten(itemList$, itemList => itemList[0]);

console.log(firstItem$.value); // 1

itemList$.set([val(4), val(5), val(6)]);

console.log(firstItem$.value); // 4
`

Compute

compute is useful for subscribing to flexible dynamic dependencies.

The get function passed to the effect callback can be used to get the current value of a Val and subscribe to it.
The effect callback will be re-evaluated whenever the dependencies change.
Stale dependencies are unsubscribed automatically.

`js
import { val, compute } from "value-enhancer";

const count$ = val(0);
const a$ = val("a");
const b$ = val("b");

const s$ = compute(get => {
return get(count$) % 2 === 0 ? get(a$) : get(b$);
});
`

From

from creates a Val from any value source. Both derive and combine are implemented using from under the hood.

`ts
import { from } from "value-enhancer";

const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");

const isDarkMode$ = from(
() => prefersDark.matches,
notify => {
prefersDark.addEventListener("change", notify);
return () => prefersDark.removeEventListener("change", notify);
}
);
`

FlattenFrom

flattenFrom creates a Val from any value source like from but also flatten the value if the value is a Val. flatten is implemented using flattenFrom.

Custom Equal

By default, Object.is equality check is used to determine whether a value has changed. You can customize the equality check by passing a equal function.

`js
import { val } from "value-enhancer";

const isSameXYPosition = (p1, p2) => p1.x === p2.x && p1.y === p2.y;
const isSameXYZPosition = (p1, p2) =>
p1.x === p2.x && p1.y === p2.y && p1.z === p2.z;

const xyzPosition$ = val({ x: 0, y: 0, z: 0 }, { equal: isSameXYZPosition });
const xyPosition$ = derive(xyzPosition$, ({ x, y }) => ({ x, y }), {
equal: isSameXYPosition,
});

xyPosition$.set({ x: 0, y: 0, z: 0 }); // nothing happened
`

Synchronous subscription

Subscription is triggered asynchronously on next tick by default. To trigger synchronously, set eager parameter to true.

`js
count$.subscribe(count => console.log(subscribe: ${count}), true);
count$.reaction(count => console.log(reaction: ${count}), true);
`

Or set eager to true when creating the Val.

`js
// subscription of count$ is trigger synchronously by default
const count$ = val(3, { eager: true });

const derived$ = derive(count$, count => count * 3, { eager: true });
`

Reactive Collections

The Reactive Collections are a group of classes that expand on the built-in JavaScript collections, allowing changes to the collections to be observed. See docs for API details.

`ts
import { derive } from "value-enhancer";
import { reactiveList } from "value-enhancer/collections";

const list = reactiveList(["a", "b", "c"]);

const item$ = derive(list.$, list => list[2]); // watch the item at index 2

console.log(item$.value); // "c"

list.set(2, "d");

console.log(item$.value); // "d"
`

`ts
import { val, flatten } from "value-enhancer";
import { reactiveMap } from "value-enhancer/collections";

const map = reactiveMap();
const v = val("someValue");

const item$ = flatten(map.$, map => map.get("someKey")); // watch the item at "someKey"

console.log(item$.value); // undefined

map.set("someKey", v); // set a val, the value inside the val is subscribed and flatten to item$

console.log(item$.value); // "someValue"

v.set("someValue2"); // you can also set a non-val value, which is passed to item$` directly

console.log(item$.value); // "someValue2"
`

Patterns

$3

With this pattern, Writable Val properties are exposed as $$ and ReadonlyVal properties are exposed as $.

Note that they are all Writable Val under the hood. The difference is just the type.

`ts
import { val, type ReadonlyVal, type Val } from "value-enhancer";

interface MyClassVals {
a: number;
b: string;
}

export type MyClass$ = {
[K in keyof MyClassVals]: ReadonlyVal;
};

export type MyClass$$ = {
[K in keyof MyClassVals]: Val;
};

export class MyClass {
public readonly $: MyClass$;
public readonly $$: MyClass$$;

public constructor() {
this.$ = this.$$ = {
a: val(1),
b: val("2"),
};
}
}

const myClass = new MyClass();
console.log(myClass.$.a.value);
myClass.$$.a.set(3);
`

$3

If you want to ensure maximum safety and prevent others from modifying the value accidentally, you can use a real ReadonlyVal.

`ts
import {
readonlyVal,
type ReadonlyVal,
type ValSetValue,
} from "value-enhancer";

interface MyClassVals {
a: number;
b: string;
}

export type MyClass$ = {
[K in keyof MyClassVals]: ReadonlyVal;
};

export type MyClassSet$ = {
[K in keyof MyClassVals]: ValSetValue;
};

export class MyClass {
public readonly $: MyClass$;
public readonly set$: MyClassSet$;

public constructor() {
const [a$, setA] = readonlyVal(1);
const [b$, setB] = readonlyVal("2");
this.$ = { a: a$, b: b$ };
this.set$ = { a: setA, b: setB };
}
}

const myClass = new MyClass();
console.log(myClass.$.a.value);
myClass.set$.a(3);
`

$3

Writing all these ReadonlyVals and setters could be cumbersome. With groupVals you can easily create a group of ReadonlyVals and setters.

`ts
import {
type ReadonlyVal,
type ValSetValue,
type FlattenVal,
readonlyVal,
groupVals,
} from "value-enhancer";

export interface Foo$ {
a: ReadonlyVal;
b: ReadonlyVal;
c: ReadonlyVal;
}

export class Foo {
public readonly $: Foo$;
private readonly set$: { [K in keyof Foo$]: ValSetValue> };

public constructor() {
const [vals, set$] = groupVals({
a: readonlyVal(1),
b: readonlyVal(2),
c: readonlyVal("3"),
});
this.$ = vals;
this.set$ = set$;
}

public myMethod() {
this.set$.a(2);
this.set$.c("4");
}
}

const foo = new Foo();
console.log(foo.$.a.value); // 1

foo.myMethod();
console.log(foo.$.a.value); // 2
`

$3

Sharing vals to other classes directly should be careful. Other classes may dispose the vals and cause unexpected behavior.

To share ReadonlyVals to other classes, use .ref() to create a ref ReadonlyVal. It is just like derive a val without transform. It is simpler hence more efficient.

`ts
import { val, type ReadonlyVal } from "value-enhancer";

interface AProps {
a$: ReadonlyVal;
}

class A {
a$: ReadonlyVal;

constructor(props: AProps) {
this.a$ = props.a$;
}

dispose() {
this.a$.dispose();
}
}

const a$ = val(1);
const a = new A({ a$: a$.ref() });
a.dispose(); // will not affect a$
`

To share writable vals to other classes, use a .ref(true).

It creates a new Val referencing the value of the current Val as source.
All ref Vals share the same value from the source Val.
The act of setting a value on the ref Val is essentially setting the value to the source Val.

The ref Vals can be safely disposed without affecting the source Val and other ref Vals.

`ts
import { val, type Val } from "value-enhancer";

interface AProps {
a$: Val;
}

class A {
a$: Val;

constructor(props: AProps) {
this.a$ = props.a$;
}

dispose() {
this.a$.dispose();
}
}

const a$ = val(1);
const a1 = new A({ a$: a$.ref(true) });
const a2 = new A({ a$: a$.ref(true) });

a2.a$.set(2);

console.log(a$.value); // 2
console.log(a1.a$.value); // 2
console.log(a2.a$.value); // 2

a1.dispose(); // will not affect a$ and a2.a$
``