fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Candlestick Pattern Occurrence Contract

Install and import#

bash
npm install fintech-algorithms
ts
import { makeOccurrence } from "fintech-algorithms/price-action-and-candlesticks/candlestick-scanning-and-context/candlestick-pattern-occurrence-contract";

Signature#

makeOccurrence(data)

normalize detector hits into reproducible occurrences with stable identity, causal timestamps, version, geometry score, and reason codes.

Parameters#

NameTypeNotes
data{ instrument_id: string; interval: string; price_basis: string; session: string; pattern_id: string; pattern_name: string; direction: string; start_index: number; end_index: number; start_time: string; end_time: string; detected_at: string; available_at: string; bar_closed: boolean; detector_version: string; geometry_score: number; reason_codes: string[] }Topic input record; the required fields are fixed by this topic data-contract.

Returns#

{ occurrence_id, instrument_id, interval, price_basis, session, pattern_id, pattern_name, direction, start_index, end_index, start_time, end_time, detected_at, available_at, bar_closed, detector_version, geometry_score, reason_codes }

One normalized closed-bar occurrence with a deterministic identity, causal timestamps, detector version, bounded geometry score, and explicit reason codes.

Complexity: time O(n log n) worst case; see README for topic-specific n, space O(n).

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#

data
{
  "instrument_id": "SYNTH:AAA",
  "interval": "5m",
  "price_basis": "raw-trades",
  "session": "synthetic-utc",
  "pattern_id": "D06-F03-A01",
  "pattern_name": "Bullish Engulfing",
  "direction": "bullish",
  "start_index": 10,
  "end_index": 11,
  "start_time": "2026-01-05T10:00:00Z",
  "end_time": "2026-01-05T10:05:00Z",
  "detected_at": "2026-01-05T10:05:01Z",
  "available_at": "2026-01-05T10:05:01Z",
  "bar_closed": true
}

Showing 14 of 17 fields.

Call#

makeOccurrence(data)

Returns#

object with 3 fields: occurrence_id, bar_closed, geometry_score

{
  "occurrence_id": "SYNTH:AAA|5m|2026-01-05T10:05:00Z|D06-F03-A01|10:11|v1",
  "bar_closed": true,
  "geometry_score": 0.9
}

Diagrams#

Candlestick Pattern Occurrence Contract — decision

Calculation flow#

Decision flow 
flowchart LR
    A["Validated point-in-time input"] --> B["Validate identity and clocks"]
    B --> C["Require a closed terminal bar"]
    C --> D{"Boundary satisfied?"}
    D -->|"Yes"| E["Reason-coded ready output"]
    D -->|"No"| F["Explicit rejected or unavailable state"]

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#

The rest of the Candlestick Scanning and Context family#