historical-date-sort

Sort free-form historical date strings across six calendar systems by reducing them to a single IEEE 754 float (astronomical year). Zero runtime dependencies, dual ESM/CJS output, full TypeScript types.

Install

npm install historical-date-sort

Quick start

import { parseHistoricalDate, compareHistoricalDates } from "historical-date-sort";

const records = [
  { id: "A", date: "ca. 450 BCE" },
  { id: "B", date: "AH 150" },       // Islamic Hijri → ~767 CE
  { id: "C", date: "AM 5500" },      // Hebrew Anno Mundi → ~1740 CE
  { id: "D", date: "Meiji 34" },     // Japanese era → 1901 CE
  { id: "E", date: "AUC 754" },      // Roman ab urbe condita → 1 CE
  { id: "F", date: "1921" },
  { id: "G", date: "Unknown date" }, // unparseable → sorts last
];

records.sort((a, b) => compareHistoricalDates(a.date, b.date));
// Result: A (-450), E (1 CE), B (767 CE), C (~1740 CE), D (1901), F (1921), G (last)

API

parseHistoricalDate(input, options?): number

Parses a historical date string and returns an astronomical-year sort key.

• Returns a finite number for successfully parsed dates (negative = BCE/Before Common Era, 0 = year 0, positive = CE).
• Returns Infinity for recognized-but-unresolvable inputs (e.g. regnal dates without a resolver, garbled era markers) — these sort last.
• Returns Infinity for unrecognized inputs.

parseHistoricalDate("Meiji 34")           // 1901
parseHistoricalDate("AH 150")             // ≈767.12
parseHistoricalDate("AM 5786")            // 2025
parseHistoricalDate("AUC 754")            // 1
parseHistoricalDate("ca. 450 BCE")        // -450
parseHistoricalDate("49-44 BC")           // -49
parseHistoricalDate("after 217 BC")       // -216.5  (sorts between 217 BC and 216 BC)
parseHistoricalDate("Unknown date")        // Infinity

Options:

interface ParseOptions {
  calendars?: CalendarSystem[];      // restrict which plugins run; default: all six
  regnalResolver?: RegnalResolver;   // required for regnal dates
  regnalRuler?: string;              // fallback ruler for bare "regnal year N" inputs
}

Throws if calendars contains an unknown calendar name (catches typos).

compareHistoricalDates(a, b): number

Drop-in comparator for Array.prototype.sort. Handles null inputs and Infinity results safely — two unparseable values compare as equal (0), not NaN.

records.sort((a, b) => compareHistoricalDates(a.date, b.date));

null and unparseable strings always sort after all valid dates.

formatHistoricalDate(key, options?): string

Formats an astronomical-year sort key back to a human-readable string.

formatHistoricalDate(-450)                           // "450 BCE"
formatHistoricalDate(767.12, { calendar: "islamic" }) // "AH 150"
formatHistoricalDate(2025, { calendar: "hebrew" })    // "AM 5786"

Regnal dates

Regnal year parsing requires a caller-supplied resolver. Without one, regnal patterns return Infinity (sorts last) rather than falling through to Gregorian — this prevents "Year 12 of Henry III" from silently sorting to 12 CE instead of ~1227 CE.

import type { RegnalResolver } from "historical-date-sort";

const resolver: RegnalResolver = {
  resolve(ruler: string, regnalYear: number): number | null {
    const accession: Record<string, number> = {
      "Henry III": 1216,
      "Edward I":  1272,
    };
    const start = accession[ruler];
    return start !== undefined ? start + regnalYear - 1 : null;
  },
};

parseHistoricalDate("Year 12 of Henry III", { regnalResolver: resolver }); // 1227
parseHistoricalDate("3rd year of Edward I", { regnalResolver: resolver }); // 1274
parseHistoricalDate("Year 12 of Henry III");                                // Infinity

Return null from resolve() for unknown rulers — the plugin then returns Infinity.

Supported formats

Gregorian

| Input | Sort key | Notes | |---|---|---| | "1921" | 1921 | Plain integer | | "ca. 450 BCE" | -450 | ca., circa, c., ~, ≈ all accepted | | "450 BC" | -450 | BC and BCE treated identically | | "450 AD" | 450 | AD and CE treated identically | | "49-44 BC" | -49 | Range → start year | | "after 217 BC" | -216.5 | Sorts between 217 BC and 216 BC | | "before 217 BC" | -217.5 | Sorts between 218 BC and 217 BC | | "1 BC" | -1 | Standard convention | | "0 BC" / "0 AD" | 0 | Year 0 (astronomical) |

Structural guard: Gregorian is the catch-all fallback and requires the input to contain an era marker (BC, BCE, AD, CE), a circa indicator, a plain number, a plain range, or a 4-digit year. Inputs like "page 5", "Hour 5", or "10 AM Tuesday" return Infinity rather than silently sorting to 5 CE or 10 CE.

Islamic (Hijri)

| Input | Sort key | |---|---| | "AH 150" | ≈767.12 | | "A.H. 150" | ≈767.12 | | "150 AH" | ≈767.12 | | "Hijri 150" | ≈767.12 | | "Hegira 150" | ≈767.12 | | "150 H" | ≈767.12 |

Conversion: CE = AH × 0.9702 + 621.57

Hebrew (Anno Mundi)

| Input | Sort key | Notes | |---|---|---| | "AM 5786" | 2025 | | | "5786 AM" | 2025 | | | "A.M. 5786" | 2025 | | | "Anno Mundi 5786" | 2025 | Case-insensitive | | "[5786]" | 2025 | Bracketed form | | "AM5786" | 2025 | No space |

Conversion: astro = AM − 3761 (AM 1 → −3760; AM 3761 → 0; AM 5786 → 2025)

Bracketed form caveat: [N] is only recognized as a Hebrew date when the value is ≥ 4000. Values below 4000 (e.g. [1923]) are rejected to avoid false positives with bracketed Gregorian years or editorial notations.

Roman (Ab Urbe Condita)

| Input | Sort key | Notes | |---|---|---| | "AUC 754" | 1 | Arabic year | | "AUC DCCLIV" | 1 | Roman numeral year | | "A.U.C. 753" | 0 | AUC 753 = 1 BCE (year 0) |

Conversion: astro = AUC − 753

Roman numeral parsing uses round-trip validation (re-encodes result back to canonical form; rejects non-standard notations like IC, XM, IL). Bare Roman numerals without the AUC marker are not recognized.

Japanese (Gengō)

| Input | Sort key | Notes | |---|---|---| | "Meiji 34" | 1901 | | | "Showa 15" | 1940 | | | "Shōwa 15" | 1940 | Macron variants normalized | | "Reiwa 6" | 2024 | | | "Tempo 5" | 1834 | Romanization variants accepted |

Conversion: CE = era_start + regnal_year − 1

The era table covers Meio (1492) through Reiwa (2019) — approximately 50 entries covering the Edo period onward. Pre-1492 eras are not included in v1.

Regnal

| Input | Sort key (with resolver) | |---|---| | "Year 12 of Henry III" | 1227 | | "3rd year of Edward I" | 1274 | | "Henry VIII yr. 12" | 1520 | | "Henry VIII year 12" | 1520 | | "Regnal Year 12 of Henry III" | 1227 | | "regnal year 12" (with regnalRuler) | depends on resolver |

Without a resolver: returns Infinity. See Regnal dates above.

Qualitative modifiers (all calendars)

| Modifier | Effect | Example | |---|---|---| | after X | +0.5 to sort key | "after AH 150" → between AH 150 and AH 151 | | before X | −0.5 to sort key | "before AH 150" → between AH 149 and AH 150 | | ca. X, circa X, c. X, ~X, ≈X | no offset | treated as the date itself |

Tree-shaking

Each calendar system has its own subpath export. Bundlers that support exports will tree-shake unused plugins automatically:

import { parseGregorian } from "historical-date-sort/gregorian";
import { parseIslamic, ahToCE } from "historical-date-sort/islamic";
import { parseHebrew, amToCE } from "historical-date-sort/hebrew";
import { parseRoman, aucToCE, parseRomanNumeral } from "historical-date-sort/roman";
import { parseJapanese, gengoToCE, GENGO } from "historical-date-sort/japanese";
import { parseRegnal } from "historical-date-sort/regnal";
import type { RegnalResolver } from "historical-date-sort/regnal";

Plugin priority

When using the main parseHistoricalDate entry point, plugins run in this order — first match wins:

1. Islamic — AH, A.H., Hijri, Hegira, digit+H
2. Hebrew — AM, A.M., Anno Mundi, bracketed [N≥4000]
3. Japanese — era name token (Meiji, Showa, Reiwa, …)
4. Roman — requires explicit AUC / A.U.C. marker
5. Regnal — Year N of X, X yr. N, Nth year of X, etc.
6. Gregorian — catch-all fallback with structural guard

Gregorian runs last deliberately: its digit-extraction regex would otherwise consume strings like "Meiji 34" (extracting 34) or "AH 150" (extracting 150) instead of delegating to the correct plugin.

Requirements

• Node.js ≥ 18
• Zero runtime dependencies

License

MIT