Electric SQL 中如何处理自定义解析器类型扩展

理解 Electric SQL 的类型系统

Electric SQL 的 TypeScript 客户端提供了一个灵活的类型系统，允许开发者处理从数据库返回的数据。核心类型包括 Value 和 Row，它们都支持通过泛型参数进行类型扩展。

Value 类型定义了 SQL 查询返回的基本值类型，包括：

• 基本类型：string、number、boolean、bigint 和 null
• 数组类型：Value[]
• 对象类型：{ [key: string]: Value }
• 扩展类型：通过泛型参数 Extensions 支持

Row 类型则是一个 Record 类型，键为字符串，值为 Value<Extensions>。

自定义类型解析的场景

在实际开发中，我们经常会遇到需要处理数据库中的特殊数据类型的情况。例如，PostgreSQL 的 timestamptz 类型，我们希望将其解析为 JavaScript 的 Date 对象。

考虑以下 Todo 类型定义：

type Todo = {
  id: string
  title: string
  completed: boolean
  created_at: Date  // 这是一个自定义类型
}

配置 ShapeStream 解析器

为了正确处理这种自定义类型，我们需要在创建 ShapeStream 时配置自定义解析器：

const stream = new ShapeStream<Todo>({
  url: `${ELECTRIC_URL}/v1/shape`,
  table: 'todos',
  parser: {
    timestamptz: (value: string) => new Date(value)  // 自定义解析函数
  }
})

类型扩展的正确使用方式

当我们在泛型函数中使用这些自定义类型时，需要注意类型参数的约束。Electric SQL 提供了两种方式来声明类型扩展：

1. Row<never> - 表示不允许任何类型扩展，只使用基本类型
2. Row<unknown> - 表示允许任意类型扩展

在定义泛型函数时，如果我们希望支持自定义类型，应该使用 Row<unknown> 作为约束：

export function matchStream<T extends Row<unknown>>(
  stream: ShapeStreamInterface<T>,
  operations: Array<Operation>,
  matchFn: (message: ChangeMessage<T>) => boolean,
  timeout = 60000
): Promise<ChangeMessage<T>> {
  // 函数实现
}

GetExtensions 工具类型

Electric SQL 还提供了一个有用的工具类型 GetExtensions，用于从 Row 类型中提取扩展类型。它的定义如下：

export type GetExtensions<T extends Row<unknown>> = 
  T extends Row<infer Extensions> ? Extensions : never

这个工具类型在以下场景特别有用：

• 当我们需要从复杂的嵌套类型中提取扩展类型时
• 在编写高阶类型工具函数时
• 当我们需要明确区分基础类型和扩展类型时

最佳实践建议

1. 对于自定义数据类型，始终在 ShapeStream 配置中提供相应的解析器
2. 在定义泛型函数时，根据需求选择 Row<never> 或 Row<unknown>
3. 考虑使用 GetExtensions 工具类型来保持类型系统的一致性
4. 为自定义类型编写清晰的类型注释，方便团队协作

通过遵循这些模式，我们可以充分利用 Electric SQL 的类型系统，同时保持代码的类型安全和可维护性。