Time Bars

Install and import#

bash

npm install fintech-algorithms

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#

Name	Type	Notes
`trades`	`Trade[]`	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#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

trades

[
  {
    "tradeId": "W1",
    "timestamp": "2026-01-05T14:30:00.000Z",
    "session": "S1",
    "symbol": "SYNTH",
    "price": 100,
    "volume": 10,
    "currency": "USD"
  },
  {
    "tradeId": "W2",
    "timestamp": "2026-01-05T14:30:59.999Z",
    "session": "S1",
    "symbol": "SYNTH",
    "price": 101,
    "volume": 5,
    "currency": "USD"
  },
  {
    "tradeId": "W3",
    "timestamp": "2026-01-05T14:31:00.000Z",
    "session": "S1",
    "symbol": "SYNTH",
    "price": 99,
    "volume": 8,
    "currency": "USD"
  }
]

Showing 3 of 4 elements.

config

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

Call#

constructBars(trades, config)

Returns#

array of 3 objects

[
  {
    "barIndex": 0,
    "session": "S1",
    "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:59.999Z",
    "open": 100,
    "high": 101,
    "low": 100,
    "close": 101,
    "volume": 15,
    "dollarValue": 1505,
    "tickCount": 2
  },
  {
    "barIndex": 1,
    "session": "S1",
    "intervalIndex": 1,
    "startTime": "2026-01-05T14:31:00.000Z",
    "endTime": "2026-01-05T14:32:00.000Z",
    "firstTradeTime": "2026-01-05T14:31:00.000Z",
    "lastTradeTime": "2026-01-05T14:31:00.000Z",
    "open": 99,
    "high": 99,
    "low": 99,
    "close": 99,
    "volume": 8,
    "dollarValue": 792,
    "tickCount": 1
  },
  {
    "barIndex": 2,
    "session": "S1",
    "intervalIndex": 3,
    "startTime": "2026-01-05T14:33:00.000Z",
    "endTime": "2026-01-05T14:34:00.000Z",
    "firstTradeTime": "2026-01-05T14:33:15.000Z",
    "lastTradeTime": "2026-01-05T14:33:15.000Z",
    "open": 102,
    "high": 102,
    "low": 102,
    "close": 102,
    "volume": 2,
    "dollarValue": 204,
    "tickCount": 1
  }
]

Diagrams#

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#

NYSE Daily TAQ Client Specification — New York Stock Exchange, an Intercontinental Exchange company
Trading Information — New York Stock Exchange
Auctions — New York Stock Exchange
Rule 613: Consolidated Audit Trail — U.S. Securities and Exchange Commission
Evidence and data decision

Time Bars

Install and import#

Signature#

Parameters#

Returns#

Errors#

Worked example#

Input#

Call#

Returns#

Diagrams#

Calculation flow#

How it works#

References#

The rest of the Bar Construction family#