ranged-date

ranged-date

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.

Warning:

• Although it is unlikely for a given number to fall within the default range (one year), it is advisable to both restrict the range and use exclusions wherever possible, in order to avoid incorrectly classifying and converting values that were not intended to be timestamps.

Getting Started

Prerequisites

Node.JS version 6.0.0 or above.

Installing

npm i ranged-date

Testing

The following command will test the package for errors.

npm test

Deployment

const rangedDate = require('ranged-date')

Usage

const sec    = ~~(Date.now() / 1000) // Test unixtime
const ms     = sec * 1000            // Test millisecond time
const us     = ms * 1000             // Test microsecond time
const past   = sec - 31536000        // Unixtime one year prior
const future = sec + 31536000        // Unixtime one year after

console.log(rangedDate(sec))                        // converted time in ms
console.log(rangedDate(ms))                         // time in ms
console.log(rangedDate(us))                         // converted time in ms
console.log(rangedDate(String(sec)))                // converted time in ms
console.log(rangedDate(past))                       // false
console.log(rangedDate(past, 2))                    // converted time in ms
console.log(rangedDate(future))                     // false
console.log(rangedDate(future, null, 2))            // converted time in ms
console.log(rangedDate(sec, 0.5, 0.5, { s: true })) // false
console.log(rangedDate(ms, 0.5, 0.5, { ms: true })) // false
console.log(rangedDate(us, 0.5, 0.5, { us: true })) // false
console.log(
  rangedDate(new Date(ms), 0.5, 0.5, { ms: true })
)                                                   // converted time in ms

Documentation

rangedDate ⇒ number | boolean

Param	Type	Attributes	Default	Description
data	Date | number | string			Data to attempt to recognize as valid date.
back	number	<optional>	0.5	Years before current date as lower bound.
fwd	number	<optional>	0.5	Years after current date as upper bound.
exclude	rangedDate~exclude	<optional>	{}	Specifies range exclusions, if any.

Returns: number | boolean - Converted ms or false if outside range.

rangedDate~exclude

Settings for exclusion of milliseconds, seconds, or microseconds as possibilities for range matching.

Properties

Name	Type	Attributes	Description
ms	boolean	<optional>	Exclude milliseconds.
s	boolean	<optional>	Exclude seconds.
us	boolean	<optional>	Exclude microseconds.

See

• API Docs
• Global Docs

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