TypeScript中如何以类型安全方式声明选项并访问其值？

我正在使用一个提供深度可选接口的库，相关类型定义如下：

type Option = number | {
  x?: number;
  y?: number;
  z?: number;
}

interface Options {
  a?: Option;
  b?: Option;
  c?: Option;
  d?: Option;
}

function initializeLibrary(options: Options) {
  // ...
}

我希望声明一个稀疏的选项集合，自行使用这些值后再传入该库。目前的实现方式如下：

// 1. 声明稀疏选项集。
const opts = {
  a: 3,
  b: 4,
  c: { x: 3 },
};

// 2. 自行使用选项值。
console.log("Sum:", opts.a + opts.c.x);

// 3. 将选项传入库。
initializeLibrary(opts);

这种方式可行，但并不类型安全：我可以给opts添加不属于Options的属性，且不会收到错误提示。

const opts = {
  a: 3,
  f: 3, // `f`不属于Options。
};

initializeLibrary(opts); // 无错误提示！

如果将opts声明为Options类型，虽然实现了类型安全，但访问opts.a时会出现错误：

const opts : Options = {
  a: 3,
  b: 4,
  c: { x: 3 },
};

console.log(opts.a + opts.c.x); // 错误：对象可能为 'undefined'

如何以类型安全的方式声明选项，同时能正常访问其值？

我目前的尝试是重新声明自己使用的Options接口的特定部分：

interface MyOptions extends Required<Pick<Options, "a" | "b" | "c">> {
  a: number;
  c: { x: number };
}
const opts: MyOptions = {
  a: 3,
  b: 4,
  c: { x: 3 },
};

这种方式有效，能防止添加Options中不存在的属性，但我的实际场景更为复杂，希望找到更自动化的实现方式。

解决方案 #

1. 使用 satisfies 关键字（TypeScript 4.9+）

satisfies 可以确保你的对象符合Options类型约束，同时保留对象字面量的具体类型，既不会出现访问属性时的undefined错误提示，也能阻止添加非法属性。

const opts = {
  a: 3,
  b: 4,
  c: { x: 3 },
} satisfies Options;

// 正常访问属性，无类型错误
console.log("Sum:", opts.a + opts.c.x);

// 尝试添加非法属性会直接报错
const badOpts = {
  a: 3,
  f: 3, // 错误：类型 "{ a: number; f: number; }" 不满足 "Options" 类型
} satisfies Options;

// 正常传入库函数
initializeLibrary(opts);

2. 自定义工具类型（兼容低版本TypeScript）

如果你的TypeScript版本低于4.9，可以用工具类型自动推导声明属性的具体类型，同时约束属性必须来自Options：

type StrictOptions<T extends Partial<Options>> = T & {
  [K in keyof T]-?: Exclude<Options[K], undefined> extends infer O ? 
    T[K] extends O ? T[K] : never : never;
};

function createOptions<T extends Partial<Options>>(opts: StrictOptions<T>): T {
  return opts;
}

// 使用方式
const opts = createOptions({
  a: 3,
  b: 4,
  c: { x: 3 },
});

// 安全访问属性
console.log("Sum:", opts.a + opts.c.x);

// 添加非法属性会报错
const badOpts = createOptions({
  a: 3,
  f: 3, // 错误：类型 "{ a: number; f: number; }" 的参数不能赋给类型 "StrictOptions<{ a: number; f: number; }>" 的参数
});

这个工具类型StrictOptions会严格校验属性归属，并推导每个属性的具体类型，让你无需手动重复声明接口细节。

内容的提问来源于stack exchange，提问作者Neal Ehardt