Elasticsearch Date Math Parser

Common errors

• TypeError: require is not a function

  cause Attempting to import `datemath-parser` using an `import` statement in an ECMAScript Module (ESM) environment.
  fix Change your import statement to use CommonJS `require()`: `const parser = require('datemath-parser');` or `const { parse } = require('datemath-parser');`

• ReferenceError: parser is not defined

  cause The `datemath-parser` module or its `parse` function was not correctly imported or required before being used.
  fix Ensure you have `const parser = require('datemath-parser');` at the top of your file where `parser` is used, or `const { parse } = require('datemath-parser');` if you want to destructure the `parse` function directly.

• Error: Invalid Date Math String

  cause The input string provided to `parser.parse()` does not conform to the expected Elasticsearch date math format.
  fix Review the Elasticsearch date math documentation (e.g., `now+1h`, `2023-01-01||+1M/d`) and correct your date math expression. Ensure correct units (`y`, `M`, `w`, `d`, `h`, `m`, `s`) and operators (`+`, `-`, `/`).

Warnings

• gotcha The `datemath-parser` package has not been updated since 2018, indicating it is no longer actively maintained. This means it may not receive security patches, bug fixes, or updates for compatibility with newer Node.js versions or JavaScript features.
  Fix: For new projects, consider actively maintained alternatives like `@elastic/datemath` (if compatible with your needs) or general-purpose date libraries such as `date-fns` or `Moment.js` which offer similar parsing capabilities and ongoing support.
• breaking This package is exclusively a CommonJS module. Using `import` statements in a pure ECMAScript Module (ESM) environment (e.g., in a Node.js project with `"type": "module"` or browser ESM) will result in a `TypeError: require is not a function` or similar module resolution errors.
  Fix: Ensure your project or file uses CommonJS (`require()`) to import the library, or use a bundler (like Webpack, Rollup, Parcel) that can handle CommonJS modules in an ESM context. If migrating to ESM, consider replacing this library with an ESM-compatible alternative.
• gotcha The library does not ship with TypeScript type definitions. Developers using TypeScript will lack type safety, IntelliSense, and compilation checks when interacting with `datemath-parser`, unless custom declarations are provided.
  Fix: You will need to create a declaration file (`datemath-parser.d.ts`) manually in your project to provide types for the `parse` function, or rely on `@ts-ignore` for type-unsafe usage. Consider alternatives that offer native TypeScript support for a better development experience.

Install

• npm install datemath-parser npm
• yarn add datemath-parser yarn
• pnpm add datemath-parser pnpm

Imports

• parser
  wrong:

  import parser from 'datemath-parser';

  correct:

  const parser = require('datemath-parser');

  This package is CommonJS-only and does not provide native ESM exports. Using `import` will lead to runtime errors in pure ESM environments without a CommonJS wrapper or bundler.
• parse
  wrong:

  import { parse } from 'datemath-parser';

  correct:

  const { parse } = require('datemath-parser');

  The `parse` method is exposed directly on the module's default export object. Destructuring in CommonJS is a common pattern to directly access it.
• parser.parse
  wrong:

  import * as parser from 'datemath-parser';
  const timestamp = parser.parse('now+1h');

  correct:

  const parser = require('datemath-parser');
  const timestamp = parser.parse('now+1h');

  Although `import * as` might work in some transpiled environments, it's not the native or intended way for this CommonJS-only library, which typically exports a single object or function.

Quickstart

This quickstart demonstrates parsing various Elasticsearch-compatible date math expressions, including relative to 'now', with rounding, and using an explicit anchor date. It also shows how to provide a custom 'now' value and control rounding behavior.

const parser = require('datemath-parser');

// Parse a simple expression relative to 'now'
let expression1 = 'now+1h';
let timestamp1 = parser.parse(expression1);
console.log(`'${expression1}' resolves to: ${new Date(timestamp1).toISOString()} (timestamp: ${timestamp1})`);

// Parse an expression with rounding
let expression2 = 'now/d'; // round to the beginning of the day
let timestamp2 = parser.parse(expression2);
console.log(`'${expression2}' resolves to: ${new Date(timestamp2).toISOString()} (timestamp: ${timestamp2})`);

// Parse an expression with an explicit anchor date
let expression3 = '2023-01-01||+1M/d'; // January 1st, 2023 plus one month, rounded to day
let timestamp3 = parser.parse(expression3);
console.log(`'${expression3}' resolves to: ${new Date(timestamp3).toISOString()} (timestamp: ${timestamp3})`);

// Demonstrate parsing with a custom 'now' date and rounding up
const customNow = new Date('2024-03-15T10:30:00Z');
let expression4 = 'now+2d/w'; // 2 days from customNow, rounded up to the end of the week
let timestamp4 = parser.parse(expression4, customNow.getTime(), true); // Pass custom now as milliseconds, roundUp = true
console.log(`'${expression4}' (with custom now ${customNow.toISOString()}) resolves to: ${new Date(timestamp4).toISOString()} (timestamp: ${timestamp4})`);