package
A utility type for refining and narrowing TypeScript types
npm install type-refineGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
13.1 kB
Includes dependencies.
A utility type for refining and narrowing TypeScript types.
npm install type-refineimport type { Refine, Override } from 'type-refine';
type Animal = { type: 'dog'; bark: boolean } | { type: 'cat'; purr: boolean };
type Base = { pet: Record<string, Animal> };
// Narrow record values to just dogs
type OnlyDogs = Refine<Base, { pet: Record<string, { type: 'dog' }> }>;
declare const val: OnlyDogs;
val.pet.fido.bark; // ok
Slack's KnownBlock is a large union of block types. Use a tuple constraint to define exactly which blocks appear, in what order:
import type { KnownBlock } from '@slack/web-api';
type OrderNotification = Refine<
KnownBlock[],
[
{ type: 'section'; text: { type: 'mrkdwn' } },
{ type: 'divider' },
{ type: 'actions'; elements: Array<{ type: 'button' }> },
]
>;
const message: OrderNotification = [
{ type: 'section', text: { type: 'mrkdwn', text: 'New order from *Alice*' } },
{ type: 'divider' },
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.
Lock down which hooks and transports a config accepts:
type HookFn = (...args: any[]) => any;
type HookEntry = { hooks: HookFn[]; timeout?: number };
type Transport =
| { type: 'http'; url: string }
| { type: 'ws'; port: number }
| { type: 'stdio'; cmd: string };
type PluginConfig = {
name: string;
transport: Transport;
Refine<Base, Constraint> maps over the keys of Base and applies Constraint per-field:
Refine<{ a: string }, { a: 'hello' }> narrows a to 'hello'Record<string, ...> constraints refine values while keeping the original keysArray<T> constraints refine all elements; tuple constraints enforce position and length? on a constraint key makes it optional; no ? makes it requiredLoose<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 outrightLoose & OverrideBy 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.
MIT