Alert Utilities

Utilities for building alert queries and managing time ranges.

Package

@tetherto/mdk-ui-foundation

Utilities

Default historical range

import { getDefaultHistoricalAlertsRange } from '@tetherto/mdk-ui-foundation'

When to use getDefaultHistoricalAlertsRange

Use getDefaultHistoricalAlertsRange to initialise an alert-history view with the standard 14-day look-back window. Pass an explicit now value when the range must be deterministic, such as in a test.

getDefaultHistoricalAlertsRange example

import { getDefaultHistoricalAlertsRange } from '@tetherto/mdk-ui-foundation'

const initialRange = getDefaultHistoricalAlertsRange()
const testRange = getDefaultHistoricalAlertsRange(1_700_000_000_000)

Build the current-alert query

import { buildCurrentAlertDevicesParams } from '@tetherto/mdk-ui-foundation'

When to use buildCurrentAlertDevicesParams

Use buildCurrentAlertDevicesParams to construct the list-things request for devices that currently carry alerts. Pass active search tags when the server should narrow the current-alert result before client-side presentation.

buildCurrentAlertDevicesParams example

import { buildCurrentAlertDevicesParams } from '@tetherto/mdk-ui-foundation'

const allCurrentAlerts = buildCurrentAlertDevicesParams()
const matchingAlerts = buildCurrentAlertDevicesParams([
  'ip-192.168.1.1',
  'sn-ABC123',
])

Time intervals

import { breakTimeIntoIntervals } from '@tetherto/mdk-ui-foundation'

Related API

• fetchHistoricalAlertsInChunks
• mergeAlertsByUuid

When to use breakTimeIntoIntervals

Use breakTimeIntoIntervals when a historical request must be split into bounded windows before fetching. Alert history uses this to avoid requesting a large time range in one call.

Historical-alert chunking workflow

Create the windows with breakTimeIntoIntervals, fetch them from oldest to newest, then combine overlapping alert results with mergeAlertsByUuid. fetchHistoricalAlertsInChunks composes that workflow when its default error and abort behaviour fits the caller.

Range behaviour

The function returns an empty array when the bounds are non-finite, when start >= end, or when intervalMs <= 0. The final interval is clamped to end, so it may be shorter than intervalMs; callers must not assume that every window has equal duration.

breakTimeIntoIntervals example

import {
  breakTimeIntoIntervals,
  mergeAlertsByUuid,
  ONE_DAY_MS,
} from '@tetherto/mdk-ui-foundation'

let alerts = []

for (const window of breakTimeIntoIntervals(start, end, ONE_DAY_MS)) {
  const next = await fetchAlerts(window)
  alerts = mergeAlertsByUuid(alerts, next)
}

Fetch historical alerts

import { buildHistoricalAlertsParams, fetchHistoricalAlertsInChunks, mergeAlertsByUuid } from '@tetherto/mdk-ui-foundation'

Related API

• fetchHistoricalAlertsInChunks
• buildHistoricalAlertsParams
• mergeAlertsByUuid

When to use the historical-alert workflow

Use fetchHistoricalAlertsInChunks for a full alert-history range rather than issuing one unbounded request. It coordinates the range splitting and result merging; buildHistoricalAlertsParams adapts each window to the Gateway query.

Historical-alert fetch workflow

Start with the requested range, let fetchHistoricalAlertsInChunks visit each window from oldest to newest, and build one history-log request per callback. The helper uses mergeAlertsByUuid between windows. Call mergeAlertsByUuid again only when integrating the returned range into alerts already held by the caller.

Historical-alert failure and abort behaviour

Individual window failures are swallowed so one bad request does not discard the rest of the range. An abort signal is checked between windows rather than during the caller's active request; the request function must use that signal as well if it needs in-flight cancellation.

Historical-alert workflow example

import {
  buildHistoricalAlertsParams,
  fetchHistoricalAlertsInChunks,
  mergeAlertsByUuid,
} from '@tetherto/mdk-ui-foundation'

const fetchedAlerts = await fetchHistoricalAlertsInChunks(
  range,
  async (window) => {
    const params = buildHistoricalAlertsParams(window)
    const result = await gateway.historyLog(params)
    return result.data
  },
  { signal: abortController.signal },
)

const allAlerts = mergeAlertsByUuid(existingAlerts, fetchedAlerts)

Import the public APIs on this page from @tetherto/mdk-ui-foundation.

breakTimeIntoIntervals

Split [start, end] into consecutive windows of intervalMs. The final window is clamped to end. Returns an empty array when the range is empty or inverted. Mirrors Mining OS's breakTimeIntoIntervals.

Function

(start: number, end: number, intervalMs: number = ONE_DAY_MS) => TimeInterval[]

buildCurrentAlertDevicesParams

list-things params for the current-alerts table: every device that currently carries one or more alerts, with the fields the <CurrentAlerts> table reads. Consumed by useCurrentAlertDevices.

Function

(filterTags: string[] = []) => ListThingsParams

buildHistoricalAlertsParams

history-log params for a single alerts window. The chunked fetch (useHistoricalAlerts) calls this once per 24h sub-window.

Function

(range: HistoricalAlertsRange) => HistoryLogParams

fetchHistoricalAlertsInChunks

Fetch a historical-alerts range as successive 24h windows, merging the results by uuid. fetchWindow is called once per window (oldest → newest); individual window failures are swallowed (matches Mining OS) so one bad window doesn't dro…

Function

(range: { start: number; end: number }, fetchWindow: (window: TimeInterval) => Promise<T[]>, options: FetchHistoricalAlertsOptions = {}) => Promise<T[]>

getAlertsForDevices

Flatten an array of devices into a list of incident rows, one per alert. Devices without last.alerts are skipped. The output is not yet sorted; pair with sortIncidentsBySeverity for the final list-view order.

Function

(devices: ListThingsDevice[], formatDate: (d: Date) => string = (d) => d.toISOString()) => IncidentRow[]

getDefaultHistoricalAlertsRange

Default historical-alerts range: the last DEFAULT_HISTORICAL_WINDOW_MS ending now. Used by the devkit <Alerts> feature and the shell Alerts page to seed their range state.

Function

(now: number = Date.now()) => HistoricalAlertsRange

mapDevicesToIncidents

One-shot helper: devices → sorted rows. Used by the useActiveIncidents hook's select projection.

Function

(devices: ListThingsDevice[], formatDate?: (d: Date) => string) => IncidentRow[]

mapHistoryLogToAlerts

Normalise raw history-log alert rows into the shape the devkit <HistoricalAlerts> table consumes. The table derives its device label, short code, and filter tokens from each row's thing (treated as a device), so this guarantees `thin…

Function

(rows: HistoricalAlert[] = []) => HistoricalAlert[]

mergeAlertsByUuid

Concatenate next onto prev, replacing any row that shares a uuid (later windows win) and appending the rest. Rows without a uuid are always appended. Mirrors Mining OS's updateHistoricalData.

Function

(prev: T[], next: T[]) => T[]

sortIncidentsBySeverity

Sort rows by severity (critical → high → medium), then by id for deterministic ordering when severities tie. Returns a new array.

Function

(rows: IncidentRow[]) => IncidentRow[]