@derivesome/core

@derivesome/core

A lightweight reactive state management library with automatic dependency tracking.

Table of Contents

• Core Concepts
• ref
• derived
• effect
• Observable / observe
• PubSub
• ArrayProxy
• Utilities
  • findRefs
  • match
  • diff / patch
  • Stack

Core Concepts

Reactivity is built on automatic dependency tracking. When a ref.get() is called inside an effect or derived, that ref registers the running effect as a subscriber. When the ref's value changes, all subscribed effects re-run automatically. This means you never manually declare dependencies — the system infers them at runtime.

ref

ref(value) creates a reactive reference holding a single value.

import { ref } from '@derivesome/core';

const count = ref(0);

count.get();     // read and subscribe (inside an effect/derived)
count.peek();    // read without subscribing
count.set(1);    // update value — notifies subscribers only if value changed
count.set(n => n + 1); // functional update

Values are compared with strict equality (===). If the new value is the same as the previous one, no notification is sent.

ref also supports dispose() to remove all subscribers and effects:

count.dispose(); // tears down all subscriptions

isReference

import { isReference } from '@derivesome/core';

isReference(count); // true
isReference(42);    // false

derived

derived(fn) creates a computed value that re-evaluates automatically when its reactive dependencies change. It is itself a Reference, so it can be used anywhere a ref can.

import { ref, derived } from '@derivesome/core';

const count = ref(0);
const doubled = derived(() => count.get() * 2);
const label = derived(() => `Count is: ${doubled.get()}`);

doubled.peek(); // 0
count.set(5);
doubled.peek(); // 10
label.peek();   // "Count is: 10"

Dependencies are tracked dynamically per evaluation. If a branch is not taken, its refs are not subscribed:

const enabled = ref(false);
const value = ref(42);

const result = derived(() => {
  if (!enabled.get()) return -1;
  return value.get() * 2; // only subscribed when enabled is true
});

isDerived

import { isDerived } from '@derivesome/core';

isDerived(doubled); // true
isDerived(count);   // false

effect

effect(fn) runs a function immediately and re-runs it whenever any ref.get() called inside it changes.

import { ref, effect } from '@derivesome/core';

const name = ref('Alice');

effect(() => {
  console.log('Hello,', name.get());
});
// logs: "Hello, Alice"

name.set('Bob');
// logs: "Hello, Bob"

Effects are the primary way to cause side effects in response to reactive state changes. Unlike derived, they don't return a value.

Observable / observe

Every ref implements the Observable interface, which provides observe — a way to subscribe to value changes outside of the effect/derived system.

import { ref } from '@derivesome/core';

const count = ref(0);

const unsubscribe = count.observe((value) => {
  console.log('count changed to', value);
});

count.set(1); // logs: "count changed to 1"

unsubscribe(); // stop listening

count.set(2); // nothing logged

observe accepts an optional options object:

count.observe(
  (value) => console.log(value),
  {
    immediate: true,  // call the callback immediately with the current value
    cleanup: () => {  // called when the subscription is removed
      console.log('cleaned up');
    },
  }
);

isObservable

import { isObservable } from '@derivesome/core';

isObservable(count); // true

PubSub

pubsub() is the low-level primitive underlying ref. It provides a typed publish/subscribe channel with no built-in value storage.

import { pubsub } from '@derivesome/core';

const ps = pubsub<number>();

const unsub = ps.subscribe((value) => {
  console.log('received', value);
});

ps.publish(42); // logs: "received 42"

unsub(); // unsubscribe

ps.publish(99); // nothing logged

ps.dispose(); // remove all subscribers and effects

addEffect registers a function that participates in the reactive context system (re-runs through Context.runEffect):

ps.addEffect(() => {
  // re-run as a tracked effect when published
});

ArrayProxy

ArrayProxy<T> extends the native Array and emits a typed mutation event whenever the array is modified. Useful for building reactive list state.

import { ArrayProxy } from '@derivesome/core';

const items = new ArrayProxy('a', 'b', 'c');

const unsub = items.subscribe((mutation) => {
  console.log(mutation);
});

items.push('d');
// { type: 'push', items: ['d'] }

items.pop();
// { type: 'pop', removed: 'd' }

items.splice(0, 1, 'z');
// { type: 'splice', start: 0, deleteCount: 1, removed: ['a'], added: ['z'] }

items.set(0, 'x');
// { type: 'set', index: 0, value: 'x' }

items.sort();
// { type: 'sort' }

items.reverse();
// { type: 'reverse' }

items.dispose(); // remove all subscribers

Mutation types

Method	Mutation type	Extra fields
push	push	items: T[]
pop	pop	removed: T | undefined
shift	shift	removed: T | undefined
unshift	unshift	items: T[]
splice	splice	start, deleteCount, removed, added
sort	sort	—
reverse	reverse	—
fill	fill	value, start, end
copyWithin	copyWithin	target, start, end
.set(i, v)	set	index, value

Utilities

findRefs

Recursively walks any value (object, array, or primitive) and returns all Reference instances found within it.

import { ref, findRefs } from '@derivesome/core';

const a = ref(1);
const b = ref(2);

findRefs({ a, b, nested: { c: ref(3) } });
// [Reference<1>, Reference<2>, Reference<3>]

findRefs([a, b]);
// [Reference<1>, Reference<2>]

findRefs(42); // []

match

match(input, pattern) is a structural pattern matching utility. It checks whether input structurally matches pattern, working as a type guard.

import { match } from '@derivesome/core';

// Primitive matching
match('hello', 'hello'); // true
match(42, 42);           // true
match(42, 99);           // false

// Object structural matching (partial — only pattern keys are checked)
const user = { role: 'admin', name: 'Alice' };
match(user, { role: 'admin' }); // true — narrows type
match(user, { role: 'guest' }); // false

// Array matching (positional)
match([1, 2, 3], [1, 2]); // true (pattern checked index-by-index)

// Type narrowing
type Shape =
  | { kind: 'circle'; radius: number }
  | { kind: 'square'; side: number };

function area(shape: Shape): number {
  if (match(shape, { kind: 'circle' as const })) {
    return Math.PI * shape.radius ** 2; // shape is narrowed to circle
  }
  return shape.side ** 2;
}

diff / patch

diff(a, b) computes a list of structural differences between two values. patch(target, diffs) applies those diffs to produce a new value.

import { diff, patch } from '@derivesome/core';

const a = { x: 1, y: 2 };
const b = { x: 1, y: 3, z: 4 };

const diffs = diff(a, b);
// [
//   { type: 'changed', path: ['y'], oldValue: 2, newValue: 3 },
//   { type: 'added',   path: ['z'], newValue: 4 },
// ]

const result = patch({ ...a }, diffs);
// { x: 1, y: 3, z: 4 }

Works recursively on nested objects and arrays:

diff([1, 2, 3], [1, 2, 3, 4]);
// [{ type: 'added', path: [3], newValue: 4 }]

diff({ a: { b: 1 } }, { a: { b: 2 } });
// [{ type: 'changed', path: ['a', 'b'], oldValue: 1, newValue: 2 }]

Stack

A simple typed stack used internally by the context system. Exported for external use.

import { Stack } from '@derivesome/core';

const stack = new Stack([1, 2, 3]);

stack.current; // 3 (top of stack)
stack.push(4);
stack.current; // 4
stack.pop();   // 4
stack.current; // 3