ranged-date - npm Package Compare versions

Comparing version 1.0.7 to 1.1.0

docs/API.md

 ## Module
 
-### rangedDate ⇒ <code>number</code> \| <code>boolean</code>
-Converts a given string, number, or Date object to the number of milliseconds since the Unix epoch, provided that it can be recognized as seconds, milliseconds, or microseconds within a specified range in years from the current date.
+### <a name="rangedDate"></a> rangedDate ⇒ <code>number</code> \| <code>boolean</code>
+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 time range from the current date.
 
-**Returns**: <code>number</code> \| <code>boolean</code> - Converted time in ms or false if outside range.
-
 | Param | Type | Attributes | Default | Description |
 | --- | --- | --- | --- | --- |
-| data | <code>Date &#124; number &#124; string</code> |  |  | Data to attempt to recognize as valid date. |
-| low | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years before current date as lower bound. |
-| up | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years after current date as upper bound. |
-> Source: [index.js](https://github.com/jpcx/ranged-date/blob/master/index.js), [line 69](https://github.com/jpcx/ranged-date/blob/master/index.js#L69)
+| data | <code>Date</code> \| <code>number</code> \| <code>string</code> |  |  | Data to attempt to recognize as valid date. |
+| back | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years before current date as lower bound. |
+| fwd | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years after current date as upper bound. |
+| exclude | <code><a href="#rangedDate~exclude">rangedDate~exclude</a></code> | <code>&#60;optional&#62;</code> | <code>{}</code> | Specifies type exclusions, if any. |
 
+> Source: [index.js](https://github.com/jpcx/ranged-date/blob/master/index.js), [line 109](https://github.com/jpcx/ranged-date/blob/master/index.js#L109)
+
+**Returns**: <code>number</code> \| <code>boolean</code> - Converted time in ms or false if outside range.  
+
 **Example**  
 ```js
-//returns current time in ms
+// returns current time in ms
 rangedDate(new Date())
@@ -22,3 +24,3 @@ ```
 ```js
-//returns current time in ms
+// returns current time in ms
 rangedDate(String(new Date()))
@@ -28,3 +30,3 @@ ```
 ```js
-//returns current time in ms
+// returns current time in ms
 rangedDate(Date.now())
@@ -34,3 +36,3 @@ ```
 ```js
-//returns current time in ms
+// returns current time in ms
 rangedDate(String(Date.now()))
@@ -40,13 +42,13 @@ ```
 ```js
-//returns current time in ms
-rangedDate(Date.now() * 1000)
+// returns current time in ms
+rangedDate(Date.now() / 1000)
 ```
 **Example**  
 ```js
-//returns current time in ms
-rangedDate(Date.now() / 1000)
+// returns current time in ms
+rangedDate(Date.now() * 1000)
 ```
 **Example**  
 ```js
-//returns false
+// returns false
 rangedDate(Date.now() - 10000, 0.0000001, 0.0000001)
@@ -56,3 +58,3 @@ ```
 ```js
-//returns current time in ms - 10000
+// returns current time in ms - 10000
 rangedDate(Date.now() - 10000, 0.000001, 0.000001)
@@ -62,3 +64,3 @@ ```
 ```js
-//returns false
+// returns false
 rangedDate(10)
@@ -68,9 +70,9 @@ ```
 ```js
-//returns 10
-const yrSinceEpoch = new Date().getUTCFullYear() - 1970
-rangedDate(10, yrSinceEpoch + 2)
+// returns 10
+const yrSince1970 = new Date().getUTCFullYear() - 1970
+rangedDate(10, yrSince1970 + 2)
 ```
 **Example**  
 ```js
-//returns false
+// returns false
 rangedDate(Date.now() + 100000000000)
@@ -80,4 +82,68 @@ ```
 ```js
-//returns current time in ms + 100000000000
+// returns current time in ms + 100000000000
 rangedDate(Date.now() + 100000000000, 0.1, 5)
 ```
+**Example**  
+```js
+// returns -946771200000
+const yrSince1940 = new Date().getUTCFullYear() - 1940
+rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2))
+```
+**Example**  
+```js
+// returns false
+rangedDate(Date.now(), 0.5, 0.5, { ms: true })
+```
+**Example**  
+```js
+// returns current time in ms
+rangedDate(Date.now(), 0.5, 0.5, { s: true, us: true })
+```
+**Example**  
+```js
+// returns false
+rangedDate(Date.now() / 1000, 0.5, 0.5, { s: true })
+```
+**Example**  
+```js
+// returns current time in ms
+rangedDate(Date.now() / 1000, 0.5, 0.5, { ms: true, us: true })
+```
+**Example**  
+```js
+// returns false
+rangedDate(Date.now() * 1000, 0.5, 0.5, { us: true })
+```
+**Example**  
+```js
+// returns current time in ms
+rangedDate(Date.now() * 1000, 0.5, 0.5, { ms: true, s: true })
+```
+**Example**  
+```js
+// returns false
+rangedDate(Date.now(), 0.5, 0.5, { ms: true, s: true, us: true })
+```
+**Example**  
+```js
+// returns current time in ms
+rangedDate(new Date(), 0.5, 0.5, { ms: true, s: true, us: true })
+```
+**Example**  
+```js
+// returns false
+rangedDate(String(new Date()), 0.5, 0.5, { ms: true, s: true, us: true })
+```
+
+## Typedefs
+
+### <a name="rangedDate~exclude"></a> <code>rangedDate~exclude</code>
+Settings for exclusion of milliseconds, seconds, or microseconds as possibilities for type matching.
+
+**Properties**
+
+| Name | Type | Attributes | Description |
+| --- | --- | --- | --- |
+| ms | <code>boolean</code> | <code>&#60;optional&#62;</code> | Exclude milliseconds. |
+| s | <code>boolean</code> | <code>&#60;optional&#62;</code> | Exclude seconds. |
+| us | <code>boolean</code> | <code>&#60;optional&#62;</code> | Exclude microseconds. |

docs/global.md

@@ -7,9 +7,9 @@ ## Global Functions
 </dd>
-<dt><a href="#yrDist">yrDist(t)</a> ⇒ <code>number</code></dt>
-<dd><p>Returns the difference of a number and the current date in ms, in years from the current date.</p>
+<dt><a href="#yrDist">yrDist(target)</a> ⇒ <code>number</code></dt>
+<dd><p>Returns the difference of a number and the current date in ms as years from the current date.</p>
 </dd>
-<dt><a href="#bound">bound(t, l, u)</a> ⇒ <code>number</code> | <code>boolean</code></dt>
+<dt><a href="#bound">bound(target, back, fwd)</a> ⇒ <code>number</code> | <code>boolean</code></dt>
 <dd><p>Returns the given number only if it falls within a given range in years from the current date.</p>
 </dd>
-<dt><a href="#check">check(t, l, u)</a> ⇒ <code>number</code> | <code>boolean</code></dt>
+<dt><a href="#check">check(target, back, fwd, exclude)</a> ⇒ <code>number</code> | <code>boolean</code></dt>
 <dd><p>Returns time in ms if number itself, seconds equivalent, or microseconds equivalent falls within a given range in years from the current date.</p>
@@ -24,4 +24,2 @@ </dd>
 
-**Returns**: <code>boolean</code> - True if number falls within range, false if not.  
-
 | Param | Type | Description |
@@ -35,5 +33,7 @@ | --- | --- | --- |
 
+**Returns**: <code>boolean</code> - True if number falls within range, false if not.  
+
 **Example**  
 ```js
-//returns true
+// returns true
 inRange(0, -1, 1)
@@ -43,3 +43,3 @@ ```
 ```js
-//returns false
+// returns false
 inRange(-1, 0, 1)
@@ -50,16 +50,16 @@ ```
 
-### yrDist(t) ⇒ <code>number</code>
-Returns the difference of a number and the current date in ms, in years from the current date.
+### yrDist(target) ⇒ <code>number</code>
+Returns the difference of a number and the current date in ms as years from the current date.
 
-**Returns**: <code>number</code> - Years until given time in ms.  
-
 | Param | Type | Description |
 | --- | --- | --- |
-| t | <code>number</code> | Number to subtract from. |
+| target | <code>number</code> | Number to subtract from. |
 
 > Source: [index.js](https://github.com/jpcx/ranged-date/blob/master/index.js), [line 30](https://github.com/jpcx/ranged-date/blob/master/index.js#L30)
 
+**Returns**: <code>number</code> - Years until given time in ms.  
+
 **Example**  
 ```js
-//returns years until unix epoch (negative)
+// returns years until unix epoch
 yrDist(0)
@@ -69,23 +69,24 @@ ```
 ```js
-//returns 1
+// returns 1
 yrDist(Date.now() + 31536000000)
 ```
+
 <a name="bound"></a>
 
-### bound(t, l, u) ⇒ <code>number</code> \| <code>boolean</code>
+### bound(target, back, fwd) ⇒ <code>number</code> \| <code>boolean</code>
 Returns the given number only if it falls within a given range in years from the current date.
 
-**Returns**: <code>number</code> \| <code>boolean</code> - Number falls within range.  
-
 | Param | Type | Description |
 | --- | --- | --- |
-| t | <code>number</code> | Number being tested. |
-| l | <code>number</code> | Years before current date as lower bound. |
-| u | <code>number</code> | Years after current date as upper bound. |
+| target | <code>number</code> | Number being tested. |
+| back | <code>number</code> | Years before current date as lower bound. |
+| fwd | <code>number</code> | Years after current date as upper bound. |
 
 > Source: [index.js](https://github.com/jpcx/ranged-date/blob/master/index.js), [line 45](https://github.com/jpcx/ranged-date/blob/master/index.js#L45)
 
+**Returns**: <code>number</code> \| <code>boolean</code> - Number falls within range.  
+
 **Example**  
 ```js
-//returns current time in ms
+// returns current time in ms
 bound(Date.now(), 0.5, 0.5)
@@ -95,39 +96,81 @@ ```
 ```js
-//returns false
+// returns false
 bound(Date.now() * 1000, 0.5, 0.5)
 ```
+
 <a name="check"></a>
 
-### check(t, l, u) ⇒ <code>number</code> \| <code>boolean</code>
+### check(target, back, fwd, exclude) ⇒ <code>number</code> \| <code>boolean</code>
 Returns time in ms if number itself, seconds equivalent, or microseconds equivalent falls within a given range in years from the current date.
 
-**Returns**: <code>number</code> \| <code>boolean</code> - Converted ms or false if outside range.  
-
 | Param | Type | Description |
 | --- | --- | --- |
-| t | <code>number</code> | Number being tested. |
-| l | <code>number</code> | Years before current date as lower bound. |
-| u | <code>number</code> | Years after current date as upper bound. |
+| target | <code>number</code> | Number being tested. |
+| back | <code>number</code> | Years before current date as lower bound. |
+| fwd | <code>number</code> | Years after current date as upper bound. |
+| exclude | <code><a href="https://github.com/jpcx/ranged-date/blob/master/docs/API.md#rangedDate~exclude">rangedDate~exclude</a></code> | Specifies type exclusions, if any. |
 
-> Source: [index.js](https://github.com/jpcx/ranged-date/blob/master/index.js), [line 66](https://github.com/jpcx/ranged-date/blob/master/index.js#L66)
+> Source: [index.js](https://github.com/jpcx/ranged-date/blob/master/index.js), [line 93](https://github.com/jpcx/ranged-date/blob/master/index.js#L93)
 
+**Returns**: <code>number</code> \| <code>boolean</code> - Converted ms or false if outside range.  
+
 **Example**  
 ```js
-//returns current time in ms
-check(Date.now() * 1000, 0.5, 0.5)
+// returns current time in ms
+check(Date.now(), 0.5, 0.5, {})
 ```
 **Example**  
 ```js
-//returns current time in ms
-check(Date.now() / 1000, 0.5, 0.5)
+// returns current time in ms
+check(Date.now() / 1000, 0.5, 0.5, {})
 ```
 **Example**  
 ```js
-//returns false
-check(Date.now() - 100000000000, 0.5, 0.5)
+// returns current time in ms
+check(Date.now() * 1000, 0.5, 0.5, {})
 ```
 **Example**  
 ```js
-//returns current time in ms - 100000000000
-check(Date.now() - 100000000000, 5, 0.5)
+// returns false
+check(Date.now() - 100000000000, 0.5, 0.5, {})
 ```
+**Example**  
+```js
+// returns current time in ms - 100000000000
+check(Date.now() - 100000000000, 5, 0.5, {})
+```
+**Example**  
+```js
+// returns false
+check(Date.now(), 0.5, 0.5, { ms: true })
+```
+**Example**  
+```js
+// returns current time in ms
+check(Date.now(), 0.5, 0.5, { s: true, us: true })
+```
+**Example**  
+```js
+// returns false
+check(Date.now() / 1000, 0.5, 0.5, { s: true })
+```
+**Example**  
+```js
+// returns current time in ms
+check(Date.now() / 1000, 0.5, 0.5, { ms: true, us: true })
+```
+**Example**  
+```js
+// returns false
+check(Date.now() * 1000, 0.5, 0.5, { us: true })
+```
+**Example**  
+```js
+// returns current time in ms
+check(Date.now() * 1000, 0.5, 0.5, { ms: true, s: true })
+```
+**Example**  
+```js
+// returns false
+check(Date.now(), 0.5, 0.5, { ms: true, s: true , us: true })
+```

index.js

@@ -9,114 +9,189 @@ 'use strict'
  * @param {number} u - Upper bound.
+ * @returns {boolean} True if number falls within range, false if not.
  * @example
- * //returns true
+ * // returns true
  * inRange(0, -1, 1)
  * @example
- * //returns false
+ * // returns false
  * inRange(-1, 0, 1)
- * @returns {boolean} True if number falls within range, false if not.
  */
 const inRange = (t, l, u) => t > l && t < u
 /**
- * Returns the difference of a number and the current date in ms, in years from the current date.
+ * Returns the difference of a number and the current date in ms as years from the current date.
  *
- * @param {number} t - Number to subtract from.
+ * @param {number} target - Number to subtract from.
+ * @returns {number} Years until given time in ms.
  * @example
- * //returns years until unix epoch (negative)
+ * // returns years until unix epoch
  * yrDist(0)
  * @example
- * //returns 1
+ * // returns 1
  * yrDist(Date.now() + 31536000000)
- * @returns {number} Years until given time in ms.
  */
-const yrDist = t => (t - Date.now()) / +'31536e6'
+const yrDist = target => (target - Date.now()) / +'31536e6'
 /**
  * Returns the given number only if it falls within a given range in years from the current date.
  *
- * @param {number} t - Number being tested.
- * @param {number} l - Years before current date as lower bound.
- * @param {number} u - Years after current date as upper bound.
+ * @param {number} target - Number being tested.
+ * @param {number} back   - Years before current date as lower bound.
+ * @param {number} fwd    - Years after current date as upper bound.
+ * @returns {(number|boolean)} Number falls within range.
  * @example
- * //returns current time in ms
+ * // returns current time in ms
  * bound(Date.now(), 0.5, 0.5)
  * @example
- * //returns false
+ * // returns false
  * bound(Date.now() * 1000, 0.5, 0.5)
- * @returns {(number|boolean)} Number falls within range.
  */
-const bound = (t, l, u) => inRange(yrDist(t), -l, u) && t
+const bound = (target, back, fwd) => (
+  inRange(yrDist(target), -back, fwd) && target
+)
 /**
  * Returns time in ms if number itself, seconds equivalent, or microseconds equivalent falls within a given range in years from the current date.
  *
- * @param {number} t - Number being tested.
- * @param {number} l - Years before current date as lower bound.
- * @param {number} u - Years after current date as upper bound.
+ * @param   {number} target - Number being tested.
+ * @param   {number} back   - Years before current date as lower bound.
+ * @param   {number} fwd    - Years after current date as upper bound.
+ * @param   {rangedDate~exclude} exclude - Specifies exclusions, if any.
+ * @returns {(number|boolean)} Converted ms or false if outside range.
  * @example
- * //returns current time in ms
- * check(Date.now() * 1000, 0.5, 0.5)
+ * // returns current time in ms
+ * check(Date.now(), 0.5, 0.5, {})
  * @example
- * //returns current time in ms
- * check(Date.now() / 1000, 0.5, 0.5)
+ * // returns current time in ms
+ * check(Date.now() / 1000, 0.5, 0.5, {})
  * @example
- * //returns false
- * check(Date.now() - 100000000000, 0.5, 0.5)
+ * // returns current time in ms
+ * check(Date.now() * 1000, 0.5, 0.5, {})
  * @example
- * //returns current time in ms - 100000000000
- * check(Date.now() - 100000000000, 5, 0.5)
- * @returns {(number|boolean)} Converted ms or false if outside range.
+ * // returns false
+ * check(Date.now() - 100000000000, 0.5, 0.5, {})
+ * @example
+ * // returns current time in ms - 100000000000
+ * check(Date.now() - 100000000000, 5, 0.5, {})
+ * @example
+ * // returns false
+ * check(Date.now(), 0.5, 0.5, { ms: true })
+ * @example
+ * // returns current time in ms
+ * check(Date.now(), 0.5, 0.5, { s: true, us: true })
+ * @example
+ * // returns false
+ * check(Date.now() / 1000, 0.5, 0.5, { s: true })
+ * @example
+ * // returns current time in ms
+ * check(Date.now() / 1000, 0.5, 0.5, { ms: true, us: true })
+ * @example
+ * // returns false
+ * check(Date.now() * 1000, 0.5, 0.5, { us: true })
+ * @example
+ * // returns current time in ms
+ * check(Date.now() * 1000, 0.5, 0.5, { ms: true, s: true })
+ * @example
+ * // returns false
+ * check(Date.now(), 0.5, 0.5, { ms: true, s: true , us: true })
  */
-const check = (t, l, u) => isFinite(t) && (
-  bound(t, l, u) || bound(t * 1000, l, u) || bound(t / 1000, l, u)
+const check = (target, back, fwd, exclude) => isFinite(target) && (
+  (!(exclude.ms === true) && bound(target, back, fwd))
+  || (!(exclude.s === true) && bound(target * 1000, back, fwd))
+  || (!(exclude.us === true) && bound(target / 1000, back, fwd))
 )
+
 /**
- * Converts a given string, number, or Date object to the number of milliseconds since the Unix epoch, provided that it can be recognized as seconds, milliseconds, or microseconds within a specified range in years from the current date.
+ * Exclude milliseconds, seconds, or microseconds as possibilities for type matching.
  *
+ * @typedef  {rangedDate~exclude}
+ * @type     {Object}
+ * @property {boolean} [ms] - Exclude milliseconds.
+ * @property {boolean} [s]  - Exclude seconds.
+ * @property {boolean} [us] - Exclude microseconds.
+ */
+
+/**
+ * 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 time range from the current date.
+ *
  * @module rangedDate
  * @param {(Date|number|string)} data - Data to attempt to recognize as valid date.
- * @param {number} [low=0.5] - Years before current date as lower bound.
- * @param {number} [up=0.5]  - Years after current date as upper bound.
+ * @param   {number}  [back=0.5] - Years before current date as lower bound.
+ * @param   {number}  [fwd=0.5]  - Years after current date as upper bound.
+ * @param   {rangedDate~exclude} [exclude={}] - Specifies type exclusions, if any.
+ * @returns {(number|boolean)} Converted time in ms or false if outside range.
  * @example
- * //returns current time in ms
+ * // returns current time in ms
  * rangedDate(new Date())
  * @example
- * //returns current time in ms
+ * // returns current time in ms
  * rangedDate(String(new Date()))
  * @example
- * //returns current time in ms
+ * // returns current time in ms
  * rangedDate(Date.now())
  * @example
- * //returns current time in ms
+ * // returns current time in ms
  * rangedDate(String(Date.now()))
  * @example
- * //returns current time in ms
+ * // returns current time in ms
+ * rangedDate(Date.now() / 1000)
+ * @example
+ * // returns current time in ms
  * rangedDate(Date.now() * 1000)
  * @example
- * //returns current time in ms
- * rangedDate(Date.now() / 1000)
- * @example
- * //returns false
+ * // returns false
  * rangedDate(Date.now() - 10000, 0.0000001, 0.0000001)
  * @example
- * //returns current time in ms - 10000
+ * // returns current time in ms - 10000
  * rangedDate(Date.now() - 10000, 0.000001, 0.000001)
  * @example
- * //returns false
+ * // returns false
  * rangedDate(10)
  * @example
- * //returns 10
- * const yrSinceEpoch = new Date().getUTCFullYear() - 1970
- * rangedDate(10, yrSinceEpoch + 2)
+ * // returns 10
+ * const yrSince1970 = new Date().getUTCFullYear() - 1970
+ * rangedDate(10, yrSince1970 + 2)
  * @example
- * //returns false
+ * // returns false
  * rangedDate(Date.now() + 100000000000)
  * @example
- * //returns current time in ms + 100000000000
+ * // returns current time in ms + 100000000000
  * rangedDate(Date.now() + 100000000000, 0.1, 5)
- * @returns {(number|boolean)} Converted time in ms or false if outside range.
+ * @example
+ * // returns -946771200000
+ * const yrSince1940 = new Date().getUTCFullYear() - 1940
+ * rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2))
+ * @example
+ * // returns false
+ * rangedDate(Date.now(), 0.5, 0.5, { ms: true })
+ * @example
+ * // returns current time in ms
+ * rangedDate(Date.now(), 0.5, 0.5, { s: true, us: true })
+ * @example
+ * // returns false
+ * rangedDate(Date.now() / 1000, 0.5, 0.5, { s: true })
+ * @example
+ * // returns current time in ms
+ * rangedDate(Date.now() / 1000, 0.5, 0.5, { ms: true, us: true })
+ * @example
+ * // returns false
+ * rangedDate(Date.now() * 1000, 0.5, 0.5, { us: true })
+ * @example
+ * // returns current time in ms
+ * rangedDate(Date.now() * 1000, 0.5, 0.5, { ms: true, s: true })
+ * @example
+ * // returns false
+ * rangedDate(Date.now(), 0.5, 0.5, { ms: true, s: true, us: true })
+ * @example
+ * // returns current time in ms
+ * rangedDate(new Date(), 0.5, 0.5, { ms: true, s: true, us: true })
+ * @example
+ * // returns false
+ * rangedDate(String(new Date()), 0.5, 0.5, { ms: true, s: true, us: true })
  */
-const rangedDate = (data, low = 0.5, up = 0.5) => {
+const rangedDate = (data, back = 0.5, fwd = 0.5, exclude = {}) => {
   if (data instanceof Date) return data.valueOf()
-  if (typeof data == 'number') return check(data, low, up)
-  return check(Date.parse(data), low, up) || check(+data, low, up)
+  if (typeof data == 'number') return check(data, back, fwd, exclude)
+  return (
+    check(Date.parse(data), back, fwd, exclude)
+    || check(+data, back, fwd, exclude)
+  )
 }
 
 module.exports = rangedDate

package.json

 {
   "name": "ranged-date",
-  "version": "1.0.7",
-  "description": "Converts a given string, number, or Date object to the number of milliseconds since the Unix epoch, provided that it can be recognized as seconds, milliseconds, or microseconds within a specified range in years from the current date.",
+  "version": "1.1.0",
+  "description": "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 time range from the current date.",
   "engines": {
@@ -42,2 +42,2 @@ "node": ">=6.0.0"
   }
-}
+}

README.md

@@ -5,8 +5,13 @@ # 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 seconds, milliseconds, or microseconds within a specified range in years from the current 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 time range from the current date.
 
+Milliseconds, seconds, or microseconds may be excluded as possibilities for type matching.
+
 Useful for:
 * Parsing timestampted data from external APIs.
-* Integrating databases with mixed date formats.
+* 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 type exclusions wherever possible, in order to avoid incorrectly classifying and converting values that were not intended to be timestamps.*
+
 ## Getting Started
@@ -41,14 +46,22 @@
 ```js
-const time   = ~~(Date.now() / 1000) // Test unixtime in seconds
-const past   = time - 31536000       // One year prior
-const future = time + 31536000       // One year after
+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(time))               // converted time in ms
-console.log(rangedDate(time * 1000))        // converted time in ms
-console.log(rangedDate(time * 1000 * 1000)) // converted time in ms
-console.log(rangedDate(String(time)))       // 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))                        // 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
 ```
@@ -60,16 +73,26 @@
 
-**Returns**: <code>number</code> \| <code>boolean</code> - Converted ms or false if outside range.  
-
 | Param | Type | Attributes | Default | Description |
 | --- | --- | --- | --- | --- |
-| data | <code>Date &#124; number &#124; string</code> |  |  | Data to attempt to recognize as valid date. |
-| low | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years before current date as lower bound. |
-| up | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years after current date as upper bound. |
+| data | <code>Date</code> \| <code>number</code> \| <code>string</code> |  |  | Data to attempt to recognize as valid date. |
+| back | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years before current date as lower bound. |
+| fwd | <code>number</code> | <code>&#60;optional&#62;</code> | <code>0.5</code> | Years after current date as upper bound. |
+| exclude | <code><a href="#rangedDate~exclude">rangedDate~exclude</a></code> | <code>&#60;optional&#62;</code> | <code>{}</code> | Specifies type exclusions, if any. |
 
-#### Source:
-* [index.js](https://github.com/jpcx/ranged-date/blob/master/index.js)
-#### Documentation:
-* [API](https://github.com/jpcx/ranged-date/blob/master/docs/API.md)
-* [Global](https://github.com/jpcx/ranged-date/blob/master/docs/global.md)
+**Returns**: <code>number</code> \| <code>boolean</code> - Converted ms or false if outside range.  
 
+### <a name="rangedDate~exclude"></a> <code>rangedDate~exclude</code>
+Settings for exclusion of milliseconds, seconds, or microseconds as possibilities for type matching.
+
+**Properties**
+
+| Name | Type | Attributes | Description |
+| --- | --- | --- | --- |
+| ms | <code>boolean</code> | <code>&#60;optional&#62;</code> | Exclude milliseconds. |
+| s | <code>boolean</code> | <code>&#60;optional&#62;</code> | Exclude seconds. |
+| us | <code>boolean</code> | <code>&#60;optional&#62;</code> | Exclude microseconds. |
+
+### See
+* [API Docs](https://github.com/jpcx/ranged-date/blob/master/docs/API.md)
+* [Global Docs](https://github.com/jpcx/ranged-date/blob/master/docs/global.md)
+
 ## Versioning
@@ -76,0 +99,0 @@

test.js

 'use strict'
-process.env.TZ = 'UTC'
 
@@ -11,6 +10,8 @@ const rangedDate = require('./index.js')
 const now = ~~(Date.now() / 1000) * 1000
-const yrSinceEpoch = new Date(now).getUTCFullYear() - 1970
+const yrSince1970 = new Date(now).getUTCFullYear() - 1970
+const yrSince1940 = new Date(now).getUTCFullYear() - 1940
 
-console.log(`Using ${now} as argument for current date in ms.`)
-console.log('Using ' + process.env.TZ + ' as current timezone.')
+console.log(`Using ${now} as 'now' argument for current date in ms.`)
+console.log(`Using ${yrSince1970} as 'yrSince1970' argument for the number of years since 1970.`)
+console.log(`Using ${yrSince1940} as 'yrSince1940' argument for the number of years since 1940.`)
 
@@ -22,69 +23,455 @@ console.log('---')
 tests.push({
-  operate: 'rangedDate(new Date(now))',
   expects: now,
-  results: rangedDate(new Date(now))
+  results: () => rangedDate(new Date(now))
 })
 tests.push({
-  operate: 'rangedDate(String(new Date(now)))',
   expects: now,
-  results: rangedDate(String(new Date(now)))
+  results: () => rangedDate(String(new Date(now)))
 })
 tests.push({
-  operate: 'rangedDate(now)',
   expects: now,
-  results: rangedDate(now)
+  results: () => rangedDate(String(now))
 })
 tests.push({
-  operate: 'rangedDate(String(now))',
   expects: now,
-  results: rangedDate(String(now))
+  results: () => rangedDate(now)
 })
 tests.push({
-  operate: 'rangedDate(now * 1000)',
   expects: now,
-  results: rangedDate(now * 1000)
+  results: () => rangedDate(now / 1000)
 })
 tests.push({
-  operate: 'rangedDate(now / 1000)',
   expects: now,
-  results: rangedDate(now / 1000)
+  results: () => rangedDate(now * 1000)
 })
 tests.push({
-  operate: 'rangedDate(now - 10000, 0.0000001, 0.0000001)',
   expects: false,
-  results: rangedDate(now - 10000, 0.0000001, 0.0000001)
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001)
 })
 tests.push({
-  operate: 'rangedDate(now - 10000, 0.000001, 0.000001)',
   expects: now - 10000,
-  results: rangedDate(now - 10000, 0.000001, 0.000001)
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001)
 })
 tests.push({
-  operate: 'rangedDate(10)',
   expects: false,
-  results: rangedDate(10)
+  results: () => rangedDate(10)
 })
 tests.push({
-  operate: 'rangedDate(10, ' + (yrSinceEpoch + 2) + ')',
   expects: 10,
-  results: rangedDate(10, yrSinceEpoch + 2)
+  results: () => rangedDate(10, yrSince1970 + 2)
 })
 tests.push({
-  operate: 'rangedDate(now + 100000000000)',
   expects: false,
-  results: rangedDate(now + 100000000000)
+  results: () => rangedDate(now + 100000000000)
 })
 tests.push({
-  operate: 'rangedDate(now + 100000000000, 0.1, 5)',
   expects: now + 100000000000,
-  results: rangedDate(now + 100000000000, 0.1, 5)
+  results: () => rangedDate(now + 100000000000, 0.1, 5)
 })
+tests.push({
+  expects: -946771200000,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2))
+})
 
+// test us exclusions
+tests.push({
+  expects: now,
+  results: () => rangedDate(new Date(now), 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(String(new Date(now)), 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(String(now), 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now, 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001, { us: true })
+})
+tests.push({
+  expects: now - 10000,
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001, { us: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: 10,
+  results: () => rangedDate(10, yrSince1970 + 2, 0.5, { us: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.5, 0.5, { us: true })
+})
+tests.push({
+  expects: now + 100000000000,
+  results: () => rangedDate(now + 100000000000, 0.1, 5, { us: true })
+})
+tests.push({
+  expects: -946771200000,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2), { us: true })
+})
+
+// test ms exclusions
+tests.push({
+  expects: now,
+  results: () => rangedDate(new Date(now), 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(new Date(now)), 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(now), 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now, 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: 10000,
+  results: () => rangedDate(10, yrSince1970 + 2, 0.5, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.5, 0.5, { ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.1, 5, { ms: true })
+})
+tests.push({
+  expects: -946771200000,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2), { ms: true })
+})
+
+// test s exclusions
+tests.push({
+  expects: now,
+  results: () => rangedDate(new Date(now), 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(String(new Date(now)), 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(String(now), 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now, 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001, { s: true })
+})
+tests.push({
+  expects: now - 10000,
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001, { s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: 10,
+  results: () => rangedDate(10, yrSince1970 + 2, 0.5, { s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.5, 0.5, { s: true })
+})
+tests.push({
+  expects: now + 100000000000,
+  results: () => rangedDate(now + 100000000000, 0.1, 5, { s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2), { s: true })
+})
+
+// test us and ms exclusions
+tests.push({
+  expects: now,
+  results: () => rangedDate(new Date(now), 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(new Date(now)), 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(now), 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now, 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: 10000,
+  results: () => rangedDate(10, yrSince1970 + 2, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.5, 0.5, { us: true, ms: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.1, 5, { us: true, ms: true })
+})
+tests.push({
+  expects: -946771200000,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2), { us: true, ms: true })
+})
+
+// test us and s exclusions
+tests.push({
+  expects: now,
+  results: () => rangedDate(new Date(now), 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(String(new Date(now)), 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(String(now), 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now, 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001, { us: true, s: true })
+})
+tests.push({
+  expects: now - 10000,
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001, { us: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: 10,
+  results: () => rangedDate(10, yrSince1970 + 2, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.5, 0.5, { us: true, s: true })
+})
+tests.push({
+  expects: now + 100000000000,
+  results: () => rangedDate(now + 100000000000, 0.1, 5, { us: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2), { us: true, s: true })
+})
+
+// test ms and s exclusions
+tests.push({
+  expects: now,
+  results: () => rangedDate(new Date(now), 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(new Date(now)), 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(now), 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now, 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: 0.01,
+  results: () => rangedDate(10, yrSince1970 + 2, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.5, 0.5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.1, 5, { ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2), { ms: true, s: true })
+})
+
+// test us, ms, and s exclusions
+tests.push({
+  expects: now,
+  results: () => rangedDate(new Date(now), 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(new Date(now)), 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(String(now), 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now, 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.0000001, 0.0000001, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now - 10000, 0.000001, 0.000001, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(10, yrSince1970 + 2, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.5, 0.5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(now + 100000000000, 0.1, 5, { us: true, ms: true, s: true })
+})
+tests.push({
+  expects: false,
+  results: () => rangedDate(-946771200, yrSince1940 + 2, -(yrSince1940 - 2), { us: true, ms: true, s: true })
+})
+
+// invalid exclusion tests
+tests.push({
+  expects: now,
+  results: () => rangedDate(now, 0.5, 0.5, { invalid: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now / 1000, 0.5, 0.5, { invalid: true })
+})
+tests.push({
+  expects: now,
+  results: () => rangedDate(now * 1000, 0.5, 0.5, { invalid: true })
+})
+
 const errors = []
 for (let test of tests) {
-  console.log('Operation: ' + test.operate)
+  test.operation = test.results.toString().replace('() => ', '')
+  test.results = test.results()
+  console.log('Operation: ' + test.operation)
   if (test.expects !== test.results) {
     console.log('Expected:  ' + ANSI_RED + test.expects + ANSI_RESET)
     console.log('Result:    ' + ANSI_RED + test.results + ANSI_RESET)
-    errors.push(test.operate)
+    errors.push(test.operation)
   } else {
@@ -105,1 +492,3 @@ console.log('Expected:  ' + test.expects)
 }
+
+console.log(`\n${tests.length - errors.length} / ${tests.length} tests completed successfully.`)

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

35984

increased by95.99%

Lines of code

714

increased by173.56%

Number of lines in readme file

106

increased by27.71%

Number of low supply chain risk alerts

1

decreased by-66.67%

Worsened metrics

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes