Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Patterns

Framework state

A value is a plain object, so a state container holds it as it stands. Replace it whole. The untouched subtrees keep their identity, so a dependency array detects no change.

const [shop, setShop] = useState(Shop.seal({ owner, city }));
setShop(Shop.patch(shop, { owner: { email: "e@example.com" } }));

useEffect(() => showMap(shop.city), [shop.city]); // the patch did not touch `city`: no re-run

Solid reads the same with createSignal, and takes the comparison directly: createSignal(user, { equals }).

Svelte and Vue are deeply reactive by default, so ask for a shallow container. A deep one gives your code a proxy in place of the value. patch rebuilds a changed value and its parents, and keeps the untouched branches by reference. Given a proxy, it copies those branches as well.

Values are frozen in development, so Vue skips them and ref behaves like shallowRef until you build for production. A write through Vue’s ref or Solid’s createStore then mutates the value instead of throwing.

framework
ReactuseState
SolidcreateSignal, not createStore
Svelte 5$state.raw, not $state
VueshallowRef, not ref

Return payloads across serialization boundaries

Return the payload, not the value. A generated client derives its response type from the handler, so a Val there arrives on the other side already typed as one, without having passed through the seal.

app.get("/user/:id", (c) => {
  const body: PayloadOf<User> = user; // the brand drops, the object is the same one
  return c.json(body);
});

Now the other side cannot use what arrives until it seals it:

const plain = await res.json(); // the generated client types this as PayloadOf<User>
const bad: User = plain; // type error: the brand is missing
const user = User.seal(plain); // sealed, and now it is one

PayloadOf<V> removes the brand from the type, not from the value, so it costs nothing at run time. A Val whose payload contains an array cannot be assigned to its PayloadOf. The value’s array is readonly, while PayloadOf keeps the mutable array the type declares. Return the copy that Val.unwrap makes instead:

type Post = Val<"Post", { title: string; tags: string[] }>;

const body: PayloadOf<Post> = post; // type error: tags is readonly
const copy: PayloadOf<Post> = Val.unwrap(post);

PayloadOf and Val.unwrap both remove the brand of a nested Val.

Persistence helpers can create the same hole. Jotai’s atomWithStorage, for example, parses stored JSON and returns it as the type inferred from its initial value. Store a PayloadOf<User>, then seal it after reading.

Seal at the boundary, because the two sides deploy separately. The value was sealed by whichever build the server is running, and that seal may be older than yours.

Map / Set

Use an object’s properties.

type Tags = Val<"Tags", Record<string, true>>; // a Set
type PriceTable = Val<"PriceTable", Record<string, Money>>; // a Map

Use true rather than null for a set, so if (tags[key]) is the membership test. equals ignores key order, so comparing two of them is set equality.

patch sets the entries it lists, and removes an entry set to undefined. Call seal to rebuild the whole table.

PriceTable.patch(table, { apple: Money.seal({ amount: 120, currency: "JPY" }), fig: undefined });

PriceTable.seal(Object.fromEntries(Object.entries(table).filter(([, m]) => m.amount < 500)));

Dates

export type UnixEpochMs = Val<"UnixEpochMs", number>;

export const UnixEpochMs = Val.companion<UnixEpochMs>()
  .impl(() => ({
    showLocal(d) {
      return Temporal.Instant.fromEpochMilliseconds(d).toLocaleString();
    },
  }))
  .build();

Large integers

Keep an integer outside the safe range of number as a decimal string, since JSON.stringify throws on a bigint. Compare and compute through BigInt() in members, because "10" < "9".

type BigInteger = Val<"BigInteger", string>;

const BigInteger = Val.companion<BigInteger>()
  .implSeal((n: string | bigint, seal) => {
    const s = String(n);
    // One string per integer, for `equals`.
    // `BigInt("010")` is 10n, so only the pattern rejects "010".
    if (!/^(0|-?[1-9]\d*)$/.test(s)) throw new RangeError(`not an integer: ${s}`);
    return seal(s);
  })
  .impl(() => ({
    add(a, b: BigInteger): BigInteger {
      return BigInteger.seal(BigInt(a) + BigInt(b));
    },
    compare(a, b: BigInteger): -1 | 0 | 1 {
      const x = BigInt(a);
      const y = BigInt(b);
      return x < y ? -1 : x > y ? 1 : 0;
    },
  }))
  .build();

BigInteger.add(BigInteger.seal(1n), BigInteger.seal("9007199254740993"));