fintech-algorithms

Time Bars

Install and import

bash
npm install fintech-algorithms
ts
import { constructBars } from "fintech-algorithms/market-data-engineering/bar-construction/time-bars";

Signature

constructBars(trades, config)

Groups a trade tape into fixed-duration bars. This is the sampling scheme every chart you have seen uses, and it is a *choice*: it samples the market at a constant rate regardless of how much is happening in it.

Parameters

NameTypeNotes
tradesTrade[]The raw tape in chronological order. Each trade carries tradeId, timestamp, session, symbol, price, volume and currency.
config{ intervalSeconds: number; sessionStarts: Record<string, string>; closePartial?: boolean; emptyBarPolicy?: "omit" }intervalSeconds sets the bar length. sessionStarts maps each session id to its opening timestamp, so bucket boundaries are anchored to the session rather than to the first trade. closePartial decides whether a final incomplete bar is emitted. emptyBarPolicy: "omit" drops intervals with no trades instead of emitting a flat bar.

Returns

Bar[] · length fewer

One bar per interval that produced trades, carrying open, high, low, close, volume and the interval boundaries.

Errors

  • When intervalSeconds is not a positive number — throws
  • When sessionStarts is missing or empty — throws

Complexity: time O(n), space O(bars).

Worked example

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input

trades
[
  {
    "tradeId": "T0001",
    "timestamp": "2026-01-05T14:30:00.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 99.99,
    "volume": 36,
    "currency": "USD"
  },
  {
    "tradeId": "T0002",
    "timestamp": "2026-01-05T14:30:04.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 99.99,
    "volume": 73,
    "currency": "USD"
  },
  {
    "tradeId": "T0003",
    "timestamp": "2026-01-05T14:30:07.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 100,
    "volume": 110,
    "currency": "USD"
  }
]

Showing 3 of 240 elements.

config
{
  "closePartial": true,
  "intervalSeconds": 60,
  "sessionStarts": {
    "2026-01-05": "2026-01-05T14:30:00.000Z",
    "2026-01-06": "2026-01-06T14:30:00.000Z"
  },
  "emptyBarPolicy": "omit"
}

Call

constructBars(trades, config)

Returns

array of 18 objects

[
  {
    "barIndex": 0,
    "session": "2026-01-05",
    "intervalIndex": 0,
    "startTime": "2026-01-05T14:30:00.000Z",
    "endTime": "2026-01-05T14:31:00.000Z",
    "firstTradeTime": "2026-01-05T14:30:00.000Z",
    "lastTradeTime": "2026-01-05T14:30:54.000Z",
    "open": 99.99,
    "high": 100.06,
    "low": 99.98,
    "close": 100.05,
    "volume": 1531,
    "dollarValue": 153130.02,
    "tickCount": 14
  },
  {
    "barIndex": 1,
    "session": "2026-01-05",
    "intervalIndex": 1,
    "startTime": "2026-01-05T14:31:00.000Z",
    "endTime": "2026-01-05T14:32:00.000Z",
    "firstTradeTime": "2026-01-05T14:31:01.000Z",
    "lastTradeTime": "2026-01-05T14:31:58.000Z",
    "open": 100.06,
    "high": 100.13,
    "low": 100.04,
    "close": 100.13,
    "volume": 1935,
    "dollarValue": 193681.33,
    "tickCount": 15
  },
  {
    "barIndex": 2,
    "session": "2026-01-05",
    "intervalIndex": 2,
    "startTime": "2026-01-05T14:32:00.000Z",
    "endTime": "2026-01-05T14:33:00.000Z",
    "firstTradeTime": "2026-01-05T14:32:06.000Z",
    "lastTradeTime": "2026-01-05T14:32:55.000Z",
    "open": 100.15,
    "high": 100.18,
    "low": 100.13,
    "close": 100.16,
    "volume": 1444,
    "dollarValue": 144624.75,
    "tickCount": 11
  }
]

Showing 3 of 18 elements.

Diagrams

Time Bars — article hero
Time Bars — boundary and state
Time Bars — construction anatomy

Calculation flow

Causal construction flow — Time Bars 
flowchart TD
    A["Receive finalized eligible trade"] --> B{"New session key?"}
    B -->|Yes| C["Apply finite-tail policy and reset"]
    B -->|No| D["Keep current interval"]
    C --> E["Compute session-relative interval index"]
    D --> E
    E --> F{"Same interval?"}
    F -->|No| G["Emit prior nonempty bar"]
    F -->|Yes| H["Accumulate trade into OHLCV and lineage"]
    G --> H
    H --> A

How it works

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References