just 项目 just-percentile 包：百分位数（线性插值）算法实现与版本演进解读

开发工具【免费下载链接】justA library of dependency-free JavaScript utilities that do just one thing.项目地址https://gitcode.com/gh_mirrors/jus/just点击查看免费下载导读本文围绕 just 仓库中just-percentile包CHANGELOG.md展开从它的核心算法基于 NIST 规范的线性插值百分位数、参数校验与错误处理到 ESM/CJS 双格式构建与版本迭代脉络逐层拆解一个零依赖统计工具包的实现细节。读完本文你将能够看懂percentile([15, 20, 35, 40, 50], 0.4)为何返回 29 而非 27.5 的计算过程理解 R7 排序公式与 NIST 规范的关系以及该包 4.0.0 → 4.2.0 三个版本的演进动机并能在自己的项目中正确使用它。just-percentile是 just 库README.md中 90 多个零依赖工具包的一员职责单一——return the value at the given percentile (using linear interpolation)见 package.json 描述字段。它的完整源码见 index.cjs类型声明见 index.d.ts测试用例见 test/array-percentile/index.cjs。一、版本演进主线4.0.0 → 4.2.0关联文档 CHANGELOG.md 完整记录了该包从 4.0.0 到 4.2.0 的四个版本变更按时间逆序排列。梳理如下版本类型变更内容影响面4.2.0Minor将 Node 模块文件从.js重命名为.cjs包结构与构建4.1.1Patch重排序导出将 default 导出放在最后关联 issue #488ESM 构建产物4.1.0Minorpackage.json 更新修复 issue #467 与 #483包元数据4.0.0Major仅影响 .mjs将新的百分位数算法同步到 ESM 版本关联 PR #318算法行为结合当前仓库实际内容可以进一步印证4.2.0 的重命名已落地当前包目录下同时存在 index.cjs 与 index.mjs且 package.json 中main字段指向index.cjsexports字段通过require: ./index.cjs/import: ./index.mjs实现了 CommonJS 与 ES Module 双格式的按条件分发。4.1.1 的导出重排已体现在 index.mjs 中函数定义在前export {arrayPercentile as default}位于文件最末一行正是default 导出放最后的实现形态。4.0.0 的算法同步已收敛当前 index.cjs 与 index.mjs 的算法主体完全一致——两者都注释为// Percentile (Exlusive) from the nist spec注意源码中 Exlusive 为原始拼写且逐行计算结果相同下文实测可验证。这说明 4.0.0 的 Major 变更旨在消除 CJS 与 ESM 两套产物之间的行为差异4.1.1 的导出重排则是对构建产物的进一步打磨。值得一提的是仓库中的大部分包都遵循同一套 CHANGELOG 结构与构建脚本just-percentile的演进路径也是 just 仓库整体工程化的缩影。二、算法核心NIST 规范的线性插值百分位数2.1 两种百分位计算范式计算百分位数主要有两条路线就近取值nearest-rank找到目标名次rank后直接返回对应元素不做插值结果必然落在数据集的某个原始值上。线性插值linear interpolation当目标名次落在两个相邻数据点之间时按小数部分在两者之间做线性内插结果可以不是数据集中的原始值。just-percentile采用第二种这正是其 README 描述 using linear interpolationREADME.md的含义。它参照的是 NIST Engineering Statistics Handbook 中定义的R7 排序公式percentile的定义见 index.d.ts 的注释Uses R7 formula described in the nist specR7 也是 Excel 的PERCENTILE函数所采用的估计量类型。2.2 从源码拆解计算流程核心实现 的完整流程如下// Percentile (Exlusive) from the nist spec function percentile(arr, percentage) { if (!Array.isArray(arr)) { throw new Error(the first argument to percentile must be an array); } if (percentage 0 || percentage 1) { throw new Error(The percent must be between 0 and 1); } if (!arr.length) { throw new Error(no values were passed to percentile); } //sort doesnt call if length is one. need to check explicitly. if (arr.length 1 !Number.isFinite(arr[0])) { throw new Error(numericError); } var sorted arr.sort(function(a, b) { if (!Number.isFinite(a)) { throw new Error(numericError); } return a - b; }); var rank percentage * (arr.length - 1) 1; var rankInt Math.floor(rank); var rankFrac rank - rankInt; if(rank 0) { return arr[0]; } if(rank arr.length) { return arr[arr.length - 1]; } var upper sorted[rankInt]; var lower sorted[rankInt - 1]; return (lower rankFrac * (upper - lower)); }计算分为三步第一步排序。直接调用原生Array.prototype.sort并传入数字比较器a - b把原数组原地升序排序。需要特别留意的是该函数会就地修改传入的数组——实测percentile([5, 4, 1, 3, 2], 0.5)调用结束后原数组已变为[1, 2, 3, 4, 5]。如果调用方需要保留原始数据应先拷贝一份例如[...arr]再传入。第二步计算名次rank。采用 R7 公式rank percentage * (arr.length - 1) 1然后把 rank 拆成整数部分rankInt与小数部分rankFracrankInt Math.floor(rank)——命中的下界索引rankFrac rank - rankInt——线性插值的权重。第三步线性插值。当0 rank arr.length时取lower sorted[rankInt - 1]、upper sorted[rankInt]返回lower rankFrac * (upper - lower)两个边界条件单独处理rank 0时直接返回arr[0]rank arr.length时直接返回末元素。2.3 一个容易误读的细节为什么0.4返回 29 而不是 27.5README 中给出的示例README.md是percentile([15, 20, 35, 40, 50], 0.05); // 15 percentile([15, 20, 35, 40, 50], 0.3); // 20 percentile([15, 20, 35, 40, 50], 0.4); // 27.5 percentile([15, 20, 35, 40, 50], 0.95); // 50而类型声明注释index.d.ts里写的是percentile([15, 20, 35, 40, 50], .40); // 26我在本机实际运行当前仓库的 index.cjs 得到的结果是percentile([15, 20, 35, 40, 50], 0.4) // 29 percentile([15, 20, 35, 40, 50], 0.3) // 23 percentile([15, 20, 35, 40, 50], 0.05) // 16 percentile([15, 20, 35, 40, 50], 0.95) // 48README 的注释、类型声明注释与当前实现三者并不完全一致——这是该包文档与代码之间存在偏差的真实情况动手实践时请以当前源码的实际输出为准。不过测试套件test/array-percentile/index.cjs中的断言与当前实现是完全自洽的例如t.equal(percentile([1, 2, 3, 4, 5], 0.15).toFixed(2), 1.60); t.equal(percentile([5, 4, 1, 3, 2], 0.35).toFixed(2), 2.40); t.equal(percentile([100, 101, 92, 4, 102, 66, 66], 0.65).toFixed(2), 99.20);这些断言展示了三个典型场景目标名次落在两个索引之间时的插值结果如0.15 → 1.60、重复值数据集如三个 66、以及含负数的数据集。此外仓库还内置了 NIST 规范文档中的标准数据集校验test/array-percentile/index.cjsvar values [ 95.1772, 95.1567, 95.1937, 95.1959, 95.1442, 95.0610, 95.1591, 95.1195, 95.1065, 95.0925, 95.1990, 95.1682, ]; var expectedPercentile 95.1957; t.equal(percentile(values, 0.90).toFixed(4), expectedPercentile);实测当前实现输出95.1957与预期完全吻合证明该实现与 NIST 规范参考值一致。三、参数校验与错误处理源码级just-percentile对非法输入采取快速失败策略全部通过显式throw new Error(...)实现共有四类错误信息触发条件错误信息对应源码位置第一个参数不是数组the first argument to percentile must be an arrayindex.cjs百分位参数超出[0, 1]The percent must be between 0 and 1index.cjs数组为空no values were passed to percentileindex.cjs元素不是有限数值all values passed to percentile must be numeric即numericError变量index.cjs逐一拆解这些校验的边界情况非数组参数percentile(1, 2, 3, 50)、percentile(null, 0.4)、percentile(undefined, 0.66)都会触发第一条错误。README 中也专门标注了这类反例README.md。空数组percentile([], 0.5)触发no values were passed to percentile。注意测试中还有percentile([], 1.5)这种空数组 越界百分位的组合由于空数组校验在百分位校验之后、且两处都抛错最终仍会以抛错告终先命中越界百分位。非数值元素校验依赖Number.isFinite因此2这种数字字符串、false/true布尔值、对象{}、以及Infinity都会被拒绝。单元素数组的隐式边界源码注释特别说明了//sort doesnt call if length is one. need to check explicitly.——原生sort在数组长度为 1 时不会调用比较器因此排序阶段对非数值的校验会漏检实现里对arr.length 1 !Number.isFinite(arr[0])做了显式提前校验。这是阅读源码时容易忽略的一个细节。百分位参数 NaNpercentage 0 || percentage 1对NaN恒为 false因此NaN会绕过校验最终使结果为NaN。这是实现的一个已知边界行为使用时请自行保证百分位是[0, 1]内的有限数值。测试套件test/array-percentile/index.cjs用t.throws覆盖了以上全部非法场景类型层面index.tests.ts 则用ts-expect-error标注了非数组、混合类型数组等应在编译期被拒绝的调用。四、ESM/CJS 双格式构建机制与 4.1.1/4.2.0 变更的落点4.1 双格式产物从何而来just-percentile的三种分发文件各有分工index.cjs——手写的 CommonJS 实现module.exports percentile是算法的事实来源source of truthindex.mjs——构建生成的 ES Module 版本末尾export {arrayPercentile as default}index.d.ts——TypeScript 类型声明为percentile(arr: number[], percentage: number): number。ESM 产物并非手写而是通过 Rollup 从 CJS 自动生成。构建入口是 packages/array-percentile/rollup.config.js它调用仓库共享的 config/createRollupConfig.jsmodule.exports function createRollupConfig(path) { return { input: resolve(path, ./index.cjs), output: { file: resolve(path, ./index.mjs), format: esm, }, plugins: [cjs()], }; };即以index.cjs为输入通过rollup/plugin-commonjs把 CommonJS 包装代码转换为 ESM 输出.js → .cjs的命名变化正是 4.2.0 的 Minor 变更内容。4.2 双格式的行为一致性我分别用require()加载 index.cjs、用动态import()加载 index.mjs对同一组输入做了对比实测CJS percentile([15,20,35,40,50], 0.4) // 29 ESM percentile([15,20,35,40,50], 0.4) // 29两者输出完全一致印证了 4.0.0 中将新算法同步到 .mjs的变更目标——消除历史遗留的 CJS/ESM 行为差异。同时index.mjs 中export语句位于文件末尾、var arrayPercentile percentile;的临时变量命名也与 4.1.1 reorder exports to set default last 的变更描述对应。4.3 package.json 的条件导出package.json 通过exports字段实现按环境分发{ name: just-percentile, version: 4.2.0, description: return the value at the given percentile (using linear interpolation), type: module, exports: { .: { types: ./index.d.ts, require: ./index.cjs, import: ./index.mjs }, ./package.json: ./package.json }, main: index.cjs, types: index.d.ts }type: module声明包默认按 ESM 解释import条件指向index.mjsrequire条件指向index.cjsNode.js 会按调用方的模块系统自动选择main与types字段保留了向后兼容的入口。这也是 4.1.0 中 package.json updates to fix #467 and #483 所完善的工程化配置。五、安装与使用5.1 安装两种包管理器任选README.mdnpm install just-percentileyarn add just-percentile仓库内的just-percentile是 just monorepolerna.json下的一个工作区包上述命令会安装 npm 上独立发布的同名包若要在本仓库内直接引用本地实现CommonJS 环境可require(../../packages/array-percentile)测试套件正是这样引用的见 test/array-percentile/index.cjs。5.2 基础用法import percentile from just-percentile; percentile([1, 2, 3], 0); // 1 percentile([1, 2, 3], 0.5); // 2 percentile([1, 2, 3], 1); // 3CommonJS 环境则使用const percentile require(just-percentile);5.3 典型反例会抛错percentile(1, 2, 3, 50); // throws第一个参数必须是数组 percentile([1, 2, 3], 50); // throws元素必须是有限数值 percentile([], 50); // throws空数组六、实践要点小结综合源码、测试与实测使用just-percentile时有几个值得记住的要点百分位参数是[0, 1]内的小数0.5表示 50 分位不要传50。输入数组会被原地排序。需要保留原数据时先拷贝例如percentile([...data], 0.9)。结果可能不是数据集的原始值。线性插值决定了结果可以是介于两个数据点之间的浮点数判断结果时应允许精度误差测试里普遍用.toFixed(2)或.toFixed(4)断言。结果会随版本变化。从 CHANGELOG 可知4.0.0 之前的 .mjs 版本使用过不同的算法README、类型注释与当前实现之间的示例数值也存在历史偏差线上环境务必以实际安装版本的输出为准。错误信息稳定可依赖。四类错误消息固定便于在业务代码中通过error.message区分失败原因。在 just 库的统计分析家族中just-percentile与 array-mean 等工具一样保持零依赖、单一职责与 MIT 许可LICENSE适合直接嵌入数据统计、性能监控分位数如 P50/P90/P95等场景。赞分享开发工具【免费下载链接】justA library of dependency-free JavaScript utilities that do just one thing.项目地址https://gitcode.com/gh_mirrors/jus/just点击查看免费下载相关推荐just 仓库版本演进解析从 CHANGELOG 读懂 just-cartesian-product 的三次关键变更与双模块打包实现just 仓库版本演进解析从 CHANGELOG 读懂 just cartesian product 的三次关键变更与双模块打包实现 本篇以 packages开发工具30 Seconds of CodeJavaScript 百分位计算percentile实现与原理详解30 Seconds of CodeJavaScript 百分位计算percentile实现与原理详解 导读 在 30 Seconds of Code 项教程文档just-partition 使用指南与版本演进解析零依赖数组分区工具的实现与维护just partition 使用指南与版本演进解析零依赖数组分区工具的实现与维护 just partition 是 just 库中一个零依赖、只做一件事的数开发工具上一篇React-Countdown部署指南从开发到生产的完整构建流程下一篇gh_mirrors/eng/eng-practices实战案例代码审查评论处理技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考