@sksat/uneri 0.1.1

package/dist/components/TimeSeriesChart.d.ts

@@ -0,0 +1,70 @@
+import uPlot from "uplot";
+import "uplot/dist/uPlot.min.css";
+/**
+ * Custom y-axis range function that prevents uPlot's axis split function
+ * from crashing with near-constant data.
+ *
+ * When all y-values are nearly identical, the default range calculation
+ * produces such a tiny axis range that the tick generation loop tries to
+ * create an impossibly large array (RangeError: Invalid array length).
+ *
+ * Enforces a minimum visible range proportional to the data's magnitude.
+ */
+export declare function safeYRange(_u: uPlot, dataMin: number, dataMax: number, _scaleKey: string): uPlot.Range.MinMax;
+/**
+ * Convert Float64Array to a regular array, replacing NaN with null.
+ *
+ * uPlot cannot recognise NaN inside Float64Array as gaps — it only handles
+ * null/undefined in plain arrays.  alignTimeSeries() returns Float64Array
+ * with NaN for missing points, so this bridge is needed before handing
+ * the data to uPlot.
+ */
+export declare function float64NanToNull(arr: Float64Array): (number | null)[];
+/** Configuration for a single series in a multi-series chart. */
+export interface SeriesConfig {
+    label: string;
+    color: string;
+}
+/** Multi-series data: shared x-axis + multiple y arrays. */
+export interface MultiSeriesData {
+    /** Shared time axis. */
+    t: Float64Array;
+    /** One Float64Array per series (NaN for gaps). */
+    values: Float64Array[];
+    /** Config for each series (same order as values[]). */
+    series: SeriesConfig[];
+}
+/**
+ * Compute Grafana-style legend isolation visibility.
+ *
+ * Click a series → isolate (show only that series).
+ * Click the already-isolated series → show all.
+ *
+ * @param clickedIndex 1-based uPlot series index (0 = x-axis, ignored)
+ * @param currentShow  Current visibility, indexed 0..N where 0 is x-axis
+ * @returns New visibility array (same length as currentShow)
+ */
+export declare function computeLegendIsolation(clickedIndex: number, currentShow: boolean[]): boolean[];
+/**
+ * Build uPlot series config array from SeriesConfig[].
+ *
+ * spanGaps is enabled because aligned multi-series data contains null gaps
+ * (from float64NanToNull) at time points where a series has no value.
+ * Each series should render as a continuous line across those gaps.
+ */
+export declare function buildMultiSeriesConfig(configs: SeriesConfig[]): uPlot.Series[];
+interface TimeSeriesChartProps {
+    title: string;
+    yLabel: string;
+    /** Single-series data: [xValues, yValues]. */
+    data?: [Float64Array, Float64Array] | null;
+    /** Multi-series data (takes precedence over `data`). */
+    multiData?: MultiSeriesData | null;
+    height?: number;
+    /** Color for single-series mode. Ignored when multiData is used. */
+    color?: string;
+    /** Called when the user zooms into a time range via drag. */
+    onZoom?: (tMin: number, tMax: number) => void;
+}
+export declare function TimeSeriesChart({ title, yLabel, data, multiData, height, color, onZoom, }: TimeSeriesChartProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/db/IngestBuffer.d.ts

@@ -0,0 +1,59 @@
+import type { TimePoint } from "../types.js";
+/**
+ * Staging buffer for DuckDB ingestion.
+ *
+ * Accumulates incoming data points and provides them in batches
+ * via `drain()`. The drain pattern decouples data arrival from
+ * DuckDB insertion timing (polling interval), avoiding the need
+ * for index-based tracking.
+ *
+ * **Contract**: `t` values pushed to this buffer MUST be strictly
+ * monotonically increasing. Out-of-order data will be silently missed
+ * by incremental queries. This is guaranteed by the orts simulator
+ * (simulation time always advances). Consumers using uneri with other
+ * data sources must enforce this property.
+ */
+export declare class IngestBuffer<T extends TimePoint = TimePoint> {
+    private pending;
+    private _latestT;
+    private _rebuildData;
+    /** Push a single point. Must satisfy t > latestT (strictly increasing). */
+    push(point: T): void;
+    /** Push multiple points at once (appended to end). */
+    pushMany(points: T[]): void;
+    /**
+     * Prepend points to the front of the buffer.
+     * Used for re-queuing failed insert batches: since new points may have
+     * arrived in `pending` during the async insert, appending the failed
+     * batch would break t-monotonicity. Prepending preserves order.
+     */
+    prependMany(points: T[]): void;
+    /**
+     * Drain all pending points, returning them and clearing the buffer.
+     * Returns an empty array if nothing is pending.
+     */
+    drain(): T[];
+    /**
+     * Signal a full table rebuild. The tick loop should clear the DuckDB table
+     * and insert the returned data from `consumeRebuild()`.
+     *
+     * Clears any stale pending points to prevent duplicates (fullData is
+     * the complete replacement dataset). Points pushed after this call
+     * are treated as genuinely new and will be included by consumeRebuild().
+     */
+    markRebuild(fullData: T[]): void;
+    /**
+     * Consume a pending rebuild signal. Returns the rebuild data merged
+     * with any points pushed since markRebuild(), or null if no rebuild
+     * is pending. The rebuild flag and pending buffer are both cleared.
+     */
+    consumeRebuild(): T[] | null;
+    /** Number of points waiting to be drained. */
+    get pendingCount(): number;
+    /**
+     * The latest t value seen across all pushed points.
+     * Used for timeRange calculation in chart components.
+     * Returns -Infinity if no points have been pushed.
+     */
+    get latestT(): number;
+}

package/dist/db/duckdb.d.ts

@@ -0,0 +1,6 @@
+import * as duckdb from "@duckdb/duckdb-wasm";
+/**
+ * Initialize DuckDB-wasm (singleton). Uses jsDelivr CDN for WASM bundles.
+ * Safe to call multiple times — returns the same promise.
+ */
+export declare function initDuckDB(): Promise<duckdb.AsyncDuckDB>;

package/dist/db/store.d.ts

@@ -0,0 +1,94 @@
+import type { AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
+import type { ChartDataMap, TableSchema, TimePoint } from "../types.js";
+import type { RowTuple } from "../worker/protocol.js";
+/**
+ * Generate a CREATE OR REPLACE TABLE statement from a schema definition.
+ */
+export declare function buildCreateTableSQL(schema: TableSchema): string;
+/**
+ * Generate an INSERT INTO ... VALUES statement from pre-converted row tuples.
+ * This is the core SQL builder used by both `buildInsertSQL` (with toRow)
+ * and the chart data Worker (which receives already-converted tuples).
+ * Returns an empty string when the batch is empty.
+ */
+export declare function buildInsertSQLFromRows(tableName: string, rows: RowTuple[]): string;
+/**
+ * Generate an INSERT INTO ... VALUES statement for a batch of points.
+ * Delegates to `buildInsertSQLFromRows` after converting via `schema.toRow()`.
+ * Returns an empty string when the batch is empty.
+ */
+export declare function buildInsertSQL<T extends TimePoint>(schema: TableSchema<T>, points: T[]): string;
+/**
+ * Build a SELECT query for derived quantities with optional query-time
+ * downsampling via time-bucket partitioning.
+ *
+ * When maxPoints is specified and > 0, divides the time range into
+ * maxPoints equal-duration buckets and picks the first point in each
+ * bucket. This ensures even *temporal* coverage regardless of data
+ * density — critical when sparse overview data and dense streaming
+ * data coexist in the same table.
+ */
+export declare function buildDerivedQuery(schema: TableSchema, tMin?: number, maxPoints?: number, tMax?: number): string;
+/**
+ * Build SQL to create a temp table of "keeper" t values from old data.
+ * Uses NTILE to divide old rows into equal-count buckets, keeping the
+ * earliest t (MIN) from each bucket as the representative point.
+ */
+export declare function buildCompactKeepersSQL(tableName: string, cutoffT: number, targetOldRows: number): string;
+/**
+ * Build SQL to delete non-keeper old rows (those older than cutoff
+ * and not in the keepers temp table).
+ */
+export declare function buildCompactDeleteSQL(tableName: string, cutoffT: number): string;
+/**
+ * Create (or replace) the table described by the schema.
+ */
+export declare function createTable(conn: AsyncDuckDBConnection, schema: TableSchema): Promise<void>;
+/**
+ * Insert an array of points into the table in batches of 1000.
+ */
+export declare function insertPoints<T extends TimePoint>(conn: AsyncDuckDBConnection, schema: TableSchema<T>, points: T[]): Promise<void>;
+/**
+ * Delete all rows from the table.
+ */
+export declare function clearTable(conn: AsyncDuckDBConnection, schema: TableSchema): Promise<void>;
+/**
+ * Run the derived query and return results as a ChartDataMap.
+ */
+export declare function queryDerived(conn: AsyncDuckDBConnection, schema: TableSchema, tMin?: number, maxPoints?: number, tMax?: number): Promise<ChartDataMap>;
+/**
+ * Build a simple SELECT for new rows after `tAfter`, with no downsampling.
+ * Used for the hot path in cold/hot incremental updates.
+ *
+ * Relies on the monotonicity contract: t is strictly increasing, so
+ * `t > tAfter` with strict inequality avoids re-fetching the boundary point.
+ *
+ * Derived columns must be row-local (no window functions or aggregation).
+ */
+export declare function buildIncrementalQuery(schema: TableSchema, tAfter: number): string;
+/**
+ * Run the incremental query and return results as a ChartDataMap.
+ * No downsampling — returns all rows matching the condition.
+ */
+export declare function queryDerivedIncremental(conn: AsyncDuckDBConnection, schema: TableSchema, tAfter: number): Promise<ChartDataMap>;
+/** Configuration for periodic DuckDB compaction. */
+export interface CompactOptions {
+    /** Compact when total rows exceed this threshold. */
+    maxRows: number;
+    /** Keep this many recent rows at full resolution. */
+    keepRecentRows: number;
+    /** Downsample old data to this many representative rows. */
+    targetOldRows: number;
+}
+/** Default compaction thresholds (see plan for rationale). */
+export declare const COMPACT_DEFAULTS: CompactOptions;
+/**
+ * Compact old data in DuckDB to control memory usage.
+ *
+ * Keeps the most recent `keepRecentRows` at full resolution and
+ * downsamples older rows to `targetOldRows` using NTILE bucketing.
+ * Returns true if compaction was performed.
+ *
+ * Assumes t values are unique (one per simulation step).
+ */
+export declare function compactTable(conn: AsyncDuckDBConnection, schema: TableSchema, opts?: CompactOptions): Promise<boolean>;

package/dist/hooks/useDuckDB.d.ts

@@ -0,0 +1,9 @@
+import type { AsyncDuckDB, AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
+import type { TableSchema } from "../types.js";
+export interface UseDuckDBReturn {
+    db: AsyncDuckDB | null;
+    conn: AsyncDuckDBConnection | null;
+    isReady: boolean;
+    error: string | null;
+}
+export declare function useDuckDB(schema: TableSchema): UseDuckDBReturn;

package/dist/hooks/useTimeSeriesStore.d.ts

@@ -0,0 +1,35 @@
+import type { AsyncDuckDBConnection } from "@duckdb/duckdb-wasm";
+import type { IngestBuffer } from "../db/IngestBuffer.js";
+import type { CompactOptions } from "../db/store.js";
+import type { ChartDataMap, TableSchema, TimePoint } from "../types.js";
+/** Maximum number of points to display in charts. Query-time downsampling
+ *  keeps chart rendering fast regardless of total data in DuckDB. */
+export declare const DISPLAY_MAX_POINTS = 2000;
+/** Time range for chart display: null = all history, number = last N seconds. */
+export type TimeRange = number | null;
+/** Compute the minimum t value for a chart query given a time range window. */
+export declare function computeTMin(timeRange: TimeRange, latestT: number): number | undefined;
+export interface UseTimeSeriesStoreOptions<T extends TimePoint> {
+    conn: AsyncDuckDBConnection | null;
+    schema: TableSchema<T>;
+    ingestBufferRef: React.RefObject<IngestBuffer<T>>;
+    /** Show only last N seconds of data, or null for all history. */
+    timeRange?: TimeRange;
+    /** Maximum number of points to display (default: DISPLAY_MAX_POINTS). */
+    maxPoints?: number;
+    /** Polling interval in ms for realtime mode (default: 250). */
+    tickInterval?: number;
+    /** Run cold (full downsampled) refresh every Nth tick (default: 20). */
+    coldRefreshEveryN?: number;
+    /** Trigger cold refresh when hot buffer exceeds this many rows (default: 500). */
+    hotRowBudget?: number;
+    /** Run compaction check every Nth cold refresh (default: 5). */
+    compactEveryN?: number;
+    /** Compaction configuration (default: COMPACT_DEFAULTS). */
+    compactOptions?: CompactOptions;
+}
+export interface UseTimeSeriesStoreReturn {
+    data: ChartDataMap | null;
+    isLoading: boolean;
+}
+export declare function useTimeSeriesStore<T extends TimePoint>(options: UseTimeSeriesStoreOptions<T>): UseTimeSeriesStoreReturn;

package/dist/hooks/useTimeSeriesStoreWorker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Worker-based alternative to useTimeSeriesStore.
+ *
+ * Moves the entire DuckDB tick loop (insert, query, merge, trim) to a
+ * dedicated Web Worker, keeping the main thread free for rendering.
+ *
+ * Same return type as useTimeSeriesStore for drop-in replacement.
+ */
+import type { IngestBuffer } from "../db/IngestBuffer.js";
+import type { TableSchema, TimePoint } from "../types.js";
+import { ChartDataWorkerClient } from "../worker/chartDataWorkerClient.js";
+import { type TimeRange, type UseTimeSeriesStoreReturn } from "./useTimeSeriesStore.js";
+export interface UseTimeSeriesStoreWorkerOptions<T extends TimePoint> {
+    schema: TableSchema<T>;
+    ingestBufferRef: React.RefObject<IngestBuffer<T>>;
+    /** Show only last N seconds of data, or null for all history. */
+    timeRange?: TimeRange;
+    /** Maximum number of points to display (default: DISPLAY_MAX_POINTS). */
+    maxPoints?: number;
+    /** Polling interval in ms for draining the IngestBuffer (default: 250). */
+    drainInterval?: number;
+    /** Worker tick interval in ms (default: 250). */
+    tickInterval?: number;
+    /** Run cold (full downsampled) refresh every Nth tick (default: 20). */
+    coldRefreshEveryN?: number;
+    /** Trigger cold refresh when hot buffer exceeds this many rows (default: 500). */
+    hotRowBudget?: number;
+    /** Optional ref to receive the worker client instance (for debug queries etc.). */
+    clientRef?: React.MutableRefObject<ChartDataWorkerClient | null>;
+    /** Set to false to disable the Worker (no Worker is spawned). Default: true. */
+    enabled?: boolean;
+}
+export declare function useTimeSeriesStoreWorker<T extends TimePoint>(options: UseTimeSeriesStoreWorkerOptions<T>): UseTimeSeriesStoreReturn;

package/dist/index.css

@@ -0,0 +1,2 @@
+.uplot,.uplot *,.uplot :before,.uplot :after{box-sizing:border-box}.uplot{width:min-content;font-family:system-ui,-apple-system,Segoe UI,Roboto,Helvetica Neue,Arial,Noto Sans,sans-serif,Apple Color Emoji,Segoe UI Emoji,Segoe UI Symbol,Noto Color Emoji;line-height:1.5}.u-title{text-align:center;font-size:18px;font-weight:700}.u-wrap{-webkit-user-select:none;user-select:none;position:relative}.u-over,.u-under{position:absolute}.u-under{overflow:hidden}.uplot canvas{width:100%;height:100%;display:block;position:relative}.u-axis{position:absolute}.u-legend{text-align:center;margin:auto;font-size:14px}.u-inline{display:block}.u-inline *{display:inline-block}.u-inline tr{margin-right:16px}.u-legend th{font-weight:600}.u-legend th>*{vertical-align:middle;display:inline-block}.u-legend .u-marker{width:1em;height:1em;margin-right:4px;background-clip:padding-box!important}.u-inline.u-live th:after{content:":";vertical-align:middle}.u-inline:not(.u-live) .u-value{display:none}.u-series>*{padding:4px}.u-series th{cursor:pointer}.u-legend .u-off>*{opacity:.3}.u-select{pointer-events:none;background:#00000012;position:absolute}.u-cursor-x,.u-cursor-y{pointer-events:none;will-change:transform;position:absolute;top:0;left:0}.u-hz .u-cursor-x,.u-vt .u-cursor-y{border-right:1px dashed #607d8b;height:100%}.u-hz .u-cursor-y,.u-vt .u-cursor-x{border-bottom:1px dashed #607d8b;width:100%}.u-cursor-pt{pointer-events:none;will-change:transform;border:0 solid;border-radius:50%;position:absolute;top:0;left:0;background-clip:padding-box!important}.u-axis.u-off,.u-select.u-off,.u-cursor-x.u-off,.u-cursor-y.u-off,.u-cursor-pt.u-off{display:none}
+/*$vite$:1*/

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export type { MultiSeriesData, SeriesConfig, } from "./components/TimeSeriesChart.js";
+export { buildMultiSeriesConfig, safeYRange, TimeSeriesChart, } from "./components/TimeSeriesChart.js";
+export { initDuckDB } from "./db/duckdb.js";
+export { IngestBuffer } from "./db/IngestBuffer.js";
+export type { CompactOptions } from "./db/store.js";
+export { buildCompactDeleteSQL, buildCompactKeepersSQL, buildCreateTableSQL, buildDerivedQuery, buildIncrementalQuery, buildInsertSQL, buildInsertSQLFromRows, COMPACT_DEFAULTS, clearTable, compactTable, createTable, insertPoints, queryDerived, queryDerivedIncremental, } from "./db/store.js";
+export type { UseDuckDBReturn } from "./hooks/useDuckDB.js";
+export { useDuckDB } from "./hooks/useDuckDB.js";
+export type { TimeRange, UseTimeSeriesStoreOptions, UseTimeSeriesStoreReturn, } from "./hooks/useTimeSeriesStore.js";
+export { computeTMin, DISPLAY_MAX_POINTS, useTimeSeriesStore, } from "./hooks/useTimeSeriesStore.js";
+export type { UseTimeSeriesStoreWorkerOptions } from "./hooks/useTimeSeriesStoreWorker.js";
+export { useTimeSeriesStoreWorker } from "./hooks/useTimeSeriesStoreWorker.js";
+export type { ChartDataMap, ColumnDef, ColumnType, DerivedColumn, TableSchema, TimePoint, } from "./types.js";
+export type { AlignedMultiSeries, NamedTimeSeries, } from "./utils/alignTimeSeries.js";
+export { alignTimeSeries } from "./utils/alignTimeSeries.js";
+export { ChartBuffer } from "./utils/ChartBuffer.js";
+export { lowerBound, quantizeChartTime, sliceArrays, upperBound, } from "./utils/chartViewport.js";
+export { mergeChartData, trimChartDataLeft } from "./utils/mergeChartData.js";
+export { ChartDataWorkerClient } from "./worker/chartDataWorkerClient.js";
+export type { RowTuple, WorkerTableSchema } from "./worker/protocol.js";