@fhss-web-team/fuzzy-dates 1.2.2 → 2.0.0

package/dist/fuzzyDate/fuzzyDate.js

@@ -1,246 +0,0 @@
-import { parse } from './parse/index';
-import { normalize } from './normalize/normalize';
-import { collate } from './collate/collate';
-import { toGedcomX } from './gedcomX/toGedcomX';
-import { DATE_NEG_INFINITY, DATE_POS_INFINITY } from './helpers/constants';
-import { ok, err } from './helpers/result';
-import { fuzzyDateJsonSchema } from './helpers/schemas';
-/**
- * Represents an immutable, parsed fuzzy date suitable for genealogy and
- * historical data contexts.
- *
- * A `FuzzyDate` encapsulates a human-entered date expression
- * (e.g. `"before 1900"`, `"between 1 Jan 1900 and 31 Dec 1901"`,
- * `"March 1890"`) and exposes multiple *derived representations* optimized
- * for different use cases:
- *
- * - A canonical JSON model for storage and transport
- * - Query bounds for database filtering
- * - A collation key for stable chronological ordering
- * - A normalized, human-readable string form
- * - A GEDCOM X formal date representation
- *
- * ---
- *
- * ### Design principles
- *
- * - **Immutable**: Instances cannot be mutated after construction.
- * - **Explicit construction**: Instances must be created via `parse()` or
- *   `fromJSON()`. Direct construction via `new` is intentionally disallowed.
- * - **Derived projections**: Query bounds, collation keys, and serializations
- *   are all derived from a single internal model to guarantee consistency.
- * - **UTC semantics**: All date calculations and comparisons are performed
- *   using UTC to avoid timezone-related ambiguity.
- *
- * ---
- *
- * ### Intended usage
- *
- * - Use `parse()` for untrusted, human-entered input.
- * - Use `fromJSON()` when hydrating from a trusted serialized model
- *   (e.g. database JSON).
- * - Store the JSON model as the canonical representation.
- * - Store `lowerBound`, `upperBound`, and `collationKey` separately for
- *   efficient querying and ordering.
- */
-export class FuzzyDate {
-    /**
-     * Canonical internal model representing the parsed fuzzy date.
-     *
-     * This model is considered the single source of truth; all other
-     * representations are derived from it.
-     */
-    _model;
-    /**
-     * Private constructor to enforce factory-based creation.
-     *
-     * Consumers must use {@link FuzzyDate.parse} or {@link FuzzyDate.fromJSON}.
-     */
-    constructor(model) {
-        this._model = model;
-    }
-    /**
-     * GEDCOM X formal date representation of this fuzzy date.
-     *
-     * This value is suitable for interoperability with genealogy systems
-     * that support the GEDCOM X date specification.
-     *
-     * @see https://github.com/FamilySearch/gedcomx/blob/master/specifications/date-format-specification.md
-     *
-     * @remarks
-     * This representation is derived and may evolve as GEDCOM X mapping
-     * rules are refined.
-     */
-    get formal() {
-        return toGedcomX(this._model);
-    }
-    /**
-     * Normalized, human-readable representation of the fuzzy date.
-     *
-     * This format represents the interpreted meaning of the original input
-     * using a standardized vocabulary and ordering.
-     *
-     * Example outputs:
-     * - `"before 1900"`
-     * - `"March 1890"`
-     * - `"between 1 Jan 1900 and 31 Dec 1901"`
-     */
-    get normalized() {
-        return normalize(this._model);
-    }
-    /**
-     * The inclusive lower bound of this fuzzy date's possible interval (UTC).
-     *
-     * This bound is intended for **endpoint-in-window** searching:
-     * a fuzzy date matches an inclusive search range `[searchStart, searchEnd]`
-     * if **either** its `lowerBound` **or** its `upperBound` falls within the
-     * search range.
-     *
-     * Formally (inclusive):
-     *
-     * ```text
-     * (searchStart <= lowerBound <= searchEnd) OR (searchStart <= upperBound <= searchEnd)
-     * ```
-     *
-     * ## Unbounded intervals
-     *
-     * Open-ended intervals are represented with `null`:
-     * - `lowerBound === null` means unbounded in the past (−∞)
-     * - `upperBound === null` means unbounded in the future (+∞)
-     *
-     * When using the predicate above, treat a `null` bound as not satisfying
-     * the endpoint check (i.e., it is not “within” any finite window).
-     *
-     * @remarks
-     * - Derived from the canonical model.
-     * - Always interpreted as UTC.
-     */
-    get lowerBound() {
-        return this._model.start.minDate === DATE_NEG_INFINITY
-            ? null
-            : this._model.start.minDate;
-    }
-    /**
-     * The inclusive upper bound of this fuzzy date's possible interval (UTC).
-     *
-     * This bound is intended for **endpoint-in-window** searching:
-     * a fuzzy date matches an inclusive search range `[searchStart, searchEnd]`
-     * if **either** its `lowerBound` **or** its `upperBound` falls within the
-     * search range.
-     *
-     * Formally (inclusive):
-     *
-     * ```text
-     * (searchStart <= lowerBound <= searchEnd) OR (searchStart <= upperBound <= searchEnd)
-     * ```
-     *
-     * ## Unbounded intervals
-     *
-     * Open-ended intervals are represented with `null`:
-     * - `lowerBound === null` means unbounded in the past (−∞)
-     * - `upperBound === null` means unbounded in the future (+∞)
-     *
-     * When using the predicate above, treat a `null` bound as not satisfying
-     * the endpoint check (i.e., it is not “within” any finite window).
-     *
-     * @remarks
-     * - Derived from the canonical model.
-     * - Always interpreted as UTC.
-     */
-    get upperBound() {
-        return this._model.start.maxDate === DATE_POS_INFINITY
-            ? null
-            : this._model.start.maxDate;
-    }
-    /**
-     * Collation key used for chronological ordering.
-     *
-     * The collation key is a derived string whose lexicographic ordering
-     * is guaranteed to match the semantic chronological ordering of fuzzy dates.
-     *
-     * ```text
-     * a occurs before b  ⇔  a.collationKey < b.collationKey
-     * ```
-     *
-     * This property is intended for:
-     * - database indexing
-     * - `ORDER BY` clauses
-     * - stable sorting without parsing
-     *
-     * @remarks
-     * - Not human-readable
-     * - Not intended for round-tripping
-     * - Derived entirely from the canonical model
-     */
-    get collationKey() {
-        return collate(this._model);
-    }
-    /**
-     * Serializes this fuzzy date to its canonical JSON representation.
-     *
-     * The returned object is suitable for long-term storage,
-     * transport, and later reconstruction via {@link fromJSON}.
-     */
-    toJSON() {
-        return {
-            modifier: this._model.modifier,
-            start: {
-                format: this._model.start.format,
-                minDate: this._model.start.minDate.toISOString(),
-                maxDate: this._model.start.maxDate.toISOString(),
-            },
-            end: {
-                format: this._model.end.format,
-                minDate: this._model.end.minDate.toISOString(),
-                maxDate: this._model.end.maxDate.toISOString(),
-            },
-        };
-    }
-    /**
-     * Reconstructs a `FuzzyDate` from a previously serialized canonical model.
-     *
-     * @param data A trusted `FuzzyDateModel`, typically loaded from storage.
-     */
-    static fromJSON(data) {
-        try {
-            const json = typeof data === 'string' ? JSON.parse(data) : data;
-            const safeJson = fuzzyDateJsonSchema.parse(json);
-            const model = {
-                modifier: safeJson.modifier,
-                start: {
-                    format: safeJson.start.format,
-                    minDate: new Date(safeJson.start.minDate),
-                    maxDate: new Date(safeJson.start.maxDate),
-                },
-                end: {
-                    format: safeJson.end.format,
-                    minDate: new Date(safeJson.end.minDate),
-                    maxDate: new Date(safeJson.end.maxDate),
-                },
-            };
-            return ok(new FuzzyDate(model));
-        }
-        catch {
-            return err('Invalid JSON data.');
-        }
-    }
-    /**
-     * Parses a human-readable date string into a `FuzzyDate`.
-     *
-     * This method should be used for all untrusted or user-provided input.
-     *
-     * @param input Human-readable date expression.
-     * @returns A result object containing either a `FuzzyDate` or parse issues.
-     *
-     * @remarks
-     * - Parsing is non-throwing; errors are returned as structured issues.
-     * - Successful results are guaranteed to produce a valid canonical model.
-     */
-    static parse(input) {
-        const result = parse(input);
-        if (!result.ok)
-            return result;
-        const date = new FuzzyDate(result.value);
-        return ok(date);
-    }
-}

package/dist/fuzzyDate/fuzzyDate.spec.d.ts

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

package/dist/fuzzyDate/fuzzyDate.spec.js

@@ -1,158 +0,0 @@
-import { assert, describe, expect, it } from 'vitest';
-import { FuzzyDate } from './fuzzyDate';
-describe('Fuzzy Date', () => {
-    it('errs if it parses an invalid date', () => {
-        const unknownDate = FuzzyDate.parse('a');
-        expect(unknownDate).toStrictEqual({
-            ok: false,
-            error: 'Unknown date format.',
-        });
-        const invalidBetween = FuzzyDate.parse('between 1900');
-        expect(invalidBetween).toStrictEqual({
-            ok: false,
-            error: 'Invalid "BETWEEN" modifier.',
-        });
-        const invalidFrom = FuzzyDate.parse('from 1900');
-        expect(invalidFrom).toStrictEqual({
-            ok: false,
-            error: 'Invalid "FROM" modifier.',
-        });
-        const invalidMonth = FuzzyDate.parse('jam 1900');
-        expect(invalidMonth).toStrictEqual({
-            ok: false,
-            error: 'Unknown month.',
-        });
-    });
-    it('parses date inputs', () => {
-        const formats = {
-            '1800s': '1800s',
-            '1800': '1800',
-            'Winter 1800': 'winter 1800',
-            '1800 Winter': 'winter 1800',
-            'Jan 1800': 'January 1800',
-            'January 1800': 'January 1800',
-            '1800 Jan': 'January 1800',
-            '1800 January': 'January 1800',
-            '1 Jan 1800': '1 January 1800',
-            '1 1800': 'January 1800',
-            '01 1800': 'January 1800',
-            '1800 1': 'January 1800',
-            '1800 01': 'January 1800',
-            '1 January 1800': '1 January 1800',
-            '01 Jan 1800': '1 January 1800',
-            '01 January 1800': '1 January 1800',
-            'Jan 1 1800': '1 January 1800',
-            'January 1 1800': '1 January 1800',
-            'Jan 01 1800': '1 January 1800',
-            'January 01 1800': '1 January 1800',
-            '1800 Jan 1': '1 January 1800',
-            '1800 January 1': '1 January 1800',
-            '1800 Jan 01': '1 January 1800',
-            '1800 January 01': '1 January 1800',
-            '1800 1 Jan': '1 January 1800',
-            '1800 1 January': '1 January 1800',
-            '1800 01 Jan': '1 January 1800',
-            '1800 01 January': '1 January 1800',
-            '1 1 1800': '1 January 1800',
-            '01 1 1800': '1 January 1800',
-            '1 01 1800': '1 January 1800',
-            '1800 1 1': '1 January 1800',
-            '1800 01 1': '1 January 1800',
-            '1800 1 01': '1 January 1800',
-            '    1st    of    February    1900    ': '1 February 1900',
-            'feb 1st, 1900': '1 February 1900',
-            'February 1st, 1900': '1 February 1900',
-            '  ---___////,,,,    sEpTeMbEr 30  th ,,,   ---// 1984': '30 September 1984',
-        };
-        for (const [key, value] of Object.entries(formats)) {
-            const result = FuzzyDate.parse(key);
-            let normal;
-            if (result.ok) {
-                normal = result.value.normalized;
-            }
-            else {
-                normal = result.error;
-            }
-            expect(normal).toStrictEqual(value);
-        }
-    });
-    it('test modifiers parsing', () => {
-        const modifiers = [
-            '',
-            'before',
-            'after',
-            'about',
-            'between',
-            'from',
-            'early',
-            'mid',
-            'late',
-            'or',
-        ];
-        const parse = {
-            'before 1st of February 1900': 'before 1 February 1900',
-            'after 1st of February 1900': 'after 1 February 1900',
-            'about 1st of February 1900': 'about 1 February 1900',
-            'between 1st of February 1900 and 18/03/1905': 'between 1 February 1900 and 18 March 1905',
-            'from 1st of February 1900 to 18/03/1905': 'from 1 February 1900 to 18 March 1905',
-        };
-        Object.entries(parse).forEach(([input, expected]) => {
-            const result = FuzzyDate.parse(input);
-            let normal;
-            if (result.ok) {
-                normal = result.value.normalized;
-            }
-            else {
-                normal = result.error;
-            }
-            expect(normal).toStrictEqual(expected);
-        });
-    });
-    it('orders serialized dates in chronological order', () => {
-        const order = [
-            'before 2000',
-            'before jan 2000',
-            'before jan 1 2000',
-            'about 2000',
-            'about jan 2000',
-            'about jan 1 2000',
-            '2000',
-            'jan 2000',
-            'jan 1 2000',
-            'from 2000 to 2001',
-            'from 2000 to jan 2001',
-            'from 2000 to 1 jan 2001',
-            'from jan 2000 to 2001',
-            'from jan 2000 to jan 2001',
-            'from jan 2000 to 1 jan 2001',
-            'from 1 jan 2000 to 2001',
-            'from 1 jan 2000 to jan 2001',
-            'from 1 jan 2000 to 1 jan 2001',
-            'between 2000 and 2001',
-            'between 2000 and jan 2001',
-            'between 2000 and 1 jan 2001',
-            'between jan 2000 and 2001',
-            'between jan 2000 and jan 2001',
-            'between jan 2000 and 1 jan 2001',
-            'between 1 jan 2000 and 2001',
-            'between 1 jan 2000 and jan 2001',
-            'between 1 jan 2000 and 1 jan 2001',
-            'after 2000',
-            'after jan 2000',
-            'after jan 1 2000',
-            'jan 2 2000',
-            'dec 31 2000',
-            '',
-        ];
-        for (let i = 1; i < order.length - 1; i++) {
-            const previous = FuzzyDate.parse(order[i - 1]);
-            const current = FuzzyDate.parse(order[i]);
-            if (previous.ok && current.ok) {
-                expect(previous.value.collationKey < current.value.collationKey).toBeTruthy();
-            }
-            else {
-                assert.fail('failed to parse input');
-            }
-        }
-    });
-});

package/dist/fuzzyDate/gedcomX/toGedcomX.js

@@ -1,31 +0,0 @@
-export function toGedcomX(model) {
-    const startDate = toSimpleDate(model.start);
-    const endDate = toSimpleDate(model.end);
-    const gedcomModifierMap = {
-        NONE: startDate,
-        BEFORE: `/${endDate}`,
-        AFTER: `${startDate}/`,
-        EARLY: `${startDate}/${endDate}`,
-        MID: `${startDate}/${endDate}`,
-        LATE: `${startDate}/${endDate}`,
-        FROM: `${startDate}/${endDate}`,
-        BETWEEN: `${startDate}/${endDate}`,
-        ABOUT: `A${startDate}`,
-    };
-    return gedcomModifierMap[model.modifier];
-}
-function toSimpleDate(dateValue) {
-    const year = dateValue.minDate.getUTCFullYear();
-    const month = dateValue.minDate.getUTCMonth() + 1;
-    const day = dateValue.minDate.getUTCDate();
-    const sign = year >= 0 ? '+' : '-';
-    const yearAbs = Math.abs(year);
-    const yyyy = String(yearAbs).padStart(4, '0');
-    if (dateValue.format === 'YYYY' || dateValue.format === 'YYYYs')
-        return `${sign}${yyyy}`;
-    const mm = String(month).padStart(2, '0');
-    if (dateValue.format === 'MMMM_YYYY' || dateValue.format === 'SEASON_YYYY')
-        return `${sign}${yyyy}-${mm}`;
-    const dd = String(day).padStart(2, '0');
-    return `${sign}${yyyy}-${mm}-${dd}`;
-}

package/dist/fuzzyDate/helpers/constants.d.ts

@@ -1,4 +0,0 @@
-export declare const DATE_NEG_INFINITY: Date;
-export declare const DATE_POS_INFINITY: Date;
-export declare const FORMAT_ORDER: readonly ["YYYYs", "YYYY", "SEASON_YYYY", "MMMM_YYYY", "D_MMMM_YYYY"];
-export declare const MODIFIER_ORDER: readonly ["BEFORE", "ABOUT", "NONE", "EARLY", "MID", "LATE", "FROM", "BETWEEN", "AFTER"];

package/dist/fuzzyDate/helpers/constants.js

@@ -1,20 +0,0 @@
-export const DATE_NEG_INFINITY = new Date(-8640000000000000);
-export const DATE_POS_INFINITY = new Date(8640000000000000);
-export const FORMAT_ORDER = [
-    'YYYYs',
-    'YYYY',
-    'SEASON_YYYY',
-    'MMMM_YYYY',
-    'D_MMMM_YYYY',
-];
-export const MODIFIER_ORDER = [
-    'BEFORE',
-    'ABOUT',
-    'NONE',
-    'EARLY',
-    'MID',
-    'LATE',
-    'FROM',
-    'BETWEEN',
-    'AFTER',
-];

package/dist/fuzzyDate/helpers/schemas.d.ts

@@ -1,36 +0,0 @@
-import z from 'zod';
-export declare const fuzzyDateJsonSchema: z.ZodObject<{
-    modifier: z.ZodEnum<{
-        BEFORE: "BEFORE";
-        ABOUT: "ABOUT";
-        NONE: "NONE";
-        EARLY: "EARLY";
-        MID: "MID";
-        LATE: "LATE";
-        FROM: "FROM";
-        BETWEEN: "BETWEEN";
-        AFTER: "AFTER";
-    }>;
-    start: z.ZodObject<{
-        format: z.ZodEnum<{
-            YYYYs: "YYYYs";
-            YYYY: "YYYY";
-            SEASON_YYYY: "SEASON_YYYY";
-            MMMM_YYYY: "MMMM_YYYY";
-            D_MMMM_YYYY: "D_MMMM_YYYY";
-        }>;
-        minDate: z.ZodISODateTime;
-        maxDate: z.ZodISODateTime;
-    }, z.core.$strip>;
-    end: z.ZodObject<{
-        format: z.ZodEnum<{
-            YYYYs: "YYYYs";
-            YYYY: "YYYY";
-            SEASON_YYYY: "SEASON_YYYY";
-            MMMM_YYYY: "MMMM_YYYY";
-            D_MMMM_YYYY: "D_MMMM_YYYY";
-        }>;
-        minDate: z.ZodISODateTime;
-        maxDate: z.ZodISODateTime;
-    }, z.core.$strip>;
-}, z.core.$strip>;

package/dist/fuzzyDate/helpers/schemas.js

@@ -1,12 +0,0 @@
-import z from 'zod';
-import { FORMAT_ORDER, MODIFIER_ORDER } from './constants';
-const fuzzyDateValueSchema = z.object({
-    format: z.enum(FORMAT_ORDER),
-    minDate: z.iso.datetime(),
-    maxDate: z.iso.datetime(),
-});
-export const fuzzyDateJsonSchema = z.object({
-    modifier: z.enum(MODIFIER_ORDER),
-    start: fuzzyDateValueSchema,
-    end: fuzzyDateValueSchema,
-});

package/dist/fuzzyDate/helpers/types.d.ts

@@ -1,16 +0,0 @@
-import z from 'zod';
-import { FORMAT_ORDER, MODIFIER_ORDER } from './constants';
-import { fuzzyDateJsonSchema } from './schemas';
-export type FuzzyDateFormat = (typeof FORMAT_ORDER)[number];
-export type FuzzyDate = (typeof MODIFIER_ORDER)[number];
-export type FuzzyDateValue = {
-    format: FuzzyDateFormat;
-    minDate: Date;
-    maxDate: Date;
-};
-export type FuzzyDateModel = {
-    modifier: FuzzyDate;
-    start: FuzzyDateValue;
-    end: FuzzyDateValue;
-};
-export type FuzzyDateJson = z.infer<typeof fuzzyDateJsonSchema>;

package/dist/fuzzyDate/helpers/types.js

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

package/dist/fuzzyDate/normalize/normalize.js

@@ -1,47 +0,0 @@
-import { isSeasonMonth, SEASON_MONTH_MAP } from '../helpers/maps';
-// Main function
-export function normalize(model) {
-    const startDate = normalizeDate(model.start.minDate, model.start.format);
-    const endDate = normalizeDate(model.end.minDate, model.end.format);
-    const normalModifierMap = {
-        NONE: startDate,
-        BEFORE: `before ${endDate}`,
-        AFTER: `after ${startDate}`,
-        EARLY: `early ${startDate}`,
-        MID: `mid ${startDate}`,
-        LATE: `late ${startDate}`,
-        FROM: `from ${startDate} to ${endDate}`,
-        BETWEEN: `between ${startDate} and ${endDate}`,
-        ABOUT: `about ${startDate}`,
-    };
-    return normalModifierMap[model.modifier];
-}
-// Helpers
-function normalizeDate(date, format) {
-    const options = { timeZone: 'UTC' };
-    switch (format) {
-        case 'YYYY':
-            options.year = 'numeric';
-            break;
-        case 'MMMM_YYYY':
-            options.month = 'long';
-            options.year = 'numeric';
-            break;
-        case 'D_MMMM_YYYY':
-            options.day = 'numeric';
-            options.month = 'long';
-            options.year = 'numeric';
-            break;
-        case 'SEASON_YYYY': {
-            const month = date.getUTCMonth() + 1;
-            if (!isSeasonMonth(month))
-                return ''; // month always returns 1 - 12 so this should never happen
-            return `${SEASON_MONTH_MAP[month]} ${date.getUTCFullYear()}`;
-        }
-        case 'YYYYs': {
-            const year = date.getUTCFullYear();
-            return `${year}s`;
-        }
-    }
-    return date.toLocaleDateString('en-GB', options);
-}