npm package: @snps/datetime
Description: Zero-dependency date and time library with duration support
Author: Synapse Framework Team
Latest version: 0.0.2

# @snps/datetime

Zero-dependency date and time library with duration support.

## Installation

```bash
pnpm install @snps/datetime
```

## API

### `DateTime`

The `DateTime` class provides an immutable way to work with dates and times.

#### Constructor

Creates a new `DateTime` instance. If no date is provided, it defaults to the current date and time.

```typescript
import { DateTime } from '@snps/datetime';

const now = new DateTime();
const specificDate = new DateTime(new Date('2023-10-27T10:00:00.000Z'));
```

#### `now()`

Creates a new `DateTime` instance for the current date and time.

```typescript
const now = DateTime.now();
```

#### `fromTimestamp(ms: number)`

Creates a new `DateTime` instance from a timestamp in milliseconds.

```typescript
const dt = DateTime.fromTimestamp(1609459200000);
```

#### `parse(dateString: string)`

Creates a new `DateTime` instance from an ISO 8601 string.

```typescript
const dt = DateTime.parse('2021-01-01T00:00:00.000Z');
```

#### `fromDate(year: number, month: number, day: number = 1)`

Creates a new `DateTime` instance from year, month, and day components.

```typescript
const dt = DateTime.fromDate(2021, 1, 15);
```

#### `format(formatString: string)`

Formats the `DateTime` instance as a string.

```typescript
const dt = DateTime.fromDate(2021, 3, 15);
dt.format('YYYY-MM-DD'); // '2021-03-15'
```

#### `toISO()`

Formats the `DateTime` instance as an ISO 8601 string.

```typescript
const dt = DateTime.parse('2021-03-15T14:30:45.123Z');
dt.toISO(); // '2021-03-15T14:30:45.123Z'
```

#### `relative(from?: DateTime)`

Returns the relative time from the `DateTime` instance to the `from` date (or now).

```typescript
const past = DateTime.fromTimestamp(Date.now() - 30000);
past.relative(); // '30 seconds ago'
```

#### `add(duration: DateDuration)`

Adds a duration to the `DateTime` instance.

```typescript
const dt = DateTime.fromDate(2021, 1, 1);
const newDt = dt.add({ years: 1, months: 2, days: 3 });
```

#### `subtract(duration: DateDuration)`

Subtracts a duration from the `DateTime` instance.

```typescript
const dt = DateTime.fromDate(2021, 5, 15);
const newDt = dt.subtract({ years: 1, months: 2, days: 3 });
```

#### `startOfDay()`

Returns a new `DateTime` instance set to the start of the day.

```typescript
const dt = DateTime.parse('2021-01-15T14:30:45.123Z');
const start = dt.startOfDay();
```

#### `endOfDay()`

Returns a new `DateTime` instance set to the end of the day.

```typescript
const dt = DateTime.parse('2021-01-15T14:30:45.123Z');
const end = dt.endOfDay();
```

#### `isBefore(other: DateTime)`

Checks if the `DateTime` instance is before another `DateTime` instance.

```typescript
const dt1 = DateTime.fromDate(2021, 1, 1);
const dt2 = DateTime.fromDate(2021, 1, 2);
dt1.isBefore(dt2); // true
```

#### `isAfter(other: DateTime)`

Checks if the `DateTime` instance is after another `DateTime` instance.

```typescript
const dt1 = DateTime.fromDate(2021, 1, 1);
const dt2 = DateTime.fromDate(2021, 1, 2);
dt2.isAfter(dt1); // true
```

#### `isSame(other: DateTime)`

Checks if the `DateTime` instance is the same as another `DateTime` instance.

```typescript
const dt1 = DateTime.fromTimestamp(1609459200000);
const dt2 = DateTime.fromTimestamp(1609459200000);
dt1.isSame(dt2); // true
```

#### Getters

- `getYear(): number`
- `getMonth(): number`
- `getDay(): number`
- `getHours(): number`
- `getMinutes(): number`
- `getSeconds(): number`
- `valueOf(): number`
- `toDate(): Date`