Each position is narrowed to its specific block type, with full autocomplete for that block's fields. Swapping the order or adding extra blocks is a type error.
Configuring a plugin system
Lock down which hooks and transports a config accepts:
Refine<Base, Constraint> maps over the keys of Base and applies Constraint per-field:
Unmentioned fields pass through unchanged
Literal narrowing — Refine<{ a: string }, { a: 'hello' }> narrows a to 'hello'
Nested refinement — object fields are refined per-key, preserving base fields not in the constraint
Union narrowing — discriminated unions are narrowed by matching members
Record key preservation — Record<string, ...> constraints refine values while keeping the original keys
Array refinement — Array<T> constraints refine all elements; tuple constraints enforce position and length
Function narrowing — refine parameter types and return types
Optionality control — ? on a constraint key makes it optional; no ? makes it required
Conformance by default — every constraint value must be a narrowing of the matching base field; supplying an unrelated type is a compile error
Loose<T> / Override<T> escape hatches — wrap any value, at any nesting depth, to skip the conformance check: Loose<T> merges with the base (siblings preserved, new keys added), Override<T> replaces the node outright
Conformance, Loose & Override
By default a constraint may only narrow the base — each value you supply must be assignable to the corresponding base field. This catches typos and accidental replacements:
type Config = { retries: number; hooks: Array<() => void> };// ❌ error — `string` is not a narrowing of `number`type Bad = Refine<Config, { retries: string }>;// ✅ ok — `3` is a narrowing of `number`type Good = Refine<Config, { retries: 3 }>;
To bypass the conformance check, wrap a value — at any nesting depth — in one of two escape hatches:
wrapper
conformance
object result
siblings
can add new keys
(default)
enforced — narrow only
merge
kept
no
Loose<T>
skipped
merge (T applied as a refinement)
kept
yes
Override<T>
skipped
replace with exactly T
dropped
yes
// Loose — replace `hooks` but keep merging; `retries` is preserved:type L = Refine<Config, Loose<{ hooks: string[] }>>;// → { retries: number; hooks: string[] }// Loose narrows shared keys, preserves siblings, AND adds new ones:type C = Refine<Config, Loose<{ retries: 3; label: string }>>;// → { retries: 3; hooks: Array<() => void>; label: string }// Override at a leaf — same result, replacing just that field:type A = Refine<Config, { hooks: Override<string[]> }>;// → { retries: number; hooks: string[] }// Override an entire object — siblings dropped, new keys allowed:type B =
Reach for Loose to keep the base and layer changes on top — narrowing or replacing fields that don't conform and adding new ones — without the conformance check. Reach for Override when you want to discard the base at that node and use a different shape entirely.