temporal-polyfill 函数式 API 原理揭秘：非标准函数与普通记录对象背后的设计智慧

temporal-polyfill 函数式 API 原理揭秘：非标准函数与普通记录对象背后的设计智慧

【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporal

temporal-polyfill 是新一代 JavaScript 时间库 Temporal 的轻量级 Polyfill，被誉为 Date 对象的继任者。本文为你揭秘 temporal-polyfill 函数式 API 的核心原理，带你理解"非标准函数"与"普通记录对象"这两大设计背后隐藏的智慧，读懂它，你就能真正掌握 JavaScript Temporal 时代最前沿的 API 设计思路。

一、为什么 Temporal 需要 Polyfill？

JavaScript 的Date对象已经服役了三十年，它的 API 设计饱受诟病：月份从 0 开始、时区处理混乱、不可变操作缺失……Temporal 正是为解决这些问题而诞生的下一代标准日期时间 API，提供了PlainDate、PlainTime、Instant、ZonedDateTime等全新类型。

但 Temporal 标准尚未在所有 JavaScript 运行环境中完全落地。temporal-polyfill 的价值就在于：它用纯 JavaScript 完整实现了 Temporal 规范，让你今天就能在生产环境使用未来的 API。

💡 更妙的是，temporal-polyfill 不只是"类 API 的搬运工"，它还额外提供了一套函数式 API（位于 polyfill/src/funcApi/ 目录），这正是本文的主角。

二、什么是"非标准函数"？函数式 API 与类 API 的区别

标准的 Temporal 类 API 长这样：

const date = new Temporal.PlainDate(2024, 5, 1) const next = date.add({ days: 3 }) // 方法调用 const day = next.dayOfWeek // 属性读取

而 temporal-polyfill 的函数式 API 则完全换了一种风格，把操作拆解成一个个独立的纯函数：

import * as PlainDateFns from 'temporal-polyfill/fns/PlainDate' const date = PlainDateFns.create(2024, 5, 1) // 构造函数 const next = PlainDateFns.addDays(date, 3) // 函数操作 const day = PlainDateFns.dayOfWeek(next) // 函数读取

对比一下两者的本质区别：

这种"函数在前面、数据在后面"的写法，就是所谓的非标准函数——它不遵循new+ 方法调用的传统模式，而是把 Temporal 的每个能力都变成可独立导入、独立测试的模块。

三、普通记录对象（Record）：数据与行为分离的设计哲学

函数式 API 最核心的概念是Record（记录对象）。打开 polyfill/src/funcApi/recordTypes.ts 你会发现，PlainDateRecord、InstantRecord、DurationRecord等 9 种记录类型，本质上都是普通的 JavaScript 对象。

以PlainDateRecord为例，它的形状非常朴素：

type PlainDateRecord = { readonly year: number readonly month: number readonly day: number readonly calendarId: string toJSON(): string // 序列化为 ISO 字符串 }

设计要点一：只读字段，杜绝副作用

所有字段都是readonly，记录对象一旦创建就不可修改。任何"修改"操作（如add、withFields）都会返回一个全新的记录对象，原对象保持不变。这让数据流变得可预测，在复杂应用中大大减少了"改了一个对象，别处悄悄受影响"的隐性 Bug。

设计要点二：toJSON 提供统一出口

每个记录都自带toJSON()方法，返回标准的 ISO 8601 字符串。这意味着JSON.stringify(record)能直接输出正确的时间文本，序列化零成本。

设计要点三：valueOf 被"故意禁用"

你会在类型定义中看到valueOf(): never——这是刻意为之！never表示该方法永远不会正常返回。为什么要禁用？

date + 1 // 若不禁用 valueOf，可能被隐式转成数字

时间对象被隐式转换为数字是 JavaScript 经典的坑（Date就中招过）。禁用valueOf等于从语言层面杜绝了隐式类型转换，强迫开发者走显式的比较函数，比如equals、compare。这正是设计智慧的体现：用类型系统消灭一整类运行时错误。

四、品牌（Brand）与内部槽：看不见的类型安全屏障

记录对象既然是"普通对象"，那么问题来了：怎么区分一个PlainDateRecord和一个普通{year, month, day}对象？甚至怎么区分它和PlainDateTimeRecord？

答案藏在两套"品牌机制"里：

1️⃣ 编译期品牌：unique symbol

在 recordTypes.ts 中，每个类型都有一个唯一的 symbol 作为品牌：

export declare const PlainDateRecordBrand: unique symbol type PlainDateRecord = { readonly [PlainDateRecordBrand]: undefined // 编译期指纹 ... }

这个 symbol 字段在运行时几乎不占空间，却在 TypeScript 编译期起到了"身份识别"的作用——类型检查器能据此精确区分 9 种记录类型，防止把DurationRecord误传给需要PlainDateRecord的函数。

2️⃣ 运行时品牌：WeakMap 内部槽

如果只靠普通字段，记录对象的数据就完全暴露了。temporal-polyfill 的做法是：公开对象只保留少量可见字段，真正的"内部状态"（如日历实现对象、计算好的缓存）存放在 WeakMap 里。

打开 polyfill/src/funcApi/temporalRecords.ts，你会看到一排内部槽映射：

const plainDateMap = new WeakMap<object, unknown>() const durationMap = new WeakMap<object, unknown>()

每个记录对象创建时，内部槽通过setPlainDateSlots(instance, slots)存入 WeakMap；读取时通过getPlainDateSlots(record)取出。外部无法通过Object.keys窥探内部实现，而函数则通过isPlainDateRecord、getPlainDateSlots等工具做统一的运行时校验。

这是典型的"门面模式 + 品牌模式"组合：对外是干净普通的对象，对内是安全私密的槽。普通用户只看到简单数据，内部实现却能随意演进而不破坏兼容性。

五、双引擎设计：原生优先，Shim 兜底

函数式 API 还有一个非常聪明的设计：同一套函数签名，背后有两个实现引擎。

在 polyfill/src/funcApi/plainDate.ts 中，每个函数的定义都是：

export const create = NativeTemporal ? Native.create : Shim.create

• Native 实现（polyfill/src/funcApi/native/）：当运行环境已原生支持 Temporal 时，直接包装浏览器的原生对象，性能最优、包体积最小；
• Shim 实现（polyfill/src/funcApi/shim/）：当环境不支持时，用纯 JS 完整模拟，功能零损失。

NativeTemporal开关（见 polyfill/src/nativeSwitch.ts）在运行时自动检测，使用者完全无感知。这意味着：今天用 polyfill 写的代码，未来浏览器原生支持 Temporal 后，会自动"升级"到原生实现，一行代码都不用改。这是长期兼容性的典范。

六、设计智慧总结：函数式 API 到底赢在哪里？

把前面所有设计串起来，函数式 API 的价值可以用一个词概括：极致的模块化。

对于库作者，函数式 API 让每个函数都可以独立单元测试（项目中的 fns-direct-coverage.test.ts 等测试就是为它们量身打造的）；对于应用开发者，它提供了一条平滑升级到 Temporal 的路径——项目甚至自带了 codemod 迁移工具（见 codemod/src/），可以把函数式 API 代码自动改写为标准类 API 代码。

七、结语：向未来 JavaScript 时间编程迈进

temporal-polyfill 的函数式 API 不是标新立异，而是深思熟虑后的工程选择：用普通对象承载数据，用非标准函数承载行为，用品牌机制保证安全，用双引擎保证兼容。这四招组合拳，让 polyfill 既能"轻"（体积小、按需加载），又能"稳"（类型安全、行为可预期），还能"远"（面向原生时代的未来）。

如果你正在做时间日期相关的开发，不妨深入研究这份源码——polyfill/src/funcApi/ 目录里的每一行代码，都值得你慢慢品味。下一次当你写下PlainDateFns.addDays(date, 3)时，你会知道，这个简单的函数背后，藏着一整个优雅的架构世界。🚀

【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporal