深入解析 just 库的 just-map-object:对象键值映射的用法、源码实现与弃用迁移

原创2026-10-14 18:08:021,616 阅读
文章标签:开发工具

深入解析 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'}

三个示例分别展示了三类典型变换:

  1. 纯值变换:(key, value) => value + 1 —— key 被忽略,等价于“对所有值做映射”;
  2. 以 key 覆盖 value:(key, value) => key —— 结果对象的值变成各自的键名;
  3. 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
登录后查看全文
just