Alerts
Alerts are kept by symbol. Each alert compares two things: the value watched (source: the price, or a line of an indicator) and what it is compared with (value: a number, a line of a drawing, or a line of an indicator), with the conditions (trigger) of the library's alerts: cross (crossing), cross-up (crossing up), cross-down (crossing down), above (greater than), below (less than), and the channel conditions enter-channel (entering the channel), exit-channel (exiting the channel), inside-channel (inside the channel) and outside-channel (outside the channel). A channel condition compares with the channel between two bounds, with value written as the two bounds [a, b] (in any order: on each bar the lower is taken as the bottom and the higher as the top); entering is crossing the bottom upward or the top downward, exiting the other way round, and inside and outside are whether it is between the two bounds when checked. Common ways of writing them:
- The price crossing up 68000:
{ trigger: 'cross-up', value: 68000 } - The price crossing a trend line, or the bottom of a rectangle:
{ trigger: 'cross', value: { kind: 'drawing', id, level: 'bottom' } }(levelis the line of the drawing, the first without it; a line is judged as it is drawn: extended, its extension is judged too, and a hidden Fibonacci level cannot be watched) - The price leaving a rectangle (out through the top or the bottom):
{ trigger: 'exit-channel', value: [{ kind: 'drawing', id, level: 'top' }, { kind: 'drawing', id, level: 'bottom' }] }, called "Exiting rectangle" on a rectangle (the four channel conditions on a rectangle are entering, exiting, inside and outside the rectangle); a parallel channel hasbaseandparallel, a Fibonacci tool two levels, as'0.382'and'0.618', and a price rangetopandbottomtoo - The price entering the channel from 100,000 to 105,000:
{ trigger: 'enter-channel', value: [105000, 100000] }; RSI between 30 and 70:{ source: { kind: 'indicator', type: 'RSI', key: 'rsi' }, trigger: 'inside-channel', value: [70, 30] }. Bounds can be lines of indicators too, as the upper and lower Bollinger Bands - The price falling through the neckline of a head and shoulders, or crossing an anchored VWAP or the top of a regression trend:
levelis'neckline','vwap'and'2'(a line at a ratio or a number of standard deviations is named by the number its label shows: the lines of a regression trend are'2','-2'and the base line'0', the two outer ones first, so that "entering/exiting the channel" is the whole regression channel by default; the bands of an anchored VWAP are'1'and'-1'; the rays of the time levels of a speed resistance fan are like'time-0.382') - RSI above 70:
{ source: { kind: 'indicator', type: 'RSI', key: 'rsi' }, trigger: 'above', value: 70 } - A MACD golden cross:
{ source: { kind: 'indicator', type: 'MACD', key: 'macd' }, trigger: 'cross-up', value: { kind: 'indicator', type: 'MACD', key: 'signalLine' } } - The price crossing up the 20-day moving average:
{ trigger: 'cross-up', value: { kind: 'indicator', type: 'MA', params: { periods: [20] }, key: 'ma20' } }
Indicators are computed by the type, parameters (params) and price (source) the alert noted for itself, whether or not the chart has the indicator, and whatever its parameters were changed to later. Other settings: timeframe (the timeframe of the bars judged, the current chart's without it), frequency (once, only once, paused automatically after firing; once-per-bar, at most once a bar; every-time, each time it holds), onClose (true judges only by closed bars, at most once when each bar closes, once still pausing after firing; false by default, counting bars before they close), expires (when it expires, a timestamp in milliseconds; null never expires), message (a message the user wrote, added after the alert's text when it fires), sound (a sound when it fires, on by default) and enabled (on, by default). How all alerts sound is in the state's alertSound: with on off, none sounds, and volume is the volume from 0 to 1 (on and 1 by default), with the method setAlertSound({ on?, volume? }). The chart has no interface for these two: the page puts them in its own settings.
const id = await chart.addAlert(
{
trigger: 'cross-up',
value: 70000,
frequency: 'once-per-bar',
message: 'Above the last high'
},
'BTCUSDT'
);
await chart.updateAlert(id, { expires: Date.now() + 7 * 86_400_000 });
const watched = (await chart.getAlerts()).filter((alert) => alert.status === 'watching');Every symbol is watched while the page is open. For each symbol and timeframe with alerts (on and not expired), an unseen chart in the background loads bars of the alert's timeframe, takes live data, and computes indicators and the positions of drawings, judging exactly as a chart showing that symbol and timeframe would; the market data subscriptions are shared with the charts showing the symbol, only symbols with alerts are subscribed to, and they are unsubscribed once their alerts are paused, removed or expired. An alert is judged only once, in the background, so that a chart showing the symbol at the same time does not report it twice; charts only draw the alert lines (one line for a comparison with a number, two for a channel of two numbers; an alert on an indicator is drawn in the indicator's pane, when the chart has that indicator with the same computation), and while replaying history they fire by the bars replayed (replay: true). Alert lines can be dragged, the two of a channel each on its own. Once the page is closed, nothing is watched.
Alerts with the page closed: handing them to a server. The server judges by the same bars, indicators and drawings with the open-source library's createAlertEngine() (a judge that draws nothing, with the same code for judging, indicators and drawings as the chart), exactly as the page judges. On the page: setRemoteAlerts(statuses) hands the alerts over, statuses being the status of each alert there (as { a1: 'watching', a2: 'failed' }); the page no longer watches any alert and shows these statuses (loading for those not given: still on their way over), the bottom of the alert window says "Watched with this page closed too", calling it again replaces the statuses, and null hands them back to the page. When one fires there, reportAlert(id, { time, price }) (the time and close of the bar) has the page pop up the message, sound and emit the alert event (remote: true) as for one it fired itself; an alert that fires only once is paused there, and the page does not change it. describeAlert(id) gives the title and body the page says when it fires, for the server to say the same in its push notifications.
What to hand the server: alertSpec(). The server opens no page, so it has to know how an alert is judged: by bars of which timeframe, built into which timeframe, with which trading calendar, reading which indicators and watching which drawings. alertSpec(alert, symbol, drawings, intervals) turns an alert of the page (ProChartAlert), its symbol (SymbolInfo), the drawings of the symbol (the open-source library's DrawingInput) and the datafeed's timeframes (datafeed.intervals, for a symbol that does not state its own) into this spec (AlertSpec): symbol, interval (the bars fetched), timeframe (the timeframe built, null when it is the same as interval), calendar, indicators, drawings and alert (an alert as the open-source library's createAlertEngine() takes it). Alerts of one symbol and one series of bars share a judge, and indicators with the same settings share an id, so the server computes nothing twice. When it cannot be done, it returns null: the symbol has no bars that can build the timeframe, or the alert reads an indicator only the page has (a custom indicator). When a drawing or line the alert names is not in drawings, the judge reports that it cannot watch the alert (failed) once handed over.
import { alertSpec } from '@kumo-charts/pro-chart';
// alert is an alert from getAlerts(), 'BTCUSDT' its symbol, and drawings the drawings of the symbol.
const symbol = await datafeed.resolveSymbol('BTCUSDT');
const spec = alertSpec(alert, symbol, drawings, datafeed.intervals);
if (spec) {
// The spec is JSON, for the server to keep; it fetches bars and builds a judge from it.
await fetch('/my-alerts', { method: 'PUT', body: JSON.stringify(spec) });
}status says whether the page is watching: watching (watching live data), loading (the data is on its way), paused (paused, or an alert that fires once has fired), expired (it expired) and failed (it cannot be watched: the symbol or its bars cannot be had, or the alert's drawing or indicator is gone; when the datafeed fails, it tries again after a while). Changes emit alertStatusChange.
For users: "Add an alert at the price" in the context menu adds one in a click (crossing, once); "Add alert…", "Add alert…" on the price scale, Alt+A, "Add alert…" in a drawing's context menu and the bell in an indicator's legend all open the alert window, filled in with the price, drawing or indicator; double-clicking an alert line or "Edit alert…" in its context menu changes an existing alert. At the top of the window is a one-sentence summary (as "Alerts on Price Crossing up 66,121.50, judged on 15m bars as they form, only once.", following the settings), with three groups below. Condition: Watch (price, indicator, drawing), the indicator and its plot or the drawing and its line (a channel condition takes the two lines of the "Channel", and a drawing with only two lines needs no choice; Fib retracement defaults to the two levels 0.382 and 0.618), How (the price, indicators and drawings with two lines or more all have entering, exiting, inside and outside the channel, called entering, exiting, inside and outside the rectangle on a rectangle), the price or Compared with (a value, with the current price written below; a price can be compared with an indicator's line on the main pane, and an indicator with another of its lines; a channel condition has the two rows "Upper bound" and "Lower bound", each a number or an indicator's line, 1% above and below by default for the price, and the indicator's highest and lowest reference lines by default for an indicator, as 80 and 20 for RSI), and the timeframe (each timeframe as "Live" and "On close", that is onClose). Firing: how many times it fires (once, once a bar, every time) and how long it lasts (until removed, 24 hours, 7 days, 30 days, until a time…, the time filled in in the time zone chosen for the chart). Notification: sound and a note. The bottom says "Watched while this page is open". The window has no pause: pausing and resuming are in the page's own list of alerts, with updateAlert(id, { enabled }). features: { alerts: false } takes these entry points away, the chart draws no alert lines, and the page no longer watches (nor fires during a replay); the alerts themselves are still kept and the methods work as before, and everything comes back when it is on again.