@design-edito/tools 0.4.22 → 0.5.0

package/agnostic/strings/char-codes/index.js

@@ -5,8 +5,6 @@
  * @returns Base-36 encoded character code.
  */
 export function charCodeToB36(charCode) {
-    if (charCode === null)
-        return '\x00';
     return charCode.toString(36);
 }
 /**
@@ -15,8 +13,6 @@ export function charCodeToB36(charCode) {
  * @returns Unicode character code.
  */
 export function b36CharCodeToCharCode(b36CharCode) {
-    if (b36CharCode === null)
-        return 0;
     const charCode = parseInt(b36CharCode, 36);
     if (!Number.isInteger(charCode))
         return 0;
@@ -91,7 +87,7 @@ export function toB36CharCodes(string) {
 export function fromCharCodes(charCodes) {
     return charCodes
         .map(charFromCharCode)
-        .map(char => char ?? '\x00')
+        .map(char => char)
         .join('');
 }
 /**
@@ -102,7 +98,7 @@ export function fromCharCodes(charCodes) {
 export function fromB36CharCodes(b36CharCodes) {
     return b36CharCodes
         .map(charFromB36CharCode)
-        .map(char => char ?? '\x00')
+        .map(char => char)
         .join('');
 }
 // Serialization

package/agnostic/strings/index.d.ts

@@ -1,6 +1,6 @@
+export * as charCodes from './char-codes/index.js'
 export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
-export * as charCodes from './char-codes/index.js'
 export * as parseTable from './parse-table/index.js'
 export * as replaceAll from './replace-all/index.js'
 export * as splitTrim from './split-trim/index.js'

package/agnostic/strings/index.js

@@ -1,6 +1,6 @@
+export * as charCodes from './char-codes/index.js'
 export * as matches from './matches/index.js'
 export * as normalizeIndent from './normalize-indent/index.js'
-export * as charCodes from './char-codes/index.js'
 export * as parseTable from './parse-table/index.js'
 export * as replaceAll from './replace-all/index.js'
 export * as splitTrim from './split-trim/index.js'

package/agnostic/strings/normalize-indent/index.js

@@ -23,9 +23,9 @@
 export function normalizeIndent(input, indentLevel = 0) {
     const indent = (' ').repeat(indentLevel);
     const lines = input.split('\n');
-    const noIndentLines = lines.map(line => line.replace(/^\s*/igm, ''));
+    const noIndentLines = lines.map(line => line.replace(/^\s*/igmv, ''));
     const pipeReplacedLines = noIndentLines.map(line => {
-        const nbPipeCharsOnLineStart = line.match(/^\|+/igm)?.[0].length ?? 0;
+        const nbPipeCharsOnLineStart = line.match(/^\|+/igmv)?.[0].length ?? 0;
         const noPipeLine = line.slice(nbPipeCharsOnLineStart);
         const replacedPipes = (' ').repeat(nbPipeCharsOnLineStart);
         return replacedPipes + noPipeLine;

package/agnostic/strings/parse-table/index.d.ts

@@ -90,24 +90,24 @@ export type ParseTableOptions<T extends Record<string, string>> = ParseTableLine
  * 2. **Fixed-width columns** (`mode: 'column'` or when `columns` is provided): Slices text at fixed character positions
  *
  * @template T - The type of objects in the resulting array, extending `Record<string, string>`.
- * @param {string} table - The string representation of the table to parse.
- * @param {Partial<ParseTableOptions<T>> & { schema: (obj: unknown) => T | undefined }} options - Configuration options.
- * @param {function(unknown): T | undefined} options.schema - **Required.** Validates and transforms each row. Return `undefined` to skip invalid rows.
- * @param {'line' | 'column'} [options.mode] - Parsing mode. If omitted, inferred from presence of `columns` property.
- * @param {function(string): string[]} [options.splitLines] - How to split input into lines.
- * @param {number} [options.headerPos=0] - Index of the header line.
- * @param {[number, number]} [options.bodyBounds=[1, Infinity]] - Range of lines to parse as body rows `[start, end)`.
+ * @param table - The string representation of the table to parse.
+ * @param options - Configuration options.
+ * @param options.schema - **Required.** Validates and transforms each row. Return `undefined` to skip invalid rows.
+ * @param [options.mode] - Parsing mode. If omitted, inferred from presence of `columns` property.
+ * @param [options.splitLines] - How to split input into lines.
+ * @param [options.headerPos=0] - Index of the header line.
+ * @param [options.bodyBounds=[1, Infinity]] - Range of lines to parse as body rows `[start, end)`.
  *
  * **Delimiter-based mode options:**
- * @param {function(string): string[]} [options.splitHeaderCells] - How to split header line into column names.
- * @param {function(string): string[]} [options.splitBodyCells] - How to split body lines into cell values.
+ * @param [options.splitHeaderCells] - How to split header line into column names.
+ * @param [options.splitBodyCells] - How to split body lines into cell values.
  *
  * **Fixed-width column mode options:**
- * @param {number[]} [options.columns] - Starting positions for each column.
- * @param {function(string): string} [options.headerCellRefine] - Clean/normalize header names.
- * @param {function(string): string} [options.bodyCellRefine] - Clean/normalize cell values.
+ * @param [options.columns] - Starting positions for each column.
+ * @param [options.headerCellRefine] - Clean/normalize header names.
+ * @param [options.bodyCellRefine] - Clean/normalize cell values.
  *
- * @returns {Outcome.Either<T[], string>}
+ * @returns
  * - On success: `{ success: true, payload: T[] }` containing parsed rows.
  * - On failure: `{ success: false, payload: string }` containing error message.
  *

package/agnostic/strings/parse-table/index.js

@@ -1,4 +1,5 @@
 import * as Outcome from '../../misc/outcome/index.js';
+import { isRecord } from '../../objects/is-record/index.js';
 const defaultLineModeOptions = {
     mode: 'line',
     splitLines: i => i.split('\n'),
@@ -6,7 +7,14 @@ const defaultLineModeOptions = {
     splitHeaderCells: h => h.split('\t'),
     bodyBounds: [1, Infinity],
     splitBodyCells: i => i.split('\t'),
-    schema: i => i
+    schema: i => {
+        if (isRecord(i)
+            && Object.values(i).every(v => typeof v === 'string')) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+            return i;
+        }
+        return {};
+    }
 };
 const defaultColumnModeOptions = {
     mode: 'column',
@@ -16,7 +24,14 @@ const defaultColumnModeOptions = {
     columns: [],
     headerCellRefine: h => h,
     bodyCellRefine: v => v,
-    schema: i => i
+    schema: i => {
+        if (isRecord(i)
+            && Object.values(i).every(v => typeof v === 'string')) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+            return i;
+        }
+        return {};
+    }
 };
 /**
  * Parses a tabular string input into an array of typed objects.
@@ -26,24 +41,24 @@ const defaultColumnModeOptions = {
  * 2. **Fixed-width columns** (`mode: 'column'` or when `columns` is provided): Slices text at fixed character positions
  *
  * @template T - The type of objects in the resulting array, extending `Record<string, string>`.
- * @param {string} table - The string representation of the table to parse.
- * @param {Partial<ParseTableOptions<T>> & { schema: (obj: unknown) => T | undefined }} options - Configuration options.
- * @param {function(unknown): T | undefined} options.schema - **Required.** Validates and transforms each row. Return `undefined` to skip invalid rows.
- * @param {'line' | 'column'} [options.mode] - Parsing mode. If omitted, inferred from presence of `columns` property.
- * @param {function(string): string[]} [options.splitLines] - How to split input into lines.
- * @param {number} [options.headerPos=0] - Index of the header line.
- * @param {[number, number]} [options.bodyBounds=[1, Infinity]] - Range of lines to parse as body rows `[start, end)`.
+ * @param table - The string representation of the table to parse.
+ * @param options - Configuration options.
+ * @param options.schema - **Required.** Validates and transforms each row. Return `undefined` to skip invalid rows.
+ * @param [options.mode] - Parsing mode. If omitted, inferred from presence of `columns` property.
+ * @param [options.splitLines] - How to split input into lines.
+ * @param [options.headerPos=0] - Index of the header line.
+ * @param [options.bodyBounds=[1, Infinity]] - Range of lines to parse as body rows `[start, end)`.
  *
  * **Delimiter-based mode options:**
- * @param {function(string): string[]} [options.splitHeaderCells] - How to split header line into column names.
- * @param {function(string): string[]} [options.splitBodyCells] - How to split body lines into cell values.
+ * @param [options.splitHeaderCells] - How to split header line into column names.
+ * @param [options.splitBodyCells] - How to split body lines into cell values.
  *
  * **Fixed-width column mode options:**
- * @param {number[]} [options.columns] - Starting positions for each column.
- * @param {function(string): string} [options.headerCellRefine] - Clean/normalize header names.
- * @param {function(string): string} [options.bodyCellRefine] - Clean/normalize cell values.
+ * @param [options.columns] - Starting positions for each column.
+ * @param [options.headerCellRefine] - Clean/normalize header names.
+ * @param [options.bodyCellRefine] - Clean/normalize cell values.
  *
- * @returns {Outcome.Either<T[], string>}
+ * @returns
  * - On success: `{ success: true, payload: T[] }` containing parsed rows.
  * - On failure: `{ success: false, payload: string }` containing error message.
  *
@@ -102,7 +117,7 @@ export function parseTable(table, _options) {
         bodyLinesSplit.forEach(lineCells => {
             const row = {};
             const cellCount = Math.min(lineCells.length, headers.length);
-            for (let cellPos = 0; cellPos < cellCount; cellPos++) {
+            for (let cellPos = 0; cellPos < cellCount; cellPos = cellPos + 1) {
                 const cellName = headers[cellPos];
                 const cellValue = lineCells[cellPos];
                 if (cellName !== undefined

package/agnostic/strings/replace-all/index.d.ts

@@ -18,4 +18,4 @@
  * replaceAll('abc 123 abc', /abc/g, match => match.toUpperCase())
  * // => 'ABC 123 ABC'
  */
-export declare function replaceAll(input: string, pattern: string | RegExp, replacer: string | ((substring: string, ...args: any[]) => string)): string;
+export declare function replaceAll(input: string, pattern: string | RegExp, replacer: string | ((substring: string, ...args: unknown[]) => string)): string;

package/agnostic/strings/replace-all/index.js

@@ -21,6 +21,7 @@
  * // => 'ABC 123 ABC'
  */
 export function replaceAll(input, pattern, replacer) {
+    // eslint-disable-next-line no-console
     console.warn('[DEPRECATED] Use String.replaceAll instead');
     const found = Array.from(input.match(pattern) ?? []);
     const foundReplaced = typeof replacer === 'string'

package/agnostic/strings/to-alphanum/index.js

@@ -17,8 +17,8 @@
  * // => "Hello-World"
  */
 export function toAlphanum(string, replacer = '') {
-    const replaced = string.replace(/[^a-z0-9]/igm, replacer);
+    const replaced = string.replace(/[^a-z0-9]/igmv, replacer);
     if (replacer.length === 0)
         return replaced;
-    return replaced.replace(new RegExp(`${replacer}+`, 'igm'), replacer);
+    return replaced.replace(new RegExp(`${replacer}+`, 'igmv'), replacer);
 }

package/agnostic/strings/trim/index.js

@@ -8,7 +8,7 @@
  * trimStart("   hello") // => "hello"
  */
 export function trimStart(string) {
-    return string.replace(/^\s*/, '');
+    return string.replace(/^\s*/v, '');
 }
 /**
  * Removes all trailing whitespace characters from a string.
@@ -20,5 +20,5 @@ export function trimStart(string) {
  * trimEnd("hello   ") // => "hello"
  */
 export function trimEnd(string) {
-    return string.replace(/\s*$/, '');
+    return string.replace(/\s*$/v, '');
 }

package/agnostic/time/dates/format-date/index.js

@@ -52,6 +52,7 @@ export function formatDate(date, format, locale = 'en') {
     if (Intl
         .DateTimeFormat
         .supportedLocalesOf(locale).length === 0) {
+        // eslint-disable-next-line no-param-reassign
         locale = 'en';
     }
     const day = date.getDate();
@@ -109,7 +110,8 @@ export function formatDate(date, format, locale = 'en') {
             return '';
         }
     };
-    const regexp = /{{(DD|D|dd|d|MM|M|MMMM|MMM|YYYY|YY|HH|H|hh|h|mm|m|ss|s|A|a|th|ms)}}/g;
+    const regexp = /\{\{(DD|D|dd|d|MM|M|MMMM|MMM|YYYY|YY|HH|H|hh|h|mm|m|ss|s|A|a|th|ms)\}\}/gv;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
     return format.replace(regexp, (match, token) => replacements[token]?.() ?? match);
 }
 // [WIP] this was removed since JavaScript's Date object don't hold timezone data

package/agnostic/time/dates/index.d.ts

@@ -1 +1,2 @@
 export * as formatDate from './format-date/index.js'
+export * as toFrenchRepublican from './to-french-republican/index.js'

package/agnostic/time/dates/index.js

@@ -1 +1,2 @@
 export * as formatDate from './format-date/index.js'
+export * as toFrenchRepublican from './to-french-republican/index.js'

package/agnostic/time/dates/to-french-republican/index.d.ts

@@ -0,0 +1,16 @@
+import type { FrenchRepublicanDate } from './types.js';
+/**
+ * Converts a `Date` to the French Republican calendar.
+ *
+ * @param date - The date to convert.
+ * @returns The equivalent {@link FrenchRepublicanDate}.
+ *
+ * @remarks
+ * The date's local calendar day (`getFullYear` / `getMonth` / `getDate`) is
+ * used as the Gregorian date, so the result reflects the runtime's local
+ * timezone. Build the `Date` in the timezone you care about if this matters.
+ *
+ * @example
+ * toFrenchRepublican(new Date(1799, 10, 9)).formatted // => '18 Brumaire an VIII'
+ */
+export declare function toFrenchRepublican(date: Date): FrenchRepublicanDate;

package/agnostic/time/dates/to-french-republican/index.js

@@ -0,0 +1,82 @@
+// French Republican calendar conversion.
+//
+// Rule: the calendar as it was actually applied (1792–1805). A Republican year
+// begins on the civil day, at the Paris meridian, during which the true autumnal
+// (September) equinox occurs. We simply extrapolate that same rule to any date.
+//
+// Year N starts on the September equinox of Gregorian year (1791 + N):
+//   An I -> equinox of 1792 (22 September 1792).
+//
+// The gap between two consecutive equinox-based new years is 365 or 366 days, so
+// the number of complementary days (5 or 6) falls out automatically — no separate
+// leap-year rule is needed.
+import { gregorianToJdn, republicanYearStartJdn, toRoman, MONTH_NAMES, COMPLEMENTARY_DAY_NAMES, DECADE_DAY_NAMES } from './utils.js';
+/**
+ * Converts a `Date` to the French Republican calendar.
+ *
+ * @param date - The date to convert.
+ * @returns The equivalent {@link FrenchRepublicanDate}.
+ *
+ * @remarks
+ * The date's local calendar day (`getFullYear` / `getMonth` / `getDate`) is
+ * used as the Gregorian date, so the result reflects the runtime's local
+ * timezone. Build the `Date` in the timezone you care about if this matters.
+ *
+ * @example
+ * toFrenchRepublican(new Date(1799, 10, 9)).formatted // => '18 Brumaire an VIII'
+ */
+export function toFrenchRepublican(date) {
+    const year = date.getFullYear();
+    const month = date.getMonth() + 1;
+    const day = date.getDate();
+    const jdn = gregorianToJdn(year, month, day);
+    // The Republican year that contains this date started at the equinox of some
+    // Gregorian year g. Guess g = the date's Gregorian year, then step back if the
+    // date falls before that year's new year (i.e. it's in Jan..Sep).
+    let g = year;
+    let startJdn = republicanYearStartJdn(g);
+    if (jdn < startJdn) {
+        g -= 1;
+        startJdn = republicanYearStartJdn(g);
+    }
+    const republicanYear = g - 1791;
+    const yearRoman = toRoman(republicanYear);
+    const dayOfYear = jdn - startJdn; // 0-based
+    if (dayOfYear >= 360) {
+        // Complementary day (sansculottide): dayOfYear 360..365 -> index 0..5.
+        const complementaryIndex = dayOfYear - 360;
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const dayName = COMPLEMENTARY_DAY_NAMES[complementaryIndex];
+        return {
+            year: republicanYear,
+            yearRoman,
+            isComplementary: true,
+            monthIndex: null,
+            monthName: null,
+            dayOfMonth: complementaryIndex + 1,
+            dayName,
+            decade: null,
+            dayOfYear,
+            formatted: `${dayName}, an ${yearRoman}`
+        };
+    }
+    const monthIndex = Math.floor(dayOfYear / 30); // 0..11
+    const dayOfMonth = (dayOfYear % 30) + 1; // 1..30
+    const decadeDayIndex = (dayOfMonth - 1) % 10; // 0..9
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const monthName = MONTH_NAMES[monthIndex];
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const dayName = DECADE_DAY_NAMES[decadeDayIndex];
+    return {
+        year: republicanYear,
+        yearRoman,
+        isComplementary: false,
+        monthIndex,
+        monthName,
+        dayOfMonth,
+        dayName,
+        decade: Math.floor((dayOfMonth - 1) / 10) + 1, // 1..3
+        dayOfYear,
+        formatted: `${dayOfMonth} ${monthName} an ${yearRoman}`
+    };
+}

package/agnostic/time/dates/to-french-republican/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/agnostic/time/dates/to-french-republican/index.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { toFrenchRepublican } from './index.js';
+import { RepublicanMonth, ComplementaryDay, DecadeDay } from './types.js';
+describe('toFrenchRepublican', () => {
+    it('maps the first day of the calendar (An I) to 1 Vendémiaire', () => {
+        const result = toFrenchRepublican(new Date(1792, 8, 22));
+        expect(result).toMatchObject({
+            year: 1,
+            yearRoman: 'I',
+            isComplementary: false,
+            monthIndex: 0,
+            monthName: RepublicanMonth.VENDEMIAIRE,
+            dayOfMonth: 1,
+            dayName: DecadeDay.PRIMIDI,
+            decade: 1,
+            dayOfYear: 0,
+            formatted: '1 Vendémiaire an I'
+        });
+    });
+    it('converts a well-known historical date (18 Brumaire an VIII)', () => {
+        const result = toFrenchRepublican(new Date(1799, 10, 9));
+        expect(result.formatted).toBe('18 Brumaire an VIII');
+        expect(result.year).toBe(8);
+        expect(result.yearRoman).toBe('VIII');
+        expect(result.monthName).toBe(RepublicanMonth.BRUMAIRE);
+        expect(result.dayOfMonth).toBe(18);
+    });
+    it('converts 9 Thermidor an II (fall of Robespierre)', () => {
+        const result = toFrenchRepublican(new Date(1794, 6, 27));
+        expect(result.formatted).toBe('9 Thermidor an II');
+        expect(result.monthName).toBe(RepublicanMonth.THERMIDOR);
+    });
+    describe('regular days', () => {
+        it('computes the décade (1–3) from the day of the month', () => {
+            // 18 Brumaire -> second décade, Octidi (8th day of the décade).
+            const result = toFrenchRepublican(new Date(1799, 10, 9));
+            expect(result.isComplementary).toBe(false);
+            expect(result.decade).toBe(2);
+            expect(result.dayName).toBe(DecadeDay.OCTIDI);
+        });
+        it('never yields a day of month outside 1–30', () => {
+            const result = toFrenchRepublican(new Date(2026, 7, 25));
+            expect(result.isComplementary).toBe(false);
+            expect(result.dayOfMonth).toBeGreaterThanOrEqual(1);
+            expect(result.dayOfMonth).toBeLessThanOrEqual(30);
+            expect(result.dayOfYear).toBeLessThan(360);
+        });
+    });
+    describe('complementary days (sansculottides)', () => {
+        it('nulls out the month fields on a complementary day', () => {
+            const result = toFrenchRepublican(new Date(1795, 8, 17));
+            expect(result).toMatchObject({
+                isComplementary: true,
+                monthIndex: null,
+                monthName: null,
+                decade: null,
+                dayOfMonth: 1,
+                dayName: ComplementaryDay.VERTU,
+                formatted: 'Jour de la vertu, an III'
+            });
+        });
+        it('exposes the 6th complementary day in a sextile year (An III)', () => {
+            // An III is a leap (sextile) year, so it has a sixth sansculottide.
+            const result = toFrenchRepublican(new Date(1795, 8, 22));
+            expect(result.isComplementary).toBe(true);
+            expect(result.dayOfMonth).toBe(6);
+            expect(result.dayName).toBe(ComplementaryDay.REVOLUTION);
+            expect(result.dayOfYear).toBe(365);
+        });
+        it('rolls over to the next year on the following equinox', () => {
+            const lastDay = toFrenchRepublican(new Date(1795, 8, 22));
+            const newYear = toFrenchRepublican(new Date(1795, 8, 23));
+            expect(lastDay.year).toBe(3);
+            expect(newYear.year).toBe(4);
+            expect(newYear.formatted).toBe('1 Vendémiaire an IV');
+            expect(newYear.dayOfYear).toBe(0);
+        });
+    });
+    describe('year handling', () => {
+        it('steps back a Gregorian year for dates before the new year', () => {
+            // January 1800 still belongs to An VIII (started at the 1799 equinox).
+            const result = toFrenchRepublican(new Date(1800, 0, 1));
+            expect(result.year).toBe(8);
+        });
+        it('extrapolates the rule to modern dates', () => {
+            const result = toFrenchRepublican(new Date(2026, 7, 25));
+            expect(result.year).toBe(234);
+            expect(result.yearRoman).toBe('CCXXXIV');
+            expect(result.formatted).toBe('8 Fructidor an CCXXXIV');
+        });
+    });
+});
+describe('Republican calendar enums', () => {
+    it('lists the twelve months in order', () => {
+        const months = Object.values(RepublicanMonth);
+        expect(months).toHaveLength(12);
+        expect(months[0]).toBe('Vendémiaire');
+        expect(months[11]).toBe('Fructidor');
+    });
+    it('lists the six complementary days in order', () => {
+        const days = Object.values(ComplementaryDay);
+        expect(days).toHaveLength(6);
+        expect(days[0]).toBe('Jour de la vertu');
+        expect(days[5]).toBe('Jour de la Révolution');
+    });
+    it('lists the ten décade days in order', () => {
+        const days = Object.values(DecadeDay);
+        expect(days).toHaveLength(10);
+        expect(days[0]).toBe('Primidi');
+        expect(days[9]).toBe('Décadi');
+    });
+});

package/agnostic/time/dates/to-french-republican/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The twelve 30-day months of the Republican year, in order.
+ */
+export declare enum RepublicanMonth {
+    VENDEMIAIRE = "Vend\u00E9miaire",
+    BRUMAIRE = "Brumaire",
+    FRIMAIRE = "Frimaire",
+    NIVOSE = "Niv\u00F4se",
+    PLUVIOSE = "Pluvi\u00F4se",
+    VENTOSE = "Vent\u00F4se",
+    GERMINAL = "Germinal",
+    FLOREAL = "Flor\u00E9al",
+    PRAIRIAL = "Prairial",
+    MESSIDOR = "Messidor",
+    THERMIDOR = "Thermidor",
+    FRUCTIDOR = "Fructidor"
+}
+/**
+ * The complementary days ("les sansculottides"), in order. The 6th only exists
+ * in sextile years.
+ */
+export declare enum ComplementaryDay {
+    VERTU = "Jour de la vertu",
+    GENIE = "Jour du g\u00E9nie",
+    TRAVAIL = "Jour du travail",
+    OPINION = "Jour de l'opinion",
+    RECOMPENSES = "Jour des r\u00E9compenses",
+    REVOLUTION = "Jour de la R\u00E9volution"
+}
+/**
+ * The ten days of a décade, in order. Each month is three décades.
+ */
+export declare enum DecadeDay {
+    PRIMIDI = "Primidi",
+    DUODI = "Duodi",
+    TRIDI = "Tridi",
+    QUARTIDI = "Quartidi",
+    QUINTIDI = "Quintidi",
+    SEXTIDI = "Sextidi",
+    SEPTIDI = "Septidi",
+    OCTIDI = "Octidi",
+    NONIDI = "Nonidi",
+    DECADI = "D\u00E9cadi"
+}
+/**
+ * Fields shared by every Republican date, whether or not it is a complementary
+ * day.
+ */
+type FrenchRepublicanDateCommon = {
+    /** Republican year (An I = 1), counted from the 1792 equinox. */
+    year: number;
+    /** Republican year in Roman numerals (e.g. `'VIII'`). */
+    yearRoman: string;
+    /** 1-based day number within the month or the complementary period. */
+    dayOfMonth: number;
+    /** 0-based day index within the Republican year (0–365). */
+    dayOfYear: number;
+    /** Human-readable French label (e.g. `'18 Brumaire an VIII'`). */
+    formatted: string;
+};
+/**
+ * A regular day, falling inside one of the twelve 30-day months.
+ */
+export type FrenchRepublicanMonthDate = FrenchRepublicanDateCommon & {
+    isComplementary: false;
+    /** 0-based month index (0–11). */
+    monthIndex: number;
+    monthName: RepublicanMonth;
+    /** Name of the day within its décade. */
+    dayName: DecadeDay;
+    /** 1-based décade within the month (1–3). */
+    decade: number;
+};
+/**
+ * A complementary day ("sansculottide"), falling outside any month at the end
+ * of the year.
+ */
+export type FrenchRepublicanComplementaryDate = FrenchRepublicanDateCommon & {
+    isComplementary: true;
+    monthIndex: null;
+    monthName: null;
+    dayName: ComplementaryDay;
+    decade: null;
+};
+/**
+ * A date expressed in the French Republican calendar. Discriminated on
+ * `isComplementary`: month fields are populated for a regular day and `null`
+ * for a complementary day.
+ */
+export type FrenchRepublicanDate = FrenchRepublicanMonthDate | FrenchRepublicanComplementaryDate;
+export {};

package/agnostic/time/dates/to-french-republican/types.js

@@ -0,0 +1,47 @@
+/**
+ * The twelve 30-day months of the Republican year, in order.
+ */
+export var RepublicanMonth;
+(function (RepublicanMonth) {
+    RepublicanMonth["VENDEMIAIRE"] = "Vend\u00E9miaire";
+    RepublicanMonth["BRUMAIRE"] = "Brumaire";
+    RepublicanMonth["FRIMAIRE"] = "Frimaire";
+    RepublicanMonth["NIVOSE"] = "Niv\u00F4se";
+    RepublicanMonth["PLUVIOSE"] = "Pluvi\u00F4se";
+    RepublicanMonth["VENTOSE"] = "Vent\u00F4se";
+    RepublicanMonth["GERMINAL"] = "Germinal";
+    RepublicanMonth["FLOREAL"] = "Flor\u00E9al";
+    RepublicanMonth["PRAIRIAL"] = "Prairial";
+    RepublicanMonth["MESSIDOR"] = "Messidor";
+    RepublicanMonth["THERMIDOR"] = "Thermidor";
+    RepublicanMonth["FRUCTIDOR"] = "Fructidor";
+})(RepublicanMonth || (RepublicanMonth = {}));
+/**
+ * The complementary days ("les sansculottides"), in order. The 6th only exists
+ * in sextile years.
+ */
+export var ComplementaryDay;
+(function (ComplementaryDay) {
+    ComplementaryDay["VERTU"] = "Jour de la vertu";
+    ComplementaryDay["GENIE"] = "Jour du g\u00E9nie";
+    ComplementaryDay["TRAVAIL"] = "Jour du travail";
+    ComplementaryDay["OPINION"] = "Jour de l'opinion";
+    ComplementaryDay["RECOMPENSES"] = "Jour des r\u00E9compenses";
+    ComplementaryDay["REVOLUTION"] = "Jour de la R\u00E9volution";
+})(ComplementaryDay || (ComplementaryDay = {}));
+/**
+ * The ten days of a décade, in order. Each month is three décades.
+ */
+export var DecadeDay;
+(function (DecadeDay) {
+    DecadeDay["PRIMIDI"] = "Primidi";
+    DecadeDay["DUODI"] = "Duodi";
+    DecadeDay["TRIDI"] = "Tridi";
+    DecadeDay["QUARTIDI"] = "Quartidi";
+    DecadeDay["QUINTIDI"] = "Quintidi";
+    DecadeDay["SEXTIDI"] = "Sextidi";
+    DecadeDay["SEPTIDI"] = "Septidi";
+    DecadeDay["OCTIDI"] = "Octidi";
+    DecadeDay["NONIDI"] = "Nonidi";
+    DecadeDay["DECADI"] = "D\u00E9cadi";
+})(DecadeDay || (DecadeDay = {}));

package/agnostic/time/dates/to-french-republican/utils.d.ts

@@ -0,0 +1,32 @@
+import { RepublicanMonth, ComplementaryDay, DecadeDay } from './types.js';
+/** The twelve month names, indexed by 0-based month index. */
+export declare const MONTH_NAMES: RepublicanMonth[];
+/** The six complementary day names, indexed by 0-based complementary index. */
+export declare const COMPLEMENTARY_DAY_NAMES: ComplementaryDay[];
+/** The ten décade day names, indexed by 0-based day-of-décade index. */
+export declare const DECADE_DAY_NAMES: DecadeDay[];
+/**
+ * Julian Day Number (integer, noon-based) for a proleptic Gregorian date.
+ *
+ * @param year - Gregorian year.
+ * @param month - Month, 1–12.
+ * @param day - Day of month, 1–31.
+ * @returns The Julian Day Number.
+ */
+export declare function gregorianToJdn(year: number, month: number, day: number): number;
+/**
+ * JDN of 1 Vendémiaire — the civil day (Paris meridian) hosting the September
+ * equinox of the given Gregorian year.
+ *
+ * @param gregorianYear - The Gregorian year whose equinox opens the Republican year.
+ * @returns The Julian Day Number of that year's 1 Vendémiaire.
+ */
+export declare function republicanYearStartJdn(gregorianYear: number): number;
+/**
+ * Formats a positive integer as a Roman numeral. Non-positive inputs are
+ * returned as their decimal string.
+ *
+ * @param n - The number to format.
+ * @returns The Roman numeral (e.g. `8` -> `'VIII'`).
+ */
+export declare function toRoman(n: number): string;