Class: SaneDate

SaneDate

new SaneDate(initialValueOrYearopt, monthopt, nullable, dateopt, nullable, hoursopt, nullable, minutesopt, nullable, secondsopt, nullable, millisecondsopt, nullable)

Creates a new SaneDate, either based on Date.now(), a given initial value or given date parts.

Parameters:
Name Type Attributes Default Description
initialValueOrYear Date | SaneDate | String | Number | Object <optional>
 null

something, that can be used to construct an initial value, this may be a vanilla Date, a SaneDate, a parsable string, a unix timestamp or an object implementing a method toISOString/toIsoString/getISOString/getIsoString; if this is a number, it will be treated as the year, if any other parameter is set as well; if nullish and all other parameters are not set either, the initial value is Date.now()
month Number <optional>
<nullable>
 null

month between 1 and 12, to set in initial value
date Number <optional>
<nullable>
 null

date between 1 and 31, to set in initial value
hours Number <optional>
<nullable>
 null

hours between 0 and 23, to set in initial value
minutes Number <optional>
<nullable>
 null

minutes between 0 and 59, to set in initial value
seconds Number <optional>
<nullable>
 null

seconds between 0 and 59, to set in initial value
milliseconds Number <optional>
<nullable>
 null

milliseconds between 0 and 999, to set in initial value
Source:
Throws:

error if created date is invalid

Members

date

Properties:
Type Description
Number

the date's day of the month in the range of 1 to 31
Source:

hours

Properties:
Type Description
Number

the date's hours in the range of 0 to 23
Source:

milliseconds

Properties:
Type Description
Number

the date's milliseconds in the range of 0 to 999
Source:

minutes

Properties:
Type Description
Number

the date's minutes in the range of 0 to 59
Source:

month

Properties:
Type Description
Number

the date's month in the range of 1 to 12
Source:

seconds

Properties:
Type Description
Number

the date's seconds in the range of 0 to 59
Source:

utc

Properties:
Type Description
Boolean

defines if the date should behave as a UTC date instead of a local date (which is the default)
Source:

year

Properties:
Type Description
Number

the date's year in the range of 0 to 9999
Source:

Methods

backward(part, amountopt, nullable) → {SaneDate}

Moves the date's time backward a certain offset.

Parameters:
Name Type Attributes Default Description
part String | Object

the name of the date part to change, one of "years", "months", "days", "hours", "minutes", "seconds" and "milliseconds" or a dictionary of part/amount pairs ({hours : 1, seconds : 30})
amount Number <optional>
<nullable>
 0

integer defining the negative offset from the current date, negative value is treated as an error
Source:
Throws:

error on invalid part name or negative amount

Returns:
the SaneDate instance
Type
SaneDate
Example
let d = new SaneDate();
d = d.backward('years', 1000);

clone() → {SaneDate}

Returns a copy of the current SaneDate. Might be very handy for creating dates based on another with an offset for example. Keeps UTC mode.

Source:
Returns:
copy of current SaneDate instance
Type
SaneDate
Example
const d = new SaneDate();
const theFuture = d.clone().forward('hours', 8);

compareTo(initialValueOrSaneDate, typeopt, nullable, withMillisecondsopt, nullable) → {Number}

Compares the date to another date in terms of placement on the time axis.

Returns a classical comparator value (-1/0/1), being -1 if the date is earlier than the parameter. Normally checks date and time. Set type to "date" to only check date.

Parameters:
Name Type Attributes Default Description
initialValueOrSaneDate Date | SaneDate | String | Number | Object | SaneDate

anything compatible to the SaneDate constructor or a SaneDate instance
type String <optional>
<nullable>
 'datetime'

either "datetime" or "date", telling the method if time should be considered
withMilliseconds Boolean <optional>
<nullable>
 true

tells the method if milliseconds should be considered if type is "datetime"
Source:
Throws:

error if compare date is not usable

Returns:
-1 if this date is smaller/earlier, 0 if identical, 1 if this date is bigger/later
Type
Number
Example
const d = new SaneDate();
if( d.compareTo('2016-04-07', 'date') === 0 ){
  alert('congratulations, that\'s the same date!');
}

format(definitionopt, nullable, localeopt, typeopt, nullable, optionsopt, nullable) → {String}

Returns a formatted string, describing the current date in a verbose, human-readable, non-technical way.

"definition" may be a format shortcut for "dateStyle" (and "timeStyle" if type is "datetime") or a format string, for a custom format, using these tokens:

YY 18 two-digit year; YYYY 2018 four-digit year; M 1-12 the month, beginning at 1; MM 01-12 the month, 2-digits; D 1-31 the day of the month; DD 01-31 the day of the month, 2-digits; H 0-23 the hour; HH 00-23 the hour, 2-digits; h 1-12 the hour, 12-hour clock; hh 01-12 the hour, 12-hour clock, 2-digits; m 0-59 the minute; mm 00-59 the minute, 2-digits; s 0-59 the second; ss 00-59 the second, 2-digits; SSS 000-999 the millisecond, 3-digits; Z +05:00 the offset from UTC, ±HH:mm; ZZ +0500 the offset from UTC, ±HHmm; A AM PM; a am pm;

Using these, you could create your own ISO string like this: "YYYY-MM-DDTHH:mm:ss.SSSZ"

If you use "full", "long", "medium" or "short" instead, you'll use the DateTimeFormatters built-in, preset format styles for localized dates, based on the given locale(s).

Parameters:
Name Type Attributes Default Description
definition String <optional>
<nullable>
 'long'

either a preset style to quickly define a format style, by setting shortcuts for dateStyle and timeStyle (if type is "datetime"), set to "none" or nullish value to skip quick format; alternatively, define this as a format string to use a custom format
locale String | Array.<String> <optional>
 'en-US'

locale to use for date format and text generation, use array to define fallback; always falls back to en-US if nothing else works
type String <optional>
<nullable>
 'datetime'

set to 'datetime', 'date' or 'time' to define which parts should be rendered
options Object <optional>
<nullable>
 null

options to pass to the Intl.DateTimeFormat constructor, is applied last, so should override anything predefined, if key is reset
Source:
See:
Returns:
- the formatted date/time string
Type
String
Example
const d = new SaneDate();
d.format('de-DE', 'long', 'datetime', {timeZone : 'UTC'})
=> '12. Dezember 2023 um 02:00:00 UTC'
d.format('YYYY-MM-DDTHH:mm:ss.SSSZ')
=> '2023-12-12T02:00:00'

forward(part, amountopt, nullable) → {SaneDate}

Moves the date's time forward a certain offset.

Parameters:
Name Type Attributes Default Description
part String | Object

the name of the date part to change, one of "years", "months", "days", "hours", "minutes", "seconds" and "milliseconds" or a dictionary of part/amount pairs ({hours : 1, seconds : 30})
amount Number <optional>
<nullable>
 0

integer defining the positive offset from the current date, negative value is treated as an error
Source:
Throws:

error on invalid part name or negative amount

Returns:
the SaneDate instance
Type
SaneDate
Example
let d = new SaneDate();
d = d.forward('hours', 8);

getDelta(initialValueOrSaneDate, largestUnitopt, nullable, relativeopt, nullable) → {Object}

Calculates a time delta between the SaneDate and a comparison value.

The result is a plain object with the delta's units up to the defined "largestUnit". All values are integers. The largest unit is days, since above neither months nor years are calculable via a fixed divisor and therefore useless (since month vary from 28 to 31 days and years vary between 365 and 366 days, so both are not a fixed unit).

By default, the order does not matter and only the absolute value is used, but you can change this through the parameter "relative", which by setting this to true, will include "-", if the comparison value is in the future.

Parameters:
Name Type Attributes Default Description
initialValueOrSaneDate Date | SaneDate | String | Number | Object | SaneDate

anything compatible to the SaneDate constructor or a SaneDate instance
largestUnit String <optional>
<nullable>
 'days'

the largest time unit to differentiate in the result
relative Boolean <optional>
<nullable>
 false

if true, returns negative values if first parameter is later than this date (this adheres to the order defined by compareTo)
Source:
Throws:

error on unknown largestUnit or incompatible comparison value

Returns:
time delta object in the format {days : 1, hours : 2, minutes : 3, seconds : 4, milliseconds : 5} (keys depending on largestUnit)
Type
Object
Example
const now = new SaneDate();
const theFuture = now.clone().forward({days : 1, hours : 2, minutes : 3, seconds : 4, milliseconds : 5});
now.getDelta(theFuture)
=> {days : 1, hours : 2, minutes : 3, seconds : 4, milliseconds : 5}
now.getDelta(theFuture, 'hours', true)
=> {hours : -26, minutes : -3, seconds : -4, milliseconds : -5}

getIsoDateString() → {String}

Returns the representation of the date's current date parts (year, month, day) as an ISO-string.

A difference to the vanilla implementation is, that this method respects UTC mode and does not always coerce the date to UTC automatically. So, this will return a local ISO representation if not in UTC mode and the UTC representation in UTC mode.

Source:
Returns:
date ISO-string of the format "2016-04-07"
Type
String
Example
const d = new SaneDate();
thatDatePicker.setValue(d.getIsoDateString());

getIsoString(withSeparatoropt, nullable, withTimezoneopt, nullable) → {String}

Returns the date as an ISO-string.

A difference to the vanilla implementation is, that this method respects UTC mode and does not always coerce the date to UTC automatically. So, this will return a local ISO representation (optionally with timezone information in relation to UTC) if not in UTC mode and the UTC representation in UTC mode.

Parameters:
Name Type Attributes Default Description
withSeparator Boolean <optional>
<nullable>
 true

defines if date and time should be separated with a "T"
withTimezone Boolean <optional>
<nullable>
 true

defines if the ISO string should end with timezone information, such as "Z" or "+02:00"
Source:
Returns:
ISO-string of the format "2016-04-07T13:37:00.222Z"
Type
String
Example
const d = new SaneDate();
thatDateTimePicker.setValue(d.getIsoString());

getIsoTimeString(withTimezoneopt, nullable) → {String}

Returns the representation of the date's current time parts (hours, minutes, seconds, milliseconds) as an ISO-string.

A difference to the vanilla implementation is, that this method respects UTC mode and does not always coerce the date to UTC automatically. So, this will return a local ISO representation (optionally with timezone information in relation to UTC) if not in UTC mode and the UTC representation in UTC mode.

Parameters:
Name Type Attributes Default Description
withTimezone Boolean <optional>
<nullable>
 true

defines if the ISO string should end with timezone information, such as "Z" or "+02:00"
Source:
Returns:
time ISO-string of the format "12:59:00.123Z"
Type
String
Example
const d = new SaneDate();
thatDatePicker.setValue(`2023-12-12T${d.getIsoTimeString()}`);

getTimezone() → {String}

Returns the date's current timezone, like it would occur in an ISO-string ("Z", "+06:00", "-02:30").

If you need the raw offset, use the vanilla date's getTimezoneOffset() method.

Source:
Returns:
- the timezone string
Type
String
Example
const d = new SaneDate()
d.getTimezone()
=> "+09:30"

getVanillaDate() → {Date}

Return the current original JavaScript date object wrapped by SaneDate. Use this to do special things.

Source:
Returns:
the original JavaScript date object
Type
Date
Example
const d = new SaneDate();
const timezoneOffset = d.getVanillaDate().getTimezoneOffset();

getWeekDay(startingWithopt, nullable, asNameopt, nullable) → {Number|String}

Returns the current day of the week as a number between 1 and 7 or an english day name. This method counts days the European way, starting with monday, but you can change this behaviour using the first parameter (if your week starts with sunday or friday for example).

Parameters:
Name Type Attributes Default Description
startingWith String <optional>
<nullable>
 'monday'

set to the english day, which is the first day of the week (monday, tuesday, wednesday, thursday, friday, saturday, sunday)
asName Boolean <optional>
<nullable>
 false

set to true, if you'd like the method to return english day names instead of an index
Source:
Returns:
weekday index between 1 and 7 or english name of the day
Type
Number | String
Example
const d = new SaneDate();
if( d.getWeekDay() == 5 ){
  alert(`Thank god it's ${d.getWeekday(null, true)}!`);
}

isAfter(initialValueOrSaneDate, typeopt, nullable, withMillisecondsopt, nullable) → {Boolean}

Returns if the SaneDate is later on the time axis than the comparison value.

Parameters:
Name Type Attributes Default Description
initialValueOrSaneDate Date | SaneDate | String | Number | Object | SaneDate

anything compatible to the SaneDate constructor or a SaneDate instance
type String <optional>
<nullable>
 'datetime'

either "datetime" or "date", telling the method if time should be considered
withMilliseconds Boolean <optional>
<nullable>
 true

tells the method if milliseconds should be considered if type is "datetime"
Source:
Throws:

error if compare date is not usable

Returns:
true if SaneDate is later than compare value
Type
Boolean
Example
const now = new SaneDate();
const theFuture = now.clone().forward({days : 1, hours : 2, minutes : 3, seconds : 4, milliseconds : 5});
now.isAfter(theFuture)
=> false
theFuture.isAfter(now)
=> true

isBefore(initialValueOrSaneDate, typeopt, nullable, withMillisecondsopt, nullable) → {Boolean}

Returns if the SaneDate is earlier on the time axis than the comparison value.

Parameters:
Name Type Attributes Default Description
initialValueOrSaneDate Date | SaneDate | String | Number | Object | SaneDate

anything compatible to the SaneDate constructor or a SaneDate instance
type String <optional>
<nullable>
 'datetime'

either "datetime" or "date", telling the method if time should be considered
withMilliseconds Boolean <optional>
<nullable>
 true

tells the method if milliseconds should be considered if type is "datetime"
Source:
Throws:

error if compare date is not usable

Returns:
true if SaneDate is earlier than compare value
Type
Boolean
Example
const now = new SaneDate();
const theFuture = now.clone().forward({days : 1, hours : 2, minutes : 3, seconds : 4, milliseconds : 5});
now.isBefore(theFuture)
=> true
theFuture.isBefore(now)
=> false

isSame(initialValueOrSaneDate, typeopt, nullable, withMillisecondsopt, nullable) → {Boolean}

Returns if the SaneDate is at the same time as comparison value.

Parameters:
Name Type Attributes Default Description
initialValueOrSaneDate Date | SaneDate | String | Number | Object | SaneDate

anything compatible to the SaneDate constructor or a SaneDate instance
type String <optional>
<nullable>
 'datetime'

either "datetime" or "date", telling the method if time should be considered
withMilliseconds Boolean <optional>
<nullable>
 true

tells the method if milliseconds should be considered if type is "datetime"
Source:
Throws:

error if compare date is not usable

Returns:
true if SaneDate is at the same time as compare value
Type
Boolean
Example
const now = new SaneDate();
const theFuture = now.clone();
now.isSame(theFuture)
=> true
theFuture.forward({days : 1, hours : 2, minutes : 3, seconds : 4, milliseconds : 5});
theFuture.isSame(now)
=> false

move(part, amountopt, nullable) → {SaneDate}

Move the date a defined offset to the past or the future.

Parameters:
Name Type Attributes Default Description
part String | Object

the name of the date part to change, one of "years", "months", "days", "hours", "minutes", "seconds" and "milliseconds" or a dictionary of part/amount pairs ({hours : -1, seconds : 30})
amount Number <optional>
<nullable>
 0

negative or positive integer defining the offset from the current date
Source:
Throws:

error on invalid part name

Returns:
the SaneDate instance
Type
SaneDate
Example
let d = new SaneDate();
d = d.move('years', 10).move('milliseconds', -1);