@tinybirdco/sdk 0.0.54 → 0.0.56

package/src/schema/types.ts

@@ -14,7 +14,7 @@ const VALIDATOR_BRAND = Symbol.for("tinybird.validator");
 export interface TypeValidator<
   TType,
   TTinybirdType extends string = string,
-  TModifiers extends TypeModifiers = TypeModifiers
+  TModifiers extends TypeModifiers = TypeModifiers,
 > {
   readonly [VALIDATOR_BRAND]: true;
   /** The inferred TypeScript type */
@@ -25,15 +25,33 @@ export interface TypeValidator<
   readonly _modifiers: TModifiers;
 
   /** Make this column nullable */
-  nullable(): TypeValidator<TType | null, `Nullable(${TTinybirdType})`, TModifiers & { nullable: true }>;
+  nullable(): TypeValidator<
+    TType | null,
+    `Nullable(${TTinybirdType})`,
+    TModifiers & { nullable: true }
+  >;
   /** Apply LowCardinality optimization (for strings with few unique values) */
-  lowCardinality(): TypeValidator<TType, `LowCardinality(${TTinybirdType})`, TModifiers & { lowCardinality: true }>;
+  lowCardinality(): TypeValidator<
+    TType,
+    `LowCardinality(${TTinybirdType})`,
+    TModifiers & { lowCardinality: true }
+  >;
   /** Set a default value for the column */
-  default(value: TType): TypeValidator<TType, TTinybirdType, TModifiers & { hasDefault: true; defaultValue: TType }>;
+  default(
+    value: TType,
+  ): TypeValidator<
+    TType,
+    TTinybirdType,
+    TModifiers & { hasDefault: true; defaultValue: TType }
+  >;
   /** Set a codec for compression */
-  codec(codec: string): TypeValidator<TType, TTinybirdType, TModifiers & { codec: string }>;
+  codec(
+    codec: string,
+  ): TypeValidator<TType, TTinybirdType, TModifiers & { codec: string }>;
   /** Set an explicit JSON path for extraction (overrides autogenerated path) */
-  jsonPath(path: string): TypeValidator<TType, TTinybirdType, TModifiers & { jsonPath: string }>;
+  jsonPath(
+    path: string,
+  ): TypeValidator<TType, TTinybirdType, TModifiers & { jsonPath: string }>;
 }
 
 export interface TypeModifiers {
@@ -46,15 +64,18 @@ export interface TypeModifiers {
 }
 
 // Internal implementation
-interface ValidatorImpl<TType, TTinybirdType extends string, TModifiers extends TypeModifiers>
-  extends TypeValidator<TType, TTinybirdType, TModifiers> {
+interface ValidatorImpl<
+  TType,
+  TTinybirdType extends string,
+  TModifiers extends TypeModifiers,
+> extends TypeValidator<TType, TTinybirdType, TModifiers> {
   readonly tinybirdType: TTinybirdType;
   readonly modifiers: TModifiers;
 }
 
 function createValidator<TType, TTinybirdType extends string>(
   tinybirdType: TTinybirdType,
-  modifiers: TypeModifiers = {}
+  modifiers: TypeModifiers = {},
 ): TypeValidator<TType, TTinybirdType, TypeModifiers> {
   const validator: ValidatorImpl<TType, TTinybirdType, TypeModifiers> = {
     [VALIDATOR_BRAND]: true,
@@ -69,34 +90,53 @@ function createValidator<TType, TTinybirdType extends string>(
       // ClickHouse requires: LowCardinality(Nullable(X)), not Nullable(LowCardinality(X))
       if (modifiers.lowCardinality) {
         // Extract base type from LowCardinality(X) and wrap as LowCardinality(Nullable(X))
-        const baseType = tinybirdType.replace(/^LowCardinality\((.+)\)$/, '$1');
+        const baseType = tinybirdType.replace(/^LowCardinality\((.+)\)$/, "$1");
         const newType = `LowCardinality(Nullable(${baseType}))`;
-        return createValidator<TType | null, `LowCardinality(Nullable(${string}))`>(
-          newType as `LowCardinality(Nullable(${string}))`,
-          { ...modifiers, nullable: true }
-        ) as unknown as TypeValidator<TType | null, `Nullable(${TTinybirdType})`, TypeModifiers & { nullable: true }>;
+        return createValidator<
+          TType | null,
+          `LowCardinality(Nullable(${string}))`
+        >(newType as `LowCardinality(Nullable(${string}))`, {
+          ...modifiers,
+          nullable: true,
+        }) as unknown as TypeValidator<
+          TType | null,
+          `Nullable(${TTinybirdType})`,
+          TypeModifiers & { nullable: true }
+        >;
       }
       return createValidator<TType | null, `Nullable(${TTinybirdType})`>(
         `Nullable(${tinybirdType})` as `Nullable(${TTinybirdType})`,
-        { ...modifiers, nullable: true }
-      ) as TypeValidator<TType | null, `Nullable(${TTinybirdType})`, TypeModifiers & { nullable: true }>;
+        { ...modifiers, nullable: true },
+      ) as TypeValidator<
+        TType | null,
+        `Nullable(${TTinybirdType})`,
+        TypeModifiers & { nullable: true }
+      >;
     },
 
     lowCardinality() {
       // If already nullable, wrap as LowCardinality(Nullable(X))
       if (modifiers.nullable) {
         // Extract base type from Nullable(X) and wrap as LowCardinality(Nullable(X))
-        const baseType = tinybirdType.replace(/^Nullable\((.+)\)$/, '$1');
+        const baseType = tinybirdType.replace(/^Nullable\((.+)\)$/, "$1");
         const newType = `LowCardinality(Nullable(${baseType}))`;
         return createValidator<TType, `LowCardinality(Nullable(${string}))`>(
           newType as `LowCardinality(Nullable(${string}))`,
-          { ...modifiers, lowCardinality: true }
-        ) as unknown as TypeValidator<TType, `LowCardinality(${TTinybirdType})`, TypeModifiers & { lowCardinality: true }>;
+          { ...modifiers, lowCardinality: true },
+        ) as unknown as TypeValidator<
+          TType,
+          `LowCardinality(${TTinybirdType})`,
+          TypeModifiers & { lowCardinality: true }
+        >;
       }
       return createValidator<TType, `LowCardinality(${TTinybirdType})`>(
         `LowCardinality(${tinybirdType})` as `LowCardinality(${TTinybirdType})`,
-        { ...modifiers, lowCardinality: true }
-      ) as TypeValidator<TType, `LowCardinality(${TTinybirdType})`, TypeModifiers & { lowCardinality: true }>;
+        { ...modifiers, lowCardinality: true },
+      ) as TypeValidator<
+        TType,
+        `LowCardinality(${TTinybirdType})`,
+        TypeModifiers & { lowCardinality: true }
+      >;
     },
 
     default(value: TType) {
@@ -104,21 +144,33 @@ function createValidator<TType, TTinybirdType extends string>(
         ...modifiers,
         hasDefault: true,
         defaultValue: value,
-      }) as TypeValidator<TType, TTinybirdType, TypeModifiers & { hasDefault: true; defaultValue: TType }>;
+      }) as TypeValidator<
+        TType,
+        TTinybirdType,
+        TypeModifiers & { hasDefault: true; defaultValue: TType }
+      >;
     },
 
     codec(codec: string) {
       return createValidator<TType, TTinybirdType>(tinybirdType, {
         ...modifiers,
         codec,
-      }) as TypeValidator<TType, TTinybirdType, TypeModifiers & { codec: string }>;
+      }) as TypeValidator<
+        TType,
+        TTinybirdType,
+        TypeModifiers & { codec: string }
+      >;
     },
 
     jsonPath(path: string) {
       return createValidator<TType, TTinybirdType>(tinybirdType, {
         ...modifiers,
         jsonPath: path,
-      }) as TypeValidator<TType, TTinybirdType, TypeModifiers & { jsonPath: string }>;
+      }) as TypeValidator<
+        TType,
+        TTinybirdType,
+        TypeModifiers & { jsonPath: string }
+      >;
     },
   };
 
@@ -139,116 +191,141 @@ function createValidator<TType, TTinybirdType extends string>(
  *   tags: t.array(t.string()),
  *   metadata: t.json(),
  * };
+ *
+ * // With custom types for narrower type inference:
+ * type UserId = string & { readonly __brand: 'UserId' };
+ * type Timestamp = string & { readonly __brand: 'Timestamp' };
+ *
+ * const typedSchema = {
+ *   user_id: t.string<UserId>(),
+ *   created_at: t.dateTime<Timestamp>(),
+ * };
  * ```
  */
 export const t = {
   // ============ String Types ============
 
   /** String type - variable length UTF-8 string */
-  string: () => createValidator<string, "String">("String"),
+  string: <T extends string = string>() =>
+    createValidator<T, "String">("String"),
 
   /** FixedString(N) - fixed length string, padded with null bytes */
-  fixedString: (length: number) =>
-    createValidator<string, `FixedString(${number})`>(`FixedString(${length})`),
+  fixedString: <T extends string = string>(length: number) =>
+    createValidator<T, `FixedString(${number})`>(`FixedString(${length})`),
 
   /** UUID - 16-byte universally unique identifier */
-  uuid: () => createValidator<string, "UUID">("UUID"),
+  uuid: <T extends string = string>() => createValidator<T, "UUID">("UUID"),
 
   // ============ Integer Types ============
 
   /** Int8 - signed 8-bit integer (-128 to 127) */
-  int8: () => createValidator<number, "Int8">("Int8"),
+  int8: <T extends number = number>() => createValidator<T, "Int8">("Int8"),
 
   /** Int16 - signed 16-bit integer */
-  int16: () => createValidator<number, "Int16">("Int16"),
+  int16: <T extends number = number>() => createValidator<T, "Int16">("Int16"),
 
   /** Int32 - signed 32-bit integer */
-  int32: () => createValidator<number, "Int32">("Int32"),
+  int32: <T extends number = number>() => createValidator<T, "Int32">("Int32"),
 
   /** Int64 - signed 64-bit integer (represented as number, may lose precision) */
-  int64: () => createValidator<number, "Int64">("Int64"),
+  int64: <T extends number = number>() => createValidator<T, "Int64">("Int64"),
 
   /** Int128 - signed 128-bit integer (represented as bigint) */
-  int128: () => createValidator<bigint, "Int128">("Int128"),
+  int128: <T extends bigint = bigint>() =>
+    createValidator<T, "Int128">("Int128"),
 
   /** Int256 - signed 256-bit integer (represented as bigint) */
-  int256: () => createValidator<bigint, "Int256">("Int256"),
+  int256: <T extends bigint = bigint>() =>
+    createValidator<T, "Int256">("Int256"),
 
   /** UInt8 - unsigned 8-bit integer (0 to 255) */
-  uint8: () => createValidator<number, "UInt8">("UInt8"),
+  uint8: <T extends number = number>() => createValidator<T, "UInt8">("UInt8"),
 
   /** UInt16 - unsigned 16-bit integer */
-  uint16: () => createValidator<number, "UInt16">("UInt16"),
+  uint16: <T extends number = number>() =>
+    createValidator<T, "UInt16">("UInt16"),
 
   /** UInt32 - unsigned 32-bit integer */
-  uint32: () => createValidator<number, "UInt32">("UInt32"),
+  uint32: <T extends number = number>() =>
+    createValidator<T, "UInt32">("UInt32"),
 
   /** UInt64 - unsigned 64-bit integer (represented as number, may lose precision) */
-  uint64: () => createValidator<number, "UInt64">("UInt64"),
+  uint64: <T extends number = number>() =>
+    createValidator<T, "UInt64">("UInt64"),
 
   /** UInt128 - unsigned 128-bit integer (represented as bigint) */
-  uint128: () => createValidator<bigint, "UInt128">("UInt128"),
+  uint128: <T extends bigint = bigint>() =>
+    createValidator<T, "UInt128">("UInt128"),
 
   /** UInt256 - unsigned 256-bit integer (represented as bigint) */
-  uint256: () => createValidator<bigint, "UInt256">("UInt256"),
+  uint256: <T extends bigint = bigint>() =>
+    createValidator<T, "UInt256">("UInt256"),
 
   // ============ Float Types ============
 
   /** Float32 - 32-bit floating point */
-  float32: () => createValidator<number, "Float32">("Float32"),
+  float32: <T extends number = number>() =>
+    createValidator<T, "Float32">("Float32"),
 
   /** Float64 - 64-bit floating point (double precision) */
-  float64: () => createValidator<number, "Float64">("Float64"),
+  float64: <T extends number = number>() =>
+    createValidator<T, "Float64">("Float64"),
 
   /** Decimal(precision, scale) - fixed-point decimal number */
-  decimal: (precision: number, scale: number) =>
-    createValidator<number, `Decimal(${number}, ${number})`>(
-      `Decimal(${precision}, ${scale})`
+  decimal: <T extends number = number>(precision: number, scale: number) =>
+    createValidator<T, `Decimal(${number}, ${number})`>(
+      `Decimal(${precision}, ${scale})`,
     ),
 
   // ============ Boolean ============
 
   /** Bool - boolean value (true/false) */
-  bool: () => createValidator<boolean, "Bool">("Bool"),
+  bool: <T extends boolean = boolean>() => createValidator<T, "Bool">("Bool"),
 
   // ============ Date/Time Types ============
 
   /** Date - string in YYYY-MM-DD format (e.g. 2024-01-15) */
-  date: () => createValidator<string, "Date">("Date"),
+  date: <T extends string = string>() => createValidator<T, "Date">("Date"),
 
   /** Date32 - string in YYYY-MM-DD format (e.g. 2024-01-15, extended date range) */
-  date32: () => createValidator<string, "Date32">("Date32"),
+  date32: <T extends string = string>() =>
+    createValidator<T, "Date32">("Date32"),
 
   /** DateTime - string in YYYY-MM-DD HH:MM:SS format (e.g. 2024-01-15 10:30:00) */
-  dateTime: (timezone?: string) =>
+  dateTime: <T extends string = string>(timezone?: string) =>
     timezone
-      ? createValidator<string, `DateTime('${string}')`>(`DateTime('${timezone}')`)
-      : createValidator<string, "DateTime">("DateTime"),
+      ? createValidator<T, `DateTime('${string}')`>(`DateTime('${timezone}')`)
+      : createValidator<T, "DateTime">("DateTime"),
 
   /** DateTime64 - string in YYYY-MM-DD HH:MM:SS[.fraction] format (e.g. 2024-01-15 10:30:00.123) */
-  dateTime64: (precision: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 = 3, timezone?: string) =>
+  dateTime64: <T extends string = string>(
+    precision: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 = 3,
+    timezone?: string,
+  ) =>
     timezone
-      ? createValidator<string, `DateTime64(${number}, '${string}')`>(
-          `DateTime64(${precision}, '${timezone}')`
+      ? createValidator<T, `DateTime64(${number}, '${string}')`>(
+          `DateTime64(${precision}, '${timezone}')`,
         )
-      : createValidator<string, `DateTime64(${number})`>(`DateTime64(${precision})`),
+      : createValidator<T, `DateTime64(${number})`>(`DateTime64(${precision})`),
 
   // ============ Complex Types ============
 
   /** Array(T) - array of elements of type T */
   array: <TElement extends TypeValidator<unknown, string, TypeModifiers>>(
-    element: TElement
+    element: TElement,
   ): TypeValidator<
     TElement["_type"][],
     `Array(${TElement["_tinybirdType"]})`,
     TypeModifiers
   > =>
     createValidator<TElement["_type"][], `Array(${TElement["_tinybirdType"]})`>(
-      `Array(${element._tinybirdType})` as `Array(${TElement["_tinybirdType"]})`
+      `Array(${element._tinybirdType})` as `Array(${TElement["_tinybirdType"]})`,
     ),
 
   /** Tuple(T1, T2, ...) - tuple of heterogeneous types */
-  tuple: <TElements extends readonly TypeValidator<unknown, string, TypeModifiers>[]>(
+  tuple: <
+    TElements extends readonly TypeValidator<unknown, string, TypeModifiers>[],
+  >(
     ...elements: TElements
   ): TypeValidator<
     { [K in keyof TElements]: TElements[K]["_type"] },
@@ -263,10 +340,10 @@ export const t = {
   /** Map(K, V) - dictionary/map type */
   map: <
     TKey extends TypeValidator<string | number, string, TypeModifiers>,
-    TValue extends TypeValidator<unknown, string, TypeModifiers>
+    TValue extends TypeValidator<unknown, string, TypeModifiers>,
   >(
     keyType: TKey,
-    valueType: TValue
+    valueType: TValue,
   ): TypeValidator<
     Map<TKey["_type"], TValue["_type"]>,
     `Map(${TKey["_tinybirdType"]}, ${TValue["_tinybirdType"]})`,
@@ -288,7 +365,7 @@ export const t = {
       .map((v, i) => `'${v.replace(/'/g, "\\'")}' = ${i + 1}`)
       .join(", ");
     return createValidator<TValues[number], `Enum8(${string})`>(
-      `Enum8(${enumMapping})` as `Enum8(${string})`
+      `Enum8(${enumMapping})` as `Enum8(${string})`,
     );
   },
 
@@ -298,27 +375,27 @@ export const t = {
       .map((v, i) => `'${v.replace(/'/g, "\\'")}' = ${i + 1}`)
       .join(", ");
     return createValidator<TValues[number], `Enum16(${string})`>(
-      `Enum16(${enumMapping})` as `Enum16(${string})`
+      `Enum16(${enumMapping})` as `Enum16(${string})`,
     );
   },
 
   // ============ Special Types ============
 
   /** IPv4 - IPv4 address */
-  ipv4: () => createValidator<string, "IPv4">("IPv4"),
+  ipv4: <T extends string = string>() => createValidator<T, "IPv4">("IPv4"),
 
   /** IPv6 - IPv6 address */
-  ipv6: () => createValidator<string, "IPv6">("IPv6"),
+  ipv6: <T extends string = string>() => createValidator<T, "IPv6">("IPv6"),
 
   // ============ Aggregate Function States ============
 
   /** SimpleAggregateFunction - for materialized views with simple aggregates */
   simpleAggregateFunction: <
     TFunc extends string,
-    TType extends TypeValidator<unknown, string, TypeModifiers>
+    TType extends TypeValidator<unknown, string, TypeModifiers>,
   >(
     func: TFunc,
-    type: TType
+    type: TType,
   ): TypeValidator<
     TType["_type"],
     `SimpleAggregateFunction(${TFunc}, ${TType["_tinybirdType"]})`,
@@ -332,10 +409,10 @@ export const t = {
   /** AggregateFunction - for materialized views with complex aggregates */
   aggregateFunction: <
     TFunc extends string,
-    TType extends TypeValidator<unknown, string, TypeModifiers>
+    TType extends TypeValidator<unknown, string, TypeModifiers>,
   >(
     func: TFunc,
-    type: TType
+    type: TType,
   ): TypeValidator<
     TType["_type"],
     `AggregateFunction(${TFunc}, ${TType["_tinybirdType"]})`,