@sksat/uneri 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+/** Minimum requirement for a data point: must have a time field. */
+export interface TimePoint {
+    readonly t: number;
+}
+/** SQL column type supported by DuckDB. */
+export type ColumnType = "DOUBLE" | "INTEGER" | "BIGINT" | "FLOAT";
+/** Defines a single column in the time-series table. */
+export interface ColumnDef {
+    name: string;
+    type: ColumnType;
+}
+/**
+ * Defines a derived quantity computed from base columns via SQL.
+ *
+ * **Constraint**: `sql` MUST be a row-local expression — it may only
+ * reference columns from the same row. Window functions (LAG, LEAD,
+ * AVG(...) OVER, ROW_NUMBER OVER, etc.) and correlated subqueries are
+ * NOT supported and will produce incorrect results with incremental queries.
+ */
+export interface DerivedColumn {
+    name: string;
+    sql: string;
+    unit?: string;
+}
+/** Full schema definition for a time-series table. */
+export interface TableSchema<T extends TimePoint = TimePoint> {
+    tableName: string;
+    columns: ColumnDef[];
+    derived: DerivedColumn[];
+    toRow(point: T): (number | null)[];
+}
+/** Generic chart data: keyed by column name. */
+export type ChartDataMap = {
+    t: Float64Array;
+    [derivedName: string]: Float64Array;
+};

package/dist/utils/ChartBuffer.d.ts

@@ -0,0 +1,57 @@
+import type { ChartDataMap } from "../types.js";
+/**
+ * Column-oriented ring buffer for real-time chart display.
+ *
+ * Stores time-series data as Float64Arrays keyed by column name,
+ * matching the ChartDataMap shape expected by uPlot. Supports
+ * efficient append and left-trim operations.
+ *
+ * Used as a DuckDB bypass: during live streaming, data flows
+ * directly from WebSocket → ChartBuffer → uPlot.setData().
+ */
+export declare class ChartBuffer {
+    private _columns;
+    private _data;
+    private _length;
+    private _capacity;
+    /**
+     * @param columns Column names (must include "t" as the time axis).
+     * @param capacity Maximum number of points before oldest are dropped.
+     */
+    constructor(columns: string[], capacity: number);
+    get length(): number;
+    get capacity(): number;
+    get columns(): readonly string[];
+    /**
+     * Append a single row of values.
+     * @param values Object with a value for each column name.
+     */
+    push(values: Record<string, number>): void;
+    /**
+     * Append multiple rows at once.
+     * @param rows Array of value objects, one per row.
+     */
+    pushMany(rows: Record<string, number>[]): void;
+    /**
+     * Get a snapshot of the current data as ChartDataMap.
+     * Returns subarray views (zero-copy) into the internal buffers.
+     */
+    toChartData(): ChartDataMap;
+    /**
+     * Get a windowed view of data for a specific time range.
+     * Returns subarray views (zero-copy) for points where tMin <= t <= tMax.
+     */
+    getWindow(tMin: number, tMax: number): ChartDataMap;
+    /** Clear all data. */
+    clear(): void;
+    /** The latest time value, or -Infinity if empty. */
+    get latestT(): number;
+    /** The earliest time value, or Infinity if empty. */
+    get earliestT(): number;
+    /** Drop the oldest half of the data when capacity is reached. */
+    private _trimOldest;
+    /** Binary search: first index where arr[i] >= value. */
+    private _lowerBound;
+    /** Binary search: first index where arr[i] > value. */
+    private _upperBound;
+}

package/dist/utils/alignTimeSeries.d.ts

@@ -0,0 +1,23 @@
+/** A single named time series with independent time array. */
+export interface NamedTimeSeries {
+    label: string;
+    t: Float64Array;
+    values: Float64Array;
+}
+/** Result of alignment: shared time array + per-series values (NaN for gaps). */
+export interface AlignedMultiSeries {
+    /** Merged, sorted, deduplicated time array. */
+    t: Float64Array;
+    /** One array per input series, same length as t. Missing values are NaN. */
+    values: Float64Array[];
+    /** Labels in the same order as values[]. */
+    labels: string[];
+}
+/**
+ * Merge independent time series into a shared time axis.
+ *
+ * Each input series may have a different time array. The output has a single
+ * merged time array with all unique time values (sorted), and each series
+ * is filled with NaN where it has no data at a given time point.
+ */
+export declare function alignTimeSeries(inputs: NamedTimeSeries[]): AlignedMultiSeries;

package/dist/utils/chartViewport.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Slice typed arrays to a visible time window.
+ * Uses binary search (O(log n)) + Float64Array.subarray (zero-copy).
+ *
+ * @param arrays - Array of Float64Arrays where arrays[0] is the time column.
+ * @param currentTime - Right edge of the viewport. If undefined, use all data.
+ * @param timeRange - Duration of the viewport window. If null, no left-edge clipping.
+ */
+export declare function sliceArrays(arrays: Float64Array[] | null, currentTime: number | undefined, timeRange: number | null): Float64Array[] | null;
+/**
+ * Quantize time to 0.5s steps to reduce useMemo recalculations.
+ * 60fps over 10s produces ~20 unique values instead of 600.
+ */
+export declare function quantizeChartTime(time: number | undefined): number | undefined;
+/** Find first index where arr[i] >= value. */
+export declare function lowerBound(arr: Float64Array, value: number, lo: number, hi: number): number;
+/** Find first index where arr[i] > value. */
+export declare function upperBound(arr: Float64Array, value: number, lo: number, hi: number): number;

package/dist/utils/mergeChartData.d.ts

@@ -0,0 +1,11 @@
+import type { ChartDataMap } from "../types.js";
+/**
+ * Concatenate cold snapshot + hot buffer into a single ChartDataMap.
+ * Returns `cold` directly when `hot` is null or empty (zero allocation).
+ */
+export declare function mergeChartData(cold: ChartDataMap, hot: ChartDataMap | null, derivedNames: string[]): ChartDataMap;
+/**
+ * Trim data points where t < tMin using binary search + subarray (O(1) zero-copy).
+ * Returns the original data if no trimming is needed.
+ */
+export declare function trimChartDataLeft(data: ChartDataMap, tMin: number, derivedNames: string[]): ChartDataMap;

package/dist/worker/chartDataWorker.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Chart Data Web Worker.
+ *
+ * Owns DuckDB and runs the cold/hot tick loop autonomously.
+ * Receives data points (as row tuples) from the main thread,
+ * inserts them into DuckDB, and periodically queries + merges
+ * to produce ChartDataMap which is transferred back via zero-copy.
+ *
+ * This is a direct port of the useTimeSeriesStore tick logic.
+ */
+export {};

package/dist/worker/chartDataWorkerClient.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Main-thread typed wrapper for the chart data Web Worker.
+ *
+ * Manages Worker lifecycle, message buffering before ready,
+ * and typed callbacks for chart data and errors.
+ */
+import type { TimeRange } from "../hooks/useTimeSeriesStore.js";
+import type { ChartDataMap } from "../types.js";
+import type { RowTuple, WorkerTableSchema } from "./protocol.js";
+export declare class ChartDataWorkerClient {
+    private worker;
+    private ready;
+    private disposed;
+    private pendingMessages;
+    private onDataCallback;
+    private onErrorCallback;
+    private queryId;
+    private debugResolvers;
+    private zoomResolvers;
+    constructor();
+    /** Initialize the Worker with a table schema and optional tick parameters. */
+    init(schema: WorkerTableSchema, opts?: {
+        tickInterval?: number;
+        coldRefreshEveryN?: number;
+        hotRowBudget?: number;
+    }): void;
+    /** Send data points (as pre-converted row tuples) to the Worker. */
+    ingest(rows: RowTuple[], latestT: number): void;
+    /** Signal a full table rebuild with new data. */
+    rebuild(rows: RowTuple[], latestT: number): void;
+    /** Update time range and max points configuration. */
+    configure(timeRange: TimeRange, maxPoints: number): void;
+    /** Register callback for receiving chart data from the Worker. */
+    onData(callback: (data: ChartDataMap) => void): void;
+    /** Register callback for Worker errors. */
+    onError(callback: (message: string) => void): void;
+    /** Query the row count in DuckDB (for debug/testing). */
+    queryRowCount(): Promise<number>;
+    /** Run a zoom query on the Worker's DuckDB and return the result. */
+    zoomQuery(tMin: number, tMax: number, maxPoints: number): Promise<ChartDataMap>;
+    /** Dispose the Worker and release resources. */
+    dispose(): void;
+    /** Resolve all pending query Promises so callers don't hang. */
+    private resolveAllPending;
+    private send;
+    private handleMessage;
+}

package/dist/worker/multiChartDataWorker.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Multi-satellite Chart Data Web Worker.
+ *
+ * Manages N DuckDB tables (one per satellite), runs per-satellite queries
+ * with unified tMin/tMax, aligns results via alignTimeSeries, and produces
+ * serialized MultiChartDataMap transferred back to the main thread.
+ *
+ * Direct port of useMultiSatelliteStore tick logic.
+ */
+export {};

package/dist/worker/multiChartDataWorkerClient.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Main-thread typed wrapper for the multi-satellite chart data Web Worker.
+ */
+import type { TimeRange } from "../hooks/useTimeSeriesStore.js";
+import type { RowTuple, WorkerSatelliteConfig, WorkerTableSchema } from "./protocol.js";
+/** Deserialized multi-series data for a single metric. */
+export interface MultiSeriesResult {
+    t: Float64Array;
+    values: Float64Array[];
+    series: Array<{
+        label: string;
+        color: string;
+    }>;
+}
+/** Map from metric name to multi-series data. */
+export type MultiChartDataResult = {
+    [metricName: string]: MultiSeriesResult | null;
+};
+export declare class MultiChartDataWorkerClient {
+    private worker;
+    private ready;
+    private disposed;
+    private pendingMessages;
+    private onDataCallback;
+    private onErrorCallback;
+    private queryId;
+    private zoomResolvers;
+    constructor();
+    init(baseSchema: WorkerTableSchema, satelliteConfigs: WorkerSatelliteConfig[], metricNames: string[], opts?: {
+        tickInterval?: number;
+        queryEveryN?: number;
+        compactEveryN?: number;
+    }): void;
+    ingest(satelliteId: string, rows: RowTuple[], latestT: number): void;
+    rebuild(satelliteId: string, rows: RowTuple[], latestT: number): void;
+    configure(timeRange: TimeRange, maxPoints: number): void;
+    updateConfigs(satelliteConfigs: WorkerSatelliteConfig[], metricNames: string[]): void;
+    /**
+     * Ad-hoc zoom query: request aligned multi-series data for the absolute
+     * time window `[tMin, tMax]`, bypassing the tick loop's configured
+     * `timeRange`. Returns a Promise that resolves with the same
+     * `MultiChartDataResult` shape as `onData`.
+     */
+    zoomQuery(tMin: number, tMax: number, maxPoints: number): Promise<MultiChartDataResult>;
+    onData(callback: (data: MultiChartDataResult) => void): void;
+    onError(callback: (message: string) => void): void;
+    dispose(): void;
+    /** Resolve all pending zoom promises so callers do not hang on disposal. */
+    private resolveAllPending;
+    private send;
+    private handleMessage;
+}

package/dist/worker/protocol.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Message protocol for the chart data Web Worker.
+ *
+ * The Worker owns DuckDB and the entire tick loop (cold/hot query, merge, trim).
+ * The main thread only sends data points and configuration, and receives
+ * ready-to-render ChartDataMap via zero-copy ArrayBuffer transfer.
+ */
+import type { TimeRange } from "../hooks/useTimeSeriesStore.js";
+import type { ColumnDef, DerivedColumn } from "../types.js";
+/** A single row as a tuple of nullable numbers, produced by schema.toRow(). */
+export type RowTuple = (number | null)[];
+/**
+ * Serializable subset of TableSchema — excludes the `toRow` function
+ * which cannot be transferred to a Worker.
+ */
+export interface WorkerTableSchema {
+    tableName: string;
+    columns: ColumnDef[];
+    derived: DerivedColumn[];
+}
+export type MainToWorkerMessage = {
+    type: "init";
+    schema: WorkerTableSchema;
+    tickInterval?: number;
+    coldRefreshEveryN?: number;
+    hotRowBudget?: number;
+} | {
+    type: "ingest";
+    rows: RowTuple[];
+    latestT: number;
+} | {
+    type: "rebuild";
+    rows: RowTuple[];
+    latestT: number;
+} | {
+    type: "configure";
+    timeRange: TimeRange;
+    maxPoints: number;
+} | {
+    type: "dispose";
+} | {
+    type: "debug-query";
+    id: number;
+    query: "row-count";
+} | {
+    type: "zoom-query";
+    id: number;
+    tMin: number;
+    tMax: number;
+    maxPoints: number;
+};
+/** Serializable satellite config (matches SatelliteConfig from buildMultiChartData). */
+export interface WorkerSatelliteConfig {
+    id: string;
+    label: string;
+    color: string;
+}
+export type MultiMainToWorkerMessage = {
+    type: "multi-init";
+    baseSchema: WorkerTableSchema;
+    satelliteConfigs: WorkerSatelliteConfig[];
+    metricNames: string[];
+    tickInterval?: number;
+    queryEveryN?: number;
+    compactEveryN?: number;
+} | {
+    type: "multi-ingest";
+    satelliteId: string;
+    rows: RowTuple[];
+    latestT: number;
+} | {
+    type: "multi-rebuild";
+    satelliteId: string;
+    rows: RowTuple[];
+    latestT: number;
+} | {
+    type: "multi-configure";
+    timeRange: TimeRange;
+    maxPoints: number;
+} | {
+    type: "multi-update-configs";
+    satelliteConfigs: WorkerSatelliteConfig[];
+    metricNames: string[];
+} | {
+    /**
+     * Ad-hoc zoom query: return aligned multi-series data for the absolute
+     * time window `[tMin, tMax]`, bypassing the configured `timeRange`.
+     * Each satellite's DuckDB is queried for the same window; results
+     * are aligned and returned as a one-shot response keyed by `id`.
+     */
+    type: "multi-zoom-query";
+    id: number;
+    tMin: number;
+    tMax: number;
+    maxPoints: number;
+} | {
+    type: "dispose";
+};
+/**
+ * Serialized MultiSeriesData for a single metric.
+ * `t` is the aligned time array, `values` are per-satellite value arrays.
+ */
+export interface SerializedMultiSeriesData {
+    metricName: string;
+    seriesLabels: string[];
+    seriesColors: string[];
+    /** [t, values[0], values[1], ...] — all transferred. */
+    buffers: ArrayBuffer[];
+}
+export type MultiWorkerToMainMessage = {
+    type: "ready";
+} | {
+    type: "multi-chart-data";
+    /** One entry per metric that has data. */
+    metrics: SerializedMultiSeriesData[];
+} | {
+    /** One-shot response to a `multi-zoom-query`, correlated by `id`. */
+    type: "multi-zoom-result";
+    id: number;
+    metrics: SerializedMultiSeriesData[];
+} | {
+    type: "error";
+    message: string;
+};
+export type WorkerToMainMessage = {
+    type: "ready";
+} | {
+    type: "chart-data";
+    /** Column names in the same order as buffers. */
+    keys: string[];
+    /** One ArrayBuffer per column — transferred (zero-copy). */
+    buffers: ArrayBuffer[];
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "debug-result";
+    id: number;
+    result: number;
+} | {
+    type: "zoom-result";
+    id: number;
+    keys: string[];
+    buffers: ArrayBuffer[];
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@sksat/uneri",
+  "version": "0.1.1",
+  "description": "DuckDB-wasm + uPlot real-time time-series charting for streaming simulation data.",
+  "keywords": [
+    "duckdb",
+    "wasm",
+    "charting",
+    "uplot",
+    "time-series",
+    "visualization"
+  ],
+  "author": "sksat <sksat@sksat.net>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sksat/orts",
+    "directory": "uneri"
+  },
+  "homepage": "https://sksat.github.io/orts/",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./style.css": "./dist/index.css",
+    "./align": "./src/utils/alignTimeSeries.ts",
+    "./multiWorkerClient": "./src/worker/multiChartDataWorkerClient.ts",
+    "./workerProtocol": "./src/worker/protocol.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@duckdb/duckdb-wasm": "1.32.0",
+    "uplot": "^1.6.32"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.1",
+    "@vitejs/plugin-react": "^6.0.0",
+    "happy-dom": "^20.5.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vite": "^8.0.8",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^4.1.4",
+    "ws": "^8.18.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "example:sine-wave": "npx tsx examples/sine-wave/server.ts & npx vite --config vite.example.config.ts --port 5174",
+    "example:mixed-density": "npx tsx examples/mixed-density/server.ts & npx vite --config vite.mixed-density.config.ts --port 5175",
+    "example:multi-series": "npx tsx examples/multi-series/server.ts & npx vite --config vite.multi-series.config.ts --port 5176",
+    "example:multi-table": "npx tsx examples/multi-table/server.ts & npx vite --config vite.multi-table.config.ts --port 5177"
+  }
+}