sql-server-samples 前端依赖 Q 2.0 变更日志全解读：从 Promise 构造函数到 Node.js 桥接的演进路线

sql-server-samples 前端依赖 Q 2.0 变更日志全解读从 Promise 构造函数到 Node.js 桥接的演进路线【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址: https://gitcode.com/gh_mirrors/sq/sql-server-samplesQkriskowal/q是 JavaScript 早期 Promise 实现的代表性库之一也是 Microsoft Wide World Importers 示例应用wwi-app前端所依赖的异步库。本文以仓库中随附的 CHANGES.md 为核心完整梳理 Q 从 0.0.1 到 2.0.2 的版本演进重点解读 2.0 系列的破坏性变更、新的Promise构造函数、预计完成时间Estimated Time to Completion进度机制以及针对 Node.js 的桥接 API 收缩并结合仓库内 q.js 源码与 wwi-app 的实际引用方式帮助读者理解这套 promise 协议的设计取舍与迁移路径。Q 在 wwi-app 中的角色一个 OData 前端的异步基石在深入变更日志之前先明确 Q 在这个仓库中的实际位置。wwi-app 是一个 ASP.NET Core 应用其前端布局页 Views/Shared/_Layout.cshtml 中按顺序引入了~/lib/q.js与~/lib/o.js/o.min.jso.js 是一个 OData 客户端库其文档明确指出它依赖 Q 提供的 promise 能力Q.all可以并行获取多个 OData 资源.then()处理成功、.fail()处理失败。// o.js README 中的用法示例见 wwwroot/lib/o.js/README.md Q.all([ o(http://services.odata.org/V4/OData/OData.svc/Products(4)).get(), o(http://services.odata.org/V4/OData/OData.svc/Categories).take(2).get() ]).then(function(oHandlerArray) { oHandlerArray[0].data; // 1 Product with id 4 oHandlerArray[1].data.length; // 2 Categories });因此CHANGES.md记录的每一次接口变动都直接影响 wwi-app 这类依赖 Q 的应用能否平滑升级。仓库随附的 Q 版本为 2.0.2见 package.json这意味着它已经处于文档开头所警告的基于 Q 重写的新实验性发布线。2.0.2一次带有大量破坏性变更的重写CHANGES.md开篇即声明2.0 是一个实验性发布线基于对 Q 的完全重写。v1 的全部接口虽然仍受支持但部分接口会输出弃用警告这些被弃用的特性将在 v3 中被彻底移除。以下是本次发布涉及的全部破坏性变更。运行环境要求ECMAScript 5 与 WeakMap自1.0起Q 要求运行环境支持 ECMAScript 5。文档特别强调仅引入es5-shim甚至es5-sham都不足以让旧引擎兼容因为 Q 依赖一个基于 ES5 属性的 WeakMap shim。而0.9发布线将继续支持旧浏览器并尝试提供前向兼容的特性集——前提是你在迁移前消除所有弃用警告。发布管理方式的变化库的源文件为q.js仅适合作为 CommonJS即 Node.js模块消费发布产物由grunt构建生成包括适合以script标签引入的release/q.js以及适合作为 AMD 模块使用的release/amd/q.js所有新版本将发布到 S3。依赖变化Q 现在依赖asap包和 WeakMap shim使用 AMD 加载器时你需要自行引入这两个依赖以script方式使用时依赖已被内嵌进发布产物在 Node.js 中使用时依赖由npm自动处理。从 q.js 源码可以印证这一点它直接require(collections/shim)、require(collections/weak-map)和require(asap)而 package.json 的dependencies字段正是asap: ^1.0.0与collections: 2.0.1 3.0.0。生成器与函数调用接口的调整撤销了对 SpiderMonkey 风格生成器的支持仅支持 ES6 生成器fapply、fcall、fbind在Q和promise两种形式下均被弃用由Promise原型上的apply、call、bind取代无参数的Q.fbind场景由Q.function取代它更适合装饰方法/函数以确保其返回 promise 并捕获错误无附加参数的Q.fcall场景由Q.try取代Q.try不再是fcall的别名且不接受附加参数若要以参数调用函数 promise请使用Q(function).call(thisp, ...args)或apply。协议与集合方法的收紧post被弃用如需将参数展开到invoke中可以调用invoke.apply或直接使用promise.dispatch(invoke, [name, args])Q.all不再复用输入数组作为输出数组Q.all和Q.allSettled不再接受 promise 作为参数应改用Q(promise).all()或.allSettled()原有行为被弃用valueOf被移除请改用inspect().valuepromise 协议不再支持 set、delete、apply 操作函数应用是post以未定义方法名加一个thisp参数的特例when 消息现在改名为 then。因此本版本与 Q-Connectionv0.5不兼容旧的进度通知系统被移除改用新的预计完成时间特性。Node.js 桥接的收紧denodeify现在只接受被装饰的函数不再部分应用参数第二个参数决定装饰后的函数需要变长参数variadic还是具名参数named的 nodebackmakeNodeResolver不再隐式地将变长参数收集进数组用户必须传入true来以变长参数数组解析或传入一个名称数组来以包含对应属性的对象解析。新增能力promise 现在支持恶性循环检测vicious cycle detection如果 deferred promise 最终依赖于自身的解析它将以单例的 vicious cycle 错误被拒绝新增Q.push与promise.pull以及用于将本地/远程对象标记为可跨 Q Connection 传输的Q.isPortable新增promise.iterate用于请求一个远程迭代器的 promise。新的 Promise 构造函数2.0 引入了一个支持两种形态的Promise构造函数new Promise(callback(resolve, reject))与new Promise(promiseHandler)。promise handler 是一个新概念将作为未来可扩展性的基础。该构造函数被设计为至少兼容 ECMAScript 6 的Promise。本次引入的 API 包括Promise(setup(resolve, reject))用于构造各种类型的 promisePromise.resolve用于将值强制转换为 promise、包装 thenable、以及透传其他 promise。从 q.js 的实现可以看到构造函数是如何运转的它内部创建一个 deferred获取其 handler然后在 try/catch 中执行setup(deferred.resolve, deferred.reject, deferred.setEstimate)若 setup 抛错则自动 reject从而保证构造器回调中的异常不会丢失。进度跟踪预计完成时间Estimated Time to Completion2.0 用一套更完善的机制替代了旧的进度通知追踪预计完成时间。这允许 promise 从多个 promise 组合出聚合估计值特别是Q.all会采用其中最长的估计作为自身的估计。then方法现在可以接受一个毫秒数替代原来的progress函数表示 fulfillment handler 预期需要多少毫秒来解析。新接口的完整用法原文示例var promise new Q.Promise(function (resolve, reject, setEstimate) { setTimeout(resolve, 1000); setEstimate(Date.now() 1000); }); // 或 var deferred Q.defer(); setTimeout(deferred.resolve, 1000); deferred.setEstimate(Date.now() 1000); var promise deferred.promise; var estimate promise.getEstimate(); // now 1s promise.observeEstimate(function (estimate) { // estimate now 1s });observeEstimate会在自己的事件中收到一次初始通知此后每当setEstimate发出更新时再次收到通知setEstimate不会同步派发通知。进度比例与估计时间的互相换算预计完成时间的更新可以结合开始时间与当前时间换算为进度比例progress (now - start) / (estimate - start)反过来如果一个 promise 知道自己的进度百分比例如已下载字节数除以内容总长度和开始时间就可以更新预计完成时间estimate start (now - start) / progress关于兼容性旧的进度通知 API包括deferred.notify和then(f, r, progress)不会报错但也不会再发送任何通知。该特性未来可能以状态通知系统的形式部分恢复但行为大概率会改变。源码层面的佐证位于 q.jsQ.all内部维护一个estimates数组对每个输入 promise 调用observeEstimate当新估计大于当前最大值时更新并在所有估计就绪后通过deferred.setEstimate(estimate)发布聚合估计。这正是文档所说Q.all采用最长估计的实现细节。Node.js 桥接收缩到三个核心方法Q 1 时代提供了种类繁多的n*系列方法用于桥接 Node.js但实际使用率很低。2.0 将 Node.js 桥接收缩到三个核心 APIpromise.nodeify、Q.denodeify与Q.ninvoke。denodeify的行为被调整为与 RSVP.js 的denodeify一致。Q v1 中的旧版会在 nodeback 被传入多于一个非错误参数时推断方法接受变长参数这留下了明显的歧义。新接口通过denodeify的第二个参数来明确决定行为省略第二参数得到常规的 Node.js 风格回调传入true得到变长参数收集为数组传入一个名称数组参数将以各自名称被收集到一个对象字面量上。// 省略第二参数常规 Node 风格回调 Q.denodeify(fs.readFile)(path, utf-8) .then(function (contents) { /* contents 为单值 */ }); // 传入 true变长参数收集为数组 Q.denodeify(callbackStyleFn, true)(args) .then(function (valuesArray) { /* 数组 */ }); // 传入名称数组收集为具名对象 Q.denodeify(callbackStyleFn, [a, b])(args) .then(function (obj) { /* { a: ..., b: ... } */ });同时makeNodeResolver被弃用不再支持隐式的变长参数行为。弃用清单与迁移指引直接抛错的迁移 shim以下方法仅提供直接抛错的迁移 shimQ.set、promise.setQ.delete、promise.deleteQ.makePromise改用新的Promise构造函数与 promise handler移到 promise 原型上的方法以下Q方法被弃用改用promise原型上的对应方法thenResolve、thenReject、isPending、isFulfilled、isRejected、dispatch、get、post、invoke、keys其他弃用项弃用的旧 API推荐的替代Q.master不再需要Q.resolveQ或Promise.resolveQ.fulfillQ或Promise.resolveQ.isPromiseAlikeQ.isThenableQ.nearerpromise.inspectQ.fail/promise.failpromise.catchQ.fin/promise.finpromise.finallyQ.mapply/promise.mapplypromise.postQ.send/promise.sendpromise.invokeQ.mcall/promise.mcallpromise.invokeQ.promisenew Q.Promise传入函数Q.makePromisenew Q.Promise传入 handler 对象promise.fbindQ.fbindpromise.passByCopy()Q.passByCopy(promise)暂时性以下实验性别名也被弃用且在q/node中不存在nsend用于ninvoke、nmcall用于ninvoke、nmapply用于npost。版本演进脉络从 1.0/0.9 到早期原型CHANGES.md以完整的时间线记录了 Q 的整个演进过程理解这些历史有助于把握 2.0 各项变更的来龙去脉。1.0.0 与 0.9.7功能趋于稳定1.0.0 本质上是 0.9 的正式发布版0.9 已进入温和维护模式。0.9.7 引入了passByCopy、join和race修复了Q.async对 ES6 生成器实现的支持问题并将Q.all的进度通知传播为 ES6 迭代风格{value, index}。0.9.6 ~ 0.9.0向 TC39 并发方案靠拢0.9.6修复了旧版 Q promise 与新 inspect 机制的识别与强制转换问题重构了nextTick的微任务实现0.9.5引入inspect以{state: fulfilled | rejected | pending, value | reason}报告 promise 状态、allSettled、spawn长堆栈跟踪改为默认关闭需设置Q.longStackSupport true开启0.9.4isPromise/isPromiseAlike恒返回布尔值支持 ES6 生成器引入未处理拒绝 APIstopUnhandledRejectionTracking、getUnhandledReasons、resetUnhandledRejections0.9.3Q.timeout错误支持自定义消息在 Node.js 0.10 中改用setImmediate以避免调用栈爆栈。0.9.0API 清理与迁移对照表0.9.0 移除了一批已弃用或未文档化的方法CHANGES.md给出了完整的迁移对照表0.8.x 方法0.9 替代Q.refQcall、apply、bind*fcall/invoke、fapply/post、fbindncall、napply*nfcall/ninvoke、nfapply/npostenddoneputsetnodenbindnendnodeifyisResolvedisPendingdeferred.nodedeferred.makeNodeResolverMethod、senderdispatchersenddispatchview、viewInfo无注*不鼓励使用thisp调用方法时请使用post或invoke。同期的重要变化还包括Q 导出Q(value)函数作为resolve的别名长堆栈跟踪可通过Q.stackJumpLimit 0关闭Node.js 进程退出时若有未处理拒绝会输出到控制台delete/set不再有 fulfillment 值Q promise 不再被冻结以获得 V8 性能收益新增thenReject作为thenResolve的对应物。更早期的原型阶段0.8.x ~ 0.1.x早期版本奠定了 Q 的核心概念基础了解它们可以解释为何 2.0 的某些 API 显得历史悠久0.8.x引入done、Q.onerror、thenResolve、nfcall/nfapply/nfbind、q/queue模块、allSettled雏形、长堆栈跟踪Q.timeout修复了拒绝时未清理定时器导致事件循环挂起的问题Q.all对已解析 promise 数组做了性能优化0.7.x移除report与asapfin的回调不再接收任何参数enqueue更名为nextTick0.6.0将ref导出为Q构造函数新增async装饰器用yield蹦床trampolinepromise0.5.x加入all、join、waitend作为链的终结方法使传播的拒绝被抛出以便 Node 输出堆栈0.4.xpromise 原型增加end支持 RequireJSq.js 可作为脚本使用并创建全局Q0.3.0post恢复为双参数签名与 Tyler Close 的ref_sendAPI 一致新增变长invokePromise构造函数更名为makePromise0.2.xthenable带then方法的对象被接受使 Q 符合 Promises/A、B、D 规范promise 被定义为 duck-type实现promiseSend(op, resolved, ...)与valueOf的对象多个 Q 实例可以交换 promise 对象拒绝也被 duck-typed0.1.x补充 ES5Object.create/Object.freezeshim、isRejected、isResolved等基础能力。实践要点如何安全地在依赖 Q 的项目中升级结合CHANGES.md的警告与 wwi-app 的实际用法可以总结出针对依赖 Q 的前端应用的升级要点评估运行环境升级到 1.0 要求 ECMAScript 5 与 WeakMap 支持无法满足的旧浏览器请停留在 0.9 发布线逐一消除弃用警告0.9 线提供了前向兼容的特性集前提是迁移前清理所有弃用调用2.0 中的弃用项在 v3 会被彻底删除越早迁移成本越低区分消费方式Node.js 场景使用 CommonJS 的q.js并依赖 npm 管理asap/collections浏览器script场景使用内嵌依赖的发布版AMD 场景需自行引入asap与 WeakMap shim重写then回调链把progress回调参数改为毫秒数handler 预期耗时把fail/fin改为catch/finally更新 Node 风格函数装饰denodeify(fn, true)或denodeify(fn, [a,b])显式声明变长/具名参数消除旧版隐式推断的歧义。如需深入了解 Q 的更多设计文档仓库内还保留了 q.js约 1800 行的完整实现、README.md、VERSIONS.md 以及 ref_send.md 协议说明测试用例集中在 test/含 Promises/A 适配器aplus-adapter.js与预计完成时间测试eta-test.js可作为进一步研究的入口。【免费下载链接】sql-server-samplesAzure Data SQL Samples - Official Microsoft GitHub Repository containing code samples for SQL Server, Azure SQL, Azure Synapse, and Azure SQL Edge项目地址: https://gitcode.com/gh_mirrors/sq/sql-server-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考