深入解析 just 库的 just-map-object:对象键值映射的用法、源码实现与弃用迁移
深入解析 just 库的 just-map-object:对象键值映射的用法、源码实现与弃用迁移
just-map-object 是 just 库中一个零依赖的实用工具包,它“对对象的每个属性应用一个接收 (key, value) 的回调,并返回一个新对象”。本文以 packages/object-map/README.md 为主线,完整梳理该包的安装方式、API 契约与官方示例,再结合仓库源码深入剖析其遍历机制、类型系统约束,以及官方推荐的替代方案 just-map-values 的迁移方法,帮助你在项目中正确选型与安全升级。
一、包定位与安装
just 是一个“依赖为零、每个模块只做一件事”的 JavaScript 工具库集合(monorepo,根目录由 lerna.json 管理)。just-map-object 对应其中的 packages/object-map 子包,其职责单一:map an object, passing key and value to predicates(映射对象,将 key 和 value 传给谓词函数)。
安装方式(继承自 README):
npm install just-map-object
yarn add just-map-object
从 packages/object-map/package.json 可以看到该包的发布形态与模块解析规则:
| 字段 | 值 | 说明 |
|---|---|---|
name |
just-map-object |
npm 包名 |
version |
2.3.0 |
当前仓库版本 |
main |
index.cjs |
CommonJS 入口 |
module |
index.mjs |
ESM 入口 |
types |
index.d.ts |
TypeScript 类型声明 |
exports |
{ require: ./index.cjs, types: ./index.d.ts, default: ./index.mjs } |
同时支持 require 与 import 两种消费方式 |
dependencies |
(无) | 零运行时依赖 |
构建方面,每个子包通过 yarn build 触发 rollup -c,各包的 rollup.config.js 复用仓库共享的 config/createRollupConfig.js:以 index.cjs 为输入、index.mjs 为 ESM 输出。也就是说,index.cjs 是该包的“单一事实来源”,ESM 产物由它编译而来。
二、API 与官方示例(完整继承)
函数签名非常简洁:
map(obj, predicate)
// predicate 的实参顺序为 (key, value),返回值作为新对象的对应属性值
README 给出的全部官方示例如下(注意其中带有弃用提示,详见第五节):
import map from 'just-map-object';
// DEPRECATED: use just-map-values
map({a: 3, b: 5, c: 9}, (key, value) => value + 1); // {a: 4, b: 6, c: 10}
map({a: 3, b: 5, c: 9}, (key, value) => key); // {a: 'a', b: 'b', c: 'c'}
map({a: 3, b: 5, c: 9}, (key, value) => key + value); // {a: 'a3', b: 'b5', c: 'c9'}
三个示例分别展示了三类典型变换:
- 纯值变换:
(key, value) => value + 1—— key 被忽略,等价于“对所有值做映射”; - 以 key 覆盖 value:
(key, value) => key—— 结果对象的值变成各自的键名; - key 与 value 组合:
(key, value) => key + value—— 触发字符串拼接(数字与字符串相加),如3 + 'a'的顺序是'a' + 3,故得到'a3'。
关键语义:map 总是返回一个新对象,原对象不被修改;新对象的键集合与原对象完全一致,仅值被谓词替换。
三、源码实现逐行解析
map 的全部实现仅约 10 行,见 packages/object-map/index.mjs(index.cjs 中的 CommonJS 版本 逻辑完全相同):
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(key, obj[key]);
}
return result;
}
export {objectMap as default};
从源码结构可以提炼出以下行为特征:
- 遍历范围由
Object.keys决定。它只返回对象自身可枚举的字符串键:- 原型链上的继承属性不会被遍历;
Object.defineProperty定义的enumerable: false属性会被跳过;Symbol键不会被处理(需要Object.getOwnPropertySymbols才能枚举到)。
- 不修改原对象。新结果写入全新的
{}字面量对象,原对象引用关系保持不变,这在需要保留原始数据或做不可变更新时是重要保证。 - 空对象返回空对象。
map({}, fn)中Object.keys({})为[],循环不执行,直接返回{}。 - 无运行时参数校验。实现中没有对
obj是否为空对象/对象做防御;若传入undefined或null,错误会在Object.keys(obj)处以TypeError抛出。参数的“必须传两个参数”这一约束由类型层面保证(见下节)。 - 键顺序遵循
Object.keys的顺序。对于普通字符串键,即对象的插入顺序(整数样式的键会按升序优先排列,这是 JS 引擎的通用行为)。 - 谓词返回值原样落位。若谓词返回
undefined,对应属性值即为undefined;返回函数、对象等复杂值也原样保留,函数本身不做深拷贝。
四、TypeScript 类型与类型级测试
类型声明位于 packages/object-map/index.d.ts:
declare function map<T, U = T>(
item: Record<string, T>,
callback: (key: string, value: T) => U
): Record<string, U>;
export default map;
泛型设计有两个要点:
T推断自输入对象的值类型,回调第二个参数被静态绑定为(key: string, value: T);U的默认值等于T,因此“值类型不变”的映射(如value + 1作用在数字上)不需要显式标注返回类型;而值类型发生变化的映射(如返回布尔或字符串)则由U推断新类型。
仓库配套的 packages/object-map/index.test.ts 是一组类型级测试,用 @ts-expect-error 固化了合法与非法调用的边界:
// OK —— 合法调用
const test1: Record<string, boolean> = map(
{ primary: null, secondary: null },
(key) => key === "primary" // 只用到 key,回调参数可以少传
);
const test2: Record<string, number> = map(
{ primary: null, secondary: null },
(key) => key.length
);
const test3: Record<string, string> = map(
{ a: "pple" },
(key, value) => key + value
);
// Not OK —— 期望编译报错
// @ts-expect-error
const test4: Record<string, string> = map({ foo: 1 }, (_, value) => value + 1); // 返回 number 赋给 string
// @ts-expect-error
map(); // 参数缺失
// @ts-expect-error
map({ foo: 1 }); // 缺少 predicate
// @ts-expect-error
map((value) => {}); // 第一个参数不是对象
// @ts-expect-error
map({ foo: 1 }, ""); // predicate 不是函数
// @ts-expect-error
map({ foo: 1 }, {}); // predicate 不是函数
这份测试同时说明了类型契约的“宽”与“严”:回调可以少用参数(只用 key 也合法),但对返回类型不匹配、参数缺失、predicate 非函数等情形会被编译器拦截——运行时实现没有任何校验逻辑,这些约束全部由 .d.ts 提供。
五、重要提示:已标记弃用,官方推荐 just-map-values
README 的示例注释中明确写着 // DEPRECATED: use just-map-values,仓库中 md-variables.json 的生成变量同样包含该弃用说明。也就是说:just-map-object 仍随 monorepo 一起维护和发版,但官方建议新代码改用 just-map-values。
两者都在对对象值做映射,核心区别在回调实参顺序:
| 维度 | just-map-object(packages/object-map) | just-map-values(packages/object-map-values) |
|---|---|---|
| 回调实参 | (key, value) |
(value, key, object) |
| 变换对象 | 值(键不变) | 值(键不变) |
| 能否访问整个原对象 | 不能 | 能(第三个参数 object) |
| README 状态 | 标记 DEPRECATED | 官方推荐 |
just-map-values 的实现见 packages/object-map-values/index.mjs,循环体为 result<a href="https://link.gitcode.com/i/26765bc7d92609100b93528f0fed8193" target="_blank">key] = predicate(obj[key], key, obj),其余遍历机制与 just-map-object 完全一致。其 [README 示例:
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}
迁移方法:把回调实参顺序从 (key, value) 调整为 (value, key),并替换包名:
// 迁移前
import map from 'just-map-object';
map({a: 3, b: 5, c: 9}, (key, value) => key + value); // {a: 'a3', b: 'b5', c: 'c9'}
// 迁移后
import map from 'just-map-values';
map({a: 3, b: 5, c: 9}, (value, key) => key + value); // {a: 'a3', b: 'b5', c: 'c9'}
此外,just 库还有第三个近亲模块 just-map-keys(packages/object-map-keys/index.mjs):它同样接收 (value, key, object),但用回调返回值替换键名、保留原值(result[newKey] = value)。三者构成“值映射(旧签名)/ 值映射(新签名)/ 键映射”的完整矩阵,可按需选择。
六、版本与维护状态
从 packages/object-map/CHANGELOG.md 可以追溯该包的发布轨迹:
2.3.0:node 模块文件由.js更名为.cjs(即当前仓库中index.cjs的由来);2.2.1:调整导出顺序,将 default 导出置于最后;2.2.0:package.json相关修复(对应 monorepo 层面的导出问题);2.1.1:补充类型声明。
可以推断:包虽被 README 标记弃用,但仍跟随 just monorepo 的整体发版节奏维护(当前版本 2.3.0)。对存量代码,just-map-object 在 2.x 版本下按本文描述的行为继续可用;对新增功能,按官方建议优先选择 just-map-values。
七、关键文件索引
| 内容 | 相对路径 |
|---|---|
| 包 README(本文主线文档) | packages/object-map/README.md |
| ESM 入口实现 | packages/object-map/index.mjs |
| CommonJS 入口实现 | packages/object-map/index.cjs |
| TypeScript 类型声明 | packages/object-map/index.d.ts |
| 类型级测试 | packages/object-map/index.test.ts |
| 包元信息(版本/exports/构建脚本) | packages/object-map/package.json |
| 版本变更日志 | packages/object-map/CHANGELOG.md |
| 子包 Rollup 配置 | packages/object-map/rollup.config.js |
| 共享 Rollup 配置工厂 | config/createRollupConfig.js |
| 推荐替代:just-map-values | packages/object-map-values/index.mjs |
| 根 README 中该包的章节 | README.md |