Volume-Imbalance Bars: Build Candles from Signed Shares Without Look-Ahead

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

/** Causal volume-imbalance bars under this package's explicit convention. */
export type Trade = {
  tradeId: string; timestamp: string; session: string; symbol: string;
  price: number; volume: number; currency: string;
};
export type Config = {
  closePartial?: boolean;
  initialTickSign?: -1 | 1;
  initialExpectedTicks?: number;
  initialExpectedSignedVolume?: number;
  alphaTicks?: number;
  alphaSignedVolume?: number;
  thresholdFloorShares?: number;
  thresholdScale?: number;
};
export type Bar = {
  barIndex: number; session: string; startTime: string; endTime: string;
  open: number; high: number; low: number; close: number; volume: number;
  dollarValue: number; tickCount: number; firstTradeId: string; lastTradeId: string;
  closeReason: "threshold" | "session_end" | "stream_end"; isComplete: boolean;
  signedVolume: number; thresholdShares: number; expectedTicksBefore: number;
  expectedSignedVolumeBefore: number; overshootShares: number; thresholdMet: boolean;
};

function timestamp(value: unknown): number {
  if (typeof value !== "string" || !value.endsWith("Z"))
    throw new Error("timestamp must be an ISO-8601 UTC string ending in Z");
  const parsed = Date.parse(value);
  if (!Number.isFinite(parsed)) throw new Error("timestamp must be valid ISO-8601");
  return parsed;
}
function finite(value: unknown, name: string, positive = false): number {
  if (typeof value !== "number" || !Number.isFinite(value))
    throw new Error(`${name} must be a finite number`);
  if (positive && value <= 0) throw new Error(`${name} must be positive`);
  return value;
}
function rounded(value: number): number { return Number(value.toFixed(8)); }
function normalized(config: Config) {
  if (config === null || typeof config !== "object") throw new Error("config must be an object");
  const closePartial = config.closePartial ?? true;
  if (typeof closePartial !== "boolean") throw new Error("closePartial must be boolean");
  const initialSign = config.initialTickSign ?? 1;
  if (initialSign !== -1 && initialSign !== 1) throw new Error("initialTickSign must be -1 or 1");
  const alphaTicks = finite(config.alphaTicks ?? .2, "alphaTicks", true);
  const alphaSigned = finite(config.alphaSignedVolume ?? .2, "alphaSignedVolume", true);
  if (alphaTicks > 1 || alphaSigned > 1) throw new Error("EMA coefficients must be in (0, 1]");
  return {
    closePartial, initialSign,
    initialExpectedTicks: finite(config.initialExpectedTicks ?? 16, "initialExpectedTicks", true),
    initialExpectedSigned: finite(config.initialExpectedSignedVolume ?? 35, "initialExpectedSignedVolume"),
    alphaTicks, alphaSigned,
    floor: finite(config.thresholdFloorShares ?? 300, "thresholdFloorShares", true),
    scale: finite(config.thresholdScale ?? 1, "thresholdScale", true),
  };
}
function validateTrades(trades: Trade[]): void {
  if (!Array.isArray(trades)) throw new Error("trades must be an array");
  const ids = new Set<string>(), closedSessions = new Set<string>();
  let previous = -Infinity, currentSession: string | null = null;
  let symbol: string | null = null, currency: string | null = null;
  for (const trade of trades) {
    if (!trade || typeof trade !== "object") throw new Error("trade is missing a required field");
    for (const key of ["tradeId", "timestamp", "session", "symbol", "currency"] as const)
      if (typeof trade[key] !== "string" || !trade[key]) throw new Error(`${key} must be a non-empty string`);
    const now = timestamp(trade.timestamp);
    if (now < previous) throw new Error("trades must be globally chronological");
    previous = now;
    if (ids.has(trade.tradeId)) throw new Error("tradeId must be unique after corrections are resolved");
    ids.add(trade.tradeId);
    finite(trade.price, "price", true); finite(trade.volume, "volume", true);
    if (symbol === null) { symbol = trade.symbol; currency = trade.currency; }
    else if (trade.symbol !== symbol || trade.currency !== currency)
      throw new Error("one symbol and one currency are allowed per call");
    if (currentSession === null) currentSession = trade.session;
    else if (trade.session !== currentSession) {
      closedSessions.add(currentSession);
      if (closedSessions.has(trade.session)) throw new Error("a session may not reappear after a later session begins");
      currentSession = trade.session;
    }
  }
}

export function constructBars(trades: Trade[], config: Config): Bar[] {
  const cfg = normalized(config); validateTrades(trades);
  if (!trades.length) return [];
  const result: Bar[] = [];
  let current: Trade[] = [], session: string | null = null, previousPrice: number | null = null;
  let tickSign = cfg.initialSign, expectedTicks = cfg.initialExpectedTicks;
  let expectedSigned = cfg.initialExpectedSigned, signedVolume = 0;
  let frozenThreshold = 0, frozenExpectedTicks = 0, frozenExpectedSigned = 0;
  const beginBar = () => {
    current = []; signedVolume = 0;
    frozenExpectedTicks = expectedTicks; frozenExpectedSigned = expectedSigned;
    frozenThreshold = Math.max(cfg.floor, cfg.scale * frozenExpectedTicks * Math.abs(frozenExpectedSigned));
  };
  const emit = (reason: Bar["closeReason"]) => {
    if (!current.length) return;
    const prices = current.map(t => t.price), volumes = current.map(t => t.volume);
    const thresholdMet = Math.abs(signedVolume) >= frozenThreshold;
    result.push({
      barIndex: result.length, session: current[0].session,
      startTime: current[0].timestamp, endTime: current.at(-1)!.timestamp,
      open: rounded(prices[0]), high: rounded(Math.max(...prices)), low: rounded(Math.min(...prices)),
      close: rounded(prices.at(-1)!), volume: rounded(volumes.reduce((a,b) => a+b, 0)),
      dollarValue: rounded(current.reduce((a,t) => a+t.price*t.volume, 0)), tickCount: current.length,
      firstTradeId: current[0].tradeId, lastTradeId: current.at(-1)!.tradeId,
      closeReason: reason, isComplete: reason === "threshold", signedVolume: rounded(signedVolume),
      thresholdShares: rounded(frozenThreshold), expectedTicksBefore: rounded(frozenExpectedTicks),
      expectedSignedVolumeBefore: rounded(frozenExpectedSigned),
      overshootShares: rounded(Math.max(Math.abs(signedVolume)-frozenThreshold, 0)), thresholdMet,
    });
    if (reason === "threshold") {
      const observedTicks = current.length, observedSigned = signedVolume / observedTicks;
      expectedTicks = (1-cfg.alphaTicks)*expectedTicks + cfg.alphaTicks*observedTicks;
      expectedSigned = (1-cfg.alphaSigned)*expectedSigned + cfg.alphaSigned*observedSigned;
    }
    beginBar();
  };
  beginBar();
  for (const trade of trades) {
    if (session !== null && trade.session !== session) {
      if (current.length && cfg.closePartial) emit("session_end"); else beginBar();
      expectedTicks = cfg.initialExpectedTicks; expectedSigned = cfg.initialExpectedSigned;
      previousPrice = null; tickSign = cfg.initialSign; beginBar();
    }
    session = trade.session;
    if (previousPrice !== null)
      tickSign = trade.price > previousPrice ? 1 : trade.price < previousPrice ? -1 : tickSign;
    previousPrice = trade.price; current.push(trade); signedVolume += tickSign*trade.volume;
    if (Math.abs(signedVolume) >= frozenThreshold) emit("threshold");
  }
  if (current.length && cfg.closePartial) emit("stream_end");
  return result;
}