Remeda 字符串大写转换指南：从 Lodash toUpper 迁移到 toUpperCase

导读

在从 Lodash 迁移到 Remeda 的过程中，字符串大小写转换是最常见的改造点之一。本文围绕 Lodash 迁移对照文档 展开，讲解 Lodash _.toUpper 与 Remeda toUpperCase 的用法对应关系、两者在空输入处理上的关键差异，以及何时应当改用 CSS text-transform: uppercase 而非 JavaScript 转换。读完本文，你将掌握 toUpperCase 的 data-first 与 data-last 两种调用方式、其基于 String.prototype.toUpperCase 的底层实现与类型推断能力，并能安全地完成迁移与空值兜底处理。

toUpper 与 toUpperCase：同名函数的迁移对照

Lodash 的字符串大写函数名为 _.toUpper，而 Remeda 采用更贴近原生 API 的命名 toUpperCase。虽然行为相似，但两者在函数签名与调用约束上有显著区别：

• Lodash：_.toUpper(input) 允许省略参数，甚至允许传入 undefined，此时会返回空字符串 ""；
• Remeda：toUpperCase(input) 要求必须传入一个字符串，undefined 不被支持。

文档给出的基础用法对照如下：

// Lodash
_.toUpper(input);

// Remeda
toUpperCase(input);

在 Remeda 中，toUpperCase 被标记为 @dataFirst 与 @dataLast 双签名，意味着除直接调用外，还可以作为管道函数使用，详见后文"data-last 管道用法"一节。

命名与分类

• toUpperCase 在 Remeda 中被归入 String 类别（源码 JSDoc 中的 @category String，见 toUpperCase.ts）；
• 迁移文档的 frontmatter 同样声明了 category: String 与 remeda: toUpperCase（见 toUpper.md），两者保持一致，方便文档站按类别组织映射条目（相关实现见 entries.ts）。

首选 CSS text-transform：显示场景不要用 JS 转换

迁移文档首先强调了一个重要的工程原则：如果只是为了"显示"效果，请优先使用 CSS text-transform: uppercase，而不是在 JavaScript 中转换字符串。

// Lodash：在渲染前转换字符串
<div>{_.toUpper(input)}</div>

// CSS：交给浏览器渲染层处理，无需改动数据
<div style="text-transform:uppercase">{input}</div>

这样做的核心原因在于locale 感知能力：String.prototype.toUpperCase 是基于默认 locale 的转换，对于土耳其语（Turkish）中 i/İ 这类需要特殊规则的语言并不准确；而 CSS 的 text-transform: uppercase 是 locale-aware 的，会跟随页面语言环境给出正确结果。这一点在 toUpperCase 的源码 JSDoc 中有明确说明（见 toUpperCase.ts），capitalize、toLowerCase 等相邻函数的文档也持有相同立场（见 capitalize.ts、toLowerCase.ts）。

因此，在 React/Vue 等前端模板中遇到"展示大写"的需求时，应优先选择 CSS 方案；只有当数据本身需要被大写化（例如生成 ID、规范化存储内容、比较字符串）时才调用 toUpperCase。

缺失输入：Lodash 宽松，Remeda 严格

这是迁移中最容易踩坑的差异点。Lodash 允许两种"缺失输入"的调用方式：

_.toUpper();
_.toUpper(input); // input 为 undefined 时也合法

而 Remeda 的 toUpperCase 只接受字符串，且函数实现直接调用 data.toUpperCase()（见 toUpperCase.ts），传入 undefined 会在运行时抛出 TypeError。因此迁移前必须对可能为 undefined 的输入做兜底，文档给出了两种推荐写法：

// 方案一：先判断再调用
input !== undefined ? toUpperCase(input) : "";

// 方案二：使用空值合并运算符兜底
toUpperCase(input ?? "");

在 TypeScript 项目中，input ?? "" 的写法更简洁，同时也能把 string | undefined 收敛为 string，让类型系统在编译期就阻止错误调用。如果你的输入可能为 null，?? 同样适用，因为空值合并运算符会同时覆盖 null 与 undefined。

data-first 与 data-last：两种调用形态与管道集成

toUpperCase 与其他 Remeda 函数一样，通过 purry 机制同时提供 data-first 与 data-last 两种签名（见 toUpperCase.ts）：

• data-first：toUpperCase(data)，数据作为第一个参数传入；
• data-last：toUpperCase()，返回一个接收数据的函数，适合与 pipe 组合。

// data-first
toUpperCase("Hello World"); // "HELLO WORLD"

// data-last（管道用法）
pipe("Hello World", toUpperCase()); // "HELLO WORLD"

从源码实现看，toUpperCase 的实际逻辑委托给 purry(toUpperCaseImplementation, args)（见 toUpperCase.ts）。purry 根据传入参数个数判断调用形态：参数个数等于实现函数形参数时直接执行，少一个参数时则通过 lazyDataLastImpl 返回 data-last 函数（见 purry.ts）。这意味着 toUpperCase 可以无缝嵌入 Remeda 的管道风格代码，例如与其他字符串处理函数链式组合。

类型层面的精确推断

toUpperCase 的签名使用了 TypeScript 的内置模板字面量类型 Uppercase<T>：

export function toUpperCase<T extends string>(data: T): Uppercase<T>;

这使它具备字面量类型级别的精确推断能力。类型测试文件 toUpperCase.test-d.ts 验证了以下场景：

• 输入 "hello world" 字面量，输出被推断为 "HELLO WORLD" 字面量类型；
• 输入普通 string 类型，输出为 Uppercase<string>；
• 输入模板字面量类型 prefix_${number}，输出被精确推断为 PREFIX_${number} 的对应大写形式（见 toUpperCase.test-d.ts）；
• 空字符串 "" 保持为 ""。

也就是说，toUpperCase 不仅能改变运行时的字符串，还能同步"改写"编译期的字符串类型，这在基于字符串字面量的判别联合（discriminated union）、路由表或状态机等场景中非常有用。

底层实现：String.prototype.toUpperCase 的薄封装

toUpperCase 本质上是对 JavaScript 内建方法 String.prototype.toUpperCase 的一层薄封装，核心实现只有一行：

const toUpperCaseImplementation = <T extends string>(data: T): Uppercase<T> =>
  data.toUpperCase();

源码在实现处添加了 @ts-expect-error 注释，原因是 TypeScript 无法仅凭代码自动推断 Uppercase<T> 的精确映射，因此需要依赖声明重载来提供类型（见 toUpperCase.ts）。

正因为是薄封装，它继承了原生方法的一切行为特征，包括其 locale 不准确性（详情见 MDN 关于 toLocaleUpperCase 的描述）。若需要更符合语言习惯的转换，可考虑使用 toLocaleUpperCase；而纯展示场景则应使用 CSS 方案。

Unicode 与特殊字符的行为验证

单元测试 toUpperCase.test.ts 对 Unicode 场景做了系统性验证，以下行为可以直接视为该函数的事实约束：

输入类别	示例	结果
纯小写	"hello world"	"HELLO WORLD"
混合大小写	"HeLlO WoRlD"	"HELLO WORLD"
变音符号	"café naïve"	"CAFÉ NAÏVE"
非拉丁字母（西里尔、希腊）	"москва" / "ελλάδα"	"МОСКВА" / "ΕΛΛΆΔΑ"
Emoji	"🎉party"	"🎉PARTY"
补充平面（astral plane）代理对	"𝒽ello"	"𝒽ELLO"
组合字符	"e\u{301}llo"	"E\u{301}LLO"
德语 ß（eszett）	"straße"	"STRASSE"
土耳其语带点 i	"i̇stanbul"	"İSTANBUL"

其中几个值得注意的细节：

• 德语 ß 大写化："straße" 转为 "STRASSE"，这是因为 String.prototype.toUpperCase 在多数引擎中遵循官方的大小写映射规则；
• 土耳其语问题：i̇stanbul 中带点的 i 被转为带点的 İ，但由于 toUpperCase 基于默认 locale，不含 locale 规则，土耳其语环境下可能需要 locale-aware 方案；
• 组合字符保留：e 加组合重音符（U+0301）只对基础字母 e 大写，组合符号本身保持原样，不会产生多余的重音叠加（测试见 toUpperCase.test.ts）。

这些测试同时以 describe("unicode") 分组出现在类型测试 toUpperCase.test-d.ts 中，说明运行时行为与类型推断在这些场景下保持一致。

相关的大小写处理函数族

toUpperCase 并非孤立存在。在 Remeda 中它隶属于一组大小写处理函数，源码 JSDoc 中相互引用（见 toUpperCase.ts），包括：

• toLowerCase：与 toUpperCase 完全对称，底层包装 String.prototype.toLowerCase，类型上使用 Lowercase<T>（见 toLowerCase.ts）；
• capitalize：仅将首字母大写，底层使用 toUpperCase 与内置 Capitalize 类型（见 capitalize.ts）；
• uncapitalize、toCamelCase、toKebabCase、toSnakeCase、toTitleCase：其他大小写与命名风格转换。

所有这些函数都通过 index.ts 从包入口统一导出。如果你的迁移需求涉及整串大写、整串小写、首字母大写等多类操作，可以一次性参考这一函数族，保持代码风格一致。

迁移清单：从 _.toUpper 切换到 toUpperCase

综合以上分析，给出一个可直接照做的迁移步骤：

1. 判断使用场景：若仅为显示效果，改用 CSS text-transform: uppercase，无需任何函数调用；
2. 处理缺失输入：输入可能为 undefined 或 null 时，先做空值兜底（推荐 input ?? ""），或在调用前用条件判断保护；
3. 替换调用：_.toUpper(input) → toUpperCase(input)；若处于管道中，使用 toUpperCase() 的 data-last 形式；
4. 确认类型契约：对于字符串字面量输入，toUpperCase 会返回精确的大写字面量类型，若业务依赖该类型推断，迁移反而能获得比 Lodash 更强的类型保障；
5. 了解边界：牢记该函数基于默认 locale、不含 locale 规则，涉及土耳其语等敏感语言时改用 toLocaleUpperCase 或 CSS 方案。

需要提醒的是，Remeda 的 toUpperCase 只接受字符串且不支持省略参数，这与 Lodash 的宽松行为是迁移中唯一的语义差异，处理得当即可无缝替换。