Implement support for Temporal objects (except Temporal.Duration).

Author: rkh

fluent-bundle/package.json

@@ -49,6 +49,7 @@
     "npm": ">=7.0.0"
   },
   "devDependencies": {
-    "@fluent/dedent": "^0.5.0"
+    "@fluent/dedent": "^0.5.0",
+    "temporal-polyfill": "^0.2.5"
   }
 }

fluent-bundle/src/builtins.ts

@@ -88,7 +88,7 @@ export function NUMBER(
   }
 
   if (arg instanceof FluentDateTime) {
-    return new FluentNumber(arg.valueOf(), {
+    return new FluentNumber(arg.toNumber(), {
       ...values(opts, NUMBER_ALLOWED),
     });
   }
@@ -157,17 +157,8 @@ export function DATETIME(
     return new FluentNone(`DATETIME(${arg.valueOf()})`);
   }
 
-  if (arg instanceof FluentDateTime) {
-    return new FluentDateTime(arg.valueOf(), {
-      ...arg.opts,
-      ...values(opts, DATETIME_ALLOWED),
-    });
-  }
-
-  if (arg instanceof FluentNumber) {
-    return new FluentDateTime(arg.valueOf(), {
-      ...values(opts, DATETIME_ALLOWED),
-    });
+  if (arg instanceof FluentDateTime || arg instanceof FluentNumber) {
+    return FluentDateTime.from(arg, values(opts, DATETIME_ALLOWED));
   }
 
   throw new TypeError("Invalid argument to DATETIME");

fluent-bundle/src/bundle.ts

@@ -1,13 +1,12 @@
 import { resolveComplexPattern } from "./resolver.js";
 import { Scope } from "./scope.js";
 import { FluentResource } from "./resource.js";
-import { FluentValue, FluentNone, FluentFunction } from "./types.js";
+import { FluentVariable, FluentNone, FluentFunction } from "./types.js";
 import { Message, Term, Pattern } from "./ast.js";
 import { NUMBER, DATETIME } from "./builtins.js";
 import { getMemoizerForLocale, IntlCache } from "./memoizer.js";
 
 export type TextTransform = (text: string) => string;
-export type FluentVariable = FluentValue | string | number | Date;
 
 /**
  * Message bundles are single-language stores of translation resources. They are

fluent-bundle/src/index.ts

@@ -8,14 +8,16 @@
  */
 
 export type { Message } from "./ast.js";
-export { FluentBundle, FluentVariable, TextTransform } from "./bundle.js";
+export { FluentBundle, TextTransform } from "./bundle.js";
 export { FluentResource } from "./resource.js";
 export type { Scope } from "./scope.js";
 export {
   FluentValue,
+  FluentVariable,
   FluentType,
   FluentFunction,
   FluentNone,
   FluentNumber,
   FluentDateTime,
+  FluentDateInfo,
 } from "./types.js";

fluent-bundle/src/resolver.ts

@@ -30,6 +30,7 @@ import {
   FluentNone,
   FluentNumber,
   FluentDateTime,
+  FluentVariable,
 } from "./types.js";
 import { Scope } from "./scope.js";
 import {
@@ -44,7 +45,6 @@ import {
   ComplexPattern,
   Pattern,
 } from "./ast.js";
-import { FluentVariable } from "./bundle.js";
 
 /**
  * The maximum number of placeables which can be expanded in a single call to
@@ -187,8 +187,8 @@ function resolveVariableReference(
     case "number":
       return new FluentNumber(arg);
     case "object":
-      if (arg instanceof Date) {
-        return new FluentDateTime(arg.getTime());
+      if (FluentDateTime.isDateTimeValue(arg)) {
+        return FluentDateTime.from(arg);
       }
     // eslint-disable-next-line no-fallthrough
     default:

fluent-bundle/src/scope.ts

@@ -1,5 +1,6 @@
-import { FluentBundle, FluentVariable } from "./bundle.js";
+import { FluentBundle } from "./bundle.js";
 import { ComplexPattern } from "./ast.js";
+import { FluentVariable } from "./types.js";
 
 export class Scope {
   /** The bundle for which the given resolution is happening. */

fluent-bundle/src/temporal.d.ts

@@ -0,0 +1,56 @@
+declare namespace FluentTemporal {
+  class Duration {
+  }
+
+  class Instant {
+    epochMilliseconds: number;
+    toZonedDateTimeISO(timeZone: string): ZonedDateTime;
+  }
+
+  class PlainDate {
+    calendarId: string;
+    toZonedDateTime(timeZone: string | { timeZone: string }): ZonedDateTime;
+  }
+
+  class PlainDateTime {
+    calendarId: string;
+    withCalendar(calendar: string): PlainDateTime;
+    toZonedDateTime(timeZone: string | { timeZone: string }): ZonedDateTime;
+  }
+
+  class PlainMonthDay {
+    calendarId: string;
+    withCalendar(calendar: string): PlainMonthDay;
+  }
+
+  class PlainTime {
+  }
+
+  class PlainYearMonth {
+    calendarId: string;
+    withCalendar(calendar: string): PlainYearMonth;
+  }
+
+  class ZonedDateTime {
+    timeZoneId: string;
+    calendarId: string;
+    epochMilliseconds: number;
+    withTimeZone(timeZone: string): ZonedDateTime;
+    withCalendar(calendar: string): ZonedDateTime;
+    toPlainDateTime(): PlainDateTime;
+  }
+
+  type PlainWithCalendar = PlainDateTime | PlainDate | PlainMonthDay | PlainYearMonth;
+  type Plain = PlainWithCalendar | PlainDate;
+
+  interface TemporalContainer {
+    Duration: typeof Duration;
+    Instant: typeof Instant;
+    PlainDate: typeof PlainDate;
+    PlainDateTime: typeof PlainDateTime;
+    PlainMonthDay: typeof PlainMonthDay;
+    PlainTime: typeof PlainTime;
+    PlainYearMonth: typeof PlainYearMonth;
+    ZonedDateTime: typeof ZonedDateTime;
+  }
+}

fluent-bundle/src/types.ts

@@ -1,12 +1,34 @@
 import { Scope } from "./scope.js";
 
 export type FluentValue = FluentType<unknown> | string;
+export type FluentStrictDateValue = FluentTemporal.Plain | Date;
+export type FluentDateValue = FluentStrictDateValue | number;
+export type FluentDateInfo = FluentDateValue | Date | FluentTemporal.Instant | FluentTemporal.ZonedDateTime;
+export type FluentVariable = FluentValue | FluentDateInfo | string | number;
 
 export type FluentFunction = (
   positional: Array<FluentValue>,
   named: Record<string, FluentValue>
 ) => FluentValue;
 
+// helper function to determine if a value is a Temporal object, without having to define a global Temporal namespace
+function isTemporal(value: any, type: "Duration"): value is FluentTemporal.Duration;
+function isTemporal(value: any, type: "Instant"): value is FluentTemporal.Instant;
+function isTemporal(value: any, type: "PlainDate"): value is FluentTemporal.PlainDate;
+function isTemporal(value: any, type: "PlainDateTime"): value is FluentTemporal.PlainDateTime;
+function isTemporal(value: any, type: "PlainMonthDay"): value is FluentTemporal.PlainMonthDay;
+function isTemporal(value: any, type: "PlainTime"): value is FluentTemporal.PlainTime;
+function isTemporal(value: any, type: "PlainYearMonth"): value is FluentTemporal.PlainYearMonth;
+function isTemporal(value: any, type: "ZonedDateTime"): value is FluentTemporal.ZonedDateTime;
+function isTemporal(value: any, type: keyof FluentTemporal.TemporalContainer): boolean {
+  const temporal = (globalThis as any).Temporal as FluentTemporal.TemporalContainer | undefined;
+  const prototype = temporal && temporal[type];
+  if (!prototype) {
+    return false;
+  }
+  return value instanceof prototype;
+}
+
 /**
  * The `FluentType` class is the base of Fluent's type system.
  *
@@ -109,32 +131,128 @@ export class FluentNumber extends FluentType<number> {
  * option bag of options which will be passed to `Intl.DateTimeFormat` when the
  * `FluentDateTime` is formatted to a string.
  */
-export class FluentDateTime extends FluentType<number> {
+export class FluentDateTime extends FluentType<FluentDateValue> {
   /** Options passed to `Intl.DateTimeFormat`. */
   public opts: Intl.DateTimeFormatOptions;
 
+  /** ignore */
+  static isDateTimeValue(info: any): info is FluentStrictDateValue {
+    return info instanceof Date ||  isTemporal(info, "Instant") ||
+      isTemporal(info, "PlainDateTime") || isTemporal(info, "PlainDate") ||
+      isTemporal(info, "PlainMonthDay") || isTemporal(info, "PlainTime") ||
+      isTemporal(info, "PlainYearMonth") || isTemporal(info, "ZonedDateTime");
+  }
+
+  /**
+   * Converts various types representing dates and times to a `FluentDateTime`.
+   */
+  static from(
+    info: FluentDateInfo | FluentType<FluentDateInfo>,
+    opts: Intl.DateTimeFormatOptions = {}
+  ): FluentDateTime {
+    if (typeof info === "number") {
+      return new FluentDateTime(info, opts);
+    }
+
+    if (info instanceof FluentDateTime) {
+      return new FluentDateTime(info.value, {
+        ...info.opts, ...opts
+      });
+    }
+
+    if (info instanceof FluentType) {
+      return FluentDateTime.from(info.valueOf(), opts);
+    }
+    
+    if (info instanceof Date) {
+      return new FluentDateTime(info.getTime(), opts);
+    }
+    
+    if (isTemporal(info, "Instant")) {
+      return new FluentDateTime(info.epochMilliseconds, opts);
+    }
+    
+    if (isTemporal(info, "ZonedDateTime")) {
+      let zoned: FluentTemporal.ZonedDateTime = info;
+      if (opts.timeZone) {
+        zoned = info.withTimeZone(opts.timeZone);
+      } else {
+        opts = { ...opts, timeZone: info.timeZoneId };
+      }
+      if (opts.calendar === undefined) {
+        opts = { ...opts, calendar: zoned.calendarId };
+      }
+      return new FluentDateTime(zoned.epochMilliseconds, opts);
+    }
+
+    if (isTemporal(info, "PlainYearMonth")) {
+      if (opts.calendar === undefined) {
+        opts = { ...opts, calendar: info.calendarId };
+      } else {
+        info = info.withCalendar(opts.calendar);
+      }
+      return new FluentDateTime(info, opts);
+    }
+
+    if (
+      isTemporal(info, "PlainDateTime") || isTemporal(info, "PlainDate") ||
+      isTemporal(info, "PlainMonthDay") || isTemporal(info, "PlainTime")
+    ) {
+      return new FluentDateTime(info, opts);
+    }
+
+    throw new Error("Invalid value passed to FluentDateTime");
+  }
+
   /**
    * Create an instance of `FluentDateTime` with options to the
    * `Intl.DateTimeFormat` constructor.
    *
    * @param value The number value of this `FluentDateTime`, in milliseconds.
    * @param opts Options which will be passed to `Intl.DateTimeFormat`.
    */
-  constructor(value: number, opts: Intl.DateTimeFormatOptions = {}) {
+  constructor(value: FluentDateValue, opts: Intl.DateTimeFormatOptions = {}) {
     super(value);
     this.opts = opts;
   }
 
+  /**
+   * Convert this `FluentDateTime` to a number.
+   * Note that this isn't always possible due to the nature of Temporal objects.
+   * In such cases, a TypeError will be thrown.
+   */
+  toNumber(): number {
+    const value = this.value;
+
+    if (typeof value === "number") {
+      return value;
+    }
+
+    if (value instanceof Date) {
+      return value.getTime();
+    }
+
+    if (isTemporal(value, "PlainDateTime") || isTemporal(value, "PlainDate")) {
+      return value.toZonedDateTime("UTC").epochMilliseconds;
+    }
+
+    throw new TypeError("Unwrapping a non-number value as a number");
+  }
+
   /**
    * Format this `FluentDateTime` to a string.
    */
   toString(scope: Scope): string {
     try {
       const dtf = scope.memoizeIntlObject(Intl.DateTimeFormat, this.opts);
-      return dtf.format(this.value);
+      return dtf.format(this.value as Parameters<Intl.DateTimeFormat["format"]>[0]);
     } catch (err) {
       scope.reportError(err);
-      return new Date(this.value).toISOString();
+      if (typeof this.value === "number" || this.value instanceof Date) {
+        return new Date(this.value).toISOString();
+      } else {
+        return this.value.toString();
+      }
     }
   }
 }