Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
The d3-time npm package is a module that provides utilities for manipulating dates in JavaScript. It is part of the D3 (Data-Driven Documents) suite of tools, which are used for producing dynamic, interactive data visualizations in web browsers. d3-time is specifically designed to handle time scales, sequences, and intervals, making it a powerful tool for dealing with temporal data.
Time Scales
Create a time scale that maps a domain of dates to a range of numeric values. This is useful for creating time-based charts.
const timeScale = d3.scaleTime().domain([new Date(2020, 0, 1), new Date(2020, 11, 31)]).range([0, 100]);
Time Intervals
Generate an array of dates at regular intervals, such as every month between two dates. This is useful for generating axis ticks or processing data at regular time intervals.
const start = new Date(2020, 0, 1); const end = new Date(2020, 11, 31); const everyMonth = d3.timeMonth.every(1); const months = everyMonth.range(start, end);
Time Formatting
Format dates according to a specified pattern. This is useful for displaying dates in a human-readable format.
const formatTime = d3.timeFormat('%B %d, %Y'); const formatted = formatTime(new Date(2020, 0, 1));
Moment.js is a legacy package for parsing, validating, manipulating, and formatting dates. It is more feature-rich than d3-time but is also larger in size. Moment.js has been a go-to library for date operations, though it is now considered a legacy project in maintenance mode.
date-fns provides the most comprehensive, yet simple and consistent toolset for manipulating JavaScript dates in a browser & Node.js. It offers a modular approach, where you can pick and choose which functions to include. It is a modern alternative to Moment.js and is often preferred for its smaller bundle sizes and functional programming approach.
Luxon is a powerful, modern, and friendly wrapper for JavaScript dates and times. Created by one of the Moment.js team members, it includes internationalization support and operates on the Intl API. It is a good alternative to d3-time when complex date manipulation and formatting are required.
When visualizing time series data, analyzing temporal patterns, or working with time in general, the irregularities of conventional time units quickly become apparent. In the Gregorian calendar, for example, most months have 31 days but some have 28, 29 or 30; most years have 365 days but leap years have 366; and with daylight saving, most days have 24 hours but some have 23 or 25. Adding to complexity, daylight saving conventions vary around the world.
As a result of these temporal peculiarities, it can be difficult to perform seemingly-trivial tasks. For example, if you want to compute the number of days that have passed between two dates, you can’t simply subtract and divide by 24 hours (86,400,000 ms):
var start = new Date(2015, 02, 01), // Sun Mar 01 2015 00:00:00 GMT-0800 (PST)
end = new Date(2015, 03, 01); // Wed Apr 01 2015 00:00:00 GMT-0700 (PDT)
(end - start) / 864e5; // 30.958333333333332, oops!
You can, however, use day.count:
d3_time.day.count(start, end); // 31
Day is one of several time intervals provided by d3-time. Each interval represents a conventional unit of time—hours, weeks, months, etc.—and has methods to calculate boundary dates. For example, the day interval computes midnight (typically 12:00 AM local time) of the corresponding day. In addition to rounding and counting, intervals can also be used to generate arrays of boundary dates. For example, to compute each Sunday in the current month:
var now = new Date;
d3_time.week.range(d3_time.month.floor(now), d3_time.month.ceil(now));
// [Sun Jun 07 2015 00:00:00 GMT-0700 (PDT),
// Sun Jun 14 2015 00:00:00 GMT-0700 (PDT),
// Sun Jun 21 2015 00:00:00 GMT-0700 (PDT),
// Sun Jun 28 2015 00:00:00 GMT-0700 (PDT)]
The d3-time module does not implement its own calendaring system; it merely implements a convenient API for calendar math on top of ECMAScript Date. Thus, it ignores leap seconds and can only work with the local time zone and Coordinated Universal Time (UTC).
This module is used by D3’s time scales to generate sensible ticks, by D3’s time format, and can also be used directly to do things like calendar layouts.
If you use NPM, npm install d3-time
. Otherwise, download the latest release. The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom build using Rollup or your preferred bundler. You can also load directly from d3js.org:
<script src="https://d3js.org/d3-time.v0.1.min.js"></script>
In a vanilla environment, a d3_time
global is exported. Try d3-time in your browser.
# interval(date)
Alias for interval.floor. For example, year(date)
and year.floor(date)
are equivalent.
# interval.floor(date)
Returns a new date representing the latest interval boundary date before or equal to date. For example, d3_time.day.floor(new Date)
typically returns 12:00 AM local time on the current day.
This method is idempotent: if the specified date is already floored to the current interval, a new date with an identical time is returned. Furthermore, the returned date is the minimum expressible value of the associated interval, such that floor(floor(date) - 1) returns the preceeding interval boundary date.
Note that the ==
and ===
operators do not compare by value with Date objects, and thus you cannot use them to tell whether the specified date has already been floored. Instead, coerce to a number and then compare:
// Returns true if the specified date is a day boundary.
function isDay(date) {
return +d3_time.day.floor(date) === +date;
}
This is more reliable than testing whether the time is 12:00 AM, as in some time zones midnight may not exist due to daylight saving.
# interval.round(date)
Returns a new date representing the closest interval boundary date to date. For example, day.round(new Date)
typically returns 12:00 AM local time on the current day if it is on or before noon, and 12:00 AM of the following day if it is after noon.
This method is idempotent: if the specified date is already rounded to the current interval, a new date with an identical time is returned.
# interval.ceil(date)
Returns a new date representing the earliest interval boundary date after or equal to date. For example, d3_time.day.ceil(new Date)
typically returns 12:00 AM local time on the following day.
This method is idempotent: if the specified date is already ceilinged to the current interval, a new date with an identical time is returned. Furthermore, the returned date is the maximum expressible value of the associated interval, such that eil(ceil(date) + 1) returns the following interval boundary date.
# interval.offset(date[, step])
Returns a new date equal to date plus step intervals. If step is not specified it defaults to 1. If step is negative, then the returned date will be before the specified date; if step is zero, then a copy of the specified date is returned; if step is not an integer, it is floored. This method does not round the specified date to the interval. For example, if it is currently 5:34 PM, then d3_time.day.offset(new Date, 1)
returns 5:34 PM tomorrow (even if daylight saving changes!).
# interval.range(start, stop[, step])
Returns every an array of dates representing every interval boundary after or equal to start (inclusive) and before stop (exclusive). If step is specified, then every stepth interval will be returned; for example, for the day interval a step of 2 will return every other day. If step is not an integer, it is floored.
# interval.filter(test)
Returns a new interval that is a filtered subset of this interval using the specified test function. The test function is passed a date and should return true if and only if the specified date should be considered part of the interval. For example, to create an interval that returns the 1st, 11th, 21th and 31th (if it exists) of each month:
var i = d3_time.day.filter(function(d) { return (d.getDate() - 1) % 10 === 0; });
The returned filtered interval does not support count. See also interval.every.
# interval.every(step)
Returns a filtered view of this interval representing every stepth date. The meaning of step is dependent on this interval’s parent interval as defined by the field function. For example, minute.every(15) returns an interval representing every fifteen minutes, starting on the hour: :00, :15, :30, :45, etc. Note that for some intervals, such as day, the resulting dates may be irregularly spaced. If step is not valid, returns null. If step is one, returns this interval.
# interval.count(start, end)
Returns the number of interval boundaries after start (exclusive) and before or equal to end (inclusive). Note that this behavior is slightly different than interval.range because its purpose is to return the zero-based number of the specified end date relative to the specified start date. For example, to compute the current zero-based day-of-year number:
var now = new Date;
d3_time.day.count(d3_time.year(now), now); // 177
Likewise, to compute the current zero-based week-of-year number for weeks that start on Sunday:
d3_time.sunday.count(d3_time.year(now), now); // 25
# d3_time.interval(floor, offset[, count[, field]])
Constructs a new custom interval given the specified floor and offset functions and an optional count function.
The floor function takes a single date as an argument and rounds it down to the nearest interval boundary.
The offset function takes a date and an integer step as arguments and advances the specified date by the specified number of boundaries; the step may be positive, negative or zero.
The optional count function takes a start date and an end date, already floored to the current interval, and returns the number of boundaries between the start (exclusive) and end (inclusive). If a count function is not specified, the returned interval does not expose count or every methods. Note: due to an internal optimization, the specified count function must not invoke interval.count on other time intervals.
The optional field function takes a date, already floored to the current interval, and returns the field value of the specified date, corresponding to the number of boundaries between this date (exclusive) and the latest previous parent boundary. For example, for the day interval, this returns the number of days since the start of the month. The field function defines the behavior of interval.every.
The following intervals are provided:
# d3_time.millisecond
# d3_time.utcMillisecond
Milliseconds; the shortest available time unit.
# d3_time.second
# d3_time.utcSecond
Seconds (e.g., 01:23:45.0000 AM); 1,000 milliseconds.
# d3_time.minute
# d3_time.utcMinute
Minutes (e.g., 01:02:00 AM); 60 seconds. Note that ECMAScript ignores leap seconds.
# d3_time.hour
# d3_time.utcHour
Hours (e.g., 01:00 AM); 60 minutes. Note that advancing time by one hour in local time can return the same hour or skip an hour due to daylight saving.
# d3_time.day
# d3_time.utcDay
Days (e.g., February 7, 2012 at 12:00 AM); typically 24 hours. Days in local time may range from 23 to 25 hours due to daylight saving.
# d3_time.week
# d3_time.utcWeek
Alias for sunday; 7 days and typically 168 hours. Weeks in local time may range from 167 to 169 hours due on daylight saving.
# d3_time.sunday
# d3_time.utcSunday
Sunday-based weeks (e.g., February 5, 2012 at 12:00 AM).
# d3_time.monday
# d3_time.utcMonday
Monday-based weeks (e.g., February 6, 2012 at 12:00 AM).
# d3_time.tuesday
# d3_time.utcTuesday
Tuesday-based weeks (e.g., February 7, 2012 at 12:00 AM).
# d3_time.wednesday
# d3_time.utcWednesday
Wednesday-based weeks (e.g., February 8, 2012 at 12:00 AM).
# d3_time.thursday
# d3_time.utcThursday
Thursday-based weeks (e.g., February 9, 2012 at 12:00 AM).
# d3_time.friday
# d3_time.utcFriday
Friday-based weeks (e.g., February 10, 2012 at 12:00 AM).
# d3_time.saturday
# d3_time.utcSaturday
Saturday-based weeks (e.g., February 11, 2012 at 12:00 AM).
# d3_time.month
# d3_time.utcMonth
Months (e.g., February 1, 2012 at 12:00 AM); ranges from 28 to 31 days.
# d3_time.year
# d3_time.utcYear
Years (e.g., January 1, 2012 at 12:00 AM); ranges from 365 to 366 days.
For convenience, aliases for interval.range are also provided as plural forms of the corresponding interval.
# d3_time.milliseconds(start, stop[, step])
# d3_time.utcMilliseconds(start, stop[, step])
Aliases for millisecond.range and utcMillisecond.range.
# d3_time.seconds(start, stop[, step])
# d3_time.utcSeconds(start, stop[, step])
Aliases for second.range and utcSecond.range.
# d3_time.minutes(start, stop[, step])
# d3_time.utcMinutes(start, stop[, step])
Aliases for minute.range and utcMinute.range.
# d3_time.hours(start, stop[, step])
# d3_time.utcHours(start, stop[, step])
Aliases for hour.range and utcHour.range.
# d3_time.days(start, stop[, step])
# d3_time.utcDays(start, stop[, step])
Aliases for day.range and utcDay.range.
# d3_time.weeks(start, stop[, step])
# d3_time.utcWeeks(start, stop[, step])
Aliases for week.range and utcWeek.range.
# d3_time.sundays(start, stop[, step])
# d3_time.utcSundays(start, stop[, step])
Aliases for sunday.range and utcSunday.range.
# d3_time.mondays(start, stop[, step])
# d3_time.utcMondays(start, stop[, step])
Aliases for monday.range and utcMonday.range.
# d3_time.tuesdays(start, stop[, step])
# d3_time.utcTuesdays(start, stop[, step])
Aliases for tuesday.range and utcTuesday.range.
# d3_time.wednesdays(start, stop[, step])
# d3_time.utcWednesdays(start, stop[, step])
Aliases for wednesday.range and utcWednesday.range.
# d3_time.thursdays(start, stop[, step])
# d3_time.utcThursdays(start, stop[, step])
Aliases for thursday.range and utcThursday.range.
# d3_time.fridays(start, stop[, step])
# d3_time.utcFridays(start, stop[, step])
Aliases for friday.range and utcFriday.range.
# d3_time.saturdays(start, stop[, step])
# d3_time.utcSaturdays(start, stop[, step])
Aliases for saturday.range and utcSaturday.range.
# d3_time.months(start, stop[, step])
# d3_time.utcMonths(start, stop[, step])
Aliases for month.range and utcMonth.range.
# d3_time.years(start, stop[, step])
# d3_time.utcYears(start, stop[, step])
FAQs
A calculator for humanity’s peculiar conventions of time.
The npm package d3-time receives a total of 6,895,838 weekly downloads. As such, d3-time popularity was classified as popular.
We found that d3-time demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.