ranged-date

MIGRATION NOTICE:

• ranged-date 2.0.0: back and forward ranges are now mandatory (were 0.5 each by default in 1.x.x).
• ranged-date 2.0.0: Date Objects with values outside of the specified range will return false (would return Date Object in 1.x.x).

Converts a given string, number, or Date object to the number of milliseconds since the Unix epoch, provided that it can be recognized as millisecond, second, or microsecond time within a specified range from the current date.

Milliseconds, seconds, or microseconds may be excluded as possibilities for range matching.

Useful for:

• Parsing timestampted data from external APIs.
• Integrating collections containing mixed timestamp formats.

Getting Started

Prerequisites

Node.JS version 6.0.0 or above.

Installing

npm i ranged-date

Testing

The following commands will test the package for errors.

cd /path/to/node_modules/ranged-date
npm test

API

Table of Contents

• ranged-date
• module:cert-is.TypeAssertionError
• module:cert-is.RangeAssertionError

ranged-date

index.js:150-178

Converts a given string, number, or Date object to the number of milliseconds since the Unix epoch, provided that it can be recognized as millisecond, second, or microsecond time within a specified range from the current date.

Parameters

• data (Date | number | string) Data to attempt to recognize as valid date.
• yrBack number Years before current date as lower bound.
• yrFwd number Years after current date as upper bound.
• exclusions Object Specifies interpretation exclusions, if any.
  • exclusions.us boolean Exclude microseconds interpretation. (optional, default false)
  • exclusions.ms boolean Exclude milliseconds interpretation. (optional, default false)
  • exclusions.s boolean Exclude seconds interpretation. (optional, default false)

Examples

// All return current time in ms
rangedDate(new Date(), 1, 1)
rangedDate(Date.now(), 1, 1)
rangedDate(new Date().toString(), 1, 1)
rangedDate(String(Date.now()), 1, 1)
 
// All return false
rangedDate(Date.now() - 10000000, 0.0000001, 0.0000001)
rangedDate(Date.now(), 1, 1, {ms: true})
 
// All throw cert-is TypeAssertionErrors
rangedDate()
rangedDate(new Date())
rangedDate({})
rangedDate(328385)
 
// Throws cert-is RangeAssertionError
rangedDate(Date.now(), -1, -1)

• Throws (module:cert-is.TypeAssertionError | module:cert-is.RangeAssertionError) Throws an assertion error if parameter requirements are not met.

Returns (number | boolean) Converted time in ms or false if outside range.

module:cert-is.TypeAssertionError

index.js:150-178

Thrown by cert-is in response to a type assertion error.

Type: Error

module:cert-is.RangeAssertionError

index.js:150-178

Thrown by cert-is in response to a range assertion error.

Type: Error

Versioning

Versioning using SemVer. For available versions, see the tags on this repository.

Author

• Justin Collier - jpcx

License

This project is licensed under the ISC License - see the LICENSE.md file for details