Immutability
Readonly<T> only protects the top-level properties. It also cannot prevent a value from changing
through the original reference:
type Profile = Readonly<{
name: string;
address: { city: string };
}>;
const raw = { name: "alice", address: { city: "Osaka" } };
const profile: Profile = raw;
profile.name = "mallory"; // type error: the top-level property is readonly
profile.address.city = "Tokyo"; // allowed: Readonly is shallow
raw.name = "mallory"; // allowed: raw is still writable
A recursive readonly type prevents the nested write, but the original reference remains writable. Keeping a value unchanged requires both deep readonly types and a copy at construction.
Vals are immutable
Vals are immutable. Their types are deeply readonly, and their constructors deep-copy their inputs. The copy skips anything already inside a Val, such as a nested Val or a branch taken from an existing Val:
type Profile = Val<"Profile", { name: string; address: { city: string } }>;
const Profile = Val.companion<Profile>().build();
const raw = { name: "alice", address: { city: "Osaka" } };
const profile = Profile.seal(raw);
profile.address.city = "Tokyo"; // type error: Vals are deeply readonly
raw.address.city = "Tokyo";
profile.address.city; // "Osaka"
const renamed = Profile.seal({ ...profile, name: "bob" });
renamed.address === profile.address; // true: not copied again
Val makes the payload deeply readonly:
type Post = Val<"Post", { tags: string[] }>;
declare const post: Post;
post.tags.push("typescript"); // type error: tags is readonly
readonly exists only in the type system. In development, Valof also freezes values, so a write
that uses a cast to bypass the type throws where it happens. Production builds skip the freeze. Some
generic object utilities, such as Object.assign, write to a Val without a cast. See
Caveats.
Only primitives, arrays and plain objects can live inside a Val. See Allowed Types.
Avoid a copy with .nocopy
.nocopy uses the payload as the value, without copying it. The default copy already skips anything
inside a Val, so use .nocopy only where profiling shows the copy is a bottleneck.
Warning
.nocopyis an explicit escape hatch. You must ensure the value and everything inside it is stable plain data with no mutable aliases. If that is wrong, another reference can change a Val in production. Prefer the default copy whenever there is doubt.
Only when you can make that guarantee, use .nocopy:
import { Val } from "valof";
type Profile = Val<"Profile", { name: string; address: { city: string } }>;
const Profile = Val.companion<Profile>().build();
const seed = { name: "alice", address: { city: "Osaka" } } as const;
const profile = Profile.seal.nocopy(seed);
The common trap is a mutable alias behind a readonly view:
const mutable = { name: "alice", address: { city: "Osaka" } };
const seed: SeedOf<Profile> = mutable; // TypeScript permits this readonly view.
const profile = Profile.seal.nocopy(seed);
// In production, this also changes `profile.address.city`.
// Development freezing normally makes this assignment throw instead.
mutable.address.city = "Tokyo";
readonly is only a guardrail. Mutable views, casts, accessors and proxies can still break this
contract. The default seal’s nocopy requires deeply readonly input. Val.of.nocopy<V> and custom
seals leave the responsibility to their callers and implementations. Development validates and
freezes the payload, and production trusts the contract. patch still copies.