Companion objects
For the limits of standalone functions and classes, see TypeScript problems Valof addresses.
Collect related functions in a companion object
Valof collects the constructor and functions under a value with the same name as the type:
type User = Val<"User", { id: string; name: string; nickname?: string }>;
const User = Val.sealer<User>().impl({
displayName(user) {
return user.nickname ?? user.name;
},
// A member calling another member annotates its return type, to avoid an implicit `any`.
formatLabel(user, separator: string): string {
return user.id + separator + User.displayName(user);
},
});
Val.sealer<User>() creates the constructor. .impl({ ... }) adds functions under the User
namespace, where they are the companion’s members, in one call that ends the chain. Every member
takes its Val first, so Valof infers that parameter as User. You only annotate the parameters that
follow it, and the return type where a member references User itself.
The result remains callable and exposes the members:
const user = User({ id: "a", name: "bob" });
User.displayName(user);
User.formatLabel(user, ": ");
Call a member with the value last
Vals are plain data, so their members can’t be chained like methods. Instead, every member can be called with the value last, which is the form a pipeline expects:
User.formatLabel(user, ": "); // "a: bob"
User.formatLabel(": ")(user); // "a: bob"
pipe(user, User.patch({ nickname: "b" }), User.displayName); // "b"
patch, a trait’s members, an enum’s match and [Tag].match can be called either way too. Valof
ships no pipe. Use the one from your favorite library.
A member cannot have an optional, a default or a rest parameter. Pass undefined explicitly where
an argument has no value:
const User = Val.sealer<User>().impl({
greet: (user, greeting: string | undefined) => `${greeting ?? "Hi"}, ${user.name}`,
});
User.greet(User({ id: "a", name: "bob" }), undefined); // "Hi, bob"
Valof checks the parameters that a member’s type shows, not the ones in its implementation. A type annotation can hide a default or a rest parameter. The member then type-checks, but breaks a call with the value last:
const toWire: (user: User, sep: string) => string = (user, sep = "/") => user.id + sep + user.name;
const User = Val.sealer<User>().impl({ toWire });
User.toWire("-")(User({ id: "a", name: "bob" })); // throws: `User.toWire("-")` returned a string
Do not use a default or a rest parameter in the implementation either.
Called with the value last, a generic member loses its type parameters. Each becomes its constraint,
or unknown where none is declared. To keep them, wrap the member in a function that calls it with
the value first:
const User = Val.sealer<User>().impl({
pick: <K extends keyof User>(user: User, key: K) => user[key],
});
const user = User({ name: "bob", age: 30 });
pipe(user, User.pick("age")); // string | number
pipe(user, (u) => User.pick(u, "age")); // number
Patch object values
Without Valof, changing a deeply readonly shop means rebuilding every object on the path:
const changed = {
...shop,
owner: {
...shop.owner,
contact: {
...shop.owner.contact,
email: "e@example.com",
},
},
};
An object-shaped Val gets patch. The same update lists only what changes:
const changed = Shop.patch(shop, {
owner: { contact: { email: "e@example.com" } },
});
A patch expresses three operations:
- Omit a key to leave it unchanged.
- Pass
{ k: undefined }to delete it. - Pass
{ k: value }to set it.
With exactOptionalPropertyTypes, { k: undefined } is accepted only for optional keys. Without
it, TypeScript also accepts it for required keys, and patch deletes them at runtime.
A patch reaches through nested plain objects, but replaces a nested Val, an array or a primitive whole:
Shop.patch(shop, { city: City.patch(shop.city, { name: "Osaka" }) });
Derive a nested Val with its own patch, so its own seal sees the change.
patch copies only the path to what changed. Untouched branches keep their reference identity:
changed.city === shop.city; // true
Shop.patch(shop, {}) === shop; // true
Reference comparisons, such as React dependency arrays, can then skip work when their value did not
change. Primitive and array Vals have no patch, because they have nothing to merge.