@databricks/appkit-ui 0.0.2

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

@@ -0,0 +1,181 @@
+import { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS } from "../constants.js";
+import { getArrowModule, getDecimalTypeId, getTypeIdSets, initializeTypeIdSets } from "./lazy-arrow.js";
+
+//#region src/js/arrow/arrow-client.ts
+var ArrowClient = class ArrowClient {
+	/**
+	* Processes an Arrow IPC buffer into a Table.
+	* Lazily loads the Apache Arrow library on first use.
+	*
+	* @param buffer - The Arrow IPC format buffer
+	* @returns Promise resolving to an Arrow Table
+	*/
+	static async processArrowBuffer(buffer) {
+		try {
+			const arrow = await getArrowModule();
+			await initializeTypeIdSets();
+			return arrow.tableFromIPC(buffer);
+		} catch (error) {
+			throw new Error(`Failed to process Arrow buffer: ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+	}
+	static async fetchAndProcessArrow(url, headers) {
+		try {
+			const buffer = await ArrowClient.fetchArrow(url, headers);
+			return ArrowClient.processArrowBuffer(buffer);
+		} catch (error) {
+			throw new Error(`Failed to fetch Arrow data: ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+	}
+	static extractArrowFields(table) {
+		return table.schema.fields.map((field) => {
+			return {
+				name: field.name,
+				type: field.type
+			};
+		});
+	}
+	static extractArrowColumns(table) {
+		const cols = {};
+		for (const field of table.schema.fields) {
+			const child = table.getChild(field.name);
+			if (child) cols[field.name] = child.toArray();
+		}
+		return cols;
+	}
+	/**
+	* Extracts chart data from Arrow table.
+	* Uses get(i) to properly handle complex types like Decimal128.
+	* Applies decimal scaling for DECIMAL types.
+	*
+	* Note: This method assumes Arrow has been loaded (via processArrowBuffer).
+	*
+	* @returns xData for axis, yDataMap for series data
+	*/
+	static extractChartData(table, xKey, yKeys) {
+		if (table.numRows === 0) return EMPTY_RESULT;
+		const decimalType = getDecimalTypeId();
+		const decimalDivisors = /* @__PURE__ */ new Map();
+		for (const field of table.schema.fields) if (field.typeId === decimalType) {
+			const decType = field.type;
+			if (typeof decType.scale === "number") decimalDivisors.set(field.name, 10 ** decType.scale);
+		}
+		const xData = extractColumnValues(table.getChild(xKey), decimalDivisors.get(xKey));
+		const yDataMap = {};
+		for (let i = 0; i < yKeys.length; i++) {
+			const key = yKeys[i];
+			yDataMap[key] = extractColumnValues(table.getChild(key), decimalDivisors.get(key));
+		}
+		return {
+			xData,
+			yDataMap
+		};
+	}
+	/**
+	* Automatically detect which fields to use for chart axes from an Arrow table
+	* Uses the schema's type information for accurate field detection
+	*
+	* Note: This method assumes Arrow has been loaded (via processArrowBuffer).
+	*
+	* @param table - Arrow Table to analyze
+	* @param orientation - Chart orientation ("vertical" for time-series, "horizontal" for categorical)
+	* @returns Object containing the detected fields
+	* @example
+	* // Time-series data
+	* detectFieldsFromArrow(timeSeriesTable)
+	* // { xField: "date", yFields: ["revenue", "cost"], chartType: "timeseries" }
+	*
+	* // Categorical data
+	* detectFieldsFromArrow(categoricalTable)
+	* // { xField: "app_name", yFields: ["totalSpend"], chartType: "categorical" }
+	*/
+	static detectFieldsFromArrow(table, orientation) {
+		const fields = table.schema.fields;
+		if (fields.length === 0) return {
+			xField: "x",
+			yFields: ["y"],
+			chartType: "categorical"
+		};
+		const fieldNames = fields.map((f) => f.name);
+		const typeIdSets = getTypeIdSets();
+		const temporalFields = [];
+		const numericFields = [];
+		const stringFields = [];
+		for (const field of fields) {
+			const typeId = field.typeId;
+			if (typeIdSets.temporal.has(typeId)) temporalFields.push(field.name);
+			else if (typeIdSets.numeric.has(typeId)) numericFields.push(field.name);
+			else if (typeIdSets.string.has(typeId)) stringFields.push(field.name);
+		}
+		let nameFields = stringFields.filter((name) => NAME_FIELD_PATTERNS.some((pattern) => name.toLowerCase().includes(pattern)));
+		if (nameFields.length === 0) nameFields = stringFields.filter((name) => !name.toLowerCase().endsWith("_id"));
+		const chartDateFields = temporalFields.filter((name) => !METADATA_DATE_PATTERNS.some((pattern) => name.toLowerCase().includes(pattern)));
+		const metadataDateFields = temporalFields.filter((name) => METADATA_DATE_PATTERNS.some((pattern) => name.toLowerCase().includes(pattern)));
+		const stringDateFields = stringFields.filter((name) => DATE_FIELD_PATTERNS.some((pattern) => name.toLowerCase().includes(pattern)) && !METADATA_DATE_PATTERNS.some((pattern) => name.toLowerCase().includes(pattern)));
+		const primaryDateFields = [...chartDateFields, ...stringDateFields];
+		const isTimeSeries = primaryDateFields.length > 0 && orientation !== "horizontal";
+		const isCategorical = nameFields.length > 0 && (primaryDateFields.length === 0 || orientation === "horizontal");
+		if (orientation === "horizontal" || isCategorical) {
+			const xField$1 = nameFields[0] || primaryDateFields[0] || metadataDateFields[0] || fieldNames[0];
+			return {
+				xField: xField$1,
+				yFields: numericFields.length > 0 ? numericFields : fieldNames.filter((k) => k !== xField$1),
+				chartType: "categorical"
+			};
+		}
+		const xField = primaryDateFields[0] || metadataDateFields[0] || nameFields[0] || fieldNames[0];
+		return {
+			xField,
+			yFields: numericFields.length > 0 ? numericFields : fieldNames.filter((k) => k !== xField),
+			chartType: isTimeSeries ? "timeseries" : "categorical"
+		};
+	}
+	static async fetchArrow(url, headers) {
+		try {
+			const response = await fetch(url, { headers: {
+				"Content-Type": "application/octet-stream",
+				...headers
+			} });
+			if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+			const buffer = await response.arrayBuffer();
+			return new Uint8Array(buffer);
+		} catch (error) {
+			throw new Error(`Failed to fetch Arrow data: ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+	}
+};
+const EMPTY_RESULT = {
+	xData: [],
+	yDataMap: {}
+};
+/**
+* Extracts values from an Arrow Vector properly.
+* Uses get(i) to handle complex types like Decimal128 correctly.
+* toArray() doesn't work properly for Decimal types - it returns raw bytes.
+*
+* @param col - The Arrow column/vector
+* @param divisor - Pre-computed divisor for DECIMAL types (10^scale)
+*/
+function extractColumnValues(col, divisor) {
+	if (!col) return [];
+	const len = col.length;
+	const result = new Array(len);
+	for (let i = 0; i < len; i++) {
+		const val = col.get(i);
+		if (val === null || val === void 0) result[i] = 0;
+		else if (typeof val === "bigint") {
+			const num = Number(val);
+			result[i] = divisor !== void 0 ? num / divisor : num;
+		} else if (typeof val === "number") result[i] = divisor !== void 0 ? val / divisor : val;
+		else if (typeof val === "string") result[i] = val;
+		else {
+			const num = Number(val);
+			result[i] = divisor !== void 0 ? num / divisor : num;
+		}
+	}
+	return result;
+}
+
+//#endregion
+export { ArrowClient };
+//# sourceMappingURL=arrow-client.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arrow-client.js","names":["cols: Record<string, any>","yDataMap: Record<string, (string | number)[]>","temporalFields: string[]","numericFields: string[]","stringFields: string[]","xField","EMPTY_RESULT: {\n  xData: (string | number)[];\n  yDataMap: Record<string, (string | number)[]>;\n}","result: (string | number)[]"],"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  initializeTypeIdSets,\n  getTypeIdSets,\n  getDecimalTypeId,\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  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  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  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  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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"}

package/dist/js/arrow/index.js

@@ -0,0 +1,3 @@
+import { DATE_FIELD_PATTERNS, NAME_FIELD_PATTERNS } from "../constants.js";
+import { getArrowModule, initializeTypeIdSets } from "./lazy-arrow.js";
+import { ArrowClient } from "./arrow-client.js";

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

@@ -0,0 +1,23 @@
+import * as apache_arrow0 from "apache-arrow";
+
+//#region src/js/arrow/lazy-arrow.d.ts
+
+/**
+ * Lazily loads the Apache Arrow library.
+ * Returns cached module if already loaded.
+ *
+ * @example
+ * ```typescript
+ * const arrow = await getArrowModule();
+ * const table = arrow.tableFromIPC(buffer);
+ * ```
+ */
+declare function getArrowModule(): Promise<typeof apache_arrow0>;
+/**
+ * Initializes the type ID sets from the Arrow Type enum.
+ * Call this after loading the Arrow module.
+ */
+declare function initializeTypeIdSets(): Promise<void>;
+//#endregion
+export { getArrowModule, initializeTypeIdSets };
+//# sourceMappingURL=lazy-arrow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-arrow.d.ts","names":[],"sources":["../../../src/js/arrow/lazy-arrow.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;iBA+BsB,cAAA,CAAA,GAAkB,eAAJ;;;;;iBAqBd,oBAAA,CAAA,GAAwB"}

package/dist/js/arrow/lazy-arrow.js

@@ -0,0 +1,86 @@
+//#region src/js/arrow/lazy-arrow.ts
+let arrowModulePromise = null;
+/**
+* Lazily loads the Apache Arrow library.
+* Returns cached module if already loaded.
+*
+* @example
+* ```typescript
+* const arrow = await getArrowModule();
+* const table = arrow.tableFromIPC(buffer);
+* ```
+*/
+async function getArrowModule() {
+	if (!arrowModulePromise) arrowModulePromise = import("apache-arrow");
+	return arrowModulePromise;
+}
+let temporalTypeIds = null;
+let numericTypeIds = null;
+let stringTypeIds = null;
+let decimalTypeId = null;
+/**
+* Initializes the type ID sets from the Arrow Type enum.
+* Call this after loading the Arrow module.
+*/
+async function initializeTypeIdSets() {
+	if (temporalTypeIds !== null) return;
+	const { Type } = await getArrowModule();
+	temporalTypeIds = new Set([
+		Type.Date,
+		Type.DateDay,
+		Type.DateMillisecond,
+		Type.Timestamp,
+		Type.TimestampSecond,
+		Type.TimestampMillisecond,
+		Type.TimestampMicrosecond,
+		Type.TimestampNanosecond,
+		Type.Time,
+		Type.TimeSecond,
+		Type.TimeMillisecond,
+		Type.TimeMicrosecond,
+		Type.TimeNanosecond
+	]);
+	numericTypeIds = new Set([
+		Type.Int,
+		Type.Int8,
+		Type.Int16,
+		Type.Int32,
+		Type.Int64,
+		Type.Uint8,
+		Type.Uint16,
+		Type.Uint32,
+		Type.Uint64,
+		Type.Float,
+		Type.Float16,
+		Type.Float32,
+		Type.Float64,
+		Type.Decimal
+	]);
+	stringTypeIds = new Set([Type.Utf8, Type.LargeUtf8]);
+	decimalTypeId = Type.Decimal;
+}
+/**
+* Returns the cached type ID sets.
+* Throws if called before initializeTypeIdSets().
+* This is safe because you can't have a Table without first loading Arrow.
+*/
+function getTypeIdSets() {
+	if (!temporalTypeIds || !numericTypeIds || !stringTypeIds) throw new Error("Arrow type IDs not initialized. Call initializeTypeIdSets() first.");
+	return {
+		temporal: temporalTypeIds,
+		numeric: numericTypeIds,
+		string: stringTypeIds
+	};
+}
+/**
+* Returns the Decimal type ID.
+* Throws if called before initializeTypeIdSets().
+*/
+function getDecimalTypeId() {
+	if (decimalTypeId === null) throw new Error("Arrow type IDs not initialized. Call initializeTypeIdSets() first.");
+	return decimalTypeId;
+}
+
+//#endregion
+export { getArrowModule, getDecimalTypeId, getTypeIdSets, initializeTypeIdSets };
+//# sourceMappingURL=lazy-arrow.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-arrow.js","names":["arrowModulePromise: Promise<typeof import(\"apache-arrow\")> | null","temporalTypeIds: Set<number> | null","numericTypeIds: Set<number> | null","stringTypeIds: Set<number> | null","decimalTypeId: number | null"],"sources":["../../../src/js/arrow/lazy-arrow.ts"],"sourcesContent":["/**\n * Lazy loader for Apache Arrow library.\n * The arrow library is substantial (~200KB+ gzipped), so we only load it\n * when Arrow format is actually used.\n *\n * This module caches the import promise to ensure the library is only\n * loaded once, even if multiple components request it simultaneously.\n */\n\nimport type { Table, Field } from \"apache-arrow\";\n\n// Re-export types for convenience (types don't add to bundle size)\nexport type { Table, Field };\n\n// ============================================================================\n// Lazy Module Loading\n// ============================================================================\n\n// Cache the import promise to avoid multiple loads\nlet arrowModulePromise: Promise<typeof import(\"apache-arrow\")> | null = null;\n\n/**\n * Lazily loads the Apache Arrow library.\n * Returns cached module if already loaded.\n *\n * @example\n * ```typescript\n * const arrow = await getArrowModule();\n * const table = arrow.tableFromIPC(buffer);\n * ```\n */\nexport async function getArrowModule(): Promise<typeof import(\"apache-arrow\")> {\n  if (!arrowModulePromise) {\n    arrowModulePromise = import(\"apache-arrow\");\n  }\n  return arrowModulePromise;\n}\n\n// ============================================================================\n// Cached Type ID Sets\n// ============================================================================\n\n// These are initialized lazily when Arrow is first loaded\nlet temporalTypeIds: Set<number> | null = null;\nlet numericTypeIds: Set<number> | null = null;\nlet stringTypeIds: Set<number> | null = null;\nlet decimalTypeId: number | null = null;\n\n/**\n * Initializes the type ID sets from the Arrow Type enum.\n * Call this after loading the Arrow module.\n */\nexport async function initializeTypeIdSets(): Promise<void> {\n  if (temporalTypeIds !== null) return; // Already initialized\n\n  const { Type } = await getArrowModule();\n\n  temporalTypeIds = new Set([\n    Type.Date,\n    Type.DateDay,\n    Type.DateMillisecond,\n    Type.Timestamp,\n    Type.TimestampSecond,\n    Type.TimestampMillisecond,\n    Type.TimestampMicrosecond,\n    Type.TimestampNanosecond,\n    Type.Time,\n    Type.TimeSecond,\n    Type.TimeMillisecond,\n    Type.TimeMicrosecond,\n    Type.TimeNanosecond,\n  ]);\n\n  numericTypeIds = new Set([\n    Type.Int,\n    Type.Int8,\n    Type.Int16,\n    Type.Int32,\n    Type.Int64,\n    Type.Uint8,\n    Type.Uint16,\n    Type.Uint32,\n    Type.Uint64,\n    Type.Float,\n    Type.Float16,\n    Type.Float32,\n    Type.Float64,\n    Type.Decimal,\n  ]);\n\n  stringTypeIds = new Set([Type.Utf8, Type.LargeUtf8]);\n\n  decimalTypeId = Type.Decimal;\n}\n\n/**\n * Returns the cached type ID sets.\n * Throws if called before initializeTypeIdSets().\n * This is safe because you can't have a Table without first loading Arrow.\n */\nexport function getTypeIdSets(): {\n  temporal: Set<number>;\n  numeric: Set<number>;\n  string: Set<number>;\n} {\n  if (!temporalTypeIds || !numericTypeIds || !stringTypeIds) {\n    throw new Error(\n      \"Arrow type IDs not initialized. Call initializeTypeIdSets() first.\",\n    );\n  }\n  return {\n    temporal: temporalTypeIds,\n    numeric: numericTypeIds,\n    string: stringTypeIds,\n  };\n}\n\n/**\n * Returns the Decimal type ID.\n * Throws if called before initializeTypeIdSets().\n */\nexport function getDecimalTypeId(): number {\n  if (decimalTypeId === null) {\n    throw new Error(\n      \"Arrow type IDs not initialized. Call initializeTypeIdSets() first.\",\n    );\n  }\n  return decimalTypeId;\n}\n"],"mappings":";AAmBA,IAAIA,qBAAoE;;;;;;;;;;;AAYxE,eAAsB,iBAAyD;AAC7E,KAAI,CAAC,mBACH,sBAAqB,OAAO;AAE9B,QAAO;;AAQT,IAAIC,kBAAsC;AAC1C,IAAIC,iBAAqC;AACzC,IAAIC,gBAAoC;AACxC,IAAIC,gBAA+B;;;;;AAMnC,eAAsB,uBAAsC;AAC1D,KAAI,oBAAoB,KAAM;CAE9B,MAAM,EAAE,SAAS,MAAM,gBAAgB;AAEvC,mBAAkB,IAAI,IAAI;EACxB,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACN,CAAC;AAEF,kBAAiB,IAAI,IAAI;EACvB,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACN,CAAC;AAEF,iBAAgB,IAAI,IAAI,CAAC,KAAK,MAAM,KAAK,UAAU,CAAC;AAEpD,iBAAgB,KAAK;;;;;;;AAQvB,SAAgB,gBAId;AACA,KAAI,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,cAC1C,OAAM,IAAI,MACR,qEACD;AAEH,QAAO;EACL,UAAU;EACV,SAAS;EACT,QAAQ;EACT;;;;;;AAOH,SAAgB,mBAA2B;AACzC,KAAI,kBAAkB,KACpB,OAAM,IAAI,MACR,qEACD;AAEH,QAAO"}

package/dist/js/constants.d.ts

@@ -0,0 +1,10 @@
+//#region src/js/constants.d.ts
+/** Field patterns to detect date/time fields by name */
+declare const DATE_FIELD_PATTERNS: readonly ["date", "time", "period", "timestamp"];
+/** Field patterns to detect name/category fields by name */
+declare const NAME_FIELD_PATTERNS: readonly ["name", "label", "app", "user", "creator", "browser", "category"];
+/** Patterns that indicate a date field is metadata, not for charting */
+declare const METADATA_DATE_PATTERNS: readonly ["created", "updated", "modified", "deleted", "last_"];
+//#endregion
+export { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS };
+//# sourceMappingURL=constants.d.ts.map

package/dist/js/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","names":[],"sources":["../../src/js/constants.ts"],"sourcesContent":[],"mappings":";;AAOa,cAAA,mBAKH,EAAA,SAAA,CAAA,MAAA,EAAA,MAAA,EAAA,QAAA,EAAA,WAAA,CAAA;AAGV;AAWa,cAXA,mBAiBH,EAAA,SAAA,CAAA,MAAA,EAAA,OAAA,EAAA,KAAA,EAAA,MAAA,EAAA,SAAA,EAAA,SAAA,EAAA,UAAA,CAAA;;cANG"}

package/dist/js/constants.js

@@ -0,0 +1,30 @@
+//#region src/js/constants.ts
+/** Field patterns to detect date/time fields by name */
+const DATE_FIELD_PATTERNS = [
+	"date",
+	"time",
+	"period",
+	"timestamp"
+];
+/** Field patterns to detect name/category fields by name */
+const NAME_FIELD_PATTERNS = [
+	"name",
+	"label",
+	"app",
+	"user",
+	"creator",
+	"browser",
+	"category"
+];
+/** Patterns that indicate a date field is metadata, not for charting */
+const METADATA_DATE_PATTERNS = [
+	"created",
+	"updated",
+	"modified",
+	"deleted",
+	"last_"
+];
+
+//#endregion
+export { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS };
+//# sourceMappingURL=constants.js.map

package/dist/js/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../src/js/constants.ts"],"sourcesContent":["// ============================================================================\n// Shared Constants for Field Detection\n// ============================================================================\n// These patterns are used by both Arrow processing and chart normalization\n// to detect field types from column names.\n\n/** Field patterns to detect date/time fields by name */\nexport const DATE_FIELD_PATTERNS = [\n  \"date\",\n  \"time\",\n  \"period\",\n  \"timestamp\",\n] as const;\n\n/** Field patterns to detect name/category fields by name */\nexport const NAME_FIELD_PATTERNS = [\n  \"name\",\n  \"label\",\n  \"app\",\n  \"user\",\n  \"creator\",\n  \"browser\",\n  \"category\",\n] as const;\n\n/** Patterns that indicate a date field is metadata, not for charting */\nexport const METADATA_DATE_PATTERNS = [\n  \"created\",\n  \"updated\",\n  \"modified\",\n  \"deleted\",\n  \"last_\",\n] as const;\n"],"mappings":";;AAOA,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACD;;AAGD,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;AAGD,MAAa,yBAAyB;CACpC;CACA;CACA;CACA;CACA;CACD"}

package/dist/js/index.d.ts

@@ -0,0 +1,8 @@
+import { SQLBinaryMarker, SQLBooleanMarker, SQLDateMarker, SQLNumberMarker, SQLStringMarker, SQLTimestampMarker, SQLTypeMarker } from "../shared/src/sql/types.js";
+import { isSQLTypeMarker, sql } from "../shared/src/sql/helpers.js";
+import { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS } from "./constants.js";
+import { ArrowClient, DetectedFields, Field, Table } from "./arrow/arrow-client.js";
+import { getArrowModule, initializeTypeIdSets } from "./arrow/lazy-arrow.js";
+import { ConnectSSEOptions, SSEMessage } from "./sse/types.js";
+import { connectSSE } from "./sse/connect-sse.js";
+export { ArrowClient, ConnectSSEOptions, DATE_FIELD_PATTERNS, DetectedFields, Field, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS, type SQLBinaryMarker, type SQLBooleanMarker, type SQLDateMarker, type SQLNumberMarker, type SQLStringMarker, type SQLTimestampMarker, type SQLTypeMarker, SSEMessage, Table, connectSSE, getArrowModule, initializeTypeIdSets, isSQLTypeMarker, sql };

package/dist/js/index.js

@@ -0,0 +1,8 @@
+import { isSQLTypeMarker, sql } from "../shared/src/sql/helpers.js";
+import { DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS } from "./constants.js";
+import { getArrowModule, initializeTypeIdSets } from "./arrow/lazy-arrow.js";
+import { ArrowClient } from "./arrow/arrow-client.js";
+import "./arrow/index.js";
+import { connectSSE } from "./sse/connect-sse.js";
+
+export { ArrowClient, DATE_FIELD_PATTERNS, METADATA_DATE_PATTERNS, NAME_FIELD_PATTERNS, connectSSE, getArrowModule, initializeTypeIdSets, isSQLTypeMarker, sql };

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

@@ -0,0 +1,14 @@
+import { ConnectSSEOptions } from "./types.js";
+
+//#region src/js/sse/connect-sse.d.ts
+
+/**
+ * Connects to an SSE endpoint with automatic retries and exponential backoff
+ * @param options - SSE connection options
+ * @param attempt - Internal retry attempt counter
+ * @returns Promise that resolves when the stream ends or retries stop
+ */
+declare function connectSSE<Payload = unknown>(options: ConnectSSEOptions<Payload>, attempt?: number): Promise<void>;
+//#endregion
+export { connectSSE };
+//# sourceMappingURL=connect-sse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connect-sse.d.ts","names":[],"sources":["../../../src/js/sse/connect-sse.ts"],"sourcesContent":[],"mappings":";;;;;;AAQA;;;;AAEa,iBAFS,UAET,CAAA,UAAA,OAAA,CAAA,CAAA,OAAA,EADF,iBACE,CADgB,OAChB,CAAA,EAAA,OAAA,CAAA,EAAA,MAAA,CAAA,EAAA,OAAA,CAAA,IAAA,CAAA"}

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

@@ -0,0 +1,128 @@
+//#region src/js/sse/connect-sse.ts
+/**
+* Connects to an SSE endpoint with automatic retries and exponential backoff
+* @param options - SSE connection options
+* @param attempt - Internal retry attempt counter
+* @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;
+	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.");
+	const headers = { Accept: "text/event-stream" };
+	const hasPayload = typeof payload !== "undefined";
+	if (hasPayload) headers["Content-Type"] = "application/json";
+	let lastEventId = initialLastEventId;
+	if (lastEventId) headers["Last-Event-ID"] = lastEventId;
+	const method = hasPayload ? "POST" : "GET";
+	const body = hasPayload ? typeof payload === "string" ? payload : JSON.stringify(payload) : void 0;
+	const timeoutController = new AbortController();
+	const timeoutId = setTimeout(() => timeoutController.abort(), timeout);
+	const combinedSignal = signal ? createCombinedSignal(signal, timeoutController.signal) : timeoutController.signal;
+	try {
+		const response = await fetch(url, {
+			headers,
+			method,
+			body,
+			signal: combinedSignal
+		});
+		clearTimeout(timeoutId);
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		if (!response.body) throw new Error("No response body");
+		const reader = response.body.getReader();
+		const decoder = new TextDecoder("utf-8");
+		let buffer = "";
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			const decoded = decoder.decode(value, { stream: true });
+			if (buffer.length + decoded.length > maxBufferSize) throw new Error("Buffer size exceeded");
+			buffer += decoded;
+			const parts = buffer.replace(/\r\n/g, "\n").split("\n\n");
+			buffer = parts.pop() ?? "";
+			for (const part of parts) {
+				const message = parseSSEEvent(part);
+				if (!message) continue;
+				if (message.id) lastEventId = message.id;
+				onMessage({
+					id: lastEventId ?? "",
+					data: message.data
+				});
+			}
+		}
+	} catch (error) {
+		clearTimeout(timeoutId);
+		if (onError) onError(error);
+		if (signal?.aborted) return;
+		if (attempt >= maxRetries) {
+			console.warn(`[connectSSE] Max retries (${maxRetries}) exceeded for ${url}`);
+			return;
+		}
+		const nextAttempt = attempt + 1;
+		const delayMs = computeExponentialDelay(nextAttempt, retryDelay);
+		if (delayMs <= 0) return;
+		await new Promise((resolve) => {
+			setTimeout(() => {
+				connectSSE({
+					...options,
+					lastEventId
+				}, nextAttempt).finally(resolve);
+			}, delayMs);
+		});
+	}
+}
+/**
+* Parses a raw SSE event chunk into a message
+* @param chunk - Raw SSE event block
+* @returns Parsed message or null when no data lines are present
+* @private
+*/
+function parseSSEEvent(chunk) {
+	const lines = chunk.replace(/\r\n/g, "\n").split("\n");
+	let id;
+	const dataLines = [];
+	for (const rawLine of lines) {
+		const line = rawLine.trimEnd();
+		if (line === "") continue;
+		if (line.startsWith(":")) continue;
+		if (line.startsWith("id:")) id = line.slice(3).trimStart();
+		else if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+	}
+	if (dataLines.length === 0) return null;
+	return {
+		id: id ?? "",
+		data: dataLines.join("\n")
+	};
+}
+/**
+* Compute exponential backoff delay in milliseconds.
+* Uses a random jitter factor to avoid thundering herd problem.
+* @param attempt - Retry attempt number (1-based)
+* @param baseDelayMs - Base delay in milliseconds
+* @returns Delay in milliseconds for this attempt
+*/
+function computeExponentialDelay(attempt, baseDelayMs) {
+	const safeAttempt = Math.max(1, attempt);
+	const rawDelayMs = baseDelayMs * Math.min(2 ** (safeAttempt - 1), 32);
+	const jitter = rawDelayMs * .2;
+	const randomizedDelayMs = rawDelayMs + Math.random() * jitter;
+	return Math.max(0, Math.floor(randomizedDelayMs));
+}
+/**
+* Combines two abort signals into a single abort signal
+* @param signal1 - First abort signal
+* @param signal2 - Second abort signal
+* @returns Combined signal
+*/
+function createCombinedSignal(signal1, signal2) {
+	const controller = new AbortController();
+	const abort = () => controller.abort();
+	signal1.addEventListener("abort", abort);
+	signal2.addEventListener("abort", abort);
+	return controller.signal;
+}
+
+//#endregion
+export { connectSSE };
+//# sourceMappingURL=connect-sse.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connect-sse.js","names":["headers: HeadersInit","id: string | undefined","dataLines: string[]"],"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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"}

package/dist/js/sse/types.d.ts

@@ -0,0 +1,34 @@
+//#region src/js/sse/types.d.ts
+/** Single SSE message payload. */
+type SSEMessage = {
+  /** Event id from server */
+  id: string;
+  /** Raw data payload */
+  data: string;
+};
+/** Options for opening a resilient SSE connection */
+interface ConnectSSEOptions<Payload = unknown> {
+  /** SSE endpoint URL */
+  url: string;
+  /** Optional request payload for POST */
+  payload?: Payload | string;
+  /** Called for each SSE message. */
+  onMessage: (message: SSEMessage) => Promise<void>;
+  /** Abort signal to stop streaming and retries. */
+  signal?: AbortSignal;
+  /** Last event id used to resume the stream. */
+  lastEventId?: string | null;
+  /** Base delay in ms for retry backoff. */
+  retryDelay?: number;
+  /** Maximum number of retry attempts */
+  maxRetries?: number;
+  /** Request timeout in ms */
+  timeout?: number;
+  /** Max in-memory buffer size before error. */
+  maxBufferSize?: number;
+  /** Called when a connection or parsing error occurs. */
+  onError?: (error: unknown) => void;
+}
+//#endregion
+export { ConnectSSEOptions, SSEMessage };
+//# sourceMappingURL=types.d.ts.map

package/dist/js/sse/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/js/sse/types.ts"],"sourcesContent":[],"mappings":";;AACY,KAAA,UAAA,GAAU;EAQL;EAAiB,EAAA,EAAA,MAAA;;MAMX,EAAA,MAAA;;;AAED,UARL,iBAQK,CAAA,UAAA,OAAA,CAAA,CAAA;;;;YAJV;;uBAEW,eAAe;;WAE3B"}