docs: adds jsdocs to timestamp helpers (#619)

Co-authored-by: Filip Skokan <[email protected]>

Resolves #618

docs/classes/jwt_encrypt.EncryptJWT.md

@@ -176,11 +176,29 @@ ___
 
 Set the "exp" (Expiration Time) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -218,11 +236,30 @@ ___
 
 Set the "iat" (Issued At) Claim.
 
+- If no argument is used the current unix timestamp is used as the claim.
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input?` | `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Issued At) Claim value to set on the JWT Claims Set. Default is current timestamp. |
+| `input?` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -293,11 +330,29 @@ ___
 
 Set the "nbf" (Not Before) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 

docs/classes/jwt_produce.ProduceJWT.md

@@ -62,11 +62,29 @@ ___
 
 Set the "exp" (Expiration Time) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -80,11 +98,30 @@ ___
 
 Set the "iat" (Issued At) Claim.
 
+- If no argument is used the current unix timestamp is used as the claim.
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input?` | `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Issued At) Claim value to set on the JWT Claims Set. Default is current timestamp. |
+| `input?` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -134,11 +171,29 @@ ___
 
 Set the "nbf" (Not Before) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 

docs/classes/jwt_sign.SignJWT.md

@@ -162,11 +162,29 @@ ___
 
 Set the "exp" (Expiration Time) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -180,11 +198,30 @@ ___
 
 Set the "iat" (Issued At) Claim.
 
+- If no argument is used the current unix timestamp is used as the claim.
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input?` | `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Issued At) Claim value to set on the JWT Claims Set. Default is current timestamp. |
+| `input?` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -234,11 +271,29 @@ ___
 
 Set the "nbf" (Not Before) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 

docs/classes/jwt_unsecured.UnsecuredJWT.md

@@ -129,11 +129,29 @@ ___
 
 Set the "exp" (Expiration Time) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "exp" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -147,11 +165,30 @@ ___
 
 Set the "iat" (Issued At) Claim.
 
+- If no argument is used the current unix timestamp is used as the claim.
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input?` | `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Issued At) Claim value to set on the JWT Claims Set. Default is current timestamp. |
+| `input?` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "iat" (Expiration Time) Claim value to set on the JWT Claims Set. |
 
 #### Returns
 
@@ -201,11 +238,29 @@ ___
 
 Set the "nbf" (Not Before) Claim.
 
+- If a `number` is passed as an argument it is used as the claim directly.
+- If a `Date` instance is passed as an argument it is converted to unix timestamp and used as the
+  claim.
+- If a `string` is passed as an argument it is resolved to a time span, and then added to the
+  current unix timestamp and used as the claim.
+
+Format used for time span should be a number followed by a unit, such as "5 minutes" or "1
+day".
+
+Valid units are: "sec", "secs", "second", "seconds", "s", "minute", "minutes", "min", "mins",
+"m", "hour", "hours", "hr", "hrs", "h", "day", "days", "d", "week", "weeks", "w", "year",
+"years", "yr", "yrs", and "y". It is not possible to specify months. 365.25 days is used as an
+alias for a year.
+
+If the string is suffixed with "ago", or prefixed with a "-", the resulting time span gets
+subtracted from the current unix timestamp. A "from now" suffix can also be used for
+readability when adding to the current unix timestamp.
+
 #### Parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. When number is passed that is used as a value, when string is passed it is resolved to a time span and added to the current timestamp. |
+| `input` | `string` \| `number` \| [`Date`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date ) | "nbf" (Not Before) Claim value to set on the JWT Claims Set. |
 
 #### Returns