@databricks/appkit 0.0.2 → 0.1.2

package/NOTICE.md

@@ -49,11 +49,13 @@ This Software contains code from the following open source projects:
 | [@radix-ui/react-tooltip](https://www.npmjs.com/package/@radix-ui/react-tooltip) | 1.2.8 | MIT | https://radix-ui.com/primitives |
 | [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table) | 8.21.3 | MIT | https://tanstack.com/table |
 | [@tanstack/react-virtual](https://www.npmjs.com/package/@tanstack/react-virtual) | 3.13.12 | MIT | https://tanstack.com/virtual |
+| [apache-arrow](https://www.npmjs.com/package/apache-arrow) | 21.1.0 | Apache-2.0 | https://arrow.apache.org/js/ |
 | [class-variance-authority](https://www.npmjs.com/package/class-variance-authority) | 0.7.1 | Apache-2.0 | https://github.com/joe-bell/cva#readme |
 | [clsx](https://www.npmjs.com/package/clsx) | 2.1.1 | MIT | https://github.com/lukeed/clsx#readme |
 | [cmdk](https://www.npmjs.com/package/cmdk) | 1.1.1 | MIT | https://github.com/pacocoursey/cmdk#readme |
 | [date-fns](https://www.npmjs.com/package/date-fns) | 4.1.0 | MIT | https://github.com/date-fns/date-fns#readme |
 | [dotenv](https://www.npmjs.com/package/dotenv) | 16.6.1 | BSD-2-Clause | https://github.com/motdotla/dotenv#readme |
+| [echarts-for-react](https://www.npmjs.com/package/echarts-for-react) | 3.0.5 | MIT | https://github.com/hustcc/echarts-for-react |
 | [embla-carousel-react](https://www.npmjs.com/package/embla-carousel-react) | 8.6.0 | MIT | https://www.embla-carousel.com |
 | [express](https://www.npmjs.com/package/express) | 4.22.0 | MIT | http://expressjs.com/ |
 | [fast-glob](https://www.npmjs.com/package/fast-glob) | 3.3.3 | MIT | https://github.com/mrmlnc/fast-glob#readme |
@@ -67,7 +69,7 @@ This Software contains code from the following open source projects:
 | [sonner](https://www.npmjs.com/package/sonner) | 2.0.7 | MIT | https://sonner.emilkowal.ski/ |
 | [tailwind-merge](https://www.npmjs.com/package/tailwind-merge) | 3.4.0 | MIT | https://github.com/dcastil/tailwind-merge |
 | [vaul](https://www.npmjs.com/package/vaul) | 1.1.2 | MIT | https://vaul.emilkowal.ski/ |
-| [ws](https://www.npmjs.com/package/ws) | 8.18.3 | MIT | https://github.com/websockets/ws |
+| [ws](https://www.npmjs.com/package/ws) | 7.5.10, 8.18.3 | MIT | https://github.com/websockets/ws |
 | [zod](https://www.npmjs.com/package/zod) | 4.1.13 | MIT | https://zod.dev |
 | [zod-to-ts](https://www.npmjs.com/package/zod-to-ts) | 2.0.0 | MIT | https://github.com/sachinraja/zod-to-ts#readme |
 

package/bin/generate-types.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import path from "node:path";
+
+import { generateFromEntryPoint } from "../dist/type-generator/index.js";
+
+// Parse arguments
+const args = process.argv.slice(2);
+const noCache = args.includes("--no-cache");
+const positionalArgs = args.filter((arg) => !arg.startsWith("--"));
+
+const rootDir = positionalArgs[0] || process.cwd();
+const outFile =
+  positionalArgs[1] || path.join(process.cwd(), "client/src/appKitTypes.d.ts");
+
+const queryFolder = path.join(rootDir, "config/queries");
+
+const warehouseId = positionalArgs[2] || process.env.DATABRICKS_WAREHOUSE_ID;
+if (!warehouseId) {
+  throw new Error("DATABRICKS_WAREHOUSE_ID is not set");
+}
+
+await generateFromEntryPoint({
+  queryFolder,
+  outFile,
+  warehouseId,
+  noCache,
+});

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.0.2";
+var version = "0.1.2";
 
 //#endregion
 export { name, version };

package/dist/cache/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/cache/index.ts"],"sourcesContent":[],"mappings":";;;;;;AAuBA;;;;;;;;;;;AAwQqC,cAxQxB,YAAA,CAwQwB;0BAAR,uBAAA;mBAkDlB,IAAA;iBAEN,QAAA;iBAawB,WAAA;UAMZ,OAAA;UAUS,MAAA;UA0BT,gBAAA;UAQW,iBAAA;EAAO,QAAA,kBAAA;;;;;;;;;;4BA3UP;;;;;;;;kCAkBX,QAAQ,eACpB,QAAQ;;;;;;;;;;;;;;;;;;;;;;+DAuGC,QAAQ;;MAGjB,QAAQ;;;;;;uBA2FgB,QAAQ;;;;;;;;;;6BAkD1B;;MAEN;;;;;;uBAawB;;WAMZ;;;;;;oBAUS;;;;;;;;;WA0BT;;;;;sBAQW"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/cache/index.ts"],"sourcesContent":[],"mappings":";;;;;;AAuBA;;;;;;;;;;;AAwPqC,cAxPxB,YAAA,CAwPwB;0BAAR,uBAAA;mBAkDlB,IAAA;iBAEN,QAAA;iBAawB,WAAA;UAMZ,OAAA;UAUS,MAAA;UA0BT,gBAAA;UAQW,iBAAA;EAAO,QAAA,kBAAA;;;;;;;;;;4BA3TP;;;;;;;;kCAkBX,QAAQ,eACpB,QAAQ;;;;;;;;;;;;;;;;;;;;;;+DAuFC,QAAQ;;MAGjB,QAAQ;;;;;;uBA2FgB,QAAQ;;;;;;;;;;6BAkD1B;;MAEN;;;;;;uBAawB;;WAMZ;;;;;;oBAUS;;;;;;;;;WA0BT;;;;;sBAQW"}

package/dist/cache/index.js

@@ -96,16 +96,13 @@ var CacheManager = class CacheManager {
 		const config = deepMerge(cacheDefaults, userConfig);
 		if (config.storage) {
 			if (await config.storage.healthCheck()) return new CacheManager(config.storage, config);
-			console.warn("[Cache] Provided storage health check failed");
 			if (config.strictPersistence) {
-				console.warn("[Cache] strictPersistence enabled but provided storage unhealthy. Cache disabled.");
 				const disabledConfig = {
 					...config,
 					enabled: false
 				};
 				return new CacheManager(new InMemoryStorage(disabledConfig), disabledConfig);
 			}
-			console.warn("[Cache] Falling back to in-memory cache.");
 			return new CacheManager(new InMemoryStorage(config), config);
 		}
 		try {
@@ -115,20 +112,14 @@ var CacheManager = class CacheManager {
 				await persistentStorage.initialize();
 				return new CacheManager(persistentStorage, config);
 			}
-			console.warn("[Cache] Lakebase health check failed, default storage unhealthy");
-		} catch (error) {
-			const errorMessage = error instanceof Error ? error.message : String(error);
-			console.warn(`[Cache] Lakebase unavailable: ${errorMessage}`);
-		}
+		} catch {}
 		if (config.strictPersistence) {
-			console.warn("[Cache] strictPersistence enabled but lakebase unavailable. Cache disabled.");
 			const disabledConfig = {
 				...config,
 				enabled: false
 			};
 			return new CacheManager(new InMemoryStorage(disabledConfig), disabledConfig);
 		}
-		console.warn("[Cache] Falling back to in-memory cache.");
 		return new CacheManager(new InMemoryStorage(config), config);
 	}
 	/**

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["result"],"sources":["../../src/cache/index.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { CacheConfig, CacheStorage } from \"shared\";\nimport { LakebaseConnector } from \"@/connectors\";\nimport type { Counter, TelemetryProvider } from \"../telemetry\";\nimport { SpanStatusCode, TelemetryManager } from \"../telemetry\";\nimport { deepMerge } from \"../utils\";\nimport { cacheDefaults } from \"./defaults\";\nimport { InMemoryStorage, PersistentStorage } from \"./storage\";\n\n/**\n * Cache manager class to handle cache operations.\n * Can be used with in-memory storage or persistent storage (Lakebase).\n *\n * The cache is automatically initialized by AppKit. Use `getInstanceSync()` to access\n * the singleton instance after initialization.\n *\n * @example\n * ```typescript\n * const cache = CacheManager.getInstanceSync();\n * const result = await cache.getOrExecute([\"users\", userId], () => fetchUser(userId), userKey);\n * ```\n */\nexport class CacheManager {\n  private static readonly MIN_CLEANUP_INTERVAL_MS = 60_000;\n  private readonly name: string = \"cache-manager\";\n  private static instance: CacheManager | null = null;\n  private static initPromise: Promise<CacheManager> | null = null;\n\n  private storage: CacheStorage;\n  private config: CacheConfig;\n  private inFlightRequests: Map<string, Promise<unknown>>;\n  private cleanupInProgress: boolean;\n  private lastCleanupAttempt: number;\n\n  // Telemetry\n  private telemetry: TelemetryProvider;\n  private telemetryMetrics: {\n    cacheHitCount: Counter;\n    cacheMissCount: Counter;\n  };\n\n  private constructor(storage: CacheStorage, config: CacheConfig) {\n    this.storage = storage;\n    this.config = config;\n    this.inFlightRequests = new Map();\n    this.cleanupInProgress = false;\n    this.lastCleanupAttempt = 0;\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      cacheHitCount: this.telemetry.getMeter().createCounter(\"cache.hit\", {\n        description: \"Total number of cache hits\",\n        unit: \"1\",\n      }),\n      cacheMissCount: this.telemetry.getMeter().createCounter(\"cache.miss\", {\n        description: \"Total number of cache misses\",\n        unit: \"1\",\n      }),\n    };\n  }\n\n  /**\n   * Get the singleton instance of the cache manager (sync version).\n   *\n   * Throws if not initialized - ensure AppKit.create() has completed first.\n   * @returns CacheManager instance\n   */\n  static getInstanceSync(): CacheManager {\n    if (!CacheManager.instance) {\n      throw new Error(\n        \"CacheManager not initialized. Ensure AppKit.create() has completed before accessing the cache.\",\n      );\n    }\n\n    return CacheManager.instance;\n  }\n\n  /**\n   * Initialize and get the singleton instance of the cache manager.\n   * Called internally by AppKit - prefer `getInstanceSync()` for plugin access.\n   * @param userConfig - User configuration for the cache manager\n   * @returns CacheManager instance\n   * @internal\n   */\n  static async getInstance(\n    userConfig?: Partial<CacheConfig>,\n  ): Promise<CacheManager> {\n    if (CacheManager.instance) {\n      return CacheManager.instance;\n    }\n\n    if (!CacheManager.initPromise) {\n      CacheManager.initPromise = CacheManager.create(userConfig).then(\n        (instance) => {\n          CacheManager.instance = instance;\n          return instance;\n        },\n      );\n    }\n\n    return CacheManager.initPromise;\n  }\n\n  /**\n   * Create a new cache manager instance\n   *\n   * Storage selection logic:\n   * 1. If `storage` provided and healthy → use provided storage\n   * 2. If `storage` provided but unhealthy → fallback to InMemory (or disable if strictPersistence)\n   * 3. If no `storage` provided and Lakebase available → use Lakebase\n   * 4. If no `storage` provided and Lakebase unavailable → fallback to InMemory (or disable if strictPersistence)\n   *\n   * @param userConfig - User configuration for the cache manager\n   * @returns CacheManager instance\n   */\n  private static async create(\n    userConfig?: Partial<CacheConfig>,\n  ): Promise<CacheManager> {\n    const config = deepMerge(cacheDefaults, userConfig);\n\n    if (config.storage) {\n      const isHealthy = await config.storage.healthCheck();\n      if (isHealthy) {\n        return new CacheManager(config.storage, config);\n      }\n\n      console.warn(\"[Cache] Provided storage health check failed\");\n\n      if (config.strictPersistence) {\n        console.warn(\n          \"[Cache] strictPersistence enabled but provided storage unhealthy. Cache disabled.\",\n        );\n        const disabledConfig = { ...config, enabled: false };\n        return new CacheManager(\n          new InMemoryStorage(disabledConfig),\n          disabledConfig,\n        );\n      }\n\n      console.warn(\"[Cache] Falling back to in-memory cache.\");\n      return new CacheManager(new InMemoryStorage(config), config);\n    }\n\n    // try to use lakebase storage\n    try {\n      const workspaceClient = new WorkspaceClient({});\n      const connector = new LakebaseConnector({ workspaceClient });\n      const isHealthy = await connector.healthCheck();\n\n      if (isHealthy) {\n        const persistentStorage = new PersistentStorage(config, connector);\n        await persistentStorage.initialize();\n        return new CacheManager(persistentStorage, config);\n      }\n\n      console.warn(\n        \"[Cache] Lakebase health check failed, default storage unhealthy\",\n      );\n    } catch (error) {\n      const errorMessage =\n        error instanceof Error ? error.message : String(error);\n      console.warn(`[Cache] Lakebase unavailable: ${errorMessage}`);\n    }\n\n    if (config.strictPersistence) {\n      console.warn(\n        \"[Cache] strictPersistence enabled but lakebase unavailable. Cache disabled.\",\n      );\n      const disabledConfig = { ...config, enabled: false };\n      return new CacheManager(\n        new InMemoryStorage(disabledConfig),\n        disabledConfig,\n      );\n    }\n\n    console.warn(\"[Cache] Falling back to in-memory cache.\");\n    return new CacheManager(new InMemoryStorage(config), config);\n  }\n\n  /**\n   * Get or execute a function and cache the result\n   * @param key - Cache key\n   * @param fn - Function to execute\n   * @param userKey - User key\n   * @param options - Options for the cache\n   * @returns Promise of the result\n   */\n  async getOrExecute<T>(\n    key: (string | number | object)[],\n    fn: () => Promise<T>,\n    userKey: string,\n    options?: { ttl?: number },\n  ): Promise<T> {\n    if (!this.config.enabled) return fn();\n\n    const cacheKey = this.generateKey(key, userKey);\n\n    return this.telemetry.startActiveSpan(\n      \"cache.getOrExecute\",\n      {\n        attributes: {\n          \"cache.key\": cacheKey,\n          \"cache.enabled\": this.config.enabled,\n          \"cache.persistent\": this.storage.isPersistent(),\n        },\n      },\n      async (span) => {\n        try {\n          // check if the value is in the cache\n          const cached = await this.storage.get<T>(cacheKey);\n          if (cached !== null) {\n            span.setAttribute(\"cache.hit\", true);\n            span.setStatus({ code: SpanStatusCode.OK });\n            this.telemetryMetrics.cacheHitCount.add(1, {\n              \"cache.key\": cacheKey,\n            });\n            return cached.value as T;\n          }\n\n          // check if the value is being processed by another request\n          const inFlight = this.inFlightRequests.get(cacheKey);\n          if (inFlight) {\n            span.setAttribute(\"cache.hit\", true);\n            span.setAttribute(\"cache.deduplication\", true);\n            span.addEvent(\"cache.deduplication_used\", {\n              \"cache.key\": cacheKey,\n            });\n            span.setStatus({ code: SpanStatusCode.OK });\n            this.telemetryMetrics.cacheHitCount.add(1, {\n              \"cache.key\": cacheKey,\n              \"cache.deduplication\": \"true\",\n            });\n            span.end();\n            return inFlight as Promise<T>;\n          }\n\n          // cache miss - execute function\n          span.setAttribute(\"cache.hit\", false);\n          span.addEvent(\"cache.miss\", { \"cache.key\": cacheKey });\n          this.telemetryMetrics.cacheMissCount.add(1, {\n            \"cache.key\": cacheKey,\n          });\n\n          const promise = fn()\n            .then(async (result) => {\n              await this.set(cacheKey, result, options);\n              span.addEvent(\"cache.value_stored\", {\n                \"cache.key\": cacheKey,\n                \"cache.ttl\": options?.ttl ?? this.config.ttl ?? 3600,\n              });\n              return result;\n            })\n            .catch((error) => {\n              span.recordException(error);\n              span.setStatus({ code: SpanStatusCode.ERROR });\n              throw error;\n            })\n            .finally(() => {\n              this.inFlightRequests.delete(cacheKey);\n            });\n\n          this.inFlightRequests.set(cacheKey, promise);\n\n          const result = await promise;\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n          throw error;\n        } finally {\n          span.end();\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  /**\n   * Get a cached value\n   * @param key - Cache key\n   * @returns Promise of the value or null if not found or expired\n   */\n  async get<T>(key: string): Promise<T | null> {\n    if (!this.config.enabled) return null;\n\n    // probabilistic cleanup trigger\n    this.maybeCleanup();\n\n    const entry = await this.storage.get<T>(key);\n    if (!entry) return null;\n\n    if (Date.now() > entry.expiry) {\n      await this.storage.delete(key);\n      return null;\n    }\n    return entry.value as T;\n  }\n\n  /** Probabilistically trigger cleanup of expired entries (fire-and-forget) */\n  private maybeCleanup(): void {\n    if (this.cleanupInProgress) return;\n    if (!this.storage.isPersistent()) return;\n    const now = Date.now();\n    if (now - this.lastCleanupAttempt < CacheManager.MIN_CLEANUP_INTERVAL_MS)\n      return;\n\n    const probability = this.config.cleanupProbability ?? 0.01;\n\n    if (Math.random() > probability) return;\n\n    this.lastCleanupAttempt = now;\n\n    this.cleanupInProgress = true;\n    (this.storage as PersistentStorage)\n      .cleanupExpired()\n      .catch((error) => {\n        console.debug(\"Error cleaning up expired entries:\", error);\n      })\n      .finally(() => {\n        this.cleanupInProgress = false;\n      });\n  }\n\n  /**\n   * Set a value in the cache\n   * @param key - Cache key\n   * @param value - Value to set\n   * @param options - Options for the cache\n   * @returns Promise of the result\n   */\n  async set<T>(\n    key: string,\n    value: T,\n    options?: { ttl?: number },\n  ): Promise<void> {\n    if (!this.config.enabled) return;\n\n    const ttl = options?.ttl ?? this.config.ttl ?? 3600;\n    const expiryTime = Date.now() + ttl * 1000;\n    await this.storage.set(key, { value, expiry: expiryTime });\n  }\n\n  /**\n   * Delete a value from the cache\n   * @param key - Cache key\n   * @returns Promise of the result\n   */\n  async delete(key: string): Promise<void> {\n    if (!this.config.enabled) return;\n    await this.storage.delete(key);\n  }\n\n  /** Clear the cache */\n  async clear(): Promise<void> {\n    await this.storage.clear();\n    this.inFlightRequests.clear();\n  }\n\n  /**\n   * Check if a value exists in the cache\n   * @param key - Cache key\n   * @returns Promise of true if the value exists, false otherwise\n   */\n  async has(key: string): Promise<boolean> {\n    if (!this.config.enabled) return false;\n\n    const entry = await this.storage.get(key);\n    if (!entry) return false;\n\n    if (Date.now() > entry.expiry) {\n      await this.storage.delete(key);\n      return false;\n    }\n    return true;\n  }\n\n  /**\n   * Generate a cache key\n   * @param parts - Parts of the key\n   * @param userKey - User key\n   * @returns Cache key\n   */\n  generateKey(parts: (string | number | object)[], userKey: string): string {\n    const allParts = [userKey, ...parts];\n    const serialized = JSON.stringify(allParts);\n    return createHash(\"sha256\").update(serialized).digest(\"hex\");\n  }\n\n  /** Close the cache */\n  async close(): Promise<void> {\n    await this.storage.close();\n  }\n\n  /**\n   * Check if the storage is healthy\n   * @returns Promise of true if the storage is healthy, false otherwise\n   */\n  async isStorageHealthy(): Promise<boolean> {\n    return this.storage.healthCheck();\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["result"],"sources":["../../src/cache/index.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { CacheConfig, CacheStorage } from \"shared\";\nimport { LakebaseConnector } from \"@/connectors\";\nimport type { Counter, TelemetryProvider } from \"../telemetry\";\nimport { SpanStatusCode, TelemetryManager } from \"../telemetry\";\nimport { deepMerge } from \"../utils\";\nimport { cacheDefaults } from \"./defaults\";\nimport { InMemoryStorage, PersistentStorage } from \"./storage\";\n\n/**\n * Cache manager class to handle cache operations.\n * Can be used with in-memory storage or persistent storage (Lakebase).\n *\n * The cache is automatically initialized by AppKit. Use `getInstanceSync()` to access\n * the singleton instance after initialization.\n *\n * @example\n * ```typescript\n * const cache = CacheManager.getInstanceSync();\n * const result = await cache.getOrExecute([\"users\", userId], () => fetchUser(userId), userKey);\n * ```\n */\nexport class CacheManager {\n  private static readonly MIN_CLEANUP_INTERVAL_MS = 60_000;\n  private readonly name: string = \"cache-manager\";\n  private static instance: CacheManager | null = null;\n  private static initPromise: Promise<CacheManager> | null = null;\n\n  private storage: CacheStorage;\n  private config: CacheConfig;\n  private inFlightRequests: Map<string, Promise<unknown>>;\n  private cleanupInProgress: boolean;\n  private lastCleanupAttempt: number;\n\n  // Telemetry\n  private telemetry: TelemetryProvider;\n  private telemetryMetrics: {\n    cacheHitCount: Counter;\n    cacheMissCount: Counter;\n  };\n\n  private constructor(storage: CacheStorage, config: CacheConfig) {\n    this.storage = storage;\n    this.config = config;\n    this.inFlightRequests = new Map();\n    this.cleanupInProgress = false;\n    this.lastCleanupAttempt = 0;\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      cacheHitCount: this.telemetry.getMeter().createCounter(\"cache.hit\", {\n        description: \"Total number of cache hits\",\n        unit: \"1\",\n      }),\n      cacheMissCount: this.telemetry.getMeter().createCounter(\"cache.miss\", {\n        description: \"Total number of cache misses\",\n        unit: \"1\",\n      }),\n    };\n  }\n\n  /**\n   * Get the singleton instance of the cache manager (sync version).\n   *\n   * Throws if not initialized - ensure AppKit.create() has completed first.\n   * @returns CacheManager instance\n   */\n  static getInstanceSync(): CacheManager {\n    if (!CacheManager.instance) {\n      throw new Error(\n        \"CacheManager not initialized. Ensure AppKit.create() has completed before accessing the cache.\",\n      );\n    }\n\n    return CacheManager.instance;\n  }\n\n  /**\n   * Initialize and get the singleton instance of the cache manager.\n   * Called internally by AppKit - prefer `getInstanceSync()` for plugin access.\n   * @param userConfig - User configuration for the cache manager\n   * @returns CacheManager instance\n   * @internal\n   */\n  static async getInstance(\n    userConfig?: Partial<CacheConfig>,\n  ): Promise<CacheManager> {\n    if (CacheManager.instance) {\n      return CacheManager.instance;\n    }\n\n    if (!CacheManager.initPromise) {\n      CacheManager.initPromise = CacheManager.create(userConfig).then(\n        (instance) => {\n          CacheManager.instance = instance;\n          return instance;\n        },\n      );\n    }\n\n    return CacheManager.initPromise;\n  }\n\n  /**\n   * Create a new cache manager instance\n   *\n   * Storage selection logic:\n   * 1. If `storage` provided and healthy → use provided storage\n   * 2. If `storage` provided but unhealthy → fallback to InMemory (or disable if strictPersistence)\n   * 3. If no `storage` provided and Lakebase available → use Lakebase\n   * 4. If no `storage` provided and Lakebase unavailable → fallback to InMemory (or disable if strictPersistence)\n   *\n   * @param userConfig - User configuration for the cache manager\n   * @returns CacheManager instance\n   */\n  private static async create(\n    userConfig?: Partial<CacheConfig>,\n  ): Promise<CacheManager> {\n    const config = deepMerge(cacheDefaults, userConfig);\n\n    if (config.storage) {\n      const isHealthy = await config.storage.healthCheck();\n      if (isHealthy) {\n        return new CacheManager(config.storage, config);\n      }\n\n      if (config.strictPersistence) {\n        const disabledConfig = { ...config, enabled: false };\n        return new CacheManager(\n          new InMemoryStorage(disabledConfig),\n          disabledConfig,\n        );\n      }\n\n      return new CacheManager(new InMemoryStorage(config), config);\n    }\n\n    // try to use lakebase storage\n    try {\n      const workspaceClient = new WorkspaceClient({});\n      const connector = new LakebaseConnector({ workspaceClient });\n      const isHealthy = await connector.healthCheck();\n\n      if (isHealthy) {\n        const persistentStorage = new PersistentStorage(config, connector);\n        await persistentStorage.initialize();\n        return new CacheManager(persistentStorage, config);\n      }\n    } catch {\n      // lakebase unavailable, continue with in-memory storage\n    }\n\n    if (config.strictPersistence) {\n      const disabledConfig = { ...config, enabled: false };\n      return new CacheManager(\n        new InMemoryStorage(disabledConfig),\n        disabledConfig,\n      );\n    }\n\n    return new CacheManager(new InMemoryStorage(config), config);\n  }\n\n  /**\n   * Get or execute a function and cache the result\n   * @param key - Cache key\n   * @param fn - Function to execute\n   * @param userKey - User key\n   * @param options - Options for the cache\n   * @returns Promise of the result\n   */\n  async getOrExecute<T>(\n    key: (string | number | object)[],\n    fn: () => Promise<T>,\n    userKey: string,\n    options?: { ttl?: number },\n  ): Promise<T> {\n    if (!this.config.enabled) return fn();\n\n    const cacheKey = this.generateKey(key, userKey);\n\n    return this.telemetry.startActiveSpan(\n      \"cache.getOrExecute\",\n      {\n        attributes: {\n          \"cache.key\": cacheKey,\n          \"cache.enabled\": this.config.enabled,\n          \"cache.persistent\": this.storage.isPersistent(),\n        },\n      },\n      async (span) => {\n        try {\n          // check if the value is in the cache\n          const cached = await this.storage.get<T>(cacheKey);\n          if (cached !== null) {\n            span.setAttribute(\"cache.hit\", true);\n            span.setStatus({ code: SpanStatusCode.OK });\n            this.telemetryMetrics.cacheHitCount.add(1, {\n              \"cache.key\": cacheKey,\n            });\n            return cached.value as T;\n          }\n\n          // check if the value is being processed by another request\n          const inFlight = this.inFlightRequests.get(cacheKey);\n          if (inFlight) {\n            span.setAttribute(\"cache.hit\", true);\n            span.setAttribute(\"cache.deduplication\", true);\n            span.addEvent(\"cache.deduplication_used\", {\n              \"cache.key\": cacheKey,\n            });\n            span.setStatus({ code: SpanStatusCode.OK });\n            this.telemetryMetrics.cacheHitCount.add(1, {\n              \"cache.key\": cacheKey,\n              \"cache.deduplication\": \"true\",\n            });\n            span.end();\n            return inFlight as Promise<T>;\n          }\n\n          // cache miss - execute function\n          span.setAttribute(\"cache.hit\", false);\n          span.addEvent(\"cache.miss\", { \"cache.key\": cacheKey });\n          this.telemetryMetrics.cacheMissCount.add(1, {\n            \"cache.key\": cacheKey,\n          });\n\n          const promise = fn()\n            .then(async (result) => {\n              await this.set(cacheKey, result, options);\n              span.addEvent(\"cache.value_stored\", {\n                \"cache.key\": cacheKey,\n                \"cache.ttl\": options?.ttl ?? this.config.ttl ?? 3600,\n              });\n              return result;\n            })\n            .catch((error) => {\n              span.recordException(error);\n              span.setStatus({ code: SpanStatusCode.ERROR });\n              throw error;\n            })\n            .finally(() => {\n              this.inFlightRequests.delete(cacheKey);\n            });\n\n          this.inFlightRequests.set(cacheKey, promise);\n\n          const result = await promise;\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n          throw error;\n        } finally {\n          span.end();\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  /**\n   * Get a cached value\n   * @param key - Cache key\n   * @returns Promise of the value or null if not found or expired\n   */\n  async get<T>(key: string): Promise<T | null> {\n    if (!this.config.enabled) return null;\n\n    // probabilistic cleanup trigger\n    this.maybeCleanup();\n\n    const entry = await this.storage.get<T>(key);\n    if (!entry) return null;\n\n    if (Date.now() > entry.expiry) {\n      await this.storage.delete(key);\n      return null;\n    }\n    return entry.value as T;\n  }\n\n  /** Probabilistically trigger cleanup of expired entries (fire-and-forget) */\n  private maybeCleanup(): void {\n    if (this.cleanupInProgress) return;\n    if (!this.storage.isPersistent()) return;\n    const now = Date.now();\n    if (now - this.lastCleanupAttempt < CacheManager.MIN_CLEANUP_INTERVAL_MS)\n      return;\n\n    const probability = this.config.cleanupProbability ?? 0.01;\n\n    if (Math.random() > probability) return;\n\n    this.lastCleanupAttempt = now;\n\n    this.cleanupInProgress = true;\n    (this.storage as PersistentStorage)\n      .cleanupExpired()\n      .catch((error) => {\n        console.debug(\"Error cleaning up expired entries:\", error);\n      })\n      .finally(() => {\n        this.cleanupInProgress = false;\n      });\n  }\n\n  /**\n   * Set a value in the cache\n   * @param key - Cache key\n   * @param value - Value to set\n   * @param options - Options for the cache\n   * @returns Promise of the result\n   */\n  async set<T>(\n    key: string,\n    value: T,\n    options?: { ttl?: number },\n  ): Promise<void> {\n    if (!this.config.enabled) return;\n\n    const ttl = options?.ttl ?? this.config.ttl ?? 3600;\n    const expiryTime = Date.now() + ttl * 1000;\n    await this.storage.set(key, { value, expiry: expiryTime });\n  }\n\n  /**\n   * Delete a value from the cache\n   * @param key - Cache key\n   * @returns Promise of the result\n   */\n  async delete(key: string): Promise<void> {\n    if (!this.config.enabled) return;\n    await this.storage.delete(key);\n  }\n\n  /** Clear the cache */\n  async clear(): Promise<void> {\n    await this.storage.clear();\n    this.inFlightRequests.clear();\n  }\n\n  /**\n   * Check if a value exists in the cache\n   * @param key - Cache key\n   * @returns Promise of true if the value exists, false otherwise\n   */\n  async has(key: string): Promise<boolean> {\n    if (!this.config.enabled) return false;\n\n    const entry = await this.storage.get(key);\n    if (!entry) return false;\n\n    if (Date.now() > entry.expiry) {\n      await this.storage.delete(key);\n      return false;\n    }\n    return true;\n  }\n\n  /**\n   * Generate a cache key\n   * @param parts - Parts of the key\n   * @param userKey - User key\n   * @returns Cache key\n   */\n  generateKey(parts: (string | number | object)[], userKey: string): string {\n    const allParts = [userKey, ...parts];\n    const serialized = JSON.stringify(allParts);\n    return createHash(\"sha256\").update(serialized).digest(\"hex\");\n  }\n\n  /** Close the cache */\n  async close(): Promise<void> {\n    await this.storage.close();\n  }\n\n  /**\n   * Check if the storage is healthy\n   * @returns Promise of true if the storage is healthy, false otherwise\n   */\n  async isStorageHealthy(): Promise<boolean> {\n    return this.storage.healthCheck();\n  }\n}\n"],"mappings":"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"}

package/dist/type-generator/cache.js

@@ -0,0 +1,49 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import fs from "node:fs";
+
+//#region src/type-generator/cache.ts
+const CACHE_VERSION = "1";
+const CACHE_FILE = ".appkit-types-cache.json";
+/**
+* Hash the SQL query
+* Uses MD5 to hash the SQL query
+* @param sql - the SQL query to hash
+* @returns - the hash of the SQL query
+*/
+function hashSQL(sql) {
+	return crypto.createHash("md5").update(sql).digest("hex");
+}
+/**
+* Load the cache from the file system
+* If the cache is not found, run the query explain
+* @param cacheDir - the directory to load the cache from
+* @returns - the cache
+*/
+function loadCache(cacheDir) {
+	const cachePath = path.join(cacheDir, CACHE_FILE);
+	try {
+		if (fs.existsSync(cachePath)) {
+			const cache = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+			if (cache.version === CACHE_VERSION) return cache;
+		}
+	} catch {}
+	return {
+		version: CACHE_VERSION,
+		queries: {}
+	};
+}
+/**
+* Save the cache to the file system
+* The cache is saved as a JSON file, it is used to avoid running the query explain multiple times
+* @param cacheDir - the directory to save the cache to
+* @param cache - cache object to save
+*/
+function saveCache(cacheDir, cache) {
+	const cachePath = path.join(cacheDir, CACHE_FILE);
+	fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), "utf8");
+}
+
+//#endregion
+export { CACHE_VERSION, hashSQL, loadCache, saveCache };
+//# sourceMappingURL=cache.js.map

package/dist/type-generator/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs\";\nimport path from \"node:path\";\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n}\n\nexport const CACHE_VERSION = \"1\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @param cacheDir - the directory to load the cache from\n * @returns - the cache\n */\nexport function loadCache(cacheDir: string): Cache {\n  const cachePath = path.join(cacheDir, CACHE_FILE);\n  try {\n    if (fs.existsSync(cachePath)) {\n      const cache = JSON.parse(fs.readFileSync(cachePath, \"utf8\")) as Cache;\n      if (cache.version === CACHE_VERSION) {\n        return cache;\n      }\n    }\n  } catch {\n    // ignore cache errors\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * The cache is saved as a JSON file, it is used to avoid running the query explain multiple times\n * @param cacheDir - the directory to save the cache to\n * @param cache - cache object to save\n */\nexport function saveCache(cacheDir: string, cache: Cache): void {\n  const cachePath = path.join(cacheDir, CACHE_FILE);\n  fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;AAwBA,MAAa,gBAAgB;AAC7B,MAAM,aAAa;;;;;;;AAQnB,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;;AAS3D,SAAgB,UAAU,UAAyB;CACjD,MAAM,YAAY,KAAK,KAAK,UAAU,WAAW;AACjD,KAAI;AACF,MAAI,GAAG,WAAW,UAAU,EAAE;GAC5B,MAAM,QAAQ,KAAK,MAAM,GAAG,aAAa,WAAW,OAAO,CAAC;AAC5D,OAAI,MAAM,YAAY,cACpB,QAAO;;SAGL;AAGR,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;;;AAShD,SAAgB,UAAU,UAAkB,OAAoB;CAC9D,MAAM,YAAY,KAAK,KAAK,UAAU,WAAW;AACjD,IAAG,cAAc,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}

package/dist/type-generator/index.js

@@ -0,0 +1,46 @@
+import { generateQueriesFromDescribe } from "./query-registry.js";
+import fs from "node:fs";
+import dotenv from "dotenv";
+
+//#region src/type-generator/index.ts
+dotenv.config();
+/**
+* Generate type declarations for QueryRegistry
+* Create the d.ts file from the plugin routes and query schemas
+* @param querySchemas - the list of query schemas
+* @returns - the type declarations as a string
+*/
+function generateTypeDeclarations(querySchemas = []) {
+	const queryEntries = querySchemas.map(({ name, type }) => {
+		return `    ${name}: ${type.split("\n").map((line, i) => i === 0 ? line : `    ${line}`).join("\n")}`;
+	}).join(";\n");
+	return `// Auto-generated by AppKit - DO NOT EDIT
+// Generated by 'npx appkit-generate-types' or Vite plugin during build
+import "@databricks/appkit-ui/react";
+import type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from "@databricks/appkit-ui/js";
+
+declare module "@databricks/appkit-ui/react" {
+  interface QueryRegistry {${queryEntries ? `\n${queryEntries};\n  ` : ""}}
+}
+`;
+}
+/**
+* Entry point for generating type declarations from all imported files
+* @param options - the options for the generation
+* @param options.entryPoint - the entry point file
+* @param options.outFile - the output file
+* @param options.querySchemaFile - optional path to query schema file (e.g. config/queries/schema.ts)
+*/
+async function generateFromEntryPoint(options) {
+	const { outFile, queryFolder, warehouseId, noCache } = options;
+	console.log("\n[AppKit] Starting type generation...\n");
+	let queryRegistry = [];
+	if (queryFolder) queryRegistry = await generateQueriesFromDescribe(queryFolder, warehouseId, { noCache });
+	const typeDeclarations = generateTypeDeclarations(queryRegistry);
+	fs.writeFileSync(outFile, typeDeclarations, "utf-8");
+	console.log("\n[AppKit] Type generation complete!\n");
+}
+
+//#endregion
+export { generateFromEntryPoint };
+//# sourceMappingURL=index.js.map

package/dist/type-generator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["queryRegistry: QuerySchema[]"],"sources":["../../src/type-generator/index.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport dotenv from \"dotenv\";\nimport { generateQueriesFromDescribe } from \"./query-registry\";\nimport type { QuerySchema } from \"./types\";\n\ndotenv.config();\n\n/**\n * Generate type declarations for QueryRegistry\n * Create the d.ts file from the plugin routes and query schemas\n * @param querySchemas - the list of query schemas\n * @returns - the type declarations as a string\n */\nfunction generateTypeDeclarations(querySchemas: QuerySchema[] = []): string {\n  const queryEntries = querySchemas\n    .map(({ name, type }) => {\n      const indentedType = type\n        .split(\"\\n\")\n        .map((line, i) => (i === 0 ? line : `    ${line}`))\n        .join(\"\\n\");\n      return `    ${name}: ${indentedType}`;\n    })\n    .join(\";\\n\");\n\n  const querySection = queryEntries ? `\\n${queryEntries};\\n  ` : \"\";\n\n  return `// Auto-generated by AppKit - DO NOT EDIT\n// Generated by 'npx appkit-generate-types' or Vite plugin during build\nimport \"@databricks/appkit-ui/react\";\nimport type { SQLTypeMarker, SQLStringMarker, SQLNumberMarker, SQLBooleanMarker, SQLBinaryMarker, SQLDateMarker, SQLTimestampMarker } from \"@databricks/appkit-ui/js\";\n\ndeclare module \"@databricks/appkit-ui/react\" {\n  interface QueryRegistry {${querySection}}\n}\n`;\n}\n\n/**\n * Entry point for generating type declarations from all imported files\n * @param options - the options for the generation\n * @param options.entryPoint - the entry point file\n * @param options.outFile - the output file\n * @param options.querySchemaFile - optional path to query schema file (e.g. config/queries/schema.ts)\n */\nexport async function generateFromEntryPoint(options: {\n  outFile: string;\n  queryFolder?: string;\n  warehouseId: string;\n  noCache?: boolean;\n}) {\n  const { outFile, queryFolder, warehouseId, noCache } = options;\n\n  console.log(\"\\n[AppKit] Starting type generation...\\n\");\n\n  let queryRegistry: QuerySchema[] = [];\n  if (queryFolder)\n    queryRegistry = await generateQueriesFromDescribe(\n      queryFolder,\n      warehouseId,\n      {\n        noCache,\n      },\n    );\n\n  const typeDeclarations = generateTypeDeclarations(queryRegistry);\n\n  fs.writeFileSync(outFile, typeDeclarations, \"utf-8\");\n\n  console.log(\"\\n[AppKit] Type generation complete!\\n\");\n}\n"],"mappings":";;;;;AAKA,OAAO,QAAQ;;;;;;;AAQf,SAAS,yBAAyB,eAA8B,EAAE,EAAU;CAC1E,MAAM,eAAe,aAClB,KAAK,EAAE,MAAM,WAAW;AAKvB,SAAO,OAAO,KAAK,IAJE,KAClB,MAAM,KAAK,CACX,KAAK,MAAM,MAAO,MAAM,IAAI,OAAO,OAAO,OAAQ,CAClD,KAAK,KAAK;GAEb,CACD,KAAK,MAAM;AAId,QAAO;;;;;;6BAFc,eAAe,KAAK,aAAa,SAAS,GAQvB;;;;;;;;;;;AAY1C,eAAsB,uBAAuB,SAK1C;CACD,MAAM,EAAE,SAAS,aAAa,aAAa,YAAY;AAEvD,SAAQ,IAAI,2CAA2C;CAEvD,IAAIA,gBAA+B,EAAE;AACrC,KAAI,YACF,iBAAgB,MAAM,4BACpB,aACA,aACA,EACE,SACD,CACF;CAEH,MAAM,mBAAmB,yBAAyB,cAAc;AAEhE,IAAG,cAAc,SAAS,kBAAkB,QAAQ;AAEpD,SAAQ,IAAI,yCAAyC"}

package/dist/type-generator/query-registry.js

@@ -0,0 +1,170 @@
+import { CACHE_VERSION, hashSQL, loadCache, saveCache } from "./cache.js";
+import { Spinner } from "./spinner.js";
+import { sqlTypeToHelper, sqlTypeToMarker } from "./types.js";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+import path from "node:path";
+import fs from "node:fs";
+
+//#region src/type-generator/query-registry.ts
+/**
+* Extract parameters from a SQL query
+* @param sql - the SQL query to extract parameters from
+* @returns an array of parameter names
+*/
+function extractParameters(sql) {
+	const matches = sql.matchAll(/:([a-zA-Z_]\w*)/g);
+	const params = /* @__PURE__ */ new Set();
+	for (const match of matches) params.add(match[1]);
+	return Array.from(params);
+}
+const SERVER_INJECTED_PARAMS = ["workspaceId"];
+function convertToQueryType(result, sql, queryName) {
+	const columns = (result.result?.data_array || []).map((row) => ({
+		name: row[0] || "",
+		type_name: row[1]?.toUpperCase() || "STRING",
+		comment: row[2] || void 0
+	}));
+	const params = extractParameters(sql).filter((p) => !SERVER_INJECTED_PARAMS.includes(p));
+	const paramTypes = extractParameterTypes(sql);
+	return `{
+    name: "${queryName}";
+    parameters: ${params.length > 0 ? `{\n      ${params.map((p) => {
+		const sqlType = paramTypes[p];
+		const markerType = sqlType ? sqlTypeToMarker[sqlType] : "SQLTypeMarker";
+		const helper = sqlType ? sqlTypeToHelper[sqlType] : "sql.*()";
+		return `/** ${sqlType || "any"} - use ${helper} */\n      ${p}: ${markerType}`;
+	}).join(";\n      ")};\n    }` : "Record<string, never>"};
+    result: Array<{
+      ${columns.map((column) => {
+		const mappedType = typeMap[normalizeTypeName(column.type_name)] || "unknown";
+		const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name) ? column.name : `"${column.name}"`;
+		return `${column.comment ? `/** ${column.comment} */\n      ` : `/** @sqlType ${column.type_name} */\n      `}${name}: ${mappedType}`;
+	}).join(";\n      ")};
+    }>;
+  }`;
+}
+function extractParameterTypes(sql) {
+	const paramTypes = {};
+	const matches = sql.matchAll(/--\s*@param\s+(\w+)\s+(STRING|NUMERIC|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi);
+	for (const match of matches) {
+		const [, paramName, paramType] = match;
+		paramTypes[paramName] = paramType.toUpperCase();
+	}
+	return paramTypes;
+}
+/**
+* Generate query schemas from a folder of SQL files
+* It uses DESCRIBE QUERY to get the schema without executing the query
+* @param queryFolder - the folder containing the SQL files
+* @param warehouseId - the warehouse id to use for schema analysis
+* @param options - options for the query generation
+* @param options.noCache - if true, skip the cache and regenerate all types
+* @returns an array of query schemas
+*/
+async function generateQueriesFromDescribe(queryFolder, warehouseId, options = {}) {
+	const { noCache = false } = options;
+	const queryFiles = fs.readdirSync(queryFolder).filter((file) => file.endsWith(".sql"));
+	console.log(`  Found ${queryFiles.length} SQL queries\n`);
+	const cache = noCache ? {
+		version: CACHE_VERSION,
+		queries: {}
+	} : loadCache(queryFolder);
+	const client = new WorkspaceClient({});
+	const querySchemas = [];
+	const failedQueries = [];
+	const spinner = new Spinner();
+	for (let i = 0; i < queryFiles.length; i++) {
+		const file = queryFiles[i];
+		const queryName = path.basename(file, ".sql");
+		const sql = fs.readFileSync(path.join(queryFolder, file), "utf8");
+		const sqlHash = hashSQL(sql);
+		const cached = cache.queries[queryName];
+		if (cached && cached.hash === sqlHash) {
+			querySchemas.push({
+				name: queryName,
+				type: cached.type
+			});
+			spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);
+			spinner.stop(`✓ ${queryName} (cached)`);
+			continue;
+		}
+		spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);
+		const cleanedSql = sql.replace(/:([a-zA-Z_]\w*)/g, "''").trim().replace(/;\s*$/, "");
+		try {
+			const result = await client.statementExecution.executeStatement({
+				statement: `DESCRIBE QUERY ${cleanedSql}`,
+				warehouse_id: warehouseId
+			});
+			if (result.status.state === "FAILED") {
+				spinner.stop(`✗ ${queryName} - failed`);
+				failedQueries.push({
+					name: queryName,
+					error: "Query execution failed"
+				});
+				continue;
+			}
+			const type = convertToQueryType(result, sql, queryName);
+			querySchemas.push({
+				name: queryName,
+				type
+			});
+			cache.queries[queryName] = {
+				hash: sqlHash,
+				type
+			};
+			spinner.stop(`✓ ${queryName}`);
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : "Unknown error";
+			spinner.stop(`✗ ${queryName} - ${errorMessage}`);
+			failedQueries.push({
+				name: queryName,
+				error: errorMessage
+			});
+		}
+	}
+	saveCache(queryFolder, cache);
+	if (failedQueries.length > 0) console.warn(`  Warning: ${failedQueries.length} queries failed\n`);
+	return querySchemas;
+}
+/**
+* Normalize SQL type name by removing parameters/generics
+* Examples:
+*   DECIMAL(38,6) -> DECIMAL
+*   ARRAY<STRING> -> ARRAY
+*   MAP<STRING,INT> -> MAP
+*   STRUCT<name:STRING> -> STRUCT
+*   INTERVAL DAY TO SECOND -> INTERVAL
+*   GEOGRAPHY(4326) -> GEOGRAPHY
+*/
+function normalizeTypeName(typeName) {
+	return typeName.replace(/\(.*\)$/, "").replace(/<.*>$/, "").split(" ")[0];
+}
+/** Type Map for Databricks data types to JavaScript types */
+const typeMap = {
+	STRING: "string",
+	BINARY: "string",
+	BOOLEAN: "boolean",
+	TINYINT: "number",
+	SMALLINT: "number",
+	INT: "number",
+	BIGINT: "number",
+	FLOAT: "number",
+	DOUBLE: "number",
+	DECIMAL: "number",
+	DATE: "string",
+	TIMESTAMP: "string",
+	TIMESTAMP_NTZ: "string",
+	INTERVAL: "string",
+	ARRAY: "unknown[]",
+	MAP: "Record<string, unknown>",
+	STRUCT: "Record<string, unknown>",
+	OBJECT: "Record<string, unknown>",
+	VARIANT: "unknown",
+	GEOGRAPHY: "unknown",
+	GEOMETRY: "unknown",
+	VOID: "null"
+};
+
+//#endregion
+export { generateQueriesFromDescribe };
+//# sourceMappingURL=query-registry.js.map

package/dist/type-generator/query-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-registry.js","names":["paramTypes: Record<string, string>","querySchemas: QuerySchema[]","failedQueries: { name: string; error: string }[]","typeMap: Record<string, string>"],"sources":["../../src/type-generator/query-registry.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport { CACHE_VERSION, hashSQL, loadCache, saveCache } from \"./cache\";\nimport { Spinner } from \"./spinner\";\nimport {\n  type DatabricksStatementExecutionResponse,\n  type QuerySchema,\n  sqlTypeToHelper,\n  sqlTypeToMarker,\n} from \"./types\";\n\n/**\n * Extract parameters from a SQL query\n * @param sql - the SQL query to extract parameters from\n * @returns an array of parameter names\n */\nexport function extractParameters(sql: string): string[] {\n  const matches = sql.matchAll(/:([a-zA-Z_]\\w*)/g);\n  const params = new Set<string>();\n  for (const match of matches) {\n    params.add(match[1]);\n  }\n  return Array.from(params);\n}\n\n// parameters that are injected by the server\nexport const SERVER_INJECTED_PARAMS = [\"workspaceId\"];\n\nexport function convertToQueryType(\n  result: DatabricksStatementExecutionResponse,\n  sql: string,\n  queryName: string,\n): string {\n  const dataRows = result.result?.data_array || [];\n  const columns = dataRows.map((row) => ({\n    name: row[0] || \"\",\n    type_name: row[1]?.toUpperCase() || \"STRING\",\n    comment: row[2] || undefined,\n  }));\n\n  const params = extractParameters(sql).filter(\n    (p) => !SERVER_INJECTED_PARAMS.includes(p),\n  );\n\n  const paramTypes = extractParameterTypes(sql);\n\n  // generate parameters types with JSDoc hints\n  const paramsType =\n    params.length > 0\n      ? `{\\n      ${params\n          .map((p) => {\n            const sqlType = paramTypes[p];\n            // if no type annotation, use SQLTypeMarker (union type)\n            const markerType = sqlType\n              ? sqlTypeToMarker[sqlType]\n              : \"SQLTypeMarker\";\n            const helper = sqlType ? sqlTypeToHelper[sqlType] : \"sql.*()\";\n            return `/** ${sqlType || \"any\"} - use ${helper} */\\n      ${p}: ${markerType}`;\n          })\n          .join(\";\\n      \")};\\n    }`\n      : \"Record<string, never>\";\n\n  // generate result fields with JSDoc\n  const resultFields = columns.map((column) => {\n    const normalizedType = normalizeTypeName(column.type_name);\n    const mappedType = typeMap[normalizedType] || \"unknown\";\n    // validate column name is a valid identifier\n    const name = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(column.name)\n      ? column.name\n      : `\"${column.name}\"`;\n\n    // generate comment for column\n    const comment = column.comment\n      ? `/** ${column.comment} */\\n      `\n      : `/** @sqlType ${column.type_name} */\\n      `;\n\n    return `${comment}${name}: ${mappedType}`;\n  });\n\n  return `{\n    name: \"${queryName}\";\n    parameters: ${paramsType};\n    result: Array<{\n      ${resultFields.join(\";\\n      \")};\n    }>;\n  }`;\n}\n\nexport function extractParameterTypes(sql: string): Record<string, string> {\n  const paramTypes: Record<string, string> = {};\n  const regex =\n    /--\\s*@param\\s+(\\w+)\\s+(STRING|NUMERIC|BOOLEAN|DATE|TIMESTAMP|BINARY)/gi;\n  const matches = sql.matchAll(regex);\n  for (const match of matches) {\n    const [, paramName, paramType] = match;\n    paramTypes[paramName] = paramType.toUpperCase();\n  }\n\n  return paramTypes;\n}\n\n/**\n * Generate query schemas from a folder of SQL files\n * It uses DESCRIBE QUERY to get the schema without executing the query\n * @param queryFolder - the folder containing the SQL files\n * @param warehouseId - the warehouse id to use for schema analysis\n * @param options - options for the query generation\n * @param options.noCache - if true, skip the cache and regenerate all types\n * @returns an array of query schemas\n */\nexport async function generateQueriesFromDescribe(\n  queryFolder: string,\n  warehouseId: string,\n  options: { noCache?: boolean } = {},\n): Promise<QuerySchema[]> {\n  const { noCache = false } = options;\n\n  // read all query files in the folder\n  const queryFiles = fs\n    .readdirSync(queryFolder)\n    .filter((file) => file.endsWith(\".sql\"));\n\n  console.log(`  Found ${queryFiles.length} SQL queries\\n`);\n\n  // load cache\n  const cache = noCache\n    ? { version: CACHE_VERSION, queries: {} }\n    : loadCache(queryFolder);\n\n  const client = new WorkspaceClient({});\n  const querySchemas: QuerySchema[] = [];\n  const failedQueries: { name: string; error: string }[] = [];\n  const spinner = new Spinner();\n\n  // process each query file\n  for (let i = 0; i < queryFiles.length; i++) {\n    const file = queryFiles[i];\n    const queryName = path.basename(file, \".sql\");\n\n    // read query file content\n    const sql = fs.readFileSync(path.join(queryFolder, file), \"utf8\");\n    const sqlHash = hashSQL(sql);\n\n    // check cache\n    const cached = cache.queries[queryName];\n    if (cached && cached.hash === sqlHash) {\n      querySchemas.push({ name: queryName, type: cached.type });\n      spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);\n      spinner.stop(`✓ ${queryName} (cached)`);\n      continue;\n    }\n\n    spinner.start(`Processing ${queryName} (${i + 1}/${queryFiles.length})`);\n\n    const sqlWithDefaults = sql.replace(/:([a-zA-Z_]\\w*)/g, \"''\");\n\n    // strip trailing semicolon for DESCRIBE QUERY\n    const cleanedSql = sqlWithDefaults.trim().replace(/;\\s*$/, \"\");\n\n    // execute DESCRIBE QUERY to get schema without running the actual query\n    try {\n      const result = (await client.statementExecution.executeStatement({\n        statement: `DESCRIBE QUERY ${cleanedSql}`,\n        warehouse_id: warehouseId,\n      })) as DatabricksStatementExecutionResponse;\n\n      if (result.status.state === \"FAILED\") {\n        spinner.stop(`✗ ${queryName} - failed`);\n        failedQueries.push({\n          name: queryName,\n          error: \"Query execution failed\",\n        });\n        continue;\n      }\n\n      // convert result to query schema\n      const type = convertToQueryType(result, sql, queryName);\n      querySchemas.push({ name: queryName, type });\n\n      // update cache\n      cache.queries[queryName] = { hash: sqlHash, type };\n\n      spinner.stop(`✓ ${queryName}`);\n    } catch (error) {\n      const errorMessage =\n        error instanceof Error ? error.message : \"Unknown error\";\n      spinner.stop(`✗ ${queryName} - ${errorMessage}`);\n      failedQueries.push({ name: queryName, error: errorMessage });\n    }\n  }\n\n  // save cache\n  saveCache(queryFolder, cache);\n\n  // log warning if there are failed queries\n  if (failedQueries.length > 0) {\n    console.warn(`  Warning: ${failedQueries.length} queries failed\\n`);\n  }\n\n  return querySchemas;\n}\n\n/**\n * Normalize SQL type name by removing parameters/generics\n * Examples:\n *   DECIMAL(38,6) -> DECIMAL\n *   ARRAY<STRING> -> ARRAY\n *   MAP<STRING,INT> -> MAP\n *   STRUCT<name:STRING> -> STRUCT\n *   INTERVAL DAY TO SECOND -> INTERVAL\n *   GEOGRAPHY(4326) -> GEOGRAPHY\n */\nexport function normalizeTypeName(typeName: string): string {\n  return typeName\n    .replace(/\\(.*\\)$/, \"\") // remove (p, s) eg: DECIMAL(38,6) -> DECIMAL\n    .replace(/<.*>$/, \"\") // remove <T> eg: ARRAY<STRING> -> ARRAY\n    .split(\" \")[0]; // take first word eg: INTERVAL DAY TO SECOND -> INTERVAL\n}\n\n/** Type Map for Databricks data types to JavaScript types */\nconst typeMap: Record<string, string> = {\n  // string types\n  STRING: \"string\",\n  BINARY: \"string\",\n  // boolean\n  BOOLEAN: \"boolean\",\n  // numeric types\n  TINYINT: \"number\",\n  SMALLINT: \"number\",\n  INT: \"number\",\n  BIGINT: \"number\",\n  FLOAT: \"number\",\n  DOUBLE: \"number\",\n  DECIMAL: \"number\",\n  // date/time types\n  DATE: \"string\",\n  TIMESTAMP: \"string\",\n  TIMESTAMP_NTZ: \"string\",\n  INTERVAL: \"string\",\n  // complex types\n  ARRAY: \"unknown[]\",\n  MAP: \"Record<string, unknown>\",\n  STRUCT: \"Record<string, unknown>\",\n  OBJECT: \"Record<string, unknown>\",\n  VARIANT: \"unknown\",\n  // spatial types\n  GEOGRAPHY: \"unknown\",\n  GEOMETRY: \"unknown\",\n  // null type\n  VOID: \"null\",\n};\n"],"mappings":"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"}

package/dist/type-generator/spinner.js

@@ -0,0 +1,37 @@
+//#region src/type-generator/spinner.ts
+/**
+* Simple loading spinner for CLI
+*/
+var Spinner = class {
+	constructor() {
+		this.frames = [
+			"   ",
+			".  ",
+			".. ",
+			"..."
+		];
+		this.current = 0;
+		this.interval = null;
+		this.text = "";
+	}
+	start(text) {
+		this.text = text;
+		this.current = 0;
+		process.stdout.write(`  ${this.text}${this.frames[0]}`);
+		this.interval = setInterval(() => {
+			this.current = (this.current + 1) % this.frames.length;
+			process.stdout.write(`\r  ${this.text}${this.frames[this.current]}`);
+		}, 300);
+	}
+	stop(finalText) {
+		if (this.interval) {
+			clearInterval(this.interval);
+			this.interval = null;
+		}
+		process.stdout.write(`\x1b[2K\r  ${finalText || this.text}\n`);
+	}
+};
+
+//#endregion
+export { Spinner };
+//# sourceMappingURL=spinner.js.map

package/dist/type-generator/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","names":[],"sources":["../../src/type-generator/spinner.ts"],"sourcesContent":["/**\n * Simple loading spinner for CLI\n */\nexport class Spinner {\n  private frames = [\"   \", \".  \", \".. \", \"...\"];\n  private current = 0;\n  private interval: NodeJS.Timeout | null = null;\n  private text = \"\";\n\n  start(text: string) {\n    this.text = text;\n    this.current = 0;\n    process.stdout.write(`  ${this.text}${this.frames[0]}`);\n    this.interval = setInterval(() => {\n      this.current = (this.current + 1) % this.frames.length;\n      process.stdout.write(`\\r  ${this.text}${this.frames[this.current]}`);\n    }, 300);\n  }\n\n  stop(finalText?: string) {\n    if (this.interval) {\n      clearInterval(this.interval);\n      this.interval = null;\n    }\n    // clear the line and write the final text\n    process.stdout.write(`\\x1b[2K\\r  ${finalText || this.text}\\n`);\n  }\n}\n"],"mappings":";;;;AAGA,IAAa,UAAb,MAAqB;;gBACF;GAAC;GAAO;GAAO;GAAO;GAAM;iBAC3B;kBACwB;cAC3B;;CAEf,MAAM,MAAc;AAClB,OAAK,OAAO;AACZ,OAAK,UAAU;AACf,UAAQ,OAAO,MAAM,KAAK,KAAK,OAAO,KAAK,OAAO,KAAK;AACvD,OAAK,WAAW,kBAAkB;AAChC,QAAK,WAAW,KAAK,UAAU,KAAK,KAAK,OAAO;AAChD,WAAQ,OAAO,MAAM,OAAO,KAAK,OAAO,KAAK,OAAO,KAAK,WAAW;KACnE,IAAI;;CAGT,KAAK,WAAoB;AACvB,MAAI,KAAK,UAAU;AACjB,iBAAc,KAAK,SAAS;AAC5B,QAAK,WAAW;;AAGlB,UAAQ,OAAO,MAAM,cAAc,aAAa,KAAK,KAAK,IAAI"}

package/dist/type-generator/types.js

@@ -0,0 +1,45 @@
+//#region src/type-generator/types.ts
+/**
+* Map of SQL types to their corresponding marker types
+* Used to convert SQL types to their corresponding marker types
+*/
+const sqlTypeToMarker = {
+	STRING: "SQLStringMarker",
+	BINARY: "SQLBinaryMarker",
+	BOOLEAN: "SQLBooleanMarker",
+	NUMERIC: "SQLNumberMarker",
+	INT: "SQLNumberMarker",
+	BIGINT: "SQLNumberMarker",
+	TINYINT: "SQLNumberMarker",
+	SMALLINT: "SQLNumberMarker",
+	FLOAT: "SQLNumberMarker",
+	DOUBLE: "SQLNumberMarker",
+	DECIMAL: "SQLNumberMarker",
+	DATE: "SQLDateMarker",
+	TIMESTAMP: "SQLTimestampMarker",
+	TIMESTAMP_NTZ: "SQLTimestampMarker"
+};
+/**
+* Map of SQL types to their corresponding helper function names
+* Used to generate JSDoc hints for parameters
+*/
+const sqlTypeToHelper = {
+	STRING: "sql.string()",
+	BINARY: "sql.binary()",
+	BOOLEAN: "sql.boolean()",
+	NUMERIC: "sql.number()",
+	INT: "sql.number()",
+	BIGINT: "sql.number()",
+	TINYINT: "sql.number()",
+	SMALLINT: "sql.number()",
+	FLOAT: "sql.number()",
+	DOUBLE: "sql.number()",
+	DECIMAL: "sql.number()",
+	DATE: "sql.date()",
+	TIMESTAMP: "sql.timestamp()",
+	TIMESTAMP_NTZ: "sql.timestamp()"
+};
+
+//#endregion
+export { sqlTypeToHelper, sqlTypeToMarker };
+//# sourceMappingURL=types.js.map

package/dist/type-generator/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":["sqlTypeToMarker: Record<string, string>","sqlTypeToHelper: Record<string, string>"],"sources":["../../src/type-generator/types.ts"],"sourcesContent":["/**\n * Databricks statement execution response interface for DESCRIBE QUERY\n * @property statement_id - the id of the statement\n * @property status - the status of the statement\n * @property result - the result containing column schema as rows [col_name, data_type, comment]\n */\nexport interface DatabricksStatementExecutionResponse {\n  statement_id: string;\n  status: { state: string };\n  result?: {\n    data_array?: (string | null)[][];\n  };\n}\n\n/**\n * Map of SQL types to their corresponding marker types\n * Used to convert SQL types to their corresponding marker types\n */\nexport const sqlTypeToMarker: Record<string, string> = {\n  // string\n  STRING: \"SQLStringMarker\",\n  BINARY: \"SQLBinaryMarker\",\n  // boolean\n  BOOLEAN: \"SQLBooleanMarker\",\n  // numeric\n  NUMERIC: \"SQLNumberMarker\",\n  INT: \"SQLNumberMarker\",\n  BIGINT: \"SQLNumberMarker\",\n  TINYINT: \"SQLNumberMarker\",\n  SMALLINT: \"SQLNumberMarker\",\n  FLOAT: \"SQLNumberMarker\",\n  DOUBLE: \"SQLNumberMarker\",\n  DECIMAL: \"SQLNumberMarker\",\n  // date/time\n  DATE: \"SQLDateMarker\",\n  TIMESTAMP: \"SQLTimestampMarker\",\n  TIMESTAMP_NTZ: \"SQLTimestampMarker\",\n};\n\n/**\n * Map of SQL types to their corresponding helper function names\n * Used to generate JSDoc hints for parameters\n */\nexport const sqlTypeToHelper: Record<string, string> = {\n  // string\n  STRING: \"sql.string()\",\n  BINARY: \"sql.binary()\",\n  // boolean\n  BOOLEAN: \"sql.boolean()\",\n  // numeric\n  NUMERIC: \"sql.number()\",\n  INT: \"sql.number()\",\n  BIGINT: \"sql.number()\",\n  TINYINT: \"sql.number()\",\n  SMALLINT: \"sql.number()\",\n  FLOAT: \"sql.number()\",\n  DOUBLE: \"sql.number()\",\n  DECIMAL: \"sql.number()\",\n  // date/time\n  DATE: \"sql.date()\",\n  TIMESTAMP: \"sql.timestamp()\",\n  TIMESTAMP_NTZ: \"sql.timestamp()\",\n};\n\n/**\n * Query schema interface\n * @property name - the name of the query\n * @property type - the type of the query (string, number, boolean, object, array, etc.)\n */\nexport interface QuerySchema {\n  name: string;\n  type: string;\n}\n"],"mappings":";;;;;AAkBA,MAAaA,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB;;;;;AAMD,MAAaC,kBAA0C;CAErD,QAAQ;CACR,QAAQ;CAER,SAAS;CAET,SAAS;CACT,KAAK;CACL,QAAQ;CACR,SAAS;CACT,UAAU;CACV,OAAO;CACP,QAAQ;CACR,SAAS;CAET,MAAM;CACN,WAAW;CACX,eAAe;CAChB"}

package/dist/type-generator/vite-plugin.d.ts

@@ -12,7 +12,7 @@ interface AppKitTypesPluginOptions {
 }
 /**
  * Vite plugin to generate types for AppKit queries.
- * Calls `npx appkit-generate-types` under the hood.
+ * Calls generateFromEntryPoint under the hood.
  * @param options - Options to override default values.
  * @returns Vite plugin to generate types for AppKit queries.
  */

package/dist/type-generator/vite-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin.d.ts","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":[],"mappings":";;;;;;AAEmC;AAkBnC,UAbU,wBAAA,CAauB;EAAA,OAAA,CAAA,EAAA,MAAA;;cAAsC,CAAA,EAAA,MAAA,EAAA;;;;;;;;iBAAvD,iBAAA,WAA4B,2BAA2B"}
+{"version":3,"file":"vite-plugin.d.ts","names":[],"sources":["../../src/type-generator/vite-plugin.ts"],"sourcesContent":[],"mappings":";;;;;;AACmC;AAmBnC,UAbU,wBAAA,CAauB;EAAA,OAAA,CAAA,EAAA,MAAA;;cAAsC,CAAA,EAAA,MAAA,EAAA;;;;;;;;iBAAvD,iBAAA,WAA4B,2BAA2B"}