es-toolkit compat 模块 stubObject 函数完全指南：返回新空对象的恒值函数

es-toolkit compat 模块 stubObject 函数完全指南：返回新空对象的恒值函数

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

stubObject是 es-toolkit 为兼容 lodash 而提供的恒值（stub）函数之一，它不接受任何参数、每次调用都返回一个全新的空对象{}。在需要默认值、函数式编程回退分支或一致性返回值等场景中，它可以替代字面量写法并避免共享引用带来的副作用。读完本文，你将掌握stubObject的源码实现、完整用法、实例语义、适用场景以及它与stubArray、stubTrue等兄弟函数的关系。

stubObject 是什么

stubObject定义于 src/compat/util/stubObject.ts，其完整实现只有短短几行：

/** * Returns an empty object. * * @returns An empty object. * @example * stubObject() // Returns {} */ export function stubObject(): any { return {}; }

从源码结构可以推断，它与 lodash 同名 API 保持一致的语义：不接收任何参数，总是返回一个新创建的空对象字面量。注意其返回类型标注为any，这是为了与 lodash 类型签名对齐——调用方拿到的是一个可自由赋值的空对象。

在 es-toolkit 中，该函数属于 compat（兼容层）模块，通过 src/compat/compat.ts 与stubArray、stubFalse、stubString、stubTrue一起统一导出，使用方式为：

import { stubObject } from 'es-toolkit/compat';

函数签名与返回值

每次调用stubObject()都会通过return {}执行一次对象字面量求值，因此产生的是全新实例，而非缓存或共享的同一引用。

基础用法

最简单的调用直接得到一个空对象：

import { stubObject } from 'es-toolkit/compat'; // Returns an empty object const emptyObject = stubObject(); console.log(emptyObject); // => {}

核心语义：每次调用返回新实例

这是stubObject与直接共享一个模块级常量空对象最本质的区别。文档示例验证如下：

import { stubObject } from 'es-toolkit/compat'; const obj1 = stubObject(); const obj2 = stubObject(); console.log(obj1 === obj2); // => false (different instances) console.log(typeof obj1); // => 'object' console.log(Object.keys(obj1).length); // => 0

三个断言分别说明：两次调用产生不同引用；结果是object类型；对象上没有可枚举自身属性。这意味着对其中一个返回值做修改（如新增属性、修改属性）不会污染其他调用结果，适合在需要“每次拿全新可变对象”的场景中使用。

典型使用场景

作为默认值

利用函数默认参数在每次缺参调用时才求值的特性，stubObject()可以为形参提供安全的新空对象：

function processData(data = stubObject()) { return { ...data, processed: true }; } console.log(processData()); // => { processed: true } console.log(processData({ name: 'John' })); // => { name: 'John', processed: true }

不传参数时拿到的是独立的新对象，不会因默认对象被外部修改而产生跨调用污染。

函数式编程中的回退分支

在需要“可调用、返回固定值”的回调场景中，恒值函数可以无缝嵌入：

const createEmpty = () => stubObject(); const obj = createEmpty(); obj.newProperty = 'value'; // Safe because it's a new object

从代码结构看，这类用法常见于map、cond、overSome等组合工具中作为兜底分支。例如 src/compat/object/transform.spec.ts 中就用map(values, stubObject)批量生成空对象作为期望值，验证了它作为纯函数回调的可组合性。

stub 恒值函数家族

stubObject并非孤立存在。在 src/compat/util 目录下，es-toolkit 提供了一组语义相同的恒值函数，统一经 src/compat/compat.ts 导出：

它们在cond、overEvery、overSome、iteratee等工具的测试中被广泛使用（见 cond.spec.ts、overEvery.spec.ts），用于提供恒定真值/假值或空容器作为组合逻辑的叶子节点。其中stubTrue采用函数重载声明形式（stubTrue(): true），而stubObject与stubArray标注为any/any[]，体现了不同类型返回值在类型约束上的差异。

官方建议：多数场景直接用{}

需要特别留意的是，官方文档对stubObject给出了明确的使用警告：它只是一个返回空对象的简单包装，属于不必要的抽象。在性能与直白性优先的普通代码中，应直接用对象字面量：

// 推荐：直接使用字面量，更快、更直接 const emptyObject = {};

stubObject的价值主要体现在需要“以函数形式提供返回值”的场合——比如回调、默认参数、组合工具的参数位置——而不是替代日常的空对象写法。

测试验证

单元测试 stubObject.spec.ts 使用 Vitest 验证其核心契约：

import { describe, expect, it } from 'vitest'; import { stubObject } from './stubObject'; describe('stubObject', () => { it('should return an empty object', () => { expect(stubObject()).toEqual({}); }); });

测试通过toEqual({})断言返回值与空对象结构相等，同时该函数在其他模块测试中的复用（如 transform.spec.ts 中map(values, stubObject)与map(falsey, stubObject)）也印证了它作为可复用恒值函数的定位。

小结

• stubObject是 es-toolkit compat 层提供的无参恒值函数，每次调用返回全新空对象，源码见 src/compat/util/stubObject.ts，从es-toolkit/compat导入。
• 核心语义是“每次新实例”，适合默认值、函数式组合与需要独立可变对象的场景。
• 它与stubArray、stubTrue、stubFalse、stubString构成完整的 stub 家族，作为组合工具的恒值节点使用。
• 普通业务代码中官方建议直接使用{}，仅在有函数化需求时引入stubObject。

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit