@autometa/datetime 0.1.15 → 1.0.0-rc.0

package/README.md

@@ -1,3 +1,48 @@
-# Introduction
+# @autometa/datetime
 
-There's nothing here yet
+Utilities for creating deterministic dates and measuring time differences in
+Autometa tests. The package provides:
+
+- `Dates` – convenience shortcuts (yesterday, nextWeek, midnight, etc.), phrase
+	parsing (`"2 days from now"`) and explicit time offsets.
+- `Dates.iso` / `Dates.fmt` – ISO string or YYYY-MM-DD formatted variants of the
+	same API surface.
+- `Time.diff` – helpers for calculating the difference between two dates in
+	milliseconds, seconds, minutes, hours, days, or weeks.
+
+```ts
+import { Dates, Time } from "@autometa/datetime";
+
+// Shortcut access
+const tomorrow = Dates.tomorrow;
+const nextFortnight = Dates.iso.nextFortnight;
+
+// Phrase parsing & offsets
+const launch = Dates.fromPhrase("3 weeks from now");
+const reminder = Dates.make(-2, "days");
+
+// Time differences
+const diffInHours = Time.diff.hours(new Date(), reminder);
+```
+
+## Custom clocks
+
+For deterministic scenarios (e.g. unit tests) you can inject your own clock via
+`createDates`:
+
+```ts
+import { createDates } from "@autometa/datetime";
+
+const fixed = new Date("2024-01-01T08:00:00Z");
+const clock = { now: () => fixed };
+
+const dates = createDates({ clock });
+expect(dates.today.toISOString()).toBe("2024-01-01T08:00:00.000Z");
+```
+
+## Migration notes
+
+- Singletons (`Dates`, `Time`) remain for convenience but now wrap factories so
+	you can create isolated instances with custom clocks.
+- Phrase parsing errors throw `AutomationError` with actionable messaging.
+- All packages enforce >=90% cobertura across statements/branches/functions.

package/dist/dates/clock.d.ts

@@ -0,0 +1,5 @@
+export interface Clock {
+    now(): Date;
+}
+export declare const systemClock: Clock;
+export declare function cloneDate(date: Date): Date;

package/dist/dates/date-factory.d.ts

@@ -0,0 +1,20 @@
+import type { Clock } from "./clock.js";
+import { type StandardTimeUnit } from "./time-units.js";
+export type DateShortcut = "now" | "beforeYesterday" | "yesterday" | "today" | "tomorrow" | "afterTomorrow" | "midnight" | "lastWeek" | "nextWeek" | "lastFortnight" | "nextFortnight";
+export interface DateFactoryOptions {
+    clock?: Clock;
+}
+export declare class DateFactory {
+    private readonly clock;
+    constructor(options?: DateFactoryOptions);
+    find(shortcut: DateShortcut): Date;
+    fromPhraseSafe(phrase: unknown): Date;
+    fromPhrase(phrase: unknown): Date;
+    make(timeOffset: number, timeUnit: string | StandardTimeUnit): Date;
+    private currentDate;
+    private midnight;
+    private parseDate;
+    private isDateLike;
+    private extractRelative;
+    private buildRelativeMatch;
+}

package/dist/dates/formatted-date-factory.d.ts

@@ -0,0 +1,23 @@
+import type { DateFactory } from "./date-factory.js";
+import type { StandardTimeUnit } from "./time-units.js";
+export interface FormattedDateFactoryOptions {
+    formatter?: (date: Date) => string;
+}
+export declare class FormattedDateFactory {
+    private readonly dateFactory;
+    private readonly format;
+    constructor(dateFactory: DateFactory, options?: FormattedDateFactoryOptions);
+    make(offset: number, unit: StandardTimeUnit | string): string;
+    fromPhrase(phrase: unknown): string;
+    get beforeYesterday(): string;
+    get yesterday(): string;
+    get today(): string;
+    get tomorrow(): string;
+    get afterTomorrow(): string;
+    get midnight(): string;
+    get lastWeek(): string;
+    get nextWeek(): string;
+    get lastFortnight(): string;
+    get nextFortnight(): string;
+    private fromShortcut;
+}

package/dist/dates/iso-date-factory.d.ts

@@ -0,0 +1,23 @@
+import type { DateFactory } from "./date-factory.js";
+import type { StandardTimeUnit } from "./time-units.js";
+export interface IsoDateFactoryOptions {
+    serializer?: (date: Date) => string;
+}
+export declare class IsoDateFactory {
+    private readonly dateFactory;
+    private readonly serialise;
+    constructor(dateFactory: DateFactory, options?: IsoDateFactoryOptions);
+    make(offset: number, unit: StandardTimeUnit | string): string;
+    fromPhrase(phrase: unknown): string;
+    get beforeYesterday(): string;
+    get yesterday(): string;
+    get today(): string;
+    get tomorrow(): string;
+    get afterTomorrow(): string;
+    get midnight(): string;
+    get lastWeek(): string;
+    get nextWeek(): string;
+    get lastFortnight(): string;
+    get nextFortnight(): string;
+    private fromShortcut;
+}

package/dist/dates/object.d.ts

@@ -0,0 +1,28 @@
+import { DateFactory, type DateFactoryOptions } from "./date-factory.js";
+import { FormattedDateFactory } from "./formatted-date-factory.js";
+import { IsoDateFactory } from "./iso-date-factory.js";
+import type { StandardTimeUnit } from "./time-units.js";
+export interface DatesOptions extends DateFactoryOptions {
+    factory?: DateFactory;
+}
+export interface DatesObject {
+    readonly iso: IsoDateFactory;
+    readonly fmt: FormattedDateFactory;
+    readonly now: Date;
+    readonly beforeYesterday: Date;
+    readonly yesterday: Date;
+    readonly today: Date;
+    readonly tomorrow: Date;
+    readonly afterTomorrow: Date;
+    readonly midnight: Date;
+    readonly lastWeek: Date;
+    readonly nextWeek: Date;
+    readonly lastFortnight: Date;
+    readonly nextFortnight: Date;
+    fromPhrase(phrase: unknown): Date;
+    fromPhraseSafe(phrase: unknown): Date;
+    make(offset: number, unit: StandardTimeUnit | string): Date;
+}
+export declare function createDates(options?: DatesOptions): DatesObject;
+export declare const Dates: DatesObject;
+export type { DateFactoryOptions };

package/dist/dates/time-units.d.ts

@@ -0,0 +1,6 @@
+export type StandardTimeUnit = "milliseconds" | "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years";
+export interface NormalisedTimeUnit {
+    unit: StandardTimeUnit;
+    scale: number;
+}
+export declare function resolveTimeUnit(input: string): NormalisedTimeUnit;

package/dist/index.cjs

@@ -0,0 +1,482 @@
+'use strict';
+
+var errors = require('@autometa/errors');
+var isoDatestringValidator = require('iso-datestring-validator');
+var asserters = require('@autometa/asserters');
+
+// src/dates/date-factory.ts
+
+// src/dates/clock.ts
+var systemClock = {
+  now: () => /* @__PURE__ */ new Date()
+};
+function cloneDate(date) {
+  return new Date(date.getTime());
+}
+var UNIT_ALIASES = {
+  millisecond: { unit: "milliseconds", scale: 1 },
+  milliseconds: { unit: "milliseconds", scale: 1 },
+  ms: { unit: "milliseconds", scale: 1 },
+  second: { unit: "seconds", scale: 1 },
+  seconds: { unit: "seconds", scale: 1 },
+  sec: { unit: "seconds", scale: 1 },
+  secs: { unit: "seconds", scale: 1 },
+  minute: { unit: "minutes", scale: 1 },
+  minutes: { unit: "minutes", scale: 1 },
+  min: { unit: "minutes", scale: 1 },
+  mins: { unit: "minutes", scale: 1 },
+  hour: { unit: "hours", scale: 1 },
+  hours: { unit: "hours", scale: 1 },
+  hr: { unit: "hours", scale: 1 },
+  hrs: { unit: "hours", scale: 1 },
+  day: { unit: "days", scale: 1 },
+  days: { unit: "days", scale: 1 },
+  week: { unit: "weeks", scale: 1 },
+  weeks: { unit: "weeks", scale: 1 },
+  fortnight: { unit: "days", scale: 14 },
+  fortnights: { unit: "days", scale: 14 },
+  month: { unit: "months", scale: 1 },
+  months: { unit: "months", scale: 1 },
+  year: { unit: "years", scale: 1 },
+  years: { unit: "years", scale: 1 }
+};
+function resolveTimeUnit(input) {
+  const key = input.trim().toLowerCase();
+  const resolved = UNIT_ALIASES[key];
+  if (!resolved) {
+    throw new errors.AutomationError(
+      `Unsupported time unit '${input}'. Expected one of ${Object.keys(UNIT_ALIASES).sort().join(", ")}.`
+    );
+  }
+  return resolved;
+}
+
+// src/shared/phrases.ts
+var SEPARATORS = /[\s_-]+/g;
+function capitalize(word) {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+function splitWords(phrase) {
+  return phrase.trim().split(SEPARATORS).filter(Boolean).map((word) => word.toLowerCase());
+}
+function toCamelKey(phrase) {
+  const words = splitWords(phrase);
+  if (words.length === 0) {
+    return "";
+  }
+  const [first, ...rest] = words;
+  return first + rest.map(capitalize).join("");
+}
+function normalizeToken(phrase) {
+  return splitWords(phrase).join("");
+}
+
+// src/dates/date-factory.ts
+var SHORTCUT_LOOKUP = /* @__PURE__ */ new Set([
+  "now",
+  "beforeYesterday",
+  "yesterday",
+  "today",
+  "tomorrow",
+  "afterTomorrow",
+  "midnight",
+  "lastWeek",
+  "nextWeek",
+  "lastFortnight",
+  "nextFortnight"
+]);
+var FUTURE_PATTERN = /^(\d+)\s+([A-Za-z\s]+?)\s+from\s+now$/i;
+var PAST_PATTERN = /^(\d+)\s+([A-Za-z\s]+?)\s+ago$/i;
+function invalidDate() {
+  return new Date(Number.NaN);
+}
+function isDateShortcut(value) {
+  return SHORTCUT_LOOKUP.has(value);
+}
+var DateFactory = class {
+  constructor(options = {}) {
+    this.clock = options.clock ?? systemClock;
+  }
+  find(shortcut) {
+    switch (shortcut) {
+      case "now":
+        return this.currentDate();
+      case "beforeYesterday":
+        return this.make(-2, "days");
+      case "yesterday":
+        return this.make(-1, "days");
+      case "today":
+        return this.make(0, "days");
+      case "tomorrow":
+        return this.make(1, "days");
+      case "afterTomorrow":
+        return this.make(2, "days");
+      case "midnight":
+        return this.midnight();
+      case "lastWeek":
+        return this.make(-1, "weeks");
+      case "nextWeek":
+        return this.make(1, "weeks");
+      case "lastFortnight":
+        return this.make(-14, "days");
+      case "nextFortnight":
+        return this.make(14, "days");
+      default:
+        throw new errors.AutomationError(
+          `Unsupported date shortcut '${shortcut}'.`
+        );
+    }
+  }
+  fromPhraseSafe(phrase) {
+    if (typeof phrase !== "string") {
+      return invalidDate();
+    }
+    const trimmed = phrase.trim();
+    if (trimmed.length === 0) {
+      return invalidDate();
+    }
+    const shortcutCandidate = toCamelKey(trimmed);
+    if (isDateShortcut(shortcutCandidate)) {
+      return this.find(shortcutCandidate);
+    }
+    const relative = this.extractRelative(trimmed);
+    if (relative) {
+      return this.make(relative.offset, relative.unit);
+    }
+    if (this.isDateLike(trimmed)) {
+      return this.parseDate(trimmed);
+    }
+    return invalidDate();
+  }
+  fromPhrase(phrase) {
+    const result = this.fromPhraseSafe(phrase);
+    if (Number.isNaN(result.getTime())) {
+      throw new errors.AutomationError(
+        `Could not parse date from phrase '${String(phrase)}'. Valid shortcuts are: ${[...SHORTCUT_LOOKUP].join(", ")}.`
+      );
+    }
+    return result;
+  }
+  make(timeOffset, timeUnit) {
+    if (!Number.isFinite(timeOffset)) {
+      throw new errors.AutomationError(
+        `Time offset must be finite. Received '${timeOffset}'.`
+      );
+    }
+    const { unit, scale } = resolveTimeUnit(String(timeUnit));
+    const offset = timeOffset * scale;
+    const date = this.currentDate();
+    switch (unit) {
+      case "years":
+        date.setFullYear(date.getFullYear() + offset);
+        break;
+      case "months":
+        date.setMonth(date.getMonth() + offset);
+        break;
+      case "weeks":
+        date.setDate(date.getDate() + offset * 7);
+        break;
+      case "days":
+        date.setDate(date.getDate() + offset);
+        break;
+      case "hours":
+        date.setHours(date.getHours() + offset);
+        break;
+      case "minutes":
+        date.setMinutes(date.getMinutes() + offset);
+        break;
+      case "seconds":
+        date.setSeconds(date.getSeconds() + offset);
+        break;
+      case "milliseconds":
+        date.setMilliseconds(date.getMilliseconds() + offset);
+        break;
+      default:
+        throw new errors.AutomationError(`Unsupported time unit '${unit}'.`);
+    }
+    return date;
+  }
+  currentDate() {
+    return cloneDate(this.clock.now());
+  }
+  midnight() {
+    const date = this.currentDate();
+    date.setUTCDate(date.getUTCDate() + 1);
+    date.setUTCHours(0, 0, 0, 0);
+    return date;
+  }
+  parseDate(value) {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) {
+      return parsed;
+    }
+    return new Date(Date.parse(value));
+  }
+  isDateLike(value) {
+    if (!Number.isNaN(new Date(value).getTime())) {
+      return true;
+    }
+    return isoDatestringValidator.isValidDate(value) || isoDatestringValidator.isValidISODateString(value) || isoDatestringValidator.isValidTime(value) || isoDatestringValidator.isValidYearMonth(value);
+  }
+  extractRelative(phrase) {
+    const futureMatch = FUTURE_PATTERN.exec(phrase);
+    if (futureMatch) {
+      return this.buildRelativeMatch(futureMatch, 1);
+    }
+    const pastMatch = PAST_PATTERN.exec(phrase);
+    if (pastMatch) {
+      return this.buildRelativeMatch(pastMatch, -1);
+    }
+    return void 0;
+  }
+  buildRelativeMatch(match, direction) {
+    const value = match[1];
+    const unit = match[2];
+    if (!value || !unit) {
+      return void 0;
+    }
+    const magnitude = Number.parseInt(value, 10);
+    if (!Number.isFinite(magnitude)) {
+      return void 0;
+    }
+    const convertedUnit = normalizeToken(unit);
+    const { unit: normalisedUnit, scale } = resolveTimeUnit(convertedUnit);
+    const offset = magnitude * scale * direction;
+    return {
+      offset,
+      unit: normalisedUnit
+    };
+  }
+};
+
+// src/dates/formatted-date-factory.ts
+var FormattedDateFactory = class {
+  constructor(dateFactory, options = {}) {
+    this.dateFactory = dateFactory;
+    this.format = options.formatter ?? ((date) => date.toISOString().substring(0, 10));
+  }
+  make(offset, unit) {
+    return this.format(this.dateFactory.make(offset, unit));
+  }
+  fromPhrase(phrase) {
+    return this.format(this.dateFactory.fromPhrase(phrase));
+  }
+  get beforeYesterday() {
+    return this.fromShortcut("beforeYesterday");
+  }
+  get yesterday() {
+    return this.fromShortcut("yesterday");
+  }
+  get today() {
+    return this.fromShortcut("today");
+  }
+  get tomorrow() {
+    return this.fromShortcut("tomorrow");
+  }
+  get afterTomorrow() {
+    return this.fromShortcut("afterTomorrow");
+  }
+  get midnight() {
+    return this.fromShortcut("midnight");
+  }
+  get lastWeek() {
+    return this.fromShortcut("lastWeek");
+  }
+  get nextWeek() {
+    return this.fromShortcut("nextWeek");
+  }
+  get lastFortnight() {
+    return this.fromShortcut("lastFortnight");
+  }
+  get nextFortnight() {
+    return this.fromShortcut("nextFortnight");
+  }
+  fromShortcut(shortcut) {
+    return this.format(this.dateFactory.find(shortcut));
+  }
+};
+
+// src/dates/iso-date-factory.ts
+var IsoDateFactory = class {
+  constructor(dateFactory, options = {}) {
+    this.dateFactory = dateFactory;
+    this.serialise = options.serializer ?? ((date) => date.toISOString());
+  }
+  make(offset, unit) {
+    return this.serialise(this.dateFactory.make(offset, unit));
+  }
+  fromPhrase(phrase) {
+    return this.serialise(this.dateFactory.fromPhrase(phrase));
+  }
+  get beforeYesterday() {
+    return this.fromShortcut("beforeYesterday");
+  }
+  get yesterday() {
+    return this.fromShortcut("yesterday");
+  }
+  get today() {
+    return this.fromShortcut("today");
+  }
+  get tomorrow() {
+    return this.fromShortcut("tomorrow");
+  }
+  get afterTomorrow() {
+    return this.fromShortcut("afterTomorrow");
+  }
+  get midnight() {
+    return this.fromShortcut("midnight");
+  }
+  get lastWeek() {
+    return this.fromShortcut("lastWeek");
+  }
+  get nextWeek() {
+    return this.fromShortcut("nextWeek");
+  }
+  get lastFortnight() {
+    return this.fromShortcut("lastFortnight");
+  }
+  get nextFortnight() {
+    return this.fromShortcut("nextFortnight");
+  }
+  fromShortcut(shortcut) {
+    return this.serialise(this.dateFactory.find(shortcut));
+  }
+};
+
+// src/dates/object.ts
+var DatesFacade = class {
+  constructor(factory) {
+    this.factory = factory;
+    this.iso = new IsoDateFactory(factory);
+    this.fmt = new FormattedDateFactory(factory);
+  }
+  get now() {
+    return this.fromShortcut("now");
+  }
+  get beforeYesterday() {
+    return this.fromShortcut("beforeYesterday");
+  }
+  get yesterday() {
+    return this.fromShortcut("yesterday");
+  }
+  get today() {
+    return this.fromShortcut("today");
+  }
+  get tomorrow() {
+    return this.fromShortcut("tomorrow");
+  }
+  get afterTomorrow() {
+    return this.fromShortcut("afterTomorrow");
+  }
+  get midnight() {
+    return this.fromShortcut("midnight");
+  }
+  get lastWeek() {
+    return this.fromShortcut("lastWeek");
+  }
+  get nextWeek() {
+    return this.fromShortcut("nextWeek");
+  }
+  get lastFortnight() {
+    return this.fromShortcut("lastFortnight");
+  }
+  get nextFortnight() {
+    return this.fromShortcut("nextFortnight");
+  }
+  fromPhrase(phrase) {
+    return this.factory.fromPhrase(phrase);
+  }
+  fromPhraseSafe(phrase) {
+    return this.factory.fromPhraseSafe(phrase);
+  }
+  make(offset, unit) {
+    return this.factory.make(offset, unit);
+  }
+  fromShortcut(shortcut) {
+    return this.factory.find(shortcut);
+  }
+};
+function createDates(options = {}) {
+  const factory = options.factory ?? new DateFactory(options);
+  return new DatesFacade(factory);
+}
+var Dates = createDates();
+var SUPPORTED_METHODS = [
+  "minutes",
+  "seconds",
+  "millis",
+  "days",
+  "hours",
+  "weeks"
+];
+function toTime(date) {
+  return new Date(date).getTime();
+}
+var TimeDiff = class {
+  minutes(start, end) {
+    return this.millis(start, end) / 6e4;
+  }
+  seconds(start, end) {
+    return this.millis(start, end) / 1e3;
+  }
+  millis(start, end) {
+    const distance = Math.abs(toTime(end) - toTime(start));
+    return Math.round(distance);
+  }
+  days(start, end) {
+    return this.millis(start, end) / 864e5;
+  }
+  hours(start, end) {
+    return this.millis(start, end) / 36e5;
+  }
+  weeks(start, end) {
+    return this.millis(start, end) / 6048e5;
+  }
+  fromPhrase(phrase) {
+    if (typeof phrase !== "string") {
+      throw new errors.AutomationError(
+        `TimeDiff.fromPhrase expects a string, received '${typeof phrase}'.`
+      );
+    }
+    const key = normalizeToken(phrase);
+    if (!this.hasMethod(key)) {
+      throw new errors.AutomationError(
+        `Unsupported diff unit '${phrase}'. Expected one of ${this.supportedMethods().join(", ")}.`
+      );
+    }
+    asserters.assertKey(this, key, "TimeDiff.fromPhrase");
+    const method = this[key];
+    if (typeof method !== "function") {
+      throw new errors.AutomationError(`Diff method '${key}' is not callable.`);
+    }
+    return method.bind(this);
+  }
+  hasMethod(name) {
+    return SUPPORTED_METHODS.includes(name);
+  }
+  supportedMethods() {
+    return [...SUPPORTED_METHODS];
+  }
+};
+
+// src/time/time.ts
+var TimeFacade = class {
+  constructor(diff) {
+    this.diff = diff;
+  }
+};
+function createTime() {
+  return new TimeFacade(new TimeDiff());
+}
+var Time = createTime();
+
+exports.DateFactory = DateFactory;
+exports.Dates = Dates;
+exports.FormattedDateFactory = FormattedDateFactory;
+exports.IsoDateFactory = IsoDateFactory;
+exports.Time = Time;
+exports.TimeDiff = TimeDiff;
+exports.createDates = createDates;
+exports.createTime = createTime;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.cjs.map