Vega Time Utilities

3.1.0 · active · verified Sun Apr 19

vega-time is a JavaScript utility package providing a suite of date and time manipulation functions specifically designed for use within the Vega visualization ecosystem. It offers functionalities for parsing, formatting, flooring, and ceiling time values, crucial for handling temporal data in data visualizations. As part of the larger Vega monorepo, its development is closely aligned with Vega's evolution, ensuring seamless integration. The current stable version of the Vega monorepo is v6.2.0, with vega-time benefiting from this active development cycle which includes regular minor and patch releases. A significant change in the v6 series is the transition to an ESM-only distribution, impacting how the library is imported and used in modern JavaScript environments. This package differentiates itself by offering robust, performant time utilities tailored for data visualization contexts, handling various time units and interval operations that are common in charting and graphing.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use CommonJS 'require()' to import vega-time in a project configured for ESM, or using a version of Node.js that defaults to ESM.

fix Change 'const { timeFormat } = require("vega-time");' to 'import { timeFormat } from "vega-time";'. Ensure your package.json has '"type": "module"' or use .mjs file extensions.
```
Date results are incorrect or 'Invalid Date' when parsing strings.
```
cause The format string provided to `timeParse` does not accurately match the input date string, or the input string is not a valid date.

fix Carefully review the `timeParse` format specifiers (e.g., '%Y' for full year, '%m' for month, '%d' for day) and ensure they precisely map to your input string's structure. Test with known valid date strings and their corresponding formats.

Warnings

breaking Vega monorepo packages, including vega-time, transitioned to ESM-only starting with v6.0.0. CommonJS 'require()' statements will no longer work.
Fix: Update all import statements from 'require("pkg")' to 'import { Symbol } from "pkg";' and ensure your project is configured for ESM (e.g., '"type": "module"' in package.json or using .mjs file extensions).
gotcha A security advisory (GHSA-7f2v-3qq3-vvjf) regarding improved expressions was fixed in v5.33.1 for v5 releases. Users on older v5 versions might be vulnerable.
Fix: Upgrade to vega v5.33.1 or later to mitigate the security vulnerability. For v6 users, the fix is implicitly included.
gotcha Prior to v6.0.0, the Vega interpreter had issues correctly handling string datetime values, which could lead to unexpected behavior in visualizations using temporal data.
Fix: Upgrade to vega v6.0.0 or later to ensure proper handling of string datetimes within expressions and interpreters.
gotcha In v5.31.0, internal utility functions in vega-utils (which vega-time may depend on) were updated to use `Object.hasOwn` instead of `Object.prototype.hasOwnProperty`. This is a minor change but indicates a move towards more modern JavaScript features.
Fix: Ensure your environment supports `Object.hasOwn` (Node.js >= 16.9.0, modern browsers). For older environments, a polyfill might be necessary if experiencing issues, though this is primarily an internal implementation detail.

Install

npm install vega-time npm
yarn add vega-time yarn
pnpm add vega-time pnpm

Imports

timeFormat
wrong:
```
const timeFormat = require('vega-time').timeFormat;
```
correct:
```
import { timeFormat } from 'vega-time';
```
Vega packages, including vega-time, are ESM-only since v6.0.0. Use named imports.
timeParse
wrong:
```
import vegaTime from 'vega-time'; const timeParse = vegaTime.timeParse;
```
correct:
```
import { timeParse } from 'vega-time';
```
vega-time primarily uses named exports. Avoid attempting to import as a default or destructuring from a default import.
timeMonth
wrong:
```
import { month } from 'vega-time';
```
correct:
```
import { timeMonth } from 'vega-time';
```
Time interval objects (e.g., for floor/ceil operations) are typically prefixed with 'time' (e.g., timeMonth, timeDay).

Quickstart

Demonstrates how to import and use core vega-time functions for formatting, parsing, flooring, and offsetting dates using various time intervals.

import { timeFormat, timeParse, timeFloor, timeMonth } from 'vega-time';

// Example 1: Formatting a date into a specific string format
const now = new Date();
const formattedDate = timeFormat('%Y-%m-%d')(now);
console.log(`Formatted date: ${formattedDate}`);
// Expected output: e.g., Formatted date: 2026-04-19 (or current date)

// Example 2: Parsing a date string into a Date object
const dateString = '2023-10-26 14:30:00';
const parse = timeParse('%Y-%m-%d %H:%M:%S');
const parsedDate = parse(dateString);
console.log(`Parsed date: ${parsedDate}`);
// Expected output: e.g., Parsed date: Thu Oct 26 2023 14:30:00 GMT...

// Example 3: Flooring a date to the beginning of the nearest month
const specificDate = new Date('2026-04-19T10:00:00Z');
const flooredToMonth = timeFloor(timeMonth)(specificDate);
console.log(`Date floored to month: ${flooredToMonth}`);
// Expected output: e.g., Date floored to month: Sat Apr 01 2026 00:00:00 GMT...

// Example 4: Offsetting a date by a specific time interval
const today = new Date('2026-04-19T12:00:00Z');
const nextMonth = timeMonth.offset(today, 1);
console.log(`Today: ${today.toISOString()}`);
console.log(`Next month: ${nextMonth?.toISOString()}`);
// Expected output: e.g., Next month: 2026-05-19T12:00:00.000Z

view raw JSON →