@formkit/tempo 0.0.2 → 0.0.4

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?: string;
+    /**
+     * Whether or not to escape literals.
+     */
+    genitive?: boolean;
+    /**
+     * 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.
@@ -179,6 +205,18 @@ declare function applyOffset(dateInput: DateInput, offset?: string): Date;
  */
 declare function date(date?: DateInput): Date;
 
+/**
+ * Creates a date object for the input date at the given timezone. For example
+ * `tzDate("2017-05-06T12:00", "Europe/Amsterdam")` will return a date object
+ * for 2017-05-06T10:00:00Z since 12:00 in Amsterdam is 10:00Z.
+ *
+ * If given a Date object it will use local time and convert it to the given
+ * timezone, thus "changing" the date.
+ * @param inputDate - An iso8601 date string with no timezone
+ * @param tz - A timezone string
+ */
+declare function tzDate(inputDate: DateInput, tz: string): Date;
+
 /**
  * Gets the what day of the year a given date is. For example, August 1st is
  * the 213th day of the year on non-leapyears and 214th on leapyears.
@@ -200,33 +238,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 +327,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 +389,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, tzDate, 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?: string;
+    /**
+     * Whether or not to escape literals.
+     */
+    genitive?: boolean;
+    /**
+     * 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.
@@ -179,6 +205,18 @@ declare function applyOffset(dateInput: DateInput, offset?: string): Date;
  */
 declare function date(date?: DateInput): Date;
 
+/**
+ * Creates a date object for the input date at the given timezone. For example
+ * `tzDate("2017-05-06T12:00", "Europe/Amsterdam")` will return a date object
+ * for 2017-05-06T10:00:00Z since 12:00 in Amsterdam is 10:00Z.
+ *
+ * If given a Date object it will use local time and convert it to the given
+ * timezone, thus "changing" the date.
+ * @param inputDate - An iso8601 date string with no timezone
+ * @param tz - A timezone string
+ */
+declare function tzDate(inputDate: DateInput, tz: string): Date;
+
 /**
  * Gets the what day of the year a given date is. For example, August 1st is
  * the 213th day of the year on non-leapyears and 214th on leapyears.
@@ -200,33 +238,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 +327,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 +389,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, tzDate, weekEnd, weekStart, yearDays };

package/dist/index.mjs

@@ -341,6 +341,46 @@ function applyOffset(dateInput, offset2 = "+0000") {
   return new Date(d.getTime() + timeDiffInMins * 1e3 * 60);
 }
 
+// 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/tzDate.ts
+function tzDate(inputDate, tz) {
+  const d = date(inputDate);
+  return applyOffset(d, offset(d, tz));
+}
+
 // src/dayOfYear.ts
 function dayOfYear(inputDate) {
   const d = date(inputDate);
@@ -563,13 +603,48 @@ function partStyle(locale, part, value) {
   return formats ? formats[part][value] : void 0;
 }
 
+// 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 +719,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 +913,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);
@@ -928,6 +965,7 @@ export {
   range,
   removeOffset,
   sameDay,
+  tzDate,
   weekEnd,
   weekStart,
   yearDays