@formkit/tempo 0.0.2 → 0.0.3

package/dist/index.d.cts

@@ -113,6 +113,32 @@ interface ParseOptions {
      */
     dateOverflow?: "forward" | "backward" | "throw";
 }
+interface FormatOptions {
+    /**
+     * A date object or ISO 8601 string.
+     */
+    date: DateInput;
+    /**
+     * A format string or object.
+     */
+    format: Format;
+    /**
+     * A locale or en by default.
+     */
+    locale?: "en";
+    /**
+     * Whether or not to escape literals.
+     */
+    genitive?: false;
+    /**
+     * A function to filter parts.
+     */
+    tz?: string;
+    /**
+     * A function to filter parts.
+     */
+    partFilter?: (part: Part) => boolean;
+}
 
 /**
  * Returns a new date object 1/n days after the original one.
@@ -200,33 +226,35 @@ declare function dayStart(inputDate: DateInput): Date;
 
 /**
  * Produce a formatted string. Available strings:
- *
- * YY - 2 digit year
- * YYYY - 4 digit year
- * M - The month 1-12
- * MM - The month 01-12
- * MMM - Short name Jan-Dec
- * MMMM - Full name January - December
- * D - The day of the month 1-31
- * DD - The day of the month 01-31
- * d - Single digit day "T"
- * ddd - Short day name Thu
- * dddd - Full day name Wednesday
- * H - Minimum hour digits, 24 hour, 0-23
- * HH - 2 hour digits, 24 hour, 00-23
- * h - Minimum hour digits, 12 hour clock, 1-12
- * hh - 2 hour digits, 12 hour clock, 01-12
- * m - The minute 0-59
- * mm - The minute 00-59
- * s - The second 0-59
- * ss - The second 00-59
- * a - am/pm
- * A - AM/PM
- * Z - +0800, +0530, -1345
+ * token | description
+ * ------|------------
+ * YY | 2 digit year
+ * YYYY | 4 digit year
+ * M | The month 1-12
+ * MM | The month 01-12
+ * MMM | Short name Jan-Dec
+ * MMMM | Full name January | December
+ * D | The day of the month 1-31
+ * DD | The day of the month 01-31
+ * d | Single digit day "T"
+ * ddd | Short day name Thu
+ * dddd | Full day name Wednesday
+ * H | Minimum hour digits, 24 hour, 0-23
+ * HH | 2 hour digits, 24 hour, 00-23
+ * h | Minimum hour digits, 12 hour clock, 1-12
+ * hh | 2 hour digits, 12 hour clock, 01-12
+ * m | The minute 0-59
+ * mm | The minute 00-59
+ * s | The second 0-59
+ * ss | The second 00-59
+ * a | am/pm
+ * A | AM/PM
+ * Z | +0800, +0530, -1345
  *
  * @param inputDate - A date object or ISO 8601 string
  * @param format - A format
  */
+declare function format(options: FormatOptions): string;
 declare function format(inputDate: DateInput, format?: Format, locale?: string, genitive?: boolean, partFilter?: (part: Part) => boolean): string;
 
 /**
@@ -287,8 +315,8 @@ declare function nearestDay(inputDate: DateInput, search: (date: Date) => boolea
  * ISO8601 compatible offsets like -0800 or +0530.
  *
  * @param dateInput - The date on which to determine the offset.
- * @param tzA - The second timezone to compare determine the offset between.
- * @param tzB - The first timezone to compare determine the offset between.
+ * @param tzA - (default: UTC) The second timezone to compare determine the offset between.
+ * @param tzB - (default: device) The first timezone to compare determine the offset between.
  */
 declare function offset(utcTime: DateInput, tzA?: string, tzB?: string): string;
 
@@ -349,4 +377,4 @@ declare function weekStart(inputDate: DateInput, startOfWeekDay?: number): Date;
  */
 declare function yearDays(inputDate: DateInput): number;
 
-export { type DateInput, type FilledPart, type Format, type FormatPattern, type FormatStyle, type FormatStyleObj, type FormatToken, type NamedFormatOption, type NamedFormats, type ParseOptions, type Part, addDay, addHour, addMinute, addMonth, addSecond, addYear, ap, applyOffset, date, dayEnd, dayOfYear, dayStart, format, formatStr, fourDigitYear, iso8601, monthDays, monthEnd, monthStart, nearestDay, offset, parse, parts, range, removeOffset, sameDay, weekEnd, weekStart, yearDays };
+export { type DateInput, type FilledPart, type Format, type FormatOptions, type FormatPattern, type FormatStyle, type FormatStyleObj, type FormatToken, type NamedFormatOption, type NamedFormats, type ParseOptions, type Part, addDay, addHour, addMinute, addMonth, addSecond, addYear, ap, applyOffset, date, dayEnd, dayOfYear, dayStart, format, formatStr, fourDigitYear, iso8601, monthDays, monthEnd, monthStart, nearestDay, offset, parse, parts, range, removeOffset, sameDay, weekEnd, weekStart, yearDays };

package/dist/index.d.ts

@@ -113,6 +113,32 @@ interface ParseOptions {
      */
     dateOverflow?: "forward" | "backward" | "throw";
 }
+interface FormatOptions {
+    /**
+     * A date object or ISO 8601 string.
+     */
+    date: DateInput;
+    /**
+     * A format string or object.
+     */
+    format: Format;
+    /**
+     * A locale or en by default.
+     */
+    locale?: "en";
+    /**
+     * Whether or not to escape literals.
+     */
+    genitive?: false;
+    /**
+     * A function to filter parts.
+     */
+    tz?: string;
+    /**
+     * A function to filter parts.
+     */
+    partFilter?: (part: Part) => boolean;
+}
 
 /**
  * Returns a new date object 1/n days after the original one.
@@ -200,33 +226,35 @@ declare function dayStart(inputDate: DateInput): Date;
 
 /**
  * Produce a formatted string. Available strings:
- *
- * YY - 2 digit year
- * YYYY - 4 digit year
- * M - The month 1-12
- * MM - The month 01-12
- * MMM - Short name Jan-Dec
- * MMMM - Full name January - December
- * D - The day of the month 1-31
- * DD - The day of the month 01-31
- * d - Single digit day "T"
- * ddd - Short day name Thu
- * dddd - Full day name Wednesday
- * H - Minimum hour digits, 24 hour, 0-23
- * HH - 2 hour digits, 24 hour, 00-23
- * h - Minimum hour digits, 12 hour clock, 1-12
- * hh - 2 hour digits, 12 hour clock, 01-12
- * m - The minute 0-59
- * mm - The minute 00-59
- * s - The second 0-59
- * ss - The second 00-59
- * a - am/pm
- * A - AM/PM
- * Z - +0800, +0530, -1345
+ * token | description
+ * ------|------------
+ * YY | 2 digit year
+ * YYYY | 4 digit year
+ * M | The month 1-12
+ * MM | The month 01-12
+ * MMM | Short name Jan-Dec
+ * MMMM | Full name January | December
+ * D | The day of the month 1-31
+ * DD | The day of the month 01-31
+ * d | Single digit day "T"
+ * ddd | Short day name Thu
+ * dddd | Full day name Wednesday
+ * H | Minimum hour digits, 24 hour, 0-23
+ * HH | 2 hour digits, 24 hour, 00-23
+ * h | Minimum hour digits, 12 hour clock, 1-12
+ * hh | 2 hour digits, 12 hour clock, 01-12
+ * m | The minute 0-59
+ * mm | The minute 00-59
+ * s | The second 0-59
+ * ss | The second 00-59
+ * a | am/pm
+ * A | AM/PM
+ * Z | +0800, +0530, -1345
  *
  * @param inputDate - A date object or ISO 8601 string
  * @param format - A format
  */
+declare function format(options: FormatOptions): string;
 declare function format(inputDate: DateInput, format?: Format, locale?: string, genitive?: boolean, partFilter?: (part: Part) => boolean): string;
 
 /**
@@ -287,8 +315,8 @@ declare function nearestDay(inputDate: DateInput, search: (date: Date) => boolea
  * ISO8601 compatible offsets like -0800 or +0530.
  *
  * @param dateInput - The date on which to determine the offset.
- * @param tzA - The second timezone to compare determine the offset between.
- * @param tzB - The first timezone to compare determine the offset between.
+ * @param tzA - (default: UTC) The second timezone to compare determine the offset between.
+ * @param tzB - (default: device) The first timezone to compare determine the offset between.
  */
 declare function offset(utcTime: DateInput, tzA?: string, tzB?: string): string;
 
@@ -349,4 +377,4 @@ declare function weekStart(inputDate: DateInput, startOfWeekDay?: number): Date;
  */
 declare function yearDays(inputDate: DateInput): number;
 
-export { type DateInput, type FilledPart, type Format, type FormatPattern, type FormatStyle, type FormatStyleObj, type FormatToken, type NamedFormatOption, type NamedFormats, type ParseOptions, type Part, addDay, addHour, addMinute, addMonth, addSecond, addYear, ap, applyOffset, date, dayEnd, dayOfYear, dayStart, format, formatStr, fourDigitYear, iso8601, monthDays, monthEnd, monthStart, nearestDay, offset, parse, parts, range, removeOffset, sameDay, weekEnd, weekStart, yearDays };
+export { type DateInput, type FilledPart, type Format, type FormatOptions, type FormatPattern, type FormatStyle, type FormatStyleObj, type FormatToken, type NamedFormatOption, type NamedFormats, type ParseOptions, type Part, addDay, addHour, addMinute, addMonth, addSecond, addYear, ap, applyOffset, date, dayEnd, dayOfYear, dayStart, format, formatStr, fourDigitYear, iso8601, monthDays, monthEnd, monthStart, nearestDay, offset, parse, parts, range, removeOffset, sameDay, weekEnd, weekStart, yearDays };

package/dist/index.mjs

@@ -563,13 +563,82 @@ function partStyle(locale, part, value) {
   return formats ? formats[part][value] : void 0;
 }
 
+// src/deviceTZ.ts
+function deviceTZ() {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+// src/offset.ts
+function relativeTime(d, timeZone) {
+  const utcParts = new Intl.DateTimeFormat("en-US", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    timeZone,
+    hourCycle: "h23"
+  }).formatToParts(d).map(normStr);
+  const parts2 = {};
+  utcParts.forEach((part) => {
+    parts2[part.type] = part.value;
+  });
+  return /* @__PURE__ */ new Date(
+    `${parts2.year}-${parts2.month}-${parts2.day}T${parts2.hour}:${parts2.minute}:${parts2.second}Z`
+  );
+}
+function offset(utcTime, tzA = "UTC", tzB = "device") {
+  tzB = tzB === "device" ? deviceTZ() : tzB;
+  const d = date(utcTime);
+  const timeA = relativeTime(d, tzA);
+  const timeB = relativeTime(d, tzB);
+  const timeDiffInMins = (timeB.getTime() - timeA.getTime()) / 1e3 / 60;
+  return minsToOffset(timeDiffInMins);
+}
+
+// src/removeOffset.ts
+function removeOffset(dateInput, offset2 = "+0000") {
+  const positive = offset2.slice(0, 1) === "+";
+  return applyOffset(
+    dateInput,
+    offset2.replace(positive ? "+" : "-", positive ? "-" : "+")
+  );
+}
+
+// src/deviceLocale.ts
+function deviceLocale() {
+  return Intl.DateTimeFormat().resolvedOptions().locale;
+}
+
 // src/format.ts
-function format(inputDate, format2 = "long", locale = "en", genitive = false, partFilter = () => true) {
+function format(inputDateOrOptions, format2 = "long", locale = "device", genitive = false, partFilter) {
+  let tz;
+  if (typeof inputDateOrOptions === "object" && !(inputDateOrOptions instanceof Date)) {
+    ;
+    ({
+      date: inputDateOrOptions,
+      format: format2,
+      locale,
+      genitive,
+      partFilter,
+      tz
+    } = inputDateOrOptions);
+  }
   if (format2 === "ISO8601")
-    return date(inputDate).toISOString();
+    return date(inputDateOrOptions).toISOString();
+  if (tz) {
+    inputDateOrOptions = removeOffset(
+      inputDateOrOptions,
+      offset(inputDateOrOptions, tz)
+    );
+  }
+  if (!locale || locale === "device") {
+    locale = deviceLocale();
+  }
   return fill(
-    inputDate,
-    parts(format2, locale).filter(partFilter),
+    inputDateOrOptions,
+    parts(format2, locale).filter(partFilter != null ? partFilter : () => true),
     locale,
     genitive
   ).map((p) => p.value).join("");
@@ -644,35 +713,6 @@ function nearestDay(inputDate, search, constraint = 7) {
   return null;
 }
 
-// src/offset.ts
-function offset(utcTime, tzA = "UTC", tzB = "browser") {
-  tzB = tzB === "browser" ? Intl.DateTimeFormat().resolvedOptions().timeZone : tzB;
-  const d = date(utcTime);
-  const relativeTime = (timeZone) => {
-    const utcParts = new Intl.DateTimeFormat("en-US", {
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
-      hour: "2-digit",
-      minute: "2-digit",
-      second: "2-digit",
-      timeZone,
-      hourCycle: "h23"
-    }).formatToParts(d).map(normStr);
-    const parts2 = {};
-    utcParts.forEach((part) => {
-      parts2[part.type] = part.value;
-    });
-    return /* @__PURE__ */ new Date(
-      `${parts2.year}-${parts2.month}-${parts2.day}T${parts2.hour}:${parts2.minute}:${parts2.second}Z`
-    );
-  };
-  const timeA = relativeTime(tzA);
-  const timeB = relativeTime(tzB);
-  const timeDiffInMins = (timeB.getTime() - timeA.getTime()) / 1e3 / 60;
-  return minsToOffset(timeDiffInMins);
-}
-
 // src/range.ts
 function range(token, locale = "en", genitive = false) {
   const r = (n, c) => Array(n).fill("").map((_, i) => `${c(i)}`);
@@ -867,15 +907,6 @@ function parseParts(dateStr, formatParts) {
   return parsed;
 }
 
-// src/removeOffset.ts
-function removeOffset(dateInput, offset2 = "+0000") {
-  const positive = offset2.slice(0, 1) === "+";
-  return applyOffset(
-    dateInput,
-    offset2.replace(positive ? "+" : "-", positive ? "-" : "+")
-  );
-}
-
 // src/sameDay.ts
 function sameDay(inputDateA, inputDateB) {
   const a = date(inputDateA);