@tinybirdco/sdk 0.0.4 → 0.0.7

package/src/codegen/type-mapper.ts

@@ -0,0 +1,265 @@
+/**
+ * Type mapping from ClickHouse types to TypeScript SDK validators
+ */
+
+/**
+ * Parse enum values from an enum type string
+ * e.g., "'a' = 1, 'b' = 2" -> ["a", "b"]
+ */
+function parseEnumValues(enumContent: string): string[] {
+  const values: string[] = [];
+  const regex = /'([^']+)'\s*=\s*\d+/g;
+  let match;
+  while ((match = regex.exec(enumContent)) !== null) {
+    values.push(match[1]);
+  }
+  return values;
+}
+
+/**
+ * Map a ClickHouse type to a t.* validator call
+ *
+ * Handles:
+ * - Basic types: String, Int32, Float64, DateTime, etc.
+ * - Nullable wrapper: Nullable(String) -> t.string().nullable()
+ * - LowCardinality wrapper: LowCardinality(String) -> t.string().lowCardinality()
+ * - Parameterized types: DateTime('UTC'), FixedString(10), Decimal(10, 2)
+ * - Complex types: Array(String), Map(String, Int32)
+ * - Aggregate functions: SimpleAggregateFunction(sum, UInt64)
+ */
+export function clickhouseTypeToValidator(chType: string): string {
+  // Trim whitespace
+  chType = chType.trim();
+
+  // Handle Nullable wrapper
+  const nullableMatch = chType.match(/^Nullable\((.+)\)$/);
+  if (nullableMatch) {
+    const innerType = clickhouseTypeToValidator(nullableMatch[1]);
+    return `${innerType}.nullable()`;
+  }
+
+  // Handle LowCardinality wrapper
+  const lowCardMatch = chType.match(/^LowCardinality\((.+)\)$/);
+  if (lowCardMatch) {
+    const innerType = clickhouseTypeToValidator(lowCardMatch[1]);
+    // If inner type already has .nullable(), we need to handle this specially
+    // LowCardinality(Nullable(X)) should become t.X().nullable().lowCardinality()
+    // But the recursive call already returns t.X().nullable()
+    return `${innerType}.lowCardinality()`;
+  }
+
+  // Simple type mappings
+  const simpleTypeMap: Record<string, string> = {
+    String: "t.string()",
+    UUID: "t.uuid()",
+    Int8: "t.int8()",
+    Int16: "t.int16()",
+    Int32: "t.int32()",
+    Int64: "t.int64()",
+    Int128: "t.int128()",
+    Int256: "t.int256()",
+    UInt8: "t.uint8()",
+    UInt16: "t.uint16()",
+    UInt32: "t.uint32()",
+    UInt64: "t.uint64()",
+    UInt128: "t.uint128()",
+    UInt256: "t.uint256()",
+    Float32: "t.float32()",
+    Float64: "t.float64()",
+    Bool: "t.bool()",
+    Boolean: "t.bool()",
+    Date: "t.date()",
+    Date32: "t.date32()",
+    DateTime: "t.dateTime()",
+    JSON: "t.json()",
+    Object: "t.json()",
+    IPv4: "t.ipv4()",
+    IPv6: "t.ipv6()",
+  };
+
+  if (simpleTypeMap[chType]) {
+    return simpleTypeMap[chType];
+  }
+
+  // DateTime with timezone: DateTime('UTC')
+  const dtTzMatch = chType.match(/^DateTime\('([^']+)'\)$/);
+  if (dtTzMatch) {
+    return `t.dateTime("${dtTzMatch[1]}")`;
+  }
+
+  // DateTime64 with precision and optional timezone
+  const dt64Match = chType.match(/^DateTime64\((\d+)(?:,\s*'([^']+)')?\)$/);
+  if (dt64Match) {
+    const precision = dt64Match[1];
+    const tz = dt64Match[2];
+    if (tz) {
+      return `t.dateTime64(${precision}, "${tz}")`;
+    }
+    return `t.dateTime64(${precision})`;
+  }
+
+  // DateTime64 without precision (defaults to 3)
+  if (chType === "DateTime64") {
+    return "t.dateTime64(3)";
+  }
+
+  // FixedString(N)
+  const fixedMatch = chType.match(/^FixedString\((\d+)\)$/);
+  if (fixedMatch) {
+    return `t.fixedString(${fixedMatch[1]})`;
+  }
+
+  // Decimal(P, S) or Decimal(P)
+  const decMatch = chType.match(/^Decimal\((\d+)(?:,\s*(\d+))?\)$/);
+  if (decMatch) {
+    const precision = decMatch[1];
+    const scale = decMatch[2] ?? "0";
+    return `t.decimal(${precision}, ${scale})`;
+  }
+
+  // Decimal32, Decimal64, Decimal128, Decimal256 with scale
+  const decNMatch = chType.match(/^Decimal(32|64|128|256)\((\d+)\)$/);
+  if (decNMatch) {
+    const bits = decNMatch[1];
+    const scale = decNMatch[2];
+    const precisionMap: Record<string, number> = {
+      "32": 9,
+      "64": 18,
+      "128": 38,
+      "256": 76,
+    };
+    return `t.decimal(${precisionMap[bits]}, ${scale})`;
+  }
+
+  // Array(T)
+  const arrMatch = chType.match(/^Array\((.+)\)$/);
+  if (arrMatch) {
+    const innerType = clickhouseTypeToValidator(arrMatch[1]);
+    return `t.array(${innerType})`;
+  }
+
+  // Tuple(T1, T2, ...) - simplified handling
+  const tupleMatch = chType.match(/^Tuple\((.+)\)$/);
+  if (tupleMatch) {
+    // For complex tuples, we just use a JSON type
+    // TODO: Could parse and generate t.tuple() for simple cases
+    return `t.json() /* Tuple: ${chType} */`;
+  }
+
+  // Map(K, V)
+  const mapMatch = chType.match(/^Map\(([^,]+),\s*(.+)\)$/);
+  if (mapMatch) {
+    const keyType = clickhouseTypeToValidator(mapMatch[1]);
+    const valueType = clickhouseTypeToValidator(mapMatch[2]);
+    return `t.map(${keyType}, ${valueType})`;
+  }
+
+  // Enum8('a' = 1, 'b' = 2)
+  const enum8Match = chType.match(/^Enum8\((.+)\)$/);
+  if (enum8Match) {
+    const values = parseEnumValues(enum8Match[1]);
+    if (values.length > 0) {
+      return `t.enum8(${values.map((v) => `"${v}"`).join(", ")})`;
+    }
+    return `t.string() /* Enum8 */`;
+  }
+
+  // Enum16('a' = 1, 'b' = 2)
+  const enum16Match = chType.match(/^Enum16\((.+)\)$/);
+  if (enum16Match) {
+    const values = parseEnumValues(enum16Match[1]);
+    if (values.length > 0) {
+      return `t.enum16(${values.map((v) => `"${v}"`).join(", ")})`;
+    }
+    return `t.string() /* Enum16 */`;
+  }
+
+  // SimpleAggregateFunction(func, T)
+  const simpleAggMatch = chType.match(/^SimpleAggregateFunction\((\w+),\s*(.+)\)$/);
+  if (simpleAggMatch) {
+    const func = simpleAggMatch[1];
+    const innerType = clickhouseTypeToValidator(simpleAggMatch[2]);
+    return `t.simpleAggregateFunction("${func}", ${innerType})`;
+  }
+
+  // AggregateFunction(func, T)
+  const aggMatch = chType.match(/^AggregateFunction\((\w+),\s*(.+)\)$/);
+  if (aggMatch) {
+    const func = aggMatch[1];
+    const innerType = clickhouseTypeToValidator(aggMatch[2]);
+    return `t.aggregateFunction("${func}", ${innerType})`;
+  }
+
+  // Nested - treat as JSON
+  if (chType.startsWith("Nested(")) {
+    return `t.json() /* ${chType} */`;
+  }
+
+  // Fallback for unknown types
+  return `t.string() /* TODO: Unknown type: ${chType} */`;
+}
+
+/**
+ * Map a pipe parameter type to a p.* validator call
+ */
+export function paramTypeToValidator(
+  paramType: string,
+  defaultValue?: string | number,
+  required: boolean = true
+): string {
+  // Normalize type
+  paramType = paramType.trim();
+
+  // Simple type mappings
+  const typeMap: Record<string, string> = {
+    String: "p.string()",
+    UUID: "p.uuid()",
+    Int8: "p.int8()",
+    Int16: "p.int16()",
+    Int32: "p.int32()",
+    Int64: "p.int64()",
+    UInt8: "p.uint8()",
+    UInt16: "p.uint16()",
+    UInt32: "p.uint32()",
+    UInt64: "p.uint64()",
+    Float32: "p.float32()",
+    Float64: "p.float64()",
+    Boolean: "p.boolean()",
+    Bool: "p.boolean()",
+    Date: "p.date()",
+    DateTime: "p.dateTime()",
+    DateTime64: "p.dateTime64()",
+  };
+
+  let validator = typeMap[paramType];
+
+  // Handle parameterized DateTime types
+  if (!validator) {
+    if (paramType.startsWith("DateTime64")) {
+      validator = "p.dateTime64()";
+    } else if (paramType.startsWith("DateTime")) {
+      validator = "p.dateTime()";
+    } else if (paramType.startsWith("Array")) {
+      // Array parameters - default to string array
+      validator = "p.array(p.string())";
+    } else {
+      // Default to string for unknown types
+      validator = "p.string()";
+    }
+  }
+
+  // Add optional with default if not required or has a default value
+  if (!required || defaultValue !== undefined) {
+    if (defaultValue !== undefined) {
+      const formattedDefault =
+        typeof defaultValue === "string" ? `"${defaultValue}"` : defaultValue;
+      // Replace () with .optional(value)
+      validator = validator.replace(/\(\)$/, `().optional(${formattedDefault})`);
+    } else {
+      // Just make it optional without a default
+      validator = validator.replace(/\(\)$/, "().optional()");
+    }
+  }
+
+  return validator;
+}

package/src/codegen/utils.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect } from "vitest";
+import {
+  toCamelCase,
+  toPascalCase,
+  escapeString,
+  parseSortingKey,
+  generateEngineCode,
+  formatSqlForTemplate,
+} from "./utils.js";
+
+describe("toCamelCase", () => {
+  it("converts snake_case to camelCase", () => {
+    expect(toCamelCase("page_views")).toBe("pageViews");
+    expect(toCamelCase("user_session_data")).toBe("userSessionData");
+  });
+
+  it("converts kebab-case to camelCase", () => {
+    expect(toCamelCase("page-views")).toBe("pageViews");
+    expect(toCamelCase("user-session-data")).toBe("userSessionData");
+  });
+
+  it("lowercases first character of PascalCase", () => {
+    expect(toCamelCase("PageViews")).toBe("pageViews");
+  });
+
+  it("handles single word", () => {
+    expect(toCamelCase("events")).toBe("events");
+  });
+
+  it("prefixes reserved keywords with underscore", () => {
+    expect(toCamelCase("class")).toBe("_class");
+    expect(toCamelCase("function")).toBe("_function");
+    expect(toCamelCase("return")).toBe("_return");
+    expect(toCamelCase("import")).toBe("_import");
+    expect(toCamelCase("export")).toBe("_export");
+  });
+
+  it("prefixes names starting with numbers", () => {
+    expect(toCamelCase("123_test")).toBe("_123Test");
+    expect(toCamelCase("1events")).toBe("_1events");
+  });
+});
+
+describe("toPascalCase", () => {
+  it("converts snake_case to PascalCase", () => {
+    expect(toPascalCase("page_views")).toBe("PageViews");
+    expect(toPascalCase("user_session_data")).toBe("UserSessionData");
+  });
+
+  it("converts kebab-case to PascalCase", () => {
+    expect(toPascalCase("page-views")).toBe("PageViews");
+  });
+
+  it("uppercases first character", () => {
+    expect(toPascalCase("events")).toBe("Events");
+  });
+});
+
+describe("escapeString", () => {
+  it("escapes double quotes", () => {
+    expect(escapeString('hello "world"')).toBe('hello \\"world\\"');
+  });
+
+  it("escapes backslashes", () => {
+    expect(escapeString("path\\to\\file")).toBe("path\\\\to\\\\file");
+  });
+
+  it("escapes newlines", () => {
+    expect(escapeString("line1\nline2")).toBe("line1\\nline2");
+  });
+
+  it("escapes tabs", () => {
+    expect(escapeString("col1\tcol2")).toBe("col1\\tcol2");
+  });
+
+  it("handles combined escapes", () => {
+    expect(escapeString('say "hello\\world"\n')).toBe('say \\"hello\\\\world\\"\\n');
+  });
+});
+
+describe("parseSortingKey", () => {
+  it("parses single column", () => {
+    expect(parseSortingKey("timestamp")).toEqual(["timestamp"]);
+  });
+
+  it("parses multiple columns", () => {
+    expect(parseSortingKey("user_id, timestamp")).toEqual(["user_id", "timestamp"]);
+  });
+
+  it("trims whitespace", () => {
+    expect(parseSortingKey("  user_id  ,  timestamp  ")).toEqual(["user_id", "timestamp"]);
+  });
+
+  it("returns empty array for undefined", () => {
+    expect(parseSortingKey(undefined)).toEqual([]);
+  });
+
+  it("returns empty array for empty string", () => {
+    expect(parseSortingKey("")).toEqual([]);
+  });
+});
+
+describe("generateEngineCode", () => {
+  it("generates MergeTree engine code", () => {
+    const code = generateEngineCode({
+      type: "MergeTree",
+      sorting_key: "timestamp",
+    });
+    expect(code).toContain("engine.mergeTree");
+    expect(code).toContain('sortingKey: "timestamp"');
+  });
+
+  it("generates MergeTree with multiple sorting keys", () => {
+    const code = generateEngineCode({
+      type: "MergeTree",
+      sorting_key: "user_id, timestamp",
+    });
+    expect(code).toContain("engine.mergeTree");
+    expect(code).toContain('sortingKey: ["user_id", "timestamp"]');
+  });
+
+  it("includes partition key", () => {
+    const code = generateEngineCode({
+      type: "MergeTree",
+      sorting_key: "timestamp",
+      partition_key: "toYYYYMM(timestamp)",
+    });
+    expect(code).toContain('partitionKey: "toYYYYMM(timestamp)"');
+  });
+
+  it("includes TTL", () => {
+    const code = generateEngineCode({
+      type: "MergeTree",
+      sorting_key: "timestamp",
+      ttl: "timestamp + INTERVAL 90 DAY",
+    });
+    expect(code).toContain('ttl: "timestamp + INTERVAL 90 DAY"');
+  });
+
+  it("generates ReplacingMergeTree with ver column", () => {
+    const code = generateEngineCode({
+      type: "ReplacingMergeTree",
+      sorting_key: "id",
+      ver: "updated_at",
+    });
+    expect(code).toContain("engine.replacingMergeTree");
+    expect(code).toContain('ver: "updated_at"');
+  });
+
+  it("generates SummingMergeTree with columns", () => {
+    const code = generateEngineCode({
+      type: "SummingMergeTree",
+      sorting_key: "date, category",
+      summing_columns: "count, total",
+    });
+    expect(code).toContain("engine.summingMergeTree");
+    expect(code).toContain('columns: ["count", "total"]');
+  });
+
+  it("generates AggregatingMergeTree", () => {
+    const code = generateEngineCode({
+      type: "AggregatingMergeTree",
+      sorting_key: "date",
+    });
+    expect(code).toContain("engine.aggregatingMergeTree");
+  });
+
+  it("generates CollapsingMergeTree with sign column", () => {
+    const code = generateEngineCode({
+      type: "CollapsingMergeTree",
+      sorting_key: "id, timestamp",
+      sign: "sign",
+    });
+    expect(code).toContain("engine.collapsingMergeTree");
+    expect(code).toContain('sign: "sign"');
+  });
+
+  it("generates VersionedCollapsingMergeTree", () => {
+    const code = generateEngineCode({
+      type: "VersionedCollapsingMergeTree",
+      sorting_key: "id",
+      sign: "sign",
+      version: "version",
+    });
+    expect(code).toContain("engine.versionedCollapsingMergeTree");
+    expect(code).toContain('sign: "sign"');
+    expect(code).toContain('version: "version"');
+  });
+
+  it("defaults to mergeTree for unknown engine types", () => {
+    const code = generateEngineCode({
+      type: "UnknownEngine",
+      sorting_key: "id",
+    });
+    expect(code).toContain("engine.mergeTree");
+  });
+});
+
+describe("formatSqlForTemplate", () => {
+  it("escapes backticks", () => {
+    expect(formatSqlForTemplate("SELECT `column` FROM table")).toBe(
+      "SELECT \\`column\\` FROM table"
+    );
+  });
+
+  it("escapes template literal interpolations", () => {
+    expect(formatSqlForTemplate("SELECT ${column} FROM table")).toBe(
+      "SELECT \\${column} FROM table"
+    );
+  });
+
+  it("preserves newlines", () => {
+    const sql = "SELECT *\nFROM table\nWHERE id = 1";
+    expect(formatSqlForTemplate(sql)).toBe(sql);
+  });
+
+  it("preserves Tinybird template syntax", () => {
+    const sql = "SELECT * FROM table WHERE id = {{Int32(id)}}";
+    expect(formatSqlForTemplate(sql)).toBe(sql);
+  });
+});

package/src/codegen/utils.ts

@@ -0,0 +1,174 @@
+/**
+ * Utility functions for code generation
+ */
+
+/**
+ * Convert a string to camelCase
+ * Handles snake_case and kebab-case
+ */
+export function toCamelCase(str: string): string {
+  // Handle reserved keywords
+  const reserved = new Set([
+    "break", "case", "catch", "class", "const", "continue", "debugger",
+    "default", "delete", "do", "else", "enum", "export", "extends",
+    "false", "finally", "for", "function", "if", "import", "in",
+    "instanceof", "new", "null", "return", "super", "switch", "this",
+    "throw", "true", "try", "typeof", "undefined", "var", "void",
+    "while", "with", "yield", "let", "static", "implements", "interface",
+    "package", "private", "protected", "public", "await", "async",
+  ]);
+
+  const result = str
+    .replace(/[-_](.)/g, (_, char) => char.toUpperCase())
+    .replace(/^[A-Z]/, (char) => char.toLowerCase());
+
+  // If the result is a reserved keyword or starts with a number, prefix with underscore
+  if (reserved.has(result) || /^\d/.test(result)) {
+    return `_${result}`;
+  }
+
+  return result;
+}
+
+/**
+ * Convert a string to PascalCase
+ * Handles snake_case and kebab-case
+ */
+export function toPascalCase(str: string): string {
+  const camel = toCamelCase(str);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+
+/**
+ * Escape a string for use in JavaScript/TypeScript code
+ */
+export function escapeString(str: string): string {
+  return str
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t");
+}
+
+/**
+ * Parse a sorting key string into an array
+ * Handles comma-separated values and quoted identifiers
+ */
+export function parseSortingKey(sortingKey?: string): string[] {
+  if (!sortingKey) {
+    return [];
+  }
+
+  // Split by comma, trim whitespace
+  return sortingKey
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Generate engine code from engine info
+ */
+export function generateEngineCode(engine: {
+  type: string;
+  sorting_key?: string;
+  partition_key?: string;
+  primary_key?: string;
+  ttl?: string;
+  ver?: string;
+  sign?: string;
+  version?: string;
+  summing_columns?: string;
+}): string {
+  const sortingKey = parseSortingKey(engine.sorting_key);
+
+  // Build options object
+  const options: string[] = [];
+
+  // Sorting key is required for all MergeTree engines
+  if (sortingKey.length === 1) {
+    options.push(`sortingKey: "${sortingKey[0]}"`);
+  } else if (sortingKey.length > 1) {
+    options.push(`sortingKey: [${sortingKey.map((k) => `"${k}"`).join(", ")}]`);
+  }
+
+  // Optional fields
+  if (engine.partition_key) {
+    options.push(`partitionKey: "${escapeString(engine.partition_key)}"`);
+  }
+
+  if (engine.primary_key && engine.primary_key !== engine.sorting_key) {
+    const primaryKey = parseSortingKey(engine.primary_key);
+    if (primaryKey.length === 1) {
+      options.push(`primaryKey: "${primaryKey[0]}"`);
+    } else if (primaryKey.length > 1) {
+      options.push(`primaryKey: [${primaryKey.map((k) => `"${k}"`).join(", ")}]`);
+    }
+  }
+
+  if (engine.ttl) {
+    options.push(`ttl: "${escapeString(engine.ttl)}"`);
+  }
+
+  // Engine-specific options
+  if (engine.type === "ReplacingMergeTree" && engine.ver) {
+    options.push(`ver: "${engine.ver}"`);
+  }
+
+  if (
+    (engine.type === "CollapsingMergeTree" ||
+      engine.type === "VersionedCollapsingMergeTree") &&
+    engine.sign
+  ) {
+    options.push(`sign: "${engine.sign}"`);
+  }
+
+  if (engine.type === "VersionedCollapsingMergeTree" && engine.version) {
+    options.push(`version: "${engine.version}"`);
+  }
+
+  if (engine.type === "SummingMergeTree" && engine.summing_columns) {
+    const columns = parseSortingKey(engine.summing_columns);
+    if (columns.length > 0) {
+      options.push(`columns: [${columns.map((c) => `"${c}"`).join(", ")}]`);
+    }
+  }
+
+  // Map engine type to function name
+  const engineFunctionMap: Record<string, string> = {
+    MergeTree: "engine.mergeTree",
+    ReplacingMergeTree: "engine.replacingMergeTree",
+    SummingMergeTree: "engine.summingMergeTree",
+    AggregatingMergeTree: "engine.aggregatingMergeTree",
+    CollapsingMergeTree: "engine.collapsingMergeTree",
+    VersionedCollapsingMergeTree: "engine.versionedCollapsingMergeTree",
+  };
+
+  const engineFunc = engineFunctionMap[engine.type] ?? "engine.mergeTree";
+
+  if (options.length === 0) {
+    return `${engineFunc}({ sortingKey: [] })`;
+  }
+
+  return `${engineFunc}({\n    ${options.join(",\n    ")},\n  })`;
+}
+
+/**
+ * Indent a multi-line string
+ */
+export function indent(str: string, spaces: number): string {
+  const prefix = " ".repeat(spaces);
+  return str
+    .split("\n")
+    .map((line) => (line.trim() ? prefix + line : line))
+    .join("\n");
+}
+
+/**
+ * Format SQL for inclusion in template literal
+ * Preserves newlines and indentation but escapes backticks
+ */
+export function formatSqlForTemplate(sql: string): string {
+  return sql.replace(/`/g, "\\`").replace(/\${/g, "\\${");
+}