npm package: @neumatter/datetime
Description: Module for using date and time. Enables the use of time zones and calendars.
Author: Cal Young
Latest version: 1.0.7


# DateTime
[![JavaScript Style Guide](https://cdn.rawgit.com/standard/standard/master/badge.svg)](https://github.com/standard/standard)

<br />

## Table of Contents
- [ Installation ](#install)
- [ DateTime ](#datetime)

<br />

<a name="install"></a>
## Install

```console
npm i @neumatter/datetime
```

<br />

<a name="datetime"></a>
## DateTime

### static `DateTime.from`:

Args [
  `item: string | bigint | number | DateTime | DateTimeLike`,
  `options?: {
    timeZone?: string | TimeZone,
    calendar?: string | Calendar,
    overflow?: 'constrain' | 'reject'
  }`
]

Returns `DateTime`

```js
import { DateTime } from '@neumatter/datetime'

// All returns: DateTime(2023-04-16T13:00:00-05:00[America/Chicago])
DateTime.from({
  year: 2023,
  month: 4,
  day: 16,
  hour: 13,
  timeZone: 'America/Chicago'
})
DateTime.from('2023-04-16T13:00:00-05:00[America/Chicago]')
DateTime.from(1681668000000000000n, { timeZone: 'America/Chicago' })
```

### static `DateTime.now`:

Args [
  `options?: {
    timeZone?: string | TimeZone,
    calendar?: string | Calendar
  }`
]

Returns `DateTime` - The current time.

```js
import { DateTime } from '@neumatter/datetime'

DateTime.now({ timeZone: 'America/Chicago' })
DateTime.now({ timeZone: 'Europe/Rome', calendar: 'hebrew' })
DateTime.now()
```

### static `DateTime.compare`:

Args [`a: DateTime`, `b: DateTime`]

Returns `-1 | 0 | 1`

### static `DateTime.max`:

Args [`...dateTime: Array<DateTime>`]

Returns `DateTime` - The largest value.

### static `DateTime.min`:

Args [`...dateTime: Array<DateTime>`]

Returns `DateTime` - The smallest value.

### static `DateTime.isDateTime`:

Args [`input: any`]

Returns `boolean` - If the input is a DateTime object.

### constructor `new DateTime`:

Args [
  `year?: number`,
  `month?: number`,
  `day?: number`,
  `hour?: number`,
  `minute?: number`,
  `second?: number`,
  `millisecond?: number`,
  `microsecond?: number`,
  `nanosecond?: number`,
  `timeZone?: string | TimeZone`,
  `calendar?: string | Calendar`
]

Returns `DateTime`

### property `isZonedDate: boolean`

### property `hasISOCalendar: boolean`

### property `calendar: Calendar`

### property `year: number`

### property `month: number`

### property `monthCode: string`

### property `day: number`

### property `hour: number`

### property `minute: number`

### property `second: number`

### property `millisecond: number`

### property `microsecond: number`

### property `nanosecond: number`

### property `timeZone: TimeZone`

### property `era: string | undefined`

### property `eraYear: number | undefined`

### property `dayOfWeek: number`

### property `dayOfYear: number`

### property `weekOfYear: number`

### property `daysInWeek: number`

### property `daysInYear: number`

### property `daysInMonth: number`

### property `monthsInYear: number`

### property `inLeapYear: boolean`

### property `epochSeconds: number`

### property `epochMilliseconds: number`

### property `epochNanoseconds: bigint`

### property `offsetNanoseconds: number`

### property `offset: string`

### property `startOfDay: DateTime`

### method `with (isoDateLike: {})`:

`isoDateLike.year?: number`
`isoDateLike.month?: number`
`isoDateLike.day?: number`
`isoDateLike.hour?: number`
`isoDateLike.minute?: number`
`isoDateLike.second?: number`
`isoDateLike.millisecond?: number`
`isoDateLike.microsecond?: number`
`isoDateLike.nanosecond?: number`
`isoDateLike.timeZone?: TimeZone`
`isoDateLike.calendar?: Calendar`

Returns a new `DateTime` with the given properties.

### method `withTimeZone (timeZoneId: string)`:

Returns a new `DateTime` with the given `TimeZone`.