A TypeScript builder's `.set()` is declared to return `Builder<T & Record<K, V>>`, but at runtime it hands back the same object. What does that force the implementation to do, and what should you watch for?

## Why an assertion is unavoidable An accumulating builder declares each chaining method to return a different instantiation of the builder type: ```ts interface Builder<T> { set<K extends string, V>(key: K, value: V): Builder<T & Record<K, V>>; build(): T; } ``` At runtime there is only one object (or a fresh copy of one), and it is the same class either way. But in the type layer, `Builder<T>` and `Builder<T & Record<K, V>>` are two different types, and a value cannot re-declare its own type parameter mid-life. `return this` fails to check for exactly that reason, and there is no sound conversion the compiler could invent: the object genuinely does not yet have the property the new type promises — the *next* line of the method is what puts it there. So the pattern requires an assertion. That is not a defect in your code; it is the seam where a compile-time story about a chain meets a runtime object that just carries a bag of values. ## Put the seam in exactly one place The bad version sprinkles `as` through every chaining method, so each one is separately capable of lying. The good version keeps the implementation deliberately untyped inside and asserts once, at the factory that hands the builder to callers: ```ts interface Builder<T> { set<K extends string, V>(key: K, value: V): Builder<T & Record<K, V>>; build(): T; } class BuilderImpl { constructor(private readonly parts: Record<string, unknown> = {}) {} set(key: string, value: unknown): BuilderImpl { return new BuilderImpl({ ...this.parts, [key]: value }); } build(): Record<string, unknown> { return this.parts; } } export const builder = (): Builder<{}> => new BuilderImpl() as unknown as Builder<{}>; ``` The class knows nothing about accumulation — it copies a record and returns a new instance. The public type knows everything about accumulation and nothing about the class. One conversion joins them, and because `BuilderImpl` and `Builder<{}>` are not comparable in either direction (the private field alone makes the class nominal), the conversion has to route through `unknown`, which is a useful signal rather than a nuisance: it marks the line as the unchecked one. ## The assertion is unverified — treat it as such An assertion performs no check and emits no code. If the declared interface says `build(): T` while the implementation forgets to store a value, no caller finds out from the compiler; they get `undefined` typed as `string`. Two habits keep the seam honest. First, cover the *types* with type-level tests: write a file of chains that must compile, plus chains that must not, marked with `@ts-expect-error` so the build fails if the error ever stops appearing. Second, cover the *values* with an ordinary unit test that builds an object and asserts its contents. The type test protects the interface, the unit test protects the class, and the assertion in between is only as trustworthy as both. ## Erasure: the gate is a source-code promise If you extend the interface so `build()` is only available once required keys are present, you have added a compile-time gate over statically written chains. Nothing survives to runtime — the type arguments are erased, there is no reflection over them, and a caller reaching the builder from untyped JavaScript, from `JSON.parse` output, or through `any` can call `build()` on an empty builder. A public builder should therefore still check its own invariants in `build()` and throw a clear error. The type layer removes the mistake from code the compiler sees; it does not remove it from the process. ## Mutation is a design decision, not an afterthought Because the chain reads as functional, callers assume each call yields an independent builder. If your `set` mutates and returns `this`, that assumption is false: ```ts const base = builder().set("host", "localhost"); const a = base.set("port", 80); const b = base.set("port", 443); // with a mutating impl, a and b are the same object: both see 443 ``` The types say `a` and `b` have different accumulated shapes; the runtime says they are one object. Copy-on-write — construct a new instance from a spread of the previous parts, as in the example above — makes the runtime match the types, at the cost of one small object per call, which is almost always the right trade for a configuration builder. If you deliberately keep it mutating for performance, say so in the API docs and do not present branched chains as supported.