time-values v1.2.2

time-values

Gets the year, month, day, hour, minute, and second values of a date object or string.

The time is converted to the local timezone regardless of the format it's in.

Examples:

import getTimeValues from 'time-values'

const d = new Date()
d.setFullYear('2022')
d.setMonth(3) // April
d.setDate(30) // Day
d.setHours(4)
d.setMinutes(40)
d.setSeconds(10)

const timeValues = getTimeValues(d)

console.log({
  year: timeValues.year, // 2022
  month: timeValues.month, // 4
  day: timeValues.day, // 30
  hour: timeValues.hour, // 4
  minute: timeValues.minute, // 40
  second: timeValues.second // 10
})

const timeValues = getTimeValues('2022-04-30T04:40:10')
console.log({
  year: timeValues.year, // 2022
  month: timeValues.month, // 4
  day: timeValues.day, // 30
  hour: timeValues.hour, // 4
  minute: timeValues.minute, // 40
  second: timeValues.second // 10
})

const timeValues = getTimeValues() // year, month, etc. for the current time

This works with MOST common date formats (such as yyyy-mm-ddThh:mm:ss and mm/dd/yyyy). It even supports some of the weirder ones.

The object returned from the getTimeValues() function can also be passed back into it, or any object literal that optionally defines year, month, day, hour, minute, or second. Omitting any of these properties defaults to the current date values.

const timeValues = getTimeValues({
  year: 2022,
  month: 12,
  day: 20,
})
console.log({
  year: timeValues.year, // 2022
  month: timeValues.month, // 12
  day: timeValues.day, // 20
  hour: timeValues.hour, // (whatever the local hour is)
  minute: timeValues.minute, // (local minute)
  second: timeValues.second // (local second)
})

Each of the time properties can be "out of range" as well, and it will be corrected in the generated output. This is useful for calculating date arithmetic, such as getting the date one week from the initial value:

const timeValues = getTimeValues({ year: 2022, month: 12, day: 25 })
const weekLater = getTimeValues({ ...timeValues, day: timeValues.day + 7 })
console.log({
  year: weekLater.year, // 2023
  month: weekLater.month, // 1
  day: weekLater.day, // 1
})

Another example:

const timeValues = getTimeValues({
  year: 2022,
  month: 13, // overflows the year
  day: 20,
  hour: 18,
  minute: 0,
  second: -1 // underflows minutes
})
console.log({
  year: timeValues.year, // 2023
  month: timeValues.month, // 1
  day: timeValues.day, // 20
  hour: timeValues.hour, // 17
  minute: timeValues.minute, // 59
  second: timeValues.second // 59
})

To convert a the time value object returned back into a date object, use the getTimeValues.toDate() function:

import getTimeValues from 'time-values'

const date = getTimeValues.toDate({
  year: 2022,
  month: 9,
  day: 3,
  hour: 12,
  minute: 30,
  second: 10
})

date.toISOString() // '2022-09-03T16:30:10.000Z'

getTimeValues.toDate('2022-09-03T16:30:10.000Z').toISOString() // 2022-09-03T16:30:10.000Z