The @perfective/common/date package provides functions to work with the Date type.

There are a couple important differences in how @perfective handles the Date values.

• @perfective treats Date objects as immutable, so setter methods are not supported.

• @perfective functions return null instead of the Invalid Date instances.

  Using null allows to combine the results of the functions using Maybe:

  import { date, Timestamp, timestamp } from '@perfective/common/date`;
  import { Maybe, just } from '@perfective/common/maybe';
  
  function parseTime(input: string): Maybe<number> { // (1)
      const time = Date.parse(input);
      if (Number.isNaN(time)) {
          return nothing();
      }
      return just(time);
  }
  
  function maybeTime(input: string): Maybe<Timestamp> { // (2)
      return just(input).to(date).to(timestamp);
  }

  1. Date.parse(input) returns a number or NaN, so additional checks are required.

  2. date() function returns Date | null, so it’s easily chained into Maybe.

• Constructors:

  • date(date: Date): Date | null; — creates a copy of a given date. If the given date is Invalid Date, returns null.

  • date(timestamp: Timestamp): Date | null — creates a Date for a given Timestamp. If the given Timestamp is invalid, returns null.

  • date(input: string): Date | null — parses a Date from a given input string. If the given input cannot be parsed, returns null.

  • now(): Date — creates a Date for the current moment. Uses Date.now(), so it can be mocked in the tests (for example, in Jest).

  • epoch(): Date — creates a Date for the Unix epoch (i.e., January 1, 1970, 00:00:00 UTC).

• Predicates:

  • isValid(date: Date): boolean — returns true if a given Date is a valid (not an Invalid Date).

  • isInvalid(date: Date): boolean — returns true if a given Date is an Invalid Date.

• Timestamp = number — an alias type for number and is specified in milliseconds since the Unix epoch.

• timestamp(date: Date): Timestamp | null — returns a Timestamp for a given date. If the given Date is Invalid Date, returns null.

• timestamp(input: string): Timestamp | null — parses a given date/time input string as a Timestamp. If the given input is invalid, returns null.

  Use instead of the Date.parse() function, as it’s easy to compose using maybe().