4. Compose services#

Goal: understand yield* — the one idea the whole library is built on.

This is the step that makes everything else obvious. Take your time here.

This example gives TaskList a fresh context inside each TaskStats call. For state owned by a component or route, use toProvide as in step 3 so repeated reads resolve the same configured instance.

The problem yield* solves#

Dependencies are easy to hide when a service reaches into a runtime container. Craft makes each dependency visible in the type by yielding it:

export const { TaskList } = craftService(
  { name: 'TaskList', providedIn: 'function' },
  function* () {
    const api = yield* TaskApi(); // ← tracked

    // Exposed as `tasks`: a service's API is what it yields.
    yield* state('tasks', [] as Task[], /* … */);
  },
);

Now TaskList's type carries TaskApi as a dependency. Everything downstream — the DI check on routes, the testing register, the dependency snapshot — reads that type.

Why a generator?#

A generator is just a function that can hand control back to its caller at each yield. Craft uses it as a collection channel: each yield* reports "I need this" to the runtime driving the factory, which resolves it and folds it into the graph.

You don't manage that channel yourself. In practice the whole rule is:

Every named entity yields what it does not own. A factory, a computed, a method — each one records its dependencies with yield*.

const api = yield* TaskApi(); // a service
const tasks = yield* state('tasks', []); // a primitive

Composing two services#

const { TaskApi } = craftService(
  { name: 'TaskApi', providedIn: 'global' },
  function* () {
    // raw fetch, only to keep this example about composition —
    // see the note below
    yield* craftExpose('fetchAll', () =>
      fetch('/api/tasks').then((r) => r.json()),
    );
  },
);

const { TaskList } = craftService(
  { name: 'TaskList', providedIn: 'function' },
  function* () {
    const api = yield* TaskApi();
    yield* state('tasks', [] as Task[], ({ set }) => ({
      // For this demo only; we'll later see why this belongs in a mutation instead.
      load: function* () {
        return yield* set(yield* api.fetchAll());
      },
    }));
  },
);

const { TaskStats } = craftService(
  { name: 'TaskStats', providedIn: 'function' },
  function* () {
    const { tasks } = yield* TaskList();
    yield* craftComputed('done', function* () {
      return (yield* tasks()).filter((t) => t.done).length;
    });
  },
);

A service's factory is always a generator: its API is what it yields. A named primitive is exposed under its name; anything else — like fetchAll — is exposed with craftExpose(name, value).

TaskStats does not own TaskList. The computed yields tasks so that read is recorded on done, not silently closed over from the factory.

Taking only what you need#

TaskStats only reads the array. Say so, and the graph records only that:

const { TaskStats } = craftService(
  { name: 'TaskStats', providedIn: 'function' },
  function* () {
    const fetchAll = yield* TaskApi.fetchAll(); // one property
    // …
  },
);

A test for TaskStats then has to mock fetchAll and nothing else.

What you gained#

The mental model: declare with a name, drive with yield*, derive the rest. Every remaining step is a variation on it — query yields, mutation yields, guards yield, route providers yield.