mmntjs
Compatibility-first migration bridge away from moment.js

Docs

Query and Comparison

Document comparison semantics such as diff, isBefore, isAfter, and range checks.

Guidance

Comparison Drift Changes Business Logic

A small difference in diff semantics or range checking can change billing windows, expiration logic, or feature gating. Comparison APIs should be treated as logic-affecting rather than display-only.

  • Check both boolean queries and numeric diff output.
  • Use fixtures near midnight, month boundaries, and DST transitions.
  • Confirm whether downstream code expects truncation, rounding, or exact floating output.

Review The Semantics Your Product Actually Depends On

Many teams think of comparison as simple ordering, but production code often depends on more than that: unit-scoped comparisons, inclusive range checks, and moment.js's truncated fractional diff semantics.

If a replacement changes any of those details, the failure mode is usually a branch that still runs but now picks a different path in edge cases.

  • Verify isBefore, isSame, and isAfter both with and without units.
  • Test isBetween assumptions about inclusivity instead of inferring them from naming.
  • Compare diff for month, quarter, and year units separately from day or hour math.

Prefer Fixtures Over Intuition

The safest comparison review uses dates your application already cares about: billing cutoffs, report windows, grace periods, or retention boundaries. Those are more revealing than generic examples because they encode the real business meaning of a date comparison.

  • Keep at least one fixture where both timestamps are valid but close to a unit boundary.
  • Keep one fixture that crosses a timezone or DST-sensitive wall-clock transition if your app uses local time.
  • Add explicit regression tests for any comparison that guards a write, charge, or notification.

Examples

Unit-scoped comparison

import moment from "mmntjs";

const start = moment("2024-01-31T23:30:00");
const cutoff = moment("2024-02-01T00:15:00");

start.isBefore(cutoff); // true
start.isBefore(cutoff, "day"); // also true, but unit-scoped checks should still be tested explicitly

Comparisons with units often hide assumptions about report dates, grace periods, and calendar rollovers.

Month diff semantics

import moment from "mmntjs";

const signedAt = moment("2024-01-31");
const renewedAt = moment("2024-02-29");

renewedAt.diff(signedAt, "months");
renewedAt.diff(signedAt, "months", true);

Check integer and floating diff results separately when product logic truncates or displays month-based intervals.

How To Use This Doc

Use this page as a migration review aid rather than as a generic tutorial. If the behavior in this area is business-critical, compare it directly against your current moment.js usage and record the outcome before expanding rollout.