Documentation Tilia

Comment Tilia Construit le Graphe de Dépendances

L’API Proxy de JavaScript

Tilia utilise l’API Proxy de JavaScript pour intercepter les accès aux propriétés des objets. Un Proxy est un wrapper transparent qui permet de définir des comportements personnalisés pour les opérations fondamentales (lecture, écriture, etc.).

// Principe simplifié du Proxy
const handler = {
  get(target, property) {
    console.log(`Lecture de ${property}`);
    return target[property];
  },
  set(target, property, value) {
    console.log(`Écriture de ${property} = ${value}`);
    target[property] = value;
    return true;
  }
};

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

proxy.name;        // Log: "Lecture de name"
proxy.name = "Bob"; // Log: "Écriture de name = Bob"

Le mécanisme de tracking

Quand vous appelez tilia({...}), l’objet est enveloppé dans un Proxy avec deux “traps” (interceptions) essentielles :

1. Le trap GET (lecture)

Quand une propriété est lue pendant l’exécution d’un callback d’observation, Tilia enregistre cette propriété comme dépendance :

// État interne simplifié de Tilia
let currentObserver = null;  // L'observateur en cours d'exécution
const dependencies = new Map();  // Map: observer -> Set de dépendances

const handler = {
  get(target, key) {
    if (currentObserver !== null) {
      // 📝 Enregistrement de la dépendance
      // "Cet observateur dépend de cette propriété"
      addDependency(currentObserver, target, key);
    }
    return target[key];
  },
  // ...
};

2. Le trap SET (écriture)

Quand une propriété est modifiée, Tilia trouve tous les observateurs qui en dépendent et les notifie :

const handler = {
  // ...
  set(target, key, value) {
    const oldValue = target[key];
    target[key] = value;
    
    if (oldValue !== value) {
      // 📢 Notification des observateurs
      // "Cette propriété a changé, prévenez tous ceux qui en dépendent"
      notifyObservers(target, key);
    }
    return true;
  }
};

Graphe dynamique

Un point crucial : le graphe de dépendances est dynamique. Il est reconstruit à chaque exécution du callback, ce qui permet de gérer des conditions :

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

observe(() => {
  console.log("Nom:", state.name);
  
  if (state.showDetails) {
    // 'email' n'est observé QUE si showDetails est true
    console.log("Email:", state.email);
  }
});

// Dépendances actuelles: {name, showDetails}

state.email = "new@email.com";  // 😴 Pas de notification (email non observé)

state.showDetails = true;       // ✨ Notification + ré-exécution
// Maintenant les dépendances incluent: {name, showDetails, email}

state.email = "another@email.com"; // ✨ Notification (email est maintenant observé)

computed

Retourne une valeur calculée à insérer dans un objet Tilia.

La valeur est calculée quand la clé est lue (pull réactivité) et est détruite (invalidée) quand une valeur observée change.

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"),
  // La valeur 'age' est toujours à jour
  age: computed(() => globals.now.diff(alice.birthday, "year")),
});

💡 Pro tip: Le computed peut être créé n’importe où mais ne devient actif qu’une fois inséré dans un objet Tilia.

Une fois qu’une valeur est calculée, elle se comporte exactement comme une valeur régulière jusqu’à ce qu’elle expire en raison d’un changement dans les dépendances. Cela signifie qu’il y a presque zéro overhead pour les valeurs calculées agissant comme des getters.

Chaînage de computed

Les valeurs computed peuvent dépendre d’autres valeurs computed :

const store = tilia({
  items: [
    { price: 100, quantity: 2 },
    { price: 50, quantity: 1 },
  ],
  discount: 0.1,  // 10% de réduction
  
  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 la réduction à 20%
console.log(store.total);  // 200 (250 - 50)

Architecture Interne

Structure du Proxy Handler

Voici une représentation simplifiée du handler Proxy utilisé par Tilia :

// Simplifié pour la compréhension
const createHandler = (context: TiliaContext) => ({
  get(target: object, key: string | symbol, receiver: unknown) {
    // 1. Ignorer les symboles et propriétés internes
    if (typeof key === "symbol" || key.startsWith("_")) {
      return Reflect.get(target, key, receiver);
    }
    
    // 2. Enregistrer la dépendance si un observer est actif
    if (context.currentObserver !== null) {
      context.addDependency(context.currentObserver, target, key);
    }
    
    // 3. Récupérer la valeur
    const value = Reflect.get(target, key, receiver);
    
    // 4. Si c'est un objet, le wrapper récursivement
    if (isObject(value) && !isProxy(value)) {
      return createProxy(value, context);
    }
    
    // 5. Si c'est un computed, l'exécuter
    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. Effectuer la modification
    const result = Reflect.set(target, key, value, receiver);
    
    // 2. Notifier si la valeur a changé
    if (!Object.is(oldValue, value)) {
      context.notify(target, key);
    }
    
    return result;
  },
  
  deleteProperty(target: object, key: string | symbol) {
    const result = Reflect.deleteProperty(target, key);
    
    // Notifier de la suppression
    if (result) {
      context.notify(target, key);
    }
    
    return result;
  },
  
  ownKeys(target: object) {
    // Tracker l'itération sur les clés
    if (context.currentObserver !== null) {
      context.addDependency(context.currentObserver, target, KEYS_SYMBOL);
    }
    return Reflect.ownKeys(target);
  },
});

Cycle de vie d’un computed

┌─────────────────────────────────────────────────────────────┐
│                    ÉTAT INITIAL                              │
│  computed créé mais pas encore exécuté                       │
│  cache = EMPTY, valid = false                                │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (première lecture)
┌─────────────────────────────────────────────────────────────┐
│                    EXÉCUTION                                 │
│  1. currentObserver = ce computed                            │
│  2. Exécution de la fonction                                 │
│  3. Dépendances enregistrées pendant l'exécution            │
│  4. cache = résultat, valid = true                          │
│  5. currentObserver = null                                   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (lectures suivantes)
┌─────────────────────────────────────────────────────────────┐
│                    CACHE HIT                                 │
│  valid = true → retourne cache directement                  │
│  Aucun recalcul                                              │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (dépendance change)
┌─────────────────────────────────────────────────────────────┐
│                    INVALIDATION                              │
│  1. SET détecté sur une dépendance                          │
│  2. valid = false                                            │
│  3. Notification propagée aux observateurs                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼ (prochaine lecture)
┌─────────────────────────────────────────────────────────────┐
│                    RE-EXÉCUTION                              │
│  Même processus que EXÉCUTION                                │
│  Nouvelles dépendances potentiellement différentes          │
└─────────────────────────────────────────────────────────────┘

Forest Mode

Tilia supporte le “Forest Mode” où plusieurs objets tilia() séparés peuvent être observés ensemble :

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

// Un seul observe qui dépend de DEUX arbres
observe(() => {
  console.log(`${alice.name} a ${alice.age} ans`);
  console.log(`${bob.name} a ${bob.age} ans`);
});

alice.age = 11;  // ✨ Déclenche l'observe
bob.age = 13;    // ✨ Déclenche aussi l'observe

Ce fonctionnement est possible grâce au contexte global partagé qui maintient les dépendances de tous les arbres.

Mutations dans computed : risque de boucle infinie

Le principal danger des mutations dans un computed est le risque de boucle infinie : si le computed lit la valeur qu’il modifie, il s’invalide lui-même et tourne en boucle.

const state = tilia({
  items: [] as number[],
  
  // ❌ DANGER : le computed lit ET modifie 'items'
  count: computed(() => {
    const len = state.items.length;  // Lecture de 'items'
    state.items.push(len);           // Écriture dans 'items' → invalide le computed !
    return len;                      // → Recalcul → Lecture → Écriture → ∞
  }),
});

// Accéder à state.count provoque une boucle infinie !

Le problème : Le computed observe items, puis le modifie, ce qui l’invalide et provoque un nouveau calcul, qui observe à nouveau, modifie à nouveau, etc.

Solution : utiliser watch pour séparer observation et mutation

watch sépare clairement :

• La phase d’observation (premier callback) : trackée, définit les dépendances
• La phase de mutation (second callback) : sans tracking, pas de risque de boucle

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

// ✅ BON : watch sépare observation et mutation
watch(
  () => state.count,              // Observation : trackée
  (count) => {
    state.history.push(count);    // Mutation : pas de tracking ici
  }
);

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

Avec watch, la mutation dans le second callback n’est pas trackée, donc elle ne peut pas créer de boucle même si elle lit et modifie les mêmes valeurs.

Garbage Collection

Ce que gère le GC natif de JavaScript

Le garbage collector natif de JavaScript gère très bien la libération des objets trackés qui ne sont plus utilisés en mémoire. Si un objet tilia({...}) n’est plus référencé nulle part, JavaScript le libère automatiquement, ainsi que toutes ses dépendances internes.

Vous n’avez rien à faire pour cela : c’est le comportement standard de JavaScript.

Ce que gère le GC de Tilia

Pour chaque propriété observée, Tilia maintient une liste de watchers. Quand un watcher est “cleared” (par exemple, quand un composant React se démonte), il est retiré de la liste, mais la liste elle-même (même vide) reste attachée à la propriété.

Ces listes vides représentent très peu de données, mais Tilia les nettoie périodiquement :

import { make } from "tilia";

// Configuration du seuil GC
const ctx = make({
  gc: 100,  // Déclenche le nettoyage après 100 watchers cleared
});

// Le seuil par défaut est 50

Quand le nettoyage se déclenche

1. Un watcher est “cleared” (composant démonté, etc.)
2. Le compteur clearedWatchers s’incrémente
3. Si clearedWatchers >= gc, nettoyage de la liste des watchers
4. clearedWatchers reset à 0

Configuration selon l’application

// Application avec beaucoup de composants dynamiques (listes, onglets, modales)
const ctx = make({ gc: 200 });

// Application plus stable avec peu de montages/démontages
const ctx = make({ gc: 30 });

En pratique, le seuil par défaut (50) convient à la plupart des applications.