node-dateformat

dateformat is a Node.js port of Steven Levithan’s original dateFormat() function that turns JavaScript Date objects into formatted strings using compact mask patterns like “yyyy-mm-dd” or named presets such as “isoDateTime” and “fullDate”. It supports more than 30 mask tokens covering days, months, years, hours, minutes, seconds, milliseconds, ISO week numbers, ordinal suffixes, and timezone abbreviations, plus a built-in “UTC:”/“GMT:” mask prefix for converting local times to UTC without extra date math.

Beyond the default masks, dateformat lets callers register their own named formats on the exported masks object and localize day names, month names, and AM/PM markers through the i18n object, making it useful for applications that need locale-aware date rendering without pulling in a larger internationalization library. The package ships as a small, zero-dependency ES module, making it a drop-in formatting utility for logging, UI display, or API responses.

What You Get

• A single dateFormat(date, mask, utc, gmt) function covering 30+ format tokens
• 13 built-in named masks (shortDate, isoDateTime, fullDate, expiresHeaderFormat, etc.) for common formats
• UTC/GMT conversion via a UTC:/GMT: mask prefix or boolean argument, with no manual offset math
• A mutable i18n object for localizing day names, month names, and AM/PM strings
• ISO 8601 week-of-year (W/WW) and day-of-week (N) tokens for ISO calendar calculations

Common Use Cases

• Formatting timestamps for log lines and audit trails in a consistent, sortable format
• Rendering human-friendly dates and times in server-rendered UI or email templates
• Producing RFC-1123-style Expires header values for HTTP caching logic
• Localizing date/time strings for non-English-speaking user bases

Under The Hood

Architecture dateformat exports a single default function (src/dateformat.js, ~326 lines) alongside two mutable named exports, masks and i18n, plus a formatTimezone helper. Internally, a flags object literal maps each mask token (dd, mmmm, TT, N, etc.) to a closure that reads the relevant Date component, and a single regex (token) walks the mask string via String.replace, dispatching each match to its flag function. Helper functions (getWeek, getDayOfWeek, getDayName, pad) are pure, side-effect-free computations layered outside the main function. Customization and localization work by mutating the exported masks/i18n objects rather than passing configuration into the function, which keeps the core call simple but means extension state is effectively module-level global state — a workable but slightly informal architecture for a utility this size; changing the token regex or the flags mapping would break every mask at once.

Tech Stack The package is plain JavaScript authored as native ES modules ("type": "module") with zero runtime dependencies. The publish build compiles src/ to lib/ with Babel (@babel/cli, @babel/core, @babel/preset-env) and minifies the output with uglify-js, targeting Node >=12.20. Tests run under Mocha against the built lib/dateformat.js, and a small benchmarking script under benchmark/ compares performance against a previous version of the function. There is no bundler, database, or web framework involved — this is a self-contained formatting utility distributed via npm.

Code Quality Testing is extensive relative to the codebase size: 36 separate test files, largely one per mask token, using Mocha with Node’s built-in assert module (strictEqual/notStrictEqual) rather than a separate assertion library. Error handling is minimal but deliberate — invalid dates raise a TypeError explicitly rather than failing silently. Type information is limited to JSDoc comments on the main function, with no TypeScript source or type-checking step. No linter, formatter, or CI workflow configuration was found in the repository, so quality enforcement relies on manual review and the test suite alone.

API Design The public surface is intentionally small: one function plus two mutable objects (masks, i18n) and one named helper (formatTimezone). Named masks reduce the need to memorize token syntax for common cases, and the argument-skipping behavior (a single string argument with no digits is treated as a mask, not a date) lowers boilerplate for the common “just format now” case. The tradeoff is that localization and custom-mask registration happen by mutating shared exported objects rather than through parameters or an options object, which is a dated pattern compared to newer date libraries but remains easy to pick up from the README’s examples.