Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo

Alerts

API reference for @luxalgo/vela-pro-alerts, including the alerts plugin, controller, backend port, dialog, and widget.

View as Markdown

This page documents @luxalgo/vela-pro-alerts, including the alerts() plugin factory, AlertsController, the alert backend port, the alert editor dialog, the standalone alerts list widget, and rule and trigger event types.

Import symbols on this page from @luxalgo/vela-pro-alerts. Related guides: Alerts, Standalone widgets.

Functions

alerts

Alerts as a Vela Pro plugin. Its API opens the new-alert dialog for other plugins.

function alerts(opts?: EnableAlertsOptions): VelaProPlugin<AlertsApi>

See also: AlertsApi, EnableAlertsOptions, VelaProPlugin.

alertsController

function alertsController(): AlertsController | null

See also: AlertsController.

classifyAlert

The kind of an alert an engine raised (see the module note).

function classifyAlert(a: { id: string; title?: string }): Exclude<ScriptEvent, 'any'>

See also: ScriptEvent.

createAlertsList

The alerts list as a widget: { el, update, destroy }.

function createAlertsList(props: AlertsListProps): AlertsListWidget

See also: AlertsListProps, AlertsListWidget.

describeCondition

A readable summary of a rule's condition.

function describeCondition(rule: AlertRule, formatPrice: (p: number) => string): string

See also: AlertRule.

enableAlerts

Enable ALERTS on every shell built afterwards. Returns the page's AlertsController. Call ONCE, before constructing shells. Idempotent.

function enableAlerts(opts?: EnableAlertsOptions): AlertsController

See also: AlertsController, EnableAlertsOptions.

openAlertDialog

function openAlertDialog(ctx: WidgetContext, alerts: AlertsController, seed: AlertDialogSeed): void

See also: AlertDialogSeed, AlertsController. From @luxalgo/vela/plugin: WidgetContext.

priceConditionMet

Whether a price operator holds over one step.

function priceConditionMet(
    op: PriceOperator,
    value: number,
    upper: number | undefined,
    step: PriceStep,
): boolean

// Unexported supporting type referenced above
interface PriceStep {
    prev: number | undefined;
    curr: number;
}

See also: PriceOperator.

renderMessage

Fill a message template's placeholders. Unknown ones stay as written.

function renderMessage(
    template: string,
    values: Record<string, string | number | undefined>,
): string

scriptAlertSources

What source can alert on. Comments are ignored; dynamic titles are skipped.

function scriptAlertSources(source: string): ScriptAlertSources

See also: ScriptAlertSources.

Classes

AlertsController class

class AlertsController {
    constructor(opts: AlertsControllerOptions);
    readonly unreadCount: number;
    readonly webhooksAllowed: boolean;
    rules(): AlertRule[];
    rule(id: string): AlertRule | undefined;
    log(): readonly AlertEvent[];
    lastPrice(symbol: string): number | undefined;
    create(a: NewAlert): AlertRule;
    update(id: string, patch: Partial<Omit<AlertRule, 'id' | 'createdAt'>>): void;
    remove(id: string): void;
    setPaused(id: string, paused: boolean): void;
    moveLevel(id: string, value: number, which?: 'value' | 'upper'): void;
    markRead(): void;
    clearLog(): void;
    notePrice(symbol: string, price: number, barTime: number, interval?: string): void;
    noteScriptAlert(
        symbol: string,
        indicatorId: string,
        alert: { id: string; message: string; title?: string; time: number },
        interval?: string,
    ): void;
    onFire(cb: (e: AlertEvent, rule: AlertRule) => void): () => void;
    onChange(cb: (what: AlertsChange) => void): () => void;
    flush(): void;
}
MemberTypeDescription
constructor(opts: AlertsControllerOptions)
unreadCountnumber
webhooksAllowedboolean
rules()() => AlertRule[]
rule()(id: string) => AlertRule | undefined
log()() => readonly AlertEvent[]
lastPrice()(symbol: string) => number | undefined
create()(a: NewAlert) => AlertRule
update()(id: string, patch: Partial<Omit<AlertRule, 'id' | 'createdAt'>>) => void
remove()(id: string) => void
setPaused()(id: string, paused: boolean) => void
moveLevel()(id: string, value: number, which?: 'value' | 'upper') => voidMove a price alert's level (its line was dragged). Default: which = 'value'.
markRead()() => void
clearLog()() => void
notePrice()(symbol: string, price: number, barTime: number, interval?: string) => voidA chart's live bar: its open time and its latest close. Default: interval = ''.
noteScriptAlert()(symbol: string, indicatorId: string, alert: { id: string; message: string; … (truncated; see declaration)An indicator raised an alert (handle.on('alert')). Default: interval = ''.
onFire()(cb: (e: AlertEvent, rule: AlertRule) => void) => () => void
onChange()(cb: (what: AlertsChange) => void) => () => void
flush()() => voidWrite pending changes now (tests, page unload).

See also: AlertEvent, AlertRule, AlertsChange, AlertsControllerOptions, NewAlert.

AlertsListWidget

class AlertsListWidget {
    constructor(props: AlertsListProps);
    readonly el: HTMLElement;
    update(next: Partial<Omit<AlertsListProps, 'controller'>>): void;
    destroy(): void;
}

See also: AlertsListProps.

LocalAlertsBackend

The browser's localStorage, under one key (default 'vela-pro.alerts').

class LocalAlertsBackend implements AlertsBackend {
    constructor(key?: string);
    load(): { rules: AlertRule[]; events: AlertEvent[] };
    save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}

Default: constructor(key = 'vela-pro.alerts').

See also: AlertEvent, AlertRule, AlertsBackend.

MemoryAlertsBackend

An in-memory backend (tests, or a host that persists through onFire and its own store).

class MemoryAlertsBackend implements AlertsBackend {
    load(): { rules: AlertRule[]; events: AlertEvent[] };
    save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}

See also: AlertEvent, AlertRule, AlertsBackend.

Interfaces and types

AlertCondition

type AlertCondition =
    | { kind: 'price'; op: PriceOperator; value: number; upper?: number }
    | { kind: 'script'; indicatorId: string; indicatorTitle: string; event: ScriptEvent; conditionTitle?: string; };

See also: PriceOperator, ScriptEvent.

AlertDialogSeed

interface AlertDialogSeed {
    symbol: string;
    price?: number;
    indicatorId?: string;
    rule?: AlertRule;
}
MemberTypeDescription
symbolstring
price?numberPrefill a price alert at this level.
indicatorId?stringPrefill a script alert on this indicator.
rule?AlertRuleEdit an existing alert instead.

See also: AlertRule.

AlertEvent

interface AlertEvent {
    id: string;
    ruleId: string;
    name: string;
    symbol: string;
    time: number;
    message: string;
    price?: number;
}

AlertFrequency

once fires a single time then stops; the others keep the alert active.

type AlertFrequency = 'once' | 'once-per-bar' | 'once-per-bar-close' | 'every-time';

AlertNotify

interface AlertNotify {
    toast: boolean;
    sound: boolean;
    webhook?: string;
}
MemberTypeDescription
toastboolean
soundboolean
webhook?stringPOST the alert to this URL (only where the host allows webhooks).

AlertRule

interface AlertRule {
    id: string;
    name: string;
    symbol: string;
    condition: AlertCondition;
    frequency: AlertFrequency;
    message: string;
    notify: AlertNotify;
    status: AlertStatus;
    expiresAt: number | null;
    createdAt: number;
    updatedAt: number;
    lastFiredAt?: number;
    fireCount: number;
}
MemberTypeDescription
idstring
namestring
symbolstring
conditionAlertCondition
frequencyAlertFrequency
messagestringMessage template: {{ticker}}, {{close}}, {{time}}, {{interval}}, {{name}}.
notifyAlertNotify
statusAlertStatus
expiresAtnumber | nullEpoch ms after which the alert stops; null never.
createdAtnumber
updatedAtnumber
lastFiredAt?number
fireCountnumber

See also: AlertCondition, AlertFrequency, AlertNotify, AlertStatus.

AlertsBackend

Where alerts and their history live. Default: the browser (LocalAlertsBackend).

interface AlertsBackend {
    load(): { rules: AlertRule[]; events: AlertEvent[] };
    save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}

See also: AlertEvent, AlertRule.

AlertsChange

type AlertsChange = 'rules' | 'events';

AlertsControllerOptions

interface AlertsControllerOptions {
    backend: AlertsBackend;
    onFire?: (event: AlertEvent, rule: AlertRule) => void;
    webhooks?: boolean;
    now?: () => number;
}
MemberTypeDescription
backendAlertsBackend
onFire?(event: AlertEvent, rule: AlertRule) => voidCalled for every firing, after the built-in notifications.
webhooks?booleanLet alerts POST to a webhook URL.
now?() => number

See also: AlertEvent, AlertRule, AlertsBackend.

AlertsListProps

The alerts list's props. controller is read once; the others can change through update.

interface AlertsListProps {
    controller: AlertsController;
    symbol?: string;
    host?: HTMLElement;
    active?: boolean;
    onOpenAlert?: (seed: AlertDialogSeed) => void;
    onNotify?: (message: string, kind: 'info' | 'success' | 'error') => void;
}
MemberTypeDescription
controllerAlertsControllerThe alerts and their log.
symbol?stringThe symbol "New alert" starts on.
host?HTMLElementWhere overlays mount (default: the widget's own element).
active?booleanShown or hidden: shown on the log, it marks the fired alerts read.
onOpenAlert?(seed: AlertDialogSeed) => voidOpen the alert editor ("New alert", a row, Edit). Without it, the list only shows and pauses alerts.
onNotify?(message: string, kind: 'info' | 'success' | 'error') => voidTell the user something (no symbol to add an alert on).

See also: AlertDialogSeed, AlertsController.

AlertStatus

type AlertStatus = 'active' | 'paused' | 'triggered' | 'expired';

EnableAlertsOptions

Options for enableAlerts.

interface EnableAlertsOptions {
    backend?: AlertsBackend;
    onFire?: (event: AlertEvent, rule: AlertRule) => void;
    webhooks?: boolean;
    contextMenu?: boolean;
    shortcut?: boolean;
    legendAction?: boolean;
    topbarBell?: boolean;
}
MemberTypeDescription
backend?AlertsBackendWhere alerts are kept. Default: the browser's localStorage.
onFire?(event: AlertEvent, rule: AlertRule) => voidCalled on every firing: route it to email, push, a server…
webhooks?booleanLet users give an alert a webhook URL (POSTed the fired event). Default false.
contextMenu?boolean"Add alert" in the chart's right-click menu (default true).
shortcut?booleanAlt+A opens the dialog at the last price (default true).
legendAction?booleanA bell on script indicators' legend rows (default true).
topbarBell?booleanKeep the topbar's bell, opening the Alerts panel (default false: the bell is put away, the rail's Alerts entry takes its place).

See also: AlertEvent, AlertRule, AlertsBackend.

NewAlert

interface NewAlert {
    name?: string;
    symbol: string;
    condition: AlertCondition;
    frequency?: AlertFrequency;
    message?: string;
    notify?: Partial<AlertNotify>;
    expiresAt?: number | null;
}

See also: AlertCondition, AlertFrequency, AlertNotify.

PriceOperator

type PriceOperator =
    | 'crossing'
    | 'crossing-up'
    | 'crossing-down'
    | 'greater-than'
    | 'less-than'
    | 'entering-channel'
    | 'exiting-channel'
    | 'inside-channel'
    | 'outside-channel';

ScriptAlertSources interface

interface ScriptAlertSources {
    conditions: string[];
    alerts: boolean;
    strategy: boolean;
}
MemberTypeDescription
conditionsstring[]alertcondition() titles, in source order (an untitled one reads "Alert").
alertsbooleanThe script calls alert().
strategybooleanThe script is a strategy (its order fills alert).

ScriptEvent

type ScriptEvent = 'any' | 'alert' | 'condition' | 'order-fill';

Constants

ALERTS_NATIVE_TYPE

const ALERTS_NATIVE_TYPE: 'vela-pro.alerts';

ALERTS_PANEL_ID

const ALERTS_PANEL_ID: 'vela-pro.alerts';

FREQUENCIES

const FREQUENCIES: ReadonlyArray<{ id: AlertFrequency; label: string; hint: string }>;

See also: AlertFrequency.

PRICE_OPERATORS

const PRICE_OPERATORS: ReadonlyArray<{ id: PriceOperator; label: string; channel?: boolean }>;

See also: PriceOperator.

On this page