Electric-SQL 中 React Hook 的类型安全封装实践

背景介绍

Electric-SQL 是一个强大的实时数据库同步解决方案，它提供了 React Hook 形式的 API useShape 来订阅数据库表的变化。在实际开发中，开发者常常需要处理类型安全和配置复用的问题。

原始用法分析

Electric-SQL 提供的 useShape Hook 基本用法如下：

const { data } = useShape<T>({
  url: process.env.ELECTRIC_PROXY_URL!,
  table: "table_name",
  where: `table_id = '${table_id}'`,
})

这种写法存在两个主要问题：

1. 每次调用都需要重复配置公共选项（如 URL）
2. 类型参数 T 需要手动指定，容易出错

改进方案

我们可以通过创建自定义 Hook 工厂函数来解决这些问题：

import { ShapeStreamOptions } from "@electric-sql/client"
import { useShape as useShape_ } from "@electric-sql/react"
import { Selectable } from "kysely"
import { DB } from "schema"

export function useShape<K extends keyof DB>(
  table: K,
  options: Omit<ShapeStreamOptions<Selectable<DB[K]>>, "url" | "table" | "parser"> = {},
) {
  return useShape_<Selectable<DB[K]>>({
    url: `${process.env.EXPO_PUBLIC_CROSSHATCH_SERVER}/v1/shape`,
    table: `public.${table}`,
    ...options,
  })
}

实现解析

这个封装实现了以下优化：

1. 类型安全：通过泛型 K extends keyof DB 确保只能传入数据库中存在的表名
2. 自动类型推断：利用 Kysely 生成的 DB 类型自动推断表结构
3. 配置复用：公共配置（如 URL 和表名前缀）只需定义一次
4. 简化调用：调用时只需关注表名和查询条件

实际应用

改进后的调用方式更加简洁：

const { data } = useShape("users", {
  where: `age > 18`
})

TypeScript 会自动推断 data 的类型为 Selectable<DB['users']>，提供完整的类型提示和检查。

与 Kysely 的协同

这种模式特别适合与 Kysely 配合使用：

1. 使用 kysely-codegen 自动生成数据库类型定义
2. 在数据库结构变更后，只需重新生成类型定义
3. TypeScript 会标记出所有需要更新的地方

总结

通过简单的封装，我们显著提升了 Electric-SQL 在 React 应用中的开发体验：

• 减少了重复代码
• 增强了类型安全性
• 简化了 API 调用
• 与现有 ORM 工具无缝集成

这种模式不仅适用于 Electric-SQL，也可以作为其他数据库客户端库的通用封装思路。