DynamoDB Toolbox 中 FormattedItem 类型的使用技巧

理解 FormattedItem 类型

在 DynamoDB Toolbox 这个优秀的 TypeScript 库中，FormattedItem<ENTITY> 是一个非常有用的类型工具。它能够根据我们定义的实体模式（schema）自动推断出完整的类型结构，包括实体本身的属性以及 DynamoDB Toolbox 自动添加的内部属性。

默认情况下，FormattedItem 类型会包含：

1. 实体模式中定义的所有属性
2. 两个自动管理的时间戳属性：created 和 modified

时间戳属性的控制

在实际开发中，我们经常需要创建新的实体对象，但在创建阶段并不需要（也不应该）手动设置 created 和 modified 这些内部属性。DynamoDB Toolbox 提供了灵活的方式来控制这些时间戳属性：

全局禁用时间戳

可以在创建实体时通过配置完全禁用时间戳功能：

const myEntity = new Entity({
  name: 'MyEntity',
  attributes: {...},
  timestamps: false  // 禁用所有时间戳属性
});

选择性禁用特定时间戳

也可以选择性地禁用某一个时间戳属性：

const myEntity = new Entity({
  name: 'MyEntity',
  attributes: {...},
  timestamps: {
    createdAt: false,  // 仅禁用 createdAt
    updatedAt: true    // 保留 updatedAt
  }
});

更合适的类型选择

对于创建新实体的场景，特别是使用 batchWrite 批量写入时，FormattedItem 可能不是最合适的选择，因为它要求包含所有属性（包括自动生成的属性）。

DynamoDB Toolbox 提供了 PutItemInput 类型，它更适合这种场景：

• 自动使具有默认值的属性变为可选
• 使关联属性（如时间戳）变为可选
• 完美匹配写入操作的类型要求

使用示例：

type StationDescription = PutItemInput<typeof stationDescriptionEntity>;

const stations: StationDescription[] = [];

for (const data of someOtherDataSource) {
  stations.push({
    id: data.id,
    foo: 'bar',
    address: data.address + 'x'
  });  // 不再需要包含 created/modified
}

类型推断的最佳实践

在使用 DynamoDB Toolbox 的类型系统时，有一个重要注意事项：当手动为 Entity 提供泛型参数时，必须提供所有泛型参数，否则未提供的参数会使用默认值而非从参数中推断。

因此，最佳实践是让 TypeScript 自动推断类型，而不是手动指定泛型参数：

// 推荐做法 - 自动推断所有类型
const myEntity = new Entity({
  name: 'MyEntity',
  attributes: {...},
  timestamps: false
});

// 不推荐 - 手动指定泛型可能导致类型推断不完整
const myEntity = new Entity<...>({...});

通过遵循这些实践，可以确保获得最准确的类型推断，同时保持代码的简洁性和可维护性。