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

Traits

For the contract that a trait adds, see TypeScript Problems Valof Addresses.

Declare what Vals share

A trait declares the fields and the functions:

import { Trait, type Self } from "valof";

type Greetable = Trait<
  "Greetable",
  { name: string },
  {
    greet: (self: Self) => string;
    toWire: (self: Self, sep: string) => string;
  }
>;

The second argument is the shape: the fields every implementing Val holds. It follows the same rules as a payload, so a shape no Val could ever hold is an error where it is written.

The third declares the functions. They become members of every companion that implements the trait, and they take the value first.

Self stands for the implementing Val. A member may take it, and may not return it. What returns a Self is a constructor, and a trait has no brand to seal with.

Implement it on a Val

A Val declares its traits in the third argument, and its companion implements them:

const Greetable = Trait.companion<Greetable>().build();

type User = Val<"User", { id: string }, Greetable>;
const User = Val.companion<User>()
  .implTrait(Greetable, () => ({
    greet: (u) => `Hi, ${u.name}`,
    toWire: (u, sep) => `${u.id}${sep}${u.name}`,
  }))
  .build();

User.greet(User.seal({ id: "a", name: "alice" })); // "Hi, alice"

const duck: Greetable = { name: "duck" }; // type error: only a Val declaring Greetable is assignable

Trait.companion<Greetable>().build() creates the trait’s companion, even for a trait that implements nothing itself. implTrait takes it as the first argument, and a function returning the trait’s members as the second.

A trait adds the fields it requires to the payload, so the User payload includes name without listing it. A payload may list one of them again with the same or a narrower type. A conflicting type is a type error.

The unimplemented-trait rule in valof-lint reports a Val that declared a trait and never implemented it.

Give a default implementation

Every Val writing its own greet repeats the same line. A trait can implement a member itself, reading the shape alone, and that becomes the default for every Val that does not replace it:

const Greetable = Trait.companion<Greetable>()
  .impl(() => ({ greet: (g) => `Hi, ${g.name}` }))
  .build();

type User = Val<"User", { id: string; name: string }, Greetable>;
const User = Val.companion<User>()
  .implTrait(Greetable, () => ({
    toWire: (u, sep) => `${u.id}${sep}${u.name}`,
  }))
  .build();

type Admin = Val<"Admin", { name: string; level: number }, Greetable>;
const Admin = Val.companion<Admin>()
  .implTrait(Greetable, () => ({
    toWire: (a, sep) => `admin${sep}${a.name}`,
    greet: (a) => `Sir ${a.name}`,
  }))
  .build();

User.greet(User.seal({ id: "a", name: "alice" })); // "Hi, alice"
Admin.greet(Admin.seal({ name: "root", level: 9 })); // "Sir root"

The function returns the members the trait does not implement, as both Vals return toWire. It may also return a default to replace it, as Admin replaces greet.

Forbid replacing a default with Final

Mark one Final:

type Greetable = Trait<
  "Greetable",
  { name: string },
  {
    greet: (self: Self) => string;
    shout: Final<(self: Self) => string>;
  }
>;

const Greetable = Trait.companion<Greetable>()
  .impl(() => ({
    greet: (g) => `Hi, ${g.name}`, // a Val may replace this one
    shout: (g) => g.name.toUpperCase(), // declared Final: no Val may
  }))
  .build();

type User = Val<"User", { id: string; name: string }, Greetable>;
const User = Val.companion<User>().implTrait(Greetable).build();

The trait implements both, so implTrait needs no second argument. A Val may still return greet from the function to replace it. Returning shout is an error.

The trait’s companion exposes its Final members, but not its defaults. Greetable.shout(user) can be called, and Greetable.greet is a type error, because calling a default through the trait would run it even for a Val that replaced it. Call a default through the Val’s companion, which dispatches.

A default calling a Final member references the trait and annotates its return type:

const Greetable = Trait.companion<Greetable>()
  .impl(() => ({
    shout: (g): string => g.name.toUpperCase(),
    // A member referencing `Greetable` itself annotates its return type, to avoid an implicit `any`.
    greet: (g): string => `Hi, ${Greetable.shout(g)}`,
  }))
  .build();

Implement traits on an enum

An enum implements each trait it declares over the union, with one implTrait per trait. What differs per variant is a match inside the implementation:

type Describable = Trait<"Describable", { id: string }, { describe: (self: Self) => string }>;
const Describable = Trait.companion<Describable>().build();

type Cmd = Enum<"Cmd", { Add: { n: number }; Del: { at: number } }, Describable>;
const Cmd = Enum.companion<Cmd>()
  .implTrait(Describable, () => ({
    describe: (c): string => Cmd.match(c, { Add: (a) => `add ${a.n}`, Del: (d) => `del ${d.at}` }),
  }))
  .build();

Cmd.describe(Cmd.Add.create({ id: "c1", n: 2 })); // "add 2"

A trait’s fields become fields every variant shares. id comes from Describable, and Cmd.Add requires it.

A trait intersected into one variant’s payload applies to that variant alone, and that variant implements it:

type Named = Trait<"Named", { label: string }, { named: (self: Self) => string }>;
const Named = Trait.companion<Named>().build();

type Item = Enum<"Item", { Book: { pages: number } & Named; Pen: { ink: string } }>;
const Item = Enum.companion<Item>()
  .Book.implTrait(Named, () => ({ named: (b) => `${b.label}, ${b.pages} pages` }))
  .build();

Item.Book.named(Item.Book.create({ label: "Dune", pages: 412 })); // "Dune, 412 pages"

Hold values of different types together

dyn pairs a value with one Val’s implementation, so values of different types share an array. The concrete type is gone, and only the trait is left. This is inspired by Rust’s Box<dyn Trait>:

const party: Dyn<Greetable>[] = [
  Greetable.dyn(User, User.seal({ id: "a", name: "alice" })),
  Greetable.dyn(Admin, Admin.seal({ name: "root", level: 9 })),
];

party.map((p) => p.greet()); // ["Hi, alice", "Sir root"]
party.map((p) => p.name); // ["alice", "root"]: a trait field, read from the box

A box already holds the value, so its members take only the arguments after it. The trait’s fields are readable on it, and a function taking Greetable accepts one. The Val’s own fields are not. p.id is a type error, because dyn drops the concrete type.

A box is a proxy over its value, not a Val. It has its own identity, and it has no patch. A payload cannot hold one.

The two arguments belong together. The companion has to match the value’s own type, so another Val’s companion is rejected.

An enum boxes the same way, through its own companion: Describable.dyn(Cmd, Cmd.Add.create({ id: "c1", n: 2 })).

dyn selects the implementation from the companion passed to it. If an enum and its variant both declared a trait, Named.dyn(Item, book) and Named.dyn(Item.Book, book) would call different implementations, so a variant cannot declare a trait that the enum already declares.

A function over boxes is registered on the trait’s companion, with .implAssoc. implTrait does not copy it onto a Val.

Implement several traits

Intersect them in the declaration, and implement each in its own step:

type Weighed = Trait<"Weighed", { kg: number }, { heavy: (self: Self) => boolean }>;
const Weighed = Trait.companion<Weighed>()
  .impl(() => ({ heavy: (w) => w.kg > 10 }))
  .build();

type Crate = Val<"Crate", { name: string; kg: number }, Greetable & Weighed>;
const Crate = Val.companion<Crate>().implTrait(Greetable).implTrait(Weighed).build();

const crate = Crate.seal({ name: "box", kg: 20 });
Greetable.dyn(Crate, crate).greet(); // "Hi, box"
Weighed.dyn(Crate, crate).heavy(); // true

Write &, not |.

Each trait boxes on its own. No two traits on one Val may declare the same member name.