@pbkware/dot-net-date-number-formatting 0.2.0

package/src/code/datetime-formatter.ts

@@ -0,0 +1,718 @@
+import { Err, Ok, Result } from "@pbkware/js-utils";
+import {
+  DotNetDateTimeStyleId,
+  DotNetDateTimeStyleSet,
+  DotNetDateTimeStyles,
+} from "./datetime-style.js";
+import { DotNetLocaleSettings } from "./locale-settings.js";
+
+type ElementType =
+  | "standard"
+  | "day"
+  | "day2"
+  | "dayNameShort"
+  | "dayNameLong"
+  | "month"
+  | "month2"
+  | "monthNameShort"
+  | "monthNameLong"
+  | "year2"
+  | "year3"
+  | "year4"
+  | "year5"
+  | "hour12"
+  | "hour12_2"
+  | "hour24"
+  | "hour24_2"
+  | "minute"
+  | "minute2"
+  | "second"
+  | "second2"
+  | "fraction"
+  | "fractionTrim"
+  | "amPm1"
+  | "amPm2"
+  | "dateSep"
+  | "timeSep"
+  | "literal";
+
+interface Element {
+  type: ElementType;
+  len?: number;
+  text?: string;
+}
+
+const dayNamesShort = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const dayNamesLong = [
+  "Sunday",
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+  "Saturday",
+];
+const monthNamesShort = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+];
+const monthNamesLong = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+
+function pad(value: number, len: number): string {
+  return value.toString().padStart(len, "0");
+}
+
+function formatStandard(token: string, date: Date, locale: string): string {
+  switch (token) {
+    case "d":
+      return new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(
+        date,
+      );
+    case "D":
+      return new Intl.DateTimeFormat(locale, { dateStyle: "full" }).format(
+        date,
+      );
+    case "f":
+      return new Intl.DateTimeFormat(locale, {
+        dateStyle: "full",
+        timeStyle: "short",
+      }).format(date);
+    case "F":
+      return new Intl.DateTimeFormat(locale, {
+        dateStyle: "full",
+        timeStyle: "medium",
+      }).format(date);
+    case "g":
+      return new Intl.DateTimeFormat(locale, {
+        dateStyle: "short",
+        timeStyle: "short",
+      }).format(date);
+    case "G":
+      return new Intl.DateTimeFormat(locale, {
+        dateStyle: "short",
+        timeStyle: "medium",
+      }).format(date);
+    case "M":
+    case "m":
+      return `${monthNamesLong[date.getMonth()]} ${date.getDate()}`;
+    case "O":
+    case "o":
+      return date.toISOString();
+    case "s":
+      return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1, 2)}-${pad(date.getDate(), 2)}T${pad(date.getHours(), 2)}:${pad(date.getMinutes(), 2)}:${pad(date.getSeconds(), 2)}`;
+    case "t":
+      return new Intl.DateTimeFormat(locale, { timeStyle: "short" }).format(
+        date,
+      );
+    case "T":
+      return new Intl.DateTimeFormat(locale, { timeStyle: "medium" }).format(
+        date,
+      );
+    case "u":
+      return date.toISOString().replace("T", " ").replace("Z", "Z");
+    case "Y":
+    case "y":
+      return `${pad(date.getFullYear(), 4)} ${monthNamesLong[date.getMonth()]}`;
+    default:
+      return "?";
+  }
+}
+
+function tokenizeCustom(format: string): Result<Element[]> {
+  const elements: Element[] = [];
+  let index = 0;
+
+  const pushLiteral = (text: string) => {
+    if (text.length > 0) {
+      elements.push({ type: "literal", text });
+    }
+  };
+
+  while (index < format.length) {
+    const current = format[index];
+
+    if (current === "'" || current === '"') {
+      const quote = current;
+      index += 1;
+      let literal = "";
+      while (index < format.length && format[index] !== quote) {
+        literal += format[index];
+        index += 1;
+      }
+      if (index >= format.length) {
+        return new Err("Unterminated quoted literal in format");
+      }
+      index += 1;
+      pushLiteral(literal);
+      continue;
+    }
+
+    if (current === "\\") {
+      index += 1;
+      if (index >= format.length) {
+        return new Err("Single-char literal escape at end of format");
+      }
+      pushLiteral(format[index]);
+      index += 1;
+      continue;
+    }
+
+    if (current === "%") {
+      index += 1;
+      continue;
+    }
+
+    let runLength = 1;
+    while (
+      index + runLength < format.length &&
+      format[index + runLength] === current
+    ) {
+      runLength += 1;
+    }
+
+    const consume = () => {
+      index += runLength;
+    };
+
+    switch (current) {
+      case "d":
+        if (runLength === 1) elements.push({ type: "day" });
+        else if (runLength === 2) elements.push({ type: "day2" });
+        else if (runLength === 3) elements.push({ type: "dayNameShort" });
+        else if (runLength === 4) elements.push({ type: "dayNameLong" });
+        else return new Err("Too many repeated d characters");
+        consume();
+        break;
+      case "M":
+        if (runLength === 1) elements.push({ type: "month" });
+        else if (runLength === 2) elements.push({ type: "month2" });
+        else if (runLength === 3) elements.push({ type: "monthNameShort" });
+        else if (runLength === 4) elements.push({ type: "monthNameLong" });
+        else return new Err("Too many repeated M characters");
+        consume();
+        break;
+      case "y":
+        if (runLength === 1 || runLength === 2)
+          elements.push({ type: "year2" });
+        else if (runLength === 3) elements.push({ type: "year3" });
+        else if (runLength === 4) elements.push({ type: "year4" });
+        else if (runLength === 5) elements.push({ type: "year5" });
+        else return new Err("Too many repeated y characters");
+        consume();
+        break;
+      case "h":
+        elements.push({ type: runLength === 1 ? "hour12" : "hour12_2" });
+        consume();
+        break;
+      case "H":
+        elements.push({ type: runLength === 1 ? "hour24" : "hour24_2" });
+        consume();
+        break;
+      case "m":
+        elements.push({ type: runLength === 1 ? "minute" : "minute2" });
+        consume();
+        break;
+      case "s":
+        elements.push({ type: runLength === 1 ? "second" : "second2" });
+        consume();
+        break;
+      case "f":
+        elements.push({ type: "fraction", len: Math.min(runLength, 7) });
+        consume();
+        break;
+      case "F":
+        elements.push({ type: "fractionTrim", len: Math.min(runLength, 7) });
+        consume();
+        break;
+      case "t":
+        elements.push({ type: runLength === 1 ? "amPm1" : "amPm2" });
+        consume();
+        break;
+      case "/":
+        elements.push({ type: "dateSep" });
+        consume();
+        break;
+      case ":":
+        elements.push({ type: "timeSep" });
+        consume();
+        break;
+      default:
+        pushLiteral(current.repeat(runLength));
+        consume();
+        break;
+    }
+  }
+
+  return new Ok(elements);
+}
+
+/**
+ * Formatter for dates and times using .NET-compatible format strings.
+ *
+ * Supports both standard format strings (d, D, f, F, g, G, M, O, s, t, T, u, Y) and
+ * custom format strings with specific date/time components (yyyy, MM, dd, HH, mm, ss, etc.).
+ *
+ * @example
+ * ```typescript
+ * const formatter = new DotNetDateTimeFormatter();
+ * formatter.localeSettings = DotNetLocaleSettings.createInvariant();
+ *
+ * // Standard format strings
+ * formatter.trySetFormat('d');  // Short date
+ * console.log(formatter.toString(new Date(2024, 6, 5)));  // "7/5/2024"
+ *
+ * formatter.trySetFormat('F');  // Full date/time
+ * console.log(formatter.toString(new Date(2024, 6, 5, 14, 30, 0)));
+ * // "Friday, July 5, 2024 2:30:00 PM"
+ *
+ * // Custom format strings
+ * formatter.trySetFormat('yyyy-MM-dd');
+ * console.log(formatter.toString(new Date(2024, 6, 5)));  // "2024-07-05"
+ *
+ * formatter.trySetFormat("dddd, MMMM d 'at' h:mm tt");
+ * console.log(formatter.toString(new Date(2024, 6, 5, 14, 30, 0)));
+ * // "Friday, July 5 at 2:30 PM"
+ * ```
+ *
+ * @public
+ * @category DateTime Formatting
+ */
+export class DotNetDateTimeFormatter {
+  /**
+   * Set of date/time style flags that are not currently supported by this implementation.
+   * Operations using these styles will fail.
+   */
+  static readonly unsupportedStyles = new Set<DotNetDateTimeStyleId>([
+    DotNetDateTimeStyleId.AdjustToUniversal,
+    DotNetDateTimeStyleId.AssumeLocal,
+    DotNetDateTimeStyleId.AssumeUniversal,
+    DotNetDateTimeStyleId.RoundTripKind,
+  ]);
+
+  private format = "";
+
+  /**
+   * The set of {@link DotNetDateTimeStyleId} flags that control date/time parsing behavior.
+   * Currently only used for future parsing functionality.
+   */
+  styles: DotNetDateTimeStyleSet = new Set(DotNetDateTimeStyles.none);
+
+  /**
+   * The locale settings that determine date/time separators and formatting conventions.
+   */
+  localeSettings = DotNetLocaleSettings.current;
+
+  private formatIsStandard = false;
+  private elements: Element[] = [];
+
+  /**
+   * Contains the error message from the last failed operation.
+   * Check this property if {@link DotNetDateTimeFormatter.trySetFormat} returns an error.
+   */
+  parseErrorText = "";
+
+  /**
+   * Sets the format string to use for formatting dates and times.
+   *
+   * The format string is tokenized to confirm validity and to optimize formatting/parsing operations.
+   *
+   * @param value - A standard format string (single character like 'd', 'F', 'o') or
+   *                custom format string (e.g., "yyyy-MM-dd HH:mm:ss").
+   * @returns A Result indicating success or containing an error message if the format string is invalid.
+   *
+   * @example
+   * ```typescript
+   * // Standard format
+   * formatter.trySetFormat('d');  // Short date
+   *
+   * // Custom format
+   * formatter.trySetFormat('yyyy-MM-dd HH:mm:ss');
+   *
+   * // Check for errors
+   * const result = formatter.trySetFormat('');
+   * if (result.isErr()) {
+   *   console.error(result.error);  // "Format text cannot be empty"
+   * }
+   * ```
+   */
+  trySetFormat(value: string): Result<void> {
+    if (value.length === 0) {
+      return new Err("Format text cannot be empty");
+    }
+
+    this.format = value;
+    this.formatIsStandard = value.length === 1;
+
+    if (this.formatIsStandard) {
+      this.elements = [{ type: "standard", text: value }];
+      return new Ok(undefined);
+    }
+
+    const parsed = tokenizeCustom(value);
+    if (parsed.isErr()) {
+      return parsed.createType<void>();
+    }
+
+    this.elements = parsed.value;
+    return new Ok(undefined);
+  }
+
+  /**
+   * Formats a Date using the current format string.
+   *
+   * @param value - The Date to format.
+   * @returns The formatted date/time string.
+   *
+   * @example
+   * ```typescript
+   * const date = new Date(2024, 6, 5, 14, 30, 45);
+   *
+   * formatter.trySetFormat('d');
+   * console.log(formatter.toString(date));  // "7/5/2024"
+   *
+   * formatter.trySetFormat('yyyy-MM-dd HH:mm:ss');
+   * console.log(formatter.toString(date));  // "2024-07-05 14:30:45"
+   * ```
+   */
+  toString(value: Date): string {
+    if (this.formatIsStandard) {
+      return formatStandard(this.format, value, this.localeSettings.name);
+    }
+
+    let result = "";
+    const hour = value.getHours();
+    const hour12 = hour % 12 === 0 ? 12 : hour % 12;
+
+    for (const element of this.elements) {
+      switch (element.type) {
+        case "day":
+          result += value.getDate().toString();
+          break;
+        case "day2":
+          result += pad(value.getDate(), 2);
+          break;
+        case "dayNameShort":
+          result += dayNamesShort[value.getDay()];
+          break;
+        case "dayNameLong":
+          result += dayNamesLong[value.getDay()];
+          break;
+        case "month":
+          result += (value.getMonth() + 1).toString();
+          break;
+        case "month2":
+          result += pad(value.getMonth() + 1, 2);
+          break;
+        case "monthNameShort":
+          result += monthNamesShort[value.getMonth()];
+          break;
+        case "monthNameLong":
+          result += monthNamesLong[value.getMonth()];
+          break;
+        case "year2":
+          result += (value.getFullYear() % 100).toString();
+          break;
+        case "year3":
+          result += pad(value.getFullYear(), 3);
+          break;
+        case "year4":
+          result += pad(value.getFullYear(), 4);
+          break;
+        case "year5":
+          result += pad(value.getFullYear(), 5);
+          break;
+        case "hour12":
+          result += hour12.toString();
+          break;
+        case "hour12_2":
+          result += pad(hour12, 2);
+          break;
+        case "hour24":
+          result += hour.toString();
+          break;
+        case "hour24_2":
+          result += pad(hour, 2);
+          break;
+        case "minute":
+          result += value.getMinutes().toString();
+          break;
+        case "minute2":
+          result += pad(value.getMinutes(), 2);
+          break;
+        case "second":
+          result += value.getSeconds().toString();
+          break;
+        case "second2":
+          result += pad(value.getSeconds(), 2);
+          break;
+        case "fraction": {
+          const ms = pad(value.getMilliseconds(), 3);
+          result += (ms + "0000000").slice(0, element.len ?? 3);
+          break;
+        }
+        case "fractionTrim": {
+          const ms = pad(value.getMilliseconds(), 3);
+          result += (ms + "0000000")
+            .slice(0, element.len ?? 3)
+            .replace(/0+$/, "");
+          break;
+        }
+        case "amPm1":
+          result += hour < 12 ? "A" : "P";
+          break;
+        case "amPm2":
+          result += hour < 12 ? "AM" : "PM";
+          break;
+        case "dateSep":
+          result += this.localeSettings.dateSeparator;
+          break;
+        case "timeSep":
+          result += this.localeSettings.timeSeparator;
+          break;
+        case "literal":
+          result += element.text ?? "";
+          break;
+        case "standard":
+          result += formatStandard(
+            element.text ?? "",
+            value,
+            this.localeSettings.name,
+          );
+          break;
+      }
+    }
+
+    return result;
+  }
+
+  tryFromString(strValue: string): Result<Date> {
+    let parseText = strValue;
+
+    if (
+      this.styles.has(DotNetDateTimeStyleId.AllowLeadingWhite) &&
+      this.styles.has(DotNetDateTimeStyleId.AllowTrailingWhite)
+    ) {
+      parseText = parseText.trim();
+    } else if (this.styles.has(DotNetDateTimeStyleId.AllowLeadingWhite)) {
+      parseText = parseText.trimStart();
+    } else if (this.styles.has(DotNetDateTimeStyleId.AllowTrailingWhite)) {
+      parseText = parseText.trimEnd();
+    }
+
+    if (parseText.length === 0) {
+      return new Err("DateTime string is empty");
+    }
+
+    if (this.formatIsStandard) {
+      const parsed = new Date(parseText);
+      if (Number.isNaN(parsed.getTime())) {
+        return new Err("Invalid Date string");
+      }
+      return new Ok(parsed);
+    }
+
+    const regexParts: string[] = ["^"];
+    const setters: Array<
+      (
+        match: string,
+        state: {
+          y: number;
+          m: number;
+          d: number;
+          hh: number;
+          mm: number;
+          ss: number;
+          ms: number;
+          ampm: number;
+        },
+      ) => void
+    > = [];
+
+    for (const element of this.elements) {
+      switch (element.type) {
+        case "day":
+        case "day2":
+          regexParts.push("(\\d{1,2})");
+          setters.push((v, s) => {
+            s.d = Number.parseInt(v, 10);
+          });
+          break;
+        case "month":
+        case "month2":
+          regexParts.push("(\\d{1,2})");
+          setters.push((v, s) => {
+            s.m = Number.parseInt(v, 10);
+          });
+          break;
+        case "year2":
+          regexParts.push("(\\d{1,2})");
+          setters.push((v, s) => {
+            const yr = Number.parseInt(v, 10);
+            s.y = yr < 50 ? 2000 + yr : 1900 + yr;
+          });
+          break;
+        case "year3":
+        case "year4":
+        case "year5":
+          regexParts.push("(\\d{3,5})");
+          setters.push((v, s) => {
+            s.y = Number.parseInt(v, 10);
+          });
+          break;
+        case "hour12":
+        case "hour12_2":
+          regexParts.push("(\\d{1,2})");
+          setters.push((v, s) => {
+            s.hh = Number.parseInt(v, 10);
+          });
+          break;
+        case "hour24":
+        case "hour24_2":
+          regexParts.push("(\\d{1,2})");
+          setters.push((v, s) => {
+            s.hh = Number.parseInt(v, 10);
+          });
+          break;
+        case "minute":
+        case "minute2":
+          regexParts.push("(\\d{1,2})");
+          setters.push((v, s) => {
+            s.mm = Number.parseInt(v, 10);
+          });
+          break;
+        case "second":
+        case "second2":
+          regexParts.push("(\\d{1,2})");
+          setters.push((v, s) => {
+            s.ss = Number.parseInt(v, 10);
+          });
+          break;
+        case "fraction":
+        case "fractionTrim":
+          regexParts.push("(\\d{1,7})");
+          setters.push((v, s) => {
+            s.ms = Number.parseInt((v + "000").slice(0, 3), 10);
+          });
+          break;
+        case "amPm1":
+          regexParts.push("([APap])");
+          setters.push((v, s) => {
+            s.ampm = v.toUpperCase() === "P" ? 2 : 1;
+          });
+          break;
+        case "amPm2":
+          regexParts.push("(AM|PM|am|pm)");
+          setters.push((v, s) => {
+            s.ampm = v.toUpperCase() === "PM" ? 2 : 1;
+          });
+          break;
+        case "dayNameShort":
+          regexParts.push(`(${dayNamesShort.join("|")})`);
+          setters.push(() => undefined);
+          break;
+        case "dayNameLong":
+          regexParts.push(`(${dayNamesLong.join("|")})`);
+          setters.push(() => undefined);
+          break;
+        case "monthNameShort":
+          regexParts.push(`(${monthNamesShort.join("|")})`);
+          setters.push((v, s) => {
+            s.m =
+              monthNamesShort.findIndex(
+                (x) => x.toLowerCase() === v.toLowerCase(),
+              ) + 1;
+          });
+          break;
+        case "monthNameLong":
+          regexParts.push(`(${monthNamesLong.join("|")})`);
+          setters.push((v, s) => {
+            s.m =
+              monthNamesLong.findIndex(
+                (x) => x.toLowerCase() === v.toLowerCase(),
+              ) + 1;
+          });
+          break;
+        case "dateSep":
+          regexParts.push(
+            this.localeSettings.dateSeparator.replace(
+              /[.*+?^${}()|[\]\\]/g,
+              "\\$&",
+            ),
+          );
+          break;
+        case "timeSep":
+          regexParts.push(
+            this.localeSettings.timeSeparator.replace(
+              /[.*+?^${}()|[\]\\]/g,
+              "\\$&",
+            ),
+          );
+          break;
+        case "literal":
+          regexParts.push(
+            (element.text ?? "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+          );
+          break;
+        case "standard":
+          break;
+      }
+    }
+
+    regexParts.push("$");
+    const re = new RegExp(regexParts.join(""));
+    const match = re.exec(parseText);
+    if (match === null) {
+      return new Err("DateTime string does not match all Format specifiers");
+    }
+
+    const state = { y: 1, m: 1, d: 1, hh: 0, mm: 0, ss: 0, ms: 0, ampm: 0 };
+    let group = 1;
+    for (const setter of setters) {
+      setter(match[group], state);
+      group += 1;
+    }
+
+    if (state.ampm > 0) {
+      if (state.hh === 12) state.hh = 0;
+      if (state.ampm === 2) state.hh += 12;
+    }
+
+    const value = new Date(
+      state.y,
+      state.m - 1,
+      state.d,
+      state.hh,
+      state.mm,
+      state.ss,
+      state.ms,
+    );
+    if (Number.isNaN(value.getTime())) {
+      return new Err("Year, Month or Day is invalid");
+    }
+
+    return new Ok(value);
+  }
+}