datetime-utility

v3.0.3

Published

3 years ago

Simple tools for date manipulation in Javascript

Downloads

0High
0Medium
0Low

emanuelmoraes-dev

date datetime utility tools

datetime-utility

Simple tools for date manipulation in Javascript or TypeScript

Install

npm install datetime-utility --save

PERIODS

MILLISECOND
SECOND
MINUTE
HOUR
DAY
WEEK
MONTH
TWO_MONTHS
QUARTER
SEMESTER
YEAR

isISODate(str : String)

check if a string is an ISO-compliant date

parameters

str: string to check

examples

console.log( isISODate( '2015-02-21T00:52:43.822Z' ) ); // true
console.log( isISODate( '2015-02-21T00:52:43.822' ) );  // false
console.log( isISODate( '2015-02-21T00:52:43Z' ) );     // true
console.log( isISODate( '2015-02-21T00:52:43' ) );      // false
console.log( isISODate( '2015-02-21T00:52Z' ) );        // true
console.log( isISODate( '2015-02-21T00:52' ) );         // false
console.log( isISODate( '2015-02-21T00Z' ) );           // false

toDate(str : String, pattern : String, strict: boolean)

Returns a date based on a string with a given pattern

parameters

str: String to convert to date
pattern: String containing date mask (default value 'yyyy/MM/dd hh:mm:ss.S')
strict: if true, if the amount of characters for a value in "pattern" is not respected, the function returns null. Default value: true

Pattern | Description ------- | ------------------------------------------ dd | day of the month containing two characters d | day of the month MM | month of the year (minimum 1) containing two characters M | month of the year yyyy | full year containing four characters y | full year hh | hours of day with two characters h | hours of day mm | minutes of hour with two characters m | minutes of hour ss | seconds of minute with two characters s | seconds of minute SSS | millisecond of second with tree characters SS | millisecond of second with at least two characters S | millisecond of second

examples

toDate('10/06/2019 21:13', 'dd/MM/yyyy hh:mm') // returns Date
toDate('10/6/2019 21:13', 'd/M/yyyy hh:mm') // returns Date
toDate('10/6/2019 21:13:49.5', 'd/M/yyyy hh:mm:ss.S') // returns Date
toDate('10/6/2019 21:13:49.5', 'd/M/yyyy hh:mm:ss.SS') // returns null, invalid millisecond
toDate('10/6/2019 21:13:49.5', 'd/M/yyyy hh:mm:ss.SS', false) // returns Date
toDate('10/6/2019 21:13:49.59', 'd/M/yyyy hh:mm:ss.SS') // returns Date
toDate('10/6/2019 21:13:49.593', 'd/M/yyyy hh:mm:ss.SS') // returns Date
toDate('10/6/2019 21:13:49.593', 'd/M/yyyy hh:mm:ss.SSS') // returns Date
toDate('10/6/2019 21:13:49.5', 'd/M/yyyy hh:mm:ss.SSS') // returns null, invalid millisecond
toDate('10/6/2019 21:13:49.5', 'd/M/yyyy hh:mm:ss.SSS', false) // returns Date
toDate('10/6/2019 21:13', 'dd/MM/yyyy hh:mm') // returns null, invalid month
toDate('10/6/2019 21:13', 'dd/MM/yyyy hh:mm', false) // returns Date

dateToStr(date : Date|String, pattern : String)

Converts a date to a string in the format described in the pattern

parameters

date: date (or string in ISO format) to convert to string
pattern: date format (default value: 'yyyy/MM/dd')

Pattern | Description ------- | ------------------------------------------ dd | day of the month containing two characters d | day of the month MM | month of the year (minimum 1) containing two characters M | month of the year yyyy | full year containing four characters yy | year containing the last two digits y | full year hh | hours of day with two characters h | hours of day mm | minutes of hour with two characters m | minutes of hour ss | seconds of minute with two characters s | seconds of minute SSS | millisecond of second with tree characters SS | millisecond of second with at least two characters S | millisecond of second

examples

dateToStr(
    toDate('10/06/2019 21:13', 'dd/MM/yyyy hh:mm'),
    'dd/MM/yyyy hh:mm'
) // 10/06/2019 21:13

dateToStr(
    toDate('10/6/2019 21:13', 'd/M/yyyy hh:mm'),
    'd/M/yyyy hh:mm'
) // 10/6/2019 21:13

dateToStr(
     toDate('10/6/2019 21:13', 'd/M/yyyy hh:mm'),
     'd/M/yy hh:mm'
 ) // 10/6/19 21:13

dateToStr(
    toDate('10/6/2019 21:13:26.2', 'd/M/yyyy hh:mm:ss.S'),
    'd/M/yyyy hh:mm:ss.SSS'
) // 10/6/2019 21:13:26.002

dateToStr(
    toDate('10/6/2019 21:13:26.2', 'd/M/yyyy hh:mm:ss.S'),
    'd/M/yyyy hh:mm:ss.SS'
) // 10/6/2019 21:13:26.02

dateToStr(
    toDate('10/6/2019 21:13:26.2', 'd/M/yyyy hh:mm:ss.S'),
    'd/M/yyyy hh:mm:ss.S'
) // 10/6/2019 21:13:26.2

dateToStr(
    toDate('10/6/2019 21:13:26.273', 'd/M/yyyy hh:mm:ss.S'),
    'd/M/yyyy hh:mm:ss.SS'
) // 10/6/2019 21:13:26.27

dateToStr(
    null,
    'dd/MM/yyyy hh:mm'
) // null

getMinPattern(strDate: String, pattern: String)

Returns the minimum pattern (strictly necessary) of a given formatted string representing a date

parameters

strDate: date in string format
pattern: 'strDate' parameter date format

Pattern | Description ------- | ------------------------------------------ dd | day of the month containing two characters d | day of the month MM | month of the year (minimum 1) containing two characters M | month of the year yyyy | full year containing four characters yy | year containing the last two digits y | full year hh | hours of day with two characters h | hours of day mm | minutes of hour with two characters m | minutes of hour ss | seconds of minute with two characters s | seconds of minute SSS | millisecond of second with tree characters SS | millisecond of second with at least two characters S | millisecond of second

examples

let date = toDate('10/06/2019 21:13', 'dd/MM/yyyy hh:mm:ss.S')
let minPattern = getMinPattern('10/06/2019 21:13', 'dd/MM/yyyy hh:mm:ss.S') // dd/MM/yyyy hh:mm
date = plus(date, PERIODS.YEAR, 1)
dateToStr(date, minPattern) // 10/06/2020 21:13

date = toDate('10/06/2019 21:13:00.000', 'dd/MM/yyyy hh:mm')
minPattern = getMinPattern('10/06/2019 21:13:00.000', 'dd/MM/yyyy hh:mm') // dd/MM/yyyy hh:mm
date = plus(date, PERIODS.YEAR, 1)
dateToStr(date, minPattern) // 10/06/2020 21:13

getMinPattern(
    null,
    'dd/MM/yyyy hh:mm:ss.S'
) // null

plus(date: Date|String, period: String|Number, duration : Number)

Adds a value of a time period on a date

parameters

date: date (or string in ISO format) to be increased by a period of time
period: textual or numeric representation (stored in 'PERIODS') of a period of time to be added to the date
duration: unit of time to be added to the date

examples

plus(
    toDate('10/06/2019 21:13', 'dd/MM/yyyy hh:mm'),
    PERIODS.DAY,
    -1
) // date with one day less

plus(
    toDate('10/06/2019 21:13', 'dd/MM/yyyy hh:mm'),
    PERIODS.YEAR,
    1
) // date with one year more

dateEquals(date1 : Date|String, date2 : Date|String, ignore : Number)

Returns true if both dates are equal, ignoring certain lower values

parameters

date1: first date (or string in ISO format) of comparison
date2: second date (or string in ISO format) of comparison
ignore: position from which the lowest values will be ignored (if not informed, nothing is ignored.)

ignore | ignored values ------- | ----------------------------------------------------- default | nothing ignored 7 | nothing ignored 6 | millisecond 5 | millisecond and second 4 | millisecond, second and minute 3 | millisecond, second, minute and hour 2 | millisecond, second, minute, hour and day 1 | millisecond, second, minute, hour, day and month 0 | ignoring everything, that is, the dates are the same

examples

dateEquals(
    toDate('2019/06/10 10:30'),
    toDate('2019/06/10 10:30')
) // true

dateEquals(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    toDate('2019/06/10 02:13')
) // false

// ignoring millisecond, second, minute, hour and day
dateEquals(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    toDate('2019/06/10 02:13'),
    2
) // true

// ignoring millisecond, second, minute and hour
dateEquals(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    toDate('2019/06/10 02:13'),
    3
) // true

// ignoring millisecond, second and minute
dateEquals(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    toDate('2019/06/10 02:13'),
    4
) // false

dateEqualsReverse(date1 : Date|String, date2 : Date|String, ignore : Number)

Returns true if both dates are equal, ignoring certain higher values

parameters

date1: first date (or string in ISO format) of comparison
date2: second date (or string in ISO format) of comparison
ignore: position from which the highest values will be ignored (if not informed, nothing will be ignored).

ignore | ignored values ------- | ----------------------------------------------------- default | nothing ignored 7 | nothing ignored 6 | year 5 | year and month 4 | year, month and day 3 | year, month, day and hour 2 | year, month, day, hour and minute 1 | year, month, day, hour, minute and second 0 | ignoring everything, that is, the dates are the same

examples

dateEqualsReverse(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/10/06 10:40'), 
    toDate('2019/10/06 10:40')
) // true

dateEqualsReverse(
    toDate('2019/10/06 10:40'),
    toDate('2019/12/06 10:40')
) // false

// ignoring year, month and day
dateEqualsReverse(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/10/06 10:40'),
    toDate('2019/12/06 10:40'),
    4
) // true

// ignoring year and month
dateEqualsReverse(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/10/06 10:40'),
    toDate('2019/12/06 10:40'),
    5
) // true

// ignoring year
dateEqualsReverse(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/10/06 10:40'),
    toDate('2019/12/06 10:40'),
    6
) // false

getDateIgnore(date : Date|String, ignore : Number)

Gets date ignoring lower values

parameters

date: date (or string in ISO format) that will have higher values ignored
ignore: position from which the lowest values will be ignored (if not informed, nothing is ignored.)

examples

getDateIgnore(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    3
) // Date only with year, month and day

getDateIgnore(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    4
) // Date only with year, month, day and hour

getDateIgnore(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    7
) // gets exactly the same date

getDateIgnoreReverse(date : Date|String, ignore : Number)

Gets date ignoring high values

parameters

date: date (or string in ISO format) that will have higher values ignored
ignore: position from which the highest values will be ignored (if not informed, nothing will be ignored).

examples

getDateIgnoreReverse(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    4
) // Date only with hour, minute, second and millisecond

getDateIgnoreReverse(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    5
) // Date only with day, hour, minute, second and millisecond

getDateIgnoreReverse(
    // default pattern: 'yyyy/MM/dd hh:mm:ss.S'
    toDate('2019/06/10 10:30'),
    7
) // gets exactly the same date

formatTime(time : Number, ...args : Number)

Gets values from a time

parameters

time: milliseconds obtained by the getTime() function
...args: types of values to be extracted and placed in an array

examples

formatTime(
    200100,
    PERIODS.MINUTE, 
    PERIODS.SECOND
) // [<amount of minutes in 200100 milliseconds>, <number of seconds remaining>]

Attention!

The MONTH, TWO_MONTHS, SEMESTER, QUARTER, and YEAR variables can not be used in formatTime.

dateInApointment(date : Date | String, target : Date|String, period : String|Number, duration : Number, marginErrorPeriod: string | number, marginErrorDuration: number)

Returns true if the date is present within a recurring schedule.

parameters

date: first scheduling date (or string in ISO format)
target: check to see if you are on scheduling.
period: textual or numeric representation (stored in 'PERIODS') of a time period of the schedule
duration: unit to include new periodic dates in schedule
marginErrorPeriod: textual or numeric representation (stored in 'PERIODS') of a programming period to be used to define a "margin of error". (Default value: PERIODS.MILLISECOND)
marginErrorDuration: margin of error value. (Default value: 0)

examples

dateInApointment(
    toDate('2000/01/02'),
    toDate('2025/07/02'),
    PERIODS.SEMESTER,
    1
) // returns true because the date 2025/07/02 is included in a timeline for each semester from the date of 2000/01/02

dateInApointment(
    toDate('2000/01/02'),
    toDate('2025/07/02'),
    PERIODS.SEMESTER,
    2
) // returns false because the date 2025/07/02 is not included in a timeline for each two semester from the date of 2000/01/02

dateInApointment(
    toDate('2000/01/01'),
    toDate('2025/07/03'),
    PERIODS.SEMESTER,
    1,
    PERIODS.DAY,
    1
) // returns false because the date 2025/07/03 is not included in a timeline for each semester from the date 2000/01/01 and the margin of error is only 1 day

dateInApointment(
    toDate('2000/01/01'),
    toDate('2025/07/02'),
    PERIODS.SEMESTER,
    1,
    PERIODS.DAY,
    1
) // returns true because although the date 2025/07/02 is not included in a timeline for each semester from the date 2000/01/01, the margin of error has been set to 1 day

scape(str : String)

Returns string with special regular expression characters with escape

parameters

str: string to have its special RegExp characters with escape

example

scape('ab.*+?^${c}()|d[]\\ef/') // ab\.\*\+\?\^\$\{c\}\(\)\|d\[\]\\ef\/

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

datetime-utility

Install

PERIODS

isISODate(str : String)

parameters

examples

toDate(str : String, pattern : String, strict: boolean)

parameters

examples

dateToStr(date : Date|String, pattern : String)

parameters

examples

getMinPattern(strDate: String, pattern: String)

parameters

examples

plus(date: Date|String, period: String|Number, duration : Number)

parameters

examples

dateEquals(date1 : Date|String, date2 : Date|String, ignore : Number)

parameters

examples

dateEqualsReverse(date1 : Date|String, date2 : Date|String, ignore : Number)

parameters

examples

getDateIgnore(date : Date|String, ignore : Number)

parameters

examples

getDateIgnoreReverse(date : Date|String, ignore : Number)

parameters

examples

formatTime(time : Number, ...args : Number)

parameters

examples

Attention!

dateInApointment(date : Date | String, target : Date|String, period : String|Number, duration : Number, marginErrorPeriod: string | number, marginErrorDuration: number)

parameters

examples

scape(str : String)

parameters

example