Valibot 中如何正确处理动态对象模式类型推断

在 Valibot 项目中，开发者经常需要创建动态的对象模式（schema），其中部分键是固定的，部分键则是基于传入参数动态生成的。本文深入探讨了在使用 Valibot 时如何正确处理这种动态对象模式的类型推断问题。

问题背景

当我们需要创建一个函数来返回 Valibot 对象模式时，通常会遇到这样的情况：模式中的某些键是固定的，而其他键则基于传入的数组参数动态生成。例如：

function makeSchema(keys: string[]) {
  return v.strictObject({
    foo: v.strictObject({ bar: v.boolean() }), // 固定键
    ...v.entriesFromList(keys, v.number()),    // 动态键
  });
}

理想情况下，我们希望这个函数的返回类型能够精确反映生成的模式结构，包括固定键和动态键。

类型推断的挑战

直接使用 v.GenericType<...> 来定义返回类型会遇到一个问题：它会将对象的所有键都标记为可选（optional），即使这些键在模式中是必需的。这是因为 GenericType 内部使用了 InputWithQuestionMarks 类型，它会自动为所有属性添加可选标记。

解决方案

1. 依赖 TypeScript 的类型推断

最简单的解决方案是让 TypeScript 自动推断函数的返回类型：

function makeSchema<const T extends readonly string[]>(keys: T) {
  return v.strictObject({
    foo: v.strictObject({ bar: v.boolean() }),
    ...v.entriesFromList(keys, v.number()),
  });
}

这种方法利用了 TypeScript 强大的类型推断能力，能够自动推导出精确的返回类型。对于大多数场景，这是最简单有效的解决方案。

2. 显式声明返回类型

如果需要显式声明函数返回类型（例如遵循团队编码规范），可以通过以下方式实现：

function makeSchema<const T extends readonly string[]>(
  keys: T
): v.StrictObjectSchema<
  {
    readonly foo: v.StrictObjectSchema<
      { readonly bar: v.BooleanSchema<undefined> },
      undefined
    >;
  } & Record<T[number], v.NumberSchema<undefined>>,
  undefined
> {
  return v.strictObject({
    foo: v.strictObject({ bar: v.boolean() }),
    ...v.entriesFromList(keys, v.number()),
  });
}

虽然这种写法较为冗长，但它提供了最精确的类型定义，确保了类型安全。

高级应用

对于更复杂的模式结构，类型定义可能会变得相当复杂。例如：

type ComplexSchema<A extends readonly string[]> =
  v.StrictObjectSchema<
    {
      readonly repository: v.StrictObjectSchema<
        {
          readonly tests: v.StrictObjectSchema<
            {
              readonly entries: v.SchemaWithPipe<
                [
                  v.ArraySchema<v.StrictObjectSchema<...>>,
                  v.MinLengthAction<...>
                ]
              >;
            },
            undefined
          >;
        } & {
          [K in `additionalPath${...}`]: v.StrictObjectSchema<...>;
        },
        undefined
      >;
    },
    undefined
  >;

在这种情况下，虽然类型定义变得复杂，但它确保了模式的每个部分都有精确的类型定义，这对于大型项目的类型安全至关重要。

最佳实践建议

1. 优先使用类型推断：在大多数情况下，让 TypeScript 自动推断类型是最简单有效的方案。

2. 必要时显式声明类型：当需要确保函数返回特定类型或遵循团队规范时，才使用显式类型声明。

3. 考虑可读性：对于特别复杂的模式类型，可以考虑将其分解为多个较小的类型别名，以提高代码可读性。

4. 权衡类型精度和简洁性：在类型精度和代码简洁性之间找到平衡点，避免过度复杂的类型定义。

通过理解 Valibot 的类型系统工作原理，开发者可以更有效地创建和维护动态对象模式，同时确保类型安全。