just 系列教程:just-map-values 对象值映射工具——用法、参数语义与源码级实现解析

原创2026-10-14 17:50:041,434 阅读
文章标签:开发工具

just 系列教程:just-map-values 对象值映射工具——用法、参数语义与源码级实现解析

本文以 just 工具库中的 just-map-values 包为核心,讲解它的安装方式、map(obj, predicate) 的三个回调参数(value、key、object)语义、TypeScript 类型约束,以及零依赖实现背后的细节:不修改原对象、只遍历自有可枚举属性、数组入参的处理行为等。读完你可以直接在 ES Module / CommonJS / 原生浏览器环境中引入该工具,理解它与 just-map-object 等相邻工具的取舍,并在代码库中快速完成对象值的批量转换。

一、模块定位:只做一件事的零依赖工具

just-map-values 是 just 系列"零依赖 npm 模块、每个模块只做一件事"(a library of zero-dependency npm modules that do just one thing)的一部分。它的官方一句话描述是:

Map an object, predicate updates values, receives (value, key, object)

即用回调函数(predicate)对对象的每个值进行更新,回调依次接收当前值、键名和整个对象三个参数,并返回一个新的对象,原对象保持不变。

根据 包清单,该包当前版本为 3.2.0,"type": "module",依赖数为零,采用 MIT 许可(见 LICENSE)。它同时提供 ES Module 与 CommonJS 两种产物,无需转译即可直接消费:

// esm (node / bundler)
import map from 'just-map-values';

// esm (原生浏览器,直接引用 mjs 文件)
import map from './node_modules/just-map-values/index.mjs';

// cjs
const map = require('just-map-values');

仓库中通过 exports 字段 完成了这一约定:

"exports": {
  ".": {
    "types": "./index.d.ts",
    "require": "./index.cjs",
    "import": "./index.mjs"
  }
}

也就是说:import 语句命中 index.mjs,require 命中 index.cjs,TypeScript 则读取 index.d.ts。仓库根 README.md 给出的平台支持表格中,Node 6.0 以上、Chrome 46+、Safari 8+、Firefox 16+、Edge 12+ 均可运行 just 系列的大部分工具,该工具的 ES5 级实现(见下文源码)也符合这一兼容性基线。

二、安装与基本用法

安装命令(摘自 packages/object-map-values/README.md):

npm install just-map-values
yarn add just-map-values

基本用法完整示例:

import map from 'just-map-values';

// predicate updates values, receives (value, key, obj)
map({a: 3, b: 5, c: 9}, (value) => value + 1); // {a: 4, b: 6, c: 10}
map({a: 3, b: 5, c: 9}, (value, key) => value + key); // {a: '3a', b: '5b', c: '9c'}
map({a: 3, b: 5, c: 9}, (value, key, obj) => obj.b); // {a: 5, b: 5, c: 5}

三个回调参数覆盖了三类典型场景:

  1. 只看值:(value) => value + 1,对每个值做统一变换(加 1、类型转换、格式化等);
  2. 值 + 键:(value, key) => value + key,把键名拼进新值。注意 value + key 中 number 与 string 拼接,得到的是字符串结果,如 '3a';
  3. 值 + 键 + 完整对象:(value, key, obj) => obj.b,回调可以访问整个原始对象,上例结果是把所有值都替换为 b 键对应的值 5。

第三个参数尤其有用——它让"依据对象中另一个字段的值来改写当前字段"这类逻辑成为可能,无需在回调外捕获额外上下文。

三、回调参数与 TypeScript 类型定义

index.d.ts 给出了完整的类型签名:

declare function mapValues<T, U = T>(
  item: Record<string, T>,
  callback: (value: T, key: string, object: Record<string, T>) => U
): Record<string, U>;

export default mapValues;

类型层面值得注意的三点:

  • 两个泛型 T 与 U:T 是输入对象值的类型,U 是输出值的类型且默认等于 T。因此 map({ a: 1 }, (value) => value + 1) 的返回类型是 Record<string, number>,而把值映射为其他类型(如 string[]、boolean)时 U 会被自动推断;
  • 输入是 Record<string, T>:即"字符串键 → T"的对象形态。数组虽然也有字符串索引,但从类型签名看该工具面向普通对象;
  • 回调形参是 (value, key, object),与 Array.prototype.map 的 (element, index, array) 顺序一致,值在前、键在后。这是理解它与相邻工具 just-map-object 差异的关键(见第六节)。

对应的 TypeScript 测试位于 index.tests.ts,既验证了合法用法,也通过 @ts-expect-error 锁定了非法用法:

// OK —— 输出类型 U 被正确推断
const test1: Record<string, string[]> = map({ a: "string" }, (value) =>
  value.split("")
);
const test2: Record<string, string> = map(
  { a: "string" },
  (value, key) => key + value
);
const test3: Record<string, boolean> = map(
  { a: "string", string: "a", b: "string" },
  (value, key, obj) => obj[value] === key
);

// Not OK —— 以下调用都会被类型系统拒绝
// @ts-expect-error
const test4: Record<string, string> = map({ foo: 1 }, (value) => value + 1);
// @ts-expect-error
map();
// @ts-expect-error
map({ foo: 1 });
// @ts-expect-error
map((value: string) => {});
// @ts-expect-error
map({ foo: 1 }, "");
// @ts-expect-error
map({ foo: 1 }, {});
// @ts-expect-error
map({ a: 1 }, (value: string) => {});

从中可以读出约束边界:必须传两个参数(对象 + 函数);回调必须是函数,不能是字符串或对象;输入值类型与回调形参声明的类型不一致时也会报错(最后一个用例中 { a: 1 } 的值是 number,回调却声明 (value: string),类型不匹配)。

四、源码实现:10 行代码的核心逻辑

index.mjs(CJS 版 index.cjs 逻辑完全相同,仅导出方式不同)的实现如下:

function map(obj, predicate) {
  var result = {};
  var keys = Object.keys(obj);
  var len = keys.length;
  for (var i = 0; i < len; i++) {
    var key = keys[i];
    result[key] = predicate(obj[key], key, obj);
  }
  return result;
}

export {objectMapValues as default};

从源码结构看,这段实现体现了几个明确的行为语义:

  • 不修改原对象:新建空对象 result,逐个写入,最后返回。原 obj 完全不变,属于纯函数式的"映射"而非"就地更新";
  • 只处理自有可枚举属性:使用 Object.keys(obj) 收集键名,因此原型链上的属性、不可枚举属性都不会出现在结果中;
  • 键保持不变:循环中 result[key] 沿用原键名,只有值被 predicate(obj[key], key, obj) 的返回值替换。这与 just-map-keys(更新键、保留值)形成互补;
  • 属性顺序稳定:按 Object.keys 返回的顺序写入,对普通对象(字符串键)即为插入顺序,结果对象中键的排列与源对象一致;
  • ES5 兼容写法:var 声明与 for 循环,不依赖任何 ES2015+ 语法,与 just 系列宣称的平台支持基线一致。

仓库中 index.mjs 与 index.cjs 的对应关系还体现在构建配置上:rollup.config.js 引用根目录的 createRollupConfig,后者以 index.cjs 为输入、经 @rollup/plugin-commonjs 转换后输出 ESM 格式的 index.mjs。也就是说,CJS 源文件是这个包的单一事实来源,ESM 版本由构建派生。

五、运行期测试用例:数组入参与三参数的实际表现

目录 test/object-map-values/index.cjs 中的测试覆盖了三类回调参数,并补充了 README 未展示的行为边界。该测试复用仓库自带的断言工具 test/util/test.js,并借助 just-compare(packages/collection-compare)做深比较。

只用 value 参数:

var obj1 = {a: 3, b: 5, c: 9};
var result1 = map(obj1, function(value) {
  return value + 1;
});
t.ok(compare(result1, {a: 4, b: 6, c: 10}));

var obj2 = {a: 3, b: 0, c: null};
var result2 = map(obj2, function(value) {
  return Boolean(value);
});
t.ok(compare(result2, {a: true, b: false, c: false}));

第二个例子说明:0、null 等假值会原样传给回调(不会被跳过),返回值由回调决定——这里 Boolean(value) 把整个对象映射为布尔值对象。

使用 key 参数(含数组入参):

var obj2 = [1, 2, 3];
var result2 = map(obj2, function(value, key) {
  return Boolean(Number(key)) || key;
});
t.ok(compare(result2, {0: '0', 1: true, 2: true}));

这一段揭示了运行期行为:数组也是对象,Object.keys([1, 2, 3]) 返回 ['0', '1', '2'],因此 map 可以把数组"打散"为以索引字符串为键的普通对象(键 0 因 Number('0') 为假值而保留原字符串 '0',键 '1'、'2' 则被映射为 true)。从源码结构看,实现并未对输入类型做对象/数组区分,数组入参会得到这种"索引键对象"结果——如果你期望的是保持数组形态的转换,应选用 just 的 array 系列工具。

value 与 key 组合:

var result1 = map(obj1, function(value, key) {
  return key + value;
});
t.ok(compare(result1, {a: 'a3', b: 'b5', c: 'c9'}));

三个参数全用:

var result1 = map(obj1, function(value, key, obj) {
  return obj['b'] + value + key;
});
t.ok(compare(result1, {a: '8a', b: '10b', c: '14c'}));

第三个参数 obj 是完整的原始对象,可以在回调中引用其他键的值(这里 obj['b'] 恒为 5),验证了"跨字段派生"这一典型用途。

六、与相邻工具的取舍:map-values vs map-object vs deep-map-values

just 的 Objects 模块清单 里与"映射"相关的工具有多个,理解它们的参数顺序差异可以避免误用:

  • just-map-values(本文主角):回调为 (value, key, object),更新值,键保持不变。参数顺序与 Array.prototype.map 一致(值/元素在前)。
  • just-map-object:回调为 (key, value),键在前、值在后。它的 README 中已明确标注 // DEPRECATED: use just-map-values,即官方建议新项目直接改用 just-map-values 的 (value, key, object) 签名。源码对比 packages/object-map/index.mjs 与本文的 index.mjs 可见,两者结构几乎一致,唯一区别在回调调用行:predicate(key, obj[key]) vs predicate(obj[key], key, obj)。
  • just-map-keys:回调同为 (value, key, object),但更新的是键,值保持不变。
  • just-deep-map-values:对所有深度的值做映射,回调只有一个参数((number) => number * number),适用于嵌套对象的递归变换。

选择建议:只做一层的值变换用 just-map-values;要重写键名用 just-map-keys;对象嵌套多层、需要对任意深度的值统一变换时用 just-deep-map-values;已存在代码若用了 just-map-object,迁移到 just-map-values 时注意把回调参数顺序从 (key, value) 调整为 (value, key)。

七、版本沿革

CHANGELOG.md 记录了该包的发布轨迹:

版本 变更
3.2.0 Rename node module .js → .cjs(CJS 产物文件扩展名规范化)
3.1.1 fix: reorder exports to set default last #488
3.1.0 package.json updates to fix #467 and #483

3.2.0 的 .js → .cjs 重命名与 package.json 中的 "main": "index.cjs"、exports.require 指向相印证:由于包声明了 "type": "module",.cjs 扩展名是 CommonJS 产物在 ESM 包内被正确识别的必要条件。

八、小结与可复现的验证路径

  • 功能:返回一个新对象,其中每个值由 predicate(value, key, object) 的返回值替换,键保持不变,原对象不被修改(index.mjs 第 11–20 行的实现即为全部逻辑);
  • 多格式消费:import / require / 浏览器直引 .mjs 三条路径均由 package.json 的 exports 字段保障;
  • 类型安全:泛型 T/U 使输入输出类型各自独立推断,非法调用在编译期即被拦截(index.tests.ts 中六处 @ts-expect-error 可作核对基准);
  • 行为边界:假值会传给回调、数组入参会被映射为索引键对象,均有 test/object-map-values/index.cjs 中的用例佐证。

如需在本地复现验证,可以安装依赖后直接引用仓库内的包目录运行示例,例如将 import map from '../../packages/object-map-values/index.mjs' 放入一个临时脚本执行,再对照本文第二节、第五节的期望输出逐项核对。

登录后查看全文
just