fecha

Lightweight date formatting and parsing (~2KB). Meant to replace parsing and formatting functionality of moment.js.

NPM

npm install fecha --save

Yarn

yarn add fecha

Fecha vs Moment

Use it

Formatting

format accepts a Date object (or timestamp) and a string format and returns a formatted string. See below for available format tokens.

Note: format will throw an error when passed invalid parameters

import { format } from 'fecha';

type format = (date: Date, format?: string, i18n?: I18nSettings) => str;

// Custom formats
format(new Date(2015, 10, 20), 'dddd MMMM Do, YYYY'); // 'Friday November 20th, 2015'
format(new Date(1998, 5, 3, 15, 23, 10, 350), 'YYYY-MM-DD hh:mm:ss.SSS A'); // '1998-06-03 03:23:10.350 PM'

// Named masks
format(new Date(2015, 10, 20), 'isoDate'); // '2015-11-20'
format(new Date(2015, 10, 20), 'mediumDate'); // 'Nov 20, 2015'
format(new Date(2015, 10, 20, 3, 2, 1), 'isoDateTime'); // '2015-11-20T03:02:01-05:00'
format(new Date(2015, 2, 10, 5, 30, 20), 'shortTime'); // '05:30'

// Literals
format(new Date(2001, 2, 5, 6, 7, 2, 5), '[on] MM-DD-YYYY [at] HH:mm'); // 'on 03-05-2001 at 06:07'

Parsing

parse accepts a Date string and a string format and returns a Date object. See below for available format tokens.

NOTE: parse will throw an error when passed invalid string format or missing format. You MUST specify a format.

import { parse } from 'fecha';

type parse = (dateStr: string, format: string, i18n?: I18nSettingsOptional) => Date|null;

// Custom formats
parse('February 3rd, 2014', 'MMMM Do, YYYY'); // new Date(2014, 1, 3)
parse('10-12-10 14:11:12', 'YY-MM-DD HH:mm:ss'); // new Date(2010, 11, 10, 14, 11, 12)

// Named masks
parse('5/3/98', 'shortDate'); // new Date(1998, 4, 3)
parse('November 4, 2005', 'longDate'); // new Date(2005, 10, 4)
parse('2015-11-20T03:02:01-05:00', 'isoDateTime'); // new Date(2015, 10, 20, 3, 2, 1)

// Override i18n
parse('4 de octubre de 1983', 'M de MMMM de YYYY', {
  monthNames: [
    'enero',
    'febrero',
    'marzo',
    'abril',
    'mayo',
    'junio',
    'julio',
    'agosto',
    'septiembre',
    'octubre',
    'noviembre',
    'diciembre'
  ]
}); // new Date(1983, 9, 4)

i18n Support

import {setGlobalDateI18n} from 'fecha';

/*
Default I18n Settings
{
  dayNamesShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thur', 'Fri', 'Sat'],
  dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
  monthNamesShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  monthNames: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
  amPm: ['am', 'pm'],
  // D is the day of the month, function returns something like...  3rd or 11th
  DoFn(dayOfMonth) {
    return dayOfMonth + [ 'th', 'st', 'nd', 'rd' ][ dayOfMonth % 10 > 3 ? 0 : (dayOfMonth - dayOfMonth % 10 !== 10) * dayOfMonth % 10 ];
  }
}
*/

setGlobalDateI18n({
  dayNamesShort: ['Sun', 'Mon', 'Tue', 'Wed', 'Thur', 'Fri', 'Sat'],
  dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
  monthNamesShort: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  monthNames: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
  amPm: ['am', 'pm'],
  // D is the day of the month, function returns something like...  3rd or 11th
  DoFn: function (D) {
    return D + [ 'th', 'st', 'nd', 'rd' ][ D % 10 > 3 ? 0 : (D - D % 10 !== 10) * D % 10 ];
  }
});

Custom Named Masks

import { format, setGlobalDateMasks } from 'fecha';
/*
Default global masks
{
  default: 'ddd MMM DD YYYY HH:mm:ss',
  shortDate: 'M/D/YY',
  mediumDate: 'MMM D, YYYY',
  longDate: 'MMMM D, YYYY',
  fullDate: 'dddd, MMMM D, YYYY',
  shortTime: 'HH:mm',
  mediumTime: 'HH:mm:ss',
  longTime: 'HH:mm:ss.SSS'
}
*/

// Create a new mask
setGlobalDateMasks({
  myMask: 'HH:mm:ss YY/MM/DD';
});

// Use it
format(new Date(2014, 5, 6, 14, 10, 45), 'myMask'); // '14:10:45 14/06/06'

Formatting Tokens

4.2.3

• Fixed bug with UTC date on daylights savings time #94

4.2.1

• Fixed missing source map
• Fixed security y18n

4.2.0

Added isoDate and isoDateTime masks

4.1.0

Added Z format/parse and fixed Peru timezone issue

• Added Z format token. See readme for more info. Big thanks to @fer22f for writing the code.
• Fixed a strange issue when Peru changed timezones in 1990. See #78

4.0.0

Major Features and Breaking changes in this version

Improvements

• Valid date parsing - By default fecha will check validity of dates. Previously 2019-55-01 or 2019-01-42 would parse correctly, since Javascript can handle it. Now invalid dates will return null instead
• ES Module and Tree Shaking Support - You can now import fecha parse or format independently `js import {format, parse} from 'fecha';

format(...); parse(...)

#### Breaking changes
- `parseDate` may return `null` when previously returned a `Date`. See improvements above, but invalid dates will return `null` now
- Change to how to set masks and i18n
Previously
```js
import fecha from 'fecha';

fecha.i18n = { ... }
fecha.masks.myMask = 'DD , MM, YYYY' 

New

import {parse, format, setGlobalDateI18n, setGlobalDateMasks} from 'fecha';

setGlobalDateI18n({
    // ...
})
setGlobalDateMasks({
  myMask: 'DD , MM, YYYY'
});

3.0.3

• Fixed bug when using brackets when parsing dates

  3.0.2

• Fixed issue where src files are not included correctly in npm

3.0.0

• Moved to ES modules
• Changed invalid date from false to null

2.3.3

Fixed bug with year 999 not having leading zero

2.3.2

Added typescript definitions to NPM

2.3.0

Added strict version of date parser that returns null on invalid dates (may use strict version in v3)

2.2.0

Fixed a bug when parsing Do format dates

2.0.0

Fecha now throws errors on invalid dates in fecha.format and is stricter about what dates it accepts. Dates must pass Object.prototype.toString.call(dateObj) !== '[object Date]'.