time-values/README.md

Gets date/time attributes from a date or string with no dependencies

# 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:

```js
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
})
```

```js
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
})
```

```js
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.

```js
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:

```js
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:

```js
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:

```js
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
```