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

package/README.md

@@ -1,16 +1,10 @@
 # Fuzzy Dates
 
-Parse imprecise, human-entered date strings into a structured, consistent model that you can normalize, search, sort, and serialize.
-
-Explore the docs
-
-## Features
-
-- Handles modifiers like `before`, `after`, `about`, `between`, `from`, `early`, `mid`, `late`.
-- Normalizes many input shapes (`1st of February 1900`, `Feb 1 1900`, `winter 1890`, `1800s`).
-- Produces inclusive lower/upper bounds for range filtering and a collation key for stable chronological sorting.
-- Outputs a canonical JSON model plus GEDCOM X formal dates for genealogy interoperability.
-- ESM + TypeScript ready (`.d.ts` shipped with the package).
+Parse human-entered fuzzy date text into a consistent model you can use to:
+- normalize display text,
+- filter with inclusive UTC bounds,
+- sort chronologically with deterministic keys,
+- serialize to GEDCOM X formal dates.
 
 ## Installation
 
@@ -21,43 +15,112 @@ npm i @fhss-web-team/fuzzy-dates
 ## Quick start
 
 ```ts
-import { FuzzyDate } from "@fhss-web-team/fuzzy-dates";
+import { FuzzyDate } from '@fhss-web-team/fuzzy-dates';
 
-const parsed = FuzzyDate.parse("about Feb 1900");
-if (!parsed.ok) throw parsed.error;
+const parsed = FuzzyDate.parse('about Feb 1900');
+if (!parsed.ok) throw new Error(parsed.error);
 
 const date = parsed.value;
-console.log(date.normalized); // "about 1 February 1900"
-console.log(date.lowerBound); // 1899-02-01T00:00:00.000Z (Date)
-console.log(date.upperBound); // 1901-01-31T23:59:59.999Z (Date)
-console.log(date.collationKey); // deterministic string for sorting
-
-// Serialize for storage and hydrate later
-const json = date.toJSON();
-const hydrated = FuzzyDate.fromJSON(json);
+console.log(date.normalized); // "about February 1900"
+console.log(date.earliest.toISOString()); // "1900-02-01T00:00:00.000Z"
+console.log(date.latest.toISOString()); // "1900-02-28T23:59:59.999Z"
+console.log(date.collationKeys); // [primary, timeRelation, range, approximate]
+console.log(date.formal); // "A+1900-02"
+```
+
+## API
+
+### `FuzzyDate.parse(input: string): Result<FuzzyDate, string>`
+Non-throwing parse entrypoint.
+
+- Success shape: `{ ok: true, value: FuzzyDate }`
+- Error shape: `{ ok: false, error: string }`
+
+### `FuzzyDate.sort(a: FuzzyDate, b: FuzzyDate): number`
+Comparator for chronological ordering.
+
+```ts
+dates.sort(FuzzyDate.sort);
 ```
 
-## API snapshot
+### `FuzzyDate.query(searchStart: Date, searchEnd: Date, dates: readonly FuzzyDate[]): FuzzyDate[]`
+Filters using endpoint-in-window logic (inclusive):
+
+```text
+(searchStart <= earliest <= searchEnd) OR (searchStart <= latest <= searchEnd)
+```
 
-- `FuzzyDate.parse(input: string): Result<FuzzyDate, string>` — non-throwing parse; errors come back as `{ ok: false, error }`.
-- `FuzzyDate.fromJSON(model: FuzzyDateModel)` — rebuild from the canonical JSON model.
-- `FuzzyDate` instance properties:
-  - `normalized` — normalized human-readable string.
-  - `lowerBound` / `upperBound` — inclusive Date bounds (or `null` for unbounded).
-  - `collationKey` — sortable string aligned to chronological order.
-  - `formal` — GEDCOM X formal date representation.
-  - `toJSON()` — returns the canonical model.
+This is intentionally different from generic interval-overlap matching.
+
+### Instance getters
+
+- `normalized: string`  
+  Standardized human-readable expression.
+- `formal: string`  
+  GEDCOM X formal date representation.
+- `approximate: boolean`  
+  Whether the parsed expression is marked approximate.
+- `earliest: Date` / `latest: Date`  
+  Inclusive UTC bounds. Open-ended ranges are represented with sentinel values:
+  - `before ...` uses `earliest = new Date(-8640000000000000)`
+  - `after ...` uses `latest = new Date(8640000000000000)`
+- `collationKeys: readonly [number, -1 | 0 | 1, number, 0 | 1]`  
+  Keys used by `FuzzyDate.sort`.
+
+## Supported input
+
+### Modifiers
+
+- `about ...`, `approximately ...`, `around ...`
+- `before ...`
+- `after ...`
+- `between ... and ...`
+- `from ... to ...`
+
+Notes:
+- `between ... and ...` is treated as approximate.
+- `from ... to ...` is exact unless prefixed with an approximation modifier.
+
+### Simple date forms
+
+Supported orderings include:
+- `YYYY`
+- `month YYYY` / `YYYY month` (named month, numeric month, or season)
+- `day month YYYY`
+- `month day YYYY`
+- `YYYY month day`
+- `YYYY day month`
+- digit variants for month/day in those positions
+
+Examples:
+- `1900`
+- `January 1900`, `1900 Jan`, `01 1900`, `1900 1`
+- `1 Jan 1900`, `Jan 1 1900`, `1900 January 1`, `1900 1 Jan`
+- `winter 1900`, `1900 autumn`
+
+Input normalization steps:
+- case-insensitive,
+- strips ordinal suffixes (`1st`, `2nd`, `3rd`, `4th`, ...),
+- treats punctuation/separators (`. , / - _`) as whitespace.
+
+## Behavior details
+
+- All parsing and bounds are UTC-based.
+- Calendar-overflow dates are normalized by JavaScript `Date` semantics.
+  - `29 feb 1900` normalizes to `1 March 1900`.
+  - `31 apr 1900` normalizes to `1 May 1900`.
+- Current year support is strictly four digits (`0000`-`9999` pattern in input).
+- Decade shorthand like `1800s` is not currently supported.
 
 ## Development
 
-- Tests: `npm test` (Vitest)
-- Build: `npm run build` (TypeScript -> `dist/`)
-- Pack locally (publish dry-run): `npm pack` then install the generated `.tgz` in a temp project to verify exports and typings.
+- Tests: `npm test`
+- Build: `npm run build`
+- Package check: `npm pack`
 
 ## Support
 
-This package was developed by the [BYU's Center for Family History and Genealogy](https://cfhg.byu.edu/). To support
-our mission to provide quality online family history research and resources for the public at no cost, consider donating [HERE](https://donate.churchofjesuschrist.org/contribute/byu/family-home-social-sciences/center-family-history-genealogy)
+This package was developed by the [BYU Center for Family History and Genealogy](https://cfhg.byu.edu/). To support our mission to provide quality online family history research and resources for the public at no cost, consider donating [here](https://donate.churchofjesuschrist.org/contribute/byu/family-home-social-sciences/center-family-history-genealogy).
 
 ## License
 

package/dist/index.d.ts

@@ -1,3 +1 @@
-export { FuzzyDate } from './fuzzyDate/fuzzyDate.js';
-export { FuzzyDateJson } from './fuzzyDate/helpers/types.js';
-export { fuzzyDateJsonSchema } from './fuzzyDate/helpers/schemas.js';
+export { FuzzyDate } from './src/fuzzyDate.js';

package/dist/index.js

@@ -1,2 +1 @@
-export { FuzzyDate } from './fuzzyDate/fuzzyDate.js';
-export { fuzzyDateJsonSchema } from './fuzzyDate/helpers/schemas.js';
+export { FuzzyDate } from './src/fuzzyDate.js';

package/dist/src/collation/collationKey.d.ts

@@ -0,0 +1,2 @@
+import { FuzzyDateModel } from '../helpers/types';
+export declare function collate(model: FuzzyDateModel): readonly [number, -1 | 0 | 1, number, 0 | 1];

package/dist/src/collation/collationKey.js

@@ -0,0 +1,44 @@
+import { isRange } from '../helpers/types';
+export function collate(model) {
+    if (isRange(model)) {
+        // left open
+        if (model.start === null && model.end !== null) {
+            return [
+                model.end.min.getTime(),
+                -1,
+                -1 * (model.end.max.getTime() - model.end.min.getTime()),
+                model.approximate ? 0 : 1,
+            ];
+        }
+        // right open
+        if (model.end === null && model.start !== null) {
+            return [
+                model.start.max.getTime(),
+                1,
+                -1 * (model.start.max.getTime() - model.start.min.getTime()),
+                model.approximate ? 0 : 1,
+            ];
+        }
+        // closed
+        if (model.start !== null && model.end !== null) {
+            return [
+                model.start.min.getTime(),
+                0,
+                -1 * (model.end.max.getTime() - model.start.min.getTime()),
+                model.approximate ? 0 : 1,
+            ];
+        }
+    }
+    else {
+        // simple
+        if (model.start !== null && model.end !== null) {
+            return [
+                model.start.min.getTime(),
+                0,
+                -1 * (model.end.max.getTime() - model.start.min.getTime()),
+                model.approximate ? 0 : 1,
+            ];
+        }
+    }
+    return [Number.MAX_SAFE_INTEGER, 1, Number.MAX_SAFE_INTEGER, 1];
+}

package/dist/{fuzzyDate → src}/fuzzyDate.d.ts

@@ -1,4 +1,3 @@
-import { FuzzyDateJson } from './helpers/types';
 /**
  * Represents an immutable, parsed fuzzy date suitable for genealogy and
  * historical data contexts.
@@ -19,9 +18,9 @@ import { FuzzyDateJson } from './helpers/types';
  * ### 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
+ * - **Explicit construction**: Instances must be created via `parse()`.
+ *   Direct construction via `new` is intentionally disallowed.
+ * - **Derived projections**: Query bounds and collation keys
  *   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.
@@ -31,10 +30,7 @@ import { FuzzyDateJson } from './helpers/types';
  * ### 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
+ * - Store `lowerBound`, `upperBound`, and `collationKeys` separately for
  *   efficient querying and ordering.
  */
 export declare class FuzzyDate {
@@ -48,7 +44,7 @@ export declare class FuzzyDate {
     /**
      * Private constructor to enforce factory-based creation.
      *
-     * Consumers must use {@link FuzzyDate.parse} or {@link FuzzyDate.fromJSON}.
+     * Consumers must use {@link FuzzyDate.parse}.
      */
     private constructor();
     /**
@@ -81,97 +77,78 @@ export declare class FuzzyDate {
      *
      * 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
+     * if **either** its `earliest` **or** its `latest` falls within the
      * search range.
      *
-     * Formally (inclusive):
-     *
      * ```text
-     * (searchStart <= lowerBound <= searchEnd) OR (searchStart <= upperBound <= searchEnd)
+     * (searchStart <= earliest <= searchEnd) OR (searchStart <= latest <= 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(): Date | null;
+    get earliest(): Date;
     /**
      * 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
+     * if **either** its `earliest` **or** its `latest` falls within the
      * search range.
      *
-     * Formally (inclusive):
-     *
      * ```text
-     * (searchStart <= lowerBound <= searchEnd) OR (searchStart <= upperBound <= searchEnd)
+     * (searchStart <= earliest <= searchEnd) OR (searchStart <= latest <= 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(): Date | null;
+    get latest(): Date;
     /**
-     * Collation key used for chronological ordering.
+     * A lexicographically sortable tuple representing this fuzzy date.
      *
-     * The collation key is a derived string whose lexicographic ordering
-     * is guaranteed to match the semantic chronological ordering of fuzzy dates.
+     * Sort **ascending** by each element in order to achieve correct chronological ordering.
      *
-     * ```text
-     * a occurs before b  ⇔  a.collationKey < b.collationKey
-     * ```
+     * Tuple structure:
      *
-     * This property is intended for:
-     * - database indexing
-     * - `ORDER BY` clauses
-     * - stable sorting without parsing
+     * 1. `primary` (number)
+     *    - Epoch milliseconds used as the primary chronological anchor.
+     *    - For closed ranges and simple dates: the start minimum.
+     *    - For left-open ranges: the end minimum.
+     *    - For right-open ranges: the start maximum.
      *
-     * @remarks
-     * - Not human-readable
-     * - Not intended for round-tripping
-     * - Derived entirely from the canonical model
-     */
-    get collationKey(): string;
-    /**
-     * Serializes this fuzzy date to its canonical JSON representation.
+     * 2. `timeRelation` (-1 | 0 | 1)
+     *    - Distinguishes range type.
+     *    - `-1` → left-open range  (… end)
+     *    - `0`  → closed range or simple date
+     *    - `1`  → right-open range (start …)
      *
-     * The returned object is suitable for long-term storage,
-     * transport, and later reconstruction via {@link fromJSON}.
+     * 3. `range` (number)
+     *    - Total span of the range in milliseconds.
+     *    - For simple dates, this represents the precision window.
+     *    - Wider ranges sort before smaller ones.
+     *
+     * 4. `approximate` (0 | 1)
+     *    - `0` → approximate
+     *    - `1` → exact
+     *    - Approximate values sort first.
+     *
+     * Example (SQL):
+     *
+     * ```sql
+     * ORDER BY primary ASC,
+     *          timeRelation ASC,
+     *          range ASC,
+     *          approximate ASC
+     * ```
      */
-    toJSON(): FuzzyDateJson;
+    get collationKeys(): readonly [number, -1 | 0 | 1, number, 0 | 1];
     /**
-     * Reconstructs a `FuzzyDate` from a previously serialized canonical model.
+     * Gets whether the date is marked as approximate.
      *
-     * @param data A trusted `FuzzyDateModel`, typically loaded from storage.
+     * @returns True if the underlying model marks the date as approximate; otherwise false.
      */
-    static fromJSON(data: unknown): {
-        ok: true;
-        value: FuzzyDate;
-    } | {
-        ok: false;
-        error: "Invalid JSON data.";
-    };
+    get approximate(): boolean;
     /**
      * Parses a human-readable date string into a `FuzzyDate`.
      *
@@ -203,4 +180,43 @@ export declare class FuzzyDate {
         ok: true;
         value: FuzzyDate;
     };
+    /**
+     * Comparator for sorting {@link FuzzyDate} instances chronologically.
+     *
+     * This method performs a lexicographic ascending comparison using each
+     * instance’s {@link FuzzyDate.collationKeys} tuple.
+     *
+     * Sort precedence (ascending):
+     * 1. Primary epoch anchor (milliseconds)
+     * 2. Time relation (-1 | 0 | 1)
+     * 3. Range span (milliseconds)
+     * 4. Approximate flag (0 = approximate, 1 = exact)
+     *
+     * Designed for use with `Array.prototype.sort`.
+     *
+     * @param a - The first {@link FuzzyDate} to compare.
+     * @param b - The second {@link FuzzyDate} to compare.
+     * @returns
+     * - A negative number if `a` should sort before `b`
+     * - A positive number if `a` should sort after `b`
+     * - `0` if they are considered equivalent for sorting
+     *
+     * @example
+     * ```ts
+     * dates.sort(FuzzyDate.sort);
+     * ```
+     */
+    static sort(a: FuzzyDate, b: FuzzyDate): number;
+    /**
+     * Filters dates using endpoint-in-window semantics.
+     *
+     * A date matches when either endpoint (`earliest` or `latest`) is inside
+     * the inclusive UTC window `[searchStart, searchEnd]`.
+     *
+     * @param searchStart Inclusive window start (UTC).
+     * @param searchEnd Inclusive window end (UTC).
+     * @param dates Collection of fuzzy dates to evaluate.
+     * @returns Sublist of dates that match the query.
+     */
+    static query(searchStart: Date, searchEnd: Date, dates: readonly FuzzyDate[]): FuzzyDate[];
 }

package/dist/src/fuzzyDate.js

@@ -0,0 +1,238 @@
+import { parse } from './parse/index';
+import { normalize } from './normalize/normalize';
+import { toGedcomX } from './gedcomX/toGedcomX';
+import { ok } from './helpers/result';
+import { DATE_NEG_INFINITY, DATE_POS_INFINITY } from './helpers/constants';
+import { collate } from './collation/collationKey';
+/**
+ * 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()`.
+ *   Direct construction via `new` is intentionally disallowed.
+ * - **Derived projections**: Query bounds and collation keys
+ *   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.
+ * - Store `lowerBound`, `upperBound`, and `collationKeys` 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}.
+     */
+    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 `earliest` **or** its `latest` falls within the
+     * search range.
+     *
+     * ```text
+     * (searchStart <= earliest <= searchEnd) OR (searchStart <= latest <= searchEnd)
+     * ```
+     *
+     * @remarks
+     * - Always interpreted as UTC.
+     */
+    get earliest() {
+        return this._model.start?.min ?? DATE_NEG_INFINITY;
+    }
+    /**
+     * 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 `earliest` **or** its `latest` falls within the
+     * search range.
+     *
+     * ```text
+     * (searchStart <= earliest <= searchEnd) OR (searchStart <= latest <= searchEnd)
+     * ```
+     *
+     * @remarks
+     * - Always interpreted as UTC.
+     */
+    get latest() {
+        return this._model.end?.max ?? DATE_POS_INFINITY;
+    }
+    /**
+     * A lexicographically sortable tuple representing this fuzzy date.
+     *
+     * Sort **ascending** by each element in order to achieve correct chronological ordering.
+     *
+     * Tuple structure:
+     *
+     * 1. `primary` (number)
+     *    - Epoch milliseconds used as the primary chronological anchor.
+     *    - For closed ranges and simple dates: the start minimum.
+     *    - For left-open ranges: the end minimum.
+     *    - For right-open ranges: the start maximum.
+     *
+     * 2. `timeRelation` (-1 | 0 | 1)
+     *    - Distinguishes range type.
+     *    - `-1` → left-open range  (… end)
+     *    - `0`  → closed range or simple date
+     *    - `1`  → right-open range (start …)
+     *
+     * 3. `range` (number)
+     *    - Total span of the range in milliseconds.
+     *    - For simple dates, this represents the precision window.
+     *    - Wider ranges sort before smaller ones.
+     *
+     * 4. `approximate` (0 | 1)
+     *    - `0` → approximate
+     *    - `1` → exact
+     *    - Approximate values sort first.
+     *
+     * Example (SQL):
+     *
+     * ```sql
+     * ORDER BY primary ASC,
+     *          timeRelation ASC,
+     *          range ASC,
+     *          approximate ASC
+     * ```
+     */
+    get collationKeys() {
+        return collate(this._model);
+    }
+    /**
+     * Gets whether the date is marked as approximate.
+     *
+     * @returns True if the underlying model marks the date as approximate; otherwise false.
+     */
+    get approximate() {
+        return this._model.approximate;
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Comparator for sorting {@link FuzzyDate} instances chronologically.
+     *
+     * This method performs a lexicographic ascending comparison using each
+     * instance’s {@link FuzzyDate.collationKeys} tuple.
+     *
+     * Sort precedence (ascending):
+     * 1. Primary epoch anchor (milliseconds)
+     * 2. Time relation (-1 | 0 | 1)
+     * 3. Range span (milliseconds)
+     * 4. Approximate flag (0 = approximate, 1 = exact)
+     *
+     * Designed for use with `Array.prototype.sort`.
+     *
+     * @param a - The first {@link FuzzyDate} to compare.
+     * @param b - The second {@link FuzzyDate} to compare.
+     * @returns
+     * - A negative number if `a` should sort before `b`
+     * - A positive number if `a` should sort after `b`
+     * - `0` if they are considered equivalent for sorting
+     *
+     * @example
+     * ```ts
+     * dates.sort(FuzzyDate.sort);
+     * ```
+     */
+    static sort(a, b) {
+        return (a.collationKeys[0] - b.collationKeys[0] ||
+            a.collationKeys[1] - b.collationKeys[1] ||
+            a.collationKeys[2] - b.collationKeys[2] ||
+            a.collationKeys[3] - b.collationKeys[3]);
+    }
+    /**
+     * Filters dates using endpoint-in-window semantics.
+     *
+     * A date matches when either endpoint (`earliest` or `latest`) is inside
+     * the inclusive UTC window `[searchStart, searchEnd]`.
+     *
+     * @param searchStart Inclusive window start (UTC).
+     * @param searchEnd Inclusive window end (UTC).
+     * @param dates Collection of fuzzy dates to evaluate.
+     * @returns Sublist of dates that match the query.
+     */
+    static query(searchStart, searchEnd, dates) {
+        return dates.filter((date) => (searchStart <= date.earliest && date.earliest <= searchEnd) ||
+            (searchStart <= date.latest && date.latest <= searchEnd));
+    }
+}