nl2time 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { TimeContext, ConfigError, type TimeContextOptions, type DateOrder, type Bias, type NextWeekdayPolicy, type PartialPeriodPolicy, } from './context.js';
+export type { TimeExpr, Grain, Unit, Weekday, DayPeriod, CalendarAmount, Mod, Target, PartialDate, PartialTime, } from './ir/types.js';
+export { IR_VERSION } from './ir/types.js';
+export { validateExpr, IRValidationError } from './ir/validate.js';
+export { resolve, resolveOne, NotResolvableError, AmbiguityError, type TimeValue, type Resolution, } from './engine/resolve.js';
+export { parse, type ParseResult, type ParseMatch } from './parse/index.js';
+export { describe, type Description, type DescribeOptions, type Framing, } from './describe/index.js';
+export { Temporal } from './clock/index.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { TimeContext, ConfigError, } from './context.js';
+export { IR_VERSION } from './ir/types.js';
+export { validateExpr, IRValidationError } from './ir/validate.js';
+export { resolve, resolveOne, NotResolvableError, AmbiguityError, } from './engine/resolve.js';
+export { parse } from './parse/index.js';
+export { describe, } from './describe/index.js';
+export { Temporal } from './clock/index.js';

package/dist/ir/types.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The nl2time intermediate representation (IR).
+ *
+ * A TimeExpr is a small, JSON-serializable operator tree over timeline
+ * intervals. Both directions of the library meet here: parsing produces a
+ * TimeExpr, and describe() selects a TimeExpr before rendering it. Resolution
+ * of a TimeExpr against a TimeContext is deterministic.
+ *
+ * The IR is language-neutral: the normative spec is schema/timeexpr.schema.json
+ * plus docs/ir-spec.md, and ports (e.g. Python) implement the same semantics.
+ */
+export type Grain = 'instant' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Units usable in offsets/snaps — every grain except the zero-width 'instant'. */
+export type Unit = Exclude<Grain, 'instant'>;
+export type Weekday = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+/** CLDR-style flexible day periods (boundaries come from locale data). */
+export type DayPeriod = 'morning' | 'afternoon' | 'evening' | 'night';
+/**
+ * A calendar amount with unit-preserving fields ("2 months" is not a number of
+ * seconds). Fields may be negative ("the past 3 days" is days: -3).
+ */
+export interface CalendarAmount {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+}
+/** Approximation / edge channel, after TIMEX3's `mod`: "early July", "around 5". */
+export type Mod = 'approx' | 'start' | 'mid' | 'end';
+/** What a `seek` navigates to. */
+export type Target = {
+    kind: 'weekday';
+    weekday: Weekday;
+} | {
+    kind: 'month';
+    month: number;
+} | {
+    kind: 'dayPeriod';
+    period: DayPeriod;
+} | {
+    kind: 'unit';
+    unit: Unit;
+};
+/**
+ * Partial civil components. Only components the source text asserted are
+ * present (chrono-node's known-vs-implied insight); missing components are
+ * completed at resolution time under context policy, never defaulted here.
+ */
+export interface PartialDate {
+    year?: number;
+    month?: number;
+    day?: number;
+}
+export interface PartialTime {
+    hour?: number;
+    minute?: number;
+    second?: number;
+    /** 'unknown' marks an ambiguous clock reading ("at 4") → AM/PM candidates. */
+    meridiem?: 'am' | 'pm' | 'unknown';
+}
+interface ModCarrier {
+    mod?: Mod;
+}
+export type TimeExpr = TimeExprBody & ModCarrier;
+export type TimeExprBody = 
+/** The reference instant from the TimeContext. */
+{
+    op: 'now';
+}
+/** Civil components asserted by the text; optionally a day period. */
+ | {
+    op: 'literal';
+    date?: PartialDate;
+    time?: PartialTime;
+    dayPeriod?: DayPeriod;
+}
+/** Calendar offset: offset(now, -1, 'week') is "one week before now". */
+ | {
+    op: 'offset';
+    base: TimeExpr;
+    amount: number;
+    unit: Unit;
+}
+/**
+ * Snap to the containing unit interval: snap(x, 'week') is the whole week
+ * containing x (honoring the context week start). edge collapses to a point.
+ */
+ | {
+    op: 'snap';
+    base: TimeExpr;
+    unit: Unit;
+    edge?: 'start' | 'end';
+}
+/**
+ * Anchored span: span(now, {days: -3}) is the 3 days ending at now.
+ * Positive amounts extend forward from the anchor start.
+ */
+ | {
+    op: 'span';
+    anchor: TimeExpr;
+    amount: CalendarAmount;
+    business?: boolean;
+} | {
+    op: 'between';
+    start: TimeExpr;
+    end: TimeExpr;
+}
+/**
+ * Directed calendar navigation: seek(now, 'next', weekday tue) is "next
+ * Tuesday" (semantics of 'next' controlled by context nextWeekday policy);
+ * seek(marchExpr, 'next', weekday mon, 2) is "the 2nd Monday of March".
+ */
+ | {
+    op: 'seek';
+    base: TimeExpr;
+    dir: 'next' | 'prev' | 'nearest';
+    target: Target;
+    n?: number;
+}
+/** Constraint intersection: "Tuesday" ∩ "morning" (SCATE-style). */
+ | {
+    op: 'intersect';
+    parts: TimeExpr[];
+}
+/** An exact elapsed duration ("for 90 minutes"). ISO-8601 duration string. */
+ | {
+    op: 'duration';
+    iso: string;
+}
+/** A calendar amount as a value in its own right ("2 months"). */
+ | {
+    op: 'amount';
+    amount: CalendarAmount;
+}
+/**
+ * A named holiday, resolved by the engine's holiday table (fixed-date,
+ * nth-weekday, or computed — Easter). Without a year: candidate occurrences
+ * around the reference, ordered by bias/dir.
+ */
+ | {
+    op: 'holiday';
+    name: HolidayName;
+    year?: number;
+    dir?: 'prev' | 'next';
+}
+/**
+ * Recurrence — representable and serializable in v1, resolvable in v2.
+ * "every Tuesday" = { every: 'week', filter: seek weekday tue }.
+ */
+ | {
+    op: 'recur';
+    every: Unit;
+    filter?: TimeExpr;
+};
+export type HolidayName = 'black-friday' | 'earth-day' | 'st-patricks' | 'workers-day' | 'new-year' | 'new-year-eve' | 'valentines' | 'easter' | 'halloween' | 'thanksgiving' | 'christmas' | 'christmas-eve' | 'independence-day' | 'labor-day' | 'memorial-day' | 'mothers-day' | 'fathers-day';
+export declare const HOLIDAY_NAMES: readonly HolidayName[];
+/** Current IR schema version, embedded when serializing. */
+export declare const IR_VERSION = 1;
+export declare const UNITS: readonly Unit[];
+export declare const WEEKDAYS: readonly Weekday[];
+export declare const DAY_PERIODS: readonly DayPeriod[];
+export {};

package/dist/ir/types.js

@@ -0,0 +1,31 @@
+/**
+ * The nl2time intermediate representation (IR).
+ *
+ * A TimeExpr is a small, JSON-serializable operator tree over timeline
+ * intervals. Both directions of the library meet here: parsing produces a
+ * TimeExpr, and describe() selects a TimeExpr before rendering it. Resolution
+ * of a TimeExpr against a TimeContext is deterministic.
+ *
+ * The IR is language-neutral: the normative spec is schema/timeexpr.schema.json
+ * plus docs/ir-spec.md, and ports (e.g. Python) implement the same semantics.
+ */
+export const HOLIDAY_NAMES = [
+    'black-friday', 'earth-day', 'st-patricks', 'workers-day',
+    'new-year', 'new-year-eve', 'valentines', 'easter', 'halloween',
+    'thanksgiving', 'christmas', 'christmas-eve', 'independence-day',
+    'labor-day', 'memorial-day', 'mothers-day', 'fathers-day',
+];
+/** Current IR schema version, embedded when serializing. */
+export const IR_VERSION = 1;
+export const UNITS = [
+    'second',
+    'minute',
+    'hour',
+    'day',
+    'week',
+    'month',
+    'quarter',
+    'year',
+];
+export const WEEKDAYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+export const DAY_PERIODS = ['morning', 'afternoon', 'evening', 'night'];

package/dist/ir/validate.d.ts

@@ -0,0 +1,11 @@
+import { type TimeExpr } from './types.js';
+export declare class IRValidationError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Structural validation of untrusted input (LLM output, stored IR, network)
+ * into a typed TimeExpr. Mirrors schema/timeexpr.schema.json; the JSON Schema
+ * is the language-neutral spec, this is the fast in-process check.
+ */
+export declare function validateExpr(input: unknown, path?: string): TimeExpr;

package/dist/ir/validate.js

@@ -0,0 +1,205 @@
+import { DAY_PERIODS, HOLIDAY_NAMES, UNITS, WEEKDAYS, } from './types.js';
+export class IRValidationError extends Error {
+    path;
+    constructor(message, path) {
+        super(`${path}: ${message}`);
+        this.path = path;
+        this.name = 'IRValidationError';
+    }
+}
+const MODS = ['approx', 'start', 'mid', 'end'];
+const DIRS = ['next', 'prev', 'nearest'];
+/**
+ * Structural validation of untrusted input (LLM output, stored IR, network)
+ * into a typed TimeExpr. Mirrors schema/timeexpr.schema.json; the JSON Schema
+ * is the language-neutral spec, this is the fast in-process check.
+ */
+export function validateExpr(input, path = '$') {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new IRValidationError('expected an object', path);
+    }
+    const obj = input;
+    if ('mod' in obj && obj.mod !== undefined && !MODS.includes(obj.mod)) {
+        throw new IRValidationError(`invalid mod ${JSON.stringify(obj.mod)}`, path);
+    }
+    const op = obj.op;
+    switch (op) {
+        case 'now':
+            return obj;
+        case 'literal': {
+            if (obj.date !== undefined)
+                validatePartialDate(obj.date, `${path}.date`);
+            if (obj.time !== undefined)
+                validatePartialTime(obj.time, `${path}.time`);
+            if (obj.dayPeriod !== undefined && !DAY_PERIODS.includes(obj.dayPeriod)) {
+                throw new IRValidationError(`invalid dayPeriod`, `${path}.dayPeriod`);
+            }
+            if (obj.date === undefined && obj.time === undefined && obj.dayPeriod === undefined) {
+                throw new IRValidationError('literal requires date, time, or dayPeriod', path);
+            }
+            return obj;
+        }
+        case 'offset': {
+            validateExpr(obj.base, `${path}.base`);
+            requireInt(obj.amount, `${path}.amount`);
+            requireUnit(obj.unit, `${path}.unit`);
+            return obj;
+        }
+        case 'snap': {
+            validateExpr(obj.base, `${path}.base`);
+            requireUnit(obj.unit, `${path}.unit`);
+            if (obj.edge !== undefined && obj.edge !== 'start' && obj.edge !== 'end') {
+                throw new IRValidationError('edge must be "start" or "end"', `${path}.edge`);
+            }
+            return obj;
+        }
+        case 'span': {
+            validateExpr(obj.anchor, `${path}.anchor`);
+            validateAmount(obj.amount, `${path}.amount`);
+            if (obj.business !== undefined && typeof obj.business !== 'boolean') {
+                throw new IRValidationError('business must be boolean', `${path}.business`);
+            }
+            return obj;
+        }
+        case 'between': {
+            validateExpr(obj.start, `${path}.start`);
+            validateExpr(obj.end, `${path}.end`);
+            return obj;
+        }
+        case 'seek': {
+            validateExpr(obj.base, `${path}.base`);
+            if (!DIRS.includes(obj.dir)) {
+                throw new IRValidationError('dir must be next|prev|nearest', `${path}.dir`);
+            }
+            validateTarget(obj.target, `${path}.target`);
+            if (obj.n !== undefined)
+                requireInt(obj.n, `${path}.n`);
+            return obj;
+        }
+        case 'intersect': {
+            if (!Array.isArray(obj.parts) || obj.parts.length < 2) {
+                throw new IRValidationError('intersect requires >= 2 parts', `${path}.parts`);
+            }
+            obj.parts.forEach((p, i) => validateExpr(p, `${path}.parts[${i}]`));
+            return obj;
+        }
+        case 'duration': {
+            if (typeof obj.iso !== 'string' || !/^-?P/.test(obj.iso)) {
+                throw new IRValidationError('duration requires an ISO-8601 string', `${path}.iso`);
+            }
+            return obj;
+        }
+        case 'amount': {
+            validateAmount(obj.amount, `${path}.amount`);
+            return obj;
+        }
+        case 'holiday': {
+            if (!HOLIDAY_NAMES.includes(obj.name)) {
+                throw new IRValidationError(`unknown holiday ${JSON.stringify(obj.name)}`, `${path}.name`);
+            }
+            if (obj.year !== undefined)
+                requireInt(obj.year, `${path}.year`);
+            if (obj.dir !== undefined && obj.dir !== 'prev' && obj.dir !== 'next') {
+                throw new IRValidationError('dir must be prev|next', `${path}.dir`);
+            }
+            return obj;
+        }
+        case 'recur': {
+            requireUnit(obj.every, `${path}.every`);
+            if (obj.filter !== undefined)
+                validateExpr(obj.filter, `${path}.filter`);
+            return obj;
+        }
+        default:
+            throw new IRValidationError(`unknown op ${JSON.stringify(op)}`, path);
+    }
+}
+function requireInt(v, path) {
+    if (typeof v !== 'number' || !Number.isInteger(v)) {
+        throw new IRValidationError('expected an integer', path);
+    }
+}
+function requireUnit(v, path) {
+    if (!UNITS.includes(v)) {
+        throw new IRValidationError(`invalid unit ${JSON.stringify(v)}`, path);
+    }
+}
+function validateTarget(v, path) {
+    if (typeof v !== 'object' || v === null) {
+        throw new IRValidationError('expected a target object', path);
+    }
+    const t = v;
+    switch (t.kind) {
+        case 'weekday':
+            if (!WEEKDAYS.includes(t.weekday)) {
+                throw new IRValidationError('invalid weekday', `${path}.weekday`);
+            }
+            return;
+        case 'month':
+            requireInt(t.month, `${path}.month`);
+            if (t.month < 1 || t.month > 12) {
+                throw new IRValidationError('month out of range', `${path}.month`);
+            }
+            return;
+        case 'dayPeriod':
+            if (!DAY_PERIODS.includes(t.period)) {
+                throw new IRValidationError('invalid dayPeriod', `${path}.period`);
+            }
+            return;
+        case 'unit':
+            requireUnit(t.unit, `${path}.unit`);
+            return;
+        default:
+            throw new IRValidationError('target kind must be weekday|month|dayPeriod|unit', path);
+    }
+}
+const AMOUNT_FIELDS = ['years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds'];
+function validateAmount(v, path) {
+    if (typeof v !== 'object' || v === null) {
+        throw new IRValidationError('expected a calendar amount object', path);
+    }
+    const keys = Object.keys(v);
+    if (keys.length === 0)
+        throw new IRValidationError('amount must have at least one field', path);
+    for (const k of keys) {
+        if (!AMOUNT_FIELDS.includes(k))
+            throw new IRValidationError(`unknown field "${k}"`, path);
+        requireInt(v[k], `${path}.${k}`);
+    }
+}
+function validatePartialDate(v, path) {
+    if (typeof v !== 'object' || v === null)
+        throw new IRValidationError('expected object', path);
+    const d = v;
+    for (const k of Object.keys(d)) {
+        if (!['year', 'month', 'day'].includes(k)) {
+            throw new IRValidationError(`unknown field "${k}"`, path);
+        }
+        requireInt(d[k], `${path}.${k}`);
+    }
+    if (typeof d.month === 'number' && (d.month < 1 || d.month > 12)) {
+        throw new IRValidationError('month out of range', `${path}.month`);
+    }
+    if (typeof d.day === 'number' && (d.day < 1 || d.day > 31)) {
+        throw new IRValidationError('day out of range', `${path}.day`);
+    }
+}
+function validatePartialTime(v, path) {
+    if (typeof v !== 'object' || v === null)
+        throw new IRValidationError('expected object', path);
+    const t = v;
+    for (const k of Object.keys(t)) {
+        if (!['hour', 'minute', 'second', 'meridiem'].includes(k)) {
+            throw new IRValidationError(`unknown field "${k}"`, path);
+        }
+    }
+    if (t.hour !== undefined)
+        requireInt(t.hour, `${path}.hour`);
+    if (t.minute !== undefined)
+        requireInt(t.minute, `${path}.minute`);
+    if (t.second !== undefined)
+        requireInt(t.second, `${path}.second`);
+    if (t.meridiem !== undefined && !['am', 'pm', 'unknown'].includes(t.meridiem)) {
+        throw new IRValidationError('meridiem must be am|pm|unknown', `${path}.meridiem`);
+    }
+}

package/dist/llm/index.d.ts

@@ -0,0 +1,26 @@
+import type { TimeContext } from '../context.js';
+import { type ParseResult } from '../parse/index.js';
+/** The TimeExpr JSON Schema — pass to constrained decoding / tool definitions. */
+export declare function irJsonSchema(): object;
+export interface CtxSummary {
+    referenceInstant: string;
+    timeZone: string;
+    locale: string;
+    weekStart: string;
+    localDateTime: string;
+}
+export declare function ctxSummary(ctx: TimeContext): CtxSummary;
+/**
+ * A prompt for translating one natural-language expression into a TimeExpr.
+ * Inject alongside irJsonSchema() via your provider's structured-output
+ * mechanism.
+ */
+export declare function buildPrompt(text: string, ctx: TimeContext): string;
+export type LLMFallback = (text: string, summary: CtxSummary) => Promise<unknown>;
+/**
+ * parse() with an LLM fallback: rules first; if no confident rule match, the
+ * fallback is asked for a TimeExpr, which is schema-validated before use.
+ * Invalid LLM output is dropped (the result just has no matches) — the engine
+ * never guesses.
+ */
+export declare function parseWithFallback(text: string, ctx: TimeContext, fallback: LLMFallback): Promise<ParseResult>;

package/dist/llm/index.js

@@ -0,0 +1,89 @@
+/**
+ * LLM adapter helpers. nl2time never makes network calls: the application
+ * supplies a fallback function (its own LLM client); this module supplies the
+ * IR JSON schema for constrained decoding, the prompt (which always carries
+ * the clock), and strict validation of whatever comes back. The LLM can only
+ * ever emit a TimeExpr — never a concrete date — so all arithmetic stays in
+ * the deterministic engine.
+ */
+import { createRequire } from 'node:module';
+import { validateExpr } from '../ir/validate.js';
+import { parse } from '../parse/index.js';
+const require = createRequire(import.meta.url);
+/** The TimeExpr JSON Schema — pass to constrained decoding / tool definitions. */
+export function irJsonSchema() {
+    return require('../../schema/timeexpr.schema.json');
+}
+export function ctxSummary(ctx) {
+    const z = ctx.zonedNow;
+    return {
+        referenceInstant: ctx.now.toString(),
+        timeZone: ctx.timeZone,
+        locale: ctx.locale,
+        weekStart: ctx.weekStart,
+        localDateTime: z.toPlainDateTime().toString(),
+    };
+}
+/**
+ * A prompt for translating one natural-language expression into a TimeExpr.
+ * Inject alongside irJsonSchema() via your provider's structured-output
+ * mechanism.
+ */
+export function buildPrompt(text, ctx) {
+    const s = ctxSummary(ctx);
+    return [
+        'Translate the natural-language time expression into a TimeExpr JSON object',
+        'conforming to the provided schema. Emit ONLY the symbolic expression —',
+        'never compute concrete dates yourself; the deterministic engine resolves',
+        'the expression against the reference context.',
+        '',
+        `Reference context (for disambiguation only):`,
+        `- reference instant (UTC): ${s.referenceInstant}`,
+        `- user local date/time: ${s.localDateTime} (${s.timeZone})`,
+        `- locale: ${s.locale}, week starts on: ${s.weekStart}`,
+        '',
+        'Guidance:',
+        '- "last week" → {"op":"snap","base":{"op":"offset","base":{"op":"now"},"amount":-1,"unit":"week"},"unit":"week"}',
+        '- "the last 3 days" → {"op":"span","anchor":{"op":"now"},"amount":{"days":-3}}',
+        '- "next Tuesday at 4" → {"op":"intersect","parts":[{"op":"seek","base":{"op":"now"},"dir":"next","target":{"kind":"weekday","weekday":"tue"}},{"op":"literal","time":{"hour":4,"meridiem":"unknown"}}]}',
+        '- Ambiguous readings stay symbolic: keep meridiem "unknown", omit unstated date components.',
+        '',
+        `Expression: ${JSON.stringify(text)}`,
+    ].join('\n');
+}
+/**
+ * parse() with an LLM fallback: rules first; if no confident rule match, the
+ * fallback is asked for a TimeExpr, which is schema-validated before use.
+ * Invalid LLM output is dropped (the result just has no matches) — the engine
+ * never guesses.
+ */
+export async function parseWithFallback(text, ctx, fallback) {
+    const ruleResult = parse(text, ctx);
+    if (ruleResult.matches.length > 0)
+        return ruleResult;
+    let raw;
+    try {
+        raw = await fallback(text, ctxSummary(ctx));
+    }
+    catch {
+        return ruleResult;
+    }
+    try {
+        const expr = validateExpr(raw);
+        return {
+            matches: [
+                {
+                    text,
+                    start: 0,
+                    end: text.length,
+                    expr,
+                    confidence: 0.6,
+                    source: 'llm',
+                },
+            ],
+        };
+    }
+    catch {
+        return ruleResult;
+    }
+}

package/dist/parse/en.d.ts

@@ -0,0 +1,18 @@
+/**
+ * English rule set. Each rule inspects the token stream at a position and, on
+ * match, emits a TimeExpr plus the number of tokens consumed. Rules are pure
+ * pattern → IR translators; all resolution semantics live in the engine.
+ */
+import type { TimeContext } from '../context.js';
+import type { TimeExpr } from '../ir/types.js';
+import type { Token } from './tokenizer.js';
+export interface RuleMatch {
+    expr: TimeExpr;
+    consumed: number;
+    confidence: number;
+    /** Marks results that combine with a date ("at 4pm") or a time ("yesterday"). */
+    role: 'date' | 'time' | 'datetime' | 'duration';
+}
+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). */
+export declare const EN_RULES: readonly Rule[];