date-fm

v3.3.2

Published

2 years ago

Date formatting library,supports browser and nodejs

Downloads

0High
0Medium
0Low

vinsurs

date datefm date-fm date-format format-date date-fn date-utils datetime time

npm

date-fm

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 parsed
format:(string) format string, only supports date format divided by / or -,such as 2018/2/10 12:32:12 or 2018-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 compare
comparator : (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 compare
comparator : (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 compare comparator : (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 compare
comparator : (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 of operator and token:
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 to false, 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 number
start:(Date|number) Start of date range,can be date object or timestamp number
end:(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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

date-fm

Install

Usage

Using in Commonjs

Format

Parse

Resolve

Relative

Compare

Using in ES6 Module

Using in Browser

Api

format(format?:string, time?:Date|number = new Date(),options?:LocaleOptions):string

parse(target:string,format:string,backupDate:Date = new Date):Date

isLeapYear(year:number|string|Date):boolean

isBefore(target:Date, comparator?:Date = new Date()):boolean

isAfter(target:Date, comparator?:Date = new Date()):boolean

isEqual(target:Date, comparator?:Date = new Date()):boolean

compare(target:Date, comparator?:Date = new Date()):number

resolve(relative:string,baseDate?:Date|number=new Date(), format?:string|false ):Date|string

relative(date:Date|number):String

isBetween(target:Date|number, start:Date|number, end:Date|number):Boolean

License