Documentation

How Tilia Builds the Dependency Graph

JavaScript’s Proxy API

Tilia uses JavaScript’s Proxy API to intercept property access on objects. A Proxy is a transparent wrapper that allows defining custom behaviors for fundamental operations (read, write, etc.).

// Simplified Proxy principle
const handler = {
  get(target, property) {
    console.log(`Reading ${property}`);
    return target[property];
  },
  set(target, property, value) {
    console.log(`Writing ${property} = ${value}`);
    target[property] = value;
    return true;
  }
};

const obj = { name: "Alice" };
const proxy = new Proxy(obj, handler);

proxy.name;        // Log: "Reading name"
proxy.name = "Bob"; // Log: "Writing name = Bob"

The tracking mechanism

When you call tilia({...}), the object is wrapped in a Proxy with two essential “traps” (interceptions):

1. The GET trap (read)

When a property is read during the execution of an observation callback, Tilia records this property as a dependency:

// Simplified internal state of Tilia
let currentObserver = null;  // The observer currently executing
const dependencies = new Map();  // Map: observer -> Set of dependencies

const handler = {
  get(target, key) {
    if (currentObserver !== null) {
      // 📝 Recording the dependency
      // "This observer depends on this property"
      addDependency(currentObserver, target, key);
    }
    return target[key];
  },
  // ...
};

2. The SET trap (write)

When a property is modified, Tilia finds all observers that depend on it and notifies them:

const handler = {
  // ...
  set(target, key, value) {
    const oldValue = target[key];
    target[key] = value;
    
    if (oldValue !== value) {
      // 📢 Notification of observers
      // "This property changed, notify all those who depend on it"
      notifyObservers(target, key);
    }
    return true;
  }
};

Dynamic graph

A crucial point: the dependency graph is dynamic. It is rebuilt on each callback execution, which allows handling conditions:

const state = tilia({
  showDetails: false,
  name: "Alice",
  email: "alice@example.com",
});

observe(() => {
  console.log("Name:", state.name);
  
  if (state.showDetails) {
    // 'email' is observed ONLY if showDetails is true
    console.log("Email:", state.email);
  }
});

// Current dependencies: {name, showDetails}

state.email = "new@email.com";  // 😴 No notification (email not observed)

state.showDetails = true;       // ✨ Notification + re-execution
// Now dependencies include: {name, showDetails, email}

state.email = "another@email.com"; // ✨ Notification (email is now observed)

computed

Return a computed value to be inserted in a Tilia object.

The value is computed when the key is read (pull reactivity) and is destroyed (invalidated) when any observed value changes.

import { computed } from "tilia";

const globals = tilia({ now: dayjs() });

setInterval(() => (globals.now = dayjs()), 1000 * 60);

const alice = tilia({
  name: "Alice",
  birthday: dayjs("2015-05-24"),
  // The value 'age' is always up-to-date
  age: computed(() => globals.now.diff(alice.birthday, "year")),
});

open Tilia
open Day

let globals = tilia({ now: now() })
setInterval(() => globals.now = now(), 1000 \* 60)

let alice = tilia({
  name: "Alice",
  birthday: dayjs("2015-05-24"),
  age: 0,
})
alice.age = computed(() => globals.now->diff(alice.birthday, "year"))

Nice, the age updates automatically, Alice can grow older :-)

💡 Pro tip: The computed can be created anywhere but only becomes active inside a Tilia object or array.

Once a value is computed, it behaves exactly like a regular value until it is expired due to a change in the dependencies. This means that there is nearly zero overhead for computed values acting as getters.

Chaining computed values

computed values can depend on other computed values:

const store = tilia({
  items: [
    { price: 100, quantity: 2 },
    { price: 50, quantity: 1 },
  ],
  discount: 0.1,  // 10% discount
  
  subtotal: computed(() => 
    store.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
  ),
  
  discountAmount: computed(() => 
    store.subtotal * store.discount
  ),
  
  total: computed(() => 
    store.subtotal - store.discountAmount
  ),
});

console.log(store.total);  // 225 (250 - 25)

store.discount = 0.2;  // Change discount to 20%
console.log(store.total);  // 200 (250 - 50)

open Tilia

let store = tilia({
  items: [
    {price: 100.0, quantity: 2},
    {price: 50.0, quantity: 1},
  ],
  discount: 0.1,  // 10% discount
  
  subtotal: computed(() => 
    Array.reduce(store.items, 0.0, (sum, item) => sum +. item.price *. Float.fromInt(item.quantity))
  ),
  
  discountAmount: computed(() => 
    store.subtotal *. store.discount
  ),
  
  total: computed(() => 
    store.subtotal -. store.discountAmount
  ),
})

Js.log(store.total)  // 225.0 (250.0 - 25.0)

store.discount = 0.2  // Change discount to 20%
Js.log(store.total)  // 200.0 (250.0 - 50.0)

Internal Architecture

Proxy Handler Structure

Here is a simplified representation of the Proxy handler used by Tilia:

// Simplified for understanding
const createHandler = (context: TiliaContext) => ({
  get(target: object, key: string | symbol, receiver: unknown) {
    // 1. Ignore symbols and internal properties
    if (typeof key === "symbol" || key.startsWith("_")) {
      return Reflect.get(target, key, receiver);
    }
    
    // 2. Record dependency if an observer is active
    if (context.currentObserver !== null) {
      context.addDependency(context.currentObserver, target, key);
    }
    
    // 3. Retrieve the value
    const value = Reflect.get(target, key, receiver);
    
    // 4. If it's an object, wrap it recursively
    if (isObject(value) && !isProxy(value)) {
      return createProxy(value, context);
    }
    
    // 5. If it's a computed, execute it
    if (isComputed(value)) {
      return executeComputed(value, context);
    }
    
    return value;
  },
  
  set(target: object, key: string | symbol, value: unknown, receiver: unknown) {
    const oldValue = Reflect.get(target, key, receiver);
    
    // 1. Perform the modification
    const result = Reflect.set(target, key, value, receiver);
    
    // 2. Notify if the value changed
    if (!Object.is(oldValue, value)) {
      context.notify(target, key);
    }
    
    return result;
  },
  
  deleteProperty(target: object, key: string | symbol) {
    const result = Reflect.deleteProperty(target, key);
    
    // Notify of the deletion
    if (result) {
      context.notify(target, key);
    }
    
    return result;
  },
  
  ownKeys(target: object) {
    // Track iteration over keys
    if (context.currentObserver !== null) {
      context.addDependency(context.currentObserver, target, KEYS_SYMBOL);
    }
    return Reflect.ownKeys(target);
  },
});

Lifecycle of a computed

┌─────────────────────────────────────────────────────────────┐
│                    INITIAL STATE                            │
│  computed created but not yet executed                      │
│  cache = EMPTY, valid = false                               │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (first read)
┌─────────────────────────────────────────────────────────────┐
│                    EXECUTION                                │
│  1. currentObserver = this computed                         │
│  2. Execution of the function                               │
│  3. Dependencies recorded during execution                  │
│  4. cache = result, valid = true                            │
│  5. currentObserver = null                                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (subsequent reads)
┌─────────────────────────────────────────────────────────────┐
│                    CACHE HIT                                │
│  valid = true → return cache directly                       │
│  No recalculation                                           │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (dependency changes)
┌─────────────────────────────────────────────────────────────┐
│                    INVALIDATION                             │
│  1. SET detected on a dependency                            │
│  2. valid = false                                           │
│  3. Notification propagated to observers                    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (next read)
┌─────────────────────────────────────────────────────────────┐
│                    RE-EXECUTION                             │
│  Same process as EXECUTION                                  │
│  Potentially different new dependencies                     │
└─────────────────────────────────────────────────────────────┘

Forest Mode

Tilia supports “Forest Mode” where multiple separate tilia() objects can be observed together:

const alice = tilia({ name: "Alice", age: 10 });
const bob = tilia({ name: "Bob", age: 12 });

// A single observe that depends on TWO trees
observe(() => {
  console.log(`${alice.name} is ${alice.age} years old`);
  console.log(`${bob.name} is ${bob.age} years old`);
});

alice.age = 11;  // ✨ Triggers the observe
bob.age = 13;    // ✨ Also triggers the observe

This is possible thanks to the shared global context that maintains dependencies for all trees.

Mutations in computed: infinite loop risk

The main danger of mutations in a computed is the risk of an infinite loop: if the computed reads the value it modifies, it invalidates itself and loops.

const state = tilia({
  items: [] as number[],
  
  // ❌ DANGER: the computed reads AND modifies 'items'
  count: computed(() => {
    const len = state.items.length;  // Read 'items'
    state.items.push(len);           // Write to 'items' → invalidates the computed!
    return len;                      // → Recalculate → Read → Write → ∞
  }),
});

// Accessing state.count causes an infinite loop!

The problem: The computed observes items, then modifies it, which invalidates it and causes a new calculation, which observes again, modifies again, etc.

Solution: use watch to separate observation and mutation

watch clearly separates:

• The observation phase (first callback): tracked, defines dependencies
• The mutation phase (second callback): without tracking, no loop risk

const state = tilia({
  count: 0,
  history: [] as number[],
});

// ✅ GOOD: watch separates observation and mutation
watch(
  // Observation: tracked
  () => state.count,              
  (count) => {
    // Mutation: no tracking here
    state.history.push(count);    
  }
);

state.count = 1;  // history becomes [1]
state.count = 2;  // history becomes [1, 2]

With watch, the mutation in the second callback is not tracked, so it cannot create a loop even if it reads and modifies the same values.

Garbage Collection

What JavaScript’s native GC manages

JavaScript’s native garbage collector manages very well the release of tracked objects that are no longer used in memory. If a tilia({...}) object is no longer referenced anywhere, JavaScript automatically releases it, along with all its internal dependencies.

You don’t need to do anything for this: it’s JavaScript’s standard behavior.

What Tilia’s GC manages

For each observed property, Tilia maintains a list of watchers. When a watcher is “cleared” (for example, when a React component unmounts), it is removed from the list, but the list itself (even empty) remains attached to the property.

These empty lists represent very little data, but Tilia cleans them up periodically:

import { make } from "tilia";

// GC threshold configuration
const ctx = make({
  gc: 100,  // Triggers cleanup after 100 watchers cleared
});

// The default threshold is 50

When cleanup triggers

1. A watcher is “cleared” (component unmounted, etc.)
2. The clearedWatchers counter increments
3. If clearedWatchers >= gc, cleanup of the watcher list
4. clearedWatchers resets to 0

Configuration based on application

// Application with many dynamic components (lists, tabs, modals)
const ctx = make({ gc: 200 });

// More stable application with few mount/unmounts
const ctx = make({ gc: 30 });

In practice, the default threshold (50) suits most applications.