advanced-date-parser

Automatically convert date-like strings and timestamps into native JavaScript Date objects — as an Express middleware or a standalone utility.

Incoming request data is always strings. ?startDate=2020-01-01 reaches your handler as "2020-01-01", not a Date. advanced-date-parser walks an object (or a whole request body/query) and replaces date-like values with real Date instances, so your handlers and validators get typed dates for free.

Table of contents

• Features
• Installation
• Quick start
• Usage
  • As Express middleware
  • As a standalone utility
• Strict mode
• Supported formats
• API
• TypeScript
• Behavior & guarantees
• Contributing
• License

Features

• 🧩 Express middleware — parse req.body, req.query, or both.
• 🔧 Standalone utility — parse any object or value, deeply and recursively.
• 🎯 Smart, opt-out strict mode — only touch keys that look like dates by default.
• 🕒 Multiple formats — ISO 8601 strings, Unix seconds, and millisecond timestamps.
• 📦 Zero runtime dependencies.
• 🟦 First-class TypeScript — ships full type definitions.
• ♻️ Dual ESM / CJS — works with both import and require.

Installation

npm install advanced-date-parser
# or
yarn add advanced-date-parser
# or
pnpm add advanced-date-parser
# or
bun add advanced-date-parser

Requirements: Node.js >= 22.

Quick start

import { parse } from 'advanced-date-parser';

parse({ startDate: '2020-01-01' });
// → { startDate: Date('2020-01-01T00:00:00.000Z') }

parse('1501781876406'); // millisecond timestamp
// → Date('2017-08-03T17:37:56.406Z')

// CommonJS
const { parse } = require('advanced-date-parser');

Usage

As Express middleware

Register a middleware and every matching value on the request is converted to a Date before your route handler runs.

import express from 'express';
import { dateParser, bodyDateParser, queryDateParser } from 'advanced-date-parser';

const app = express();
app.use(express.json());

// Parse both req.body and req.query
app.use(dateParser());

// …or scope it:
app.use(queryDateParser()); // only req.query
app.use(bodyDateParser());  // only req.body

app.get('/events', (req, res) => {
  // GET /events?startDate=2020-01-01
  req.query.startDate instanceof Date; // → true
  res.json({ ok: true });
});

As a standalone utility

parse() works on any object or value — not just requests. It walks nested objects and arrays recursively, mutating the input in place and also returning it.

import { parse } from 'advanced-date-parser';

const filter = {
  term: 'express',
  range: {
    from: '2017-10-01',
    to: '2017-10-31',
  },
  timestamps: ['2017-08-11T00:00:00.000Z', 'Friday, June 24, 2016 10:42 AM'],
};

parse(filter);
// filter.range.from      → Date
// filter.range.to        → Date
// filter.timestamps[0]   → Date
// filter.timestamps[1]   → Date
// filter.term            → 'express' (unchanged)

Strict mode

Every function accepts an optional strict boolean (default: true) that controls which values get parsed.

| Mode | Behavior | | --- | --- | | Strict (default) | Only parse values whose key matches /date/i (e.g. date, startDate, DATE_OF_BIRTH). String values inside arrays are also parsed. | | Non-strict (false) | Parse every value that looks like a date, regardless of its key. |

// Strict: only `startDate` is a date-like key, so only it is converted.
parse({ startDate: '2020-01-01', note: '2020-05-05' });
// → { startDate: Date, note: '2020-05-05' }

// Non-strict: both values are converted.
parse({ startDate: '2020-01-01', note: '2020-05-05' }, false);
// → { startDate: Date, note: Date }

Pass false to any middleware the same way:

app.use(dateParser(false));
app.use(bodyDateParser(false));
app.use(queryDateParser(false));

Supported formats

| Input | Example | Result | | --- | --- | --- | | ISO 8601 / any Date-parseable string | '2017-08-11T00:00:00.000Z', '2020-01-01' | Date | | Unix timestamp (seconds, 10 digits) | '1501781876', '1501781876.406' | Date | | Millisecond timestamp (13 digits) | '1501781876406', 1501781876406 | Date | | Unparseable / non-date string | 'today', 'express', '' | unchanged | | Booleans, null, existing Date | true, null, new Date() | unchanged |

API

All functions are available as named exports and on the default export.

import dateParser, { parse, dateParser as dp, bodyDateParser, queryDateParser } from 'advanced-date-parser';

parse(input, strict?)

Recursively converts date-like values in input. Objects and arrays are traversed and mutated in place; the same reference is returned. A scalar input is returned as a Date if it is date-like, otherwise unchanged.

• input: unknown — object, array, or scalar value.
• strict?: boolean — default true. See Strict mode.
• Returns: the parsed input.

dateParser(strict?)

Returns an Express middleware that parses both req.body and req.query.

bodyDateParser(strict?)

Returns an Express middleware that parses only req.body.

queryDateParser(strict?)

Returns an Express middleware that parses only req.query.

Each middleware has the signature (req, res, next) => void and calls next() when done.

TypeScript

Type definitions are bundled — no @types/* package needed.

import { parse } from 'advanced-date-parser';

const result = parse({ startDate: '2020-01-01' });
//    ^? Record<string, unknown>

Behavior & guarantees

• In-place mutation. parse() modifies the object you pass in and returns the same reference. Clone first if you need immutability.
• Deep traversal. Nested objects and arrays are parsed recursively.
• Circular-reference safe. Direct and indirect cycles are detected and skipped — no infinite recursion.
• Non-destructive on non-dates. Values that don't match a supported format are left exactly as they are.
• Time zones. Date-only strings (e.g. '2020-01-01') follow native new Date() semantics and are interpreted as UTC; strings with a time component follow standard Date parsing rules.

Contributing

Contributions are welcome!

• Planning a feature? Open an issue first to discuss it.
• Include tests with your change.

git clone https://github.com/phaldiya/advanced-date-parser.git
cd advanced-date-parser
bun install

bun run build      # build with tsup
bun run test       # run the test suite
bun run typecheck  # type-check with tsc
bun run lint       # lint & format check with Biome
bun run lint:fix   # apply safe lint/format fixes

Found a bug or have a question? Open one on the issue tracker.

License

MIT © Pradeep K Haldiya