Timestamps, Time Zones, Calendars, and Observation Time

Install and import#

npm install fintech-algorithms

import { timestampsTimeZonesCalendarsAndObservationTime } from "fintech-algorithms/foundations/data-variables-samples-and-measurement/timestamps-time-zones-calendars-and-observation-time";

Signature#

timestampsTimeZonesCalendarsAndObservationTime(input)

Audits a table's timestamps: whether the rows arrive in chronological order, whether every stamp carries a zone, and which rows sit at the two ends of the span.

Parameters#

Returns#

{ ordered: boolean; timezoneAware: boolean; first: string; last: string }

ordered is true when no row's timestamp precedes the one before it. timezoneAware is true only when every timestamp ends in a Z or an explicit numeric offset. first and last are the raw timestamp strings of the earliest and latest rows.

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), space O(r * c).

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#

{
  "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#

timestampsTimeZonesCalendarsAndObservationTime(input)

Returns#

object with 2 fields: ordered, timezoneAware

{
  "ordered": false,
  "timezoneAware": true
}

Diagrams#

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#

• Theory and Naming
• Time Series and Date Functionality
• Evidence boundary

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

• Observations, Entities, Variables, and DatasetsCounts what a table actually contains: how many rows, how many distinct columns across all of them, and how many distinct entit…
• Numeric, Categorical, Ordinal, and Binary VariablesClassifies every column of a table as binary, numeric, ordinal or categorical by inspecting the values actually present in it.
• Population, Sample, Census, and Sampling FrameRelates the rows in hand to the population they are meant to represent and to the frame they were drawn from, reporting the sam…
• Cross-Sectional, Time-Series, Panel, and Event DataInfers a table's layout from the shape of its own keys, deciding whether the rows are cross-sectional, a time series, a panel, …
• Identifiers, Keys, Joins, and Data GrainChecks whether a proposed set of key columns really identifies one row each, which is what makes a table safe to join.
• Missing, Nonfinite, Censored, and Truncated ValuesTallies the ways a table's value column can fail to be an ordinary number, separating missing entries, non-finite ones and ce…
• Measurement Error, Resolution, Accuracy, and PrecisionCompares repeated measurements against a known reference to separate accuracy from precision, and reads the instrument's resolu…
• Revisions, Vintages, and Point-in-Time AvailabilityPicks the value that was genuinely knowable at a given moment by keeping only the vintages published on or before it, which is …
• Data Provenance, Lineage, Ownership, and LicensingChecks a dataset's provenance record against the five fields the engine treats as mandatory and reports which of them are absent.