nl2time 0.1.1 → 0.3.1

package/dist/parse/en.d.ts

@@ -15,4 +15,13 @@ export interface RuleMatch {
 }
 export type Rule = (tokens: Token[], i: number, ctx: TimeContext) => RuleMatch | undefined;
 /** Rules in priority order (first match at a position wins ties by length then order). */
+/**
+ * Built-in English rules with stable public names (docs/extending.md).
+ * Order matters: the scanner prefers longer matches, then higher confidence,
+ * then earlier list position — so names are also the disable/override handle.
+ */
+export declare const EN_RULE_ENTRIES: readonly {
+    name: string;
+    rule: Rule;
+}[];
 export declare const EN_RULES: readonly Rule[];

package/dist/parse/en.js

@@ -610,6 +610,51 @@ function buildRange(a, b, scope, period, connWord) {
     }
     return undefined;
 }
+/**
+ * Open-range connectors (#18): "since X" → [start(X), now]; "until X" /
+ * "till X" / "through X" / "up to X" / "by X" (deadline) → [now, end(X)].
+ * These only fire when the connector opens the range — "A until B" and
+ * "from A through B" are consumed earlier by the range rule.
+ */
+const ruleOpenRange = (tokens, i, ctx) => {
+    const w = word(tokens[i]);
+    let mode;
+    let at = i + 1;
+    if (w === 'since')
+        mode = 'since';
+    else if (w === 'until' || w === 'till' || w === 'through' || w === 'thru' || w === 'by') {
+        mode = 'until';
+    }
+    else if (w === 'up' && word(tokens[i + 1]) === 'to') {
+        mode = 'until';
+        at = i + 2;
+    }
+    if (!mode)
+        return undefined;
+    // "by the 15th": a bare article only before an explicit calendar date —
+    // NOT "through the week"-style prose, which stays unmatched.
+    if (word(tokens[at]) === 'the' && ruleCalendarDate(tokens, at + 1, ctx))
+        at += 1;
+    const inner = ruleDeicticDay(tokens, at, ctx) ??
+        ruleLastThisNext(tokens, at, ctx) ??
+        ruleHoliday(tokens, at, ctx) ??
+        ruleEndOf(tokens, at, ctx) ??
+        ruleWeekOf(tokens, at, ctx) ??
+        ruleBareYear(tokens, at, ctx) ??
+        ruleCalendarDate(tokens, at, ctx) ??
+        ruleClockTime(tokens, at, ctx) ??
+        ruleWeekdayAlone(tokens, at, ctx);
+    if (!inner || inner.role === 'duration')
+        return undefined;
+    // Boundary points ("by EOD", "by the end of the month") keep their point
+    // reading — the deadline instant is the answer there, not a range.
+    if (inner.expr.op === 'snap' && inner.expr.edge !== undefined)
+        return undefined;
+    const expr = mode === 'since'
+        ? { op: 'between', start: inner.expr, end: NOW }
+        : { op: 'between', start: NOW, end: inner.expr };
+    return { expr, consumed: at + inner.consumed - i, confidence: 0.9, role: 'datetime' };
+};
 /** "week of April 10th", "the first/last week of July", "the week starting on Feb 4". */
 const ruleWeekOf = (tokens, i, ctx) => {
     let at = i;
@@ -915,6 +960,88 @@ const ruleEndOf = (tokens, i, ctx) => {
         : { ...inner.expr, mod: isEnd ? 'end' : isMid ? 'mid' : 'start' };
     return { expr, consumed: at + inner.consumed - i, confidence: 0.95, role: 'date' };
 };
+/** The period unit a half-of scope denotes, if determinable. */
+function halfScopeUnit(expr) {
+    if (expr.op === 'snap') {
+        return expr.edge === undefined &&
+            (expr.unit === 'week' || expr.unit === 'month' || expr.unit === 'quarter' || expr.unit === 'year')
+            ? expr.unit
+            : undefined;
+    }
+    if (expr.op === 'literal' && expr.date !== undefined && expr.time === undefined) {
+        if (expr.date.day !== undefined)
+            return undefined;
+        return expr.date.month !== undefined ? 'month' : 'year';
+    }
+    if (expr.op === 'seek' && expr.target.kind === 'month')
+        return 'month';
+    return undefined;
+}
+/** "the first/second half of <period>" → [start, mid) / [mid, end) (#24). */
+const ruleHalfOf = (tokens, i, ctx) => {
+    let at = i;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    const w = word(tokens[at]);
+    const t = tokens[at];
+    let which;
+    if (w === 'first')
+        which = 1;
+    else if (w === 'second' || w === 'latter' || w === 'back')
+        which = 2;
+    else if (t?.type === 'number' && t.ordinal && (t.value === 1 || t.value === 2)) {
+        which = t.value;
+    }
+    if (which === undefined)
+        return undefined;
+    if (word(tokens[at + 1]) !== 'half' || word(tokens[at + 2]) !== 'of')
+        return undefined;
+    at += 3;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    // Scope: a bare unit ("the year"), a relative period ("next month"), a
+    // month name, a quarter, or a year.
+    let scope;
+    let unit;
+    let consumed = 0;
+    const uw = word(tokens[at]) !== 'night' ? UNIT_WORDS[word(tokens[at]) ?? ''] : undefined;
+    if (uw === 'week' || uw === 'month' || uw === 'quarter' || uw === 'year') {
+        scope = snapNow(uw);
+        unit = uw;
+        consumed = 1;
+    }
+    else {
+        const inner = ruleLastThisNext(tokens, at, ctx) ??
+            ruleBareYear(tokens, at, ctx) ??
+            ruleCalendarDate(tokens, at, ctx);
+        if (inner && inner.role === 'date') {
+            unit = halfScopeUnit(inner.expr);
+            if (unit) {
+                scope = inner.expr;
+                consumed = inner.consumed;
+            }
+        }
+    }
+    if (!scope || !unit)
+        return undefined;
+    // Fixed split, deliberately not reference-clamped (unlike mod
+    // 'start'/'end'): "the first half of the year" is Jan–Jun regardless of
+    // today. Midpoints: year +6 months, quarter +45 days, month +15 days
+    // (the 16th), week +84 hours.
+    const startPoint = { op: 'snap', base: scope, unit, edge: 'start' };
+    const endPoint = { op: 'snap', base: scope, unit, edge: 'end' };
+    const mid = unit === 'year'
+        ? { op: 'offset', base: startPoint, amount: 6, unit: 'month' }
+        : unit === 'quarter'
+            ? { op: 'offset', base: startPoint, amount: 45, unit: 'day' }
+            : unit === 'month'
+                ? { op: 'offset', base: startPoint, amount: 15, unit: 'day' }
+                : { op: 'offset', base: startPoint, amount: 84, unit: 'hour' };
+    const expr = which === 1
+        ? { op: 'between', start: startPoint, end: mid }
+        : { op: 'between', start: mid, end: endPoint };
+    return { expr, consumed: at + consumed - i, confidence: 1, role: 'date' };
+};
 const REL_SYNONYMS = {
     last: 'last', previous: 'last', prior: 'last',
     this: 'this', current: 'this', present: 'this', that: 'this',
@@ -1164,6 +1291,33 @@ const ruleUnitAfterNext = (tokens, i) => {
         return undefined;
     return { expr: snapOffset(2, unit), consumed: 3, confidence: 1, role: 'date' };
 };
+/** "[the] <weekday> before last" → two occurrences back; "the week before last" → two units back (#21). */
+const ruleBeforeLast = (tokens, i) => {
+    let at = i;
+    if (word(tokens[at]) === 'the')
+        at += 1;
+    const w = word(tokens[at]);
+    if (w === undefined)
+        return undefined;
+    if (word(tokens[at + 1]) !== 'before' || word(tokens[at + 2]) !== 'last')
+        return undefined;
+    const consumed = at + 3 - i;
+    const weekday = WEEKDAY_WORDS[w];
+    if (weekday) {
+        // Strict occurrence counting: the second one strictly in the past.
+        return {
+            expr: { op: 'seek', base: NOW, dir: 'prev', target: { kind: 'weekday', weekday }, n: 2 },
+            consumed,
+            confidence: 1,
+            role: 'date',
+        };
+    }
+    const unit = w !== 'night' ? UNIT_WORDS[w] : undefined;
+    if (unit && unit !== 'second' && unit !== 'minute' && unit !== 'hour') {
+        return { expr: snapOffset(-2, unit), consumed, confidence: 1, role: 'date' };
+    }
+    return undefined;
+};
 /** "last/past/previous N units" → span backwards; "the past week" → trailing 7 days. */
 const rulePastN = (tokens, i) => {
     const w = word(tokens[i]);
@@ -1440,16 +1594,57 @@ const ruleWeekendOf = (tokens, i, ctx) => {
     if (word(tokens[at]) !== 'weekend' || word(tokens[at + 1]) !== 'of')
         return undefined;
     at += 2;
-    const inner = ruleHoliday(tokens, at, ctx) ?? ruleCalendarDate(tokens, at, ctx);
+    // Holidays keep the long-weekend reading: Saturday before through the end
+    // of the holiday ("Memorial Day weekend" = Sat–Mon).
+    const holiday = ruleHoliday(tokens, at, ctx);
+    if (holiday && holiday.role === 'date') {
+        return {
+            expr: {
+                op: 'between',
+                start: { op: 'seek', base: holiday.expr, dir: 'prev', target: { kind: 'weekday', weekday: 'sat' }, n: 1 },
+                end: { op: 'snap', base: holiday.expr, unit: 'day', edge: 'end' },
+            },
+            consumed: at + holiday.consumed - i,
+            confidence: 0.95,
+            role: 'date',
+        };
+    }
+    if (word(tokens[at]) === 'the')
+        at += 1; // "the weekend of the 18th"
+    const inner = ruleCalendarDate(tokens, at, ctx);
     if (!inner || inner.role !== 'date')
         return undefined;
+    let consumed = at + inner.consumed - i;
+    // "the weekend of July 18th and 19th": the conjunct names the weekend's
+    // other day — absorb it (#22).
+    const andAt = at + inner.consumed;
+    if (word(tokens[andAt]) === 'and') {
+        const t = tokens[andAt + 1];
+        if (t?.type === 'number' && t.ordinal && t.value >= 1 && t.value <= 31) {
+            consumed = andAt + 2 - i;
+        }
+        else {
+            const ord = readOrdinalDayWord(tokens, andAt + 1);
+            if (ord)
+                consumed = andAt + 1 + ord.consumed - i;
+        }
+    }
+    // The Sat–Sun weekend containing the date, or the following one for a
+    // midweek date: the first Saturday on-or-after (date − 1 day), so a
+    // Sunday still maps back to its own weekend (#22).
     return {
         expr: {
-            op: 'between',
-            start: { op: 'seek', base: inner.expr, dir: 'prev', target: { kind: 'weekday', weekday: 'sat' }, n: 1 },
-            end: { op: 'snap', base: inner.expr, unit: 'day', edge: 'end' },
+            op: 'span',
+            anchor: {
+                op: 'seek',
+                base: { op: 'offset', base: inner.expr, amount: -2, unit: 'day' },
+                dir: 'next',
+                target: { kind: 'weekday', weekday: 'sat' },
+                n: 1,
+            },
+            amount: { days: 2 },
         },
-        consumed: at + inner.consumed - i,
+        consumed,
         confidence: 0.95,
         role: 'date',
     };
@@ -2404,6 +2599,25 @@ const ruleClockTime = (tokens, i, ctx) => {
                 role: 'time',
             };
         }
+        // Day-shifting period phrases: "10 last night", "8 yesterday morning",
+        // "5 tomorrow afternoon" (#10). Emit the bare hour with meridiem
+        // 'unknown' and stop — the following day-part matches separately and the
+        // refiner merges them, with the period supplying the meridiem and the
+        // deictic supplying the day shift. Same noun-guard as "this <period>":
+        // "the count was 4 last night" keeps the period's range reading.
+        const relNext = word(tokens[i + hn.consumed]);
+        const isDayShifter = relNext !== undefined &&
+            (REL_SYNONYMS[relNext] !== undefined ||
+                relNext === 'yesterday' || relNext === 'tomorrow' || relNext === 'today');
+        const relPeriodWord = isDayShifter ? word(tokens[i + hn.consumed + 1]) : undefined;
+        if (allowThis && relPeriodWord !== undefined && PERIOD_WORDS[relPeriodWord]) {
+            return {
+                expr: { op: 'literal', time: { hour: hn.value, meridiem: 'unknown' } },
+                consumed: hn.consumed,
+                confidence: 0.95,
+                role: 'time',
+            };
+        }
         if (['at', 'from', 'around', 'about'].includes(word(tokens[i - 1]) ?? '')) {
             return {
                 expr: { op: 'literal', time: { hour: hn.value, meridiem: 'unknown' } },
@@ -2696,34 +2910,43 @@ const ruleAllUnit = (tokens, i) => {
     return { expr: { op: 'amount', amount: amountFor(unit, 1) }, consumed: 2, confidence: 0.9, role: 'duration' };
 };
 /** Rules in priority order (first match at a position wins ties by length then order). */
-export const EN_RULES = [
-    ruleRange,
-    ruleWeekOf,
-    ruleNthWeekdayOf,
-    ruleDayOfScope,
-    ruleWeekendOf,
-    ruleHoliday,
-    ruleEarlyLate,
-    ruleEndOf,
-    ruleDeicticDay,
-    ruleWithin,
-    ruleNAfterDate,
-    ruleUnitAfterNext,
-    rulePastN,
-    ruleNextN,
-    ruleTheNPastNext,
-    ruleTheUnit,
-    ruleLastThisNext,
-    ruleAgoIn,
-    ruleDuration,
-    ruleFractionDuration,
-    ruleAllUnit,
-    ruleDecadeCentury,
-    ruleBareYear,
-    ruleCalendarDate,
-    ruleClockTime,
-    ruleWeekdayDay,
-    ruleWeekdayAlone,
-    rulePeriodAlone,
-    ruleNow,
+/**
+ * Built-in English rules with stable public names (docs/extending.md).
+ * Order matters: the scanner prefers longer matches, then higher confidence,
+ * then earlier list position — so names are also the disable/override handle.
+ */
+export const EN_RULE_ENTRIES = [
+    { name: 'range', rule: ruleRange },
+    { name: 'open-range', rule: ruleOpenRange },
+    { name: 'week-of', rule: ruleWeekOf },
+    { name: 'nth-weekday-of', rule: ruleNthWeekdayOf },
+    { name: 'day-of-scope', rule: ruleDayOfScope },
+    { name: 'weekend-of', rule: ruleWeekendOf },
+    { name: 'holiday', rule: ruleHoliday },
+    { name: 'early-late', rule: ruleEarlyLate },
+    { name: 'half-of', rule: ruleHalfOf },
+    { name: 'end-of', rule: ruleEndOf },
+    { name: 'deictic-day', rule: ruleDeicticDay },
+    { name: 'within', rule: ruleWithin },
+    { name: 'n-after-date', rule: ruleNAfterDate },
+    { name: 'unit-after-next', rule: ruleUnitAfterNext },
+    { name: 'before-last', rule: ruleBeforeLast },
+    { name: 'past-n', rule: rulePastN },
+    { name: 'next-n', rule: ruleNextN },
+    { name: 'the-n-past-next', rule: ruleTheNPastNext },
+    { name: 'the-unit', rule: ruleTheUnit },
+    { name: 'last-this-next', rule: ruleLastThisNext },
+    { name: 'ago-in', rule: ruleAgoIn },
+    { name: 'duration', rule: ruleDuration },
+    { name: 'fraction-duration', rule: ruleFractionDuration },
+    { name: 'all-unit', rule: ruleAllUnit },
+    { name: 'decade-century', rule: ruleDecadeCentury },
+    { name: 'bare-year', rule: ruleBareYear },
+    { name: 'calendar-date', rule: ruleCalendarDate },
+    { name: 'clock-time', rule: ruleClockTime },
+    { name: 'weekday-day', rule: ruleWeekdayDay },
+    { name: 'weekday-alone', rule: ruleWeekdayAlone },
+    { name: 'period-alone', rule: rulePeriodAlone },
+    { name: 'now', rule: ruleNow },
 ];
+export const EN_RULES = EN_RULE_ENTRIES.map((e) => e.rule);

package/dist/parse/es.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from './en.js';
+import { type LatinLexicon } from './latin.js';
+export declare const ES_LEXICON: LatinLexicon;
+export declare const ES_RULE_ENTRIES: {
+    name: string;
+    rule: Rule;
+}[];
+/** Connector words allowed between merged date & time parts. */
+export declare const ES_CONNECTORS: string[];