From 2cc08dd7fa0d16a3c026c108620941a1b92c06f5 Mon Sep 17 00:00:00 2001
From: Wyatt Schulte <wyatt@joinwarp.com>
Date: Tue, 24 Feb 2026 17:21:30 -0500
Subject: [PATCH] implement generic types on all column types

---
 src/schema/types.test.ts | 390 +++++++++++++++++++++++++++++----------
 src/schema/types.ts      | 213 ++++++++++++++-------
 2 files changed, 439 insertions(+), 164 deletions(-)

diff --git a/src/schema/types.test.ts b/src/schema/types.test.ts
index 1177300..17a3903 100644
--- a/src/schema/types.test.ts
+++ b/src/schema/types.test.ts
@@ -1,226 +1,424 @@
-import { describe, it, expect } from 'vitest';
-import { t, isTypeValidator, getTinybirdType, getModifiers } from './types.js';
-
-describe('Type Validators (t.*)', () => {
-  describe('Basic types', () => {
-    it('generates String type', () => {
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { t, isTypeValidator, getTinybirdType, getModifiers } from "./types.js";
+import { defineDatasource } from "./datasource.js";
+import { engine } from "./engines.js";
+import type { InferRow } from "../infer/index.js";
+
+describe("Type Validators (t.*)", () => {
+  describe("Basic types", () => {
+    it("generates String type", () => {
       const type = t.string();
-      expect(type._tinybirdType).toBe('String');
+      expect(type._tinybirdType).toBe("String");
     });
 
-    it('generates Int32 type', () => {
+    it("generates Int32 type", () => {
       const type = t.int32();
-      expect(type._tinybirdType).toBe('Int32');
+      expect(type._tinybirdType).toBe("Int32");
     });
 
-    it('generates DateTime type', () => {
+    it("generates DateTime type", () => {
       const type = t.dateTime();
-      expect(type._tinybirdType).toBe('DateTime');
+      expect(type._tinybirdType).toBe("DateTime");
     });
 
-    it('generates DateTime with timezone', () => {
-      const type = t.dateTime('UTC');
+    it("generates DateTime with timezone", () => {
+      const type = t.dateTime("UTC");
       expect(type._tinybirdType).toBe("DateTime('UTC')");
     });
 
-    it('generates Bool type', () => {
+    it("generates Bool type", () => {
       const type = t.bool();
-      expect(type._tinybirdType).toBe('Bool');
+      expect(type._tinybirdType).toBe("Bool");
     });
 
-    it('generates UUID type', () => {
+    it("generates UUID type", () => {
       const type = t.uuid();
-      expect(type._tinybirdType).toBe('UUID');
+      expect(type._tinybirdType).toBe("UUID");
     });
 
-    it('generates Float64 type', () => {
+    it("generates Float64 type", () => {
       const type = t.float64();
-      expect(type._tinybirdType).toBe('Float64');
+      expect(type._tinybirdType).toBe("Float64");
     });
 
-    it('generates UInt64 type', () => {
+    it("generates UInt64 type", () => {
       const type = t.uint64();
-      expect(type._tinybirdType).toBe('UInt64');
+      expect(type._tinybirdType).toBe("UInt64");
     });
   });
 
-  describe('Nullable modifier', () => {
-    it('wraps type in Nullable', () => {
+  describe("Nullable modifier", () => {
+    it("wraps type in Nullable", () => {
       const type = t.string().nullable();
-      expect(type._tinybirdType).toBe('Nullable(String)');
+      expect(type._tinybirdType).toBe("Nullable(String)");
     });
 
-    it('wraps Int32 in Nullable', () => {
+    it("wraps Int32 in Nullable", () => {
       const type = t.int32().nullable();
-      expect(type._tinybirdType).toBe('Nullable(Int32)');
+      expect(type._tinybirdType).toBe("Nullable(Int32)");
     });
 
-    it('sets nullable modifier', () => {
+    it("sets nullable modifier", () => {
       const type = t.string().nullable();
       expect(type._modifiers.nullable).toBe(true);
     });
   });
 
-  describe('LowCardinality modifier', () => {
-    it('wraps type in LowCardinality', () => {
+  describe("LowCardinality modifier", () => {
+    it("wraps type in LowCardinality", () => {
       const type = t.string().lowCardinality();
-      expect(type._tinybirdType).toBe('LowCardinality(String)');
+      expect(type._tinybirdType).toBe("LowCardinality(String)");
     });
 
-    it('sets lowCardinality modifier', () => {
+    it("sets lowCardinality modifier", () => {
       const type = t.string().lowCardinality();
       expect(type._modifiers.lowCardinality).toBe(true);
     });
   });
 
-  describe('LowCardinality + Nullable ordering', () => {
-    it('generates LowCardinality(Nullable(X)) when chaining .lowCardinality().nullable()', () => {
+  describe("LowCardinality + Nullable ordering", () => {
+    it("generates LowCardinality(Nullable(X)) when chaining .lowCardinality().nullable()", () => {
       const type = t.string().lowCardinality().nullable();
-      expect(type._tinybirdType).toBe('LowCardinality(Nullable(String))');
+      expect(type._tinybirdType).toBe("LowCardinality(Nullable(String))");
     });
 
-    it('generates LowCardinality(Nullable(X)) when chaining .nullable().lowCardinality()', () => {
+    it("generates LowCardinality(Nullable(X)) when chaining .nullable().lowCardinality()", () => {
       const type = t.string().nullable().lowCardinality();
-      expect(type._tinybirdType).toBe('LowCardinality(Nullable(String))');
+      expect(type._tinybirdType).toBe("LowCardinality(Nullable(String))");
     });
 
-    it('preserves both modifiers when chained', () => {
+    it("preserves both modifiers when chained", () => {
       const type = t.string().lowCardinality().nullable();
       expect(type._modifiers.lowCardinality).toBe(true);
       expect(type._modifiers.nullable).toBe(true);
     });
   });
 
-  describe('Default values', () => {
-    it('sets hasDefault modifier', () => {
-      const type = t.string().default('test');
+  describe("Default values", () => {
+    it("sets hasDefault modifier", () => {
+      const type = t.string().default("test");
       expect(type._modifiers.hasDefault).toBe(true);
     });
 
-    it('stores defaultValue in modifiers', () => {
-      const type = t.string().default('test');
-      expect(type._modifiers.defaultValue).toBe('test');
+    it("stores defaultValue in modifiers", () => {
+      const type = t.string().default("test");
+      expect(type._modifiers.defaultValue).toBe("test");
     });
 
-    it('works with numeric defaults', () => {
+    it("works with numeric defaults", () => {
       const type = t.int32().default(42);
       expect(type._modifiers.defaultValue).toBe(42);
     });
   });
 
-  describe('Codec modifier', () => {
-    it('sets codec in modifiers', () => {
-      const type = t.string().codec('LZ4');
-      expect(type._modifiers.codec).toBe('LZ4');
+  describe("Codec modifier", () => {
+    it("sets codec in modifiers", () => {
+      const type = t.string().codec("LZ4");
+      expect(type._modifiers.codec).toBe("LZ4");
     });
   });
 
-  describe('jsonPath modifier', () => {
-    it('sets jsonPath in modifiers', () => {
-      const type = t.string().jsonPath('$.payload.id');
-      expect(type._modifiers.jsonPath).toBe('$.payload.id');
+  describe("jsonPath modifier", () => {
+    it("sets jsonPath in modifiers", () => {
+      const type = t.string().jsonPath("$.payload.id");
+      expect(type._modifiers.jsonPath).toBe("$.payload.id");
     });
 
-    it('supports chaining with other modifiers', () => {
-      const type = t.string().nullable().jsonPath('$.user.name');
-      expect(type._tinybirdType).toBe('Nullable(String)');
+    it("supports chaining with other modifiers", () => {
+      const type = t.string().nullable().jsonPath("$.user.name");
+      expect(type._tinybirdType).toBe("Nullable(String)");
       expect(type._modifiers.nullable).toBe(true);
-      expect(type._modifiers.jsonPath).toBe('$.user.name');
+      expect(type._modifiers.jsonPath).toBe("$.user.name");
     });
   });
 
-  describe('Complex types', () => {
-    it('generates Array type', () => {
+  describe("Complex types", () => {
+    it("generates Array type", () => {
       const type = t.array(t.string());
-      expect(type._tinybirdType).toBe('Array(String)');
+      expect(type._tinybirdType).toBe("Array(String)");
     });
 
-    it('generates nested Array type', () => {
+    it("generates nested Array type", () => {
       const type = t.array(t.int32());
-      expect(type._tinybirdType).toBe('Array(Int32)');
+      expect(type._tinybirdType).toBe("Array(Int32)");
     });
 
-    it('generates Map type', () => {
+    it("generates Map type", () => {
       const type = t.map(t.string(), t.int32());
-      expect(type._tinybirdType).toBe('Map(String, Int32)');
+      expect(type._tinybirdType).toBe("Map(String, Int32)");
     });
 
-    it('generates Decimal type', () => {
+    it("generates Decimal type", () => {
       const type = t.decimal(10, 2);
-      expect(type._tinybirdType).toBe('Decimal(10, 2)');
+      expect(type._tinybirdType).toBe("Decimal(10, 2)");
     });
 
-    it('generates FixedString type', () => {
+    it("generates FixedString type", () => {
       const type = t.fixedString(3);
-      expect(type._tinybirdType).toBe('FixedString(3)');
+      expect(type._tinybirdType).toBe("FixedString(3)");
     });
 
-    it('generates Tuple type', () => {
+    it("generates Tuple type", () => {
       const type = t.tuple(t.string(), t.int32());
-      expect(type._tinybirdType).toBe('Tuple(String, Int32)');
+      expect(type._tinybirdType).toBe("Tuple(String, Int32)");
     });
 
-    it('generates DateTime64 type', () => {
+    it("generates DateTime64 type", () => {
       const type = t.dateTime64(3);
-      expect(type._tinybirdType).toBe('DateTime64(3)');
+      expect(type._tinybirdType).toBe("DateTime64(3)");
     });
 
-    it('generates DateTime64 with timezone', () => {
-      const type = t.dateTime64(3, 'UTC');
+    it("generates DateTime64 with timezone", () => {
+      const type = t.dateTime64(3, "UTC");
       expect(type._tinybirdType).toBe("DateTime64(3, 'UTC')");
     });
   });
 
-  describe('Helper functions', () => {
-    it('isTypeValidator returns true for validators', () => {
+  describe("Helper functions", () => {
+    it("isTypeValidator returns true for validators", () => {
       expect(isTypeValidator(t.string())).toBe(true);
     });
 
-    it('isTypeValidator returns false for non-validators', () => {
-      expect(isTypeValidator('string')).toBe(false);
+    it("isTypeValidator returns false for non-validators", () => {
+      expect(isTypeValidator("string")).toBe(false);
       expect(isTypeValidator({})).toBe(false);
       expect(isTypeValidator(null)).toBe(false);
     });
 
-    it('getTinybirdType returns type string', () => {
-      expect(getTinybirdType(t.string())).toBe('String');
+    it("getTinybirdType returns type string", () => {
+      expect(getTinybirdType(t.string())).toBe("String");
     });
 
-    it('getModifiers returns modifiers object', () => {
+    it("getModifiers returns modifiers object", () => {
       const modifiers = getModifiers(t.string().nullable());
       expect(modifiers.nullable).toBe(true);
     });
   });
 
-  describe('Chained modifiers', () => {
-    it('supports multiple modifiers', () => {
-      const type = t.string().lowCardinality().default('test');
-      expect(type._tinybirdType).toBe('LowCardinality(String)');
+  describe("Chained modifiers", () => {
+    it("supports multiple modifiers", () => {
+      const type = t.string().lowCardinality().default("test");
+      expect(type._tinybirdType).toBe("LowCardinality(String)");
       expect(type._modifiers.lowCardinality).toBe(true);
       expect(type._modifiers.hasDefault).toBe(true);
-      expect(type._modifiers.defaultValue).toBe('test');
+      expect(type._modifiers.defaultValue).toBe("test");
     });
   });
 
-  describe('Enum types', () => {
-    it('generates Enum8 with value mapping', () => {
-      const type = t.enum8('active', 'inactive', 'pending');
-      expect(type._tinybirdType).toBe("Enum8('active' = 1, 'inactive' = 2, 'pending' = 3)");
+  describe("Enum types", () => {
+    it("generates Enum8 with value mapping", () => {
+      const type = t.enum8("active", "inactive", "pending");
+      expect(type._tinybirdType).toBe(
+        "Enum8('active' = 1, 'inactive' = 2, 'pending' = 3)",
+      );
     });
 
-    it('generates Enum16 with value mapping', () => {
-      const type = t.enum16('draft', 'published', 'archived');
-      expect(type._tinybirdType).toBe("Enum16('draft' = 1, 'published' = 2, 'archived' = 3)");
+    it("generates Enum16 with value mapping", () => {
+      const type = t.enum16("draft", "published", "archived");
+      expect(type._tinybirdType).toBe(
+        "Enum16('draft' = 1, 'published' = 2, 'archived' = 3)",
+      );
     });
 
-    it('escapes single quotes in enum values', () => {
-      const type = t.enum8("it's ok", 'normal');
+    it("escapes single quotes in enum values", () => {
+      const type = t.enum8("it's ok", "normal");
       expect(type._tinybirdType).toBe("Enum8('it\\'s ok' = 1, 'normal' = 2)");
     });
 
-    it('handles single enum value', () => {
-      const type = t.enum8('only');
+    it("handles single enum value", () => {
+      const type = t.enum8("only");
       expect(type._tinybirdType).toBe("Enum8('only' = 1)");
     });
   });
+
+  describe("Custom type generics", () => {
+    // Branded/nominal type helpers for testing
+    type UserId = string & { readonly __brand: "UserId" };
+    type TraceId = string & { readonly __brand: "TraceId" };
+    type Timestamp = string & { readonly __brand: "Timestamp" };
+    type Count = number & { readonly __brand: "Count" };
+    type Price = number & { readonly __brand: "Price" };
+    type BigId = bigint & { readonly __brand: "BigId" };
+    type IsActive = boolean & { readonly __brand: "IsActive" };
+
+    describe("runtime behavior unchanged", () => {
+      it("string with generic produces same _tinybirdType", () => {
+        expect(t.string<UserId>()._tinybirdType).toBe(t.string()._tinybirdType);
+        expect(t.string<UserId>()._tinybirdType).toBe("String");
+      });
+
+      it("int32 with generic produces same _tinybirdType", () => {
+        expect(t.int32<Count>()._tinybirdType).toBe(t.int32()._tinybirdType);
+      });
+
+      it("uuid with generic produces same _tinybirdType", () => {
+        expect(t.uuid<TraceId>()._tinybirdType).toBe("UUID");
+      });
+
+      it("dateTime with generic produces same _tinybirdType", () => {
+        expect(t.dateTime<Timestamp>()._tinybirdType).toBe("DateTime");
+        expect(t.dateTime<Timestamp>("UTC")._tinybirdType).toBe(
+          "DateTime('UTC')",
+        );
+      });
+
+      it("bool with generic produces same _tinybirdType", () => {
+        expect(t.bool<IsActive>()._tinybirdType).toBe("Bool");
+      });
+
+      it("int128 with generic produces same _tinybirdType", () => {
+        expect(t.int128<BigId>()._tinybirdType).toBe("Int128");
+      });
+
+      it("decimal with generic produces same _tinybirdType", () => {
+        expect(t.decimal<Price>(10, 2)._tinybirdType).toBe("Decimal(10, 2)");
+      });
+
+      it("fixedString with generic produces same _tinybirdType", () => {
+        type CountryCode = string & { readonly __brand: "CountryCode" };
+        expect(t.fixedString<CountryCode>(2)._tinybirdType).toBe(
+          "FixedString(2)",
+        );
+      });
+    });
+
+    describe("modifiers work with custom generics", () => {
+      it("nullable", () => {
+        const v = t.string<UserId>().nullable();
+        expect(v._tinybirdType).toBe("Nullable(String)");
+        expect(v._modifiers.nullable).toBe(true);
+      });
+
+      it("lowCardinality", () => {
+        expect(t.string<UserId>().lowCardinality()._tinybirdType).toBe(
+          "LowCardinality(String)",
+        );
+      });
+
+      it("default", () => {
+        const v = t.string<UserId>().default("fallback" as UserId);
+        expect(v._modifiers.hasDefault).toBe(true);
+        expect(v._modifiers.defaultValue).toBe("fallback");
+      });
+    });
+
+    describe("type inference", () => {
+      it("validators without generics still infer base types", () => {
+        expectTypeOf(t.string()._type).toEqualTypeOf<string>();
+        expectTypeOf(t.int32()._type).toEqualTypeOf<number>();
+        expectTypeOf(t.bool()._type).toEqualTypeOf<boolean>();
+        expectTypeOf(t.int128()._type).toEqualTypeOf<bigint>();
+        expectTypeOf(t.uuid()._type).toEqualTypeOf<string>();
+      });
+
+      it("validators with generics infer the custom type", () => {
+        expectTypeOf(t.string<UserId>()._type).toEqualTypeOf<UserId>();
+        expectTypeOf(t.uuid<TraceId>()._type).toEqualTypeOf<TraceId>();
+        expectTypeOf(t.int32<Count>()._type).toEqualTypeOf<Count>();
+        expectTypeOf(t.bool<IsActive>()._type).toEqualTypeOf<IsActive>();
+        expectTypeOf(t.int128<BigId>()._type).toEqualTypeOf<BigId>();
+        expectTypeOf(t.dateTime<Timestamp>()._type).toEqualTypeOf<Timestamp>();
+        expectTypeOf(
+          t.dateTime<Timestamp>("UTC")._type,
+        ).toEqualTypeOf<Timestamp>();
+        expectTypeOf(
+          t.dateTime64<Timestamp>(3)._type,
+        ).toEqualTypeOf<Timestamp>();
+        expectTypeOf(t.decimal<Price>(10, 2)._type).toEqualTypeOf<Price>();
+      });
+
+      it("custom types flow through nullable", () => {
+        expectTypeOf(
+          t.string<UserId>().nullable()._type,
+        ).toEqualTypeOf<UserId | null>();
+        expectTypeOf(
+          t.int32<Count>().nullable()._type,
+        ).toEqualTypeOf<Count | null>();
+      });
+
+      it("custom types flow through lowCardinality", () => {
+        expectTypeOf(
+          t.string<UserId>().lowCardinality()._type,
+        ).toEqualTypeOf<UserId>();
+      });
+
+      it("custom types flow through InferRow", () => {
+        const ds = defineDatasource("test_custom_types", {
+          schema: {
+            user_id: t.string<UserId>(),
+            event_count: t.int32<Count>(),
+            created_at: t.dateTime<Timestamp>(),
+            name: t.string(),
+          },
+          engine: engine.mergeTree({ sortingKey: ["user_id"] }),
+        });
+
+        type Row = InferRow<typeof ds>;
+
+        expectTypeOf<Row["user_id"]>().toEqualTypeOf<UserId>();
+        expectTypeOf<Row["event_count"]>().toEqualTypeOf<Count>();
+        expectTypeOf<Row["created_at"]>().toEqualTypeOf<Timestamp>();
+        expectTypeOf<Row["name"]>().toEqualTypeOf<string>();
+      });
+
+      it("rejects generics that violate base type constraint", () => {
+        // @ts-expect-error - number does not extend string
+        t.string<number>();
+
+        // @ts-expect-error - string does not extend number
+        t.int32<string>();
+
+        // @ts-expect-error - string does not extend boolean
+        t.bool<string>();
+
+        // @ts-expect-error - number does not extend bigint
+        t.int128<number>();
+      });
+    });
+
+    describe("all validators accept custom generics", () => {
+      it("string-based validators", () => {
+        type S = string & { readonly __brand: "S" };
+        expectTypeOf(t.string<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.fixedString<S>(10)._type).toEqualTypeOf<S>();
+        expectTypeOf(t.uuid<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.ipv4<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.ipv6<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.date<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.date32<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.dateTime<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.dateTime<S>("UTC")._type).toEqualTypeOf<S>();
+        expectTypeOf(t.dateTime64<S>()._type).toEqualTypeOf<S>();
+        expectTypeOf(t.dateTime64<S>(6, "UTC")._type).toEqualTypeOf<S>();
+      });
+
+      it("number-based validators", () => {
+        type N = number & { readonly __brand: "N" };
+        expectTypeOf(t.int8<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.int16<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.int32<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.int64<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.uint8<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.uint16<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.uint32<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.uint64<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.float32<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.float64<N>()._type).toEqualTypeOf<N>();
+        expectTypeOf(t.decimal<N>(10, 2)._type).toEqualTypeOf<N>();
+      });
+
+      it("bigint-based validators", () => {
+        type B = bigint & { readonly __brand: "B" };
+        expectTypeOf(t.int128<B>()._type).toEqualTypeOf<B>();
+        expectTypeOf(t.int256<B>()._type).toEqualTypeOf<B>();
+        expectTypeOf(t.uint128<B>()._type).toEqualTypeOf<B>();
+        expectTypeOf(t.uint256<B>()._type).toEqualTypeOf<B>();
+      });
+
+      it("boolean-based validators", () => {
+        type Bool = boolean & { readonly __brand: "Bool" };
+        expectTypeOf(t.bool<Bool>()._type).toEqualTypeOf<Bool>();
+      });
+    });
+  });
 });
diff --git a/src/schema/types.ts b/src/schema/types.ts
index 22e5f17..b3cf660 100644
--- a/src/schema/types.ts
+++ b/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"]})`,