typescript-nl-date-parsing-regex

Answer

Root cause (PARSER-001): PARSE_REQUEST only consulted an ISO-only DATE_RE (\d{4}-\d{2}-\d{2}). Any natural-language date ("next Tuesday", "in 3 days", "March 5") failed the regex, so the request stalled — no date was resolved and the state machine couldn't advance.

Fix: extract a pure, dependency-free date resolver into @heading/core with an injectable now for deterministic tests, and fall back to it only after ISO matching. The fromTo origin/destination extraction was separately broken by an overly-greedy case-insensitive 3-letter regex that turned "need to fly" into EED→FLY.

1. parseNaturalLanguageDate(text, now?) — new pure resolver

// packages/heading/core/src/nl-date.ts
const WEEKDAY_INDEX: Record<string, number> = {
  sunday: 0, monday: 1, tuesday: 2, wednesday: 3,
  thursday: 4, friday: 5, saturday: 6,
};
const MONTH_INDEX: Record<string, number> = {
  january: 1, february: 2, march: 3, april: 4, may: 5, june: 6,
  july: 7, august: 8, september: 9, october: 10, november: 11, december: 12,
};
const WEEKDAYS = Object.keys(WEEKDAY_INDEX).join('|');
const MONTHS = Object.keys(MONTH_INDEX).join('|');

export function parseNaturalLanguageDate(text: string, now: Date = new Date()): Date | null {
  const t = text.toLowerCase().trim();
  if (!t) return null;

  // --- relative keywords -------------------------------------------------
  if (/\btoday\b/.test(t)) return new Date(now.getTime());
  if (/\btomorrow\b/.test(t)) {
    const d = new Date(now.getTime());
    d.setDate(d.getDate() + 1);
    return d;
  }
  const inN = t.match(/\bin\s+(\d+)\s+(day|days|week|weeks)\b/);
  if (inN) {
    const n = Number(inN[1]);
    const d = new Date(now.getTime());
    d.setDate(d.getDate() + (inN[2].startsWith('week') ? n * 7 : n));
    return d;
  }
  if (/\bnext\s+week\b/.test(t)) { // Monday of the following ISO week
    const d = new Date(now.getTime());
    const daysSinceMonday = (now.getDay() + 6) % 7;
    d.setDate(now.getDate() - daysSinceMonday + 7);
    return d;
  }

  // --- named weekdays ----------------------------------------------------
  // Negative lookbehind rejects "last X" / "previous X": those must NOT be
  // interpreted as an upcoming bare weekday occurrence.
  const named = t.match(
    new RegExp(`(?<!\\b(?:last|previous)\\s)((?:next\\s+)?)(${WEEKDAYS})\\b`),
  );
  if (named) {
    const isExplicitNext = named[1] !== '';
    let delta = (WEEKDAY_INDEX[named[2]] - now.getDay() + 7) % 7;
    if (isExplicitNext && delta === 0) delta = 7; // "next X" strictly after now
    const d = new Date(now.getTime());
    d.setDate(d.getDate() + delta);
    return d;
  }

  // --- month names (month-first + day-first, optional year) --------------
  const monthFirst = t.match(new RegExp(`\\b(${MONTHS})\\s+(\\d{1,2})(?:,?\\s+(\\d{4}))?\\b`));
  const dayFirst   = t.match(new RegExp(`\\b(\\d{1,2})\\s+(${MONTHS})(?:,?\\s+(\\d{4}))?\\b`));
  const m = monthFirst ?? dayFirst;
  if (m) {
    const [monthName, dayStr, yearStr] = monthFirst
      ? [monthFirst[1], monthFirst[2], monthFirst[3]]
      : [dayFirst![2], dayFirst![1], dayFirst![3]];
    const day = Number(dayStr);
    if (day < 1 || day > 31) return null;
    const year = yearStr ? Number(yearStr) : now.getFullYear();
    const candidate = new Date(year, MONTH_INDEX[monthName] - 1, day);
    // Reject impossible dates (Feb 30 → normalized by Date constructor)
    if (candidate.getMonth() !== MONTH_INDEX[monthName] - 1 || candidate.getDate() !== day) return null;
    // Past month+day without explicit year rolls to next year (travel context)
    if (!yearStr) {
      const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
      if (candidate < today) candidate.setFullYear(year + 1);
    }
    return candidate;
  }

  return null; // caller decides: keep AWAITING_CLARIFICATION
}

2. Integration in the request parser — ISO-first, NL fallback

// packages/heading/core/src/parse-request.ts
const DATE_RE = /\b\d{4}-\d{2}-\d{2}\b/; // unchanged, ISO-only

function resolveDate(text: string, now: Date = new Date()): Date | null {
  const iso = text.match(DATE_RE);
  if (iso) return new Date(iso[0]);           // ISO-first keeps old behavior
  return parseNaturalLanguageDate(text, now); // NL fallback; null → AWAITING_CLARIFICATION
}

The state machine logic is untouched: if resolveDate returns null, the request still transitions to AWAITING_CLARIFICATION exactly as before — the fallback only adds dates it previously missed.

3. fromTo origin/destination validation

// Before: /(\w{3})\s+to\s+(\w{3})/i on "need to fly" matched "eed to fly" → EED→FLY.
// After: endpoints must be real IATA codes extracted from the text itself.
const IATA_RE = /\b[A-Z]{3}\b/g;

const iatas = new Set((text.match(IATA_RE) ?? []).map((c) => c.toUpperCase()));
const pair = text.match(/\b([a-z]{3})\s+to\s+([a-z]{3})\b/i);

if (pair) {
  const from = pair[1].toUpperCase();
  const to = pair[2].toUpperCase();
  if (iatas.has(from) && iatas.has(to)) {
    origin = from;
    destination = to;
  }
  // else: not a flight pair — "need to fly" no longer produces EED→FLY
}

Because IATA codes only exist as uppercase tokens in the input, "need to fly to paris" yields an empty iatas set and the pair is rejected, while a genuine "fly JFK to LAX" passes validation.