Immutable DateTime/TimeSpan for TypeScript based on .NET DateTime
Tags: typescript, showdev, javascript
Published: 2019-10-03 05:18:25

# Immutable DateTime
Date object is not immutable, and also modifying it is little complicated. There is no TimeSpan equivalent in JavaScript. So this library was created to provide DateTime/TimeSpan similar to .NET.

I know about `moment-js`, but I needed something very simpler.

# Features
1. Immutable DateTime
2. Support for TimeSpan (differences between dates)
3. Simple Add/Difference
4. Support for properties (year, month, day, hour, minute, second .. all are readonly properties)
5. Backward compatibility with JavaScript's Date

# Compatibility with Date
In order to make usage simple, you can pass DateTime to any method that uses `Date` and everything will still work. To prevent intellisense from listing all Date's methods, we have used a hack to create new Date object in constructor of DateTime.

For easy access, all `to*String` methods of `Date` are available in intellisense.

```typescript
   const d = DateTime.now();
   console.log(d instance of Date); // prints true..
   console.log(d instance of DateTime); // prints true..

   // however intellisense does not
   // show up Date methods
   d.year
```

## This library does not pollute Date's prototype, logically DateTime is a new class and has its own way of functioning.

# Json Parser
You will have to hook some code to change prototype of Date objects sent through `JSON.parse`. ` d.prototype = DateTime.prototype`.

# Usage

## Properties
Year, Month, Day, Hour, Minute, Second and Millisecond are all properties.

```typescript

   // now is a readonly property which returns new
   // instance of DateTime of current system time
   const d = DateTime.now;

   console.log(`${d.year}-${d.month}-${d.day}`);
```

## Trim Time
```typescript
   const d = DateTime.now;

   // returns new instance of DateTime
   // with time part trimmed...
   const day = d.date;
```

## TimeSpan
```typescript
   const d = DateTime.now;

   // t is of type TimeSpan
   const t = d.time;

   console.log(t); // prints 10.00 PM (local time)
```

## Difference in TimeSpan
```typescript

   const d1 = new DateTime(2010, 1, 1);
   const d2 = new DateTime(2012, 1, 1);

   // returns TimeSpan
   const diff = d2.diff(d1);

   // prints 730
   console.log(diff.totalDays);

```

## Add TimeSpan
```typescript
   
   const t = TimeSpan.fromDays(2);
   const d1 = new DateTime(2010, 1, 1);

   const d2 = d1.add(t);

   // prints 2010-01-03
   console.log(d2); 

```

# Type Information

```typescript
export default class DateTime {
    static get today(): DateTime;
    static get utcNow(): DateTime;
    static get now(): DateTime;

    static parse(s: string): DateTime;

    get hour(): number;
    get minute(): number;
    get second(): number;
    get millisecond(): number;
    get day(): number;
    get dayOfWeek(): number;
    get month(): number;
    get year(): number;
    get timeZoneOffset(): TimeSpan;
    get msSinceEpoch(): number;

    /** Strips time of the day and returns Date only */
    get date(): DateTime;

    get asJSDate(): Date;

    get time(): TimeSpan;

    constructor();
    constructor(time?: number | string);
    constructor(year?: number, 
       month?: number, date?: number, hours?: number,
       minutes?: number, seconds?: number, ms?: number);

    add(d: DateTime | TimeSpan): DateTime;

    add(days: number, hours?: number, minutes?: number,
       seconds?: number, milliseconds?: number): DateTime;

    addMonths(m: number): DateTime;
    addYears(y: number): DateTime;

    diff(rhs: Date | DateTime): TimeSpan;
    equals(d: DateTime): boolean;

    // for easy access, following methods
    // are available on intellisense

    toLocaleString (locales?: string | string[],
       options?: Intl.DateTimeFormatOptions): string;

    toLocaleDateString (locales?: string | string[],
       options?: Intl.DateTimeFormatOptions): string;

    toLocaleTimeString (locales?: string | string[],
       options?: Intl.DateTimeFormatOptions): string;

    toUTCString(): string;

    toISOString(): string;

    toJSON(key?: any): string;
    toTimeString(): string;
    toDateString(): string;
}
```

{% github web-atoms/date-time %}