satisfies 操作符

// theme.ts —— 第一版：只用类型注解
type TokenMap = Record<string, string>;

export const tokens: TokenMap = {
  'color.surface': '#ffffff',
  'color.text': '#1a1a2e',
  'color.accent': '#4f6df5',
};

// 问题一：tokens 的类型就是 TokenMap（Record<string, string>），
// keyof 只能拿到 string，令牌名的联合类型无从谈起
type TokenName = keyof typeof tokens; // string —— 没用

// 问题二：多写、少写、拼错键名，编译器一概不管
export const tokens2: TokenMap = {
  'color.sruface': '#ffffff', // 拼错了，没有任何提示
};

// theme.ts —— 第二版：satisfies
type TokenMap = Record<`color.${string}`, string>;

export const tokens = {
  'color.surface': '#ffffff',
  'color.text': '#1a1a2e',
  'color.accent': '#4f6df5',
} satisfies TokenMap;

// 1. 类型验证仍然生效：键名必须以 color. 开头
export const broken = {
  'bg.surface': '#ffffff', // 错误：对象字面量只能指定已知属性，
  //      且 '"bg.surface"' 不符合索引签名 `color.${string}`
} satisfies TokenMap;

// 2. 具体类型被完整保留
type TokenName = keyof typeof tokens;
// 'color.surface' | 'color.text' | 'color.accent' —— 正是想要的联合类型

// 3. 编辑器补全 tokens. 时，会列出全部三个令牌名

type RouteConfig = {
  path: string;
  auth: boolean;
};

// 写法一：类型注解 —— 检查通过后，类型变成 RouteConfig
const r1: RouteConfig = { path: '/docs', auth: false };
r1.path; // string —— 字面量 '/docs' 没了

// 写法二：类型断言 —— 不检查，类型被强行声明为 RouteConfig
const r2 = { path: '/docs', auth: false, typo: 'yes' } as RouteConfig;
// 多出来的 typo 属性、任何字段错误都不会被发现（as 只在两个类型
// 「互有重叠」时才拒绝，重叠面宽得很）

// 写法三：satisfies —— 检查，且保留原类型
const r3 = { path: '/docs', auth: false } satisfies RouteConfig;
r3.path; // '/docs' —— 字面量还在（对象在 const 声明下，属性不再拓宽）
//        （严格说：字符串字面量在对象属性位置本会拓宽为 string，
//         见第 3 节的精确规则；这里 r3 的效果与 as const 组合有关）

const r4 = {
  path: '/docs',
  auth: 'no', // 错误：string 不能赋给 boolean —— 检查确实发生了
} satisfies RouteConfig;

type LogLevel = 'debug' | 'info' | 'warn' | 'error';

const config = {
  api: { url: 'https://api.example.com', level: 'warn' },
} satisfies Record<string, { url: string; level: LogLevel }>;
// 若 level 写成 'warrn'，报错直接指向这一行这个字段：
// Type '"warrn"' is not assignable to type '"debug" | "info" | "warn" | "error"'

import { z } from 'zod';

const DocMeta = z.object({
  title: z.string(),
  order: z.number(),
  updated: z.string(),
});
type DocMeta = z.infer<typeof DocMeta>;

// satisfies 管编译期：这份测试数据字段对不对，写的时候就报错
const fixture = {
  title: '学习笔记',
  order: 180,
  updated: '2026-09-12',
} satisfies DocMeta;

// zod 管运行期：来自网络、文件、用户的不可信数据，必须走 parse
const parsed = DocMeta.parse(JSON.parse(rawInput));

const a = { x: 42 } satisfies { x: number };
a.x; // number —— 对象属性位置的字面量本来就会拓宽，satisfies 原样保留了这个拓宽

const b = { x: 42 } as const satisfies { x: number };
b.x; // 42 —— 想要字面量，加 as const

const a = 42 satisfies number;
// a: 42 —— const 声明从不拓宽字面量，satisfies 只是没拦它

let b = 42 satisfies number;
// b: number —— satisfies 会剥掉字面量的「新鲜性」，let 声明随即拓宽
// 想在 let 下也保住字面量，只能 as const：let c = 42 as const; // c: 42

// 错误：'as' expected —— satisfies 后面只能跟类型，不能跟 as const
const bad = { home: '/' } satisfies Record<string, string> as const;

// 正确：先 as const（改类型），再 satisfies（做验证）
const good = { home: '/' } as const satisfies Record<string, string>;

// 错误：语法不合法
function getUser(): User satisfies User { /* ... */ }

// 正确：在 return 的表达式上验证
function getUser(): User {
  return { name: 'Alice', age: 30 } satisfies User;
}

const ids = [101, 102] satisfies number[];
// number[] —— 元素拓宽，101/102 的信息没了

const idsFrozen = [101, 102] as const satisfies readonly number[];
// readonly [101, 102] —— 元组 + 字面量，注意目标是 readonly number[] 才兼容

const STATUS = {
  ok: 200,
  notFound: 404,
} as const satisfies Record<string, number>;

type StatusCode = (typeof STATUS)[keyof typeof STATUS]; // 200 | 404
function handle(code: StatusCode) { /* ... */ }
handle(STATUS.ok); // 通过
handle(500);       // 错误：500 不在联合类型里 —— 正是想要的效果