Documentation

carve

This is where Tilia truly shines. It lets you build a domain-driven, self-contained feature that is easy to test and reuse.

open Tilia

let feature = carve(({ derived }) => { ... fields })

The derived function in the carve argument is like a computed but with the object itself as first parameter.

Example

import { carve, source } from "tilia";

// A pure function for sorting todos, easy to test in isolation.
function list(todos: Todos) {
  const compare = todos.sort === "by date"
    ? (a, b) => a.createdAt.localeCompare(b.createdAt)
    : (a, b) => a.title.localeCompare(b.title);
  return [...todos.data].sort(compare);
}

// A pure function for toggling a todo, also easily testable.
function toggle({ data, repo }: Todos) {
  return (id: string) => {
    const todo = data.find(t => t.id === id);
    if (todo) {
      todo.completed = !todo.completed;
      repo.save(todo)
    } else {
      throw new Error(`Todo ${id} not found`);
    }
  };
}

// Injecting the dependency "repo"
function makeTodos(repo: Repo) {
  // ✨ Carve the todos feature ✨
  return carve({ derived }) => ({
    sort: "by date",
    list: derived(list),
    data: source(repo.fetchTodos, []),
    toggle: derived(toggle),
    repo,
  });
}

open Tilia

// A pure function for sorting todos, easy to test in isolation.
let list = todos =>
  todos->Array.toSorted(switch todos.sort {
    | ByDate => (a, b) => String.compare(a.createdAt, b.createdAt)
    | ByTitle => (a, b) => String.compare(a.title, b.title)
  })

// A pure function for toggling a todo, also easily testable.
let toggle = ({ data, repo }: Todos.t) =>
  switch data->Array.find(t => t.id === id) {
    | None => raise(Not_found)
    | Some(todo) =>
      todo.completed = !todo.completed
      repo.save(todo)
  }

// Injecting the dependency "repo"
let makeTodos = repo =>
  // ✨ Carve the todos feature ✨
  carve(({ derived }) => {
    sort: ByDate,
    list: derived(list),
    data: source(repo.fetchTodos, []),
    toggle: derived(toggle),
  })

💡 Pro tip: Carving is a powerful way to build domain-driven, self-contained features. Extracting logic into pure functions (like list and toggle) makes testing and reuse easy.

Recursive derivation (state machines)

For recursive derivation (such as state machines), use source:

derived((tree) => source(machine, initialValue));

derived(tree => source(machine, initialValue))

This allows you to create dynamic or self-referential state that reacts to changes in other parts of the tree.

Difference from computed

• Use computed for pure derived values that do not depend on the entire object.
• Use derived (via carve) when you need access to the full reactive object for cross-property logic or methods.

Look at todos.ts for an example of using carve to build the todos feature.