datefmt-lite

A lightweight, zero‑dependency string‑to‑string date format converter with pluggable tokens and an extensible architecture.

Convert date strings from one format to another using pure token-to-token logic—no internal Date objects and no assumptions. You control everything via inputs.

🚀 Features

• Fast: Parses and formats via pre‑compiled templates
• Pluggable Tokens: Add or override tokens without touching core code
• Flexible Year Handling: Supply a yearConverter to expand two‑digit years or provide defaults
• Override & Default Tokens: Control individual token output on a per-call basis
• Error Policies: Choose strict (throw) or silent (best‑effort) behavior
• Bracketed Literals: Use [text] to preserve literals in format output
• Zero Dependencies: Core library is pure JS—no external packages

📦 Installation

npm install datefmt-lite
# or
yarn add datefmt-lite

🔰 Quick Usage

import { formatDate } from 'datefmt-lite';

formatDate('20250425', 'yyyyMMdd', 'dd/MM/yyyy');
// → '25/04/2025'

formatDate('250425', 'yyMMdd', 'dd/MM/yyyy', {
  yearConverter: (yy) => 2000 + yy,
});
// → '25/04/2025'

📘 When to Use This Library

• You control both the input and output formats
• You want predictable, fast token-to-token formatting
• You want fallback behavior instead of runtime errors
• You don’t need built-in date math, timezone offsets, or localization (but you can inject that logic via tokens)

✅ Perfect for:

• ETL data pipelines
• Formatted export tools
• Browser-safe string conversion
• Small-bundle apps where you want full control

🔠 Supported Tokens

| Token | Meaning | Example | | ----- | ---------------- | ------- | | yyyy | full year | 2025 | | yy | 2-digit year | 25 | | MMMM | full month | April | | MMM | short month | Apr | | MM | 2-digit month | 04 | | M | 1/2-digit month | 4 | | dd | 2-digit day | 09 | | d | 1/2-digit day | 9 | | HH | 2-digit hour | 03 | | H | 1/2-digit hour | 3 | | mm | 2-digit minute | 07 | | m | 1/2-digit minute | 7 | | ss | 2-digit second | 09 | | s | 1/2-digit second | 9 |

➡️ Token definitions follow Unicode Date Field Symbols.

➡️ See docs/tokens.md for the full list and examples.

🔧 Advanced Options

formatDate(inputDate, inputFormat, outputFormat, {
  errorPolicy: 'silent',
  yearConverter: (yy) => 1900 + yy,
  customTokens: {
    Q: (p) => 'Q' + Math.ceil(p.month / 3),
  },
  overrideTokens: {
    dd: '01',
  },
  defaultTokens: {
    MM: '00',
  },
});

errorPolicy: 'throw' | 'silent'

• 'throw' (default): throws on parse/validation errors
• 'silent': returns raw input if nothing parsed; otherwise returns best-effort output with literal token fallback

➡️ See docs/formatting-behavior.md

yearConverter

• Required when using yy (2-digit year)
• If not provided in silent mode, raw yy is used as-is ('25' → 0025)

customTokens

• Add your own tokens

customTokens: {
  Q: (p) => 'Q' + Math.ceil(p.month / 3)
}

overrideTokens

• Override built-in or derived tokens (e.g., force day = '01')

defaultTokens

• Provide fallback values when parsed data is missing

🧪 Scripts

# Run tests
yarn test

# Build ESM and CJS
yarn build

📚 Full Docs

See /docs for:

• api.md: Main formatDate function signature, options, and behavior
• tokens.md: List of supported tokens (e.g., yyyy, dd, MMM, HH) and how they're matched
• examples.md: Real-world and edge-case formatting examples
• formatting-behavior.md: How overrideTokens, defaultTokens, and errorPolicy interact
• internals.md: Behind-the-scenes architecture and function flow for contributors
• contributing.md: Development setup, code structure, and how to contribute
• design.md: Core philosophy, extensibility plan, and long-term goals

📓 Changelog

See CHANGELOG.md for release history, breaking changes, and upgrade notes.

📄 License

MIT © 2025