@databricks/appkit-ui 0.44.0 → 0.45.0

package/dist/js/arrow/arrow-client.d.ts

@@ -8,9 +8,16 @@ declare class ArrowClient {
    * Lazily loads the Apache Arrow library on first use.
    *
    * @param buffer - The Arrow IPC format buffer
+   * @param columnNames - Optional real column names to relabel the schema
+   *   with. Databricks encodes ARROW_STREAM schemas positionally (`col_0`,
+   *   …); the analytics server sends the manifest names in a response header
+   *   so charts can look columns up by their real name. Relabels in-place by
+   *   rebuilding the Table around the existing vectors (no re-decode). A
+   *   no-op when the names already match, the count differs, or the names
+   *   aren't unique.
    * @returns Promise resolving to an Arrow Table
    */
-  static processArrowBuffer(buffer: Uint8Array): Promise<Table$1>;
+  static processArrowBuffer(buffer: Uint8Array, columnNames?: string[]): Promise<Table$1>;
   /**
    * Fetches Arrow data from a URL and processes it into a Table.
    * Convenience method that combines fetchArrow and processArrowBuffer.

package/dist/js/arrow/arrow-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arrow-client.d.ts","names":[],"sources":["../../../src/js/arrow/arrow-client.ts"],"mappings":";;;;cAmBa,WAAA;EAAW;;;;;;;EAAA,OAQT,kBAAA,CAAmB,MAAA,EAAQ,UAAA,GAAa,OAAA,CAAQ,OAAA;EAwD5B;;;;;;;;;;;;;EAAA,OA5BpB,oBAAA,CACX,GAAA,UACA,OAAA,GAAU,MAAA,mBACT,OAAA,CAAQ,OAAA;EA/BqB;;;;;;;;;;;EAAA,OAwDzB,kBAAA,CAAmB,KAAA,EAAO,OAAA;;;;EAqBC;;;;;;;;;;;;EAAA,OAA3B,mBAAA,CAAoB,KAAA,EAAO,OAAA,GAAQ,MAAA;EA8ExC;;;;;;;;;EAAA,OAvDK,gBAAA,CAAiB,KAAA,EAAO,OAAA,EAAO,IAAA,UAAc,KAAA;;cAyN1C,MAAA;EAAA;EAdmB;;;;;;;;;;;;;;;;;;EAAA,OArJtB,qBAAA,CACL,KAAA,EAAO,OAAA,EACP,WAAA,+BACC,cAAA;IAAmB,SAAA;EAAA;;;;;;;;;;;;;SAwHT,UAAA,CACX,GAAA,UACA,OAAA,GAAU,MAAA,mBACT,OAAA,CAAQ,UAAA;AAAA;AAAA,UAuBI,cAAA;;EAEf,MAAA;;EAEA,OAAA;AAAA"}
+{"version":3,"file":"arrow-client.d.ts","names":[],"sources":["../../../src/js/arrow/arrow-client.ts"],"mappings":";;;;cAmBa,WAAA;EAAW;;;;;;;;;;;;;;EAAA,OAeT,kBAAA,CACX,MAAA,EAAQ,UAAA,EACR,WAAA,cACC,OAAA,CAAQ,OAAA;EAuSC;;;;;;;;;;;;;EAAA,OA3PC,oBAAA,CACX,GAAA,UACA,OAAA,GAAU,MAAA,mBACT,OAAA,CAAQ,OAAA;EADT;;;;;;;;;;;EAAA,OA0BK,kBAAA,CAAmB,KAAA,EAAO,OAAA;;;;EA4CK;;;;;;;;;;;;EAAA,OAvB/B,mBAAA,CAAoB,KAAA,EAAO,OAAA,GAAQ,MAAA;EA0M9B;;;;;;AAwBd;;;EAxBc,OAnLL,gBAAA,CAAiB,KAAA,EAAO,OAAA,EAAO,IAAA,UAAc,KAAA;;cAyN1C,MAAA;EAAA;;;;;;;;;;;;;;;;;;;SAnKH,qBAAA,CACL,KAAA,EAAO,OAAA,EACP,WAAA,+BACC,cAAA;IAAmB,SAAA;EAAA;;;;;;;;;;;;;SAwHT,UAAA,CACX,GAAA,UACA,OAAA,GAAU,MAAA,mBACT,OAAA,CAAQ,UAAA;AAAA;AAAA,UAuBI,cAAA;;EAEf,MAAA;;EAEA,OAAA;AAAA"}

package/dist/js/arrow/arrow-client.js

@@ -8,13 +8,32 @@ var ArrowClient = class ArrowClient {
 	* Lazily loads the Apache Arrow library on first use.
 	*
 	* @param buffer - The Arrow IPC format buffer
+	* @param columnNames - Optional real column names to relabel the schema
+	*   with. Databricks encodes ARROW_STREAM schemas positionally (`col_0`,
+	*   …); the analytics server sends the manifest names in a response header
+	*   so charts can look columns up by their real name. Relabels in-place by
+	*   rebuilding the Table around the existing vectors (no re-decode). A
+	*   no-op when the names already match, the count differs, or the names
+	*   aren't unique.
 	* @returns Promise resolving to an Arrow Table
 	*/
-	static async processArrowBuffer(buffer) {
+	static async processArrowBuffer(buffer, columnNames) {
 		try {
 			const arrow = await getArrowModule();
 			await initializeTypeIdSets();
-			return arrow.tableFromIPC(buffer);
+			const table = arrow.tableFromIPC(buffer);
+			if (!columnNames || columnNames.length !== table.numCols) return table;
+			const fields = table.schema.fields;
+			const targetNames = columnNames.map((n, i) => n && n.length > 0 ? n : fields[i].name);
+			if (targetNames.every((n, i) => n === fields[i].name)) return table;
+			if (new Set(targetNames).size !== targetNames.length) return table;
+			const children = {};
+			for (let i = 0; i < fields.length; i++) {
+				const child = table.getChildAt(i);
+				if (!child) return table;
+				children[targetNames[i]] = child;
+			}
+			return new arrow.Table(children);
 		} catch (error) {
 			throw new Error(`Failed to process Arrow buffer: ${error instanceof Error ? error.message : "Unknown error"}`);
 		}

package/dist/js/arrow/arrow-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"arrow-client.js","names":[],"sources":["../../../src/js/arrow/arrow-client.ts"],"sourcesContent":["import type { Field, Table } from \"apache-arrow\";\nimport {\n  DATE_FIELD_PATTERNS,\n  METADATA_DATE_PATTERNS,\n  NAME_FIELD_PATTERNS,\n} from \"../constants\";\nimport {\n  getArrowModule,\n  getDecimalTypeId,\n  getTypeIdSets,\n  initializeTypeIdSets,\n} from \"./lazy-arrow\";\n\n// Re-export for backward compatibility\nexport { DATE_FIELD_PATTERNS, NAME_FIELD_PATTERNS };\n\n// Re-export Table type for consumers\nexport type { Table, Field };\n\nexport class ArrowClient {\n  /**\n   * Processes an Arrow IPC buffer into a Table.\n   * Lazily loads the Apache Arrow library on first use.\n   *\n   * @param buffer - The Arrow IPC format buffer\n   * @returns Promise resolving to an Arrow Table\n   */\n  static async processArrowBuffer(buffer: Uint8Array): Promise<Table> {\n    try {\n      const arrow = await getArrowModule();\n      // Initialize type ID sets now that Arrow is loaded\n      await initializeTypeIdSets();\n      return arrow.tableFromIPC(buffer);\n    } catch (error) {\n      throw new Error(\n        `Failed to process Arrow buffer: ${\n          error instanceof Error ? error.message : \"Unknown error\"\n        }`,\n      );\n    }\n  }\n\n  /**\n   * Fetches Arrow data from a URL and processes it into a Table.\n   * Convenience method that combines fetchArrow and processArrowBuffer.\n   *\n   * @param url - URL to fetch Arrow data from\n   * @param headers - Optional HTTP headers to include in the request\n   * @returns Promise resolving to an Arrow Table\n   * @example\n   * ```typescript\n   * const table = await ArrowClient.fetchAndProcessArrow('/api/data/arrow');\n   * console.log(`Loaded ${table.numRows} rows`);\n   * ```\n   */\n  static async fetchAndProcessArrow(\n    url: string,\n    headers?: Record<string, string>,\n  ): Promise<Table> {\n    try {\n      const buffer = await ArrowClient.fetchArrow(url, headers);\n\n      return ArrowClient.processArrowBuffer(buffer);\n    } catch (error) {\n      throw new Error(\n        `Failed to fetch Arrow data: ${\n          error instanceof Error ? error.message : \"Unknown error\"\n        }`,\n      );\n    }\n  }\n\n  /**\n   * Extracts field metadata (name and type) from an Arrow Table.\n   *\n   * @param table - Arrow Table to extract fields from\n   * @returns Array of field metadata objects\n   * @example\n   * ```typescript\n   * const fields = ArrowClient.extractArrowFields(table);\n   * // [{ name: \"date\", type: Date32 }, { name: \"value\", type: Float64 }]\n   * ```\n   */\n  static extractArrowFields(table: Table) {\n    return table.schema.fields.map((field: Field) => {\n      return {\n        name: field.name,\n        type: field.type,\n      };\n    });\n  }\n\n  /**\n   * Extracts all columns from an Arrow Table as JavaScript arrays.\n   * Each column is converted to a native JavaScript array.\n   *\n   * @param table - Arrow Table to extract columns from\n   * @returns Object mapping column names to arrays\n   * @example\n   * ```typescript\n   * const columns = ArrowClient.extractArrowColumns(table);\n   * // { date: [\"2024-01-01\", \"2024-01-02\"], value: [100, 200] }\n   * ```\n   */\n  static extractArrowColumns(table: Table): Record<string, any> {\n    const cols: Record<string, any> = {};\n\n    for (const field of table.schema.fields) {\n      const child = table.getChild(field.name);\n\n      if (child) {\n        cols[field.name] = child.toArray();\n      }\n    }\n\n    return cols;\n  }\n\n  /**\n   * Extracts chart data from Arrow table.\n   * Uses get(i) to properly handle complex types like Decimal128.\n   * Applies decimal scaling for DECIMAL types.\n   *\n   * Note: This method assumes Arrow has been loaded (via processArrowBuffer).\n   *\n   * @returns xData for axis, yDataMap for series data\n   */\n  static extractChartData(table: Table, xKey: string, yKeys: string[]) {\n    // Early exit for empty tables - return cached empty object\n    if (table.numRows === 0) {\n      return EMPTY_RESULT;\n    }\n\n    // Get the Decimal type ID (Arrow must be loaded to have a Table)\n    const decimalType = getDecimalTypeId();\n\n    // Build a map of field name -> pre-computed divisor (10^scale) for decimal types\n    const decimalDivisors = new Map<string, number>();\n    for (const field of table.schema.fields) {\n      if (field.typeId === decimalType) {\n        const decType = field.type as { scale: number };\n        if (typeof decType.scale === \"number\") {\n          // Pre-compute divisor once per field instead of per-column call\n          decimalDivisors.set(field.name, 10 ** decType.scale);\n        }\n      }\n    }\n\n    // Extract X column using proper value extraction\n    const xCol = table.getChild(xKey);\n    const xData = extractColumnValues(xCol, decimalDivisors.get(xKey));\n\n    // Extract Y columns using proper value extraction\n    const yDataMap: Record<string, (string | number)[]> = {};\n    for (let i = 0; i < yKeys.length; i++) {\n      const key = yKeys[i];\n      const col = table.getChild(key);\n      yDataMap[key] = extractColumnValues(col, decimalDivisors.get(key));\n    }\n\n    return { xData, yDataMap };\n  }\n\n  /**\n   * Automatically detect which fields to use for chart axes from an Arrow table\n   * Uses the schema's type information for accurate field detection\n   *\n   * Note: This method assumes Arrow has been loaded (via processArrowBuffer).\n   *\n   * @param table - Arrow Table to analyze\n   * @param orientation - Chart orientation (\"vertical\" for time-series, \"horizontal\" for categorical)\n   * @returns Object containing the detected fields\n   * @example\n   * // Time-series data\n   * detectFieldsFromArrow(timeSeriesTable)\n   * // { xField: \"date\", yFields: [\"revenue\", \"cost\"], chartType: \"timeseries\" }\n   *\n   * // Categorical data\n   * detectFieldsFromArrow(categoricalTable)\n   * // { xField: \"app_name\", yFields: [\"totalSpend\"], chartType: \"categorical\" }\n   */\n  static detectFieldsFromArrow(\n    table: Table,\n    orientation?: \"vertical\" | \"horizontal\",\n  ): DetectedFields & { chartType: \"timeseries\" | \"categorical\" } {\n    const fields = table.schema.fields;\n\n    if (fields.length === 0) {\n      return { xField: \"x\", yFields: [\"y\"], chartType: \"categorical\" };\n    }\n\n    const fieldNames = fields.map((f) => f.name);\n\n    // Get type ID sets (Arrow must be loaded to have a Table)\n    const typeIdSets = getTypeIdSets();\n\n    // Categorize fields by their Arrow type\n    const temporalFields: string[] = [];\n    const numericFields: string[] = [];\n    const stringFields: string[] = [];\n\n    for (const field of fields) {\n      const typeId = field.typeId;\n\n      if (typeIdSets.temporal.has(typeId)) {\n        temporalFields.push(field.name);\n      } else if (typeIdSets.numeric.has(typeId)) {\n        numericFields.push(field.name);\n      } else if (typeIdSets.string.has(typeId)) {\n        stringFields.push(field.name);\n      }\n    }\n\n    // Detect name/category fields: string fields matching name patterns\n    let nameFields = stringFields.filter((name) =>\n      NAME_FIELD_PATTERNS.some((pattern) =>\n        name.toLowerCase().includes(pattern),\n      ),\n    );\n\n    // Fallback: use any string field that doesn't end with _id\n    if (nameFields.length === 0) {\n      nameFields = stringFields.filter(\n        (name) => !name.toLowerCase().endsWith(\"_id\"),\n      );\n    }\n\n    // Separate temporal fields into \"chart-worthy\" dates vs metadata dates\n    const chartDateFields = temporalFields.filter(\n      (name) =>\n        !METADATA_DATE_PATTERNS.some((pattern) =>\n          name.toLowerCase().includes(pattern),\n        ),\n    );\n    const metadataDateFields = temporalFields.filter((name) =>\n      METADATA_DATE_PATTERNS.some((pattern) =>\n        name.toLowerCase().includes(pattern),\n      ),\n    );\n\n    // Also check string fields for date patterns (but not metadata patterns)\n    const stringDateFields = stringFields.filter(\n      (name) =>\n        DATE_FIELD_PATTERNS.some((pattern) =>\n          name.toLowerCase().includes(pattern),\n        ) &&\n        !METADATA_DATE_PATTERNS.some((pattern) =>\n          name.toLowerCase().includes(pattern),\n        ),\n    );\n\n    const primaryDateFields = [...chartDateFields, ...stringDateFields];\n\n    // Determine chart type: if we have good date fields for charting, it's time-series\n    // If we only have metadata dates (like createdAt) and name fields, it's categorical\n    const isTimeSeries =\n      primaryDateFields.length > 0 && orientation !== \"horizontal\";\n    const isCategorical =\n      nameFields.length > 0 &&\n      (primaryDateFields.length === 0 || orientation === \"horizontal\");\n\n    if (orientation === \"horizontal\" || isCategorical) {\n      // Categorical: x is name/category field, y is numeric field\n      const xField =\n        nameFields[0] ||\n        primaryDateFields[0] ||\n        metadataDateFields[0] ||\n        fieldNames[0];\n      const yFields =\n        numericFields.length > 0\n          ? numericFields\n          : fieldNames.filter((k) => k !== xField);\n      return { xField, yFields, chartType: \"categorical\" };\n    }\n\n    // Time-series (default): x is date/time field, y is numeric field\n    const xField =\n      primaryDateFields[0] ||\n      metadataDateFields[0] ||\n      nameFields[0] ||\n      fieldNames[0];\n    const yFields =\n      numericFields.length > 0\n        ? numericFields\n        : fieldNames.filter((k) => k !== xField);\n    return {\n      xField,\n      yFields,\n      chartType: isTimeSeries ? \"timeseries\" : \"categorical\",\n    };\n  }\n\n  /**\n   * Fetches raw Arrow IPC data from a URL.\n   *\n   * @param url - URL to fetch Arrow data from\n   * @param headers - Optional HTTP headers to include in the request\n   * @returns Promise resolving to the raw Arrow buffer as Uint8Array\n   * @example\n   * ```typescript\n   * const buffer = await ArrowClient.fetchArrow('/api/data/arrow');\n   * const table = await ArrowClient.processArrowBuffer(buffer);\n   * ```\n   */\n  static async fetchArrow(\n    url: string,\n    headers?: Record<string, string>,\n  ): Promise<Uint8Array> {\n    try {\n      const response = await fetch(url, {\n        headers: { \"Content-Type\": \"application/octet-stream\", ...headers },\n      });\n\n      if (!response.ok) {\n        throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n      }\n\n      const buffer = await response.arrayBuffer();\n\n      return new Uint8Array(buffer);\n    } catch (error) {\n      throw new Error(\n        `Failed to fetch Arrow data: ${\n          error instanceof Error ? error.message : \"Unknown error\"\n        }`,\n      );\n    }\n  }\n}\n\nexport interface DetectedFields {\n  /** X field */\n  xField: string;\n  /** Y fields */\n  yFields: string[];\n}\n\n// ============================================================================\n// Utility Functions\n// ============================================================================\n\n// Cached empty result to avoid allocations\nconst EMPTY_RESULT: {\n  xData: (string | number)[];\n  yDataMap: Record<string, (string | number)[]>;\n} = {\n  xData: [],\n  yDataMap: {},\n};\n\n/**\n * Extracts values from an Arrow Vector properly.\n * Uses get(i) to handle complex types like Decimal128 correctly.\n * toArray() doesn't work properly for Decimal types - it returns raw bytes.\n *\n * @param col - The Arrow column/vector\n * @param divisor - Pre-computed divisor for DECIMAL types (10^scale)\n */\nfunction extractColumnValues(\n  col: { length: number; get: (i: number) => unknown } | null | undefined,\n  divisor?: number,\n): (string | number)[] {\n  if (!col) return [];\n\n  // Pre-allocate array for better performance with large datasets\n  const len = col.length;\n  const result: (string | number)[] = new Array(len);\n\n  for (let i = 0; i < len; i++) {\n    const val = col.get(i);\n    if (val === null || val === undefined) {\n      result[i] = 0;\n    } else if (typeof val === \"bigint\") {\n      // Apply decimal scaling if needed\n      const num = Number(val);\n      result[i] = divisor !== undefined ? num / divisor : num;\n    } else if (typeof val === \"number\") {\n      // Apply decimal scaling if needed\n      result[i] = divisor !== undefined ? val / divisor : val;\n    } else if (typeof val === \"string\") {\n      result[i] = val;\n    } else {\n      // For complex types (like Decimal), try to convert to number\n      const num = Number(val);\n      result[i] = divisor !== undefined ? num / divisor : num;\n    }\n  }\n  return result;\n}\n"],"mappings":"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"}
+{"version":3,"file":"arrow-client.js","names":[],"sources":["../../../src/js/arrow/arrow-client.ts"],"sourcesContent":["import type { Field, Table, Vector } from \"apache-arrow\";\nimport {\n  DATE_FIELD_PATTERNS,\n  METADATA_DATE_PATTERNS,\n  NAME_FIELD_PATTERNS,\n} from \"../constants\";\nimport {\n  getArrowModule,\n  getDecimalTypeId,\n  getTypeIdSets,\n  initializeTypeIdSets,\n} from \"./lazy-arrow\";\n\n// Re-export for backward compatibility\nexport { DATE_FIELD_PATTERNS, NAME_FIELD_PATTERNS };\n\n// Re-export Table type for consumers\nexport type { Table, Field };\n\nexport class ArrowClient {\n  /**\n   * Processes an Arrow IPC buffer into a Table.\n   * Lazily loads the Apache Arrow library on first use.\n   *\n   * @param buffer - The Arrow IPC format buffer\n   * @param columnNames - Optional real column names to relabel the schema\n   *   with. Databricks encodes ARROW_STREAM schemas positionally (`col_0`,\n   *   …); the analytics server sends the manifest names in a response header\n   *   so charts can look columns up by their real name. Relabels in-place by\n   *   rebuilding the Table around the existing vectors (no re-decode). A\n   *   no-op when the names already match, the count differs, or the names\n   *   aren't unique.\n   * @returns Promise resolving to an Arrow Table\n   */\n  static async processArrowBuffer(\n    buffer: Uint8Array,\n    columnNames?: string[],\n  ): Promise<Table> {\n    try {\n      const arrow = await getArrowModule();\n      // Initialize type ID sets now that Arrow is loaded\n      await initializeTypeIdSets();\n      const table = arrow.tableFromIPC(buffer);\n\n      if (!columnNames || columnNames.length !== table.numCols) return table;\n      const fields = table.schema.fields;\n      const targetNames = columnNames.map((n, i) =>\n        n && n.length > 0 ? n : fields[i].name,\n      );\n      if (targetNames.every((n, i) => n === fields[i].name)) return table;\n      if (new Set(targetNames).size !== targetNames.length) return table;\n\n      const children: Record<string, Vector> = {};\n      for (let i = 0; i < fields.length; i++) {\n        const child = table.getChildAt(i);\n        if (!child) return table;\n        children[targetNames[i]] = child;\n      }\n      return new arrow.Table(children);\n    } catch (error) {\n      throw new Error(\n        `Failed to process Arrow buffer: ${\n          error instanceof Error ? error.message : \"Unknown error\"\n        }`,\n      );\n    }\n  }\n\n  /**\n   * Fetches Arrow data from a URL and processes it into a Table.\n   * Convenience method that combines fetchArrow and processArrowBuffer.\n   *\n   * @param url - URL to fetch Arrow data from\n   * @param headers - Optional HTTP headers to include in the request\n   * @returns Promise resolving to an Arrow Table\n   * @example\n   * ```typescript\n   * const table = await ArrowClient.fetchAndProcessArrow('/api/data/arrow');\n   * console.log(`Loaded ${table.numRows} rows`);\n   * ```\n   */\n  static async fetchAndProcessArrow(\n    url: string,\n    headers?: Record<string, string>,\n  ): Promise<Table> {\n    try {\n      const buffer = await ArrowClient.fetchArrow(url, headers);\n\n      return ArrowClient.processArrowBuffer(buffer);\n    } catch (error) {\n      throw new Error(\n        `Failed to fetch Arrow data: ${\n          error instanceof Error ? error.message : \"Unknown error\"\n        }`,\n      );\n    }\n  }\n\n  /**\n   * Extracts field metadata (name and type) from an Arrow Table.\n   *\n   * @param table - Arrow Table to extract fields from\n   * @returns Array of field metadata objects\n   * @example\n   * ```typescript\n   * const fields = ArrowClient.extractArrowFields(table);\n   * // [{ name: \"date\", type: Date32 }, { name: \"value\", type: Float64 }]\n   * ```\n   */\n  static extractArrowFields(table: Table) {\n    return table.schema.fields.map((field: Field) => {\n      return {\n        name: field.name,\n        type: field.type,\n      };\n    });\n  }\n\n  /**\n   * Extracts all columns from an Arrow Table as JavaScript arrays.\n   * Each column is converted to a native JavaScript array.\n   *\n   * @param table - Arrow Table to extract columns from\n   * @returns Object mapping column names to arrays\n   * @example\n   * ```typescript\n   * const columns = ArrowClient.extractArrowColumns(table);\n   * // { date: [\"2024-01-01\", \"2024-01-02\"], value: [100, 200] }\n   * ```\n   */\n  static extractArrowColumns(table: Table): Record<string, any> {\n    const cols: Record<string, any> = {};\n\n    for (const field of table.schema.fields) {\n      const child = table.getChild(field.name);\n\n      if (child) {\n        cols[field.name] = child.toArray();\n      }\n    }\n\n    return cols;\n  }\n\n  /**\n   * Extracts chart data from Arrow table.\n   * Uses get(i) to properly handle complex types like Decimal128.\n   * Applies decimal scaling for DECIMAL types.\n   *\n   * Note: This method assumes Arrow has been loaded (via processArrowBuffer).\n   *\n   * @returns xData for axis, yDataMap for series data\n   */\n  static extractChartData(table: Table, xKey: string, yKeys: string[]) {\n    // Early exit for empty tables - return cached empty object\n    if (table.numRows === 0) {\n      return EMPTY_RESULT;\n    }\n\n    // Get the Decimal type ID (Arrow must be loaded to have a Table)\n    const decimalType = getDecimalTypeId();\n\n    // Build a map of field name -> pre-computed divisor (10^scale) for decimal types\n    const decimalDivisors = new Map<string, number>();\n    for (const field of table.schema.fields) {\n      if (field.typeId === decimalType) {\n        const decType = field.type as { scale: number };\n        if (typeof decType.scale === \"number\") {\n          // Pre-compute divisor once per field instead of per-column call\n          decimalDivisors.set(field.name, 10 ** decType.scale);\n        }\n      }\n    }\n\n    // Extract X column using proper value extraction\n    const xCol = table.getChild(xKey);\n    const xData = extractColumnValues(xCol, decimalDivisors.get(xKey));\n\n    // Extract Y columns using proper value extraction\n    const yDataMap: Record<string, (string | number)[]> = {};\n    for (let i = 0; i < yKeys.length; i++) {\n      const key = yKeys[i];\n      const col = table.getChild(key);\n      yDataMap[key] = extractColumnValues(col, decimalDivisors.get(key));\n    }\n\n    return { xData, yDataMap };\n  }\n\n  /**\n   * Automatically detect which fields to use for chart axes from an Arrow table\n   * Uses the schema's type information for accurate field detection\n   *\n   * Note: This method assumes Arrow has been loaded (via processArrowBuffer).\n   *\n   * @param table - Arrow Table to analyze\n   * @param orientation - Chart orientation (\"vertical\" for time-series, \"horizontal\" for categorical)\n   * @returns Object containing the detected fields\n   * @example\n   * // Time-series data\n   * detectFieldsFromArrow(timeSeriesTable)\n   * // { xField: \"date\", yFields: [\"revenue\", \"cost\"], chartType: \"timeseries\" }\n   *\n   * // Categorical data\n   * detectFieldsFromArrow(categoricalTable)\n   * // { xField: \"app_name\", yFields: [\"totalSpend\"], chartType: \"categorical\" }\n   */\n  static detectFieldsFromArrow(\n    table: Table,\n    orientation?: \"vertical\" | \"horizontal\",\n  ): DetectedFields & { chartType: \"timeseries\" | \"categorical\" } {\n    const fields = table.schema.fields;\n\n    if (fields.length === 0) {\n      return { xField: \"x\", yFields: [\"y\"], chartType: \"categorical\" };\n    }\n\n    const fieldNames = fields.map((f) => f.name);\n\n    // Get type ID sets (Arrow must be loaded to have a Table)\n    const typeIdSets = getTypeIdSets();\n\n    // Categorize fields by their Arrow type\n    const temporalFields: string[] = [];\n    const numericFields: string[] = [];\n    const stringFields: string[] = [];\n\n    for (const field of fields) {\n      const typeId = field.typeId;\n\n      if (typeIdSets.temporal.has(typeId)) {\n        temporalFields.push(field.name);\n      } else if (typeIdSets.numeric.has(typeId)) {\n        numericFields.push(field.name);\n      } else if (typeIdSets.string.has(typeId)) {\n        stringFields.push(field.name);\n      }\n    }\n\n    // Detect name/category fields: string fields matching name patterns\n    let nameFields = stringFields.filter((name) =>\n      NAME_FIELD_PATTERNS.some((pattern) =>\n        name.toLowerCase().includes(pattern),\n      ),\n    );\n\n    // Fallback: use any string field that doesn't end with _id\n    if (nameFields.length === 0) {\n      nameFields = stringFields.filter(\n        (name) => !name.toLowerCase().endsWith(\"_id\"),\n      );\n    }\n\n    // Separate temporal fields into \"chart-worthy\" dates vs metadata dates\n    const chartDateFields = temporalFields.filter(\n      (name) =>\n        !METADATA_DATE_PATTERNS.some((pattern) =>\n          name.toLowerCase().includes(pattern),\n        ),\n    );\n    const metadataDateFields = temporalFields.filter((name) =>\n      METADATA_DATE_PATTERNS.some((pattern) =>\n        name.toLowerCase().includes(pattern),\n      ),\n    );\n\n    // Also check string fields for date patterns (but not metadata patterns)\n    const stringDateFields = stringFields.filter(\n      (name) =>\n        DATE_FIELD_PATTERNS.some((pattern) =>\n          name.toLowerCase().includes(pattern),\n        ) &&\n        !METADATA_DATE_PATTERNS.some((pattern) =>\n          name.toLowerCase().includes(pattern),\n        ),\n    );\n\n    const primaryDateFields = [...chartDateFields, ...stringDateFields];\n\n    // Determine chart type: if we have good date fields for charting, it's time-series\n    // If we only have metadata dates (like createdAt) and name fields, it's categorical\n    const isTimeSeries =\n      primaryDateFields.length > 0 && orientation !== \"horizontal\";\n    const isCategorical =\n      nameFields.length > 0 &&\n      (primaryDateFields.length === 0 || orientation === \"horizontal\");\n\n    if (orientation === \"horizontal\" || isCategorical) {\n      // Categorical: x is name/category field, y is numeric field\n      const xField =\n        nameFields[0] ||\n        primaryDateFields[0] ||\n        metadataDateFields[0] ||\n        fieldNames[0];\n      const yFields =\n        numericFields.length > 0\n          ? numericFields\n          : fieldNames.filter((k) => k !== xField);\n      return { xField, yFields, chartType: \"categorical\" };\n    }\n\n    // Time-series (default): x is date/time field, y is numeric field\n    const xField =\n      primaryDateFields[0] ||\n      metadataDateFields[0] ||\n      nameFields[0] ||\n      fieldNames[0];\n    const yFields =\n      numericFields.length > 0\n        ? numericFields\n        : fieldNames.filter((k) => k !== xField);\n    return {\n      xField,\n      yFields,\n      chartType: isTimeSeries ? \"timeseries\" : \"categorical\",\n    };\n  }\n\n  /**\n   * Fetches raw Arrow IPC data from a URL.\n   *\n   * @param url - URL to fetch Arrow data from\n   * @param headers - Optional HTTP headers to include in the request\n   * @returns Promise resolving to the raw Arrow buffer as Uint8Array\n   * @example\n   * ```typescript\n   * const buffer = await ArrowClient.fetchArrow('/api/data/arrow');\n   * const table = await ArrowClient.processArrowBuffer(buffer);\n   * ```\n   */\n  static async fetchArrow(\n    url: string,\n    headers?: Record<string, string>,\n  ): Promise<Uint8Array> {\n    try {\n      const response = await fetch(url, {\n        headers: { \"Content-Type\": \"application/octet-stream\", ...headers },\n      });\n\n      if (!response.ok) {\n        throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n      }\n\n      const buffer = await response.arrayBuffer();\n\n      return new Uint8Array(buffer);\n    } catch (error) {\n      throw new Error(\n        `Failed to fetch Arrow data: ${\n          error instanceof Error ? error.message : \"Unknown error\"\n        }`,\n      );\n    }\n  }\n}\n\nexport interface DetectedFields {\n  /** X field */\n  xField: string;\n  /** Y fields */\n  yFields: string[];\n}\n\n// ============================================================================\n// Utility Functions\n// ============================================================================\n\n// Cached empty result to avoid allocations\nconst EMPTY_RESULT: {\n  xData: (string | number)[];\n  yDataMap: Record<string, (string | number)[]>;\n} = {\n  xData: [],\n  yDataMap: {},\n};\n\n/**\n * Extracts values from an Arrow Vector properly.\n * Uses get(i) to handle complex types like Decimal128 correctly.\n * toArray() doesn't work properly for Decimal types - it returns raw bytes.\n *\n * @param col - The Arrow column/vector\n * @param divisor - Pre-computed divisor for DECIMAL types (10^scale)\n */\nfunction extractColumnValues(\n  col: { length: number; get: (i: number) => unknown } | null | undefined,\n  divisor?: number,\n): (string | number)[] {\n  if (!col) return [];\n\n  // Pre-allocate array for better performance with large datasets\n  const len = col.length;\n  const result: (string | number)[] = new Array(len);\n\n  for (let i = 0; i < len; i++) {\n    const val = col.get(i);\n    if (val === null || val === undefined) {\n      result[i] = 0;\n    } else if (typeof val === \"bigint\") {\n      // Apply decimal scaling if needed\n      const num = Number(val);\n      result[i] = divisor !== undefined ? num / divisor : num;\n    } else if (typeof val === \"number\") {\n      // Apply decimal scaling if needed\n      result[i] = divisor !== undefined ? val / divisor : val;\n    } else if (typeof val === \"string\") {\n      result[i] = val;\n    } else {\n      // For complex types (like Decimal), try to convert to number\n      const num = Number(val);\n      result[i] = divisor !== undefined ? num / divisor : num;\n    }\n  }\n  return result;\n}\n"],"mappings":";;;;AAmBA,IAAa,cAAb,MAAa,YAAY;;;;;;;;;;;;;;;CAevB,aAAa,mBACX,QACA,aACgB;AAChB,MAAI;GACF,MAAM,QAAQ,MAAM,gBAAgB;AAEpC,SAAM,sBAAsB;GAC5B,MAAM,QAAQ,MAAM,aAAa,OAAO;AAExC,OAAI,CAAC,eAAe,YAAY,WAAW,MAAM,QAAS,QAAO;GACjE,MAAM,SAAS,MAAM,OAAO;GAC5B,MAAM,cAAc,YAAY,KAAK,GAAG,MACtC,KAAK,EAAE,SAAS,IAAI,IAAI,OAAO,GAAG,KACnC;AACD,OAAI,YAAY,OAAO,GAAG,MAAM,MAAM,OAAO,GAAG,KAAK,CAAE,QAAO;AAC9D,OAAI,IAAI,IAAI,YAAY,CAAC,SAAS,YAAY,OAAQ,QAAO;GAE7D,MAAM,WAAmC,EAAE;AAC3C,QAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;IACtC,MAAM,QAAQ,MAAM,WAAW,EAAE;AACjC,QAAI,CAAC,MAAO,QAAO;AACnB,aAAS,YAAY,MAAM;;AAE7B,UAAO,IAAI,MAAM,MAAM,SAAS;WACzB,OAAO;AACd,SAAM,IAAI,MACR,mCACE,iBAAiB,QAAQ,MAAM,UAAU,kBAE5C;;;;;;;;;;;;;;;;CAiBL,aAAa,qBACX,KACA,SACgB;AAChB,MAAI;GACF,MAAM,SAAS,MAAM,YAAY,WAAW,KAAK,QAAQ;AAEzD,UAAO,YAAY,mBAAmB,OAAO;WACtC,OAAO;AACd,SAAM,IAAI,MACR,+BACE,iBAAiB,QAAQ,MAAM,UAAU,kBAE5C;;;;;;;;;;;;;;CAeL,OAAO,mBAAmB,OAAc;AACtC,SAAO,MAAM,OAAO,OAAO,KAAK,UAAiB;AAC/C,UAAO;IACL,MAAM,MAAM;IACZ,MAAM,MAAM;IACb;IACD;;;;;;;;;;;;;;CAeJ,OAAO,oBAAoB,OAAmC;EAC5D,MAAM,OAA4B,EAAE;AAEpC,OAAK,MAAM,SAAS,MAAM,OAAO,QAAQ;GACvC,MAAM,QAAQ,MAAM,SAAS,MAAM,KAAK;AAExC,OAAI,MACF,MAAK,MAAM,QAAQ,MAAM,SAAS;;AAItC,SAAO;;;;;;;;;;;CAYT,OAAO,iBAAiB,OAAc,MAAc,OAAiB;AAEnE,MAAI,MAAM,YAAY,EACpB,QAAO;EAIT,MAAM,cAAc,kBAAkB;EAGtC,MAAM,kCAAkB,IAAI,KAAqB;AACjD,OAAK,MAAM,SAAS,MAAM,OAAO,OAC/B,KAAI,MAAM,WAAW,aAAa;GAChC,MAAM,UAAU,MAAM;AACtB,OAAI,OAAO,QAAQ,UAAU,SAE3B,iBAAgB,IAAI,MAAM,MAAM,MAAM,QAAQ,MAAM;;EAO1D,MAAM,QAAQ,oBADD,MAAM,SAAS,KAAK,EACO,gBAAgB,IAAI,KAAK,CAAC;EAGlE,MAAM,WAAgD,EAAE;AACxD,OAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;GACrC,MAAM,MAAM,MAAM;AAElB,YAAS,OAAO,oBADJ,MAAM,SAAS,IAAI,EACU,gBAAgB,IAAI,IAAI,CAAC;;AAGpE,SAAO;GAAE;GAAO;GAAU;;;;;;;;;;;;;;;;;;;;CAqB5B,OAAO,sBACL,OACA,aAC8D;EAC9D,MAAM,SAAS,MAAM,OAAO;AAE5B,MAAI,OAAO,WAAW,EACpB,QAAO;GAAE,QAAQ;GAAK,SAAS,CAAC,IAAI;GAAE,WAAW;GAAe;EAGlE,MAAM,aAAa,OAAO,KAAK,MAAM,EAAE,KAAK;EAG5C,MAAM,aAAa,eAAe;EAGlC,MAAM,iBAA2B,EAAE;EACnC,MAAM,gBAA0B,EAAE;EAClC,MAAM,eAAyB,EAAE;AAEjC,OAAK,MAAM,SAAS,QAAQ;GAC1B,MAAM,SAAS,MAAM;AAErB,OAAI,WAAW,SAAS,IAAI,OAAO,CACjC,gBAAe,KAAK,MAAM,KAAK;YACtB,WAAW,QAAQ,IAAI,OAAO,CACvC,eAAc,KAAK,MAAM,KAAK;YACrB,WAAW,OAAO,IAAI,OAAO,CACtC,cAAa,KAAK,MAAM,KAAK;;EAKjC,IAAI,aAAa,aAAa,QAAQ,SACpC,oBAAoB,MAAM,YACxB,KAAK,aAAa,CAAC,SAAS,QAAQ,CACrC,CACF;AAGD,MAAI,WAAW,WAAW,EACxB,cAAa,aAAa,QACvB,SAAS,CAAC,KAAK,aAAa,CAAC,SAAS,MAAM,CAC9C;EAIH,MAAM,kBAAkB,eAAe,QACpC,SACC,CAAC,uBAAuB,MAAM,YAC5B,KAAK,aAAa,CAAC,SAAS,QAAQ,CACrC,CACJ;EACD,MAAM,qBAAqB,eAAe,QAAQ,SAChD,uBAAuB,MAAM,YAC3B,KAAK,aAAa,CAAC,SAAS,QAAQ,CACrC,CACF;EAGD,MAAM,mBAAmB,aAAa,QACnC,SACC,oBAAoB,MAAM,YACxB,KAAK,aAAa,CAAC,SAAS,QAAQ,CACrC,IACD,CAAC,uBAAuB,MAAM,YAC5B,KAAK,aAAa,CAAC,SAAS,QAAQ,CACrC,CACJ;EAED,MAAM,oBAAoB,CAAC,GAAG,iBAAiB,GAAG,iBAAiB;EAInE,MAAM,eACJ,kBAAkB,SAAS,KAAK,gBAAgB;EAClD,MAAM,gBACJ,WAAW,SAAS,MACnB,kBAAkB,WAAW,KAAK,gBAAgB;AAErD,MAAI,gBAAgB,gBAAgB,eAAe;GAEjD,MAAM,SACJ,WAAW,MACX,kBAAkB,MAClB,mBAAmB,MACnB,WAAW;AAKb,UAAO;IAAE;IAAQ,SAHf,cAAc,SAAS,IACnB,gBACA,WAAW,QAAQ,MAAM,MAAM,OAAO;IAClB,WAAW;IAAe;;EAItD,MAAM,SACJ,kBAAkB,MAClB,mBAAmB,MACnB,WAAW,MACX,WAAW;AAKb,SAAO;GACL;GACA,SALA,cAAc,SAAS,IACnB,gBACA,WAAW,QAAQ,MAAM,MAAM,OAAO;GAI1C,WAAW,eAAe,eAAe;GAC1C;;;;;;;;;;;;;;CAeH,aAAa,WACX,KACA,SACqB;AACrB,MAAI;GACF,MAAM,WAAW,MAAM,MAAM,KAAK,EAChC,SAAS;IAAE,gBAAgB;IAA4B,GAAG;IAAS,EACpE,CAAC;AAEF,OAAI,CAAC,SAAS,GACZ,OAAM,IAAI,MAAM,QAAQ,SAAS,OAAO,IAAI,SAAS,aAAa;GAGpE,MAAM,SAAS,MAAM,SAAS,aAAa;AAE3C,UAAO,IAAI,WAAW,OAAO;WACtB,OAAO;AACd,SAAM,IAAI,MACR,+BACE,iBAAiB,QAAQ,MAAM,UAAU,kBAE5C;;;;AAiBP,MAAM,eAGF;CACF,OAAO,EAAE;CACT,UAAU,EAAE;CACb;;;;;;;;;AAUD,SAAS,oBACP,KACA,SACqB;AACrB,KAAI,CAAC,IAAK,QAAO,EAAE;CAGnB,MAAM,MAAM,IAAI;CAChB,MAAM,SAA8B,IAAI,MAAM,IAAI;AAElD,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,KAAK;EAC5B,MAAM,MAAM,IAAI,IAAI,EAAE;AACtB,MAAI,QAAQ,QAAQ,QAAQ,OAC1B,QAAO,KAAK;WACH,OAAO,QAAQ,UAAU;GAElC,MAAM,MAAM,OAAO,IAAI;AACvB,UAAO,KAAK,YAAY,SAAY,MAAM,UAAU;aAC3C,OAAO,QAAQ,SAExB,QAAO,KAAK,YAAY,SAAY,MAAM,UAAU;WAC3C,OAAO,QAAQ,SACxB,QAAO,KAAK;OACP;GAEL,MAAM,MAAM,OAAO,IAAI;AACvB,UAAO,KAAK,YAAY,SAAY,MAAM,UAAU;;;AAGxD,QAAO"}

package/dist/js/sse/connect-sse.js

@@ -6,7 +6,7 @@
 * @returns Promise that resolves when the stream ends or retries stop
 */
 async function connectSSE(options, attempt = 0) {
-	const { url, payload, onMessage, signal, lastEventId: initialLastEventId = null, retryDelay = 2e3, maxRetries = 3, maxBufferSize = 1024 * 1024, timeout = 3e5, onError } = options;
+	const { url, payload, onMessage, signal, lastEventId: initialLastEventId = null, retryDelay = 2e3, maxRetries = 3, maxBufferSize = 1 * 1024 * 1024, timeout = 3e5, onError } = options;
 	if (!url || url.trim().length <= 0) throw new Error("connectSSE: 'url' must be a non-empty string.");
 	if (retryDelay <= 0) throw new Error("connectSSE: 'retryDelay' must be >= 0.");
 	if (maxBufferSize <= 0) throw new Error("connectSSE: 'maxBufferSize' must be > 0.");

package/dist/js/sse/connect-sse.js.map

@@ -1 +1 @@
-{"version":3,"file":"connect-sse.js","names":[],"sources":["../../../src/js/sse/connect-sse.ts"],"sourcesContent":["import type { ConnectSSEOptions, SSEMessage } from \"./types\";\n\n/**\n * Connects to an SSE endpoint with automatic retries and exponential backoff\n * @param options - SSE connection options\n * @param attempt - Internal retry attempt counter\n * @returns Promise that resolves when the stream ends or retries stop\n */\nexport async function connectSSE<Payload = unknown>(\n  options: ConnectSSEOptions<Payload>,\n  attempt = 0,\n) {\n  const {\n    url,\n    payload,\n    onMessage,\n    signal,\n    lastEventId: initialLastEventId = null,\n    retryDelay = 2000,\n    maxRetries = 3,\n    maxBufferSize = 1024 * 1024, // 1MB\n    timeout = 300000, // 5 minutes\n    onError,\n  } = options;\n\n  if (!url || url.trim().length <= 0) {\n    throw new Error(\"connectSSE: 'url' must be a non-empty string.\");\n  }\n\n  if (retryDelay <= 0) {\n    throw new Error(\"connectSSE: 'retryDelay' must be >= 0.\");\n  }\n  if (maxBufferSize <= 0) {\n    throw new Error(\"connectSSE: 'maxBufferSize' must be > 0.\");\n  }\n  const headers: HeadersInit = {\n    Accept: \"text/event-stream\",\n  };\n\n  const hasPayload = typeof payload !== \"undefined\";\n\n  if (hasPayload) {\n    headers[\"Content-Type\"] = \"application/json\";\n  }\n\n  let lastEventId = initialLastEventId;\n\n  if (lastEventId) {\n    headers[\"Last-Event-ID\"] = lastEventId;\n  }\n\n  const method = hasPayload ? \"POST\" : \"GET\";\n  const body = hasPayload\n    ? typeof payload === \"string\"\n      ? payload\n      : JSON.stringify(payload)\n    : undefined;\n\n  const timeoutController = new AbortController();\n  const timeoutId = setTimeout(() => timeoutController.abort(), timeout);\n\n  const combinedSignal = signal\n    ? createCombinedSignal(signal, timeoutController.signal)\n    : timeoutController.signal;\n\n  try {\n    const response = await fetch(url, {\n      headers,\n      method,\n      body,\n      signal: combinedSignal,\n    });\n\n    clearTimeout(timeoutId);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}`);\n    }\n\n    if (!response.body) {\n      throw new Error(\"No response body\");\n    }\n\n    const reader = response.body.getReader();\n    const decoder = new TextDecoder(\"utf-8\");\n\n    let buffer = \"\";\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n\n      const decoded = decoder.decode(value, { stream: true });\n\n      if (buffer.length + decoded.length > maxBufferSize) {\n        throw new Error(\"Buffer size exceeded\");\n      }\n      buffer += decoded;\n\n      const normalizedBuffer = buffer.replace(/\\r\\n/g, \"\\n\");\n      const parts = normalizedBuffer.split(\"\\n\\n\");\n\n      buffer = parts.pop() ?? \"\";\n      for (const part of parts) {\n        const message = parseSSEEvent(part);\n        if (!message) continue;\n\n        if (message.id) lastEventId = message.id;\n\n        onMessage({\n          id: lastEventId ?? \"\",\n          data: message.data,\n        });\n      }\n    }\n  } catch (error) {\n    clearTimeout(timeoutId);\n    if (onError) onError(error);\n    if (signal?.aborted) return;\n\n    if (attempt >= maxRetries) {\n      console.warn(\n        `[connectSSE] Max retries (${maxRetries}) exceeded for ${url}`,\n      );\n      return;\n    }\n\n    const nextAttempt = attempt + 1;\n    const delayMs = computeExponentialDelay(nextAttempt, retryDelay);\n\n    if (delayMs <= 0) return;\n\n    await new Promise<void>((resolve) => {\n      setTimeout(() => {\n        connectSSE({ ...options, lastEventId }, nextAttempt).finally(resolve);\n      }, delayMs);\n    });\n  }\n}\n\n/**\n * Parses a raw SSE event chunk into a message\n * @param chunk - Raw SSE event block\n * @returns Parsed message or null when no data lines are present\n * @private\n */\nfunction parseSSEEvent(chunk: string): SSEMessage | null {\n  const normalized = chunk.replace(/\\r\\n/g, \"\\n\");\n  const lines = normalized.split(\"\\n\");\n\n  let id: string | undefined;\n  const dataLines: string[] = [];\n\n  for (const rawLine of lines) {\n    const line = rawLine.trimEnd();\n\n    if (line === \"\") continue;\n    if (line.startsWith(\":\")) continue;\n\n    if (line.startsWith(\"id:\")) {\n      id = line.slice(3).trimStart();\n    } else if (line.startsWith(\"data:\")) {\n      dataLines.push(line.slice(5).trimStart());\n    }\n  }\n\n  if (dataLines.length === 0) return null;\n\n  return {\n    id: id ?? \"\",\n    data: dataLines.join(\"\\n\"),\n  };\n}\n\n/**\n * Compute exponential backoff delay in milliseconds.\n * Uses a random jitter factor to avoid thundering herd problem.\n * @param attempt - Retry attempt number (1-based)\n * @param baseDelayMs - Base delay in milliseconds\n * @returns Delay in milliseconds for this attempt\n */\nfunction computeExponentialDelay(attempt: number, baseDelayMs: number): number {\n  const safeAttempt = Math.max(1, attempt);\n  const multiplier = Math.min(2 ** (safeAttempt - 1), 32);\n  const rawDelayMs = baseDelayMs * multiplier;\n\n  const jitter = rawDelayMs * 0.2;\n  const randomizedDelayMs = rawDelayMs + Math.random() * jitter;\n\n  return Math.max(0, Math.floor(randomizedDelayMs));\n}\n\n/**\n * Combines two abort signals into a single abort signal\n * @param signal1 - First abort signal\n * @param signal2 - Second abort signal\n * @returns Combined signal\n */\nfunction createCombinedSignal(\n  signal1: AbortSignal,\n  signal2: AbortSignal,\n): AbortSignal {\n  const controller = new AbortController();\n  const abort = () => controller.abort();\n  signal1.addEventListener(\"abort\", abort);\n  signal2.addEventListener(\"abort\", abort);\n\n  return controller.signal;\n}\n"],"mappings":"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"}
+{"version":3,"file":"connect-sse.js","names":[],"sources":["../../../src/js/sse/connect-sse.ts"],"sourcesContent":["import type { ConnectSSEOptions, SSEMessage } from \"./types\";\n\n/**\n * Connects to an SSE endpoint with automatic retries and exponential backoff\n * @param options - SSE connection options\n * @param attempt - Internal retry attempt counter\n * @returns Promise that resolves when the stream ends or retries stop\n */\nexport async function connectSSE<Payload = unknown>(\n  options: ConnectSSEOptions<Payload>,\n  attempt = 0,\n) {\n  const {\n    url,\n    payload,\n    onMessage,\n    signal,\n    lastEventId: initialLastEventId = null,\n    retryDelay = 2000,\n    maxRetries = 3,\n    // 1 MiB — matches the server's `streamDefaults.maxEventSize`. SSE\n    // carries only short JSON control messages; bulk Arrow payloads stream\n    // back as the raw HTTP response body of the query request, so this\n    // buffer never needs to hold multi-MiB attachments.\n    maxBufferSize = 1 * 1024 * 1024,\n    timeout = 300000, // 5 minutes\n    onError,\n  } = options;\n\n  if (!url || url.trim().length <= 0) {\n    throw new Error(\"connectSSE: 'url' must be a non-empty string.\");\n  }\n\n  if (retryDelay <= 0) {\n    throw new Error(\"connectSSE: 'retryDelay' must be >= 0.\");\n  }\n  if (maxBufferSize <= 0) {\n    throw new Error(\"connectSSE: 'maxBufferSize' must be > 0.\");\n  }\n  const headers: HeadersInit = {\n    Accept: \"text/event-stream\",\n  };\n\n  const hasPayload = typeof payload !== \"undefined\";\n\n  if (hasPayload) {\n    headers[\"Content-Type\"] = \"application/json\";\n  }\n\n  let lastEventId = initialLastEventId;\n\n  if (lastEventId) {\n    headers[\"Last-Event-ID\"] = lastEventId;\n  }\n\n  const method = hasPayload ? \"POST\" : \"GET\";\n  const body = hasPayload\n    ? typeof payload === \"string\"\n      ? payload\n      : JSON.stringify(payload)\n    : undefined;\n\n  const timeoutController = new AbortController();\n  const timeoutId = setTimeout(() => timeoutController.abort(), timeout);\n\n  const combinedSignal = signal\n    ? createCombinedSignal(signal, timeoutController.signal)\n    : timeoutController.signal;\n\n  try {\n    const response = await fetch(url, {\n      headers,\n      method,\n      body,\n      signal: combinedSignal,\n    });\n\n    clearTimeout(timeoutId);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}`);\n    }\n\n    if (!response.body) {\n      throw new Error(\"No response body\");\n    }\n\n    const reader = response.body.getReader();\n    const decoder = new TextDecoder(\"utf-8\");\n\n    let buffer = \"\";\n    while (true) {\n      const { done, value } = await reader.read();\n      if (done) break;\n\n      const decoded = decoder.decode(value, { stream: true });\n\n      if (buffer.length + decoded.length > maxBufferSize) {\n        throw new Error(\"Buffer size exceeded\");\n      }\n      buffer += decoded;\n\n      const normalizedBuffer = buffer.replace(/\\r\\n/g, \"\\n\");\n      const parts = normalizedBuffer.split(\"\\n\\n\");\n\n      buffer = parts.pop() ?? \"\";\n      for (const part of parts) {\n        const message = parseSSEEvent(part);\n        if (!message) continue;\n\n        if (message.id) lastEventId = message.id;\n\n        onMessage({\n          id: lastEventId ?? \"\",\n          data: message.data,\n        });\n      }\n    }\n  } catch (error) {\n    clearTimeout(timeoutId);\n    if (onError) onError(error);\n    if (signal?.aborted) return;\n\n    if (attempt >= maxRetries) {\n      console.warn(\n        `[connectSSE] Max retries (${maxRetries}) exceeded for ${url}`,\n      );\n      return;\n    }\n\n    const nextAttempt = attempt + 1;\n    const delayMs = computeExponentialDelay(nextAttempt, retryDelay);\n\n    if (delayMs <= 0) return;\n\n    await new Promise<void>((resolve) => {\n      setTimeout(() => {\n        connectSSE({ ...options, lastEventId }, nextAttempt).finally(resolve);\n      }, delayMs);\n    });\n  }\n}\n\n/**\n * Parses a raw SSE event chunk into a message\n * @param chunk - Raw SSE event block\n * @returns Parsed message or null when no data lines are present\n * @private\n */\nfunction parseSSEEvent(chunk: string): SSEMessage | null {\n  const normalized = chunk.replace(/\\r\\n/g, \"\\n\");\n  const lines = normalized.split(\"\\n\");\n\n  let id: string | undefined;\n  const dataLines: string[] = [];\n\n  for (const rawLine of lines) {\n    const line = rawLine.trimEnd();\n\n    if (line === \"\") continue;\n    if (line.startsWith(\":\")) continue;\n\n    if (line.startsWith(\"id:\")) {\n      id = line.slice(3).trimStart();\n    } else if (line.startsWith(\"data:\")) {\n      dataLines.push(line.slice(5).trimStart());\n    }\n  }\n\n  if (dataLines.length === 0) return null;\n\n  return {\n    id: id ?? \"\",\n    data: dataLines.join(\"\\n\"),\n  };\n}\n\n/**\n * Compute exponential backoff delay in milliseconds.\n * Uses a random jitter factor to avoid thundering herd problem.\n * @param attempt - Retry attempt number (1-based)\n * @param baseDelayMs - Base delay in milliseconds\n * @returns Delay in milliseconds for this attempt\n */\nfunction computeExponentialDelay(attempt: number, baseDelayMs: number): number {\n  const safeAttempt = Math.max(1, attempt);\n  const multiplier = Math.min(2 ** (safeAttempt - 1), 32);\n  const rawDelayMs = baseDelayMs * multiplier;\n\n  const jitter = rawDelayMs * 0.2;\n  const randomizedDelayMs = rawDelayMs + Math.random() * jitter;\n\n  return Math.max(0, Math.floor(randomizedDelayMs));\n}\n\n/**\n * Combines two abort signals into a single abort signal\n * @param signal1 - First abort signal\n * @param signal2 - Second abort signal\n * @returns Combined signal\n */\nfunction createCombinedSignal(\n  signal1: AbortSignal,\n  signal2: AbortSignal,\n): AbortSignal {\n  const controller = new AbortController();\n  const abort = () => controller.abort();\n  signal1.addEventListener(\"abort\", abort);\n  signal2.addEventListener(\"abort\", abort);\n\n  return controller.signal;\n}\n"],"mappings":"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"}

package/dist/react/charts/types.d.ts

@@ -1,8 +1,15 @@
 import { Table } from "apache-arrow";
 
 //#region src/react/charts/types.d.ts
-/** Supported data formats for analytics queries */
-type DataFormat = "json" | "arrow" | "auto";
+/**
+ * Supported data formats for analytics queries.
+ *
+ * "json" and "arrow" are legacy aliases kept for backwards compatibility
+ * with appkit-ui < 0.33.0 — safe to remove once no consumer is on a
+ * pre-0.33.0 version. resolveFormat() normalizes them to their canonical
+ * equivalents before any downstream code reads the value.
+ */
+type DataFormat = "json_array" | "arrow_stream" | "auto" /** @deprecated Use "json_array". Safe to remove once no consumer is on appkit-ui < 0.33.0. */ | "json" /** @deprecated Use "arrow_stream". Safe to remove once no consumer is on appkit-ui < 0.33.0. */ | "arrow";
 /** Chart orientation */
 type Orientation = "vertical" | "horizontal";
 /** Supported chart types */
@@ -60,8 +67,8 @@ interface QueryProps extends ChartBaseProps {
   parameters?: Record<string, unknown>;
   /**
    * Data format to use
-   * - "json": Use JSON format (smaller payloads, simpler)
-   * - "arrow": Use Arrow format (faster for large datasets)
+   * - "json_array": Use JSON format (smaller payloads, simpler)
+   * - "arrow_stream": Use Arrow format (faster for large datasets)
    * - "auto": Automatically select based on expected data size
    * @default "auto"
    */

package/dist/react/charts/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/charts/types.ts"],"mappings":";;;;KAOY,UAAA;AAAZ;AAAA,KAGY,WAAA;;KAGA,SAAA;;KAWA,SAAA,GAAY,KAAA,GAAQ,MAAA;;KAOpB,iBAAA;;UAGK,aAAA;EArBL;EAuBV,SAAA;;EAEA,SAAA;EAzBmB;EA2BnB,IAAA;EAhBmB;EAkBnB,SAAA;AAAA;;UAIe,cAAA;EAfY;EAiB3B,KAAA;EAjB2B;EAmB3B,UAAA;EAhBe;;;;;;EAuBf,YAAA,GAAe,iBAAA;EAff;EAiBA,MAAA;EAjBS;EAmBT,MAAA;EAf6B;EAiB7B,SAAA;EAagB;EAVhB,IAAA;EAhBA;EAkBA,IAAA;EAXe;EAcf,SAAA;EAVA;EAYA,MAAA;EAPA;EAUA,OAAA,GAAU,MAAA;AAAA;;UAQK,UAAA,SAAmB,cAAA;EARxB;EAUV,QAAA;EAVgB;EAYhB,UAAA,GAAa,MAAA;EAJa;;;;;;;EAY1B,MAAA,GAAS,UAAA;EAZuC;EAchD,WAAA,OAAkB,IAAA,EAAM,CAAA,KAAM,CAAA;EAE9B,IAAA;AAAA;;UAQe,SAAA,SAAkB,cAAA;EAZxB;EAcT,IAAA,EAAM,SAAA;EAGN,QAAA;EACA,UAAA;EACA,MAAA;EACA,WAAA;AAAA;;KAQU,iBAAA,GAAoB,UAAA,GAAa,SAAA;AAhB7C;AAAA,UAuBiB,qBAAA;;EAEf,WAAA,GAAc,WAAA;EAzBmB;EA2BjC,OAAA;AAAA;;UAIe,sBAAA;EAxBf;EA0BA,WAAA,GAAc,WAAA;EAzBH;EA2BX,UAAA;EAnBU;EAqBV,MAAA;AAAA;;UAIe,sBAAA;EAlBA;EAoBf,WAAA,GAAc,WAAA;;EAEd,UAAA;EApBA;EAsBA,MAAA;EApBA;EAsBA,OAAA;AAAA;AAlBF;AAAA,UAsBiB,yBAAA;;EAEf,UAAA;AAAA;;UAIe,qBAAA;EAtBf;EAwBA,WAAA;EAxBM;EA0BN,UAAA;EAtBqC;EAwBrC,aAAA;AAAA;;UAIe,uBAAA;EAxBf;EA0BA,QAAA;AAAA;;UAIe,yBAAA;EAtBA;;;;EA2Bf,QAAA;EArBe;EAuBf,GAAA;;EAEA,GAAA;EAvBA;EAyBA,UAAA;AAAA;AAAA,KAOU,aAAA,IAAiB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC3C,cAAA,IAAkB,UAAA,GAAa,SAAA,IAAa,sBAAA;AAAA,KAC5C,cAAA,IAAkB,UAAA,GAAa,SAAA,IAAa,sBAAA;AAAA,KAC5C,iBAAA,IAAqB,UAAA,GAAa,SAAA,IAC5C,yBAAA;AAAA,KACU,aAAA,IAAiB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC3C,eAAA,IAAmB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC7C,eAAA,IAAmB,UAAA,GAAa,SAAA,IAC1C,uBAAA;AAAA,KACU,iBAAA,IAAqB,UAAA,GAAa,SAAA,IAC5C,yBAAA;;UAOe,uBAAA;EACf,KAAA;EACA,MAAA;EACA,OAAA;EACA,SAAA;AAAA;;UAIe,mBAAA,SAA4B,uBAAA;EAC3C,QAAA,EAAU,MAAA;AAAA;;iBAII,YAAA,CAAa,IAAA,EAAM,SAAA,GAAY,IAAA,IAAQ,KAAA;;iBAWvC,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,UAAA;;iBASjD,WAAA,CAAY,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,SAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/charts/types.ts"],"mappings":";;;;;AAcA;;;;;AAUA;KAVY,UAAA;;KAUA,WAAA;;KAGA,SAAA;AAWZ;AAAA,KAAY,SAAA,GAAY,KAAA,GAAQ,MAAA;;KAOpB,iBAAA;;UAGK,aAAA;EAHY;EAK3B,SAAA;EAL2B;EAO3B,SAAA;EAJe;EAMf,IAAA;;EAEA,SAAA;AAAA;;UAIe,cAAA;EAJf;EAMA,KAAA;EANS;EAQT,UAAA;EAJ6B;;;;;;EAW7B,YAAA,GAAe,iBAAA;EAEf;EAAA,MAAA;EAIA;EAFA,MAAA;EAOA;EALA,SAAA;EAUA;EAPA,IAAA;EAUU;EARV,IAAA;EAQgB;EALhB,SAAA;EAa0B;EAX1B,MAAA;EAea;EAZb,OAAA,GAAU,MAAA;AAAA;;UAQK,UAAA,SAAmB,cAAA;EAAc;EAEhD,QAAA;EAFkC;EAIlC,UAAA,GAAa,MAAA;EAAb;;;;;;;EAQA,MAAA,GAAS,UAAA;EAEqB;EAA9B,WAAA,OAAkB,IAAA,EAAM,CAAA,KAAM,CAAA;EAE9B,IAAA;AAAA;AAQF;AAAA,UAAiB,SAAA,SAAkB,cAAA;;EAEjC,IAAA,EAAM,SAAA;EAGN,QAAA;EACA,UAAA;EACA,MAAA;EACA,WAAA;AAAA;;KAQU,iBAAA,GAAoB,UAAA,GAAa,SAAA;;UAO5B,qBAAA;EAPL;EASV,WAAA,GAAc,WAAA;;EAEd,OAAA;AAAA;AAJF;AAAA,UAQiB,sBAAA;;EAEf,WAAA,GAAc,WAAA;EARd;EAUA,UAAA;EARA;EAUA,MAAA;AAAA;AANF;AAAA,UAUiB,sBAAA;;EAEf,WAAA,GAAc,WAAA;EAVd;EAYA,UAAA;EAVA;EAYA,MAAA;EAVM;EAYN,OAAA;AAAA;;UAIe,yBAAA;EAVU;EAYzB,UAAA;AAAA;;UAIe,qBAAA;EAVf;EAYA,WAAA;EAZO;EAcP,UAAA;EAVwC;EAYxC,aAAA;AAAA;;UAIe,uBAAA;EAVqB;EAYpC,QAAA;AAAA;;UAIe,yBAAA;EAVf;;;AAIF;EAWE,QAAA;;EAEA,GAAA;EAXQ;EAaR,GAAA;EATwC;EAWxC,UAAA;AAAA;AAAA,KAOU,aAAA,IAAiB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC3C,cAAA,IAAkB,UAAA,GAAa,SAAA,IAAa,sBAAA;AAAA,KAC5C,cAAA,IAAkB,UAAA,GAAa,SAAA,IAAa,sBAAA;AAAA,KAC5C,iBAAA,IAAqB,UAAA,GAAa,SAAA,IAC5C,yBAAA;AAAA,KACU,aAAA,IAAiB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC3C,eAAA,IAAmB,UAAA,GAAa,SAAA,IAAa,qBAAA;AAAA,KAC7C,eAAA,IAAmB,UAAA,GAAa,SAAA,IAC1C,uBAAA;AAAA,KACU,iBAAA,IAAqB,UAAA,GAAa,SAAA,IAC5C,yBAAA;;UAOe,uBAAA;EACf,KAAA;EACA,MAAA;EACA,OAAA;EACA,SAAA;AAAA;;UAIe,mBAAA,SAA4B,uBAAA;EAC3C,QAAA,EAAU,MAAA;AAAA;AAzBZ;AAAA,iBA6BgB,YAAA,CAAa,IAAA,EAAM,SAAA,GAAY,IAAA,IAAQ,KAAA;;iBAWvC,YAAA,CAAa,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,UAAA;;iBASjD,WAAA,CAAY,KAAA,EAAO,iBAAA,GAAoB,KAAA,IAAS,SAAA"}

package/dist/react/charts/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../src/react/charts/types.ts"],"sourcesContent":["import type { Table } from \"apache-arrow\";\n\n// ============================================================================\n// Data Format Types\n// ============================================================================\n\n/** Supported data formats for analytics queries */\nexport type DataFormat = \"json\" | \"arrow\" | \"auto\";\n\n/** Chart orientation */\nexport type Orientation = \"vertical\" | \"horizontal\";\n\n/** Supported chart types */\nexport type ChartType =\n  | \"bar\"\n  | \"line\"\n  | \"area\"\n  | \"pie\"\n  | \"donut\"\n  | \"scatter\"\n  | \"radar\"\n  | \"heatmap\";\n\n/** Data that can be passed to unified charts */\nexport type ChartData = Table | Record<string, unknown>[];\n\n// ============================================================================\n// Base Props (shared by all charts)\n// ============================================================================\n\n/** Color palette types for different visualization needs */\nexport type ChartColorPalette = \"categorical\" | \"sequential\" | \"diverging\";\n\n/** Resolved colors for the chart UI — axis text, titles, grid lines, and tooltip. */\nexport interface ChartUITokens {\n  /** Axis tick labels (≈ `--muted-foreground`) */\n  axisLabel: string;\n  /** Axis names, legend, title, and visualMap text (≈ `--foreground`) */\n  axisTitle: string;\n  /** Axis, tick, and split (grid) lines (≈ `--border`) */\n  grid: string;\n  /** Tooltip popover background (≈ `--popover`) */\n  tooltipBg: string;\n}\n\n/** Common visual and behavior props for all charts */\nexport interface ChartBaseProps {\n  /** Chart title */\n  title?: string;\n  /** Show legend */\n  showLegend?: boolean;\n  /**\n   * Color palette to use. Auto-selected based on chart type if not specified.\n   * - \"categorical\": Distinct colors for different categories (bar, pie, line)\n   * - \"sequential\": Gradient for magnitude/intensity (heatmap)\n   * - \"diverging\": Two-tone for positive/negative values\n   */\n  colorPalette?: ChartColorPalette;\n  /** Custom colors for series (overrides colorPalette) */\n  colors?: string[];\n  /** Chart height in pixels @default 300 */\n  height?: number;\n  /** Additional CSS classes */\n  className?: string;\n\n  /** X-axis field key. Auto-detected from schema if not provided. */\n  xKey?: string;\n  /** Y-axis field key(s). Auto-detected from schema if not provided. */\n  yKey?: string | string[];\n\n  /** Accessibility label for screen readers */\n  ariaLabel?: string;\n  /** Test ID for automated testing */\n  testId?: string;\n\n  /** Additional ECharts options to merge */\n  options?: Record<string, unknown>;\n}\n\n// ============================================================================\n// Query-based Props (chart fetches data)\n// ============================================================================\n\n/** Props for query-based data fetching */\nexport interface QueryProps extends ChartBaseProps {\n  /** Analytics query key registered with analytics plugin */\n  queryKey: string;\n  /** Query parameters passed to the analytics endpoint */\n  parameters?: Record<string, unknown>;\n  /**\n   * Data format to use\n   * - \"json\": Use JSON format (smaller payloads, simpler)\n   * - \"arrow\": Use Arrow format (faster for large datasets)\n   * - \"auto\": Automatically select based on expected data size\n   * @default \"auto\"\n   */\n  format?: DataFormat;\n  /** Transform raw data before rendering */\n  transformer?: <T>(data: T) => T;\n  // Discriminator: cannot use direct data with query\n  data?: never;\n}\n\n// ============================================================================\n// Data-based Props (chart receives data externally)\n// ============================================================================\n\n/** Props for direct data injection */\nexport interface DataProps extends ChartBaseProps {\n  /** Arrow Table or JSON array */\n  data: ChartData;\n\n  // Discriminator: cannot use query props with direct data\n  queryKey?: never;\n  parameters?: never;\n  format?: never;\n  transformer?: never;\n}\n\n// ============================================================================\n// Union Types for Each Chart\n// ============================================================================\n\n/** Base union type - either query-based or data-based */\nexport type UnifiedChartProps = QueryProps | DataProps;\n\n// ============================================================================\n// Chart-Specific Props\n// ============================================================================\n\n/** Props specific to bar charts */\nexport interface BarChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Stack bars */\n  stacked?: boolean;\n}\n\n/** Props specific to line charts */\nexport interface LineChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n}\n\n/** Props specific to area charts */\nexport interface AreaChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n  /** Stack areas @default false */\n  stacked?: boolean;\n}\n\n/** Props specific to scatter charts */\nexport interface ScatterChartSpecificProps {\n  /** Symbol size @default 8 */\n  symbolSize?: number;\n}\n\n/** Props specific to pie/donut charts */\nexport interface PieChartSpecificProps {\n  /** Inner radius for donut charts (0-100%) @default 0 */\n  innerRadius?: number;\n  /** Show labels on slices @default true */\n  showLabels?: boolean;\n  /** Label position @default \"outside\" */\n  labelPosition?: \"outside\" | \"inside\" | \"center\";\n}\n\n/** Props specific to radar charts */\nexport interface RadarChartSpecificProps {\n  /** Show area fill @default true */\n  showArea?: boolean;\n}\n\n/** Props specific to heatmap charts */\nexport interface HeatmapChartSpecificProps {\n  /**\n   * Field key for the Y-axis categories.\n   * For heatmaps, data should have: xKey (column), yAxisKey (row), and yKey (value).\n   */\n  yAxisKey?: string;\n  /** Min value for color scale (auto-detected if not provided) */\n  min?: number;\n  /** Max value for color scale (auto-detected if not provided) */\n  max?: number;\n  /** Show value labels on cells @default false */\n  showLabels?: boolean;\n}\n\n// ============================================================================\n// Complete Chart Props (union + specific)\n// ============================================================================\n\nexport type BarChartProps = (QueryProps | DataProps) & BarChartSpecificProps;\nexport type LineChartProps = (QueryProps | DataProps) & LineChartSpecificProps;\nexport type AreaChartProps = (QueryProps | DataProps) & AreaChartSpecificProps;\nexport type ScatterChartProps = (QueryProps | DataProps) &\n  ScatterChartSpecificProps;\nexport type PieChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type DonutChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type RadarChartProps = (QueryProps | DataProps) &\n  RadarChartSpecificProps;\nexport type HeatmapChartProps = (QueryProps | DataProps) &\n  HeatmapChartSpecificProps;\n\n// ============================================================================\n// Internal Types\n// ============================================================================\n\n/** Base normalized data shared by all chart types */\nexport interface NormalizedChartDataBase {\n  xData: (string | number)[];\n  xField: string;\n  yFields: string[];\n  chartType: \"timeseries\" | \"categorical\";\n}\n\n/** Normalized chart data for rendering (standard charts) */\nexport interface NormalizedChartData extends NormalizedChartDataBase {\n  yDataMap: Record<string, (string | number)[]>;\n}\n\n/** Type guard to check if data is an Arrow Table */\nexport function isArrowTable(data: ChartData): data is Table {\n  return (\n    data !== null &&\n    typeof data === \"object\" &&\n    \"schema\" in data &&\n    \"numRows\" in data &&\n    typeof (data as Table).getChild === \"function\"\n  );\n}\n\n/** Type guard to check if props are query-based */\nexport function isQueryProps(props: UnifiedChartProps): props is QueryProps {\n  return (\n    \"queryKey\" in props &&\n    typeof props.queryKey === \"string\" &&\n    props.queryKey.length > 0\n  );\n}\n\n/** Type guard to check if props are data-based */\nexport function isDataProps(props: UnifiedChartProps): props is DataProps {\n  return \"data\" in props && props.data != null;\n}\n"],"mappings":";;AAuOA,SAAgB,aAAa,MAAgC;AAC3D,QACE,SAAS,QACT,OAAO,SAAS,YAChB,YAAY,QACZ,aAAa,QACb,OAAQ,KAAe,aAAa;;;AAKxC,SAAgB,aAAa,OAA+C;AAC1E,QACE,cAAc,SACd,OAAO,MAAM,aAAa,YAC1B,MAAM,SAAS,SAAS;;;AAK5B,SAAgB,YAAY,OAA8C;AACxE,QAAO,UAAU,SAAS,MAAM,QAAQ"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/react/charts/types.ts"],"sourcesContent":["import type { Table } from \"apache-arrow\";\n\n// ============================================================================\n// Data Format Types\n// ============================================================================\n\n/**\n * Supported data formats for analytics queries.\n *\n * \"json\" and \"arrow\" are legacy aliases kept for backwards compatibility\n * with appkit-ui < 0.33.0 — safe to remove once no consumer is on a\n * pre-0.33.0 version. resolveFormat() normalizes them to their canonical\n * equivalents before any downstream code reads the value.\n */\nexport type DataFormat =\n  | \"json_array\"\n  | \"arrow_stream\"\n  | \"auto\"\n  /** @deprecated Use \"json_array\". Safe to remove once no consumer is on appkit-ui < 0.33.0. */\n  | \"json\"\n  /** @deprecated Use \"arrow_stream\". Safe to remove once no consumer is on appkit-ui < 0.33.0. */\n  | \"arrow\";\n\n/** Chart orientation */\nexport type Orientation = \"vertical\" | \"horizontal\";\n\n/** Supported chart types */\nexport type ChartType =\n  | \"bar\"\n  | \"line\"\n  | \"area\"\n  | \"pie\"\n  | \"donut\"\n  | \"scatter\"\n  | \"radar\"\n  | \"heatmap\";\n\n/** Data that can be passed to unified charts */\nexport type ChartData = Table | Record<string, unknown>[];\n\n// ============================================================================\n// Base Props (shared by all charts)\n// ============================================================================\n\n/** Color palette types for different visualization needs */\nexport type ChartColorPalette = \"categorical\" | \"sequential\" | \"diverging\";\n\n/** Resolved colors for the chart UI — axis text, titles, grid lines, and tooltip. */\nexport interface ChartUITokens {\n  /** Axis tick labels (≈ `--muted-foreground`) */\n  axisLabel: string;\n  /** Axis names, legend, title, and visualMap text (≈ `--foreground`) */\n  axisTitle: string;\n  /** Axis, tick, and split (grid) lines (≈ `--border`) */\n  grid: string;\n  /** Tooltip popover background (≈ `--popover`) */\n  tooltipBg: string;\n}\n\n/** Common visual and behavior props for all charts */\nexport interface ChartBaseProps {\n  /** Chart title */\n  title?: string;\n  /** Show legend */\n  showLegend?: boolean;\n  /**\n   * Color palette to use. Auto-selected based on chart type if not specified.\n   * - \"categorical\": Distinct colors for different categories (bar, pie, line)\n   * - \"sequential\": Gradient for magnitude/intensity (heatmap)\n   * - \"diverging\": Two-tone for positive/negative values\n   */\n  colorPalette?: ChartColorPalette;\n  /** Custom colors for series (overrides colorPalette) */\n  colors?: string[];\n  /** Chart height in pixels @default 300 */\n  height?: number;\n  /** Additional CSS classes */\n  className?: string;\n\n  /** X-axis field key. Auto-detected from schema if not provided. */\n  xKey?: string;\n  /** Y-axis field key(s). Auto-detected from schema if not provided. */\n  yKey?: string | string[];\n\n  /** Accessibility label for screen readers */\n  ariaLabel?: string;\n  /** Test ID for automated testing */\n  testId?: string;\n\n  /** Additional ECharts options to merge */\n  options?: Record<string, unknown>;\n}\n\n// ============================================================================\n// Query-based Props (chart fetches data)\n// ============================================================================\n\n/** Props for query-based data fetching */\nexport interface QueryProps extends ChartBaseProps {\n  /** Analytics query key registered with analytics plugin */\n  queryKey: string;\n  /** Query parameters passed to the analytics endpoint */\n  parameters?: Record<string, unknown>;\n  /**\n   * Data format to use\n   * - \"json_array\": Use JSON format (smaller payloads, simpler)\n   * - \"arrow_stream\": Use Arrow format (faster for large datasets)\n   * - \"auto\": Automatically select based on expected data size\n   * @default \"auto\"\n   */\n  format?: DataFormat;\n  /** Transform raw data before rendering */\n  transformer?: <T>(data: T) => T;\n  // Discriminator: cannot use direct data with query\n  data?: never;\n}\n\n// ============================================================================\n// Data-based Props (chart receives data externally)\n// ============================================================================\n\n/** Props for direct data injection */\nexport interface DataProps extends ChartBaseProps {\n  /** Arrow Table or JSON array */\n  data: ChartData;\n\n  // Discriminator: cannot use query props with direct data\n  queryKey?: never;\n  parameters?: never;\n  format?: never;\n  transformer?: never;\n}\n\n// ============================================================================\n// Union Types for Each Chart\n// ============================================================================\n\n/** Base union type - either query-based or data-based */\nexport type UnifiedChartProps = QueryProps | DataProps;\n\n// ============================================================================\n// Chart-Specific Props\n// ============================================================================\n\n/** Props specific to bar charts */\nexport interface BarChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Stack bars */\n  stacked?: boolean;\n}\n\n/** Props specific to line charts */\nexport interface LineChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n}\n\n/** Props specific to area charts */\nexport interface AreaChartSpecificProps {\n  /** Chart orientation @default \"vertical\" */\n  orientation?: Orientation;\n  /** Show data point symbols @default false */\n  showSymbol?: boolean;\n  /** Smooth line curves @default true */\n  smooth?: boolean;\n  /** Stack areas @default false */\n  stacked?: boolean;\n}\n\n/** Props specific to scatter charts */\nexport interface ScatterChartSpecificProps {\n  /** Symbol size @default 8 */\n  symbolSize?: number;\n}\n\n/** Props specific to pie/donut charts */\nexport interface PieChartSpecificProps {\n  /** Inner radius for donut charts (0-100%) @default 0 */\n  innerRadius?: number;\n  /** Show labels on slices @default true */\n  showLabels?: boolean;\n  /** Label position @default \"outside\" */\n  labelPosition?: \"outside\" | \"inside\" | \"center\";\n}\n\n/** Props specific to radar charts */\nexport interface RadarChartSpecificProps {\n  /** Show area fill @default true */\n  showArea?: boolean;\n}\n\n/** Props specific to heatmap charts */\nexport interface HeatmapChartSpecificProps {\n  /**\n   * Field key for the Y-axis categories.\n   * For heatmaps, data should have: xKey (column), yAxisKey (row), and yKey (value).\n   */\n  yAxisKey?: string;\n  /** Min value for color scale (auto-detected if not provided) */\n  min?: number;\n  /** Max value for color scale (auto-detected if not provided) */\n  max?: number;\n  /** Show value labels on cells @default false */\n  showLabels?: boolean;\n}\n\n// ============================================================================\n// Complete Chart Props (union + specific)\n// ============================================================================\n\nexport type BarChartProps = (QueryProps | DataProps) & BarChartSpecificProps;\nexport type LineChartProps = (QueryProps | DataProps) & LineChartSpecificProps;\nexport type AreaChartProps = (QueryProps | DataProps) & AreaChartSpecificProps;\nexport type ScatterChartProps = (QueryProps | DataProps) &\n  ScatterChartSpecificProps;\nexport type PieChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type DonutChartProps = (QueryProps | DataProps) & PieChartSpecificProps;\nexport type RadarChartProps = (QueryProps | DataProps) &\n  RadarChartSpecificProps;\nexport type HeatmapChartProps = (QueryProps | DataProps) &\n  HeatmapChartSpecificProps;\n\n// ============================================================================\n// Internal Types\n// ============================================================================\n\n/** Base normalized data shared by all chart types */\nexport interface NormalizedChartDataBase {\n  xData: (string | number)[];\n  xField: string;\n  yFields: string[];\n  chartType: \"timeseries\" | \"categorical\";\n}\n\n/** Normalized chart data for rendering (standard charts) */\nexport interface NormalizedChartData extends NormalizedChartDataBase {\n  yDataMap: Record<string, (string | number)[]>;\n}\n\n/** Type guard to check if data is an Arrow Table */\nexport function isArrowTable(data: ChartData): data is Table {\n  return (\n    data !== null &&\n    typeof data === \"object\" &&\n    \"schema\" in data &&\n    \"numRows\" in data &&\n    typeof (data as Table).getChild === \"function\"\n  );\n}\n\n/** Type guard to check if props are query-based */\nexport function isQueryProps(props: UnifiedChartProps): props is QueryProps {\n  return (\n    \"queryKey\" in props &&\n    typeof props.queryKey === \"string\" &&\n    props.queryKey.length > 0\n  );\n}\n\n/** Type guard to check if props are data-based */\nexport function isDataProps(props: UnifiedChartProps): props is DataProps {\n  return \"data\" in props && props.data != null;\n}\n"],"mappings":";;AAqPA,SAAgB,aAAa,MAAgC;AAC3D,QACE,SAAS,QACT,OAAO,SAAS,YAChB,YAAY,QACZ,aAAa,QACb,OAAQ,KAAe,aAAa;;;AAKxC,SAAgB,aAAa,OAA+C;AAC1E,QACE,cAAc,SACd,OAAO,MAAM,aAAa,YAC1B,MAAM,SAAS,SAAS;;;AAK5B,SAAgB,YAAY,OAA8C;AACxE,QAAO,UAAU,SAAS,MAAM,QAAQ"}

package/dist/react/hooks/types.d.ts

@@ -28,7 +28,7 @@ interface TypedArrowTable<TRow extends Record<string, unknown> = Record<string,
 }
 /** Options for configuring an analytics SSE query */
 interface UseAnalyticsQueryOptions<F extends AnalyticsFormat = "JSON_ARRAY"> {
-  /** Response format - "JSON_ARRAY" returns typed arrays, "ARROW_STREAM" returns TypedArrowTable */
+  /** Response format - "JSON_ARRAY" (default) returns typed arrays, "ARROW_STREAM" uses Arrow (inline or external links) */
   format?: F;
   /** Maximum size of serialized parameters in bytes */
   maxParametersSize?: number;
@@ -62,8 +62,16 @@ interface UseAnalyticsQueryResult<T> {
   data: T | null;
   /** Loading state of the query */
   loading: boolean;
-  /** Error state of the query */
+  /** Error state of the query — sanitized human-readable message */
   error: string | null;
+  /**
+   * Structured upstream error code when the server attaches one to the
+   * error payload (e.g. `RESULT_TOO_LARGE_FOR_JSON_FALLBACK`,
+   * `ARROW_DELIVERY_UNSUPPORTED`, `NOT_IMPLEMENTED`). Prefer branching UI
+   * on this stable identifier rather than substring-matching `error`,
+   * which is a free-form sanitized message.
+   */
+  errorCode: string | null;
   /**
    * Latest warehouse status emitted by the server while waiting for the SQL
    * warehouse to reach RUNNING. `null` until the first status event arrives;

package/dist/react/hooks/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/hooks/types.ts"],"mappings":";;;;;AAaA;;;;;KAAY,eAAA;;;;;;;;;;;UAkBK,eAAA,cACF,MAAA,oBAA0B,MAAA,2BAC/B,KAAA;EAKiB;AAQ3B;;;EAR2B,SAAhB,SAAA,GAAY,IAAA;AAAA;;UAQN,wBAAA,WACL,eAAA;EAGD;EAAT,MAAA,GAAS,CAAA;EAMT;EAHA,iBAAA;EAGS;EAAT,SAAA;AAAA;;;;AA0BF;;KAlBY,cAAA;;;;;;;AAyBZ;;;;UAPiB,eAAA;EACf,KAAA,EAAO,cAAA;EAQD;EANN,SAAA;AAAA;;UAIe,uBAAA;EAYiB;EAVhC,IAAA,EAAM,CAAA;EA+BS;EA7Bf,OAAA;;EAEA,KAAA;EA4BC;;;;;EAtBD,eAAA,EAAiB,eAAA;AAAA;AA8BnB;;;;;;;;;;;;;;;;;;AAAA,UATiB,aAAA;EAAA,CACd,GAAA;IACC,IAAA;IACA,UAAA,EAAY,MAAA;IACZ,MAAA;EAAA;AAAA;;KAKQ,iBAAA,0BACE,CAAA,mBAAoB,CAAA,WAAY,CAAA,GAAI,CAAA,CAAE,CAAA;;KAIxC,QAAA,GAAW,iBAAA,CAAkB,aAAA,2BAErC,iBAAA,CAAkB,aAAA;;;;AAMtB;KAAY,WAAA,SAAoB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACxD,aAAA,CAAc,CAAA;EAAa,MAAA;AAAA,IACzB,CAAA,GACA,CAAA,GACF,CAAA;;;;;KAMQ,YAAA,MAAkB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACtD,aAAA,CAAc,CAAA;EAAa,MAAA,EAAQ,KAAA;AAAA,IACjC,CAAA,SAAU,MAAA,oBACR,CAAA,GACA,MAAA,oBACF,MAAA,oBACF,MAAA;;;;;;KAOQ,mBAAA,iBAAoC,eAAA,IAAmB,CAAA,oCAG/D,eAAA,CAAgB,YAAA,CAAa,CAAA,KAC7B,WAAA,CAAY,CAAA,EAAG,CAAA;;;;KAKP,WAAA,MAAiB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACrD,aAAA,CAAc,CAAA;EAAa,UAAA;AAAA,IACzB,CAAA,GACA,MAAA,oBACF,MAAA;AAAA,UAEa,cAAA;EAAA,CACd,GAAA,WAAc,MAAA;AAAA;;;;;;;;;;;;;;;UA2BA,uBAAA;;KAGL,YAAA,GACV,iBAAA,CAAkB,uBAAA,2BAEd,iBAAA,CAAkB,uBAAA;;KAGZ,iBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,KAAA;AAAA,IACnC,CAAA;;KAKI,oBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,QAAA;AAAA,IACnC,CAAA;;KAKI,mBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,OAAA;AAAA,IACnC,GAAA,GACA,MAAA,oBACF,MAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/react/hooks/types.ts"],"mappings":";;;;;AAaA;;;;;KAAY,eAAA;;;;;;;;;;;UAkBK,eAAA,cACF,MAAA,oBAA0B,MAAA,2BAC/B,KAAA;EAKiB;AAQ3B;;;EAR2B,SAAhB,SAAA,GAAY,IAAA;AAAA;;UAQN,wBAAA,WACL,eAAA;EAGD;EAAT,MAAA,GAAS,CAAA;EAMT;EAHA,iBAAA;EAGS;EAAT,SAAA;AAAA;;;;AA0BF;;KAlBY,cAAA;;;;;;;AAyBZ;;;;UAPiB,eAAA;EACf,KAAA,EAAO,cAAA;EAQD;EANN,SAAA;AAAA;;UAIe,uBAAA;EAoBE;EAlBjB,IAAA,EAAM,CAAA;EAkB0B;EAhBhC,OAAA;EAqC4B;EAnC5B,KAAA;EAsCoB;;;;;;;EA9BpB,SAAA;EAoCU;;;;;EA9BV,eAAA,EAAiB,eAAA;AAAA;;;;;;;;;;;;;AAmCnB;;;;;;UAdiB,aAAA;EAAA,CACd,GAAA;IACC,IAAA;IACA,UAAA,EAAY,MAAA;IACZ,MAAA;EAAA;AAAA;;KAKQ,iBAAA,0BACE,CAAA,mBAAoB,CAAA,WAAY,CAAA,GAAI,CAAA,CAAE,CAAA;;KAIxC,QAAA,GAAW,iBAAA,CAAkB,aAAA,2BAErC,iBAAA,CAAkB,aAAA;;;;;KAMV,WAAA,SAAoB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACxD,aAAA,CAAc,CAAA;EAAa,MAAA;AAAA,IACzB,CAAA,GACA,CAAA,GACF,CAAA;;;;;KAMQ,YAAA,MAAkB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACtD,aAAA,CAAc,CAAA;EAAa,MAAA,EAAQ,KAAA;AAAA,IACjC,CAAA,SAAU,MAAA,oBACR,CAAA,GACA,MAAA,oBACF,MAAA,oBACF,MAAA;;;;;;KAOQ,mBAAA,iBAAoC,eAAA,IAAmB,CAAA,oCAG/D,eAAA,CAAgB,YAAA,CAAa,CAAA,KAC7B,WAAA,CAAY,CAAA,EAAG,CAAA;;;AAjBnB;KAsBY,WAAA,MAAiB,CAAA,SAAU,iBAAA,CAAkB,aAAA,IACrD,aAAA,CAAc,CAAA;EAAa,UAAA;AAAA,IACzB,CAAA,GACA,MAAA,oBACF,MAAA;AAAA,UAEa,cAAA;EAAA,CACd,GAAA,WAAc,MAAA;AAAA;;;;;;;;;;;;;;;UA2BA,uBAAA;;KAGL,YAAA,GACV,iBAAA,CAAkB,uBAAA,2BAEd,iBAAA,CAAkB,uBAAA;;KAGZ,iBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,KAAA;AAAA,IACnC,CAAA;;KAKI,oBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,QAAA;AAAA,IACnC,CAAA;;KAKI,mBAAA,MACV,CAAA,SAAU,iBAAA,CAAkB,uBAAA,IACxB,uBAAA,CAAwB,CAAA;EAAa,OAAA;AAAA,IACnC,GAAA,GACA,MAAA,oBACF,MAAA"}

package/dist/react/hooks/use-analytics-query.d.ts

@@ -2,7 +2,9 @@ import { AnalyticsFormat, InferParams, InferResultByFormat, QueryKey, UseAnalyti
 
 //#region src/react/hooks/use-analytics-query.d.ts
 /**
- * Subscribe to an analytics query over SSE and returns its latest result.
+ * Subscribe to an analytics query and return its latest result. JSON_ARRAY
+ * results stream over SSE (with warehouse-readiness progress); ARROW_STREAM
+ * results are fetched as raw Arrow bytes directly from the query endpoint.
  * Integration hook between client and analytics plugin.
  *
  * The return type is automatically inferred based on the format:
@@ -18,13 +20,13 @@ import { AnalyticsFormat, InferParams, InferResultByFormat, QueryKey, UseAnalyti
  * @param options - Analytics query settings including format
  * @returns Query result state with format-appropriate data type
  *
- * @example JSON format (default)
+ * @example JSON_ARRAY format (default)
  * ```typescript
  * const { data } = useAnalyticsQuery("spend_data", params);
  * // data: Array<{ group_key: string; cost_usd: number; ... }> | null
  * ```
  *
- * @example Arrow format
+ * @example ARROW_STREAM format
  * ```typescript
  * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW_STREAM" });
  * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null

package/dist/react/hooks/use-analytics-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-analytics-query.d.ts","names":[],"sources":["../../../src/react/hooks/use-analytics-query.ts"],"mappings":";;;;;AAgLA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,iBAAA,wBAEJ,QAAA,GAAW,QAAA,YACX,eAAA,gBAAA,CAEV,QAAA,EAAU,CAAA,EACV,UAAA,GAAa,WAAA,CAAY,CAAA,UACzB,OAAA,GAAS,wBAAA,CAAyB,CAAA,IACjC,uBAAA,CAAwB,mBAAA,CAAoB,CAAA,EAAG,CAAA,EAAG,CAAA"}
+{"version":3,"file":"use-analytics-query.d.ts","names":[],"sources":["../../../src/react/hooks/use-analytics-query.ts"],"mappings":";;;;;AA6SA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,iBAAA,wBAEJ,QAAA,GAAW,QAAA,YACX,eAAA,gBAAA,CAEV,QAAA,EAAU,CAAA,EACV,UAAA,GAAa,WAAA,CAAY,CAAA,UACzB,OAAA,GAAS,wBAAA,CAAyB,CAAA,IACjC,uBAAA,CAAwB,mBAAA,CAAoB,CAAA,EAAG,CAAA,EAAG,CAAA"}

package/dist/react/hooks/use-analytics-query.js

@@ -28,10 +28,15 @@ function getDevMode() {
 	const dev = new URL(window.location.href).searchParams.get("dev");
 	return dev ? `?dev=${dev}` : "";
 }
-function getArrowStreamUrl(id) {
-	return `/api/analytics/arrow-result/${id}`;
-}
 const GENERIC_LOAD_ERROR = "Unable to load data, please try again";
+/** Map a fetch/SSE transport error to a user-facing message. */
+function userFacingFetchError(error) {
+	if (error instanceof Error) {
+		if (error.name === "AbortError") return "Request timed out, please try again";
+		if (error.message.includes("Failed to fetch")) return "Network error. Please check your connection.";
+	}
+	return GENERIC_LOAD_ERROR;
+}
 function isWarehouseStatusPayload(value) {
 	return typeof value === "object" && value !== null && typeof value.state === "string";
 }
@@ -50,35 +55,95 @@ async function handleAnalyticsSseMessage(parsed, ctx) {
 	}
 	if (parsed.type === "result") {
 		ctx.setLoading(false);
-		ctx.setData(parsed.data);
+		ctx.setData(Array.isArray(parsed.data) ? parsed.data : []);
 		ctx.unpublishWarehouseStatus();
 		return;
 	}
-	if (parsed.type === "arrow") {
-		try {
-			const arrowData = await ArrowClient.fetchArrow(getArrowStreamUrl(parsed.statement_id));
-			const table = await ArrowClient.processArrowBuffer(arrowData);
-			ctx.setLoading(false);
-			ctx.setData(table);
-			ctx.unpublishWarehouseStatus();
-		} catch (error) {
-			console.error("[useAnalyticsQuery] Failed to fetch Arrow data", error);
-			ctx.setLoading(false);
-			ctx.setError(GENERIC_LOAD_ERROR);
-			ctx.unpublishWarehouseStatus();
-		}
-		return;
-	}
 	if (parsed.type === "error" || parsed.error || parsed.code) {
 		const errorMsg = parsed.error || parsed.message || "Unable to execute query";
 		ctx.setLoading(false);
 		ctx.setError(errorMsg);
 		ctx.unpublishWarehouseStatus();
+		if (typeof parsed.errorCode === "string") ctx.setErrorCode(parsed.errorCode);
 		if (parsed.code) console.error(`[useAnalyticsQuery] Code: ${parsed.code}, Message: ${errorMsg}`);
+		return;
+	}
+	console.error("[useAnalyticsQuery] Unrecognized SSE payload", parsed);
+	ctx.setLoading(false);
+	ctx.setError(GENERIC_LOAD_ERROR);
+	ctx.unpublishWarehouseStatus();
+}
+/**
+* Fetch the real column names for a statement from the fallback endpoint,
+* used when a very wide schema's names didn't fit in the response header.
+* Returns undefined on any failure so decoding falls back to the raw Arrow
+* schema names.
+*/
+async function fetchArrowColumns(statementId, signal) {
+	try {
+		const res = await fetch(`/api/analytics/columns/${encodeURIComponent(statementId)}`, { signal });
+		if (!res.ok) return void 0;
+		const body = await res.json();
+		return Array.isArray(body.columns) ? body.columns : void 0;
+	} catch {
+		return;
 	}
 }
 /**
-* Subscribe to an analytics query over SSE and returns its latest result.
+* Fetch an ARROW_STREAM query result as raw Arrow IPC bytes directly from
+* the query endpoint (no SSE, no second /arrow-result request) and decode
+* it into a Table. The server streams the bytes back as the POST response
+* body; errors before the first byte arrive as a JSON `{ error, errorCode }`.
+*/
+async function fetchArrowDirect(ctx) {
+	try {
+		const response = await fetch(ctx.url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: ctx.payload,
+			signal: ctx.signal
+		});
+		if (ctx.signal.aborted) return;
+		if (!response.ok) {
+			let message = GENERIC_LOAD_ERROR;
+			let code = null;
+			try {
+				const body = await response.json();
+				if (body.error) message = body.error;
+				if (typeof body.errorCode === "string") code = body.errorCode;
+			} catch {}
+			ctx.setLoading(false);
+			ctx.setError(message);
+			if (code) ctx.setErrorCode(code);
+			ctx.unpublishWarehouseStatus();
+			return;
+		}
+		const buffer = await response.arrayBuffer();
+		if (ctx.signal.aborted) return;
+		let columnNames;
+		const header = response.headers.get("X-Appkit-Arrow-Columns");
+		if (header) try {
+			columnNames = JSON.parse(decodeURIComponent(header));
+		} catch {}
+		else {
+			const ref = response.headers.get("X-Appkit-Arrow-Columns-Ref");
+			if (ref) columnNames = await fetchArrowColumns(ref, ctx.signal);
+		}
+		const table = await ArrowClient.processArrowBuffer(new Uint8Array(buffer), columnNames);
+		ctx.setData(table);
+		ctx.setLoading(false);
+		ctx.unpublishWarehouseStatus();
+	} catch (error) {
+		if (ctx.signal.aborted) return;
+		ctx.setLoading(false);
+		ctx.unpublishWarehouseStatus();
+		ctx.setError(userFacingFetchError(error));
+	}
+}
+/**
+* Subscribe to an analytics query and return its latest result. JSON_ARRAY
+* results stream over SSE (with warehouse-readiness progress); ARROW_STREAM
+* results are fetched as raw Arrow bytes directly from the query endpoint.
 * Integration hook between client and analytics plugin.
 *
 * The return type is automatically inferred based on the format:
@@ -94,13 +159,13 @@ async function handleAnalyticsSseMessage(parsed, ctx) {
 * @param options - Analytics query settings including format
 * @returns Query result state with format-appropriate data type
 *
-* @example JSON format (default)
+* @example JSON_ARRAY format (default)
 * ```typescript
 * const { data } = useAnalyticsQuery("spend_data", params);
 * // data: Array<{ group_key: string; cost_usd: number; ... }> | null
 * ```
 *
-* @example Arrow format
+* @example ARROW_STREAM format
 * ```typescript
 * const { data } = useAnalyticsQuery("spend_data", params, { format: "ARROW_STREAM" });
 * // data: TypedArrowTable<{ group_key: string; cost_usd: number; ... }> | null
@@ -115,6 +180,7 @@ function useAnalyticsQuery(queryKey, parameters, options = {}) {
 	const [data, setData] = useState(null);
 	const [loading, setLoading] = useState(false);
 	const [error, setError] = useState(null);
+	const [errorCode, setErrorCode] = useState(null);
 	const [warehouseStatus, setWarehouseStatus] = useState(null);
 	const abortControllerRef = useRef(null);
 	const { publish: publishWarehouseStatus, unpublish: unpublishWarehouseStatus } = useAnalyticsWarehousePublisher(useId(), queryKey);
@@ -145,14 +211,29 @@ function useAnalyticsQuery(queryKey, parameters, options = {}) {
 		abortControllerRef.current?.abort();
 		setLoading(true);
 		setError(null);
+		setErrorCode(null);
 		setData(null);
 		setWarehouseStatus(null);
 		publishWarehouseStatus(null);
 		const abortController = new AbortController();
 		abortControllerRef.current = abortController;
+		if (format === "ARROW_STREAM") {
+			fetchArrowDirect({
+				url: urlSuffix,
+				payload,
+				signal: abortController.signal,
+				setLoading,
+				setError,
+				setErrorCode,
+				setData: (table) => setData(table),
+				unpublishWarehouseStatus
+			});
+			return;
+		}
 		const sseContext = {
 			setLoading,
 			setError,
+			setErrorCode,
 			setData,
 			setWarehouseStatus,
 			publishWarehouseStatus,
@@ -168,29 +249,28 @@ function useAnalyticsQuery(queryKey, parameters, options = {}) {
 					await handleAnalyticsSseMessage(JSON.parse(message.data), sseContext);
 				} catch (error) {
 					console.warn("[useAnalyticsQuery] Malformed message received", error);
+					setLoading(false);
+					setError(GENERIC_LOAD_ERROR);
+					abortController.abort();
 				}
 			},
 			onError: (error) => {
 				if (abortController.signal.aborted) return;
 				setLoading(false);
 				unpublishWarehouseStatus();
-				let userMessage = GENERIC_LOAD_ERROR;
-				if (error instanceof Error) {
-					if (error.name === "AbortError") userMessage = "Request timed out, please try again";
-					else if (error.message.includes("Failed to fetch")) userMessage = "Network error. Please check your connection.";
-					console.error("[useAnalyticsQuery] Error", {
-						queryKey,
-						error: error.message,
-						stack: error.stack
-					});
-				}
-				setError(userMessage);
+				if (error instanceof Error) console.error("[useAnalyticsQuery] Error", {
+					queryKey,
+					error: error.message,
+					stack: error.stack
+				});
+				setError(userFacingFetchError(error));
 			}
 		});
 	}, [
 		queryKey,
 		payload,
 		urlSuffix,
+		format,
 		publishWarehouseStatus,
 		unpublishWarehouseStatus
 	]);
@@ -210,6 +290,7 @@ function useAnalyticsQuery(queryKey, parameters, options = {}) {
 		data,
 		loading,
 		error,
+		errorCode,
 		warehouseStatus
 	};
 }