@c9up/chronos 0.1.3

package/src/Duration.ts

@@ -0,0 +1,368 @@
+/**
+ * Duration — immutable time-span value object for the Ream framework.
+ *
+ * Represents a length of time as a bag of calendar + clock units. Closely
+ * mirrors Luxon's `Duration` API so developers coming from AdonisJS feel at
+ * home. Pure TypeScript — no Rust/NAPI dependency (durations are lightweight
+ * arithmetic on small integers, not worth an FFI crossing).
+ *
+ * @implements Story 36.8
+ */
+
+export interface DurationObject {
+	years?: number;
+	months?: number;
+	weeks?: number;
+	days?: number;
+	hours?: number;
+	minutes?: number;
+	seconds?: number;
+	milliseconds?: number;
+}
+
+export type DurationUnit = keyof DurationObject;
+
+const ORDERED_UNITS: DurationUnit[] = [
+	"years",
+	"months",
+	"weeks",
+	"days",
+	"hours",
+	"minutes",
+	"seconds",
+	"milliseconds",
+];
+
+/** Millisecond equivalents for clock units. Calendar units (years/months) are
+ *  not convertible to a fixed ms count — they depend on the anchor date. When
+ *  converting, we use an approximation (30-day month, 365-day year) and
+ *  document it. Luxon does the same. */
+const MS_PER: Record<DurationUnit, number> = {
+	years: 365.25 * 24 * 60 * 60 * 1000,
+	months: 30 * 24 * 60 * 60 * 1000,
+	weeks: 7 * 24 * 60 * 60 * 1000,
+	days: 24 * 60 * 60 * 1000,
+	hours: 60 * 60 * 1000,
+	minutes: 60 * 1000,
+	seconds: 1000,
+	milliseconds: 1,
+};
+
+export class Duration {
+	readonly #values: Readonly<Required<DurationObject>>;
+
+	private constructor(values: DurationObject) {
+		this.#values = {
+			years: values.years ?? 0,
+			months: values.months ?? 0,
+			weeks: values.weeks ?? 0,
+			days: values.days ?? 0,
+			hours: values.hours ?? 0,
+			minutes: values.minutes ?? 0,
+			seconds: values.seconds ?? 0,
+			milliseconds: values.milliseconds ?? 0,
+		};
+	}
+
+	// ─── Factories ──────────────────────────────────────────
+
+	/** Build from a plain object of unit values. */
+	static fromObject(obj: DurationObject): Duration {
+		return new Duration(obj);
+	}
+
+	/** Build from a total number of milliseconds (approximates calendar units). */
+	static fromMillis(ms: number): Duration {
+		return new Duration({ milliseconds: ms });
+	}
+
+	/**
+	 * Parse an ISO 8601 duration string (`P1Y2M3DT4H5M6.789S`).
+	 *
+	 * Supports the full `PnYnMnDTnHnMnS` form. Fractional seconds are
+	 * rounded to the nearest millisecond. Weeks (`PnW`) are a separate form
+	 * that cannot be mixed with other designators per the spec.
+	 */
+	static fromISO(iso: string): Duration {
+		const s = iso.trim();
+		if (!s.startsWith("P"))
+			throw new Error(`Invalid ISO 8601 duration: ${iso}`);
+
+		// Week form: P3W
+		const weekMatch = /^P(\d+(?:\.\d+)?)W$/.exec(s);
+		if (weekMatch) {
+			return new Duration({ weeks: Number.parseFloat(weekMatch[1]) });
+		}
+
+		const match =
+			/^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:([\d.]+)S)?)?$/.exec(
+				s,
+			);
+		if (!match) throw new Error(`Invalid ISO 8601 duration: ${iso}`);
+
+		const [, y, mo, d, h, mi, sec] = match;
+		const seconds = sec ? Math.floor(Number.parseFloat(sec)) : 0;
+		const milliseconds = sec
+			? Math.round((Number.parseFloat(sec) - seconds) * 1000)
+			: 0;
+		return new Duration({
+			years: y ? Number(y) : 0,
+			months: mo ? Number(mo) : 0,
+			days: d ? Number(d) : 0,
+			hours: h ? Number(h) : 0,
+			minutes: mi ? Number(mi) : 0,
+			seconds,
+			milliseconds,
+		});
+	}
+
+	// ─── Accessors ──────────────────────────────────────────
+
+	get years(): number {
+		return this.#values.years;
+	}
+	get months(): number {
+		return this.#values.months;
+	}
+	get weeks(): number {
+		return this.#values.weeks;
+	}
+	get days(): number {
+		return this.#values.days;
+	}
+	get hours(): number {
+		return this.#values.hours;
+	}
+	get minutes(): number {
+		return this.#values.minutes;
+	}
+	get seconds(): number {
+		return this.#values.seconds;
+	}
+	get milliseconds(): number {
+		return this.#values.milliseconds;
+	}
+
+	/** Get a specific unit. */
+	get(unit: DurationUnit): number {
+		return this.#values[unit];
+	}
+
+	/** Return the internal bag as a plain object. */
+	toObject(): Required<DurationObject> {
+		return { ...this.#values };
+	}
+
+	// ─── Arithmetic ─────────────────────────────────────────
+
+	/** Add another duration to this one (per-unit addition). */
+	plus(other: Duration | DurationObject): Duration {
+		const o = other instanceof Duration ? other.#values : other;
+		return new Duration({
+			years: this.#values.years + (o.years ?? 0),
+			months: this.#values.months + (o.months ?? 0),
+			weeks: this.#values.weeks + (o.weeks ?? 0),
+			days: this.#values.days + (o.days ?? 0),
+			hours: this.#values.hours + (o.hours ?? 0),
+			minutes: this.#values.minutes + (o.minutes ?? 0),
+			seconds: this.#values.seconds + (o.seconds ?? 0),
+			milliseconds: this.#values.milliseconds + (o.milliseconds ?? 0),
+		});
+	}
+
+	/** Subtract another duration from this one. */
+	minus(other: Duration | DurationObject): Duration {
+		const o = other instanceof Duration ? other.#values : other;
+		return new Duration({
+			years: this.#values.years - (o.years ?? 0),
+			months: this.#values.months - (o.months ?? 0),
+			weeks: this.#values.weeks - (o.weeks ?? 0),
+			days: this.#values.days - (o.days ?? 0),
+			hours: this.#values.hours - (o.hours ?? 0),
+			minutes: this.#values.minutes - (o.minutes ?? 0),
+			seconds: this.#values.seconds - (o.seconds ?? 0),
+			milliseconds: this.#values.milliseconds - (o.milliseconds ?? 0),
+		});
+	}
+
+	/** Flip the sign on every unit. */
+	negate(): Duration {
+		return new Duration({
+			years: -this.#values.years,
+			months: -this.#values.months,
+			weeks: -this.#values.weeks,
+			days: -this.#values.days,
+			hours: -this.#values.hours,
+			minutes: -this.#values.minutes,
+			seconds: -this.#values.seconds,
+			milliseconds: -this.#values.milliseconds,
+		});
+	}
+
+	// ─── Conversion ─────────────────────────────────────────
+
+	/**
+	 * Normalize clock units — cascade overflows upward so that e.g. 90 seconds
+	 * becomes 1 minute 30 seconds. Calendar units (years, months) are left
+	 * untouched because normalizing months→years requires knowing *which* year.
+	 *
+	 * Weeks are not cascaded into months — they stay as weeks unless the source
+	 * explicitly had weeks. This matches Luxon's behavior.
+	 */
+	normalize(): Duration {
+		let ms = this.#values.milliseconds;
+		let sec = this.#values.seconds;
+		let min = this.#values.minutes;
+		let hrs = this.#values.hours;
+		let days = this.#values.days;
+
+		// Use a carry function that handles negative values correctly.
+		// JS `%` is remainder (preserves sign), not modulo. For negative
+		// durations we need true modulo so the remainder is always non-negative
+		// relative to its parent unit, matching the mathematical convention.
+		const carry = (value: number, divisor: number): [number, number] => {
+			const quot = Math.trunc(value / divisor);
+			const rem = value - quot * divisor;
+			return [quot, rem];
+		};
+
+		let c: number;
+		[c, ms] = carry(ms, 1000);
+		sec += c;
+		[c, sec] = carry(sec, 60);
+		min += c;
+		[c, min] = carry(min, 60);
+		hrs += c;
+		[c, hrs] = carry(hrs, 24);
+		days += c;
+
+		return new Duration({
+			years: this.#values.years,
+			months: this.#values.months,
+			weeks: this.#values.weeks,
+			days,
+			hours: hrs,
+			minutes: min,
+			seconds: sec,
+			milliseconds: ms,
+		});
+	}
+
+	/**
+	 * Re-project this duration into the given units. Uses approximate
+	 * conversions for calendar units (365.25d/year, 30d/month). The result
+	 * is expressed only in the requested units; all others are zero.
+	 *
+	 *     Duration.fromObject({ hours: 25 }).shiftTo('days', 'hours')
+	 *     // → { days: 1, hours: 1 }
+	 */
+	shiftTo(...units: DurationUnit[]): Duration {
+		if (units.length === 0) return this;
+
+		// Convert the entire duration to approximate milliseconds, then greedily
+		// distribute into the requested units from largest to smallest.
+		let totalMs = 0;
+		for (const unit of ORDERED_UNITS) {
+			totalMs += this.#values[unit] * MS_PER[unit];
+		}
+
+		const sorted = [...units].sort(
+			(a, b) => ORDERED_UNITS.indexOf(a) - ORDERED_UNITS.indexOf(b),
+		);
+		const result: DurationObject = {};
+		for (const unit of sorted) {
+			const value = Math.trunc(totalMs / MS_PER[unit]);
+			totalMs -= value * MS_PER[unit];
+			result[unit] = value;
+		}
+		// Any leftover ms goes into the smallest requested unit as a fractional part.
+		if (totalMs !== 0 && sorted.length > 0) {
+			const smallest = sorted[sorted.length - 1];
+			result[smallest] = (result[smallest] ?? 0) + totalMs / MS_PER[smallest];
+		}
+		return new Duration(result);
+	}
+
+	/**
+	 * Express the total duration in a single unit (approximate for calendar
+	 * units — same caveat as `shiftTo`).
+	 */
+	as(unit: DurationUnit): number {
+		let totalMs = 0;
+		for (const u of ORDERED_UNITS) {
+			totalMs += this.#values[u] * MS_PER[u];
+		}
+		return totalMs / MS_PER[unit];
+	}
+
+	// ─── Formatting ─────────────────────────────────────────
+
+	/** ISO 8601 duration string (`P1Y2M3DT4H5M6S`). */
+	toISO(): string {
+		const v = this.#values;
+		let date = "";
+		if (v.years) date += `${v.years}Y`;
+		if (v.months) date += `${v.months}M`;
+		if (v.weeks) date += `${v.weeks}W`;
+		if (v.days) date += `${v.days}D`;
+		let time = "";
+		if (v.hours) time += `${v.hours}H`;
+		if (v.minutes) time += `${v.minutes}M`;
+		const totalSec = v.seconds + v.milliseconds / 1000;
+		if (totalSec) time += `${totalSec}S`;
+		if (!date && !time) return "PT0S";
+		return `P${date}${time ? `T${time}` : ""}`;
+	}
+
+	/**
+	 * Simple pattern format: `hh:mm:ss`, `HH:mm`, etc. Supported tokens:
+	 * `Y` (years), `M` (months), `d` (days), `h`/`hh` (hours), `m`/`mm`
+	 * (minutes), `s`/`ss` (seconds), `S`/`SSS` (milliseconds).
+	 */
+	toFormat(pattern: string): string {
+		const v = this.normalize().#values;
+		return pattern
+			.replace(/hh/g, String(v.hours).padStart(2, "0"))
+			.replace(/mm/g, String(v.minutes).padStart(2, "0"))
+			.replace(/ss/g, String(v.seconds).padStart(2, "0"))
+			.replace(/SSS/g, String(v.milliseconds).padStart(3, "0"))
+			.replace(/h/g, String(v.hours))
+			.replace(/m/g, String(v.minutes))
+			.replace(/s/g, String(v.seconds))
+			.replace(/S/g, String(v.milliseconds))
+			.replace(/Y/g, String(v.years))
+			.replace(/M/g, String(v.months))
+			.replace(/d/g, String(v.days));
+	}
+
+	/**
+	 * Human-readable form: "2 hours, 15 minutes". Uses English hardcoded —
+	 * locale-aware formatting will go through Rosetta once Story 36.12 lands.
+	 */
+	toHuman(): string {
+		const v = this.normalize().#values;
+		const parts: string[] = [];
+		if (v.years) parts.push(`${v.years} ${v.years === 1 ? "year" : "years"}`);
+		if (v.months)
+			parts.push(`${v.months} ${v.months === 1 ? "month" : "months"}`);
+		if (v.weeks) parts.push(`${v.weeks} ${v.weeks === 1 ? "week" : "weeks"}`);
+		if (v.days) parts.push(`${v.days} ${v.days === 1 ? "day" : "days"}`);
+		if (v.hours) parts.push(`${v.hours} ${v.hours === 1 ? "hour" : "hours"}`);
+		if (v.minutes)
+			parts.push(`${v.minutes} ${v.minutes === 1 ? "minute" : "minutes"}`);
+		if (v.seconds)
+			parts.push(`${v.seconds} ${v.seconds === 1 ? "second" : "seconds"}`);
+		if (v.milliseconds)
+			parts.push(
+				`${v.milliseconds} ${v.milliseconds === 1 ? "millisecond" : "milliseconds"}`,
+			);
+		return parts.length > 0 ? parts.join(", ") : "0 seconds";
+	}
+
+	toString(): string {
+		return this.toISO();
+	}
+	toJSON(): string {
+		return this.toISO();
+	}
+}

package/src/Interval.ts

@@ -0,0 +1,227 @@
+/**
+ * Interval — immutable half-open `[start, end)` time range.
+ *
+ * Provides set-style operations (`contains`, `overlaps`, `union`,
+ * `intersection`, `splitBy`, `splitAt`) that the standalone range helpers
+ * in `DateTime.ts` could not express cleanly as methods.
+ *
+ * @implements Story 36.9
+ */
+import { type DateInput, DateTime, type DateUnit } from "./DateTime.js";
+import { Duration, type DurationUnit } from "./Duration.js";
+
+export class Interval {
+	readonly #start: DateTime;
+	readonly #end: DateTime;
+
+	private constructor(start: DateTime, end: DateTime) {
+		if (start.isAfter(end)) {
+			throw new Error("Interval start must be <= end");
+		}
+		this.#start = start;
+		this.#end = end;
+	}
+
+	// ─── Factories ──────────────────────────────────────────
+
+	/** Build from two `DateInput` values. Half-open: `[start, end)`. */
+	static fromDateTimes(start: DateInput, end: DateInput): Interval {
+		return new Interval(DateTime.from(start), DateTime.from(end));
+	}
+
+	/** Build from a start + duration forward. */
+	static after(
+		start: DateInput,
+		duration: Duration | { amount: number; unit: DateUnit },
+	): Interval {
+		const s = DateTime.from(start);
+		// For Duration objects, convert to total milliseconds and add as ms —
+		// NOT as seconds (which was the original bug: Duration.fromMillis(1500)
+		// was being treated as 1500 seconds instead of 1.5 seconds).
+		const e =
+			"amount" in duration
+				? s.plus(duration.amount, duration.unit as DateUnit)
+				: DateTime.fromMillis(
+						s.toMillis() + Math.round(duration.as("milliseconds")),
+					);
+		return new Interval(s, e);
+	}
+
+	// ─── Accessors ──────────────────────────────────────────
+
+	get start(): DateTime {
+		return this.#start;
+	}
+	get end(): DateTime {
+		return this.#end;
+	}
+
+	/** Length in the given unit (approximate for calendar units). */
+	length(unit: DurationUnit = "milliseconds"): number {
+		const ms = this.#end.toMillis() - this.#start.toMillis();
+		const MS_PER: Record<string, number> = {
+			years: 365.25 * 86400000,
+			months: 30 * 86400000,
+			weeks: 7 * 86400000,
+			days: 86400000,
+			hours: 3600000,
+			minutes: 60000,
+			seconds: 1000,
+			milliseconds: 1,
+		};
+		return ms / (MS_PER[unit] ?? 1);
+	}
+
+	/** Duration object between start and end. */
+	toDuration(): Duration {
+		return Duration.fromMillis(this.#end.toMillis() - this.#start.toMillis());
+	}
+
+	// ─── Containment ────────────────────────────────────────
+
+	/** Does this interval contain the given instant? Half-open: `[start, end)`. */
+	contains(dt: DateInput): boolean {
+		const t = DateTime.from(dt).toMillis();
+		return t >= this.#start.toMillis() && t < this.#end.toMillis();
+	}
+
+	/** Is the given instant strictly before this interval? */
+	isBefore(dt: DateInput): boolean {
+		return DateTime.from(dt).toMillis() >= this.#end.toMillis();
+	}
+
+	/** Is the given instant strictly after this interval? */
+	isAfter(dt: DateInput): boolean {
+		return DateTime.from(dt).toMillis() < this.#start.toMillis();
+	}
+
+	/** Is this interval empty (zero length)? */
+	isEmpty(): boolean {
+		return this.#start.toMillis() === this.#end.toMillis();
+	}
+
+	// ─── Set operations ─────────────────────────────────────
+
+	/** Do the two intervals share any time? */
+	overlaps(other: Interval): boolean {
+		return (
+			this.#start.toMillis() < other.#end.toMillis() &&
+			other.#start.toMillis() < this.#end.toMillis()
+		);
+	}
+
+	/** Does this interval fully enclose `other`? */
+	engulfs(other: Interval): boolean {
+		return (
+			this.#start.toMillis() <= other.#start.toMillis() &&
+			this.#end.toMillis() >= other.#end.toMillis()
+		);
+	}
+
+	/** Does `other`'s start touch this interval's end (no overlap, no gap)? */
+	abutsStart(other: Interval): boolean {
+		return this.#end.toMillis() === other.#start.toMillis();
+	}
+
+	/** Does `other`'s end touch this interval's start? */
+	abutsEnd(other: Interval): boolean {
+		return other.#end.toMillis() === this.#start.toMillis();
+	}
+
+	/** The overlapping sub-interval, or `null` if disjoint. */
+	intersection(other: Interval): Interval | null {
+		const s = Math.max(this.#start.toMillis(), other.#start.toMillis());
+		const e = Math.min(this.#end.toMillis(), other.#end.toMillis());
+		if (s >= e) return null;
+		return Interval.fromDateTimes(
+			DateTime.fromMillis(s),
+			DateTime.fromMillis(e),
+		);
+	}
+
+	/** The smallest interval that covers both, or `null` if they don't overlap or abut. */
+	union(other: Interval): Interval | null {
+		if (
+			!this.overlaps(other) &&
+			!this.abutsStart(other) &&
+			!this.abutsEnd(other)
+		) {
+			return null;
+		}
+		return Interval.fromDateTimes(
+			DateTime.fromMillis(
+				Math.min(this.#start.toMillis(), other.#start.toMillis()),
+			),
+			DateTime.fromMillis(
+				Math.max(this.#end.toMillis(), other.#end.toMillis()),
+			),
+		);
+	}
+
+	// ─── Split ──────────────────────────────────────────────
+
+	/** Split this interval into N sub-intervals of roughly equal `duration` length. */
+	splitBy(duration: Duration | { amount: number; unit: DateUnit }): Interval[] {
+		const unitMs: Record<string, number> = {
+			year: 365.25 * 86400000,
+			month: 30 * 86400000,
+			week: 7 * 86400000,
+			day: 86400000,
+			hour: 3600000,
+			minute: 60000,
+			second: 1000,
+		};
+		const stepMs =
+			"amount" in duration
+				? duration.amount * (unitMs[duration.unit] ?? 1)
+				: duration.as("milliseconds");
+		if (stepMs <= 0) throw new Error("splitBy duration must be positive");
+
+		const result: Interval[] = [];
+		let cursor = this.#start.toMillis();
+		const endMs = this.#end.toMillis();
+		while (cursor < endMs) {
+			const next = Math.min(cursor + stepMs, endMs);
+			result.push(
+				Interval.fromDateTimes(
+					DateTime.fromMillis(cursor),
+					DateTime.fromMillis(next),
+				),
+			);
+			cursor = next;
+		}
+		return result;
+	}
+
+	/** Split at specific instants. Instants outside the interval are ignored. */
+	splitAt(...dts: DateInput[]): Interval[] {
+		const points = dts
+			.map((d) => DateTime.from(d).toMillis())
+			.filter((ms) => ms > this.#start.toMillis() && ms < this.#end.toMillis())
+			.sort((a, b) => a - b);
+
+		const result: Interval[] = [];
+		let prev = this.#start.toMillis();
+		for (const p of points) {
+			result.push(
+				Interval.fromDateTimes(
+					DateTime.fromMillis(prev),
+					DateTime.fromMillis(p),
+				),
+			);
+			prev = p;
+		}
+		result.push(Interval.fromDateTimes(DateTime.fromMillis(prev), this.#end));
+		return result;
+	}
+
+	// ─── Serialization ──────────────────────────────────────
+
+	toString(): string {
+		return `[${this.#start.toISO()}, ${this.#end.toISO()})`;
+	}
+
+	toJSON(): { start: string; end: string } {
+		return { start: this.#start.toISO(), end: this.#end.toISO() };
+	}
+}