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

Revisions, Vintages, and Point-in-Time Availability

Install and import#

bash
npm install fintech-algorithms
ts
import { revisionsVintagesAndPointInTimeAvailability } from "fintech-algorithms/foundations/data-variables-samples-and-measurement/revisions-vintages-and-point-in-time-availability";

Signature#

revisionsVintagesAndPointInTimeAvailability(input)

Picks the value that was genuinely knowable at a given moment by keeping only the vintages published on or before it, which is what stops a backtest reading the future.

Parameters#

NameTypeNotes
inputD00InputA plain object. Every F03 topic first reads rows, which must be a non-empty array of row objects, and derives the sorted union of every key seen across them before any per-topic branch runs, even though this topic does not use them. The calculation itself reads asOf, the cutoff timestamp, and vintages, an array of published revisions each carrying an availableAt timestamp and a value.

Returns#

{ asOf: string; value: unknown; vintage: string | null; excludedFutureVintages: number }

asOf echoes the cutoff. value and vintage come from the latest vintage whose availableAt is at or before the cutoff, and are both null when no vintage qualifies. excludedFutureVintages counts the revisions dropped for being published after the cutoff.

Errors#

  • When input is not a plain object — throws TypeError
  • When rows is missing, empty, or not an array — throws RangeError

Complexity: time O(r * c + v log v), space O(r * c + v).

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#

input
{
  "rows": [
    {
      "entity": "A",
      "timestamp": "2025-01-01T00:00:00Z",
      "value": 10,
      "rating": "low"
    },
    {
      "entity": "A",
      "timestamp": "2025-01-02T00:00:00Z",
      "value": null,
      "rating": "medium",
      "censored": true
    },
    {
      "entity": "B",
      "timestamp": "2025-01-01T00:00:00Z",
      "value": 12,
      "rating": "high"
    }
  ],
  "ordinalColumns": ["rating"],
  "populationSize": 100,
  "frameSize": 80,
  "keyColumns": ["entity", "timestamp"],
  "truncationRule": "values below 5 excluded",
  "measurements": [9.9, 10, 10.1, 10],
  "referenceValue": 10,
  "vintages": [
    {
      "availableAt": "2025-02-01T00:00:00Z",
      "value": 100
    },
    {
      "availableAt": "2025-03-01T00:00:00Z",
      "value": 102
    },
    {
      "availableAt": "2025-04-01T00:00:00Z",
      "value": 101
    }
  ],
  "asOf": "2025-03-15T00:00:00Z",
  "provenance": {
    "source": "teaching.csv",
    "owner": "Fintech Builder",
    "license": "CC-BY-4.0",
    "retrievedAt": "2026-08-10",
    "transformations": ["parse", "validate"]
  }
}

Call#

revisionsVintagesAndPointInTimeAvailability(input)

Returns#

object with 2 fields: asOf, value

{
  "asOf": "2025-03-15T00:00:00Z",
  "value": 102
}

Diagrams#

Revisions, Vintages, and Point-in-Time Availability — article hero
Revisions, Vintages, and Point-in-Time Availability — concept anatomy
Revisions, Vintages, and Point-in-Time Availability — mistake contrast
Revisions, Vintages, and Point-in-Time Availability — teaching map

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#

  • Real-Time Periods
  • Series Vintage Dates
  • Evidence boundary

The rest of the Data, Variables, Samples, and Measurement family#