temporal-polyfill 实现原理BigInt 纳秒数学与算法化日历如何炼成 19.5KB 体积【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporaltemporal-polyfill 实现原理是 JavaScript 开发者理解新一代时间 API 的最佳入口。作为 JavaScriptDate对象的官方继任者 Temporal 的轻量级 polyfilltemporal-polyfill 用19.5KBgzip 压缩后的迷你体积实现了近乎完整的 Temporal 规范。本文深入这个开源项目的源码拆解 BigInt 纳秒数学如何守住时间精度、算法化日历如何支撑希伯来历、农历等 14 种日历系统以及 19.5KB 体积背后的工程诀窍。Temporal 是什么为什么 Date 不够用Date对象陪伴 JavaScript 二十多年但它的痛点众所周知月份从 0 开始、时区处理混乱、没有不可变对象、日期运算反直觉。TC39 组织历时多年推出 Temporal 提案带来Temporal.PlainDate、Temporal.Instant、Temporal.ZonedDateTime等全新类型让日期时间处理变得安全、精确、可预测。由于原生 Temporal 尚未在所有环境落地polyfill 就成了过渡期的必需品。temporal-polyfill 正是为此而生它同时提供全局 polyfillimport temporal-polyfill/global有原生 Temporal 时自动使用原生实现本地 ponyfillimport { Temporal } from temporal-polyfill无副作用、可按需引入强制非原生实现temporal-polyfill/implementation用于测试与对比安装方式参考 polyfill/README.md一条npm install temporal-polyfill即可开始。核心难点一BigInt 纳秒数学Temporal 的时间精度高达纳秒10⁻⁹ 秒而 JavaScript 的Number只能安全表示 2⁵³ 以内的整数。从 1970 年 1 月 1 日算起现在的纳秒时间戳早已突破 1.6 × 10¹⁸远超安全整数范围。为什么必须用 BigInttemporal-polyfill 的答案是 bigNano.ts 中的 BigInt 方案内部统一用bigint保存纳秒级时间戳把「天」和「日内纳秒」拆开存储。这样既避免了精度丢失也让代码更简洁——所有运算都在 BigInt 上进行直到调用方明确需要Number才做转换。精妙的除法技巧BigInt 无法直接得到浮点数结果而 Temporal 大量运算如转秒、转毫秒需要精确的Number。看 bigNano.ts 中divideBigNanoToExactNumber的解法先把 BigInt 纳秒按 UTC 天切分days与timeNano日内部分仍落在安全整数范围用Number安全计算把「整天数 × 每日份数」与「日内整数 余数/除数」合并巧妙之处在于先合并再取整避免先对巨大商取整而丢失影响最终浮点舍入的小数部分。这就是为什么它敢注释说这不是日历天数学nanoInUtcDay只是方便的分块尺寸。配套的 epochMath.ts 提供epochNanoToSec、epochNanoToMilli等转换配合divModFloorBigInt实现向下取整除法保证负数时间戳也符合规范语义。时间槽slot的创建则由 slots.ts 统一管理createEpochNanoSlots返回携带epochNanoseconds: bigint的纯数据对象。核心难点二算法化日历系统如果说纳秒数学解决的是时间精度那日历系统解决的就是历法多样。Temporal 规范要求支持14 种非 ISO 日历temporal-polyfill 把它们分成了两类实现策略。策略一纯算法日历Arithmetic Calendar希伯来历、伊斯兰历civil/tabular、科普特历、波斯历、印度历、佛历、民国历等都可以用纯数学公式推算。它们的核心是儒略日Julian Day转换统一抽象在 arithmeticCalendar.ts 中日历实现只需提供fromJulianDay儒略日 → 年月日和toJulianDay年月日 → 儒略日两个核心函数闰月、闰年、月长等规则通过computeLeapMonth、computeDaysInMonth等回调注入借助memoize缓存转换结果重复查询零成本以 hebrewCalendar.ts 为例希伯来历是阴阳合历用「小时/部分halakim」体系计算1 部分 1/1080 小时。代码里monthFract 12 * 1080 793正是经典的希伯来历月长小数部分配合hebrewDelay1、hebrewDelay2处理岁首推迟规则完美还原规范行为。islamicCalendar.ts 则一文件三历islamic-civil民用、islamic-tbla天文表格共用同一套算术逻辑仅儒略日起点不同而islamic-umalqura是观测历走的是第二种策略。策略二Intl 抓取日历Intl-Scraped Calendar农历chinese、檀纪历dangi、乌姆库拉伊斯兰历islamic-umalqura这类历法规则过于复杂涉及天文观测与闰月排布temporal-polyfill 选择直接借用浏览器内置的Intl.DateTimeFormat能力——通过向 Intl 询问某年的月份数据并缓存构建出日历查询表。这套机制封装在 intlScrapedCalendar.ts 中。比如 chineseDangiCalendar.ts农历闰月的 month-day 引用规则用一张monthDayLeapMonthMaxDays表维护闰月 M01L、M12L 不允许 30 日M02L 允许 1-29 日等。所有闰月搜索起始年份也精心标注如 1651 年是闰 M01L 的 29 天闰月年确保与 ICU4C 引擎行为对齐。日本历的时代处理日本历比较特殊——它本质是公历对齐 年号era体系。japaneseCalendar.ts 用japaneseEraOrigins表记录明治、大正、昭和、平成、令和五个年号的起始年份与起始日期通过儒略日换算判断日期属于哪个年号并在 1873 年之前回退到公历纪元保证 test262 规范测试的一致性。所有日历的注册与别名处理集中在 exoticCalendars/index.ts14 种日历的元数据、islamicc等历史别名的归一化、以及被规范禁止的islamic通配 ID 的拦截都在这一个文件里清晰管理。19.5KB 体积的工程诀窍光功能完整还不够temporal-polyfill 的体积控制才是它脱颖而出的关键。官方对比数据见 size-comparison/RESULTS.md包基础日历全部日历temporal-polyfill19.5 KB23.4 KBjs-temporal/polyfill52.1 KB52.1 KB同样功能体积只有官方参考实现的三分之一不到。这是怎么做到的1. 按需拆分入口basic仅 ISO 与公历与full14 种日历两个构建层次配合global、shim、implementation、fns多个入口让使用者按需加载互不污染。入口配置见 package.json 的buildConfig.exports。2. 原生优先Native SwitchnativeSwitch.ts 只有一行核心逻辑检测globalThis.Temporal是否存在。有原生实现就直接复用polyfill 自身甚至不会被真正执行——这既是体积优化也是性能优化。3. 树摇友好的函数 API除了类风格 APItemporal-polyfill 还提供temporal-polyfill/fns/*纯函数 API详见 docs/fns/index.md每个操作都是独立的顶层函数打包器可以只保留真正用到的函数。组件库作者还能把它声明为 peer dependency避免每个应用重复打包日期库细节见 docs/fns/for-component-authors.md。4. 定制压缩器Mangler体积优化的压轴戏在 mangler.js 里。它定制了 Terser 的属性名压缩策略高频字符etrn优先分配给最短的属性名让 gzip 的重复模式更密集同时把Intl.DateTimeFormat的选项键calendar、dateStyle等加入保留字名单防止错误重命名。这种为 gzip 服务的命名哲学是 19.5KB 数字背后的隐形功臣。打包流程由 bundle.js 驱动Rollup 打包 Terser 压缩体积验证则交给 size.js 自动报告每个入口的 mingzip 大小。可靠性test262 规范的试金石小体积不等于打折实现。temporal-polyfill 通过官方test262 测试套件验证规范符合度仅有的 2 处刻意偏离也记录在 test262-expected-failures/shim.txt 中透明可查。CI 会在 Node 16 到 26 的多个版本上跑完整测试浏览器端 Chrome 67、Safari 14 即可使用完整支持矩阵见 polyfill/README.md。迁移与未来从 polyfill 到原生当原生 Temporal 逐渐普及后polyfill 代码该如何平滑过渡项目还附带了 codemod 工具npx temporal-polyfill-codemod fns-to-temporal path可以自动把基于fns函数 API 的代码改写为地道的Temporal.PlainDate类调用实现一次编写永久平滑升级。结语temporal-polyfill 实现原理向我们展示了三个工程智慧用 BigInt 守住纳秒精度、用算法抽象承载 14 种历法、用极致的压缩与拆包哲学把体积压到 19.5KB。无论你是想提前体验 Temporal 的新 API还是研究高性能 polyfill 的写法这份源码都值得一读——项目结构清晰从 polyfill/src/internal 的数学内核到 polyfill/src/exoticCalendars 的历法体系每一层都是教科书级的实现。【免费下载链接】temporal-polyfillA lightweight polyfill for Temporal, successor to the JavaScript Date object项目地址: https://gitcode.com/gh_mirrors/tempo/temporal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考