@bernierllc/validators-temporal-consistency

Temporal consistency validation for the BernierLLC validators ecosystem. Validates ISO8601 formats, timezone offsets, DST handling, date ranges, and timestamp ordering.

Installation

npm install @bernierllc/validators-temporal-consistency

Features

• ISO 8601 Format Validation - Ensures dates and timestamps follow ISO 8601 standard
• Timezone Validation - Validates timezone offsets are in correct format and valid range
• Date Range Validation - Ensures start dates come before end dates
• Timestamp Ordering - Validates timestamps in sequences are chronologically ordered
• DST Awareness - Warns about potential DST transition issues

Usage

Basic Validation

import { validateTemporalConsistency } from '@bernierllc/validators-temporal-consistency';

const data = {
  created_at: '2025-01-15T10:00:00Z',
  updated_at: '2025-01-15T10:30:00Z',
  start_date: '2025-01-15',
  end_date: '2025-01-20'
};

const result = await validateTemporalConsistency(data);

if (result.problems.length > 0) {
  result.problems.forEach(problem => {
    console.log(`${problem.severity}: ${problem.message}`);
  });
}

Validating Timestamp Arrays

import { validateTemporalConsistency } from '@bernierllc/validators-temporal-consistency';

const eventLog = {
  timestamps: [
    '2025-01-15T10:00:00Z',
    '2025-01-15T10:05:00Z',
    '2025-01-15T10:10:00Z',
    '2025-01-15T10:15:00Z'
  ]
};

const result = await validateTemporalConsistency(eventLog);

Using Individual Rules

import {
  invalidIso8601Format,
  invalidTimezone,
  invalidDateRange,
  invalidTimestampOrdering,
  dstTransitionIssue
} from '@bernierllc/validators-temporal-consistency';

// Use individual rules as needed

Validation Rules

1. Invalid ISO 8601 Format

Validates that temporal data follows ISO 8601 standard format.

Valid Formats:

• Date: YYYY-MM-DD
• DateTime: YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD HH:MM:SS
• DateTime with timezone: YYYY-MM-DDTHH:MM:SS+00:00 or YYYY-MM-DDTHH:MM:SSZ
• DateTime with milliseconds: YYYY-MM-DDTHH:MM:SS.sss

Examples:

// Valid
{ date: '2025-01-15' }
{ timestamp: '2025-01-15T10:30:00Z' }
{ datetime: '2025-01-15T10:30:00.123+05:30' }

// Invalid
{ date: '01/15/2025' }  // Wrong format
{ timestamp: '2025-1-15T10:30:00' }  // Missing leading zeros
{ date: '2025-13-01' }  // Invalid month

2. Invalid Timezone

Validates timezone offsets are in valid ISO 8601 format and within valid range.

Valid Range: -12:00 to +14:00 Valid Minutes: 00, 15, 30, 45

Examples:

// Valid
{ timezone: 'Z' }  // UTC
{ timezone: '+05:30' }  // Valid offset
{ timestamp: '2025-01-15T10:30:00-08:00' }

// Invalid
{ timezone: 'EST' }  // Named timezones not supported
{ timezone: '+15:00' }  // Out of range
{ timezone: '+05:20' }  // Invalid minutes

3. Invalid Date Range

Validates that end dates come after start dates.

Checked Pairs:

• start_date / end_date
• start_time / end_time
• created_at / updated_at

Examples:

// Valid
{
  start_date: '2025-01-15',
  end_date: '2025-01-20'
}

// Invalid
{
  start_date: '2025-01-20',
  end_date: '2025-01-15'  // End before start
}

4. Invalid Timestamp Ordering

Validates timestamps in arrays are in chronological order.

Examples:

// Valid
{
  timestamps: [
    '2025-01-15T10:00:00Z',
    '2025-01-15T10:30:00Z',
    '2025-01-15T11:00:00Z'
  ]
}

// Invalid
{
  timestamps: [
    '2025-01-15T10:00:00Z',
    '2025-01-15T11:00:00Z',
    '2025-01-15T10:30:00Z'  // Out of order
  ]
}

5. DST Transition Issue

Warns about potential DST issues when timestamps fall during transition periods without explicit timezone information.

Transition Periods:

• March (Northern Hemisphere spring forward)
• November (Northern Hemisphere fall back)
• April (Southern Hemisphere fall back)
• October (Southern Hemisphere spring forward)

Examples:

// No warning - explicit timezone
{ timestamp: '2025-03-15T02:30:00-08:00' }
{ timestamp: '2025-03-15T02:30:00Z' }

// Warning - DST transition without timezone
{ timestamp: '2025-03-15T02:30:00' }
{ timestamp: '2025-11-10T02:00:00' }  // Ambiguous hour

Temporal Field Names

The validator checks these common temporal field names:

• timestamp
• date
• datetime
• created_at
• updated_at
• start_time
• end_time
• start_date
• end_date
• timezone
• timestamps (array)

API Reference

validateTemporalConsistency<T>(data: T, utils?: SharedUtils): Promise<ValidationResult>

Main validation function that runs all temporal consistency rules.

Parameters:

• data - The temporal data to validate
• utils - Optional shared utilities (auto-created if not provided)

Returns: Promise resolving to validation result with problems array

temporalConsistencyValidator

The primitive validator instance with all rules configured.

Properties:

• name: string - Validator name ('temporal-consistency')
• domain: ValidationDomain - Validation domain ('schema')
• rules: Rule[] - Array of all validation rules

metadata

Package metadata including version, description, and rule information.

Real-World Examples

API Response Validation

const apiResponse = {
  id: '123',
  created_at: '2025-01-15T10:00:00Z',
  updated_at: '2025-01-15T10:30:00Z',
  data: { value: 'test' }
};

const result = await validateTemporalConsistency(apiResponse);

Booking System

const booking = {
  start_date: '2025-01-15',
  end_date: '2025-01-20',
  created_at: '2025-01-10T10:00:00Z',
  updated_at: '2025-01-10T10:30:00Z'
};

const result = await validateTemporalConsistency(booking);

Time-Series Data

const timeSeries = {
  timestamps: [
    '2025-01-15T10:00:00Z',
    '2025-01-15T10:01:00Z',
    '2025-01-15T10:02:00Z',
    '2025-01-15T10:03:00Z'
  ]
};

const result = await validateTemporalConsistency(timeSeries);

Event Logs

const events = {
  timestamps: [
    '2025-01-15T10:00:00Z',
    '2025-01-15T10:05:00Z',
    '2025-01-15T10:10:00Z'
  ]
};

const result = await validateTemporalConsistency(events);

Error Severity Levels

• error - Invalid format, out-of-range values, ordering violations
• warn - DST issues, future timestamps, duplicate timestamps

Integration with Validators Ecosystem

This package is part of the BernierLLC validators ecosystem:

• Built on @bernierllc/validators-core for consistent rule structure
• Uses @bernierllc/validators-utils for shared utilities
• Compatible with @bernierllc/validators-runner for advanced workflows
• Supports all standard reporter formats (JSON, Markdown, SARIF, JUnit)

Using with Runner

import { ValidatorRunner } from '@bernierllc/validators-runner';
import { temporalConsistencyValidator } from '@bernierllc/validators-temporal-consistency';

const runner = new ValidatorRunner({
  validators: [temporalConsistencyValidator],
  // ... other config
});

const result = await runner.validate(data);

Integration Status

• Logger: not-applicable - Pure validation package, no runtime logging needed
• Docs-Suite: ready - Complete API documentation with TypeDoc comments
• NeverHub: not-applicable - Primitive validator with no service dependencies

TypeScript Support

This package is written in TypeScript and includes full type definitions.

import type {
  Problem,
  ValidationResult,
  Rule,
  RuleContext
} from '@bernierllc/validators-core';

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

See Also

• @bernierllc/validators-core - Core validation types and utilities
• @bernierllc/validators-utils - Shared validation utilities
• @bernierllc/validators-runner - Validation orchestration
• @bernierllc/validators-reporters - Result formatting