stream-charts 1.2.1 → 2.0.0

package/src/app/charts/datasources/outlierDataSource.ts

@@ -0,0 +1,90 @@
+import type {OutlierChartData} from "../observables/outliers";
+import type {OutlierDatum, OutlierSeries} from "../series/outlierSeries";
+import {emptySeries} from "../series/baseSeries";
+import {BaseStreamingDataSource, type DataGenerator} from "./StreamingDataSource";
+
+export interface OutlierDataSourceOptions<M extends readonly number[]> {
+    /**
+     * The initial series, owned (and mutated in place) by the source from here on
+     */
+    initialData: Array<OutlierSeries<M>>
+    /**
+     * Creates the observable of chart data each time the source starts
+     */
+    generator: DataGenerator<OutlierChartData<M>, OutlierSeries<M>>
+    /**
+     * Data older than this (ms), relative to the newest datum in the same chunk of new data, is
+     * dropped as new data arrives. Defaults to `Infinity` (never drop).
+     */
+    dropDataAfter?: number
+    /**
+     * Called with each series' new data as it arrives
+     */
+    onUpdateData?: (seriesName: string, data: Array<OutlierDatum<M>>) => void
+}
+
+/**
+ * A data source for outlier charts. Unlike time-series charts, series that aren't in the initial
+ * data are added as they first appear in the stream.
+ */
+export class OutlierDataSource<M extends readonly number[]>
+    extends BaseStreamingDataSource<OutlierChartData<M>, OutlierDatum<M>, OutlierSeries<M>> {
+
+    private dropDataAfter: number
+    private readonly onUpdateData: ((seriesName: string, data: Array<OutlierDatum<M>>) => void) | undefined
+
+    /**
+     * Creates a outlier data source (stopped: call {@link start} to start it)
+     * @param options The initial data, the generator, and the data-retention settings
+     */
+    constructor(options: OutlierDataSourceOptions<M>) {
+        super(options.initialData, options.generator)
+        this.dropDataAfter = options.dropDataAfter ?? Infinity
+        this.onUpdateData = options.onUpdateData
+    }
+
+    /**
+     * Changes how long data is kept; takes effect as the next data arrives
+     * @param dropDataAfter Data older than this (ms) is dropped
+     */
+    setDropDataAfter(dropDataAfter: number): void {
+        this.dropDataAfter = dropDataAfter
+    }
+
+    /**
+     * @return The latest time (the `datum.x` of the last datum) over all the series, or
+     * `-Infinity` when there is no data
+     */
+    latestTime(): number {
+        return this.seriesList().reduce(
+            (tMax, series) => Math.max(tMax, series.last().map(datum => datum.datum.x).getOrElse(tMax)),
+            -Infinity
+        )
+    }
+
+    /**
+     * Adds each series' new points to it (adding the series itself the first time it appears),
+     * and drops the points that are older than `dropDataAfter` relative to the newest of the
+     * series' new points. Calls `onUpdateData` with each series' new points.
+     * @param data The chunk of chart data emitted by the generator
+     */
+    protected ingest(data: OutlierChartData<M>): void {
+        data.newPoints.forEach((newData, name) => {
+            // register a series the first time it shows up in the stream
+            const series = this.seriesMap.get(name) || emptySeries<OutlierDatum<M>>(name) as OutlierSeries<M>
+            if (!this.seriesMap.has(name)) this.seriesMap.set(name, series)
+
+            if (this.onUpdateData) this.onUpdateData(name, newData)
+
+            series.data.push(...newData)
+
+            // drop data older than the max time-window, relative to this chunk's newest datum
+            const currentTime = Math.max(...newData.map(datum => datum.datum.x), -Infinity)
+            if (Number.isFinite(currentTime)) {
+                while (series.data.length > 0 && currentTime - series.data[0].datum.x > this.dropDataAfter) {
+                    series.data.shift()
+                }
+            }
+        })
+    }
+}

package/src/app/charts/datasources/timeSeriesDataSource.ts

@@ -0,0 +1,133 @@
+import type {Datum, TimeSeries} from "../series/timeSeries";
+import type {TimeSeriesChartData} from "../series/timeSeriesChartData";
+import {emptySeries} from "../series/baseSeries";
+import {BaseStreamingDataSource, type DataGenerator} from "./StreamingDataSource";
+
+/**
+ * Maps a series name to the "time group" whose clock governs it. Series in the same group share
+ * one current time (the max time over all of them), which is what `dropDataAfter` is measured
+ * against. Plots group series by their x-axis, so this is typically
+ * `name => axisAssignments.get(name)?.xAxis ?? defaultXAxisId`.
+ */
+export type TimeGroupFor = (seriesName: string) => string
+
+/**
+ * The default time grouping: one group, holding all the series
+ */
+const SINGLE_TIME_GROUP: TimeGroupFor = () => ""
+
+/**
+ * Calculates the current time for each time group present in the chart data: the max over the
+ * group's series of each series' own max time (falling back to the chart-wide max time). Shared
+ * by the data source (for dropping old data) and the plots' view drivers (for advancing each
+ * x-axis), so both agree on what "now" is for each axis.
+ * @param data The chart data
+ * @param timeGroupFor Maps each series to its time group
+ * @return A map(group -> current_time)
+ */
+export function currentTimesByGroup(data: TimeSeriesChartData, timeGroupFor: TimeGroupFor): Map<string, number> {
+    const times = new Map<string, number>()
+    data.seriesNames.forEach(name => {
+        const group = timeGroupFor(name)
+        const seriesTime = data.maxTimes.get(name) || data.maxTime
+        times.set(group, Math.max(times.get(group) ?? -Infinity, seriesTime))
+    })
+    return times
+}
+
+export interface TimeSeriesDataSourceOptions {
+    /**
+     * The initial series, owned (and mutated in place) by the source from here on
+     */
+    initialData: Array<TimeSeries>
+    /**
+     * Creates the observable of chart data each time the source starts
+     */
+    generator: DataGenerator<TimeSeriesChartData, TimeSeries>
+    /**
+     * Data older than this (ms), relative to its time group's current time, is dropped as new
+     * data arrives. Defaults to `Infinity` (never drop).
+     */
+    dropDataAfter?: number
+    /**
+     * Assigns each series to a time group (see {@link TimeGroupFor}). Defaults to one group for
+     * all series.
+     */
+    timeGroupFor?: TimeGroupFor
+    /**
+     * Called with each series' new data as it arrives
+     */
+    onUpdateData?: (seriesName: string, data: Array<Datum>) => void
+}
+
+/**
+ * A data source for time-series charts (e.g. the scatter and raster plots)
+ */
+export class TimeSeriesDataSource extends BaseStreamingDataSource<TimeSeriesChartData, Datum, TimeSeries> {
+    private dropDataAfter: number
+    private readonly timeGroupFor: TimeGroupFor
+    private readonly onUpdateData: ((seriesName: string, data: Array<Datum>) => void) | undefined
+
+    /**
+     * Creates a time-series data source (stopped: call {@link start} to start it)
+     * @param options The initial data, the generator, and the data-retention settings
+     */
+    constructor(options: TimeSeriesDataSourceOptions) {
+        super(options.initialData, options.generator)
+        this.dropDataAfter = options.dropDataAfter ?? Infinity
+        this.timeGroupFor = options.timeGroupFor ?? SINGLE_TIME_GROUP
+        this.onUpdateData = options.onUpdateData
+    }
+
+    /**
+     * Changes how long data is kept; takes effect as the next data arrives
+     * @param dropDataAfter Data older than this (ms) is dropped
+     */
+    setDropDataAfter(dropDataAfter: number): void {
+        this.dropDataAfter = dropDataAfter
+    }
+
+    /**
+     * @return The latest time (the `x` of the last datum) over all the series, or
+     * `-Infinity` when there is no data
+     */
+    latestTime(): number {
+        return this.seriesList().reduce(
+            (tMax, series) => Math.max(tMax, series.last().map(datum => datum.x).getOrElse(tMax)),
+            -Infinity
+        )
+    }
+
+    /**
+     * Adds each series' new points to it, and drops the points that are older than
+     * `dropDataAfter` relative to the current time of the series' time group (see
+     * `currentTimesByGroup`). New points for a series that isn't in the source are ignored
+     * (time-series charts have a fixed set of series). Calls `onUpdateData` with each series' new
+     * points.
+     * @param data The chunk of chart data emitted by the generator
+     */
+    protected ingest(data: TimeSeriesChartData): void {
+        const groupTimes = currentTimesByGroup(data, this.timeGroupFor)
+
+        // add each new point to its corresponding series, the new points is a
+        // map(series_name -> new_point[])
+        data.newPoints.forEach((newData, name) => {
+            // note: as in the original subscription code, data for a series that isn't already in
+            // the source is accepted but not kept (time-series charts have a fixed set of series)
+            const series = this.seriesMap.get(name) || emptySeries<Datum>(name)
+
+            if (this.onUpdateData) this.onUpdateData(name, newData)
+
+            series.data.push(...newData)
+
+            // drop data that is older than the max time-window -- guarded on series.data.length so
+            // a sibling series in the same time group advancing the group's time past every point
+            // this series holds (e.g. this series stalls/updates slower) can't shift it down to
+            // empty and then throw on series.data[0].x
+            const currentTime = groupTimes.get(this.timeGroupFor(name)) || data.maxTime
+            while (series.data.length > 0 && currentTime - series.data[0].x > this.dropDataAfter) {
+                series.data.shift()
+            }
+        })
+    }
+}

package/src/app/charts/filters/regexFilter.ts

@@ -1,17 +1,57 @@
-import {failureResult, Result, successResult} from "result-fn";
+import {failureResult, type Result, successResult} from "result-fn";
+import safeRegex from "safe-regex";
 
 /**
- * Wraps the creation of the regex in a try/catch and returns the regex, wrapped in an option,
+ * Checks whether a regex is reasonably safe from catastrophic (exponential-time) backtracking --
+ * e.g. `/(a+)+$/`, the classic case that freezes on a long non-matching input. Every plot
+ * component tests a compiled `seriesFilter` regex against every series name on every redraw
+ * frame (not just once), so an unvetted pattern from a free-text filter field can hang the whole
+ * render loop, not just one call. Delegates to the `safe-regex` package, which walks the regex's
+ * actual parsed structure (via `regexp-tree`) rather than pattern-matching its source string, so
+ * it catches more than a hand-rolled "look for nested quantifiers" check would.
+ * @param pattern The regex (or its string source) to check
+ * @return `true` if the pattern is reasonably safe to run against arbitrary input; `false` if it
+ * risks catastrophic backtracking
+ */
+export function isSafeRegex(pattern: RegExp | string): boolean {
+    return safeRegex(pattern)
+}
+
+/**
+ * Wraps the creation of the regex in a try/catch and returns the regex, wrapped in a `Result`,
  * when it is valid. This can be used, for example, in a text field where the user types a regex.
+ * Also rejects a pattern that compiles fine but risks catastrophic backtracking (see
+ * {@link isSafeRegex}) -- a syntax error and an exponential-time pattern are both "can't use this"
+ * outcomes from the caller's point of view, so both are reported the same way.
  * @param regexString The string representation of the regex
- * @return The regular expression (`RegExp`) wrapped in an option. If the regexp
- * is invalid, then the option is none.
+ * @return The regular expression (`RegExp`) wrapped in a successful `Result`. If the regex is
+ * invalid, or is unsafe, then a failed `Result` holding a message that says why.
  */
 export function regexFilter(regexString: string): Result<RegExp, string> {
     try {
         const regex = new RegExp(regexString)
+        if (!isSafeRegex(regex)) {
+            return failureResult(
+                `Refusing to use a regex that risks catastrophic backtracking; regex_expression: ${regexString}`
+            )
+        }
         return successResult(regex)
     } catch(error) {
-        return failureResult(`Unable to compile the regex expression; regex_expression: ${regexString}`)
+        return failureResult(
+            `Unable to compile the regex expression; regex_expression: ${regexString}; error: ${error}`
+        )
     }
 }
+
+/**
+ * Builds a regex that matches `text` literally, for callers (e.g. a series-name filter input)
+ * who want to search for plain text without regex metacharacters (`.`, `*`, `+`, `(`, etc.) in it
+ * being given unintended regex semantics. Escapes those metacharacters before handing the result
+ * to {@link regexFilter}, so it shares the same `Result`-wrapped, never-throws contract.
+ * @param text The literal text to match
+ * @return The regular expression (`RegExp`) matching `text` literally, wrapped in a `Result` (see
+ * {@link regexFilter})
+ */
+export function literalFilter(text: string): Result<RegExp, string> {
+    return regexFilter(text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+}

package/src/app/charts/hooks/AxesProvider.tsx

@@ -0,0 +1,301 @@
+import {AxisInterval} from "../axes/AxisInterval";
+import {type JSX, useCallback, useMemo, useRef, useState} from "react";
+import {BaseAxisRange} from "../axes/BaseAxisRange";
+import type {BaseAxis} from "../axes/axes";
+import {usePlotDimensions} from "./usePlotDimensions";
+import {AxesState} from "../axes/AxesState";
+import type {AxesAssignment} from "../plots/plot";
+import type {Dimensions} from "../styling/margins";
+import {Optional} from "result-fn";
+import {AxesContext, type UseAxesValues} from "./useAxes";
+
+export type Props = {
+    /**
+     * Callback when axes bounds change.
+     * @param ranges The ranges (start, end) for each axis in the plot
+     */
+    onUpdateAxesInterval?: (ranges: Map<string, AxisInterval>) => void
+
+    children: JSX.Element | Array<JSX.Element>
+}
+/**
+ * The React context provider for the {@link UseAxesValues}
+ * @param props The properties
+ * @return The children wrapped in this provider
+ * @template AR The type of the axis range (e.g. {@link ContinuousAxisRange} or {@link OrdinalAxisRange})
+ * @template A The axis type
+ */
+export default function AxesProvider<AR extends BaseAxisRange, A extends BaseAxis>(props: Props): JSX.Element {
+    const {onUpdateAxesInterval, children} = props
+
+    const plotDimensions = usePlotDimensions()
+
+    const [xAxesState, setXAxesState] = useState<AxesState<A>>(AxesState.empty<A>())
+    const [yAxesState, setYAxesState] = useState<AxesState<A>>(AxesState.empty<A>())
+    const axisAssignmentsRef = useRef<Map<string, AxesAssignment>>(new Map())
+    const axesBoundsUpdateHandlersRef = useRef<Map<string, (updates: Map<string, AR>, plotDim: Dimensions) => void>>(new Map())
+    const axesRangeRef = useRef<Map<string, AR>>(new Map())
+
+    /**
+     * Retrieves the x-axis and y-axis assignments for the specified series. If the series does not
+     * have an assignment, then we assume it is using the default x- and y-axes.
+     * @param seriesName The name of the series for which to retrieve the axes assignments
+     * @return An {@link AxesAssignment} for the specified axes.
+     */
+    const axisAssignmentsFor = useCallback(
+        (seriesName: string): AxesAssignment =>
+            axisAssignmentsRef.current.get(seriesName) || {
+                xAxis: xAxesState.axisDefaultId().getOrElse(""),
+                yAxis: yAxesState.axisDefaultId().getOrElse("")
+            },
+        [xAxesState, yAxesState]
+    )
+
+    /**
+     * Called when the domain/range is updated on one or more of the chart's axes (generally x-axes). Stores
+     * the updated ranges, and in turn, dispatches the update to all the registered domain/range update
+     * handlers (e.g. the axes, which redraw themselves with their new domain).
+     * @param updates A map holding the axis ID to the updated axis time-range (i.e., map(axis_id, axis_time_range))
+     */
+    const updateAxisRanges = useCallback(
+        (updates: Map<string, AR>): void => {
+            // update the current time-ranges reference
+            updates.forEach((range, id) => {
+                axesRangeRef.current.set(id, range)
+            })
+            // dispatch the updates to all the registered handlers
+            axesBoundsUpdateHandlersRef.current
+                .forEach((handler,) => handler(updates, plotDimensions.plotDimensions))
+        },
+        [plotDimensions.plotDimensions]
+    )
+
+    /**
+     * Sets the axis ranges specified in the input map (without dispatching them to the update handlers)
+     * @param ranges The ranges to set
+     */
+    const setAxesRanges = useCallback(
+        (ranges: Map<string, AR>): void => {
+            ranges.forEach((range, id) => {
+                axesRangeRef.current.set(id, range)
+            })
+        },
+        []
+    )
+
+    /**
+     * Sets the axis range for the specified axis ID (without dispatching it to the update handlers)
+     * @param axisId The axis ID
+     * @param range The range to set
+     */
+    const setAxisRangeFor = useCallback(
+        (axisId: string, range: AR): void => {
+            axesRangeRef.current.set(axisId, range)
+        },
+        []
+    )
+
+    /**
+     * Sets the axis bounds (the current range) for the specified axis ID. Note that this does not
+     * change the original axis interval, doesn't dispatch the change to the update handlers, and
+     * does nothing when the axis has no range yet.
+     * @param axisId The axis ID
+     * @param interval The interval
+     */
+    const setAxisIntervalFor = useCallback(
+        (axisId: string, interval: AxisInterval): void => {
+            Optional.ofNullable(axesRangeRef.current.get(axisId))
+                .map(range => range.update(interval.start, interval.end) as AR)
+                .ifPresent(updatedRange => axesRangeRef.current.set(axisId, updatedRange))
+        },
+        []
+    )
+
+    /**
+     * Sets the original axis interval for the axis range (does nothing when the axis has no range yet)
+     * @param axisId The axis ID
+     * @param interval The interval to which to set the origin interval
+     */
+    const setOriginalAxisIntervalFor = useCallback(
+        (axisId: string, interval: AxisInterval): void => {
+            Optional.ofNullable(axesRangeRef.current.get(axisId))
+                .map(range => range.updateOriginal(interval.start, interval.end) as AR)
+                .ifPresent(updatedRange => axesRangeRef.current.set(axisId, updatedRange))
+        },
+        []
+    )
+
+    /**
+     * Re-applies the specified axis' stored range: dispatches it, unchanged, to the update handlers
+     * (so that the axis redraws with it). Note that this does *not* restore the axis' original
+     * range. Does nothing when the axis has no range.
+     * @param axisId The ID of the axis
+     */
+    const resetAxisIntervalFor = useCallback(
+        (axisId: string): void => {
+            Optional
+                .ofNullable(axesRangeRef.current.get(axisId))
+                .map(range => new Map<string, AR>([[axisId, range]]))
+                .ifPresent(updates => updateAxisRanges(updates))
+        },
+        [updateAxisRanges]
+    )
+
+    /**
+     * Sets the ranges of the axes in the specified map, and dispatches them to the update handlers
+     * (the same as {@link updateAxisRanges}). Axes that aren't in the map are left as they are, so
+     * the default (empty) map changes nothing.
+     * @param [axesRanges=new Map()] An optional map holds bounds for specified axes. The map
+     * associates an axis ID with the new bounds.
+     */
+    const resetAxesRanges = useCallback(
+        (axesRanges: Map<string, AR> = new Map()): void => {
+            updateAxisRanges(axesRanges)
+        },
+        [updateAxisRanges]
+    )
+
+    /**
+     * Adds a handler to deal with updates to the bounds of the axes
+     * @param handlerId the unique ID of the handler
+     * @param handler The handler function that accepts a map of updates and a plot dimension
+     * @return A map with all the handlers
+     * @throws Error when a handler with the same ID is already registered
+     */
+    const addAxesRangesUpdateHandler = useCallback(
+        (
+            handlerId: string,
+            handler: (updates: Map<string, AR>, plotDim: Dimensions) => void
+        ): Map<string, (updates: Map<string, AR>, plotDim: Dimensions) => void> => {
+            if (axesBoundsUpdateHandlersRef.current.has(handlerId)) {
+                throw new Error(
+                    `Handler with ID already exists, please remove it before adding it; ` +
+                    `handler_id: ${handlerId}; ` +
+                    `existing_handler_ids: [${Array.from(axesBoundsUpdateHandlersRef.current.keys()).join(", ")}]`
+                )
+            }
+            return axesBoundsUpdateHandlersRef.current.set(handlerId, handler)
+        },
+        []
+    )
+
+    /**
+     * Removes the axis-update handler with the specified ID
+     * @param handlerId The ID of the handler to remove
+     * @return `true` when the handler was registered (and has been removed); `false` otherwise
+     */
+    const removeAxesRangesUpdateHandler = useCallback(
+        (handlerId: string): boolean => axesBoundsUpdateHandlersRef.current.delete(handlerId),
+        []
+    )
+
+    /**
+     * Adds an x-axis to the x-axes state (a new state object, so dependents re-render)
+     * @param axis The axis to add
+     * @param id The ID of the axis to add
+     * @param [range] The initial axis range (when given, it's stored as the axis' range)
+     */
+    const addXAxis = useCallback(
+        (axis: A, id: string, range?: AR): void => {
+            setXAxesState(xAxesState.addAxis(axis, id))
+            if (range !== undefined) {
+                axesRangeRef.current.set(id, range)
+            }
+        },
+        [xAxesState]
+    )
+
+    /**
+     * Adds a y-axis to the y-axes state (a new state object, so dependents re-render)
+     * @param axis The axis to add
+     * @param id The ID of the axis to add
+     * @param [range] The initial axis range (when given, it's stored as the axis' range)
+     */
+    const addYAxis = useCallback(
+        (axis: A, id: string, range?: AR): void => {
+            setYAxesState(yAxesState.addAxis(axis, id))
+            if (range !== undefined) {
+                axesRangeRef.current.set(id, range)
+            }
+        },
+        [yAxesState]
+    )
+
+    /**
+     * Sets the axes assigned to each series (replacing any earlier assignments)
+     * @param assignments The assignment of the series to their axes
+     */
+    const setAxisAssignments = useCallback(
+        (assignments: Map<string, AxesAssignment>): void => {
+            axisAssignmentsRef.current = assignments
+        },
+        []
+    )
+
+    /**
+     * @return A copy of the map of the axes' current ranges, by axis ID
+     */
+    const axesRanges = useCallback(
+        (): Map<string, AR> => new Map<string, AR>(axesRangeRef.current),
+        []
+    )
+
+    /**
+     * Retrieves the current axis range for the specified axis ID
+     * @param axisId The ID of the axis
+     * @return The axis' range, or an empty `Optional` when the axis has no range
+     */
+    const axisRangeFor = useCallback(
+        (axisId: string) => Optional.ofNullable(axesRangeRef.current.get(axisId)),
+        []
+    )
+
+    // the context's `value` prop is typed as `unknown` (see `AxesContext` in `useAxes.tsx`), so
+    // the object literal needs its own explicit type here to give the handler functions below
+    // their parameter types -- otherwise they'd fall back to implicit `any`.
+    //
+    // Memoized so consumers relying on this context value's identity (e.g. a `useMemo`/effect
+    // keyed on it) don't re-run on essentially every render of anything above this provider --
+    // previously a fresh object literal every render, with every method inside it also a fresh
+    // closure. This is the same class of bug already documented/worked around in ScatterPlot.tsx/
+    // RasterPlot.tsx/OutlierPlot.tsx (their own comments on `axesRanges` never being memoized
+    // here) -- those workarounds (refs populated imperatively instead of `useMemo([axesRanges])`)
+    // are left in place; they're redundant once this is memoized, but harmless, and removing them
+    // isn't part of this change.
+    const value: UseAxesValues<AR, A> = useMemo(
+        () => ({
+            xAxesState,
+            yAxesState,
+            addXAxis,
+            addYAxis,
+            setAxisAssignments,
+            axisAssignmentsFor,
+            updateAxisRanges,
+            axesRanges,
+            axisRangeFor,
+            setAxesRanges,
+            setAxisRangeFor,
+            setAxisIntervalFor,
+            setOriginalAxisIntervalFor,
+            resetAxesRanges,
+            resetAxisIntervalFor,
+            onUpdateAxesInterval,
+            addAxesRangesUpdateHandler,
+            removeAxesRangesUpdateHandler,
+        }),
+        [
+            xAxesState, yAxesState,
+            addXAxis, addYAxis,
+            setAxisAssignments, axisAssignmentsFor,
+            updateAxisRanges, axesRanges, axisRangeFor,
+            setAxesRanges, setAxisRangeFor, setAxisIntervalFor, setOriginalAxisIntervalFor,
+            resetAxesRanges, resetAxisIntervalFor,
+            onUpdateAxesInterval,
+            addAxesRangesUpdateHandler, removeAxesRangesUpdateHandler,
+        ]
+    )
+
+    return <AxesContext.Provider value={value}>
+        {children}
+    </AxesContext.Provider>
+}