@intentius/chant-lexicon-sql 0.122.0 → 0.123.0

package/dist/sql-types-command.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `chant sql types [--output <path>] [--check]` (#3751): build the project the way
+ * `chant build` does, folded, and write the declarations
+ * {@link renderSqlTypes} renders from its entities, so a tag given its
+ * qualified name as the type argument has typed columns.
+ *
+ * The file goes to `<sourceDir>/sql-types.d.ts` (the project root when
+ * `sourceDir` is unset), where any tsconfig that includes the schema includes
+ * it too. `--output` puts it elsewhere, as a workspace `generated` entry's
+ * generator does. The command refuses to write beside a `sql-types.ts`: tsc
+ * resolves the `.ts` first and would drop the declarations. `chant build`
+ * never writes the file. `--check` renders the same text and compares it with
+ * the file instead of writing it: exit 1, naming the file, when they differ.
+ */
+import type { CommandGroupContext } from "@intentius/chant/cli/command-group";
+/** The file tsc would read instead of `path`: `sql-types.ts` beside `sql-types.d.ts`. */
+export declare function shadowingSource(path: string): string | undefined;
+export declare function runTypes(ctx: CommandGroupContext): Promise<number>;
+//# sourceMappingURL=sql-types-command.d.ts.map

package/dist/sql-types-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-types-command.d.ts","sourceRoot":"","sources":["../src/sql-types-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAqB9E,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIhE;AAED,wBAAsB,QAAQ,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqDxE"}

package/dist/sql-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The declarations `chant sql types` writes (#3751): one `sql-types.d.ts`
+ * that augments the dialect's `SqlSchema` with every table, view and
+ * dictionary the build declares, keyed by qualified name.
+ *
+ * {@link renderSqlTypes} is pure: the entities of a build in, the file's text
+ * out. It reads the objects as the serializer writes them, so a `.sql`
+ * file's objects and a composite's members are covered exactly as the build
+ * covers them, and it reads each template's slot record (`core/typed.ts`) for
+ * the `${}` positions a foreign key or a sort key consumes.
+ *
+ * Each column is a `Column<sqlType, { ts, nullable, cmp }>`:
+ *
+ * - `sqlType` is the type as the catalog spells it (`bigint`,
+ *   `timestamp(3) with time zone`, `Nullable(String)`);
+ * - `ts` is its value in application code (`./postgres/row-types.ts`,
+ *   `./clickhouse/row-types.ts`);
+ * - `nullable` is whether the value can be NULL. A Postgres view's columns
+ *   always can, as the server's own catalog says; a column whose type the
+ *   generator cannot tell is `never`, which fits every slot;
+ * - `cmp` is how it compares in a key: SQLPG124's type identity in Postgres
+ *   (`./lint/post-synth/postgres-names.ts`'s `typeIdentity`), the type
+ *   family in ClickHouse; `never` when it cannot be told.
+ *
+ * A view's column that is one column reference (`${t.columns.c}`, `o.${t.columns.c}`)
+ * is that column's type; any other expression is `unknown`.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SqlDialect } from "./dialects.js";
+/** The file `chant sql types` writes, in the project's source directory. */
+export declare const SQL_TYPES_FILE = "sql-types.d.ts";
+/**
+ * Where `chant sql types` writes the file by default: the project's
+ * `sourceDir`, or the project root when it is unset.
+ */
+export declare function sqlTypesPath(projectDir: string, config: Record<string, unknown> | undefined): string;
+/** The file on disk against what the build's entities render: `missing`, `stale` or `current`. */
+export declare function sqlTypesState(entities: ReadonlyMap<string, Declarable>, file: string, opts?: RenderSqlTypesOptions): "missing" | "stale" | "current";
+/** The module each dialect's `SqlSchema` is augmented in. */
+export declare const SQL_TYPES_MODULE: Readonly<Record<SqlDialect, string>>;
+export interface RenderSqlTypesOptions {
+    /** The directory each declaration's source file is named relative to. Default: the working directory. */
+    projectDir?: string;
+    /** The project's config: `sql.postgresMajor` for the catalog, `sql.dialect` when nothing is declared. */
+    config?: Record<string, unknown>;
+}
+/**
+ * The `sql-types.d.ts` for a build's entities: one module that augments the
+ * dialect's `SqlSchema` with each table, view and dictionary, in key order.
+ * Pure, so a check can render it in memory and compare it with the file.
+ */
+export declare function renderSqlTypes(entities: ReadonlyMap<string, Declarable>, opts?: RenderSqlTypesOptions): string;
+//# sourceMappingURL=sql-types.d.ts.map

package/dist/sql-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-types.d.ts","sourceRoot":"","sources":["../src/sql-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAW9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAQ7C,4EAA4E;AAC5E,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAGpG;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EACzC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,qBAA0B,GAC/B,SAAS,GAAG,OAAO,GAAG,SAAS,CASjC;AAED,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAGjE,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,yGAAyG;IACzG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yGAAyG;IACzG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAiOD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,IAAI,GAAE,qBAA0B,GAAG,MAAM,CAiClH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-sql",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "description": "SQL lexicon for chant — database schema as typed declarations, one dialect at a time; ClickHouse first, with types read from a pinned server's catalog",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -70,7 +70,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.122.0",
+    "@intentius/chant": "^0.123.0",
     "typescript": "^5.9.3"
   }
 }

package/src/clickhouse/dictionary.test.ts

@@ -171,7 +171,7 @@ describe("importing a dictionary", () => {
     ]);
     const [file] = new ClickHouseGenerator().generate(ir);
     expect(file!.content).toContain('import { database, dictionary } from "@intentius/chant-lexicon-sql/clickhouse";');
-    expect(file!.content).toContain("export const ratesDict = dictionary`");
+    expect(file!.content).toContain(`export const ratesDict = dictionary<"shop.rates_dict">\``);
     expect(file!.content).toContain("CREATE DICTIONARY ${shopDb}.rates_dict");
   });
 });

package/src/clickhouse/entities.ts

@@ -46,10 +46,12 @@ import { feed, lineage, spanText as text, splice as spliceWith, templateSyntaxEr
 import { SQL_LEXICON, SqlObject, isColumnRefOf, isSqlObjectOf, makeSqlEntity } from "../core/entity";
 import type { LineageEdge } from "../core/references";
 import { SqlLiteral, SqlTemplateError, describeValue as describe, stripUnset as strip, templateParts } from "../core/template";
+import { setTypedSlots, type ColumnsIn, type Named, type RowIn, type SlotsIn, type TypedSlot, type Unnamed } from "../core/typed";
 
 export { SQL_LEXICON } from "../core/entity";
 export type { LineageEdge } from "../core/references";
 export { SqlLiteral, SqlTemplateError, templateParts, unescapeTemplateDelimiters } from "../core/template";
+export type { AnyColumn, Column, ColumnTraits, KeyColumn, Named, NotNullColumn, UncheckedColumn, Unnamed } from "../core/typed";
 
 export const CLICKHOUSE_ENTITY_TYPES = {
   database: "ClickHouse::Database",
@@ -198,18 +200,31 @@ export interface ClickHouseDatabase extends ClickHouseObject {
   readonly props: DatabaseProps;
 }
 
-/** A table or a view: something with columns that SQL can reference. */
-export interface ClickHouseRelation extends ClickHouseObject {
+/**
+ * Every ClickHouse table, view and dictionary the project declares, keyed by
+ * its qualified name (`shop.events`). Empty here; the `sql-types.d.ts` that
+ * `chant sql types` writes augments it, and a tag given the name as its type
+ * argument reads its columns from there.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmented by the generated declarations
+export interface SqlSchema {}
+
+/**
+ * A table or a view: something with columns that SQL can reference. `N` is
+ * its qualified name when its tag was given one (`` table<"shop.events">`...` ``):
+ * its columns are then the generated declarations' entry for that name.
+ */
+export interface ClickHouseRelation<N extends string = string> extends ClickHouseObject, Named<N> {
   /** One reference per column, by name: `${events.columns.user_id}`. */
-  readonly columns: Readonly<Record<string, AttrRef>>;
+  readonly columns: ColumnsIn<SqlSchema, N>;
 }
 
-export interface ClickHouseTable extends ClickHouseRelation {
+export interface ClickHouseTable<N extends string = string> extends ClickHouseRelation<N> {
   readonly entityType: "ClickHouse::Table";
   readonly props: TableProps;
 }
 
-export interface ClickHouseView extends ClickHouseRelation {
+export interface ClickHouseView<N extends string = string> extends ClickHouseRelation<N> {
   readonly entityType: "ClickHouse::View" | "ClickHouse::MaterializedView";
   readonly props: ViewProps;
 }
@@ -312,7 +327,7 @@ export interface ClickHouseGrant extends ClickHouseObject {
 }
 
 /** A dictionary: its attributes are columns `dictGet` reads, so SQL can reference them. */
-export interface ClickHouseDictionary extends ClickHouseRelation {
+export interface ClickHouseDictionary<N extends string = string> extends ClickHouseRelation<N> {
   readonly entityType: "ClickHouse::Dictionary";
   readonly props: DictionaryProps;
 }
@@ -327,6 +342,14 @@ function makeEntity(
   return makeSqlEntity(ClickHouseObject.prototype as ClickHouseObject, entityType, sqlName, props, columnNames, dependsOn);
 }
 
+/**
+ * A declared table's, view's or dictionary's row, for application code:
+ * `RowOf<typeof events>` for a declaration given its name, or
+ * `RowOf<"shop.users">` by name, which also covers an object only a `.sql`
+ * file declares.
+ */
+export type RowOf<T extends keyof SqlSchema | Named<keyof SqlSchema & string>> = RowIn<SqlSchema, T>;
+
 export function isClickHouseObject(value: unknown): value is ClickHouseObject {
   return isSqlObjectOf(value, "ClickHouse::");
 }
@@ -444,6 +467,42 @@ function qualified(ctx: Ctx, span: Span): { database?: string; name: string } {
   return pieces.length >= 2 ? { database: pieces[pieces.length - 2], name: pieces[pieces.length - 1]! } : { name: pieces[0] ?? "" };
 }
 
+/**
+ * The `${}` that stand alone as an element of a sort key (`ORDER BY ${t.columns.a}`,
+ * `ORDER BY (${t.columns.a}, b)`), each a column that must not be Nullable
+ * (#3751). An element inside an expression (`ifNull(${...}, '')`) is not one.
+ */
+function sortKeySlots(ctx: Ctx, span: Span | undefined): TypedSlot[] {
+  if (!span) return [];
+  let sig = ctx.tokens.slice(span.from, span.to).filter((t) => !isTrivia(t));
+  const isPunct = (i: number, p: string) => sig[i]?.kind === "punct" && sig[i]!.text === p;
+  if (isPunct(0, "(") && isPunct(sig.length - 1, ")")) {
+    let depth = 0;
+    let closesAt = -1;
+    for (let i = 0; i < sig.length && closesAt < 0; i++) {
+      if (isPunct(i, "(")) depth++;
+      else if (isPunct(i, ")") && --depth === 0) closesAt = i;
+    }
+    if (closesAt === sig.length - 1) sig = sig.slice(1, -1);
+  }
+  const out: TypedSlot[] = [];
+  let depth = 0;
+  let element: typeof sig = [];
+  const flush = () => {
+    const t = element[0];
+    if (element.length === 1 && t?.kind === "ref" && isColumnRef(ctx.values[t.part])) out.push({ index: t.part, kind: "sortKey" });
+    element = [];
+  };
+  for (const t of sig) {
+    if (t.kind === "punct" && t.text === "(") depth++;
+    else if (t.kind === "punct" && t.text === ")") depth--;
+    if (depth === 0 && t.kind === "punct" && t.text === ",") flush();
+    else element.push(t);
+  }
+  flush();
+  return out;
+}
+
 type Expect = "database" | "table" | "view" | "dictionary" | "func";
 
 function build(tag: Expect, strings: TemplateStringsArray | readonly string[], values: readonly unknown[]): ClickHouseObject {
@@ -484,6 +543,7 @@ function build(tag: Expect, strings: TemplateStringsArray | readonly string[], v
   };
   const done = <T extends ClickHouseObject>(entity: T): T => {
     setInterpolationFields(entity, ctx.fed.map((paths) => [...paths].sort()));
+    if (node.statement === "table" || node.statement === "view") setTypedSlots(entity, [...sortKeySlots(ctx, node.orderBy), ...sortKeySlots(ctx, node.primaryKey)]);
     return entity;
   };
 
@@ -625,17 +685,22 @@ export function database(strings: TemplateStringsArray, ...values: unknown[]): C
   return build("database", strings, values) as ClickHouseDatabase;
 }
 
-/** `` table`CREATE TABLE ...` ``: one ClickHouse table, parsed at build time. */
-export function table(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseTable {
-  return build("table", strings, values) as ClickHouseTable;
+/**
+ * `` table`CREATE TABLE ...` ``: one ClickHouse table, parsed at build time.
+ * Given its qualified name as the type argument (`` table<"shop.events">`...` ``),
+ * its columns are the ones `chant sql types` declared for that name.
+ */
+export function table<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: SlotsIn<SqlSchema, N>): ClickHouseTable<N> {
+  return build("table", strings, values) as ClickHouseTable<N>;
 }
 
 /**
  * `` view`CREATE [MATERIALIZED] VIEW ...` ``: one view or materialized view,
- * with the tables it reads and its column lineage.
+ * with the tables it reads and its column lineage. Takes its qualified name
+ * as the type argument, as {@link table} does.
  */
-export function view(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseView {
-  return build("view", strings, values) as ClickHouseView;
+export function view<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: SlotsIn<SqlSchema, N>): ClickHouseView<N> {
+  return build("view", strings, values) as ClickHouseView<N>;
 }
 
 /**
@@ -643,8 +708,8 @@ export function view(strings: TemplateStringsArray, ...values: unknown[]): Click
  * key, source, layout and lifetime, parsed at build time (#3682). Its
  * attributes are columns: `${rates.columns.rate}`.
  */
-export function dictionary(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseDictionary {
-  return build("dictionary", strings, values) as ClickHouseDictionary;
+export function dictionary<const N extends string = Unnamed>(strings: TemplateStringsArray, ...values: SlotsIn<SqlSchema, N>): ClickHouseDictionary<N> {
+  return build("dictionary", strings, values) as ClickHouseDictionary<N>;
 }
 
 /**

package/src/clickhouse/import/generator.ts

@@ -6,6 +6,7 @@
  * without import cycles.
  */
 
+import { relationKey } from "../../core/typed";
 import type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
 import type { TemplateIR } from "@intentius/chant/import/parser";
 import { isTrivia, tokenizeText, type Token } from "../tokens";
@@ -162,6 +163,11 @@ function indent(body: string): string {
   return lines.map((l, i) => (i === 0 || l.length === 0 ? l : `  ${l}`)).join("\n");
 }
 
+const RELATIONS = new Set<string>([CLICKHOUSE_ENTITY_TYPES.table, CLICKHOUSE_ENTITY_TYPES.view, CLICKHOUSE_ENTITY_TYPES.materializedView, CLICKHOUSE_ENTITY_TYPES.dictionary]);
+
+/** A table's, view's or dictionary's qualified name as its tag's type argument (#3751), so its columns are typed once `chant sql types` has run. */
+const typeArgument = (it: Item): string => (RELATIONS.has(it.type) ? `<${JSON.stringify(relationKey(it))}>` : "");
+
 export class ClickHouseGenerator implements TypeScriptGenerator {
   readonly ownsLayout = true;
 
@@ -186,7 +192,7 @@ export class ClickHouseGenerator implements TypeScriptGenerator {
     if (this.header) lines.push(...this.header.split("\n").map((l) => `// ${l}`), "");
     lines.push(`import { ${tags.join(", ")} } from "@intentius/chant-lexicon-sql/clickhouse";`, "");
     for (const it of order) {
-      lines.push(`export const ${it.exportName} = ${CLICKHOUSE_TAG_OF[it.type]}\`\n  ${indent(bodyText(bodies.get(it.exportName)!))}\`;`, "");
+      lines.push(`export const ${it.exportName} = ${CLICKHOUSE_TAG_OF[it.type]}${typeArgument(it)}\`\n  ${indent(bodyText(bodies.get(it.exportName)!))}\`;`, "");
     }
     return [{ path: "schema.ts", content: `${lines.join("\n").trimEnd()}\n` }];
   }

package/src/clickhouse/import/roundtrip.test.ts

@@ -64,7 +64,7 @@ describe("import, build, import again", () => {
       "ClickHouse::View",
       "ClickHouse::Table",
     ]);
-    expect(file!.content).toContain("export const events = table`");
+    expect(file!.content).toContain(`export const events = table<"analytics.events">\``);
   });
 
   test("the declarations build back to one statement per object, dependencies first", async () => {

package/src/clickhouse/plan/commands.ts

@@ -165,5 +165,10 @@ export const sqlCommands: CommandGroup = {
   commands: [
     { name: "diff", description: "Classify the change between two chant build outputs (offline); --statements prints the statements it takes, --topology renders them for single, cluster:<name>, replicated or cloud", handler: runDiff },
     { name: "plan", description: "Classify the change from an environment's server to a chant build output", handler: runPlan },
+    {
+      name: "types",
+      description: "Write sql-types.d.ts: typed columns for each table, view and dictionary the build declares, for tags given their name (table<\"app.users\">) and RowOf; --output <path> writes it elsewhere; --check compares instead of writing and exits 1 when the file differs",
+      handler: async (ctx) => (await import("../../sql-types-command")).runTypes(ctx),
+    },
   ],
 };

package/src/clickhouse/row-types.ts

@@ -0,0 +1,158 @@
+/**
+ * What a ClickHouse column's value is in TypeScript, for `RowOf` (#3751): the
+ * value a row has in ClickHouse's JSON formats (`JSONEachRow`, what the HTTP
+ * clients read) with the server's default settings. 64-bit and wider
+ * integers are quoted (`output_format_json_quote_64bit_integers`), so they
+ * are strings; narrower integers, floats and decimals are numbers; dates,
+ * times, UUIDs and addresses are their text; a named tuple is an object
+ * (`output_format_json_named_tuples_as_objects`) and an unnamed one an array.
+ * `Nullable(T)` adds `| null` and `LowCardinality(T)` is `T`.
+ *
+ * The table names every type family of the pinned server's catalog
+ * (`TYPE_FAMILIES`, aliases resolved), and a test fails on one it does not,
+ * so a family a new release adds is a decision rather than a silent
+ * `unknown`.
+ */
+
+import type { ColumnTypeFamily } from "../generated/clickhouse-types";
+import { familyOf } from "../lint/post-synth/clickhouse-type-check";
+import { readType, typeTokens, type TypeParam } from "./type-syntax";
+import { isTrivia } from "./tokens";
+
+/** How a family's parameters make its row type: `inner` maps a parameter that is itself a type. */
+type Composed = (params: readonly TypeParam[], inner: (type: string) => string) => string;
+
+const NUMBER = "number";
+const STRING = "string";
+const UNKNOWN = "unknown";
+const POINT = "[number, number]";
+
+/** A union needs parentheses before `[]`. */
+const element = (ts: string): string => (/[|&]/.test(ts) && !/^\{.*\}$/s.test(ts) ? `(${ts})` : ts);
+
+/** An enum's labels as a union of string literals; its text when none read. */
+const enumLabels: Composed = (params) => {
+  const labels = params.flatMap((p) => {
+    const first = p.tokens.find((t) => !isTrivia(t));
+    return first?.kind === "string" ? [first.text.slice(1, -1).replace(/\\(.)/g, "$1").replace(/''/g, "'")] : [];
+  });
+  return labels.length > 0 ? labels.map((l) => JSON.stringify(l)).join(" | ") : STRING;
+};
+
+/** The TypeScript type of each type family's value, or how its parameters make it. */
+export const CLICKHOUSE_ROW_TYPES: Readonly<Record<ColumnTypeFamily, string | Composed>> = {
+  UInt8: NUMBER,
+  UInt16: NUMBER,
+  UInt32: NUMBER,
+  Int8: NUMBER,
+  Int16: NUMBER,
+  Int32: NUMBER,
+  Float32: NUMBER,
+  Float64: NUMBER,
+  BFloat16: NUMBER,
+  Decimal: NUMBER,
+  Decimal32: NUMBER,
+  Decimal64: NUMBER,
+  Decimal128: NUMBER,
+  Decimal256: NUMBER,
+  // Quoted in JSON, so text.
+  UInt64: STRING,
+  UInt128: STRING,
+  UInt256: STRING,
+  Int64: STRING,
+  Int128: STRING,
+  Int256: STRING,
+  IntervalNanosecond: STRING,
+  IntervalMicrosecond: STRING,
+  IntervalMillisecond: STRING,
+  IntervalSecond: STRING,
+  IntervalMinute: STRING,
+  IntervalHour: STRING,
+  IntervalDay: STRING,
+  IntervalWeek: STRING,
+  IntervalMonth: STRING,
+  IntervalQuarter: STRING,
+  IntervalYear: STRING,
+  Bool: "boolean",
+  String: STRING,
+  FixedString: STRING,
+  UUID: STRING,
+  IPv4: STRING,
+  IPv6: STRING,
+  Date: STRING,
+  Date32: STRING,
+  DateTime: STRING,
+  DateTime32: STRING,
+  DateTime64: STRING,
+  Time: STRING,
+  Time64: STRING,
+  Enum: enumLabels,
+  Enum8: enumLabels,
+  Enum16: enumLabels,
+  // Wrappers and containers.
+  Nullable: (p, inner) => `${inner(p[0]?.text ?? "")} | null`,
+  LowCardinality: (p, inner) => inner(p[0]?.text ?? ""),
+  Array: (p, inner) => `${element(inner(p[0]?.text ?? ""))}[]`,
+  Map: (p, inner) => `Record<string, ${inner(p[1]?.text ?? "")}>`,
+  Tuple: (p, inner) => {
+    const elements = p.map((x) => named(x));
+    if (elements.length > 0 && elements.every((e) => e.name !== undefined)) {
+      return `{ ${elements.map((e) => `${propertyName(e.name!)}: ${inner(e.type)}`).join("; ")} }`;
+    }
+    return `[${elements.map((e) => inner(e.type)).join(", ")}]`;
+  },
+  SimpleAggregateFunction: (p, inner) => inner(p[1]?.text ?? ""),
+  AggregateFunction: UNKNOWN,
+  Nested: UNKNOWN,
+  // Self-describing: the application's own shape.
+  JSON: UNKNOWN,
+  Dynamic: UNKNOWN,
+  Variant: UNKNOWN,
+  QBit: UNKNOWN,
+  Nothing: "null",
+  // Geometry, as the JSON formats write it: points as pairs, nested in arrays.
+  Point: POINT,
+  Ring: `${POINT}[]`,
+  LineString: `${POINT}[]`,
+  Polygon: `${POINT}[][]`,
+  MultiLineString: `${POINT}[][]`,
+  MultiPoint: `${POINT}[]`,
+  MultiPolygon: `${POINT}[][][]`,
+  Geometry: UNKNOWN,
+};
+
+/** A tuple element: `a String` is named `a`, `String` is not. */
+function named(param: TypeParam): { name?: string; type: string } {
+  const syn = readType(param.tokens);
+  if (!syn || syn.words.length < 2) return { type: param.text };
+  if (familyOf(syn.words.map((w) => w.text).join(" "))) return { type: param.text };
+  const first = syn.words[0]!;
+  const rest = param.text.slice(param.text.indexOf(first.text) + first.text.length).trim();
+  return { name: first.kind === "qident" ? first.text.slice(1, -1) : first.text, type: rest };
+}
+
+const propertyName = (name: string): string => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+
+/** A type's row type, wrappers and all; `unknown` for a type this cannot read. */
+export function clickhouseTsType(type: string): string {
+  const tokens = typeTokens(type);
+  const syn = tokens && readType(tokens);
+  if (!syn) return UNKNOWN;
+  const spec = familyOf(syn.words.map((w) => w.text).join(" "));
+  const entry = spec ? (CLICKHOUSE_ROW_TYPES as Readonly<Record<string, string | Composed | undefined>>)[spec.canonical] : undefined;
+  if (entry === undefined) return UNKNOWN;
+  return typeof entry === "string" ? entry : entry(syn.params ?? [], clickhouseTsType);
+}
+
+/** A column's row type and whether it can be NULL: `Nullable(...)` at the top, under any `LowCardinality(...)`. */
+export function clickhouseRowType(type: string): { ts: string; nullable: boolean } {
+  let t = type.trim();
+  let nullable = false;
+  for (;;) {
+    const m = /^(Nullable|LowCardinality)\s*\(([\s\S]*)\)$/i.exec(t);
+    if (!m) break;
+    if (m[1]!.toLowerCase() === "nullable") nullable = true;
+    t = m[2]!.trim();
+  }
+  return { ts: clickhouseTsType(t), nullable };
+}

package/src/clickhouse.ts

@@ -50,6 +50,16 @@ export {
   type LineageEdge,
   type TableProps,
   type ViewProps,
+  type SqlSchema,
+  type RowOf,
+  type Column,
+  type ColumnTraits,
+  type AnyColumn,
+  type UncheckedColumn,
+  type KeyColumn,
+  type NotNullColumn,
+  type Named,
+  type Unnamed,
 } from "./clickhouse/entities";
 export * from "./generated/clickhouse";
 export * from "./composites/clickhouse";

package/src/core/index.ts

@@ -25,6 +25,9 @@
  *   (`classifier.ts`);
  * - normalization helpers that are not a database's grammar, such as the
  *   `-- previously:` hint (`normalize.ts`);
+ * - typed columns: the brands, `ColumnsIn`, `SlotsIn` and `RowIn` each
+ *   dialect's `SqlSchema` is read through, and the slot record a tag leaves
+ *   for `chant sql types` (`typed.ts`);
  * - the ownership trailer on an object's comment (`ownership.ts`);
  * - receipts kept on the server (`receipts.ts`);
  * - the applier's tri-state outcome, its envelope projection and the build
@@ -54,6 +57,7 @@ export * from "./references";
 export * from "./diff";
 export * from "./classifier";
 export * from "./normalize";
+export * from "./typed";
 export * from "./ownership";
 export * from "./receipts";
 export * from "./apply";