@databricks/appkit 0.0.2

package/dist/server/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":["cookies: Record<string, string>","routes: Array<{ path: string; methods: string[] }>","path"],"sources":["../../src/server/utils.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs\";\nimport type http from \"node:http\";\nimport path from \"node:path\";\n\nexport function parseCookies(\n  req: http.IncomingMessage,\n): Record<string, string> {\n  const cookieHeader = req.headers.cookie;\n  if (!cookieHeader) return {};\n\n  // Fast path: if there's no semicolon, there's only one cookie\n  const semicolonIndex = cookieHeader.indexOf(\";\");\n  if (semicolonIndex === -1) {\n    const eqIndex = cookieHeader.indexOf(\"=\");\n    if (eqIndex === -1) return {};\n    return {\n      [cookieHeader.slice(0, eqIndex).trim()]: cookieHeader.slice(eqIndex + 1),\n    };\n  }\n\n  // Multiple cookies: parse them all\n  const cookies: Record<string, string> = {};\n  const parts = cookieHeader.split(\";\");\n  for (let i = 0; i < parts.length; i++) {\n    const eqIndex = parts[i].indexOf(\"=\");\n    if (eqIndex !== -1) {\n      const key = parts[i].slice(0, eqIndex).trim();\n      const value = parts[i].slice(eqIndex + 1);\n      cookies[key] = value;\n    }\n  }\n  return cookies;\n}\n\nexport function generateTunnelIdFromEmail(email?: string): string | undefined {\n  if (!email) return undefined;\n\n  const tunnelId = crypto\n    .createHash(\"sha256\")\n    .update(email)\n    .digest(\"base64url\")\n    .slice(0, 8);\n\n  return tunnelId;\n}\n\nexport function getRoutes(stack: unknown[], basePath = \"\") {\n  const routes: Array<{ path: string; methods: string[] }> = [];\n\n  stack.forEach((layer: any) => {\n    if (layer.route) {\n      // normal route\n      const path = basePath + layer.route.path;\n      const methods = Object.keys(layer.route.methods).map((m) =>\n        m.toUpperCase(),\n      );\n      routes.push({ path, methods });\n    } else if (layer.name === \"router\" && layer.handle.stack) {\n      // nested router\n      const nestedBase =\n        basePath +\n          layer.regexp.source\n            .replace(\"^\\\\\", \"\")\n            .replace(\"\\\\/?(?=\\\\/|$)\", \"\")\n            .replace(/\\\\\\//g, \"/\") // convert escaped slashes\n            .replace(/\\$$/, \"\") || \"\";\n      routes.push(...getRoutes(layer.handle.stack, nestedBase));\n    }\n  });\n\n  return routes;\n}\n\nexport function getQueries(configFolder: string) {\n  const queriesFolder = path.join(configFolder, \"queries\");\n\n  if (!fs.existsSync(queriesFolder)) {\n    return {};\n  }\n\n  return Object.fromEntries(\n    fs\n      .readdirSync(queriesFolder)\n      .filter((f) => path.extname(f) === \".sql\")\n      .map((f) => [path.basename(f, \".sql\"), path.basename(f, \".sql\")]),\n  );\n}\n\nimport type { PluginEndpoints } from \"shared\";\n\nexport type { PluginEndpoints };\n\nexport interface RuntimeConfig {\n  appName: string;\n  queries: Record<string, string>;\n  endpoints: PluginEndpoints;\n}\n\nexport function getRuntimeConfig(\n  endpoints: PluginEndpoints = {},\n): RuntimeConfig {\n  const configFolder = path.join(process.cwd(), \"config\");\n\n  return {\n    appName: process.env.DATABRICKS_APP_NAME || \"\",\n    queries: getQueries(configFolder),\n    endpoints,\n  };\n}\n\nexport function getConfigScript(endpoints: PluginEndpoints = {}): string {\n  const config = getRuntimeConfig(endpoints);\n\n  return `\n    <script>\n      window.__CONFIG__ = ${JSON.stringify(config)};\n    </script>\n  `;\n}\n"],"mappings":";;;;;AAKA,SAAgB,aACd,KACwB;CACxB,MAAM,eAAe,IAAI,QAAQ;AACjC,KAAI,CAAC,aAAc,QAAO,EAAE;AAI5B,KADuB,aAAa,QAAQ,IAAI,KACzB,IAAI;EACzB,MAAM,UAAU,aAAa,QAAQ,IAAI;AACzC,MAAI,YAAY,GAAI,QAAO,EAAE;AAC7B,SAAO,GACJ,aAAa,MAAM,GAAG,QAAQ,CAAC,MAAM,GAAG,aAAa,MAAM,UAAU,EAAE,EACzE;;CAIH,MAAMA,UAAkC,EAAE;CAC1C,MAAM,QAAQ,aAAa,MAAM,IAAI;AACrC,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,UAAU,MAAM,GAAG,QAAQ,IAAI;AACrC,MAAI,YAAY,IAAI;GAClB,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC,MAAM;AAE7C,WAAQ,OADM,MAAM,GAAG,MAAM,UAAU,EAAE;;;AAI7C,QAAO;;AAGT,SAAgB,0BAA0B,OAAoC;AAC5E,KAAI,CAAC,MAAO,QAAO;AAQnB,QANiB,OACd,WAAW,SAAS,CACpB,OAAO,MAAM,CACb,OAAO,YAAY,CACnB,MAAM,GAAG,EAAE;;AAKhB,SAAgB,UAAU,OAAkB,WAAW,IAAI;CACzD,MAAMC,SAAqD,EAAE;AAE7D,OAAM,SAAS,UAAe;AAC5B,MAAI,MAAM,OAAO;GAEf,MAAMC,SAAO,WAAW,MAAM,MAAM;GACpC,MAAM,UAAU,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC,KAAK,MACpD,EAAE,aAAa,CAChB;AACD,UAAO,KAAK;IAAE;IAAM;IAAS,CAAC;aACrB,MAAM,SAAS,YAAY,MAAM,OAAO,OAAO;GAExD,MAAM,aACJ,WACE,MAAM,OAAO,OACV,QAAQ,OAAO,GAAG,CAClB,QAAQ,iBAAiB,GAAG,CAC5B,QAAQ,SAAS,IAAI,CACrB,QAAQ,OAAO,GAAG,IAAI;AAC7B,UAAO,KAAK,GAAG,UAAU,MAAM,OAAO,OAAO,WAAW,CAAC;;GAE3D;AAEF,QAAO;;AAGT,SAAgB,WAAW,cAAsB;CAC/C,MAAM,gBAAgB,KAAK,KAAK,cAAc,UAAU;AAExD,KAAI,CAAC,GAAG,WAAW,cAAc,CAC/B,QAAO,EAAE;AAGX,QAAO,OAAO,YACZ,GACG,YAAY,cAAc,CAC1B,QAAQ,MAAM,KAAK,QAAQ,EAAE,KAAK,OAAO,CACzC,KAAK,MAAM,CAAC,KAAK,SAAS,GAAG,OAAO,EAAE,KAAK,SAAS,GAAG,OAAO,CAAC,CAAC,CACpE;;AAaH,SAAgB,iBACd,YAA6B,EAAE,EAChB;CACf,MAAM,eAAe,KAAK,KAAK,QAAQ,KAAK,EAAE,SAAS;AAEvD,QAAO;EACL,SAAS,QAAQ,IAAI,uBAAuB;EAC5C,SAAS,WAAW,aAAa;EACjC;EACD;;AAGH,SAAgB,gBAAgB,YAA6B,EAAE,EAAU;CACvE,MAAM,SAAS,iBAAiB,UAAU;AAE1C,QAAO;;4BAEmB,KAAK,UAAU,OAAO,CAAC"}

package/dist/server/vite-dev-server.js

@@ -0,0 +1,103 @@
+import { mergeConfigDedup } from "../utils/vite-config-merge.js";
+import { init_utils } from "../utils/index.js";
+import { BaseServer } from "./base-server.js";
+import { appKitTypesPlugin } from "../type-generator/vite-plugin.js";
+import path from "node:path";
+import fs from "node:fs";
+
+//#region src/server/vite-dev-server.ts
+init_utils();
+/**
+* Vite dev server for the AppKit.
+*
+* This class is responsible for serving the Vite dev server for the development server.
+* It also handles the index.html file for the development server.
+*
+* @example
+* ```ts
+* const viteDevServer = new ViteDevServer(app, endpoints);
+* await viteDevServer.setup();
+* ```
+*/
+var ViteDevServer = class extends BaseServer {
+	constructor(app, endpoints = {}) {
+		super(app, endpoints);
+		this.vite = null;
+	}
+	/**
+	* Setup the Vite dev server.
+	*
+	* This method sets up the Vite dev server and the index.html file for the development server.
+	*
+	* @returns
+	*/
+	async setup() {
+		const { createServer: createViteServer, loadConfigFromFile, mergeConfig } = await import("vite");
+		const react = await import("@vitejs/plugin-react");
+		const clientRoot = this.findClientRoot();
+		this.vite = await createViteServer(mergeConfigDedup((await loadConfigFromFile({
+			mode: "development",
+			command: "serve"
+		}, void 0, clientRoot))?.config ?? {}, {
+			configFile: false,
+			root: clientRoot,
+			server: {
+				middlewareMode: true,
+				watch: {
+					useFsEvents: true,
+					ignored: ["**/node_modules/**", "!**/node_modules/@databricks/**"]
+				}
+			},
+			plugins: [react.default(), appKitTypesPlugin()],
+			appType: "custom"
+		}, mergeConfig));
+		this.app.use(this.vite.middlewares);
+		this.app.use("*", async (req, res, next) => {
+			if (req.originalUrl.startsWith("/api") || req.originalUrl.startsWith("/query")) return next();
+			const vite = this.vite;
+			this.validateVite(vite);
+			try {
+				const indexPath = path.resolve(clientRoot, "index.html");
+				let html = fs.readFileSync(indexPath, "utf-8");
+				html = html.replace("<body>", `<body>${this.getConfigScript()}`);
+				html = await vite.transformIndexHtml(req.originalUrl, html);
+				res.status(200).set({ "Content-Type": "text/html" }).end(html);
+			} catch (e) {
+				vite.ssrFixStacktrace(e);
+				next(e);
+			}
+		});
+	}
+	/** Close the Vite dev server. */
+	async close() {
+		await this.vite?.close();
+	}
+	/** Find the client root. */
+	findClientRoot() {
+		const cwd = process.cwd();
+		const candidates = [
+			"client",
+			"src",
+			"app",
+			"frontend",
+			"."
+		];
+		for (const dir of candidates) {
+			const fullPath = path.resolve(cwd, dir);
+			const hasViteConfig = fs.existsSync(path.join(fullPath, "vite.config.ts")) || fs.existsSync(path.join(fullPath, "vite.config.js"));
+			const hasIndexHtml = fs.existsSync(path.join(fullPath, "index.html"));
+			if (hasViteConfig && hasIndexHtml) {
+				console.log(`Vite dev server: using client root ${fullPath}`);
+				return fullPath;
+			}
+		}
+		throw new Error(`Could not find client directory. Searched for vite.config.ts/js + index.html in: ${candidates.join(", ")}`);
+	}
+	validateVite(vite) {
+		if (!vite) throw new Error("Vite dev server not initialized");
+	}
+};
+
+//#endregion
+export { ViteDevServer };
+//# sourceMappingURL=vite-dev-server.js.map

package/dist/server/vite-dev-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-dev-server.js","names":[],"sources":["../../src/server/vite-dev-server.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport type express from \"express\";\nimport type { ViteDevServer as ViteDevServerType } from \"vite\";\nimport { mergeConfigDedup } from \"@/utils\";\nimport { BaseServer } from \"./base-server\";\nimport type { PluginEndpoints } from \"./utils\";\nimport { appKitTypesPlugin } from \"../type-generator/vite-plugin\";\n\n/**\n * Vite dev server for the AppKit.\n *\n * This class is responsible for serving the Vite dev server for the development server.\n * It also handles the index.html file for the development server.\n *\n * @example\n * ```ts\n * const viteDevServer = new ViteDevServer(app, endpoints);\n * await viteDevServer.setup();\n * ```\n */\nexport class ViteDevServer extends BaseServer {\n  private vite: ViteDevServerType | null;\n\n  constructor(app: express.Application, endpoints: PluginEndpoints = {}) {\n    super(app, endpoints);\n    this.vite = null;\n  }\n\n  /**\n   * Setup the Vite dev server.\n   *\n   * This method sets up the Vite dev server and the index.html file for the development server.\n   *\n   * @returns\n   */\n  async setup() {\n    const {\n      createServer: createViteServer,\n      loadConfigFromFile,\n      mergeConfig,\n    } = await import(\"vite\");\n    const react = await import(\"@vitejs/plugin-react\");\n\n    const clientRoot = this.findClientRoot();\n\n    const loadedConfig = await loadConfigFromFile(\n      {\n        mode: \"development\",\n        command: \"serve\",\n      },\n      undefined,\n      clientRoot,\n    );\n\n    const userConfig = loadedConfig?.config ?? {};\n    const coreConfig = {\n      configFile: false,\n      root: clientRoot,\n      server: {\n        middlewareMode: true,\n        watch: {\n          useFsEvents: true,\n          ignored: [\"**/node_modules/**\", \"!**/node_modules/@databricks/**\"],\n        },\n      },\n      plugins: [react.default(), appKitTypesPlugin()],\n      appType: \"custom\",\n    };\n\n    const mergedConfigs = mergeConfigDedup(userConfig, coreConfig, mergeConfig);\n    this.vite = await createViteServer(mergedConfigs);\n\n    this.app.use(this.vite.middlewares);\n\n    this.app.use(\"*\", async (req, res, next) => {\n      if (\n        req.originalUrl.startsWith(\"/api\") ||\n        req.originalUrl.startsWith(\"/query\")\n      ) {\n        return next();\n      }\n      const vite = this.vite;\n      this.validateVite(vite);\n\n      try {\n        const indexPath = path.resolve(clientRoot, \"index.html\");\n        let html = fs.readFileSync(indexPath, \"utf-8\");\n        html = html.replace(\"<body>\", `<body>${this.getConfigScript()}`);\n        html = await vite.transformIndexHtml(req.originalUrl, html);\n        res.status(200).set({ \"Content-Type\": \"text/html\" }).end(html);\n      } catch (e) {\n        vite.ssrFixStacktrace(e as Error);\n        next(e);\n      }\n    });\n  }\n\n  /** Close the Vite dev server. */\n  async close() {\n    await this.vite?.close();\n  }\n\n  /** Find the client root. */\n  private findClientRoot(): string {\n    const cwd = process.cwd();\n    const candidates = [\"client\", \"src\", \"app\", \"frontend\", \".\"];\n\n    for (const dir of candidates) {\n      const fullPath = path.resolve(cwd, dir);\n      const hasViteConfig =\n        fs.existsSync(path.join(fullPath, \"vite.config.ts\")) ||\n        fs.existsSync(path.join(fullPath, \"vite.config.js\"));\n      const hasIndexHtml = fs.existsSync(path.join(fullPath, \"index.html\"));\n\n      if (hasViteConfig && hasIndexHtml) {\n        console.log(`Vite dev server: using client root ${fullPath}`);\n        return fullPath;\n      }\n    }\n\n    throw new Error(\n      `Could not find client directory. Searched for vite.config.ts/js + index.html in: ${candidates.join(\", \")}`,\n    );\n  }\n\n  // type assertion to ensure vite is not null\n  private validateVite(\n    vite: ViteDevServerType | null,\n  ): asserts vite is ViteDevServerType {\n    if (!vite) {\n      throw new Error(\"Vite dev server not initialized\");\n    }\n  }\n}\n"],"mappings":";;;;;;;;YAI2C;;;;;;;;;;;;;AAiB3C,IAAa,gBAAb,cAAmC,WAAW;CAG5C,YAAY,KAA0B,YAA6B,EAAE,EAAE;AACrE,QAAM,KAAK,UAAU;AACrB,OAAK,OAAO;;;;;;;;;CAUd,MAAM,QAAQ;EACZ,MAAM,EACJ,cAAc,kBACd,oBACA,gBACE,MAAM,OAAO;EACjB,MAAM,QAAQ,MAAM,OAAO;EAE3B,MAAM,aAAa,KAAK,gBAAgB;AA2BxC,OAAK,OAAO,MAAM,iBADI,kBAxBD,MAAM,mBACzB;GACE,MAAM;GACN,SAAS;GACV,EACD,QACA,WACD,GAEgC,UAAU,EAAE,EAC1B;GACjB,YAAY;GACZ,MAAM;GACN,QAAQ;IACN,gBAAgB;IAChB,OAAO;KACL,aAAa;KACb,SAAS,CAAC,sBAAsB,kCAAkC;KACnE;IACF;GACD,SAAS,CAAC,MAAM,SAAS,EAAE,mBAAmB,CAAC;GAC/C,SAAS;GACV,EAE8D,YAAY,CAC1B;AAEjD,OAAK,IAAI,IAAI,KAAK,KAAK,YAAY;AAEnC,OAAK,IAAI,IAAI,KAAK,OAAO,KAAK,KAAK,SAAS;AAC1C,OACE,IAAI,YAAY,WAAW,OAAO,IAClC,IAAI,YAAY,WAAW,SAAS,CAEpC,QAAO,MAAM;GAEf,MAAM,OAAO,KAAK;AAClB,QAAK,aAAa,KAAK;AAEvB,OAAI;IACF,MAAM,YAAY,KAAK,QAAQ,YAAY,aAAa;IACxD,IAAI,OAAO,GAAG,aAAa,WAAW,QAAQ;AAC9C,WAAO,KAAK,QAAQ,UAAU,SAAS,KAAK,iBAAiB,GAAG;AAChE,WAAO,MAAM,KAAK,mBAAmB,IAAI,aAAa,KAAK;AAC3D,QAAI,OAAO,IAAI,CAAC,IAAI,EAAE,gBAAgB,aAAa,CAAC,CAAC,IAAI,KAAK;YACvD,GAAG;AACV,SAAK,iBAAiB,EAAW;AACjC,SAAK,EAAE;;IAET;;;CAIJ,MAAM,QAAQ;AACZ,QAAM,KAAK,MAAM,OAAO;;;CAI1B,AAAQ,iBAAyB;EAC/B,MAAM,MAAM,QAAQ,KAAK;EACzB,MAAM,aAAa;GAAC;GAAU;GAAO;GAAO;GAAY;GAAI;AAE5D,OAAK,MAAM,OAAO,YAAY;GAC5B,MAAM,WAAW,KAAK,QAAQ,KAAK,IAAI;GACvC,MAAM,gBACJ,GAAG,WAAW,KAAK,KAAK,UAAU,iBAAiB,CAAC,IACpD,GAAG,WAAW,KAAK,KAAK,UAAU,iBAAiB,CAAC;GACtD,MAAM,eAAe,GAAG,WAAW,KAAK,KAAK,UAAU,aAAa,CAAC;AAErE,OAAI,iBAAiB,cAAc;AACjC,YAAQ,IAAI,sCAAsC,WAAW;AAC7D,WAAO;;;AAIX,QAAM,IAAI,MACR,oFAAoF,WAAW,KAAK,KAAK,GAC1G;;CAIH,AAAQ,aACN,MACmC;AACnC,MAAI,CAAC,KACH,OAAM,IAAI,MAAM,kCAAkC"}

package/dist/shared/src/cache.d.ts

@@ -0,0 +1,62 @@
+import { TelemetryOptions } from "./plugin.js";
+
+//#region ../shared/src/cache.d.ts
+/** Cache entry interface */
+interface CacheEntry<T = any> {
+  value: T;
+  expiry: number;
+}
+/**
+ * Cache storage interface for custom implementations
+ * - InMemoryStorage
+ * - PersistentStorage (Lakebase)
+ */
+interface CacheStorage {
+  /** Get a cached value from the storage */
+  get<T>(key: string): Promise<CacheEntry<T> | null>;
+  /** Set a value in the storage */
+  set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+  /** Delete a value from the storage */
+  delete(key: string): Promise<void>;
+  /** Clear the storage */
+  clear(): Promise<void>;
+  /** Check if a value exists in the storage */
+  has(key: string): Promise<boolean>;
+  /** Get the size of the storage */
+  size(): Promise<number>;
+  /** Check if the storage is persistent */
+  isPersistent(): boolean;
+  /** Check if the storage is healthy */
+  healthCheck(): Promise<boolean>;
+  /** Close the storage */
+  close(): Promise<void>;
+}
+/** Configuration for caching */
+interface CacheConfig {
+  /** Whether caching is enabled */
+  enabled?: boolean;
+  /** Time to live in seconds */
+  ttl?: number;
+  /** Maximum number of bytes in the cache */
+  maxBytes?: number;
+  /** Maximum number of entries in the cache */
+  maxSize?: number;
+  /** Cache key */
+  cacheKey?: (string | number | object)[];
+  /** Cache Storage provider instance */
+  storage?: CacheStorage;
+  /** Whether to enforce strict persistence */
+  strictPersistence?: boolean;
+  /** Telemetry configuration */
+  telemetry?: TelemetryOptions;
+  /** Probability (0-1) of triggering cleanup on each get operation */
+  cleanupProbability?: number;
+  /** Probability (0-1) of checking total bytes on each write operation */
+  evictionCheckProbability?: number;
+  /** Maximum number of bytes per entry in the cache */
+  maxEntryBytes?: number;
+  [key: string]: unknown;
+}
+//#endregion
+export { CacheConfig };
+//# sourceMappingURL=cache.d.ts.map

package/dist/shared/src/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","names":[],"sources":["../../../../shared/src/cache.ts"],"sourcesContent":[],"mappings":";;;;UAGiB;EAAA,KAAA,EACR,CADQ;EAUA,MAAA,EAAA,MAAA;;;;;;;AAI4B,UAJ5B,YAAA,CAI4B;;KAIlC,CAAA,CAAA,CAAA,CAAA,GAAA,EAAA,MAAA,CAAA,EANY,OAMZ,CANoB,UAMpB,CAN+B,CAM/B,CAAA,GAAA,IAAA,CAAA;;KAID,CAAA,CAAA,CAAA,CAAA,GAAA,EAAA,MAAA,EAAA,KAAA,EARmB,UAQnB,CAR8B,CAQ9B,CAAA,CAAA,EARmC,OAQnC,CAAA,IAAA,CAAA;;QAMC,CAAA,GAAA,EAAA,MAAA,CAAA,EAZY,OAYZ,CAAA,IAAA,CAAA;EAAO;EAID,KAAA,EAAA,EAdN,OAciB,CAAA,IAAA,CAAA;EAAA;KAYhB,CAAA,GAAA,EAAA,MAAA,CAAA,EAxBQ,OAwBR,CAAA,OAAA,CAAA;;EAIkB,IAAA,EAAA,EA1BpB,OA0BoB,CAAA,MAAA,CAAA;;;;iBAtBb;;WAEN;;;UAIM,WAAA;;;;;;;;;;;;YAYL;;;;cAIE"}

package/dist/shared/src/execute.d.ts

@@ -0,0 +1,46 @@
+import { CacheConfig } from "./cache.js";
+
+//#region ../shared/src/execute.d.ts
+interface StreamConfig {
+  userSignal?: AbortSignal;
+  streamId?: string;
+  bufferSize?: number;
+  maxEventSize?: number;
+  bufferTTL?: number;
+  cleanupInterval?: number;
+  maxPersistentBuffers?: number;
+  heartbeatInterval?: number;
+  maxActiveStreams?: number;
+}
+interface RetryConfig {
+  enabled?: boolean;
+  attempts?: number;
+  initialDelay?: number;
+  maxDelay?: number;
+}
+interface TelemetryConfig {
+  enabled?: boolean;
+  spanName?: string;
+  attributes?: Record<string, any>;
+}
+interface PluginExecuteConfig {
+  cache?: CacheConfig;
+  retry?: RetryConfig;
+  telemetryInterceptor?: TelemetryConfig;
+  abort?: AbortSignal;
+  timeout?: number;
+  [key: string]: unknown;
+}
+interface PluginExecutionSettings {
+  default: PluginExecuteConfig;
+  user?: PluginExecuteConfig;
+}
+type StreamExecuteHandler<T> = ((signal?: AbortSignal) => Promise<T>) | ((signal?: AbortSignal) => AsyncGenerator<T, void, unknown>);
+interface StreamExecutionSettings {
+  default: PluginExecuteConfig;
+  user?: PluginExecuteConfig;
+  stream?: StreamConfig;
+}
+//#endregion
+export { PluginExecutionSettings, StreamConfig, StreamExecuteHandler, StreamExecutionSettings };
+//# sourceMappingURL=execute.d.ts.map

package/dist/shared/src/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","names":[],"sources":["../../../../shared/src/execute.ts"],"sourcesContent":[],"mappings":";;;UAEiB,YAAA;eACF;EADE,QAAA,CAAA,EAAA,MAAY;EAYZ,UAAA,CAAA,EAAA,MAAW;EAOX,YAAA,CAAA,EAAA,MAAe;EAMf,SAAA,CAAA,EAAA,MAAA;EAAmB,eAAA,CAAA,EAAA,MAAA;sBAC1B,CAAA,EAAA,MAAA;mBACA,CAAA,EAAA,MAAA;kBAEe,CAAA,EAAA,MAAA;;AACJ,UAlBJ,WAAA,CAkBI;EAKJ,OAAA,CAAA,EAAA,OAAA;EAAuB,QAAA,CAAA,EAAA,MAAA;cAC7B,CAAA,EAAA,MAAA;UACF,CAAA,EAAA,MAAA;;AAIG,UAtBK,eAAA,CAsBe;EAAA,OAAA,CAAA,EAAA,OAAA;UACjB,CAAA,EAAA,MAAA;YAAwB,CAAA,EApBxB,MAoBwB,CAAA,MAAA,EAAA,GAAA,CAAA;;AACxB,UAlBE,mBAAA,CAkBF;OAA+B,CAAA,EAjBpC,WAiBoC;OAAf,CAAA,EAhBrB,WAgBqB;EAAc,oBAAA,CAAA,EAdpB,eAcoB;EAE5B,KAAA,CAAA,EAfP,WAeO;EAAuB,OAAA,CAAA,EAAA,MAAA;MAC7B,EAAA,MAAA,CAAA,EAAA,OAAA;;AAEA,UAbM,uBAAA,CAaN;EAAY,OAAA,EAZZ,mBAYY;SAXd;;KAIG,qCACG,gBAAgB,QAAQ,iBACxB,gBAAgB,eAAe;UAE7B,uBAAA;WACN;SACF;WACE"}

package/dist/shared/src/plugin.d.ts

@@ -0,0 +1,50 @@
+import express from "express";
+
+//#region ../shared/src/plugin.d.ts
+interface BasePlugin {
+  name: string;
+  abortActiveOperations?(): void;
+  validateEnv(): void;
+  setup(): Promise<void>;
+  injectRoutes(router: express.Router): void;
+  getEndpoints(): PluginEndpointMap;
+}
+interface BasePluginConfig {
+  name?: string;
+  host?: string;
+  [key: string]: unknown;
+  telemetry?: TelemetryOptions;
+}
+type TelemetryOptions = boolean | {
+  traces?: boolean;
+  metrics?: boolean;
+  logs?: boolean;
+};
+type PluginPhase = "core" | "normal" | "deferred";
+type PluginConstructor<C = BasePluginConfig, I extends BasePlugin = BasePlugin> = (new (config: C) => I) & {
+  DEFAULT_CONFIG?: Record<string, unknown>;
+  phase?: PluginPhase;
+};
+type PluginMap<U extends readonly PluginData<PluginConstructor, unknown, string>[]> = { [P in U[number] as P["name"]]: InstanceType<P["plugin"]> };
+type PluginData<T, U, N> = {
+  plugin: T;
+  config: U;
+  name: N;
+};
+type ToPlugin<T, U, N extends string> = (config?: U) => PluginData<T, U, N>;
+type IAppRouter = express.Router;
+type IAppResponse = express.Response;
+type IAppRequest = express.Request;
+type HttpMethod = "get" | "post" | "put" | "delete" | "patch" | "head";
+type RouteConfig = {
+  /** Unique name for this endpoint (used for frontend access) */
+  name: string;
+  method: HttpMethod;
+  path: string;
+  handler: (req: IAppRequest, res: IAppResponse) => Promise<void>;
+};
+/** Map of endpoint names to their full paths for a plugin */
+type PluginEndpointMap = Record<string, string>;
+//#endregion
+export { BasePlugin, BasePluginConfig, IAppResponse, IAppRouter, PluginConstructor, PluginData, PluginEndpointMap, PluginMap, PluginPhase, RouteConfig, TelemetryOptions, ToPlugin };
+//# sourceMappingURL=plugin.d.ts.map

package/dist/shared/src/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../../shared/src/plugin.ts"],"sourcesContent":[],"mappings":";;;UAEiB,UAAA;;EAAA,qBAAU,GAAA,EAAA,IAAA;EAAA,WAAA,EAAA,EAAA,IAAA;OAOhB,EAAA,EAAA,OAAA,CAAA,IAAA,CAAA;cAEoB,CAAA,MAAA,EAAR,OAAA,CAAQ,MAAA,CAAA,EAAA,IAAA;cAEb,EAAA,EAAA,iBAAA;;AAGD,UAAA,gBAAA,CAUH;EAGF,IAAA,CAAA,EAAA,MAAA;EAaA,IAAA,CAAA,EAAA,MAAA;EAEA,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAiB;EAAA,SAAA,CAAA,EAlBf,gBAkBe;;AAEjB,KAjBA,gBAAA,GAiBA,OAAA,GAAA;QAAa,CAAA,EAAA,OAAA;SAEf,CAAA,EAAA,OAAA;MACL,CAAA,EAAA,OAAA;;AAkC2B,KAzCpB,WAAA,GAyCoB,MAAA,GAAA,QAAA,GAAA,UAAA;AAAX,KAvCT,iBAuCS,CAAA,IAtCf,gBAsCe,EAAA,UArCT,UAqCS,GArCI,UAqCJ,CAAA,GAAA,CAAA,KAAA,MAAA,EAnCX,CAmCW,EAAA,GAlChB,CAkCgB,CAAA,GAAA;gBAEb,CAAA,EAnCW,MAmCX,CAAA,MAAA,EAAA,OAAA,CAAA;OAAa,CAAA,EAlCX,WAkCW;;AAST,KAZA,SAYY,CAAA,UAAG,SAXN,UAWsB,CAXX,iBAWW,EAAA,OAAA,EAAA,MAAA,CAAA,EAAA,CAAA,GAAA,QATnC,CAUI,CAAA,MAAW,CAAA,IAVF,CAUE,CAAA,MAAG,CAAA,GAVO,YAUQ,CAVK,CAUL,CAAA,QAAA,CAAA,CAAA,EAEzC;AAEY,KAXA,UAWW,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,CAAA,GAAA;EAAA,MAAA,EAXqB,CAWrB;QAGb,EAd6C,CAc7C;MAEO,EAhB+C,CAgB/C;;AAAmC,KAfxC,QAewC,CAAA,CAAA,EAAA,CAAA,EAAA,UAAA,MAAA,CAAA,GAAA,CAAA,MAAA,CAAA,EAdzC,CAcyC,EAAA,GAb/C,UAa+C,CAbpC,CAaoC,EAbjC,CAaiC,EAb9B,CAa8B,CAAA;AAAO,KAX/C,UAAA,GAAa,OAAA,CAAQ,MAW0B;AAI/C,KAdA,YAAA,GAAe,OAAA,CAAQ,QAcG;KAb1B,WAAA,GAAc,OAAA,CAAQ;KAEtB,UAAA;KAEA,WAAA;;;UAGF;;iBAEO,kBAAkB,iBAAiB;;;KAIxC,iBAAA,GAAoB"}

package/dist/shared/src/sql/helpers.d.ts

@@ -0,0 +1,160 @@
+import { SQLBinaryMarker, SQLBooleanMarker, SQLDateMarker, SQLNumberMarker, SQLStringMarker, SQLTimestampMarker, SQLTypeMarker } from "./types.js";
+
+//#region ../shared/src/sql/helpers.d.ts
+
+/**
+ * SQL helper namespace
+ */
+declare const sql: {
+  /**
+   * Creates a DATE type parameter
+   * Accepts Date objects or ISO date strings (YYYY-MM-DD format)
+   * @param value - Date object or ISO date string
+   * @returns Marker object for DATE type parameter
+   * @example
+   * ```typescript
+   * const params = { startDate: sql.date(new Date("2024-01-01")) };
+   * params = { startDate: "2024-01-01" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { startDate: sql.date("2024-01-01") };
+   * params = { startDate: "2024-01-01" }
+   * ```
+   */
+  date(value: Date | string): SQLDateMarker;
+  /**
+   * Creates a TIMESTAMP type parameter
+   * Accepts Date objects, ISO timestamp strings, or Unix timestamp numbers
+   * @param value - Date object, ISO timestamp string, or Unix timestamp number
+   * @returns Marker object for TIMESTAMP type parameter
+   * @example
+   * ```typescript
+   * const params = { createdTime: sql.timestamp(new Date("2024-01-01T12:00:00Z")) };
+   * params = { createdTime: "2024-01-01T12:00:00Z" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { createdTime: sql.timestamp("2024-01-01T12:00:00Z") };
+   * params = { createdTime: "2024-01-01T12:00:00Z" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { createdTime: sql.timestamp(1704110400000) };
+   * params = { createdTime: "2024-01-01T12:00:00Z" }
+   * ```
+   */
+  timestamp(value: Date | string | number): SQLTimestampMarker;
+  /**
+   * Creates a NUMERIC type parameter
+   * Accepts numbers or numeric strings
+   * @param value - Number or numeric string
+   * @returns Marker object for NUMERIC type parameter
+   * @example
+   * ```typescript
+   * const params = { userId: sql.number(123) };
+   * params = { userId: "123" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { userId: sql.number("123") };
+   * params = { userId: "123" }
+   * ```
+   */
+  number(value: number | string): SQLNumberMarker;
+  /**
+   * Creates a STRING type parameter
+   * Accepts strings, numbers, or booleans
+   * @param value - String, number, or boolean
+   * @returns Marker object for STRING type parameter
+   * @example
+   * ```typescript
+   * const params = { name: sql.string("John") };
+   * params = { name: "John" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { name: sql.string(123) };
+   * params = { name: "123" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { name: sql.string(true) };
+   * params = { name: "true" }
+   * ```
+   */
+  string(value: string | number | boolean): SQLStringMarker;
+  /**
+   * Create a BOOLEAN type parameter
+   * Accepts booleans, strings, or numbers
+   * @param value - Boolean, string, or number
+   * @returns Marker object for BOOLEAN type parameter
+   * @example
+   * ```typescript
+   * const params = { isActive: sql.boolean(true) };
+   * params = { isActive: "true" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { isActive: sql.boolean("true") };
+   * params = { isActive: "true" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { isActive: sql.boolean(1) };
+   * params = { isActive: "true" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { isActive: sql.boolean("false") };
+   * params = { isActive: "false" }
+   * ```
+   * @example
+   * ```typescript
+   * const params = { isActive: sql.boolean(0) };
+   * params = { isActive: "false" }
+   * ```
+   * @returns
+   */
+  boolean(value: boolean | string | number): SQLBooleanMarker;
+  /**
+   * Creates a BINARY parameter as hex-encoded STRING
+   * Accepts Uint8Array, ArrayBuffer, or hex string
+   * Note: Databricks SQL Warehouse doesn't support BINARY as parameter type,
+   * so this helper returns a STRING with hex encoding. Use UNHEX(:param) in your SQL.
+   * @param value - Uint8Array, ArrayBuffer, or hex string
+   * @returns Marker object with STRING type and hex-encoded value
+   * @example
+   * ```typescript
+   * // From Uint8Array:
+   * const params = { data: sql.binary(new Uint8Array([0x53, 0x70, 0x61, 0x72, 0x6b])) };
+   * // Returns: { __sql_type: "STRING", value: "537061726B" }
+   * // SQL: SELECT UNHEX(:data) as binary_value
+   * ```
+   * @example
+   * ```typescript
+   * // From hex string:
+   * const params = { data: sql.binary("537061726B") };
+   * // Returns: { __sql_type: "STRING", value: "537061726B" }
+   * ```
+   */
+  binary(value: Uint8Array | ArrayBuffer | string): SQLBinaryMarker;
+};
+/**
+ * Type guard to check if a value is a SQL type marker
+ * @param value - Value to check
+ * @returns True if the value is a SQL type marker, false otherwise
+ * @example
+ * ```typescript
+ * const value = {
+ *   __sql_type: "DATE",
+ *   value: "2024-01-01",
+ * };
+ * const isSQLTypeMarker = isSQLTypeMarker(value);
+ * console.log(isSQLTypeMarker); // true
+ * ```
+ */
+declare function isSQLTypeMarker(value: any): value is SQLTypeMarker;
+//#endregion
+export { isSQLTypeMarker, sql };
+//# sourceMappingURL=helpers.d.ts.map

package/dist/shared/src/sql/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","names":[],"sources":["../../../../../shared/src/sql/helpers.ts"],"sourcesContent":[],"mappings":";;;;;;AAaA;AA0TC,cA1TY,GA0TZ,EAAA;;;;;;;;;;;;AAgBD;;;;;cAzTc,gBAAgB;;;;;;;;;;;;;;;;;;;;;;mBAmDX,yBAAyB;;;;;;;;;;;;;;;;;kCA6CV;;;;;;;;;;;;;;;;;;;;;;4CAkDU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6CAyDC;;;;;;;;;;;;;;;;;;;;;;gBA8D7B,aAAa,uBAAuB;;;;;;;;;;;;;;;;iBAgDpC,eAAA,uBAAsC"}

package/dist/shared/src/sql/helpers.js

@@ -0,0 +1,103 @@
+//#region ../shared/src/sql/helpers.ts
+/**
+* SQL helper namespace
+*/
+const sql = {
+	date(value) {
+		let dateValue = "";
+		if (value instanceof Date) dateValue = value.toISOString().split("T")[0];
+		else if (typeof value === "string") {
+			if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) throw new Error(`sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${value}`);
+			dateValue = value;
+		} else throw new Error(`sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${typeof value}`);
+		return {
+			__sql_type: "DATE",
+			value: dateValue
+		};
+	},
+	timestamp(value) {
+		let timestampValue = "";
+		if (value instanceof Date) timestampValue = value.toISOString().replace(/\.000(Z|[+-])/, "$1");
+		else if (typeof value === "string") {
+			if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})?$/.test(value)) throw new Error(`sql.timestamp() expects ISO timestamp string (YYYY-MM-DDTHH:MM:SS.mmmZ or YYYY-MM-DDTHH:MM:SS.mmm+HH:MM), got: ${value}`);
+			timestampValue = value;
+		} else if (typeof value === "number") timestampValue = new Date(value > 0xe8d4a51000 ? value : value * 1e3).toISOString().replace(/\.000(Z|[+-])/, "$1");
+		else throw new Error(`sql.timestamp() expects Date, ISO timestamp string, or Unix timestamp number, got: ${typeof value}`);
+		return {
+			__sql_type: "TIMESTAMP",
+			value: timestampValue
+		};
+	},
+	number(value) {
+		let numValue = "";
+		if (typeof value === "number") numValue = value.toString();
+		else if (typeof value === "string") {
+			if (value === "" || Number.isNaN(Number(value))) throw new Error(`sql.number() expects number or numeric string, got: ${value === "" ? "empty string" : value}`);
+			numValue = value;
+		} else throw new Error(`sql.number() expects number or numeric string, got: ${typeof value}`);
+		return {
+			__sql_type: "NUMERIC",
+			value: numValue
+		};
+	},
+	string(value) {
+		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") throw new Error(`sql.string() expects string or number or boolean, got: ${typeof value}`);
+		let stringValue = "";
+		if (typeof value === "string") stringValue = value;
+		else stringValue = value.toString();
+		return {
+			__sql_type: "STRING",
+			value: stringValue
+		};
+	},
+	boolean(value) {
+		if (typeof value !== "boolean" && typeof value !== "string" && typeof value !== "number") throw new Error(`sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${typeof value}`);
+		let booleanValue = "";
+		if (typeof value === "boolean") booleanValue = value.toString();
+		else if (typeof value === "number") {
+			if (value !== 1 && value !== 0) throw new Error(`sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`);
+			booleanValue = value === 1 ? "true" : "false";
+		} else if (typeof value === "string") {
+			if (value !== "true" && value !== "false") throw new Error(`sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`);
+			booleanValue = value;
+		}
+		return {
+			__sql_type: "BOOLEAN",
+			value: booleanValue
+		};
+	},
+	binary(value) {
+		let hexValue = "";
+		if (value instanceof Uint8Array) hexValue = Array.from(value).map((b) => b.toString(16).padStart(2, "0").toUpperCase()).join("");
+		else if (value instanceof ArrayBuffer) hexValue = Array.from(new Uint8Array(value)).map((b) => b.toString(16).padStart(2, "0").toUpperCase()).join("");
+		else if (typeof value === "string") {
+			if (!/^[0-9A-Fa-f]*$/.test(value)) throw new Error(`sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got invalid hex: ${value}`);
+			hexValue = value.toUpperCase();
+		} else throw new Error(`sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got: ${typeof value}`);
+		return {
+			__sql_type: "STRING",
+			value: hexValue
+		};
+	}
+};
+/**
+* Type guard to check if a value is a SQL type marker
+* @param value - Value to check
+* @returns True if the value is a SQL type marker, false otherwise
+* @example
+* ```typescript
+* const value = {
+*   __sql_type: "DATE",
+*   value: "2024-01-01",
+* };
+* const isSQLTypeMarker = isSQLTypeMarker(value);
+* console.log(isSQLTypeMarker); // true
+* ```
+*/
+function isSQLTypeMarker(value) {
+	return value !== null && typeof value === "object" && "__sql_type" in value && "value" in value && typeof value.__sql_type === "string" && typeof value.value === "string";
+}
+
+//#endregion
+export { isSQLTypeMarker, sql };
+//# sourceMappingURL=helpers.js.map

package/dist/shared/src/sql/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","names":["dateValue: string","timestampValue: string","numValue: string","stringValue: string","booleanValue: string","hexValue: string"],"sources":["../../../../../shared/src/sql/helpers.ts"],"sourcesContent":["import type {\n  SQLBinaryMarker,\n  SQLBooleanMarker,\n  SQLDateMarker,\n  SQLNumberMarker,\n  SQLStringMarker,\n  SQLTimestampMarker,\n  SQLTypeMarker,\n} from \"./types\";\n\n/**\n * SQL helper namespace\n */\nexport const sql = {\n  /**\n   * Creates a DATE type parameter\n   * Accepts Date objects or ISO date strings (YYYY-MM-DD format)\n   * @param value - Date object or ISO date string\n   * @returns Marker object for DATE type parameter\n   * @example\n   * ```typescript\n   * const params = { startDate: sql.date(new Date(\"2024-01-01\")) };\n   * params = { startDate: \"2024-01-01\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { startDate: sql.date(\"2024-01-01\") };\n   * params = { startDate: \"2024-01-01\" }\n   * ```\n   */\n  date(value: Date | string): SQLDateMarker {\n    let dateValue: string = \"\";\n\n    // check if value is a Date object\n    if (value instanceof Date) {\n      dateValue = value.toISOString().split(\"T\")[0];\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      // validate format\n      if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(value)) {\n        throw new Error(\n          `sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${value}`,\n        );\n      }\n      dateValue = value;\n    }\n    // if value is not a Date object or string, throw an error\n    else {\n      throw new Error(\n        `sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"DATE\",\n      value: dateValue,\n    };\n  },\n\n  /**\n   * Creates a TIMESTAMP type parameter\n   * Accepts Date objects, ISO timestamp strings, or Unix timestamp numbers\n   * @param value - Date object, ISO timestamp string, or Unix timestamp number\n   * @returns Marker object for TIMESTAMP type parameter\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(new Date(\"2024-01-01T12:00:00Z\")) };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(\"2024-01-01T12:00:00Z\") };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(1704110400000) };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   */\n  timestamp(value: Date | string | number): SQLTimestampMarker {\n    let timestampValue: string = \"\";\n\n    if (value instanceof Date) {\n      timestampValue = value.toISOString().replace(/\\.000(Z|[+-])/, \"$1\");\n    } else if (typeof value === \"string\") {\n      const isoRegex =\n        /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?(Z|[+-]\\d{2}:\\d{2})?$/;\n      if (!isoRegex.test(value)) {\n        throw new Error(\n          `sql.timestamp() expects ISO timestamp string (YYYY-MM-DDTHH:MM:SS.mmmZ or YYYY-MM-DDTHH:MM:SS.mmm+HH:MM), got: ${value}`,\n        );\n      }\n      timestampValue = value;\n    } else if (typeof value === \"number\") {\n      const date = new Date(value > 1e12 ? value : value * 1000);\n      timestampValue = date.toISOString().replace(/\\.000(Z|[+-])/, \"$1\");\n    } else {\n      throw new Error(\n        `sql.timestamp() expects Date, ISO timestamp string, or Unix timestamp number, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"TIMESTAMP\",\n      value: timestampValue,\n    };\n  },\n\n  /**\n   * Creates a NUMERIC type parameter\n   * Accepts numbers or numeric strings\n   * @param value - Number or numeric string\n   * @returns Marker object for NUMERIC type parameter\n   * @example\n   * ```typescript\n   * const params = { userId: sql.number(123) };\n   * params = { userId: \"123\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { userId: sql.number(\"123\") };\n   * params = { userId: \"123\" }\n   * ```\n   */\n  number(value: number | string): SQLNumberMarker {\n    let numValue: string = \"\";\n\n    // check if value is a number\n    if (typeof value === \"number\") {\n      numValue = value.toString();\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      if (value === \"\" || Number.isNaN(Number(value))) {\n        throw new Error(\n          `sql.number() expects number or numeric string, got: ${value === \"\" ? \"empty string\" : value}`,\n        );\n      }\n      numValue = value;\n    }\n    // if value is not a number or string, throw an error\n    else {\n      throw new Error(\n        `sql.number() expects number or numeric string, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"NUMERIC\",\n      value: numValue,\n    };\n  },\n\n  /**\n   * Creates a STRING type parameter\n   * Accepts strings, numbers, or booleans\n   * @param value - String, number, or boolean\n   * @returns Marker object for STRING type parameter\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(\"John\") };\n   * params = { name: \"John\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(123) };\n   * params = { name: \"123\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(true) };\n   * params = { name: \"true\" }\n   * ```\n   */\n  string(value: string | number | boolean): SQLStringMarker {\n    if (\n      typeof value !== \"string\" &&\n      typeof value !== \"number\" &&\n      typeof value !== \"boolean\"\n    ) {\n      throw new Error(\n        `sql.string() expects string or number or boolean, got: ${typeof value}`,\n      );\n    }\n\n    let stringValue: string = \"\";\n\n    if (typeof value === \"string\") {\n      stringValue = value;\n    } else {\n      stringValue = value.toString();\n    }\n\n    return {\n      __sql_type: \"STRING\",\n      value: stringValue,\n    };\n  },\n\n  /**\n   * Create a BOOLEAN type parameter\n   * Accepts booleans, strings, or numbers\n   * @param value - Boolean, string, or number\n   * @returns Marker object for BOOLEAN type parameter\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(true) };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(\"true\") };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(1) };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(\"false\") };\n   * params = { isActive: \"false\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(0) };\n   * params = { isActive: \"false\" }\n   * ```\n   * @returns\n   */\n  boolean(value: boolean | string | number): SQLBooleanMarker {\n    if (\n      typeof value !== \"boolean\" &&\n      typeof value !== \"string\" &&\n      typeof value !== \"number\"\n    ) {\n      throw new Error(\n        `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${typeof value}`,\n      );\n    }\n\n    let booleanValue: string = \"\";\n\n    if (typeof value === \"boolean\") {\n      booleanValue = value.toString();\n    }\n    // check if value is a number\n    else if (typeof value === \"number\") {\n      if (value !== 1 && value !== 0) {\n        throw new Error(\n          `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`,\n        );\n      }\n      booleanValue = value === 1 ? \"true\" : \"false\";\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      if (value !== \"true\" && value !== \"false\") {\n        throw new Error(\n          `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`,\n        );\n      }\n      booleanValue = value;\n    }\n\n    return {\n      __sql_type: \"BOOLEAN\",\n      value: booleanValue,\n    };\n  },\n\n  /**\n   * Creates a BINARY parameter as hex-encoded STRING\n   * Accepts Uint8Array, ArrayBuffer, or hex string\n   * Note: Databricks SQL Warehouse doesn't support BINARY as parameter type,\n   * so this helper returns a STRING with hex encoding. Use UNHEX(:param) in your SQL.\n   * @param value - Uint8Array, ArrayBuffer, or hex string\n   * @returns Marker object with STRING type and hex-encoded value\n   * @example\n   * ```typescript\n   * // From Uint8Array:\n   * const params = { data: sql.binary(new Uint8Array([0x53, 0x70, 0x61, 0x72, 0x6b])) };\n   * // Returns: { __sql_type: \"STRING\", value: \"537061726B\" }\n   * // SQL: SELECT UNHEX(:data) as binary_value\n   * ```\n   * @example\n   * ```typescript\n   * // From hex string:\n   * const params = { data: sql.binary(\"537061726B\") };\n   * // Returns: { __sql_type: \"STRING\", value: \"537061726B\" }\n   * ```\n   */\n  binary(value: Uint8Array | ArrayBuffer | string): SQLBinaryMarker {\n    let hexValue: string = \"\";\n\n    if (value instanceof Uint8Array) {\n      // if value is a Uint8Array, convert it to a hex string\n      hexValue = Array.from(value)\n        .map((b) => b.toString(16).padStart(2, \"0\").toUpperCase())\n        .join(\"\");\n    } else if (value instanceof ArrayBuffer) {\n      // if value is an ArrayBuffer, convert it to a hex string\n      hexValue = Array.from(new Uint8Array(value))\n        .map((b) => b.toString(16).padStart(2, \"0\").toUpperCase())\n        .join(\"\");\n    } else if (typeof value === \"string\") {\n      // validate hex string\n      if (!/^[0-9A-Fa-f]*$/.test(value)) {\n        throw new Error(\n          `sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got invalid hex: ${value}`,\n        );\n      }\n      hexValue = value.toUpperCase();\n    } else {\n      throw new Error(\n        `sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"STRING\",\n      value: hexValue,\n    };\n  },\n};\n\n/**\n * Type guard to check if a value is a SQL type marker\n * @param value - Value to check\n * @returns True if the value is a SQL type marker, false otherwise\n * @example\n * ```typescript\n * const value = {\n *   __sql_type: \"DATE\",\n *   value: \"2024-01-01\",\n * };\n * const isSQLTypeMarker = isSQLTypeMarker(value);\n * console.log(isSQLTypeMarker); // true\n * ```\n */\nexport function isSQLTypeMarker(value: any): value is SQLTypeMarker {\n  return (\n    value !== null &&\n    typeof value === \"object\" &&\n    \"__sql_type\" in value &&\n    \"value\" in value &&\n    typeof value.__sql_type === \"string\" &&\n    typeof value.value === \"string\"\n  );\n}\n"],"mappings":"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"}

package/dist/shared/src/sql/types.d.ts

@@ -0,0 +1,34 @@
+//#region ../shared/src/sql/types.d.ts
+interface SQLStringMarker {
+  __sql_type: "STRING";
+  value: string;
+}
+interface SQLNumberMarker {
+  __sql_type: "NUMERIC";
+  value: string;
+}
+interface SQLBooleanMarker {
+  __sql_type: "BOOLEAN";
+  value: string;
+}
+/**  SQL Binary marker is a STRING with hex encoding */
+interface SQLBinaryMarker {
+  __sql_type: "STRING";
+  value: string;
+}
+interface SQLDateMarker {
+  __sql_type: "DATE";
+  value: string;
+}
+interface SQLTimestampMarker {
+  __sql_type: "TIMESTAMP";
+  value: string;
+}
+/**
+ * Object that identifies a typed SQL parameter.
+ * Created using sql.date(), sql.string(), sql.number(), sql.boolean(), sql.timestamp(), sql.binary(), or sql.interval().
+ */
+type SQLTypeMarker = SQLStringMarker | SQLNumberMarker | SQLBooleanMarker | SQLBinaryMarker | SQLDateMarker | SQLTimestampMarker;
+//#endregion
+export { SQLBinaryMarker, SQLBooleanMarker, SQLDateMarker, SQLNumberMarker, SQLStringMarker, SQLTimestampMarker, SQLTypeMarker };
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/src/sql/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../../../shared/src/sql/types.ts"],"sourcesContent":[],"mappings":";UAAiB,eAAA;EAAA,UAAA,EAAA,QAAe;EAKf,KAAA,EAAA,MAAA;AAKjB;AAMiB,UAXA,eAAA,CAWe;EAKf,UAAA,EAAA,SAAa;EAKb,KAAA,EAAA,MAAA;AASjB;AAAyB,UAzBR,gBAAA,CAyBQ;YACrB,EAAA,SAAA;OACA,EAAA,MAAA;;;AAGA,UAxBa,eAAA,CAwBb;YACA,EAAA,QAAA;EAAkB,KAAA,EAAA,MAAA;;UApBL,aAAA;;;;UAKA,kBAAA;;;;;;;;KASL,aAAA,GACR,kBACA,kBACA,mBACA,kBACA,gBACA"}