Registry / data / vega-time

vega-time

JSON →
library3.1.0jsnpmunverified

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.

npm install vega-time
INSTALL
IMPORT
SIG · VEGA-TIME
V
vega-time
datajavascriptv3.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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
Debug
Known issues
breakingVega 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).
affects: >=6.0.0
gotchaA 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.
affects: <5.33.1
gotchaPrior 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.
affects: <6.0.0
gotchaIn 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.
affects: <5.31.0
Errors
Common errors & fixes
ReferenceError: require is not defined
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.
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.
Upgrade
Version history
3.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
vega-time — npm install vega-time · libregistry