自定义类型

interface CustomTypeValues {
  /**
   * 自定义列所需的类型，它将推断出正确的类型模型
   *
   * 示例：
   *
   * 如果你希望列在选择后或插入时为 `string` 类型——使用 `data: string`。例如 `text`、`varchar`
   *
   * 如果你希望列在选择后或插入时为 `number` 类型——使用 `data: number`。例如 `integer`
   */
  data: unknown;
  /**
   * 类型辅助器，表示数据库驱动针对特定数据库数据类型接受的类型
   */
  driverData?: unknown;
  /**
   * @deprecated 改用 codecs
   *
   * 类型辅助器，表示数据库驱动针对特定数据库数据类型返回的类型
   *
   * 仅在驱动的输出和输入类型不同的情况下需要
   *
   * 默认为 {@link driverData}
   */
  driverOutput?: unknown;
  /**
   * @deprecated 改用 codecs
   *
   * 类型辅助器，表示字段聚合为 JSON 后返回的类型
   */
  jsonData?: unknown;
  /**
   * 应该使用什么配置类型来生成 {@link CustomTypeParams} 的 `dataType`
   */
  config?: Record<string, any>;
  /**
   * config 参数是否应为必填
   * @default false
   */
  configRequired?: boolean;
  /**
   * 如果你的自定义数据类型默认应为 notNull，可以使用 `notNull: true`
   *
   * @example
   * const customSerial = customType<{ data: number, notNull: true, default: true }>({
   * 	  dataType() {
   * 	    return 'serial';
   *    },
   * });
   */
  notNull?: boolean;
  /**
   * 如果你的自定义数据类型有默认值，可以使用 `default: true`
   *
   * @example
   * const customSerial = customType<{ data: number, notNull: true, default: true }>({
   * 	  dataType() {
   * 	    return 'serial';
   *    },
   * });
   */
  default?: boolean;
}
interface CustomTypeParams<T extends CustomTypeValues> {
  /**
   * 用于迁移的数据库数据类型字符串表示
   * @example
   * ```
   * `jsonb`, `text`
   * ```
   *
   * 如果数据库数据类型需要额外参数，可以从 `config` 参数中获取
   * @example
   * ```
   * `varchar(256)`, `numeric(2,3)`
   * ```
   *
   * 若要使 `config` 具有特定类型，请在 {@link CustomTypeValues} 中使用 config 泛型
   *
   * @example
   * 使用示例
   * ```
   *   dataType() {
   *     return 'boolean';
   *   },
   * ```
   * 或
   * ```
   *   dataType(config) {
   * 	   return typeof config.length !== 'undefined' ? `varchar(${config.length})` : `varchar`;
   * 	 }
   * ```
   */
  dataType: (config: T['config'] | (Equal<T['configRequired'], true> extends true ? never : undefined)) => string;
  /**
   * 可选映射函数，用于将代码中期望使用的输入格式转换为适合驱动的格式
   * @example
   * 例如，使用 jsonb 时，我们需要在写入数据库前将 JS/TS 对象映射为字符串
   * ```
   * toDriver(value: TData): string {
   * 	 return JSON.stringify(value);
   * }
   * ```
   */
  toDriver?: (value: T['data']) => T['driverData'] | SQL;
  /**
   * 可选映射函数，用于将驱动返回的数据转换为所需列的输出格式
   * @example
   * 例如，使用 timestamp 时，我们需要将字符串形式的 Date 表示映射为 JS Date
   * ```
   * fromDriver(value: string): Date {
   * 	return new Date(value);
   * }
   * ```
   *
   * 这将使返回的数据从：
   * ```
   * {
   * 	customField: "2025-04-07T03:25:16.635Z";
   * }
   * ```
   * 变为：
   * ```
   * {
   * 	customField: new Date("2025-04-07T03:25:16.635Z");
   * }
   * ```
   */
  fromDriver?: (value: 'driverOutput' extends keyof T ? T['driverOutput'] : T['driverData']) => T['data'];
  /**
   * @deprecated 改用 codecs；如果使用会绕过 JSON codecs
   *
   * 可选映射函数，用于将转换后用于数据库 JSON 的数据转换为所需格式
   *
   * 由 [关系查询](https://orm.drizzle.team/docs/rqb) 使用
   *
   * 默认为 {@link fromDriver} 函数
   * @example
   * 例如，通过 [RQB](https://orm.drizzle.team/docs/rqb) 或 JSON 函数查询 bigint 列时，结果字段将以字符串形式返回，而不是常规查询中的 bigint
   * 为了处理这种情况，我们需要一个单独的函数来处理该字段的映射：
   * ```
   * fromJson(value: string): bigint {
   * 	return BigInt(value);
   * },
   * ```
   *
   * 这将使返回的数据从：
   * ```
   * {
   * 	customField: "5044565289845416380";
   * }
   * ```
   * 变为：
   * ```
   * {
   * 	customField: 5044565289845416380n;
   * }
   * ```
   */
  fromJson?: (value: T['jsonData']) => T['data'];
  /**
   * @deprecated 改用 codecs；如果使用会绕过 JSON codecs
   *
   * 可选选择修饰函数，用于修改 JSON 函数内列的选择方式
   *
   * 这种场景可能需要的额外映射可通过 {@link fromJson} 函数处理
   *
   * 由 [关系查询](https://orm.drizzle.team/docs/rqb) 使用
   *
   * 以下类型默认会被转换为 text：`bytea`、`geometry`、`timestamp`、`numeric`、`bigint`
   * @example
   * 例如，使用 bigint 时，我们需要将字段转换为 text 以保持数据完整性
   * ```
   * forJsonSelect(identifier: SQL, sql: SQLGenerator, arrayDimensions?: number): SQL {
   * 	return sql`${identifier}::text`
   * },
   * ```
   *
   * 这将把查询从：
   * ```
   * SELECT
   * 	row_to_json("t".*)
   * 	FROM
   * 	(
   * 		SELECT
   * 		"table"."custom_bigint" AS "bigint"
   * 		FROM
   * 		"table"
   * 	) AS "t"
   * ```
   * 变为：
   * ```
   * SELECT
   * 	row_to_json("t".*)
   * 	FROM
   * 	(
   * 		SELECT
   * 		"table"."custom_bigint"::text AS "bigint"
   * 		FROM
   * 		"table"
   * 	) AS "t"
   * ```
   *
   * 查询对象返回的结果将从：
   * ```
   * {
   * 	bigint: 5044565289845416000; // 由于直接转换为 JSON 格式导致部分数据丢失
   * }
   * ```
   * 变为：
   * ```
   * {
   * 	bigint: "5044565289845416380"; // 在转为 JSON 之前先将字段转换为 text，因此数据得以保留
   * }
   * ```
   */
  forJsonSelect?: (identifier: SQL, sql: SQLGenerator, arrayDimensions?: number) => SQL;
  /**
   * 选择此列将使用哪种列类型 codec
   */
  codec?: PostgresColumnType | undefined | ((config: T['config'] | (Equal<T['configRequired'], true> extends true ? never : undefined)) => PostgresColumnType | undefined);
}