DynamoDB Toolbox 中 Record 类型值被推断为 undefined 的问题解析

问题背景

在使用 DynamoDB Toolbox 进行数据建模时，开发者发现了一个关于 Record 类型的有趣现象。当定义一个包含 record(string(), assetsSchema) 的实体时，TypeScript 类型系统会将记录值推断为可能为 undefined 的类型，这与 TypeScript 原生 Record 类型的行为不一致。

问题复现

考虑以下实体定义示例：

const assetsSchema = map({
  assetId: string(),
  objectKey: string(),
  type: string().enum("image", "video"),
});

const MyEntity = new Entity({
  name: "POST",
  table: PostsTable,
  schema: schema({
    linkId: string().key().required("always").savedAs("PK"),
    userId: string().key().required("always").savedAs("SK"),
    assets: record(string(), assetsSchema),
  }),
});

查询后，Item.assets 的类型被推断为 Record<string, Asset | undefined>，而非预期的 Record<string, Asset>。这导致开发者在使用时需要额外的类型守卫来确保值的存在性。

技术分析

设计考量

DynamoDB Toolbox 的这种设计是有意为之的，主要出于以下考虑：

1. 当使用枚举作为键时，类型系统需要处理可能缺失的枚举值
2. 为了保持一致性，对所有 Record 类型都采用了相同的处理方式

与 TypeScript 原生 Record 的差异

TypeScript 原生的 Record 类型会严格确保值的类型，不允许 undefined 作为值类型的一部分（除非显式声明）。而 DynamoDB Toolbox 的 record() 方法则采用了更保守的类型推断策略。

解决方案演进

临时解决方案

开发者可以采用以下方式来绕过这个问题：

function checkIsNonNullable<T>(value?: T): value is NonNullable<T> {
  return value !== null && value !== undefined;
}

const assetIds = Object.values(assets)
  .filter(checkIsNonNullable)
  .map(asset => asset.assetId);

官方修复

在 v2 版本中，DynamoDB Toolbox 重新设计了 Record 类型的行为：

1. 区分了枚举键和非枚举键的情况
2. 对于非枚举键，不再自动添加 undefined 到值类型中
3. 新增了 .complete() 方法，允许显式声明记录值的完整性

最佳实践建议

1. 对于不需要处理枚举键的场景，建议升级到 v2 版本
2. 如果必须使用 v1 版本，可以创建自定义类型守卫来简化代码
3. 考虑使用可选链操作符(?.)来安全访问可能为 undefined 的值

总结

这个问题展示了类型系统设计中的权衡考量。DynamoDB Toolbox 最初选择了更保守的类型推断策略，以确保在各种使用场景下的安全性。随着用户反馈和实践经验的积累，在 v2 版本中提供了更精确的类型控制能力，使开发者能够根据具体需求选择合适的类型严格度。