moment-date-math

moment plugin to parse a date math, elasticsearch style

This is a plugin to the Moment.js library to support date-math operations to the moment object. Date maths operations are inputted as a string whose format is based on elasticsearch date-math format (see https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math).

This plugin does not have any dependencies beyond Moment.js itself, and may be used in the browser and in Node.js.

English is not my mother-tongue, so please forgive any mistakes and the incomprehensive readme. Any help with this documentation or source code is appreciated and welcomed

Installation

Node.js

npm install moment-date-math

Bower and other package managers

I haven't tested yet, but it should be similar to npm installation

Browser <script src="path/to/moment-date-math.js"></script>

When using this plugin in the browser, be sure to include moment.js on your page first.

Usage

Module

To use this plugin as a module, use the require function:

require("moment-date-math");

Or replace your existing

var moment = require("moment");

by

var moment = require("moment-date-math");

Example: (run at time zone +07:00)

// the following 2 lines are equivalent:
moment.parseMath('2016-06-12 21:00:00Z||+1y2M3w-4d5h6m7s').format()
moment('2016-06-12 21:00:00Z').parseMath('+1y2M3w-4d5h6m7s').format()
// => moment('2016-06-12 21:00:00Z').add(1, 'y').add(2, 'M').add(3, 'w').subtract(4, 'd').subtract(5, 'h').subtract(6, 'm').subtract(7, 's').format()
// => 2017-08-29T22:53:53+07:00

moment.parseMath('May 6th 2016 10:23:23[Z]+ 1M2d /d - 3h 4m', 'MMM Do Y hh:mm:ss').format()
// => moment('May 6th 2016 10:23:23', 'MMM Do Y hh:mm:ss').utcOffset('Z').add(1, 'M').add(2, 'd').startOf('day').subtract(3, 'h').subtract(4, 'm').format()
// => 2016-06-07T20:56:00Z

// the following 2 lines are equivalent:
moment.parseMath('now[+05:00]-28h/d + 15d/M').format()
moment().calc('[+05:00]-28h/d + 15d/M').format()
// => moment().utcOffset('+05:00').subtract(28, 'h').startOf('day').add(15, 'd').startOf('month')
// => 2016-06-01T00:00:00+05:00

moment.parseMath('2016-06-12 13:00:00 +05:00 [@]- 28 h /d + 15 d /M').format()
// => moment('2016-06-12 13:00:00 +05:00').utcOffset('2016-06-12 20:00:00 +05:00').subtract(28, 'h').startOf('day').add(15, 'd').startOf('month')
// => 2016-06-01T00:00:00+05:00

Usage

(Convention: I use x? for an optional parameter x)

moment.parseMath(fullExpression, format?): create a moment from a dateMath expression and format

moment().calc(mathExpression): apply a dateMath expression to existing moment

where:

fullExpression = < datePart > + < splitter? > + < mathExpression >

• A splitter, if exists, must be '||'
• moment.parseMath(fullExpression, format?) is equivalent to moment(datePart, format?).calc(mathExpression), except for:
  • the [@] operator, see below
  • if < datePart > is 'now' or '' (empty string), in which case it is equivalent to moment().calc(mathExpression)

A mathExpression is a string composed by consecutive dateMath operators, with optional spaces between them. There are 4 type of operators:

• Set utcOffset operator: [@] or [Z] or [+XX:XX] or [-XX:XX], where each 'X' is a digit. It translates to the function call .utcOffset(<whatever between the square brackets>), with the exception of [@]
  • There should be at most 1 utcOffset operator, and if exists, it should be the first operator in the series
  • [@] should only be used in moment.parseMath, where the contains a utc offset suffix, e.g: Z or +XX:XX. It translates to .utcOffset(< datePart >);
• Add operator: has the format of +< number1 >< unit1 >< number2 >< unit2 >...< number_n >< unit_n >. Add operator is space tolerant, i.e there can be whitespaces in between
  • The numbers are non-negative integers. Each unit is a character from the set [yMdhms]
  • It translates to .add(< number1 >, < unit1 >).add(< number2 >, < unit2 >)....add(< number_n >, < unit_n >)
• Subtract operator: similar to add operator but starts with a minus (-< number1 >< unit1 >< number2 >< unit2 >...< number_n >< unit_n >)
• startOf operator: has the format of /[yMdhms]
  • Consecutive startOf operators are not allowed (and it doesn't make sense)
  • It tranlates to .startOf(< fullUnitNotation >) where < fullUnitNotation > is 'year', 'month', 'day', 'hour', 'minute', 'second' respectively

I know, I'm not good at writing documents, nor at English. Help is appreciated. Hope you get the basic idea what this plugin is for, at least from the examples.