core-js 中的 Promise.withResolversStage 4 提案的完整实战指南【免费下载链接】core-jsStandard Library项目地址: https://gitcode.com/GitHub_Trending/co/core-js本文以 core-js 仓库中 docs/web/docs/features/proposals/promise-withresolvers.md 为骨架系统讲解Promise.withResolvers静态方法的规范签名、核心实现原理与各种入口Entry point的引入方式。读完你将掌握如何在不支持该特性的旧环境中使用 core-js 一键补齐Promise.withResolvers理解它背后NewPromiseCapability抽象操作的执行流程并能根据实际项目选择core-js或core-js-pure的引入策略。Promise.withResolvers是什么Promise.withResolvers是 TC39 的 Promise.withResolvers 提案Proposal repo 见 tc39/proposal-promise-with-resolvers所定义的Promise静态方法用于在不经过new Promise(executor)回调包装的情况下一步同时拿到一个 Promise 实例以及它的 resolve / reject 两个控制器。在 core-js 中它已进入 Stage 4正式定稿的 ECMAScript 特性并同时以es.*标准与esnext.*提案阶段别名两套模块命名存在。从源码结构看仓库同时保留了 packages/core-js/modules/es.promise.with-resolvers.js正式实现与 packages/core-js/modules/esnext.promise.with-resolvers.js向后兼容的别名入口文件头部标注了// TODO: Remove from core-js4即预计在 core-js 4 中移除这种双轨命名是 core-js 处理“提案已转正”特性的典型迁移方式。规范中的方法签名原文档给出了该特性的 TypeScript 签名class Promise { static withResolvers(): { promise: Promise, resolve: function, reject: function }; }要点拆解static它是Promise构造器上的静态方法通过Promise.withResolvers()调用而不是实例方法无参数调用时不接收任何参数返回值是一个普通对象其原型是Object.prototype返回值结构{ promise, resolve, reject }三元组promise一个已创建好的、状态待定的 Promise 实例resolve用于兑现resolve该 promise 的函数reject用于拒绝reject该 promise 的函数。与new Promise(executor)的对比传统写法需要把 resolve / reject 从 executor 回调内部“逃逸”出来let resolve, reject; const promise new Promise((res, rej) { resolve res; reject rej; }); // 之后可在任意位置调用 resolve / rejectPromise.withResolvers()把这一过程收敛为一个原子操作const { promise, resolve, reject } Promise.withResolvers();两者语义等价但后者无需提前声明变量、无需在 executor 内赋值代码更简洁也更适合在事件处理器、回调接口适配等场景中把 promise 的“创建”与“结算”解耦。core-js 中的实现原理原文档只给了签名与入口这里结合源码把底层原理补齐。core-js 的正式实现位于 packages/core-js/modules/es.promise.with-resolvers.jsuse strict; var $ require(../internals/export); var newPromiseCapabilityModule require(../internals/new-promise-capability); // Promise.withResolvers method // https://tc39.es/ecma262/#sec-promise.withResolvers $({ target: Promise, stat: true }, { withResolvers: function withResolvers() { var promiseCapability newPromiseCapabilityModule.f(this); return { promise: promiseCapability.promise, resolve: promiseCapability.resolve, reject: promiseCapability.reject }; } });关键点是newPromiseCapabilityModule.f(this)它对应 ECMAScript 规范中的NewPromiseCapability抽象操作实现在 packages/core-js/internals/new-promise-capability.jsvar PromiseCapability function (C) { var resolve, reject; this.promise new C(function ($$resolve, $$reject) { if (resolve ! undefined || reject ! undefined) throw new $TypeError(Bad Promise constructor); resolve $$resolve; reject $$reject; }); this.resolve aCallable(resolve); this.reject aCallable(reject); }; // NewPromiseCapability abstract operation // https://tc39.es/ecma262/#sec-newpromisecapability module.exports.f function (C) { return new PromiseCapability(C); };从这份实现可以读出几个重要细节支持子类化subclassingnewPromiseCapabilityModule.f(this)中的this是调用withResolvers时的接收者receiver。如果写成MyPromise.withResolvers()MyPromise继承自Promise生成 promise 的构造器就是MyPromisepromise instanceof MyPromise成立。构造函数行为校验PromiseCapability内部使用new C(executor)创建实例并通过resolve ! undefined || reject ! undefined的守卫检测 executor 是否被正确同步调用若构造器行为异常比如没有同步调用 executor会抛出TypeError: Bad Promise constructor。aCallable校验从 executor 拿到的resolve/reject会被aCallable强制校验为可调用函数否则同样抛出TypeError。严格遵循规范章节实现注释直接标注了对应的 ECMA-262 规范节sec-promise.withResolvers方便对照阅读。单元测试如何验证行为仓库在 tests/unit-global/es.promise.with-resolvers.js 中对该特性做了完整的行为验证tests/unit-pure/es.promise.with-resolvers.js为 pure 版本对应的测试静态性与元数据withResolvers是函数、arity形参个数为 0、name为withResolvers、不可枚举、且looksNative返回值结构返回对象的原型是Object.prototypepromise instanceof Promise为真resolve/reject均为函数子类化支持通过自定义构造器P(exec)调用withResolvers.call(P)断言返回的promise就是自定义构造器产出的实例异常路径当构造器的 executor 未被正确同步调用如reject被替换为非函数时抛TypeError当this为{}或null无法作为构造器时同样抛TypeError语义正确性resolve(42)后promise.then收到值42reject(42)后 promise 以42拒绝。这些测试同时被 tests/entries/unit.mjs 收集并在 tests/compat/tests.js 中作为兼容性探测点return Promise.withResolvers;参与 browserslist 目标环境的特性探测。如何引入Entry Points 详解原文档明确指出该特性的入口Entry point为core-js/proposals/promise-with-resolvers对应文件为 packages/core-js/proposals/promise-with-resolvers.js其内容会转引入esnext.promise.with-resolvers模块最终落到正式的es.promise.with-resolvers实现。也就是说通过这个入口引入时底层加载的实际就是上述的正式实现模块。不过由于该特性已进入 Stage 4 并成为标准core-js 提供了更多更精细的引入粒度按需选择即可引入方式入口路径说明提案入口旧习惯core-js/proposals/promise-with-resolvers兼容旧写法本质加载正式实现Stage 4 聚合入口core-js/stage/4在 packages/core-js/stage/4.js 中通过require(../proposals/promise-with-resolvers)统一引入所有已转正的特性ES 标准入口推荐core-js/es/promise/with-resolvers单点引入该特性对应 packages/core-js/es/promise/with-resolvers.jsES 聚合入口core-js/es/promise一次性引入全部 Promise 标准特性见 packages/core-js/es/promise/index.js其中require(../../modules/es.promise.with-resolvers)即本特性全量特性入口core-js/full/promise/with-resolvers完整版含 esnext 与 proposals对应 packages/core-js/full/promise/with-resolvers.jsstable 入口core-js/stable/promise/with-resolvers稳定特性入口对应 packages/core-js/stable/promise/with-resolvers.js转发到 es 实现actual 入口core-js/actual/promise/with-resolvers“实际环境”入口对应 packages/core-js/actual/promise/with-resolvers.js额外加载esnext别名模块以保证旧写法兼容典型用法示例在现代构建工具Babel / webpack / Vite 等环境下推荐按需引入 es 标准入口// 只补齐 Promise.withResolvers import core-js/es/promise/with-resolvers; const { promise, resolve, reject } Promise.withResolvers(); setTimeout(() resolve(done), 1000); promise.then(value console.log(value)); // 1 秒后打印 done如果需要所有 Promise 相关标准特性allSettled、any、try、finally等可引入聚合入口import core-js/es/promise;对于使用core-js-pure不污染全局命名空间、适合库作者的场景core-js-pure同样提供对等的入口路径如core-js-pure/es/promise/with-resolvers具体包结构见 packages/core-js-pure/README.md。使用 pure 版本时调用方式从“全局方法”变为“从模块获取”const Promise require(core-js-pure/es/promise); // 或直接 import core-js-pure/es/promise/with-resolvers 后 const { promise, resolve, reject } Promise.withResolvers();适用场景从源码实现与测试覆盖来看Promise.withResolvers最典型的应用场景包括事件驱动转 Promise把setTimeout、addEventListener、WebSocket 消息等基于回调的异步事件封装成可 await 的 Promise无需再手动维护外部变量回调接口适配把旧的 Callback 风格 API 封装为 Promise 风格多次触发信号的合并配合AbortSignal、流处理等场景把“一次结算”的状态机建模为待定 Promise需要暴露控制权的设计将resolve/reject传给其他模块或类由它们决定 promise 的最终状态。注意事项与版本前提本仓库当前以es.promise.with-resolvers为正式实现esnext.promise.with-resolvers仅是兼容别名源码注释标明将在 core-js 4 移除新项目应优先使用es前缀或直接以core-js/proposals/promise-with-resolvers入口引入若目标环境原生已支持Promise.withResolvers现代浏览器与 Node.js 20core-js 的该模块在环境检测到原生实现时通常不会覆盖引入成本极低在浏览器直接以script方式使用时可以引入打包产物core-js-bundle见 packages/core-js-bundle/README.md构建工具场景则优先按入口按需引入以控制体积。小结Promise.withResolvers()是无参的静态方法返回{ promise, resolve, reject }对应 ECMA-262 规范与 TC39 提案core-js 通过NewPromiseCapability抽象操作实现它支持子类化并对异常构造器抛TypeError源码见 packages/core-js/internals/new-promise-capability.js按原文档指定入口为core-js/proposals/promise-with-resolvers由于特性已转正更推荐使用core-js/es/promise/with-resolvers或聚合入口core-js/es/promise并可通过core-js/stage/4一次性补齐全部 Stage 4 特性行为正确性由 tests/unit-global/es.promise.with-resolvers.js 与 tests/unit-pure/es.promise.with-resolvers.js 双重验证可放心在旧环境使用。【免费下载链接】core-jsStandard Library项目地址: https://gitcode.com/GitHub_Trending/co/core-js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
