Documentation

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                                              |
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (first read)
┌─────────────────────────────────────────────────────────────┐
│                    EXECUTION                                │
│  1. currentObserver = this computed                         │
│  2. Execution of the function                               │
│  3. Dependencies recorded during execution                  │
│  4. cache = result                                          |
│  5. currentObserver = previous observer                     |
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (subsequent reads)
┌─────────────────────────────────────────────────────────────┐
│                    CACHE HIT                                │
│  cache exists → return cache directly                       │
│  No recalculation                                           │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (dependency changes)
┌─────────────────────────────────────────────────────────────┐
│                    INVALIDATION                             │
│  1. SET detected on a dependency                            │
│  2. if observed : value recomputed                          |
│  3. value changed ? → notification propagated to observers  |
│  4. not observed : cache reset                              |
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (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: [],
  
  // ❌ DANGER: the computed reads AND modifies 'items'
  count: computed(() => {
    // Read 'items'
    const len = state.items.length;
    // Write to 'items' → invalidates the computed!
    state.items.push(len);           
    // → Recalculate → Read → Write → ∞
    return len;                      
  }),
});

// Accessing state.count causes an infinite loop!

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

// 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]

let state = tilia({
  count: 0,
  history: [],
});

// ✅ 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.