@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

``bash
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

$3

`typescript
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});
});
}
`

$3

`typescript
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);
`

$3

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

// Use individual rules as needed
`

Validation Rules

$3

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:

`typescript
// 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
`

$3

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:

`typescript
// 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

Validates that end dates come after start dates.

Checked Pairs:
- start_date / end_date
- start_time / end_time
- created_at / updated_at

Examples:

`typescript
// 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
}
`

$3

Validates timestamps in arrays are in chronological order.

Examples:

`typescript
// 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
]
}
`

$3

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:

`typescript
// 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

$3

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

$3

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

$3

Package metadata including version, description, and rule information.

Real-World Examples

$3

`typescript
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);
`

$3

`typescript
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);
`

$3

`typescript
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);
`

$3

`typescript
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)

$3

`typescript
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.

`typescript
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