datetoken

A small DSL to express relative dates as tokens. Parse now-1d/d into a Date instead of hand-rolling arithmetic with Date.now() - 86400000.

Also available in Python, Go and ... Nim?

Install

npm install datetoken

Requires Node.js >= 20.

Usage

import datetoken from 'datetoken';

datetoken('now');              // current time
datetoken('now-1d/d');         // start of yesterday
datetoken('now-1d@d');         // end of yesterday
datetoken('now-7d');           // 7 days ago
datetoken('now/M');            // start of current month
datetoken('now-1M@M');         // end of last month
datetoken('now-1w/bw');        // start of last business week (Monday)
datetoken('now/Q');            // start of current quarter
datetoken('now-3M+2w-4d/w');   // chains work: 3 months ago + 2 weeks - 4 days, snapped to start of week

Token grammar

now [±<amount><unit>]... [/<snap> | @<snap>]

Everything starts with now. Then zero or more arithmetic operations, optionally ending with a snap to a boundary.

Arithmetic (+ / -)

Unit	Meaning
s	seconds
m	minutes
h	hours
d	days
w	weeks
M	months
Y	years

Amount defaults to 1 when omitted: now-d is the same as now-1d.

Snap to boundary (/ start, @ end)

Snap	Meaning
s m h d	second / minute / hour / day
w	week (Sunday)
bw	business week (Mon-Fri)
M	month
Y	year
Q	current quarter
Q1..Q4	specific quarter
mon..sun	weekday

/ snaps to the start of the period, @ snaps to the end.

Common patterns

Range	Start token	End token
Yesterday	now-1d/d	now-1d@d
Last 7 days	now-7d	now
This month	now/M	now@M
Last month	now-1M/M	now-1M@M
Last business week	now-1w/bw	now-1w@bw
Q1 this year	now/Q1	now@Q1

API

datetoken(token: string, startAt?: Date, clock?: ClockI): Date

• token -- datetoken expression to evaluate.
• startAt -- optional starting date (defaults to new Date()).
• clock -- optional clock interface { getTime(): Date } for testing.

Throws InvalidTokenError on malformed input.

Named exports

import datetoken, { Token } from 'datetoken';

Token is the parsed model. Both ESM and CommonJS are supported.

Development

npm test              # run tests
npm run test:watch    # watch mode
npm run lint          # biome check
npm run build         # tsup build (ESM + CJS + d.ts)

License

MIT