{"id":12348,"library":"vega-time","title":"Vega Time Utilities","description":"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.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/vega/vega","tags":["javascript","vega","date","time","utilities"],"install":[{"cmd":"npm install vega-time","lang":"bash","label":"npm"},{"cmd":"yarn add vega-time","lang":"bash","label":"yarn"},{"cmd":"pnpm add vega-time","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Vega packages, including vega-time, are ESM-only since v6.0.0. Use named imports.","wrong":"const timeFormat = require('vega-time').timeFormat;","symbol":"timeFormat","correct":"import { timeFormat } from 'vega-time';"},{"note":"vega-time primarily uses named exports. Avoid attempting to import as a default or destructuring from a default import.","wrong":"import vegaTime from 'vega-time'; const timeParse = vegaTime.timeParse;","symbol":"timeParse","correct":"import { timeParse } from 'vega-time';"},{"note":"Time interval objects (e.g., for floor/ceil operations) are typically prefixed with 'time' (e.g., timeMonth, timeDay).","wrong":"import { month } from 'vega-time';","symbol":"timeMonth","correct":"import { timeMonth } from 'vega-time';"}],"quickstart":{"code":"import { timeFormat, timeParse, timeFloor, timeMonth } from 'vega-time';\n\n// Example 1: Formatting a date into a specific string format\nconst now = new Date();\nconst formattedDate = timeFormat('%Y-%m-%d')(now);\nconsole.log(`Formatted date: ${formattedDate}`);\n// Expected output: e.g., Formatted date: 2026-04-19 (or current date)\n\n// Example 2: Parsing a date string into a Date object\nconst dateString = '2023-10-26 14:30:00';\nconst parse = timeParse('%Y-%m-%d %H:%M:%S');\nconst parsedDate = parse(dateString);\nconsole.log(`Parsed date: ${parsedDate}`);\n// Expected output: e.g., Parsed date: Thu Oct 26 2023 14:30:00 GMT...\n\n// Example 3: Flooring a date to the beginning of the nearest month\nconst specificDate = new Date('2026-04-19T10:00:00Z');\nconst flooredToMonth = timeFloor(timeMonth)(specificDate);\nconsole.log(`Date floored to month: ${flooredToMonth}`);\n// Expected output: e.g., Date floored to month: Sat Apr 01 2026 00:00:00 GMT...\n\n// Example 4: Offsetting a date by a specific time interval\nconst today = new Date('2026-04-19T12:00:00Z');\nconst nextMonth = timeMonth.offset(today, 1);\nconsole.log(`Today: ${today.toISOString()}`);\nconsole.log(`Next month: ${nextMonth?.toISOString()}`);\n// Expected output: e.g., Next month: 2026-05-19T12:00:00.000Z","lang":"typescript","description":"Demonstrates how to import and use core vega-time functions for formatting, parsing, flooring, and offsetting dates using various time intervals."},"warnings":[{"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).","message":"Vega monorepo packages, including vega-time, transitioned to ESM-only starting with v6.0.0. CommonJS 'require()' statements will no longer work.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Upgrade to vega v5.33.1 or later to mitigate the security vulnerability. For v6 users, the fix is implicitly included.","message":"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.","severity":"gotcha","affected_versions":"<5.33.1"},{"fix":"Upgrade to vega v6.0.0 or later to ensure proper handling of string datetimes within expressions and interpreters.","message":"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.","severity":"gotcha","affected_versions":"<6.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<5.31.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: require is not defined"},{"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.","cause":"The format string provided to `timeParse` does not accurately match the input date string, or the input string is not a valid date.","error":"Date results are incorrect or 'Invalid Date' when parsing strings."}],"ecosystem":"npm"}