@time-provider/plugin-native

Time-Provider ~ Native plugin

Description

This is the native Date plugin for Time-Provider.

Usage

import { createTimeProvider } from "@time-provider/core";
import { createTimeProvider as createDeterministicTimeProvider } from "@time-provider/core/deterministic";
import { plugin } from "@time-provider/plugin-native";
import { plugin as deterministicPlugin } from "@time-provider/plugin-native/deterministic";

// System: real clock and timers. This plugin is UTC-only.
const timeProvider = createTimeProvider.for(plugin).create();
timeProvider.clock.utcNow(); // a native Date

// Deterministic: a simulated clock that only moves when you move it.
using manual = createDeterministicTimeProvider
  .for(deterministicPlugin)
  .asManual()
  .withInitialTime("2026-01-01T00:00:00.000Z")
  .create();
manual.clock.moveBy({ hours: 1 });
manual.clock.utcNow(); // 2026-01-01T01:00:00.000Z

Notes

JavaScript's native Date object lacks a time zone-aware object type that stores and performs arithmetic in a specific time zone.

As a result, Time-Provider intentionally does not expose time zone or local-time APIs for Date.
This plugin provides a UTC-only facade.

If you need first-class time zone support, consider using Temporal together with the Time-Provider Temporal plugin.

If you need to keep using the native Date object, you can extend it by adding time zone support with the date-fns and date-fns-tz, outside the scope of Time-Provider.

Changelog

See CHANGELOG.md