date-fm
is a JavaScript library for date formatting,supports Browser and node.js.
Install
with npm
:
npm install date-fm --save
with yarn
:
yarn add date-fm
Usage
Using in Commonjs
Format
- The easiest way to use it is:
const { format } = require('date-fm');
console.log(format()); // output is "2018-12-20T16:25:55.036",default to current date
- locale use:
const { format } = require('date-fm');
console.log(format('YYYY/MM/DD HH:II:SS aa', new Date(2018, 11, 20))); // output is "2018/12/20 00:00:00 am"
console.log(format('YY-mm-dd hh:ii:ss WW')); // output is "19-12-25 23:23:59 Wednesday"
// locale config
console.log(
format('YY/mm/dd hh:ii:ss NN WW', new Date(), {
months: [
'Jan',
'Feb',
'Mar',
'Apr',
'May',
'Jun',
'Jul',
'Aug',
'Sep',
'Oct',
'Nov',
'Dec',
],
// Note : the first item in the array is Sunday!
weekdays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
ampm: ['am', 'pm'],
}),
); // output is "19/12/25 23:23:59 Dec Wed"
// you can alse set global locale config for format function
format.setOptions((localeOptions: LocaleOptions));
/**
interface LocaleOptions {
weekdays?: string[];
weekdaysAbbr?: string[];
months?: string[];
monthsAbbr?: string[];
ampm?: [string, string];
isPm?: (hour: number) => boolean;// default is: hour =>return hour > 12
}
*/
Parse
const { parse } = require('date-fm');
// just return a native Date object
let oDate = parse('2019-10-25 12:33:21.064', 'YYYY-MM-DD HH:II:SS.XXX');
// fallback date, default to current date
let fallbackDate = new Date(2019, 9, 25);
parse('12:33:21.064', 'HH:II:SS.XXX', fallbackDate);
Resolve
const { resolve, relative } = require('date-fm');
console.log(resolve('+3days4hours')); // output is "2019-12-20 20:25:55"
console.log(resolve('-3years2weeks', 'YYYY/MM/DD HH:II:SS aa')); // output is "2016/12/20 16:25:55 pm"
// abbreviation of "+3days4hours"
console.log(resolve('+3d4h')); // output is "2019-12-20 20:25:55"
console.log(resolve('today')); // output is "2019-12-13 00:00:00"
// based date
console.log(resolve('+1d', new Date(2019, 11, 22))); //output is "2019-12-23 00:00:00"
let date = resolve('yesterday', false); // return a native Date Object
Relative
console.log(relative(new Date(2017, 8, 24)));// output is "2 years ago"
let timestamp = Date.now();
console.log(relative(timestamp)));// output is "a few seconds ago"
Compare
const {
isBefore,
isAfter,
isLeapYear,
compare,
isBetween,
} = require('date-fm');
console.log(isBefore(new Date(2017, 8, 24))); // output is "true"
console.log(isAfter(new Date(2017, 8, 24), new Date())); // output is "false"
console.log(isLeapYear(2082)); // output is "false"
console.log(compare(new Date(2017, 8, 24), new Date(2018, 8, 24))); // output is "-1"
console.log(
isBetween(1577286966411, new Date(2016, 8, 24), new Date(2018, 8, 24)),
); // output is "false"
Using in ES6 Module
If you want to use date-fm
in other packaging based engineering projects, it's very simple. Just import it and use it
import { format } from 'date-fm';
let sDate = format();
// ...
Using in Browser
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document</title>
</head>
<body>
<script src="./node_modules/date-fm/dist/date-fm.min.js"></script>
<script>
let format = dateFm.format(new Date(2015, 4, 20));
// ...
</script>
</body>
</html>
Api
const {
compare,
format,
parse,
isAfter,
isBefore,
isBetween,
isEqual,
isLeapYear,
relative,
resolve,
} = require('date-fm');
// or
import {
compare,
format,
parse,
isAfter,
isBefore,
isBetween,
isEqual,
isLeapYear,
relative,
resolve,
} from 'date-fm';
and then
format(format?:string, time?:Date|number = new Date(),options?:LocaleOptions):string
-
description : Returns the corresponding format string according to the specified date format;
-
params :
format
:(string) format string,default to ISO8601. see the following table for the supported format symbols.time
:(Date|number) Date object or timestamp to format,default to current time.options
:(LocaleOptions) Optional,locale configuration object;interface LocaleOptions { weekdays?: string[]; // Array of custom weekdays weekdaysAbbr?: string[]; // Array of custom short weekdays months?: string[]; // Array of custom months monthsAbbr?: string[]; // Array of custom short months ampm?: [string, string]; // Array of custom am and pm isPm?: (hour: number) => boolean; // custom check if is PM,(hour:number)=>boolean }
you can alse set global locale config for format function like this:
format.setOptions(localeOptions: LocaleOptions);
The following table is supported format symbols:
symbol | description |
---|---|
YYYY | 4-digit year,eg. '2018' |
YY | 2-digit year,eg. '18' |
MM | Month with leading 0,eg. '07' |
mm | Months without leading 0,eg. '7' |
DD | Date with leading 0,eg. '06' |
dd | Date without leading 0,eg. '6' |
HH | 24 hour system with leading 0,eg. '22' |
hh | 24 hour system without leading 0,eg. '8' |
KK | 12 hour system with leading 0,eg. '06' |
kk | 12 hour system without leading 0,eg. '6' |
II | Minutes with leading 0,eg. '09' |
ii | Minutes without leading 0,eg. '9' |
SS | Seconds with leading 0,eg. '01' |
ss | Seconds without leading 0,eg. '1' |
XXX | Milliseconds |
aa | lower afternoon sign in capital,eg. 'am','pm',can be overridden by options.ampm |
AA | Upper afternoon sign in capital,eg. 'AM','PM',can be overridden by options.ampm |
jj | Days of the current year,eg. 365 or 366 |
NN | Complete spelling of English month names,eg.'December',can be overridden by options.months |
nn | Abbreviation of English month name,eg. 'Dec',can be overridden by options.monthsAbbr |
WW | Complete spelling of English week names ,eg. 'Sunday',can be overridden by options.weekdays |
ww | Abbreviation of English week name, eg. 'Sun' ,can be overridden by options.weekdaysAbbr |
- returns:(string) formated string
parse(target:string,format:string,backupDate:Date = new Date):Date
-
description :parse date string to native date object
-
params :
target
:(string) string of formated date to be parsedformat
:(string) format string, only supports date format divided by/
or-
,such as2018/2/10 12:32:12
or2018-2-10 12:32:12.999
backupDate
:(Date) fallback date when no date part is provided, default to current date -
returns:(Date) parsed date object
isLeapYear(year:number|string|Date):boolean
- description : Decide if it's a leap year
- params :
year
:(number|string|Date)Accept a date object , a number representing the year or a string representing the year can be converted to number - returns:(boolean) Return
true
if leap year,false
otherwise
isBefore(target:Date, comparator?:Date = new Date()):boolean
-
description : Determine whether target precedes comparator
-
params :
target
: (Date) Date to comparecomparator
: (Date) Date to be compared;default to current time -
returns (boolean) If target returns
true
before comparator,false
otherwise
isAfter(target:Date, comparator?:Date = new Date()):boolean
-
description : Determine whether target follows comparator
-
params :
target
: (Date) Date to comparecomparator
: (Date) Date to be compared;default to current time -
returns :(boolean) If target returns
true
after comparator,false
otherwise
isEqual(target:Date, comparator?:Date = new Date()):boolean
- description : Determine if two dates are equal
- params :
target
: (Date) Date to comparecomparator
: (Date) Date to be compared;default to current time - returns :(boolean) Return true if it is the same date, otherwise return false
compare(target:Date, comparator?:Date = new Date()):number
-
description : Compare two dates.
-
params :
target
: (Date) Date to comparecomparator
: (Date) Date to be compared;default to current time -
returns:(boolean) If target is larger than comparator, return 1, equal return 0, otherwise return - 1
resolve(relative:string,baseDate?:Date|number=new Date(), format?:string|false ):Date|string
-
description : Resolve relative date
-
params :
relative
:(string) The relative date mark such as '+3year4month' and the mark consists ofoperator
andtoken
:For example, in '+3year4month', '+' is called operator, 'year' and 'month' are valid tokens, and their combination represents a certain meaning.
supported operators are: +
,-
;
supported tokens are: year(s)
, month(s)
, week(s)
,day(s)
, hour(s)
, minute(s)
, second(s)
,millisecond(s)
, now
,lastweek
,lastyear
, lastmonth
,yesterday
, tomorrow
, today
;
abbreviations:year(s)
->y
, month(s)
->m
, week(s)
->w
,day(s)
->d
, hour(s)
->h
, minute(s)
->i
, second(s)
->s
,millisecond(s)
->MS
,so the following is equivalent:
resolve('+3days4hours');
// or
resolve('+3d4h');
Note: The above token and operator represent a certain meaning. In order to meet the specific application, try not to mix the operator
+
or-
with the following specific token:now
,lastweek
,lastyear
,lastmonth
,yesterday
,tomorrow
,today
,this will cause parsing errors!
baseDate
:(Date|number) base date or base timestamp number.
format
:(string|false) format string ,type: string
|false
.see valid format symbols above.
- returns: (Date|string) If
format
is set tofalse
, it will return a parsed date object, otherwise it will return the format string of the parsed object!
relative(date:Date|number):String
- description : Calculates the specified date relative to the current time and return the corresponding string
- params :
date
: (Date|number) date object or timestamp number - returns (string) relative string
isBetween(target:Date|number, start:Date|number, end:Date|number):Boolean
-
description Judge whether the date is within the specified range
-
params:
target
:(Date|number) Date to judge,can be date object or timestamp numberstart
:(Date|number) Start of date range,can be date object or timestamp numberend
:(Date|number) End of date range,can be date object or timestamp number -
returns:(boolean) Returns
true
if the specified date is in the range,false
otherwise
License
MIT