企业官网建设流程全解析

es-toolkit 兼容模块中的 stubTrue：常量 true 回调函数的正确打开方式

【免费下载链接】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

stubTrue是 es-toolkit 的compat（Lodash 兼容）模块中一个极简的实用函数，它不接受任何参数，永远返回字面量true。在需要“无条件通过”的回调函数或默认布尔值的场景中，它能把() => true这样的匿名函数替换为语义清晰、可复用的具名函数；同时，官方文档也明确指出：在纯数值场景下直接使用true字面量比调用函数更高效。读完本文，你将掌握stubTrue的签名、典型用法、源码实现与测试验证方式，并了解它与stubFalse、stubArray、constant等同族函数的关系，以及如何在cond等复合工具中把它当作“兜底谓词”使用。

stubTrue 是什么

stubTrue是一个零参数函数，调用后始终返回布尔值true。它归属于 es-toolkit 的兼容层（compat），用于与 Lodash 的stubTrue保持 API 一致，方便从 Lodash 迁移的代码无缝切换。

其 TypeScript 调用形态非常简单：

const result = stubTrue(); // result === true

它的官方参考文档位于 docs/compat/reference/util/stubTrue.md，日文版本位于 docs/ja/compat/reference/util/stubTrue.md，归属于 util（工具函数）分类。

官方文档的核心警告：优先使用 true 字面量

值得特别注意的是，官方文档在开篇就放置了一个醒目的warning提示块，这是理解stubTrue定位的关键：

请使用true字面量代替本函数。stubTrue函数会引入不必要的函数调用，导致运行变慢。请改用更快速、更现代的true字面量。

也就是说，es-toolkit 并不鼓励你在所有场景下都用stubTrue()，它存在的意义主要是兼容性——当 Lodash 代码中大量使用了stubTrue，迁移时可以原样保留；而在可以自由选择的新代码中，直接写true往往更优。这一点在下面的源码分析中会得到印证。

使用场景与代码示例

场景一：作为“保留全部元素”的数组过滤器

Array.prototype.filter要求传入一个返回布尔值的谓词函数。当业务逻辑要求保留数组中的所有元素时，与其写() => true，不如直接传入stubTrue：

import { stubTrue } from 'es-toolkit/compat'; // 保留数组中所有元素的过滤器 const items = [1, 2, 3, 4, 5]; const allItems = items.filter(stubTrue); console.log(allItems); // [1, 2, 3, 4, 5]

这里filter会为每个元素调用stubTrue，每次都得到true，因此allItems与items内容一致。类似的模式还适用于every、some、forEach等接受谓词回调的数组方法。

场景二：作为条件设置中的默认值

在对象字面量初始化时，stubTrue()（注意带括号，直接求值）可以充当“默认启用”的布尔开关：

import { stubTrue } from 'es-toolkit/compat'; // 默认全部启用的选项 const defaultOptions = { enableFeatureA: stubTrue(), enableFeatureB: stubTrue(), enableFeatureC: stubTrue(), }; console.log(defaultOptions); // { enableFeatureA: true, enableFeatureB: true, enableFeatureC: true }

此时stubTrue()返回的是布尔值true本身，与手写enableFeatureA: true效果完全相同，适合在批量生成默认配置或从某个映射函数派生配置时保持代码一致性。

参数与返回值

• 参数：无。调用stubTrue不需要也不接受任何参数。
• 返回值：boolean类型，恒为true。

源码级实现解析

极简的函数体

stubTrue的实现位于 src/compat/util/stubTrue.ts，函数体只有一行：

export function stubTrue(): true { return true; }

其中返回类型被精确地标注为字面量类型true（而不是宽泛的boolean），这意味着 TypeScript 编译器能确认该函数返回值的具体类型，从而在类型收窄（type narrowing）场景下提供更强的类型安全。文件中还包含两个同签名重载声明，均为文档注释服务，运行时实际执行的只有一个返回true的实现。

从实现可以看出官方警告的依据：每次调用stubTrue()都需要执行一次函数调用栈的压栈与返回，相比直接读取字面量true确实有（虽然微小但真实存在的）额外开销。因此：

• 需要函数引用（如传给filter、every、cond）时，用stubTrue；
• 只需一个布尔值（如对象属性默认值）时，直接写true更优。

测试验证

对应测试位于 src/compat/util/stubTrue.spec.ts，使用 Vitest 编写：

import { describe, expect, it } from 'vitest'; import { stubTrue } from './stubTrue'; describe('stubTrue', () => { it('should return `true`', () => { expect(stubTrue()).toEqual(true); }); });

该测试断言stubTrue()的返回值严格等于true，直接锁定了函数的行为契约。

导出链路

stubTrue通过两条路径对外导出：

• 兼容层入口 src/compat/compat.ts（第 296 行）：export { stubTrue } from './util/stubTrue.ts';
• 浏览器入口 src/browser.ts（第 294 行）：export { stubTrue } from './compat/util/stubTrue.ts';

因此你可以通过以下任一种方式引入：

import { stubTrue } from 'es-toolkit/compat'; // 或 import { stubTrue } from 'es-toolkit';

与同族 stub 函数的对比

stubTrue并非孤例，compat 的 util 目录下还有一组结构完全对称的“stub 函数”，它们都是零参数、返回固定值的常量函数，共同构成了一套可复用的“默认值生成器”：

其中stubFalse与stubTrue实现完全对称，返回字面量类型false；stubArray每次调用都返回新的空数组（而非共享同一引用），stubObject同理返回新对象，这在避免引用污染的场景下非常关键。

如果需要返回任意固定值的函数，可以使用更通用的constant（src/compat/util/constant.ts），它接受一个值并返回“恒返回该值”的新函数：constant(value)等价于“可参数化的 stub”。从实现上看，stubTrue本质上就是constant(true)的特化版本，只是以独立命名直接暴露，与 Lodash 保持完全一致。

高级用法：在 cond 中充当兜底谓词

stubTrue在 es-toolkit 内部最典型的高级用法，是作为条件分派函数cond的“恒真兜底分支”。查看 src/compat/util/cond.ts 的文档示例：

const func = cond([ [matches({ a: 1 }), constant('matches A')], [conforms({ b: isNumber }), constant('matches B')], [stubTrue, constant('no match')] // 兜底分支：前面的条件都不满足时必然命中 ]); func({ a: 1, b: 2 }); // => 'matches A' func({ a: 0, b: 1 }); // => 'matches B' func({ a: '1', b: '2' }); // => 'no match'

cond会按顺序依次求值每一对[谓词, 处理函数]，一旦某个谓词返回真值就执行对应的处理函数并返回结果。将stubTrue放在最后一个分支的谓词位置，就构造出了一个“必达兜底”，等价于其他语言中的default分支或else语句，且整个逻辑以数据驱动的方式声明式地组织。

此外，在 compat 模块的测试代码中，stubTrue被广泛用于批量构造预期值。例如：

• src/compat/predicate/isEmpty.spec.ts 中用empties.map(stubTrue)生成一组期望结果；
• src/compat/object/pickBy.spec.ts 中pickBy(object, stubTrue)验证“保留全部属性”的行为；
• src/compat/util/overSome.spec.ts 中overSome(stubFalse, [stubTrue])组合恒假与恒真谓词验证overSome的短路求值语义。

这些用法说明stubTrue不仅是一个简单的常量函数，更是谓词组合与测试脚手架中反复出现的基础构件。

总结与选型建议

• 何时使用stubTrue：需要向filter、every、some、cond等 API 传入“恒真谓词”的函数引用时；从 Lodash 迁移且希望保持代码语义不变时。
• 何时直接用true字面量：仅仅需要一个布尔默认值、不涉及函数引用传递时——官方文档明确建议以更快的字面量替代。
• 不要混淆两种形态：stubTrue（无括号）是函数引用，可传给回调参数；stubTrue()（带括号）直接求值为true。

理解stubTrue的定位，本质上也就理解了 es-toolkit compat 层的设计哲学：为 Lodash 用户提供无缝迁移的 API 表面，同时通过文档与源码明确给出更现代、更高效的替代方案。这一点从函数体的一行实现、文档开篇的 warning 提示，以及同族 stub 函数的对称设计中都清晰可见。

【免费下载链接】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