nl2time 0.1.0

package/dist/data/dayPeriods.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLDR flexible day-period boundary rules.
+ *
+ * Source: CLDR supplemental/dayPeriods.json (rule set per language). v1 ships
+ * the English rules; the generator script (issue #7) will widen coverage.
+ * Boundaries are [from, before) in local hours; a period may wrap midnight
+ * (night: 21:00 → 06:00).
+ */
+import type { DayPeriod } from '../ir/types.js';
+export interface DayPeriodRule {
+    period: DayPeriod;
+    /** Start hour (inclusive), local time. */
+    from: number;
+    /** End hour (exclusive). May be < from, meaning the period wraps midnight. */
+    before: number;
+}
+export declare function dayPeriodRules(language: string): readonly DayPeriodRule[];
+export declare function periodForHour(language: string, hour: number): DayPeriod;

package/dist/data/dayPeriods.js

@@ -0,0 +1,24 @@
+const EN_RULES = [
+    { period: 'morning', from: 6, before: 12 },
+    { period: 'afternoon', from: 12, before: 18 },
+    { period: 'evening', from: 18, before: 21 },
+    { period: 'night', from: 21, before: 6 },
+];
+export function dayPeriodRules(language) {
+    // Only 'en' data is bundled so far; other languages fall back to the en
+    // boundaries, which match CLDR's defaults closely enough for v1.
+    void language;
+    return EN_RULES;
+}
+export function periodForHour(language, hour) {
+    for (const rule of dayPeriodRules(language)) {
+        if (rule.from < rule.before) {
+            if (hour >= rule.from && hour < rule.before)
+                return rule.period;
+        }
+        else if (hour >= rule.from || hour < rule.before) {
+            return rule.period;
+        }
+    }
+    return 'night';
+}

package/dist/data/weekData.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLDR supplemental weekData slice (firstDay by territory).
+ *
+ * Source: CLDR supplemental/weekData.json. Territories not listed use the
+ * world default (001): Monday. This file is intended to be regenerated from
+ * CLDR by scripts/generate-cldr.ts (issue #7); the slice below covers the
+ * common territories so v1 behaves correctly for them.
+ */
+import type { Weekday } from '../ir/types.js';
+export declare const DEFAULT_FIRST_DAY: Weekday;
+export declare function firstDayForRegion(region: string | undefined): Weekday;

package/dist/data/weekData.js

@@ -0,0 +1,25 @@
+export const DEFAULT_FIRST_DAY = 'mon';
+const SUN = [
+    'AG', 'AS', 'BD', 'BR', 'BS', 'BT', 'BW', 'BZ', 'CA', 'CO', 'DM', 'DO', 'ET',
+    'GT', 'GU', 'HK', 'HN', 'ID', 'IL', 'IN', 'JM', 'JP', 'KE', 'KH', 'KR', 'LA',
+    'MH', 'MM', 'MO', 'MT', 'MX', 'MZ', 'NI', 'NP', 'PA', 'PE', 'PH', 'PK', 'PR',
+    'PT', 'PY', 'SA', 'SG', 'SV', 'TH', 'TT', 'TW', 'UM', 'US', 'VE', 'VI', 'WS',
+    'YE', 'ZA', 'ZW',
+];
+const SAT = [
+    'AE', 'AF', 'BH', 'DJ', 'DZ', 'EG', 'IQ', 'IR', 'JO', 'KW', 'LY', 'OM', 'QA',
+    'SD', 'SY',
+];
+const FRI = ['MV'];
+export function firstDayForRegion(region) {
+    if (!region)
+        return DEFAULT_FIRST_DAY;
+    const r = region.toUpperCase();
+    if (SUN.includes(r))
+        return 'sun';
+    if (SAT.includes(r))
+        return 'sat';
+    if (FRI.includes(r))
+        return 'fri';
+    return DEFAULT_FIRST_DAY;
+}

package/dist/describe/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The reverse direction: value → (TimeExpr, localized text).
+ *
+ * Stage 1 (select) chooses framing/unit and builds the IR expression that
+ * describes the value; stage 2 (render) turns it into locale text via Intl.
+ * The round-trip invariant: resolve(describe(v).expr, ctx) must contain v at
+ * the stated grain (tested in test/roundtrip.test.ts).
+ */
+import { type Instant } from '../clock/index.js';
+import type { TimeContext } from '../context.js';
+import type { TimeValue } from '../engine/resolve.js';
+import type { Grain, TimeExpr } from '../ir/types.js';
+export type Framing = 'calendar' | 'elapsed' | 'absolute';
+export interface DescribeOptions {
+    framing?: Framing | 'auto';
+    /** 'casual' produces "9pm last night"; 'neutral' produces "yesterday at 9:00 PM". */
+    style?: 'neutral' | 'casual';
+}
+export interface Description {
+    text: string;
+    expr: TimeExpr;
+    grain: Grain;
+    framing: Framing;
+}
+export declare function describe(value: Instant | TimeValue, ctx: TimeContext, opts?: DescribeOptions): Description;

package/dist/describe/index.js

@@ -0,0 +1,289 @@
+/**
+ * The reverse direction: value → (TimeExpr, localized text).
+ *
+ * Stage 1 (select) chooses framing/unit and builds the IR expression that
+ * describes the value; stage 2 (render) turns it into locale text via Intl.
+ * The round-trip invariant: resolve(describe(v).expr, ctx) must contain v at
+ * the stated grain (tested in test/roundtrip.test.ts).
+ */
+import { calendarDaysBetween, floorTo, toZoned, } from '../clock/index.js';
+import { periodForHour } from '../data/dayPeriods.js';
+const NOW = { op: 'now' };
+const WEEKDAYS_ISO = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+export function describe(value, ctx, opts = {}) {
+    const style = opts.style ?? 'neutral';
+    const framing = opts.framing ?? 'auto';
+    if (typeof value === 'object' && 'kind' in value) {
+        if (value.kind === 'duration' || value.kind === 'amount') {
+            return describeAmount(value, ctx);
+        }
+        const start = toZoned(value.start, ctx.timeZone);
+        return describeInterval(start, value.grain, ctx, framing, style);
+    }
+    // A bare instant: describe at minute grain (a DB timestamp answer).
+    const z = toZoned(value, ctx.timeZone);
+    return describeInterval(z, 'minute', ctx, framing, style);
+}
+function describeInterval(z, grain, ctx, framing, style) {
+    if (framing === 'elapsed')
+        return describeElapsed(z, ctx);
+    if (framing === 'absolute')
+        return describeAbsolute(z, grain, ctx);
+    // auto / calendar
+    const coarse = ['day', 'week', 'month', 'quarter', 'year'].includes(grain);
+    if (coarse)
+        return describeCoarse(z, grain, ctx);
+    return describeDateTime(z, grain, ctx, style);
+}
+// ---------------------------------------------------------------------------
+// coarse calendar grains: day / week / month / quarter / year
+// ---------------------------------------------------------------------------
+function describeCoarse(z, unit, ctx) {
+    const now = ctx.zonedNow;
+    const thisUnitStart = floorTo(now, unit, ctx.weekStart);
+    const valueStart = floorTo(z, unit, ctx.weekStart);
+    const deltaMap = {
+        day: ['yesterday', 'today', 'tomorrow'],
+        week: ['last week', 'this week', 'next week'],
+        month: ['last month', 'this month', 'next month'],
+        quarter: ['last quarter', 'this quarter', 'next quarter'],
+        year: ['last year', 'this year', 'next year'],
+    };
+    const delta = unitsBetween(thisUnitStart, valueStart, unit);
+    if (delta >= -1 && delta <= 1) {
+        const expr = delta === 0
+            ? { op: 'snap', base: NOW, unit }
+            : { op: 'snap', base: { op: 'offset', base: NOW, amount: delta, unit }, unit };
+        return { text: deltaMap[unit][delta + 1], expr, grain: unit, framing: 'calendar' };
+    }
+    if (unit === 'day')
+        return describeFarDay(z, ctx);
+    if (unit === 'week') {
+        const text = `the week of ${fmt(z, ctx, { month: 'long', day: 'numeric' })}`;
+        return {
+            text,
+            expr: {
+                op: 'snap',
+                base: { op: 'literal', date: { year: z.year, month: z.month, day: z.day } },
+                unit: 'week',
+            },
+            grain: 'week',
+            framing: 'calendar',
+        };
+    }
+    if (unit === 'month') {
+        const sameYear = z.year === now.year;
+        const text = sameYear ? fmt(z, ctx, { month: 'long' }) : fmt(z, ctx, { month: 'long', year: 'numeric' });
+        const expr = { op: 'literal', date: { month: z.month, year: z.year } };
+        return { text, expr, grain: 'month', framing: 'calendar' };
+    }
+    if (unit === 'quarter') {
+        const q = Math.floor((z.month - 1) / 3) + 1;
+        return {
+            text: `Q${q} ${z.year}`,
+            expr: {
+                op: 'snap',
+                base: { op: 'literal', date: { year: z.year, month: (q - 1) * 3 + 1 } },
+                unit: 'quarter',
+            },
+            grain: 'quarter',
+            framing: 'calendar',
+        };
+    }
+    return {
+        text: String(z.year),
+        expr: { op: 'literal', date: { year: z.year } },
+        grain: 'year',
+        framing: 'calendar',
+    };
+}
+/** A specific day beyond yesterday/tomorrow: weekday within a week, else a date. */
+function describeFarDay(z, ctx) {
+    const now = ctx.zonedNow;
+    const dayDiff = calendarDaysBetween(now, z);
+    const weekday = WEEKDAYS_ISO[z.dayOfWeek - 1];
+    if (dayDiff < 0 && dayDiff > -7) {
+        return {
+            text: `last ${fmt(z, ctx, { weekday: 'long' })}`,
+            expr: { op: 'seek', base: NOW, dir: 'prev', target: { kind: 'weekday', weekday } },
+            grain: 'day',
+            framing: 'calendar',
+        };
+    }
+    if (dayDiff > 0 && dayDiff < 7) {
+        return {
+            text: `on ${fmt(z, ctx, { weekday: 'long' })}`,
+            expr: { op: 'seek', base: NOW, dir: 'next', target: { kind: 'weekday', weekday } },
+            grain: 'day',
+            framing: 'calendar',
+        };
+    }
+    const sameYear = z.year === now.year;
+    const text = sameYear
+        ? fmt(z, ctx, { month: 'long', day: 'numeric' })
+        : fmt(z, ctx, { month: 'long', day: 'numeric', year: 'numeric' });
+    // The emitted IR always carries the year (the text may omit it): a bare
+    // month+day literal resolves past-first, which would break the round-trip
+    // for future dates.
+    const date = { year: z.year, month: z.month, day: z.day };
+    return { text, expr: { op: 'literal', date }, grain: 'day', framing: 'calendar' };
+}
+// ---------------------------------------------------------------------------
+// datetimes (grain finer than day)
+// ---------------------------------------------------------------------------
+function describeDateTime(z, grain, ctx, style) {
+    const day = describeCoarse(z, 'day', ctx);
+    const timeExpr = timeLiteralFor(z, grain);
+    const expr = { op: 'intersect', parts: [day.expr, timeExpr] };
+    const outGrain = grain === 'instant' ? 'minute' : grain;
+    if (style === 'casual') {
+        const casualDay = casualDayPhrase(z, ctx);
+        if (casualDay) {
+            return {
+                text: `${casualTime(z, ctx)} ${casualDay}`,
+                expr,
+                grain: outGrain,
+                framing: 'calendar',
+            };
+        }
+    }
+    const timeText = fmt(z, ctx, { hour: 'numeric', minute: '2-digit' });
+    // "on Tuesday" already carries a preposition; "today"/"last Friday" need "at".
+    const text = `${day.text} at ${timeText}`;
+    return { text, expr, grain: outGrain, framing: 'calendar' };
+}
+function timeLiteralFor(z, grain) {
+    const h12 = z.hour % 12 === 0 ? 12 : z.hour % 12;
+    const meridiem = z.hour < 12 ? 'am' : 'pm';
+    const time = {
+        hour: h12,
+        meridiem,
+    };
+    if (grain !== 'hour')
+        time.minute = z.minute;
+    if (grain === 'second')
+        time.second = z.second;
+    return { op: 'literal', time };
+}
+/**
+ * Casual day-period phrase for near days: "last night", "this morning",
+ * "tonight", "tomorrow evening". Returns undefined beyond ±1 day.
+ */
+function casualDayPhrase(z, ctx) {
+    const dayDiff = calendarDaysBetween(ctx.zonedNow, z);
+    if (dayDiff < -1 || dayDiff > 1)
+        return undefined;
+    const period = z.hour < 6 ? 'morning' : periodForHour(ctx.language, z.hour);
+    if (dayDiff === 0) {
+        if (period === 'night')
+            return 'tonight';
+        return `this ${period}`;
+    }
+    if (dayDiff === -1) {
+        if (period === 'evening' || period === 'night')
+            return 'last night';
+        return `yesterday ${period}`;
+    }
+    if (period === 'night')
+        return 'tomorrow night';
+    return `tomorrow ${period}`;
+}
+function casualTime(z, ctx) {
+    void ctx;
+    const h12 = z.hour % 12 === 0 ? 12 : z.hour % 12;
+    const suffix = z.hour < 12 ? 'am' : 'pm';
+    return z.minute === 0 ? `${h12}${suffix}` : `${h12}:${String(z.minute).padStart(2, '0')}${suffix}`;
+}
+// ---------------------------------------------------------------------------
+// elapsed & absolute framings
+// ---------------------------------------------------------------------------
+const ELAPSED_LADDER = [
+    { unit: 'second', seconds: 1, max: 60 },
+    { unit: 'minute', seconds: 60, max: 3600 },
+    { unit: 'hour', seconds: 3600, max: 86400 * 2 },
+    { unit: 'day', seconds: 86400, max: 86400 * 30 },
+    { unit: 'month', seconds: 86400 * 30, max: 86400 * 365 },
+    { unit: 'year', seconds: 86400 * 365, max: Infinity },
+];
+function describeElapsed(z, ctx) {
+    const diffSec = (z.epochMilliseconds - ctx.zonedNow.epochMilliseconds) / 1000;
+    const abs = Math.abs(diffSec);
+    if (abs < 1) {
+        return { text: 'now', expr: { op: 'now' }, grain: 'second', framing: 'elapsed' };
+    }
+    const rung = ELAPSED_LADDER.find((r) => abs < r.max) ?? ELAPSED_LADDER[ELAPSED_LADDER.length - 1];
+    const n = Math.max(1, Math.trunc(abs / rung.seconds));
+    const signed = diffSec < 0 ? -n : n;
+    const rtf = new Intl.RelativeTimeFormat(ctx.locale, { numeric: 'always' });
+    return {
+        text: rtf.format(signed, rung.unit),
+        expr: { op: 'offset', base: NOW, amount: signed, unit: rung.unit },
+        grain: rung.unit,
+        framing: 'elapsed',
+    };
+}
+function describeAbsolute(z, grain, ctx) {
+    const fine = ['instant', 'second', 'minute', 'hour'].includes(grain);
+    const dateOpts = fine
+        ? { dateStyle: 'medium', timeStyle: 'short' }
+        : { dateStyle: 'medium' };
+    const date = { year: z.year, month: z.month, day: z.day };
+    const expr = fine
+        ? { op: 'intersect', parts: [{ op: 'literal', date }, timeLiteralFor(z, grain)] }
+        : { op: 'literal', date };
+    return {
+        text: fmt(z, ctx, dateOpts),
+        expr,
+        grain: fine ? (grain === 'instant' ? 'minute' : grain) : grain,
+        framing: 'absolute',
+    };
+}
+function describeAmount(value, ctx) {
+    void ctx;
+    if (value.kind === 'duration') {
+        return {
+            text: value.iso,
+            expr: { op: 'duration', iso: value.iso },
+            grain: 'second',
+            framing: 'absolute',
+        };
+    }
+    const parts = Object.entries(value.amount)
+        .filter(([, v]) => typeof v === 'number' && v !== 0)
+        .map(([k, v]) => `${v} ${Math.abs(v) === 1 ? k.slice(0, -1) : k}`);
+    return {
+        text: parts.join(' '),
+        expr: { op: 'amount', amount: value.amount },
+        grain: 'second',
+        framing: 'absolute',
+    };
+}
+// ---------------------------------------------------------------------------
+function unitsBetween(a, b, unit) {
+    const dur = b.since(a, {
+        largestUnit: unit === 'quarter' ? 'month' : unit,
+        smallestUnit: unit === 'quarter' ? 'month' : unit,
+        roundingMode: 'trunc',
+    });
+    switch (unit) {
+        case 'second':
+            return dur.seconds;
+        case 'minute':
+            return dur.minutes;
+        case 'hour':
+            return dur.hours;
+        case 'day':
+            return dur.days;
+        case 'week':
+            return dur.weeks;
+        case 'month':
+            return dur.months;
+        case 'quarter':
+            return Math.trunc(dur.months / 3);
+        case 'year':
+            return dur.years;
+    }
+}
+function fmt(z, ctx, opts) {
+    return new Intl.DateTimeFormat(ctx.locale, { ...opts, timeZone: ctx.timeZone }).format(new Date(z.epochMilliseconds));
+}

package/dist/engine/resolve.d.ts

@@ -0,0 +1,31 @@
+import { type Instant, type ZInterval } from '../clock/index.js';
+import type { TimeContext } from '../context.js';
+import type { CalendarAmount, DayPeriod, Grain, TimeExpr } from '../ir/types.js';
+export declare class NotResolvableError extends Error {
+    constructor(message: string);
+}
+export declare class AmbiguityError extends Error {
+    constructor(message: string);
+}
+/** A resolved value. Intervals are half-open [start, end). */
+export type TimeValue = {
+    kind: 'interval';
+    start: Instant;
+    end: Instant;
+    grain: Grain;
+} | {
+    kind: 'duration';
+    iso: string;
+} | {
+    kind: 'amount';
+    amount: CalendarAmount;
+};
+export interface Resolution {
+    /** Ordered best-first under the context policy. Ambiguity is data, not an error. */
+    candidates: TimeValue[];
+}
+export declare function resolve(expr: TimeExpr, ctx: TimeContext): Resolution;
+/** First candidate under policy, or throw. */
+export declare function resolveOne(expr: TimeExpr, ctx: TimeContext): TimeValue;
+/** The day-period interval within (anchored to) the day of `base`. */
+export declare function dayPeriodInterval(base: ZInterval, period: DayPeriod, ctx: TimeContext): ZInterval | undefined;