feat: add type-safe sql queries with query registry

[ditadi]

Type-Safe SQL Queries with QueryRegistry

Summary

This PR introduces a compile-time type system for SQL queries, providing full type safety from query definition to result consumption. The system generates TypeScript types by analyzing SQL files and using DESCRIBE QUERY against Databricks to infer result schemas without executing the actual queries.

Features

QueryRegistry Type Generation

Automatically generates TypeScript interfaces for all SQL queries in your project:

interface QueryRegistry {
  spend_data: {
    name: "spend_data";
    parameters: {
      /** DATE - use sql.date() */
      startDate: SQLDateMarker;
      /** STRING - use sql.string() */
      groupBy: SQLStringMarker;
    };
    result: Array<{
      /** @sqlType STRING */
      group_key: string;
      /** @sqlType DECIMAL */
      cost_usd: number;
    }>;
  };
}

SQL Parameter Type Safety

• Marker Types: Specific interfaces for each SQL type (SQLDateMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLTimestampMarker, SQLBinaryMarker)
• Numeric Type Support: All numeric types (INT, BIGINT, DECIMAL, FLOAT, DOUBLE, etc.) map to SQLNumberMarker with sql.number() helper
• @param Annotations: Declare parameter types in SQL files:

  -- @param startDate DATE
  -- @param endDate DATE
  -- @param groupBy STRING
  SELECT * FROM spend WHERE date BETWEEN :startDate AND :endDate

• JSDoc Hints: Generated types include inline documentation showing which sql.*() helper to use
• Graceful Fallback: Unannotated parameters use SQLTypeMarker union, still enforcing helper usage

Type-Safe Query Hook

useAnalyticsQuery now provides full IntelliSense:

// ✅ Type-safe: IDE shows required parameters and their types
const { data, loading, error } = useAnalyticsQuery("spend_data", {
  startDate: sql.date("2024-01-01"),
  endDate: sql.date("2024-12-31"),
  groupBy: sql.string("app_name"),
});

// data is typed as Array<{ group_key: string; cost_usd: number }>

Result Schema Inference

• Uses DESCRIBE QUERY to extract column metadata without executing queries
• Normalizes parameterized types (DECIMAL(38,6) → DECIMAL, ARRAY<STRING> → ARRAY)
• Maps all Databricks types to TypeScript (STRING, DECIMAL, INT, BIGINT, ARRAY, MAP, STRUCT, etc.)
• Adds @sqlType JSDoc comments with full type info (e.g., @sqlType DECIMAL(38,6))
• Intelligent caching to avoid redundant queries (invalidates when SQL changes)

Developer Experience

Before	After
Parameters typed as any	Specific marker types with hints
Runtime errors for wrong types	Compile-time validation
No autocomplete for results	Full IntelliSense on data
Manual type assertions	Automatic type inference

Architecture

SQL Files (with @param annotations)
        ↓
Type Generator (npx appkit-generate-types)
    ├─ Parse @param comments → Parameter types
    └─ DESCRIBE QUERY → Result schema (no execution)
        ↓
Generated appKitTypes.d.ts
        ↓
Module Augmentation (QueryRegistry)
        ↓
Type-safe useAnalyticsQuery<K>
    ├─ InferParams<K> → Required parameters
    └─ InferResult<K> → Typed results

Test Plan

• Run npx appkit-generate-types and verify appKitTypes.d.ts is generated correctly
• Confirm IDE autocomplete works for query names in useAnalyticsQuery
• Verify parameter types match @param annotations
• Test compile error when using wrong sql.*() helper
• Validate result types match actual query output
• Ensure cache invalidation works when SQL files change

[fjakobs]

not blocking: we should map BigInt to JS BigInt numbers