nl2time 0.1.0

package/dist/parse/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Recognition: text → TimeExpr matches. Pure with respect to the reference
+ * instant — parsing uses ctx.locale/dateOrder only; ctx.now matters at
+ * resolve() time. (Recognition/resolution separation, docs/design.md §4.)
+ */
+import type { TimeContext } from '../context.js';
+import type { TimeExpr } from '../ir/types.js';
+export interface ParseMatch {
+    /** The matched source text span. */
+    text: string;
+    start: number;
+    end: number;
+    expr: TimeExpr;
+    confidence: number;
+    source: 'rules' | 'llm';
+}
+export interface ParseResult {
+    matches: ParseMatch[];
+}
+export declare function parse(text: string, ctx: TimeContext): ParseResult;

package/dist/parse/index.js

@@ -0,0 +1,230 @@
+import { EN_RULES } from './en.js';
+import { tokenize } from './tokenizer.js';
+const CONNECTORS = ['at', 'on', 'in', 'of', 'the', 'for', 'from', 'around', 'about', '-'];
+export function parse(text, ctx) {
+    const tokens = tokenize(text);
+    const raw = [];
+    let i = 0;
+    while (i < tokens.length) {
+        let best;
+        for (const rule of EN_RULES) {
+            const m = rule(tokens, i, ctx);
+            if (!m)
+                continue;
+            if (!best || m.consumed > best.consumed || (m.consumed === best.consumed && m.confidence > best.confidence)) {
+                best = { ...m, tokenStart: i, tokenEnd: i + m.consumed };
+            }
+        }
+        if (best) {
+            raw.push(best);
+            i = best.tokenEnd;
+        }
+        else {
+            i += 1;
+        }
+    }
+    // Merge to fixpoint: [date, duration, time] needs two passes.
+    let merged = mergeAdjacent(raw, tokens);
+    for (let pass = 0; pass < 2; pass += 1) {
+        const again = mergeAdjacent(merged, tokens);
+        if (again.length === merged.length)
+            break;
+        merged = again;
+    }
+    const matches = merged
+        .filter((m) => m.confidence >= 0.5)
+        .map((m) => {
+        const startTok = tokens[m.tokenStart];
+        const endTok = tokens[m.tokenEnd - 1];
+        return {
+            text: text.slice(startTok.start, endTok.end),
+            start: startTok.start,
+            end: endTok.end,
+            expr: m.expr,
+            confidence: m.confidence,
+            source: 'rules',
+        };
+    });
+    return { matches };
+}
+/**
+ * Refiner: merge a date-ish match with an adjacent time-ish match (optionally
+ * separated by a connector token) into intersect(date, time) — "yesterday at
+ * 9pm", "next Tuesday morning", "May 29 at noon".
+ */
+function mergeAdjacent(matches, tokens) {
+    const out = [];
+    let k = 0;
+    while (k < matches.length) {
+        const cur = matches[k];
+        const next = matches[k + 1];
+        // Anchored span: time + duration ("from 2pm for 2 hours") or duration +
+        // time ("for 2.5 hours from 9") → span(anchor, amount).
+        const spanPair = next &&
+            ((isTimeish(cur.role) && next.role === 'duration' && connectedBy(cur, next, tokens, ['for'])) ||
+                (cur.role === 'duration' && isTimeish(next.role) && connectedBy(cur, next, tokens, ['from', 'starting', 'at'])) ||
+                // "for a week starting tomorrow"
+                (cur.role === 'duration' && next.role === 'date' && connectedBy(cur, next, tokens, ['starting', 'from'])));
+        if (next && spanPair) {
+            const [anchorPart, durPart] = cur.role === 'duration' ? [next, cur] : [cur, next];
+            const amount = amountOf(durPart.expr);
+            if (amount) {
+                out.push({
+                    expr: { op: 'span', anchor: anchorPart.expr, amount },
+                    consumed: next.tokenEnd - cur.tokenStart,
+                    confidence: Math.max(cur.confidence, next.confidence),
+                    // A span anchored at a time-of-day is still time-of-day-ish: it can
+                    // merge with an adjacent date ("14th Feb from 9:30am for 7 hours").
+                    role: anchorPart.role,
+                    tokenStart: cur.tokenStart,
+                    tokenEnd: next.tokenEnd,
+                });
+                k += 2;
+                continue;
+            }
+        }
+        // Week + weekday: "previous week - Monday" → that weekday within the week.
+        if (next &&
+            isWeekExpr(cur.expr) &&
+            next.expr.op === 'seek' &&
+            next.expr.target.kind === 'weekday' &&
+            isAdjacent(cur, next, tokens)) {
+            out.push({
+                expr: { op: 'seek', base: cur.expr, dir: 'next', target: next.expr.target, n: 1 },
+                consumed: next.tokenEnd - cur.tokenStart,
+                confidence: Math.max(cur.confidence, next.confidence),
+                role: 'date',
+                tokenStart: cur.tokenStart,
+                tokenEnd: next.tokenEnd,
+            });
+            k += 2;
+            continue;
+        }
+        if (next && canMerge(cur, next) && isAdjacent(cur, next, tokens)) {
+            const [datePart, timePart] = cur.role === 'time' ? [next, cur] : [cur, next];
+            let dateExpr = datePart.expr;
+            let timeExpr = inferMeridiem(dateExpr, timePart.expr);
+            // A day-period on the date side pushes its meridiem into an explicit
+            // time range and then steps aside: "Monday morning 6-8" is Monday
+            // 06:00–08:00, not clipped to the morning boundaries.
+            if (timeExpr.op === 'between') {
+                const period = findDayPeriod(dateExpr);
+                if (period) {
+                    timeExpr = {
+                        ...timeExpr,
+                        start: forceMeridiem(timeExpr.start, period),
+                        end: forceMeridiem(timeExpr.end, period),
+                    };
+                    dateExpr = stripDayPeriod(dateExpr) ?? dateExpr;
+                }
+            }
+            out.push({
+                expr: { op: 'intersect', parts: [dateExpr, timeExpr] },
+                consumed: next.tokenEnd - cur.tokenStart,
+                confidence: Math.max(cur.confidence, next.confidence),
+                role: 'datetime',
+                tokenStart: cur.tokenStart,
+                tokenEnd: next.tokenEnd,
+            });
+            k += 2;
+            continue;
+        }
+        out.push(cur);
+        k += 1;
+    }
+    return out;
+}
+function canMerge(a, b) {
+    const dateish = (r) => r === 'date' || r === 'datetime';
+    return (dateish(a.role) && b.role === 'time') || (a.role === 'time' && dateish(b.role));
+}
+function isTimeish(role) {
+    return role === 'time' || role === 'datetime';
+}
+function isWeekExpr(expr) {
+    return expr.op === 'snap' && expr.unit === 'week';
+}
+function connectedBy(a, b, tokens, words) {
+    const between = tokens.slice(a.tokenEnd, b.tokenStart);
+    if (between.length > 2)
+        return false;
+    return between.every((t) => t.type === 'word' && (words.includes(t.value) || t.value === 'the'));
+}
+/** Extract a calendar amount from a duration-role expression. */
+function amountOf(expr) {
+    if (expr.op === 'amount')
+        return { ...expr.amount };
+    if (expr.op === 'duration') {
+        const m = expr.iso.match(/^PT(\d+)S$/);
+        if (m)
+            return { seconds: Number(m[1]) };
+    }
+    return undefined;
+}
+/**
+ * "tonight at 10": a day part that carries a day period narrows an ambiguous
+ * clock reading (night/evening/afternoon → pm, morning → am).
+ */
+function inferMeridiem(dateExpr, timeExpr) {
+    if (timeExpr.op !== 'literal' || timeExpr.time?.meridiem !== 'unknown')
+        return timeExpr;
+    const period = findDayPeriod(dateExpr);
+    if (!period)
+        return timeExpr;
+    const hour = timeExpr.time.hour ?? 12;
+    // "tonight around 3" is 3am (small hours belong to the night); "tonight at
+    // 10" is 10pm.
+    const meridiem = period === 'morning' ? 'am' : (period === 'night' || period === 'evening') && hour <= 5 ? 'am' : 'pm';
+    return {
+        ...timeExpr,
+        time: { ...timeExpr.time, meridiem },
+    };
+}
+function forceMeridiem(expr, period) {
+    if (expr.op !== 'literal' || !expr.time || (expr.time.meridiem && expr.time.meridiem !== 'unknown')) {
+        return expr;
+    }
+    const hour = expr.time.hour ?? 12;
+    const meridiem = period === 'morning' ? 'am' : (period === 'night' || period === 'evening') && hour <= 5 ? 'am' : 'pm';
+    return { ...expr, time: { ...expr.time, meridiem } };
+}
+/** Remove day-period literals from an intersect; undefined if nothing remains. */
+function stripDayPeriod(expr) {
+    if (expr.op === 'literal' && expr.dayPeriod && !expr.date && !expr.time)
+        return undefined;
+    if (expr.op === 'intersect') {
+        const parts = expr.parts.map(stripDayPeriod).filter((p) => p !== undefined);
+        if (parts.length === 0)
+            return undefined;
+        if (parts.length === 1)
+            return parts[0];
+        return { ...expr, parts };
+    }
+    return expr;
+}
+function findDayPeriod(expr) {
+    if (expr.op === 'literal' && expr.dayPeriod)
+        return expr.dayPeriod;
+    if (expr.op === 'intersect') {
+        for (const p of expr.parts) {
+            const found = findDayPeriod(p);
+            if (found)
+                return found;
+        }
+    }
+    if (expr.op === 'seek' && expr.target.kind === 'dayPeriod')
+        return expr.target.period;
+    return undefined;
+}
+const REDUNDANT_BETWEEN = new Set([
+    'mon', 'tue', 'tues', 'wed', 'weds', 'thu', 'thur', 'thurs', 'fri', 'sat', 'sun',
+    'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday',
+]);
+function isAdjacent(a, b, tokens) {
+    const between = tokens.slice(a.tokenEnd, b.tokenStart);
+    if (between.length > 2)
+        return false;
+    // A parenthesized weekday between date and time ("May/22 (Tue) 11:30") is
+    // redundant with the date and doesn't block the merge.
+    return between.every((t) => t.type === 'word' && (CONNECTORS.includes(t.value) || REDUNDANT_BETWEEN.has(t.value)));
+}

package/dist/parse/tokenizer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tokenizer for the rule-based parsers. Regexes here are deliberately simple
+ * (character classes and anchors only) so they port to any regex dialect;
+ * everything above this layer is table-driven token matching (docs/porting.md).
+ */
+export type Token = {
+    type: 'word';
+    value: string;
+    start: number;
+    end: number;
+} | {
+    type: 'number';
+    value: number;
+    ordinal: boolean;
+    start: number;
+    end: number;
+} | {
+    type: 'clock';
+    hour: number;
+    minute: number;
+    explicitMinute: boolean;
+    second?: number;
+    meridiem?: 'am' | 'pm';
+    start: number;
+    end: number;
+} | {
+    type: 'numdate';
+    parts: number[];
+    sep: string;
+    start: number;
+    end: number;
+};
+export declare function tokenize(text: string): Token[];

package/dist/parse/tokenizer.js

@@ -0,0 +1,118 @@
+/**
+ * Tokenizer for the rule-based parsers. Regexes here are deliberately simple
+ * (character classes and anchors only) so they port to any regex dialect;
+ * everything above this layer is table-driven token matching (docs/porting.md).
+ */
+const CLOCK_RE = /^(\d{1,2}):(\d{2})(?::(\d{2}))?(am|pm|a|p)?$/;
+const HOUR_MERIDIEM_RE = /^(\d{1,2})(am|pm|a|p)$/;
+const ORDINAL_RE = /^(\d{1,2})(st|nd|rd|th)$/;
+const NUMDATE_RE = /^(\d{1,4})([/\-.])(\d{1,2})(?:\2(\d{1,4}))?$/;
+const NUMBER_RE = /^\d{1,4}$/;
+const RAW_TOKEN_RE = /[a-z0-9:/\-.'~\u00bc\u00bd\u00be]+/gi;
+export function tokenize(text) {
+    const tokens = [];
+    for (const m of text.matchAll(RAW_TOKEN_RE)) {
+        const raw = m[0]
+            .toLowerCase()
+            .replace(/^-(?=\d)/, '') // "(Tue)-11:30" → clock token after paren split
+            .replace(/[.]+$/, '')
+            .replace(/[''`]s$/, '') // "fortnight's" → fortnight
+            .replace(/['']+$/, '') // "workers'" → workers
+            .replace(/^a\.m$/, 'am')
+            .replace(/^p\.m$/, 'pm')
+            .replace(/^(\d{1,2}(?::\d{2})?)\.(am|pm|a|p)$/, '$1$2'); // "9.am" → 9am
+        if (raw === '')
+            continue;
+        const start = m.index;
+        const end = start + m[0].length;
+        // Split dash-joined mixed tokens ("18-dec", "nov-feb", "friday-jun-15")
+        // into parts with explicit "-" connectors so the range machinery sees
+        // them. Pure-numeric joins (11-4, 2014-2018) and "mid-…" stay intact.
+        if (raw.includes('-') && !raw.startsWith('mid')) {
+            const segments = raw.split('-');
+            // Word-ish segments include month/year compounds ("dec/2018"); pure
+            // digit-with-suffix segments like "4.30pm" must NOT count, so joined
+            // time ranges stay intact.
+            const alpha = segments.filter((s) => /^[a-z']{2,}(\/\d{1,4})?$/.test(s)).length;
+            const numeric = segments.filter((s) => /^[\d.:]+$/.test(s)).length;
+            const splittable = segments.length >= 2 &&
+                segments.every((s) => s.length > 0) &&
+                alpha + numeric === segments.length &&
+                alpha > 0;
+            if (splittable) {
+                for (const [si, seg] of segments.entries()) {
+                    if (si > 0)
+                        tokens.push({ type: 'word', value: '-', start, end });
+                    pushToken(tokens, seg, start, end);
+                }
+                continue;
+            }
+        }
+        pushToken(tokens, raw, start, end);
+    }
+    return tokens;
+}
+function pushToken(tokens, raw, start, end) {
+    let match = raw.match(CLOCK_RE);
+    if (match) {
+        const token = {
+            type: 'clock',
+            hour: Number(match[1]),
+            minute: Number(match[2]),
+            explicitMinute: true,
+            start,
+            end,
+        };
+        if (match[3] !== undefined)
+            token.second = Number(match[3]);
+        if (match[4])
+            token.meridiem = match[4].startsWith('a') ? 'am' : 'pm';
+        tokens.push(token);
+        return;
+    }
+    match = raw.match(HOUR_MERIDIEM_RE);
+    if (match) {
+        tokens.push({
+            type: 'clock',
+            hour: Number(match[1]),
+            minute: 0,
+            explicitMinute: false,
+            meridiem: match[2].startsWith('a') ? 'am' : 'pm',
+            start,
+            end,
+        });
+        return;
+    }
+    match = raw.match(ORDINAL_RE);
+    if (match) {
+        tokens.push({ type: 'number', value: Number(match[1]), ordinal: true, start, end });
+        return;
+    }
+    match = raw.match(NUMDATE_RE);
+    if (match && match[4] !== undefined) {
+        tokens.push({
+            type: 'numdate',
+            parts: [Number(match[1]), Number(match[3]), Number(match[4])],
+            sep: match[2],
+            start,
+            end,
+        });
+        return;
+    }
+    if (match && match[2] === '/') {
+        // Two-part numeric date like 5/29 (only with slash — 5-29 is too odd).
+        tokens.push({
+            type: 'numdate',
+            parts: [Number(match[1]), Number(match[3])],
+            sep: '/',
+            start,
+            end,
+        });
+        return;
+    }
+    if (NUMBER_RE.test(raw)) {
+        tokens.push({ type: 'number', value: Number(raw), ordinal: false, start, end });
+        return;
+    }
+    tokens.push({ type: 'word', value: raw, start, end });
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "nl2time",
+  "version": "0.1.0",
+  "description": "Bidirectional natural language ⇄ date/time: parse expressions like 'last week' into concrete intervals, and describe instants as '9pm last night' — deterministic core, optional LLM assist.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./llm": "./dist/llm/index.js",
+    "./corpus": "./dist/corpus/runner.js"
+  },
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AndyFooBlah/nl2time.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "import:recognizers": "node scripts/import-recognizers.mjs",
+    "baselines": "npm run build && node scripts/update-baselines.mjs",
+    "eval": "npm run build && node scripts/eval.mjs"
+  },
+  "keywords": [
+    "date",
+    "time",
+    "natural-language",
+    "parser",
+    "humanize",
+    "relative-time",
+    "temporal",
+    "llm",
+    "timezone",
+    "locale"
+  ],
+  "dependencies": {
+    "temporal-polyfill": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}