Streams

// ---------------------------------------------------------------------------
// Requests: what `subscribe` returns
// ---------------------------------------------------------------------------

/**
 * History a `bars` or `orderFlow` stream loads before the chart's range
 * start: a bar count, a duration, or `"session"` for back to the open of the
 * session the range starts in. Missing history stays missing.
 *
 * Without it a stream loads the chart's range only. It follows the range:
 * when the chart loads older bars, the stream loads the same older range
 * plus its warmup and sends it as backfill.
 */
export type WarmupOption = number | Duration | "session";

/**
 * Bar size: `"1m"`, `"5m"`, `"4h"`, `"1D"`, `"1W"`, `"1M"`. `s` seconds, `m`
 * minutes, `h` hours, `D` days, `W` weeks, `M` months.
 */
export type Timeframe = `${number}${"s" | "m" | "h" | "D" | "W" | "M"}`;

/** Length of time: `"30s"`, `"15m"`, `"4h"`, `"1d"`, `"2w"`. */
export type Duration = `${number}${"s" | "m" | "h" | "d" | "w"}`;

/** Side that took liquidity: `Buy` lifted the ask, `Sell` hit the bid. */
export type Aggressor = "Buy" | "Sell" | "Unknown";

/** A value from the user's own data source, or why there is none. */
export type DataEvent<T> =
  | { readonly type: "Value"; readonly value: T }
  | { readonly type: "Error"; readonly error: DataError };

// ---------------------------------------------------------------------------
// Pull access: what a stream has received so far, in `ctx.streams.<name>`
// ---------------------------------------------------------------------------

/** Loading state of a market or platform stream, in its view's `status`. */
export type StreamStatus =
  /** Nothing loaded yet. */
  | { readonly type: "Loading" }
  /**
   * Data is complete from `from` (epoch ms) to now. Older history still
   * loading moves `from` back. Before `from` the stream can have partial data.
   */
  | { readonly type: "Ready"; readonly from: number }
  /**
   * Data is complete from `from` (epoch ms) to now and older history is
   * loading: a bar before `from` has no data yet, not no data.
   */
  | { readonly type: "LoadingOlder"; readonly from: number }
  /** The stream failed, e.g. `NoAccess` when the data feed has no order flow. Nothing more arrives. */
  | { readonly type: "Unavailable"; readonly error: StreamError };