@choksheak/ts-utils 0.1.8 → 0.1.9

package/dateTimeStr.d.ts

@@ -1,14 +1,8 @@
-export declare class DateTimeStr {
-    static yyyyMmDd(dt?: Date, separator?: string): string;
-    static hhMmSs(dt?: Date, separator?: string): string;
-    static hhMmSsMs(dt?: Date, timeSeparator?: string, msSeparator?: string): string;
-    static tz(dt?: Date): string;
-    /** Full local date/time string. */
-    static local(dt?: Date, dateSeparator?: string, dtSeparator?: string, timeSeparator?: string, msSeparator?: string): string;
-    /** Use the default ISO string function to keep things simple here. */
-    static utc(dt?: Date): string;
-    /** Default full local date+time string with full & concise info. */
-    static get now(): string;
-    /** Default full UTC date+time string with full & concise info. */
-    static get utcNow(): string;
-}
+export declare function yyyyMmDd(dt?: Date, separator?: string): string;
+export declare function hhMmSs(dt?: Date, separator?: string): string;
+export declare function hhMmSsMs(dt?: Date, timeSeparator?: string, msSeparator?: string): string;
+export declare function tzShort(dt?: Date): string;
+export declare function getLongMonthNameZeroIndexed(month: number, locales?: Intl.LocalesArgument): string;
+export declare function getLongMonthNameOneIndexed(month: number, locales?: Intl.LocalesArgument): string;
+export declare function getShortMonthNameZeroIndexed(month: number, locales?: Intl.LocalesArgument): string;
+export declare function getShortMonthNameOneIndexed(month: number, locales?: Intl.LocalesArgument): string;

package/dateTimeStr.js

@@ -20,52 +20,64 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/dateTimeStr.ts
 var dateTimeStr_exports = {};
 __export(dateTimeStr_exports, {
-  DateTimeStr: () => DateTimeStr
+  getLongMonthNameOneIndexed: () => getLongMonthNameOneIndexed,
+  getLongMonthNameZeroIndexed: () => getLongMonthNameZeroIndexed,
+  getShortMonthNameOneIndexed: () => getShortMonthNameOneIndexed,
+  getShortMonthNameZeroIndexed: () => getShortMonthNameZeroIndexed,
+  hhMmSs: () => hhMmSs,
+  hhMmSsMs: () => hhMmSsMs,
+  tzShort: () => tzShort,
+  yyyyMmDd: () => yyyyMmDd
 });
 module.exports = __toCommonJS(dateTimeStr_exports);
-var DateTimeStr = class _DateTimeStr {
-  static yyyyMmDd(dt = /* @__PURE__ */ new Date(), separator = "-") {
-    const yr = dt.getFullYear();
-    const mth = dt.getMonth() + 1;
-    const day = dt.getDate();
-    return yr + separator + (mth < 10 ? "0" + mth : mth) + separator + (day < 10 ? "0" + day : day);
+function yyyyMmDd(dt = /* @__PURE__ */ new Date(), separator = "-") {
+  const yr = dt.getFullYear();
+  const mth = dt.getMonth() + 1;
+  const day = dt.getDate();
+  return yr + separator + (mth < 10 ? "0" + mth : mth) + separator + (day < 10 ? "0" + day : day);
+}
+function hhMmSs(dt = /* @__PURE__ */ new Date(), separator = ":") {
+  const hr = dt.getHours();
+  const min = dt.getMinutes();
+  const sec = dt.getSeconds();
+  return (hr < 10 ? "0" + hr : hr) + separator + (min < 10 ? "0" + min : min) + separator + (sec < 10 ? "0" + sec : sec);
+}
+function hhMmSsMs(dt = /* @__PURE__ */ new Date(), timeSeparator = ":", msSeparator = ".") {
+  const ms = dt.getMilliseconds();
+  return hhMmSs(dt, timeSeparator) + msSeparator + (ms < 10 ? "00" + ms : ms < 100 ? "0" + ms : ms);
+}
+function tzShort(dt = /* @__PURE__ */ new Date()) {
+  if (dt.getTimezoneOffset() === 0) {
+    return "Z";
   }
-  static hhMmSs(dt = /* @__PURE__ */ new Date(), separator = ":") {
-    const hr = dt.getHours();
-    const min = dt.getMinutes();
-    const sec = dt.getSeconds();
-    return (hr < 10 ? "0" + hr : hr) + separator + (min < 10 ? "0" + min : min) + separator + (sec < 10 ? "0" + sec : sec);
-  }
-  static hhMmSsMs(dt = /* @__PURE__ */ new Date(), timeSeparator = ":", msSeparator = ".") {
-    const ms = dt.getMilliseconds();
-    return _DateTimeStr.hhMmSs(dt, timeSeparator) + msSeparator + (ms < 10 ? "00" + ms : ms < 100 ? "0" + ms : ms);
-  }
-  static tz(dt = /* @__PURE__ */ new Date()) {
-    if (dt.getTimezoneOffset() === 0) {
-      return "Z";
-    }
-    const tzHours = dt.getTimezoneOffset() / 60;
-    return tzHours >= 0 ? "+" + tzHours : String(tzHours);
-  }
-  /** Full local date/time string. */
-  static local(dt = /* @__PURE__ */ new Date(), dateSeparator = "-", dtSeparator = " ", timeSeparator = ":", msSeparator = ".") {
-    return _DateTimeStr.yyyyMmDd(dt, dateSeparator) + dtSeparator + _DateTimeStr.hhMmSsMs(dt, timeSeparator, msSeparator) + _DateTimeStr.tz(dt);
-  }
-  /** Use the default ISO string function to keep things simple here. */
-  static utc(dt = /* @__PURE__ */ new Date()) {
-    return dt.toISOString();
-  }
-  /** Default full local date+time string with full & concise info. */
-  static get now() {
-    return _DateTimeStr.local();
-  }
-  /** Default full UTC date+time string with full & concise info. */
-  static get utcNow() {
-    return _DateTimeStr.utc();
-  }
-};
+  const tzHours = dt.getTimezoneOffset() / 60;
+  return tzHours >= 0 ? "+" + tzHours : String(tzHours);
+}
+function getLongMonthNameZeroIndexed(month, locales = "default") {
+  return new Date(2024, month, 15).toLocaleString(locales, {
+    month: "long"
+  });
+}
+function getLongMonthNameOneIndexed(month, locales = "default") {
+  return getLongMonthNameZeroIndexed(month - 1, locales);
+}
+function getShortMonthNameZeroIndexed(month, locales = "default") {
+  return new Date(2e3, month, 15).toLocaleString(locales, {
+    month: "short"
+  });
+}
+function getShortMonthNameOneIndexed(month, locales = "default") {
+  return getShortMonthNameZeroIndexed(month - 1, locales);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DateTimeStr
+  getLongMonthNameOneIndexed,
+  getLongMonthNameZeroIndexed,
+  getShortMonthNameOneIndexed,
+  getShortMonthNameZeroIndexed,
+  hhMmSs,
+  hhMmSsMs,
+  tzShort,
+  yyyyMmDd
 });
 //# sourceMappingURL=dateTimeStr.js.map

package/dateTimeStr.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/dateTimeStr.ts"],"sourcesContent":["export class DateTimeStr {\n  public static yyyyMmDd(dt = new Date(), separator = \"-\"): string {\n    const yr = dt.getFullYear();\n    const mth = dt.getMonth() + 1;\n    const day = dt.getDate();\n\n    return (\n      yr +\n      separator +\n      (mth < 10 ? \"0\" + mth : mth) +\n      separator +\n      (day < 10 ? \"0\" + day : day)\n    );\n  }\n\n  public static hhMmSs(dt = new Date(), separator = \":\"): string {\n    const hr = dt.getHours();\n    const min = dt.getMinutes();\n    const sec = dt.getSeconds();\n\n    return (\n      (hr < 10 ? \"0\" + hr : hr) +\n      separator +\n      (min < 10 ? \"0\" + min : min) +\n      separator +\n      (sec < 10 ? \"0\" + sec : sec)\n    );\n  }\n\n  public static hhMmSsMs(\n    dt = new Date(),\n    timeSeparator = \":\",\n    msSeparator = \".\",\n  ): string {\n    const ms = dt.getMilliseconds();\n\n    return (\n      DateTimeStr.hhMmSs(dt, timeSeparator) +\n      msSeparator +\n      (ms < 10 ? \"00\" + ms : ms < 100 ? \"0\" + ms : ms)\n    );\n  }\n\n  public static tz(dt = new Date()): string {\n    if (dt.getTimezoneOffset() === 0) {\n      return \"Z\";\n    }\n\n    const tzHours = dt.getTimezoneOffset() / 60;\n    return tzHours >= 0 ? \"+\" + tzHours : String(tzHours);\n  }\n\n  /** Full local date/time string. */\n  public static local(\n    dt = new Date(),\n    dateSeparator = \"-\",\n    dtSeparator = \" \",\n    timeSeparator = \":\",\n    msSeparator = \".\",\n  ): string {\n    return (\n      DateTimeStr.yyyyMmDd(dt, dateSeparator) +\n      dtSeparator +\n      DateTimeStr.hhMmSsMs(dt, timeSeparator, msSeparator) +\n      DateTimeStr.tz(dt)\n    );\n  }\n\n  /** Use the default ISO string function to keep things simple here. */\n  public static utc(dt = new Date()) {\n    return dt.toISOString();\n  }\n\n  /** Default full local date+time string with full & concise info. */\n  public static get now() {\n    return DateTimeStr.local();\n  }\n\n  /** Default full UTC date+time string with full & concise info. */\n  public static get utcNow() {\n    return DateTimeStr.utc();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,cAAN,MAAM,aAAY;AAAA,EACvB,OAAc,SAAS,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AAC/D,UAAM,KAAK,GAAG,YAAY;AAC1B,UAAM,MAAM,GAAG,SAAS,IAAI;AAC5B,UAAM,MAAM,GAAG,QAAQ;AAEvB,WACE,KACA,aACC,MAAM,KAAK,MAAM,MAAM,OACxB,aACC,MAAM,KAAK,MAAM,MAAM;AAAA,EAE5B;AAAA,EAEA,OAAc,OAAO,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AAC7D,UAAM,KAAK,GAAG,SAAS;AACvB,UAAM,MAAM,GAAG,WAAW;AAC1B,UAAM,MAAM,GAAG,WAAW;AAE1B,YACG,KAAK,KAAK,MAAM,KAAK,MACtB,aACC,MAAM,KAAK,MAAM,MAAM,OACxB,aACC,MAAM,KAAK,MAAM,MAAM;AAAA,EAE5B;AAAA,EAEA,OAAc,SACZ,KAAK,oBAAI,KAAK,GACd,gBAAgB,KAChB,cAAc,KACN;AACR,UAAM,KAAK,GAAG,gBAAgB;AAE9B,WACE,aAAY,OAAO,IAAI,aAAa,IACpC,eACC,KAAK,KAAK,OAAO,KAAK,KAAK,MAAM,MAAM,KAAK;AAAA,EAEjD;AAAA,EAEA,OAAc,GAAG,KAAK,oBAAI,KAAK,GAAW;AACxC,QAAI,GAAG,kBAAkB,MAAM,GAAG;AAChC,aAAO;AAAA,IACT;AAEA,UAAM,UAAU,GAAG,kBAAkB,IAAI;AACzC,WAAO,WAAW,IAAI,MAAM,UAAU,OAAO,OAAO;AAAA,EACtD;AAAA;AAAA,EAGA,OAAc,MACZ,KAAK,oBAAI,KAAK,GACd,gBAAgB,KAChB,cAAc,KACd,gBAAgB,KAChB,cAAc,KACN;AACR,WACE,aAAY,SAAS,IAAI,aAAa,IACtC,cACA,aAAY,SAAS,IAAI,eAAe,WAAW,IACnD,aAAY,GAAG,EAAE;AAAA,EAErB;AAAA;AAAA,EAGA,OAAc,IAAI,KAAK,oBAAI,KAAK,GAAG;AACjC,WAAO,GAAG,YAAY;AAAA,EACxB;AAAA;AAAA,EAGA,WAAkB,MAAM;AACtB,WAAO,aAAY,MAAM;AAAA,EAC3B;AAAA;AAAA,EAGA,WAAkB,SAAS;AACzB,WAAO,aAAY,IAAI;AAAA,EACzB;AACF;","names":[]}
+{"version":3,"sources":["../src/dateTimeStr.ts"],"sourcesContent":["export function yyyyMmDd(dt = new Date(), separator = \"-\"): string {\n  const yr = dt.getFullYear();\n  const mth = dt.getMonth() + 1;\n  const day = dt.getDate();\n\n  return (\n    yr +\n    separator +\n    (mth < 10 ? \"0\" + mth : mth) +\n    separator +\n    (day < 10 ? \"0\" + day : day)\n  );\n}\n\nexport function hhMmSs(dt = new Date(), separator = \":\"): string {\n  const hr = dt.getHours();\n  const min = dt.getMinutes();\n  const sec = dt.getSeconds();\n\n  return (\n    (hr < 10 ? \"0\" + hr : hr) +\n    separator +\n    (min < 10 ? \"0\" + min : min) +\n    separator +\n    (sec < 10 ? \"0\" + sec : sec)\n  );\n}\n\nexport function hhMmSsMs(\n  dt = new Date(),\n  timeSeparator = \":\",\n  msSeparator = \".\",\n): string {\n  const ms = dt.getMilliseconds();\n\n  return (\n    hhMmSs(dt, timeSeparator) +\n    msSeparator +\n    (ms < 10 ? \"00\" + ms : ms < 100 ? \"0\" + ms : ms)\n  );\n}\n\nexport function tzShort(dt = new Date()): string {\n  if (dt.getTimezoneOffset() === 0) {\n    return \"Z\";\n  }\n\n  const tzHours = dt.getTimezoneOffset() / 60;\n  return tzHours >= 0 ? \"+\" + tzHours : String(tzHours);\n}\n\nexport function getLongMonthNameZeroIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return new Date(2024, month, 15).toLocaleString(locales, {\n    month: \"long\",\n  });\n}\n\nexport function getLongMonthNameOneIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return getLongMonthNameZeroIndexed(month - 1, locales);\n}\n\nexport function getShortMonthNameZeroIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return new Date(2000, month, 15).toLocaleString(locales, {\n    month: \"short\",\n  });\n}\n\nexport function getShortMonthNameOneIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return getShortMonthNameZeroIndexed(month - 1, locales);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,SAAS,SAAS,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AACjE,QAAM,KAAK,GAAG,YAAY;AAC1B,QAAM,MAAM,GAAG,SAAS,IAAI;AAC5B,QAAM,MAAM,GAAG,QAAQ;AAEvB,SACE,KACA,aACC,MAAM,KAAK,MAAM,MAAM,OACxB,aACC,MAAM,KAAK,MAAM,MAAM;AAE5B;AAEO,SAAS,OAAO,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AAC/D,QAAM,KAAK,GAAG,SAAS;AACvB,QAAM,MAAM,GAAG,WAAW;AAC1B,QAAM,MAAM,GAAG,WAAW;AAE1B,UACG,KAAK,KAAK,MAAM,KAAK,MACtB,aACC,MAAM,KAAK,MAAM,MAAM,OACxB,aACC,MAAM,KAAK,MAAM,MAAM;AAE5B;AAEO,SAAS,SACd,KAAK,oBAAI,KAAK,GACd,gBAAgB,KAChB,cAAc,KACN;AACR,QAAM,KAAK,GAAG,gBAAgB;AAE9B,SACE,OAAO,IAAI,aAAa,IACxB,eACC,KAAK,KAAK,OAAO,KAAK,KAAK,MAAM,MAAM,KAAK;AAEjD;AAEO,SAAS,QAAQ,KAAK,oBAAI,KAAK,GAAW;AAC/C,MAAI,GAAG,kBAAkB,MAAM,GAAG;AAChC,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,GAAG,kBAAkB,IAAI;AACzC,SAAO,WAAW,IAAI,MAAM,UAAU,OAAO,OAAO;AACtD;AAEO,SAAS,4BACd,OACA,UAAgC,WACxB;AACR,SAAO,IAAI,KAAK,MAAM,OAAO,EAAE,EAAE,eAAe,SAAS;AAAA,IACvD,OAAO;AAAA,EACT,CAAC;AACH;AAEO,SAAS,2BACd,OACA,UAAgC,WACxB;AACR,SAAO,4BAA4B,QAAQ,GAAG,OAAO;AACvD;AAEO,SAAS,6BACd,OACA,UAAgC,WACxB;AACR,SAAO,IAAI,KAAK,KAAM,OAAO,EAAE,EAAE,eAAe,SAAS;AAAA,IACvD,OAAO;AAAA,EACT,CAAC;AACH;AAEO,SAAS,4BACd,OACA,UAAgC,WACxB;AACR,SAAO,6BAA6B,QAAQ,GAAG,OAAO;AACxD;","names":[]}

package/duration.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bunch of miscellaneous constants and utility functions related to handling
+ * date and time durations.
+ *
+ * Note that month and year do not have fixed durations, and hence are excluded
+ * from this file.
+ */
+export type Duration = {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+};
+export type DurationType = keyof Duration;
+export declare const DURATION_TYPE_SEQUENCE: DurationType[];
+/**
+ * Follows the same format as Intl.DurationFormat.prototype.format().
+ *
+ * Short: 1 yr, 2 mths, 3 wks, 3 days, 4 hr, 5 min, 6 sec, 7 ms, 8 μs, 9 ns
+ * Long: 1 year, 2 months, 3 weeks, 3 days, 4 hours, 5 minutes, 6 seconds,
+ *       7 milliseconds, 8 microseconds, 9 nanoseconds
+ * Narrow: 1y 2mo 3w 3d 4h 5m 6s 7ms 8μs 9ns
+ */
+export type DurationStyle = "short" | "long" | "narrow";
+export type DurationSuffixMap = {
+    short: string;
+    shorts: string;
+    long: string;
+    longs: string;
+    narrow: string;
+};
+export type DurationSuffixType = keyof DurationSuffixMap;
+export declare const DURATION_STYLE_SUFFIX_MAP: Record<DurationType, DurationSuffixMap>;
+/**
+ * Convert a milliseconds duration into a Duration object. If the given ms is
+ * zero, then return an object with a single field of zero.
+ *
+ * durationTypeForZero - Defaults to 'milliseconds'
+ */
+export declare function msToDuration(ms: number, durationTypeForZero?: DurationType): Duration;
+/**
+ * Returns the number of milliseconds for the given duration.
+ */
+export declare function durationToMs(duration: Duration): number;
+/**
+ * Format a given Duration object into a string. If the object has no fields,
+ * then returns an empty string.
+ *
+ * style - Defaults to 'short'
+ */
+export declare function formatDuration(duration: Duration, style?: DurationStyle): string;
+/**
+ * Convert a millisecond duration into a human-readable duration string.
+ *
+ * options.durationTypeForZero - Defaults to 'milliseconds'
+ * options.style - Defaults to 'short'
+ */
+export declare function readableDuration(ms: number, options?: {
+    durationTypeForZero?: DurationType;
+    style?: DurationStyle;
+}): string;

package/duration.js

@@ -0,0 +1,174 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/duration.ts
+var duration_exports = {};
+__export(duration_exports, {
+  DURATION_STYLE_SUFFIX_MAP: () => DURATION_STYLE_SUFFIX_MAP,
+  DURATION_TYPE_SEQUENCE: () => DURATION_TYPE_SEQUENCE,
+  durationToMs: () => durationToMs,
+  formatDuration: () => formatDuration,
+  msToDuration: () => msToDuration,
+  readableDuration: () => readableDuration
+});
+module.exports = __toCommonJS(duration_exports);
+
+// src/timeConstants.ts
+var MS_PER_SECOND = 1e3;
+var MS_PER_MINUTE = 6e4;
+var MS_PER_HOUR = 36e5;
+var MS_PER_DAY = 864e5;
+var SECONDS_PER_MINUTE = 60;
+var MINUTES_PER_HOUR = 60;
+var HOURS_PER_DAY = 24;
+
+// src/duration.ts
+var DURATION_TYPE_SEQUENCE = [
+  "days",
+  "hours",
+  "minutes",
+  "seconds",
+  "milliseconds"
+];
+var DURATION_STYLE_SUFFIX_MAP = {
+  days: {
+    short: "day",
+    shorts: "days",
+    long: "day",
+    longs: "days",
+    narrow: "d"
+  },
+  hours: {
+    short: "hr",
+    shorts: "hrs",
+    long: "hour",
+    longs: "hours",
+    narrow: "h"
+  },
+  minutes: {
+    short: "min",
+    shorts: "mins",
+    long: "minute",
+    longs: "minutes",
+    narrow: "m"
+  },
+  seconds: {
+    short: "sec",
+    shorts: "secs",
+    long: "second",
+    longs: "seconds",
+    narrow: "s"
+  },
+  milliseconds: {
+    short: "ms",
+    shorts: "ms",
+    long: "millisecond",
+    longs: "milliseconds",
+    narrow: "ms"
+  }
+};
+function getDurationStyleForPlural(style) {
+  return style == "short" ? "shorts" : style === "long" ? "longs" : style;
+}
+function getValueAndUnitSeparator(style) {
+  return style === "narrow" ? "" : " ";
+}
+function getDurationTypeSeparator(style) {
+  return style === "narrow" ? " " : ", ";
+}
+function msToDuration(ms, durationTypeForZero) {
+  if (ms === 0) {
+    durationTypeForZero = durationTypeForZero != null ? durationTypeForZero : "milliseconds";
+    return { [durationTypeForZero]: 0 };
+  }
+  const duration = {};
+  for (let i = 0; i < 1; i++) {
+    let seconds = Math.floor(ms / MS_PER_SECOND);
+    const millis = ms - seconds * MS_PER_SECOND;
+    if (millis > 0) {
+      duration["milliseconds"] = millis;
+    }
+    if (seconds === 0) {
+      break;
+    }
+    let minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
+    seconds -= minutes * SECONDS_PER_MINUTE;
+    if (seconds > 0) {
+      duration["seconds"] = seconds;
+    }
+    if (minutes === 0) {
+      break;
+    }
+    let hours = Math.floor(minutes / MINUTES_PER_HOUR);
+    minutes -= hours * MINUTES_PER_HOUR;
+    if (minutes > 0) {
+      duration["minutes"] = minutes;
+    }
+    if (hours === 0) {
+      break;
+    }
+    const days = Math.floor(hours / HOURS_PER_DAY);
+    hours -= days * HOURS_PER_DAY;
+    if (hours > 0) {
+      duration["hours"] = hours;
+    }
+    if (days > 0) {
+      duration["days"] = days;
+    }
+  }
+  return duration;
+}
+function durationToMs(duration) {
+  var _a, _b, _c, _d, _e;
+  const daysMs = ((_a = duration.days) != null ? _a : 0) * MS_PER_DAY;
+  const hoursMs = ((_b = duration.hours) != null ? _b : 0) * MS_PER_HOUR;
+  const minsMs = ((_c = duration.minutes) != null ? _c : 0) * MS_PER_MINUTE;
+  const secsMs = ((_d = duration.seconds) != null ? _d : 0) * MS_PER_SECOND;
+  const msMs = (_e = duration.milliseconds) != null ? _e : 0;
+  return daysMs + hoursMs + minsMs + secsMs + msMs;
+}
+function formatDuration(duration, style) {
+  style = style != null ? style : "short";
+  const stylePlural = getDurationStyleForPlural(style);
+  const space = getValueAndUnitSeparator(style);
+  const a = [];
+  for (const unit of DURATION_TYPE_SEQUENCE) {
+    const value = duration[unit];
+    if (value === void 0) continue;
+    const suffixMap = DURATION_STYLE_SUFFIX_MAP[unit];
+    const suffix = value === 1 ? suffixMap[style] : suffixMap[stylePlural];
+    a.push(value + space + suffix);
+  }
+  const separator = getDurationTypeSeparator(style);
+  return a.join(separator);
+}
+function readableDuration(ms, options) {
+  const duration = msToDuration(ms, options == null ? void 0 : options.durationTypeForZero);
+  return formatDuration(duration, options == null ? void 0 : options.style);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DURATION_STYLE_SUFFIX_MAP,
+  DURATION_TYPE_SEQUENCE,
+  durationToMs,
+  formatDuration,
+  msToDuration,
+  readableDuration
+});
+//# sourceMappingURL=duration.js.map

package/duration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/duration.ts","../src/timeConstants.ts"],"sourcesContent":["/**\n * Bunch of miscellaneous constants and utility functions related to handling\n * date and time durations.\n *\n * Note that month and year do not have fixed durations, and hence are excluded\n * from this file.\n */\n\nimport {\n  MS_PER_SECOND,\n  SECONDS_PER_MINUTE,\n  MINUTES_PER_HOUR,\n  HOURS_PER_DAY,\n  MS_PER_DAY,\n  MS_PER_MINUTE,\n  MS_PER_HOUR,\n} from \"./timeConstants\";\n\nexport type Duration = {\n  days?: number;\n  hours?: number;\n  minutes?: number;\n  seconds?: number;\n  milliseconds?: number;\n};\n\nexport type DurationType = keyof Duration;\n\nexport const DURATION_TYPE_SEQUENCE: DurationType[] = [\n  \"days\",\n  \"hours\",\n  \"minutes\",\n  \"seconds\",\n  \"milliseconds\",\n];\n\n/**\n * Follows the same format as Intl.DurationFormat.prototype.format().\n *\n * Short: 1 yr, 2 mths, 3 wks, 3 days, 4 hr, 5 min, 6 sec, 7 ms, 8 μs, 9 ns\n * Long: 1 year, 2 months, 3 weeks, 3 days, 4 hours, 5 minutes, 6 seconds,\n *       7 milliseconds, 8 microseconds, 9 nanoseconds\n * Narrow: 1y 2mo 3w 3d 4h 5m 6s 7ms 8μs 9ns\n */\nexport type DurationStyle = \"short\" | \"long\" | \"narrow\";\n\nexport type DurationSuffixMap = {\n  short: string;\n  shorts: string;\n  long: string;\n  longs: string;\n  narrow: string;\n};\n\nexport type DurationSuffixType = keyof DurationSuffixMap;\n\nexport const DURATION_STYLE_SUFFIX_MAP: Record<\n  DurationType,\n  DurationSuffixMap\n> = {\n  days: {\n    short: \"day\",\n    shorts: \"days\",\n    long: \"day\",\n    longs: \"days\",\n    narrow: \"d\",\n  },\n  hours: {\n    short: \"hr\",\n    shorts: \"hrs\",\n    long: \"hour\",\n    longs: \"hours\",\n    narrow: \"h\",\n  },\n  minutes: {\n    short: \"min\",\n    shorts: \"mins\",\n    long: \"minute\",\n    longs: \"minutes\",\n    narrow: \"m\",\n  },\n  seconds: {\n    short: \"sec\",\n    shorts: \"secs\",\n    long: \"second\",\n    longs: \"seconds\",\n    narrow: \"s\",\n  },\n  milliseconds: {\n    short: \"ms\",\n    shorts: \"ms\",\n    long: \"millisecond\",\n    longs: \"milliseconds\",\n    narrow: \"ms\",\n  },\n};\n\nfunction getDurationStyleForPlural(style: DurationStyle): DurationSuffixType {\n  return style == \"short\" ? \"shorts\" : style === \"long\" ? \"longs\" : style;\n}\n\nfunction getValueAndUnitSeparator(style: DurationStyle): string {\n  return style === \"narrow\" ? \"\" : \" \";\n}\n\nfunction getDurationTypeSeparator(style: DurationStyle): string {\n  return style === \"narrow\" ? \" \" : \", \";\n}\n\n/**\n * Convert a milliseconds duration into a Duration object. If the given ms is\n * zero, then return an object with a single field of zero.\n *\n * durationTypeForZero - Defaults to 'milliseconds'\n */\nexport function msToDuration(\n  ms: number,\n  durationTypeForZero?: DurationType,\n): Duration {\n  if (ms === 0) {\n    durationTypeForZero = durationTypeForZero ?? \"milliseconds\";\n    return { [durationTypeForZero]: 0 };\n  }\n\n  const duration: Duration = {};\n\n  for (let i = 0; i < 1; i++) {\n    let seconds = Math.floor(ms / MS_PER_SECOND);\n    const millis = ms - seconds * MS_PER_SECOND;\n\n    if (millis > 0) {\n      duration[\"milliseconds\"] = millis;\n    }\n\n    if (seconds === 0) {\n      break;\n    }\n\n    let minutes = Math.floor(seconds / SECONDS_PER_MINUTE);\n    seconds -= minutes * SECONDS_PER_MINUTE;\n\n    if (seconds > 0) {\n      duration[\"seconds\"] = seconds;\n    }\n\n    if (minutes === 0) {\n      break;\n    }\n\n    let hours = Math.floor(minutes / MINUTES_PER_HOUR);\n    minutes -= hours * MINUTES_PER_HOUR;\n\n    if (minutes > 0) {\n      duration[\"minutes\"] = minutes;\n    }\n\n    if (hours === 0) {\n      break;\n    }\n\n    const days = Math.floor(hours / HOURS_PER_DAY);\n    hours -= days * HOURS_PER_DAY;\n\n    if (hours > 0) {\n      duration[\"hours\"] = hours;\n    }\n\n    if (days > 0) {\n      duration[\"days\"] = days;\n    }\n  }\n\n  return duration;\n}\n\n/**\n * Returns the number of milliseconds for the given duration.\n */\nexport function durationToMs(duration: Duration): number {\n  const daysMs = (duration.days ?? 0) * MS_PER_DAY;\n  const hoursMs = (duration.hours ?? 0) * MS_PER_HOUR;\n  const minsMs = (duration.minutes ?? 0) * MS_PER_MINUTE;\n  const secsMs = (duration.seconds ?? 0) * MS_PER_SECOND;\n  const msMs = duration.milliseconds ?? 0;\n\n  return daysMs + hoursMs + minsMs + secsMs + msMs;\n}\n\n/**\n * Format a given Duration object into a string. If the object has no fields,\n * then returns an empty string.\n *\n * style - Defaults to 'short'\n */\nexport function formatDuration(duration: Duration, style?: DurationStyle) {\n  style = style ?? \"short\";\n  const stylePlural = getDurationStyleForPlural(style);\n\n  const space = getValueAndUnitSeparator(style);\n\n  const a: string[] = [];\n\n  for (const unit of DURATION_TYPE_SEQUENCE) {\n    const value = duration[unit];\n    if (value === undefined) continue;\n\n    const suffixMap = DURATION_STYLE_SUFFIX_MAP[unit];\n    const suffix = value === 1 ? suffixMap[style] : suffixMap[stylePlural];\n    a.push(value + space + suffix);\n  }\n\n  const separator = getDurationTypeSeparator(style);\n  return a.join(separator);\n}\n\n/**\n * Convert a millisecond duration into a human-readable duration string.\n *\n * options.durationTypeForZero - Defaults to 'milliseconds'\n * options.style - Defaults to 'short'\n */\nexport function readableDuration(\n  ms: number,\n  options?: { durationTypeForZero?: DurationType; style?: DurationStyle },\n): string {\n  const duration = msToDuration(ms, options?.durationTypeForZero);\n\n  return formatDuration(duration, options?.style);\n}\n","/**\n * Note that month and year do not have fixed durations, and hence are excluded\n * from this file.\n */\n\nexport const MS_PER_SECOND = 1000;\nexport const MS_PER_MINUTE = 60_000;\nexport const MS_PER_HOUR = 3_600_000;\nexport const MS_PER_DAY = 86_400_000;\nexport const MS_PER_WEEK = 604_800_000;\n\nexport const SECONDS_PER_MINUTE = 60;\nexport const SECONDS_PER_HOUR = 3_600;\nexport const SECONDS_PER_DAY = 86_400;\nexport const SECONDS_PER_WEEK = 604_800;\n\nexport const MINUTES_PER_HOUR = 60;\nexport const MINUTES_PER_DAY = 1440;\nexport const MINUTES_PER_WEEK = 10_080;\n\nexport const HOURS_PER_DAY = 24;\nexport const HOURS_PER_WEEK = 168;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKO,IAAM,gBAAgB;AACtB,IAAM,gBAAgB;AACtB,IAAM,cAAc;AACpB,IAAM,aAAa;AAGnB,IAAM,qBAAqB;AAK3B,IAAM,mBAAmB;AAIzB,IAAM,gBAAgB;;;ADQtB,IAAM,yBAAyC;AAAA,EACpD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAsBO,IAAM,4BAGT;AAAA,EACF,MAAM;AAAA,IACJ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ;AAAA,EACV;AAAA,EACA,OAAO;AAAA,IACL,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ;AAAA,EACV;AAAA,EACA,SAAS;AAAA,IACP,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ;AAAA,EACV;AAAA,EACA,SAAS;AAAA,IACP,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ;AAAA,EACV;AAAA,EACA,cAAc;AAAA,IACZ,OAAO;AAAA,IACP,QAAQ;AAAA,IACR,MAAM;AAAA,IACN,OAAO;AAAA,IACP,QAAQ;AAAA,EACV;AACF;AAEA,SAAS,0BAA0B,OAA0C;AAC3E,SAAO,SAAS,UAAU,WAAW,UAAU,SAAS,UAAU;AACpE;AAEA,SAAS,yBAAyB,OAA8B;AAC9D,SAAO,UAAU,WAAW,KAAK;AACnC;AAEA,SAAS,yBAAyB,OAA8B;AAC9D,SAAO,UAAU,WAAW,MAAM;AACpC;AAQO,SAAS,aACd,IACA,qBACU;AACV,MAAI,OAAO,GAAG;AACZ,0BAAsB,oDAAuB;AAC7C,WAAO,EAAE,CAAC,mBAAmB,GAAG,EAAE;AAAA,EACpC;AAEA,QAAM,WAAqB,CAAC;AAE5B,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,QAAI,UAAU,KAAK,MAAM,KAAK,aAAa;AAC3C,UAAM,SAAS,KAAK,UAAU;AAE9B,QAAI,SAAS,GAAG;AACd,eAAS,cAAc,IAAI;AAAA,IAC7B;AAEA,QAAI,YAAY,GAAG;AACjB;AAAA,IACF;AAEA,QAAI,UAAU,KAAK,MAAM,UAAU,kBAAkB;AACrD,eAAW,UAAU;AAErB,QAAI,UAAU,GAAG;AACf,eAAS,SAAS,IAAI;AAAA,IACxB;AAEA,QAAI,YAAY,GAAG;AACjB;AAAA,IACF;AAEA,QAAI,QAAQ,KAAK,MAAM,UAAU,gBAAgB;AACjD,eAAW,QAAQ;AAEnB,QAAI,UAAU,GAAG;AACf,eAAS,SAAS,IAAI;AAAA,IACxB;AAEA,QAAI,UAAU,GAAG;AACf;AAAA,IACF;AAEA,UAAM,OAAO,KAAK,MAAM,QAAQ,aAAa;AAC7C,aAAS,OAAO;AAEhB,QAAI,QAAQ,GAAG;AACb,eAAS,OAAO,IAAI;AAAA,IACtB;AAEA,QAAI,OAAO,GAAG;AACZ,eAAS,MAAM,IAAI;AAAA,IACrB;AAAA,EACF;AAEA,SAAO;AACT;AAKO,SAAS,aAAa,UAA4B;AAlLzD;AAmLE,QAAM,WAAU,cAAS,SAAT,YAAiB,KAAK;AACtC,QAAM,YAAW,cAAS,UAAT,YAAkB,KAAK;AACxC,QAAM,WAAU,cAAS,YAAT,YAAoB,KAAK;AACzC,QAAM,WAAU,cAAS,YAAT,YAAoB,KAAK;AACzC,QAAM,QAAO,cAAS,iBAAT,YAAyB;AAEtC,SAAO,SAAS,UAAU,SAAS,SAAS;AAC9C;AAQO,SAAS,eAAe,UAAoB,OAAuB;AACxE,UAAQ,wBAAS;AACjB,QAAM,cAAc,0BAA0B,KAAK;AAEnD,QAAM,QAAQ,yBAAyB,KAAK;AAE5C,QAAM,IAAc,CAAC;AAErB,aAAW,QAAQ,wBAAwB;AACzC,UAAM,QAAQ,SAAS,IAAI;AAC3B,QAAI,UAAU,OAAW;AAEzB,UAAM,YAAY,0BAA0B,IAAI;AAChD,UAAM,SAAS,UAAU,IAAI,UAAU,KAAK,IAAI,UAAU,WAAW;AACrE,MAAE,KAAK,QAAQ,QAAQ,MAAM;AAAA,EAC/B;AAEA,QAAM,YAAY,yBAAyB,KAAK;AAChD,SAAO,EAAE,KAAK,SAAS;AACzB;AAQO,SAAS,iBACd,IACA,SACQ;AACR,QAAM,WAAW,aAAa,IAAI,mCAAS,mBAAmB;AAE9D,SAAO,eAAe,UAAU,mCAAS,KAAK;AAChD;","names":[]}

package/localStorageCache.d.ts

@@ -1,18 +1,38 @@
+import { Duration } from "./duration";
 /**
  * Simple local storage cache with support for auto-expiration.
  * Note that this works in the browser context only because nodejs does not
  * have local storage.
+ *
+ * Create a cache item accessor object with auto-expiration. The value will
+ * always be stored as a string by applying JSON.stringify(), and will be
+ * returned in the same object type by applying JSON.parse().
+ *
+ * In order to provide proper type-checking, please always specify the T
+ * type parameter. E.g. const item = storeItem<string>("name", 10_000);
+ *
+ * expires - Either a number in milliseconds, or a Duration object
  */
-export declare class LocalStorageCache {
-    static setValue<T>(key: string, value: T, expireDeltaMs: number): void;
-    static getValue<T>(key: string, logError?: boolean): T | undefined;
-}
-/** Same as above, but saves some config for reuse. */
-export declare class LocalStorageCacheItem<T> {
+export declare function storeItem<T>(key: string, expires: number | Duration, logError?: boolean, defaultValue?: T): CacheItem<T>;
+declare class CacheItem<T> {
     readonly key: string;
     readonly expireDeltaMs: number;
     readonly logError: boolean;
-    constructor(key: string, expireDeltaMs: number, logError?: boolean, defaultValue?: T);
+    /**
+     * Create a cache item accessor object with auto-expiration.
+     */
+    constructor(key: string, expireDeltaMs: number, logError: boolean, defaultValue: T | undefined);
+    /**
+     * Set the value of this item with auto-expiration.
+     */
     set(value: T): void;
+    /**
+     * Get the value of this item, or undefined if value is not set or expired.
+     */
     get(): T | undefined;
+    /**
+     * Remove the value of this item.
+     */
+    remove(): void;
 }
+export {};

package/localStorageCache.js

@@ -20,58 +20,89 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/localStorageCache.ts
 var localStorageCache_exports = {};
 __export(localStorageCache_exports, {
-  LocalStorageCache: () => LocalStorageCache,
-  LocalStorageCacheItem: () => LocalStorageCacheItem
+  storeItem: () => storeItem
 });
 module.exports = __toCommonJS(localStorageCache_exports);
-var LocalStorageCache = class {
-  static setValue(key, value, expireDeltaMs) {
-    const expireMs = Date.now() + expireDeltaMs;
+
+// src/timeConstants.ts
+var MS_PER_SECOND = 1e3;
+var MS_PER_MINUTE = 6e4;
+var MS_PER_HOUR = 36e5;
+var MS_PER_DAY = 864e5;
+
+// src/duration.ts
+function durationToMs(duration) {
+  var _a, _b, _c, _d, _e;
+  const daysMs = ((_a = duration.days) != null ? _a : 0) * MS_PER_DAY;
+  const hoursMs = ((_b = duration.hours) != null ? _b : 0) * MS_PER_HOUR;
+  const minsMs = ((_c = duration.minutes) != null ? _c : 0) * MS_PER_MINUTE;
+  const secsMs = ((_d = duration.seconds) != null ? _d : 0) * MS_PER_SECOND;
+  const msMs = (_e = duration.milliseconds) != null ? _e : 0;
+  return daysMs + hoursMs + minsMs + secsMs + msMs;
+}
+
+// src/localStorageCache.ts
+function storeItem(key, expires, logError = true, defaultValue) {
+  const expireDeltaMs = typeof expires === "number" ? expires : durationToMs(expires);
+  return new CacheItem(key, expireDeltaMs, logError, defaultValue);
+}
+var CacheItem = class {
+  /**
+   * Create a cache item accessor object with auto-expiration.
+   */
+  constructor(key, expireDeltaMs, logError, defaultValue) {
+    this.key = key;
+    this.expireDeltaMs = expireDeltaMs;
+    this.logError = logError;
+    if (defaultValue !== void 0) {
+      if (this.get() === void 0) {
+        this.set(defaultValue);
+      }
+    }
+  }
+  /**
+   * Set the value of this item with auto-expiration.
+   */
+  set(value) {
+    const expireMs = Date.now() + this.expireDeltaMs;
     const valueStr = JSON.stringify({ value, expireMs });
-    globalThis.localStorage.setItem(key, valueStr);
+    globalThis.localStorage.setItem(this.key, valueStr);
   }
-  static getValue(key, logError = true) {
-    const jsonStr = globalThis.localStorage.getItem(key);
+  /**
+   * Get the value of this item, or undefined if value is not set or expired.
+   */
+  get() {
+    const jsonStr = globalThis.localStorage.getItem(this.key);
     if (!jsonStr || typeof jsonStr !== "string") {
       return void 0;
     }
     try {
       const obj = JSON.parse(jsonStr);
       if (!obj || typeof obj !== "object" || !("value" in obj) || !("expireMs" in obj) || typeof obj.expireMs !== "number" || Date.now() >= obj.expireMs) {
-        globalThis.localStorage.removeItem(key);
+        globalThis.localStorage.removeItem(this.key);
         return void 0;
       }
       return obj.value;
     } catch (e) {
-      if (logError) {
-        console.error(`Found invalid storage value: ${key}=${jsonStr}:`, e);
+      if (this.logError) {
+        console.error(
+          `Found invalid storage value: ${this.key}=${jsonStr}:`,
+          e
+        );
       }
-      globalThis.localStorage.removeItem(key);
+      globalThis.localStorage.removeItem(this.key);
       return void 0;
     }
   }
-};
-var LocalStorageCacheItem = class {
-  constructor(key, expireDeltaMs, logError = true, defaultValue) {
-    this.key = key;
-    this.expireDeltaMs = expireDeltaMs;
-    this.logError = logError;
-    if (defaultValue !== void 0) {
-      if (this.get() === void 0) {
-        this.set(defaultValue);
-      }
-    }
-  }
-  set(value) {
-    LocalStorageCache.setValue(this.key, value, this.expireDeltaMs);
-  }
-  get() {
-    return LocalStorageCache.getValue(this.key, this.logError);
+  /**
+   * Remove the value of this item.
+   */
+  remove() {
+    globalThis.localStorage.removeItem(this.key);
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  LocalStorageCache,
-  LocalStorageCacheItem
+  storeItem
 });
 //# sourceMappingURL=localStorageCache.js.map

package/localStorageCache.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/localStorageCache.ts"],"sourcesContent":["/**\n * Simple local storage cache with support for auto-expiration.\n * Note that this works in the browser context only because nodejs does not\n * have local storage.\n */\nexport class LocalStorageCache {\n  public static setValue<T>(key: string, value: T, expireDeltaMs: number) {\n    const expireMs = Date.now() + expireDeltaMs;\n    const valueStr = JSON.stringify({ value, expireMs });\n\n    globalThis.localStorage.setItem(key, valueStr);\n  }\n\n  public static getValue<T>(key: string, logError = true): T | undefined {\n    const jsonStr = globalThis.localStorage.getItem(key);\n\n    if (!jsonStr || typeof jsonStr !== \"string\") {\n      return undefined;\n    }\n\n    try {\n      const obj: { value: T; expireMs: number } | undefined =\n        JSON.parse(jsonStr);\n      if (\n        !obj ||\n        typeof obj !== \"object\" ||\n        !(\"value\" in obj) ||\n        !(\"expireMs\" in obj) ||\n        typeof obj.expireMs !== \"number\" ||\n        Date.now() >= obj.expireMs\n      ) {\n        globalThis.localStorage.removeItem(key);\n        return undefined;\n      }\n\n      return obj.value;\n    } catch (e) {\n      if (logError) {\n        console.error(`Found invalid storage value: ${key}=${jsonStr}:`, e);\n      }\n      globalThis.localStorage.removeItem(key);\n      return undefined;\n    }\n  }\n}\n\n/** Same as above, but saves some config for reuse. */\nexport class LocalStorageCacheItem<T> {\n  public constructor(\n    public readonly key: string,\n    public readonly expireDeltaMs: number,\n    public readonly logError = true,\n    defaultValue?: T,\n  ) {\n    if (defaultValue !== undefined) {\n      if (this.get() === undefined) {\n        this.set(defaultValue);\n      }\n    }\n  }\n\n  public set(value: T) {\n    LocalStorageCache.setValue(this.key, value, this.expireDeltaMs);\n  }\n\n  public get(): T | undefined {\n    return LocalStorageCache.getValue(this.key, this.logError);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKO,IAAM,oBAAN,MAAwB;AAAA,EAC7B,OAAc,SAAY,KAAa,OAAU,eAAuB;AACtE,UAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,UAAM,WAAW,KAAK,UAAU,EAAE,OAAO,SAAS,CAAC;AAEnD,eAAW,aAAa,QAAQ,KAAK,QAAQ;AAAA,EAC/C;AAAA,EAEA,OAAc,SAAY,KAAa,WAAW,MAAqB;AACrE,UAAM,UAAU,WAAW,aAAa,QAAQ,GAAG;AAEnD,QAAI,CAAC,WAAW,OAAO,YAAY,UAAU;AAC3C,aAAO;AAAA,IACT;AAEA,QAAI;AACF,YAAM,MACJ,KAAK,MAAM,OAAO;AACpB,UACE,CAAC,OACD,OAAO,QAAQ,YACf,EAAE,WAAW,QACb,EAAE,cAAc,QAChB,OAAO,IAAI,aAAa,YACxB,KAAK,IAAI,KAAK,IAAI,UAClB;AACA,mBAAW,aAAa,WAAW,GAAG;AACtC,eAAO;AAAA,MACT;AAEA,aAAO,IAAI;AAAA,IACb,SAAS,GAAG;AACV,UAAI,UAAU;AACZ,gBAAQ,MAAM,gCAAgC,GAAG,IAAI,OAAO,KAAK,CAAC;AAAA,MACpE;AACA,iBAAW,aAAa,WAAW,GAAG;AACtC,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAGO,IAAM,wBAAN,MAA+B;AAAA,EAC7B,YACW,KACA,eACA,WAAW,MAC3B,cACA;AAJgB;AACA;AACA;AAGhB,QAAI,iBAAiB,QAAW;AAC9B,UAAI,KAAK,IAAI,MAAM,QAAW;AAC5B,aAAK,IAAI,YAAY;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AAAA,EAEO,IAAI,OAAU;AACnB,sBAAkB,SAAS,KAAK,KAAK,OAAO,KAAK,aAAa;AAAA,EAChE;AAAA,EAEO,MAAqB;AAC1B,WAAO,kBAAkB,SAAS,KAAK,KAAK,KAAK,QAAQ;AAAA,EAC3D;AACF;","names":[]}
+{"version":3,"sources":["../src/localStorageCache.ts","../src/timeConstants.ts","../src/duration.ts"],"sourcesContent":["import { Duration, durationToMs } from \"./duration\";\n\n/**\n * Simple local storage cache with support for auto-expiration.\n * Note that this works in the browser context only because nodejs does not\n * have local storage.\n *\n * Create a cache item accessor object with auto-expiration. The value will\n * always be stored as a string by applying JSON.stringify(), and will be\n * returned in the same object type by applying JSON.parse().\n *\n * In order to provide proper type-checking, please always specify the T\n * type parameter. E.g. const item = storeItem<string>(\"name\", 10_000);\n *\n * expires - Either a number in milliseconds, or a Duration object\n */\nexport function storeItem<T>(\n  key: string,\n  expires: number | Duration,\n  logError = true,\n  defaultValue?: T,\n) {\n  const expireDeltaMs =\n    typeof expires === \"number\" ? expires : durationToMs(expires);\n\n  return new CacheItem<T>(key, expireDeltaMs, logError, defaultValue);\n}\n\nclass CacheItem<T> {\n  /**\n   * Create a cache item accessor object with auto-expiration.\n   */\n  public constructor(\n    public readonly key: string,\n    public readonly expireDeltaMs: number,\n    public readonly logError: boolean,\n    defaultValue: T | undefined,\n  ) {\n    if (defaultValue !== undefined) {\n      if (this.get() === undefined) {\n        this.set(defaultValue);\n      }\n    }\n  }\n\n  /**\n   * Set the value of this item with auto-expiration.\n   */\n  public set(value: T): void {\n    const expireMs = Date.now() + this.expireDeltaMs;\n    const valueStr = JSON.stringify({ value, expireMs });\n\n    globalThis.localStorage.setItem(this.key, valueStr);\n  }\n\n  /**\n   * Get the value of this item, or undefined if value is not set or expired.\n   */\n  public get(): T | undefined {\n    const jsonStr = globalThis.localStorage.getItem(this.key);\n\n    if (!jsonStr || typeof jsonStr !== \"string\") {\n      return undefined;\n    }\n\n    try {\n      const obj: { value: T; expireMs: number } | undefined =\n        JSON.parse(jsonStr);\n      if (\n        !obj ||\n        typeof obj !== \"object\" ||\n        !(\"value\" in obj) ||\n        !(\"expireMs\" in obj) ||\n        typeof obj.expireMs !== \"number\" ||\n        Date.now() >= obj.expireMs\n      ) {\n        globalThis.localStorage.removeItem(this.key);\n        return undefined;\n      }\n\n      return obj.value;\n    } catch (e) {\n      if (this.logError) {\n        console.error(\n          `Found invalid storage value: ${this.key}=${jsonStr}:`,\n          e,\n        );\n      }\n      globalThis.localStorage.removeItem(this.key);\n      return undefined;\n    }\n  }\n\n  /**\n   * Remove the value of this item.\n   */\n  public remove(): void {\n    globalThis.localStorage.removeItem(this.key);\n  }\n}\n","/**\n * Note that month and year do not have fixed durations, and hence are excluded\n * from this file.\n */\n\nexport const MS_PER_SECOND = 1000;\nexport const MS_PER_MINUTE = 60_000;\nexport const MS_PER_HOUR = 3_600_000;\nexport const MS_PER_DAY = 86_400_000;\nexport const MS_PER_WEEK = 604_800_000;\n\nexport const SECONDS_PER_MINUTE = 60;\nexport const SECONDS_PER_HOUR = 3_600;\nexport const SECONDS_PER_DAY = 86_400;\nexport const SECONDS_PER_WEEK = 604_800;\n\nexport const MINUTES_PER_HOUR = 60;\nexport const MINUTES_PER_DAY = 1440;\nexport const MINUTES_PER_WEEK = 10_080;\n\nexport const HOURS_PER_DAY = 24;\nexport const HOURS_PER_WEEK = 168;\n","/**\n * Bunch of miscellaneous constants and utility functions related to handling\n * date and time durations.\n *\n * Note that month and year do not have fixed durations, and hence are excluded\n * from this file.\n */\n\nimport {\n  MS_PER_SECOND,\n  SECONDS_PER_MINUTE,\n  MINUTES_PER_HOUR,\n  HOURS_PER_DAY,\n  MS_PER_DAY,\n  MS_PER_MINUTE,\n  MS_PER_HOUR,\n} from \"./timeConstants\";\n\nexport type Duration = {\n  days?: number;\n  hours?: number;\n  minutes?: number;\n  seconds?: number;\n  milliseconds?: number;\n};\n\nexport type DurationType = keyof Duration;\n\nexport const DURATION_TYPE_SEQUENCE: DurationType[] = [\n  \"days\",\n  \"hours\",\n  \"minutes\",\n  \"seconds\",\n  \"milliseconds\",\n];\n\n/**\n * Follows the same format as Intl.DurationFormat.prototype.format().\n *\n * Short: 1 yr, 2 mths, 3 wks, 3 days, 4 hr, 5 min, 6 sec, 7 ms, 8 μs, 9 ns\n * Long: 1 year, 2 months, 3 weeks, 3 days, 4 hours, 5 minutes, 6 seconds,\n *       7 milliseconds, 8 microseconds, 9 nanoseconds\n * Narrow: 1y 2mo 3w 3d 4h 5m 6s 7ms 8μs 9ns\n */\nexport type DurationStyle = \"short\" | \"long\" | \"narrow\";\n\nexport type DurationSuffixMap = {\n  short: string;\n  shorts: string;\n  long: string;\n  longs: string;\n  narrow: string;\n};\n\nexport type DurationSuffixType = keyof DurationSuffixMap;\n\nexport const DURATION_STYLE_SUFFIX_MAP: Record<\n  DurationType,\n  DurationSuffixMap\n> = {\n  days: {\n    short: \"day\",\n    shorts: \"days\",\n    long: \"day\",\n    longs: \"days\",\n    narrow: \"d\",\n  },\n  hours: {\n    short: \"hr\",\n    shorts: \"hrs\",\n    long: \"hour\",\n    longs: \"hours\",\n    narrow: \"h\",\n  },\n  minutes: {\n    short: \"min\",\n    shorts: \"mins\",\n    long: \"minute\",\n    longs: \"minutes\",\n    narrow: \"m\",\n  },\n  seconds: {\n    short: \"sec\",\n    shorts: \"secs\",\n    long: \"second\",\n    longs: \"seconds\",\n    narrow: \"s\",\n  },\n  milliseconds: {\n    short: \"ms\",\n    shorts: \"ms\",\n    long: \"millisecond\",\n    longs: \"milliseconds\",\n    narrow: \"ms\",\n  },\n};\n\nfunction getDurationStyleForPlural(style: DurationStyle): DurationSuffixType {\n  return style == \"short\" ? \"shorts\" : style === \"long\" ? \"longs\" : style;\n}\n\nfunction getValueAndUnitSeparator(style: DurationStyle): string {\n  return style === \"narrow\" ? \"\" : \" \";\n}\n\nfunction getDurationTypeSeparator(style: DurationStyle): string {\n  return style === \"narrow\" ? \" \" : \", \";\n}\n\n/**\n * Convert a milliseconds duration into a Duration object. If the given ms is\n * zero, then return an object with a single field of zero.\n *\n * durationTypeForZero - Defaults to 'milliseconds'\n */\nexport function msToDuration(\n  ms: number,\n  durationTypeForZero?: DurationType,\n): Duration {\n  if (ms === 0) {\n    durationTypeForZero = durationTypeForZero ?? \"milliseconds\";\n    return { [durationTypeForZero]: 0 };\n  }\n\n  const duration: Duration = {};\n\n  for (let i = 0; i < 1; i++) {\n    let seconds = Math.floor(ms / MS_PER_SECOND);\n    const millis = ms - seconds * MS_PER_SECOND;\n\n    if (millis > 0) {\n      duration[\"milliseconds\"] = millis;\n    }\n\n    if (seconds === 0) {\n      break;\n    }\n\n    let minutes = Math.floor(seconds / SECONDS_PER_MINUTE);\n    seconds -= minutes * SECONDS_PER_MINUTE;\n\n    if (seconds > 0) {\n      duration[\"seconds\"] = seconds;\n    }\n\n    if (minutes === 0) {\n      break;\n    }\n\n    let hours = Math.floor(minutes / MINUTES_PER_HOUR);\n    minutes -= hours * MINUTES_PER_HOUR;\n\n    if (minutes > 0) {\n      duration[\"minutes\"] = minutes;\n    }\n\n    if (hours === 0) {\n      break;\n    }\n\n    const days = Math.floor(hours / HOURS_PER_DAY);\n    hours -= days * HOURS_PER_DAY;\n\n    if (hours > 0) {\n      duration[\"hours\"] = hours;\n    }\n\n    if (days > 0) {\n      duration[\"days\"] = days;\n    }\n  }\n\n  return duration;\n}\n\n/**\n * Returns the number of milliseconds for the given duration.\n */\nexport function durationToMs(duration: Duration): number {\n  const daysMs = (duration.days ?? 0) * MS_PER_DAY;\n  const hoursMs = (duration.hours ?? 0) * MS_PER_HOUR;\n  const minsMs = (duration.minutes ?? 0) * MS_PER_MINUTE;\n  const secsMs = (duration.seconds ?? 0) * MS_PER_SECOND;\n  const msMs = duration.milliseconds ?? 0;\n\n  return daysMs + hoursMs + minsMs + secsMs + msMs;\n}\n\n/**\n * Format a given Duration object into a string. If the object has no fields,\n * then returns an empty string.\n *\n * style - Defaults to 'short'\n */\nexport function formatDuration(duration: Duration, style?: DurationStyle) {\n  style = style ?? \"short\";\n  const stylePlural = getDurationStyleForPlural(style);\n\n  const space = getValueAndUnitSeparator(style);\n\n  const a: string[] = [];\n\n  for (const unit of DURATION_TYPE_SEQUENCE) {\n    const value = duration[unit];\n    if (value === undefined) continue;\n\n    const suffixMap = DURATION_STYLE_SUFFIX_MAP[unit];\n    const suffix = value === 1 ? suffixMap[style] : suffixMap[stylePlural];\n    a.push(value + space + suffix);\n  }\n\n  const separator = getDurationTypeSeparator(style);\n  return a.join(separator);\n}\n\n/**\n * Convert a millisecond duration into a human-readable duration string.\n *\n * options.durationTypeForZero - Defaults to 'milliseconds'\n * options.style - Defaults to 'short'\n */\nexport function readableDuration(\n  ms: number,\n  options?: { durationTypeForZero?: DurationType; style?: DurationStyle },\n): string {\n  const duration = msToDuration(ms, options?.durationTypeForZero);\n\n  return formatDuration(duration, options?.style);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKO,IAAM,gBAAgB;AACtB,IAAM,gBAAgB;AACtB,IAAM,cAAc;AACpB,IAAM,aAAa;;;AC0KnB,SAAS,aAAa,UAA4B;AAlLzD;AAmLE,QAAM,WAAU,cAAS,SAAT,YAAiB,KAAK;AACtC,QAAM,YAAW,cAAS,UAAT,YAAkB,KAAK;AACxC,QAAM,WAAU,cAAS,YAAT,YAAoB,KAAK;AACzC,QAAM,WAAU,cAAS,YAAT,YAAoB,KAAK;AACzC,QAAM,QAAO,cAAS,iBAAT,YAAyB;AAEtC,SAAO,SAAS,UAAU,SAAS,SAAS;AAC9C;;;AF1KO,SAAS,UACd,KACA,SACA,WAAW,MACX,cACA;AACA,QAAM,gBACJ,OAAO,YAAY,WAAW,UAAU,aAAa,OAAO;AAE9D,SAAO,IAAI,UAAa,KAAK,eAAe,UAAU,YAAY;AACpE;AAEA,IAAM,YAAN,MAAmB;AAAA;AAAA;AAAA;AAAA,EAIV,YACW,KACA,eACA,UAChB,cACA;AAJgB;AACA;AACA;AAGhB,QAAI,iBAAiB,QAAW;AAC9B,UAAI,KAAK,IAAI,MAAM,QAAW;AAC5B,aAAK,IAAI,YAAY;AAAA,MACvB;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,IAAI,OAAgB;AACzB,UAAM,WAAW,KAAK,IAAI,IAAI,KAAK;AACnC,UAAM,WAAW,KAAK,UAAU,EAAE,OAAO,SAAS,CAAC;AAEnD,eAAW,aAAa,QAAQ,KAAK,KAAK,QAAQ;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA,EAKO,MAAqB;AAC1B,UAAM,UAAU,WAAW,aAAa,QAAQ,KAAK,GAAG;AAExD,QAAI,CAAC,WAAW,OAAO,YAAY,UAAU;AAC3C,aAAO;AAAA,IACT;AAEA,QAAI;AACF,YAAM,MACJ,KAAK,MAAM,OAAO;AACpB,UACE,CAAC,OACD,OAAO,QAAQ,YACf,EAAE,WAAW,QACb,EAAE,cAAc,QAChB,OAAO,IAAI,aAAa,YACxB,KAAK,IAAI,KAAK,IAAI,UAClB;AACA,mBAAW,aAAa,WAAW,KAAK,GAAG;AAC3C,eAAO;AAAA,MACT;AAEA,aAAO,IAAI;AAAA,IACb,SAAS,GAAG;AACV,UAAI,KAAK,UAAU;AACjB,gBAAQ;AAAA,UACN,gCAAgC,KAAK,GAAG,IAAI,OAAO;AAAA,UACnD;AAAA,QACF;AAAA,MACF;AACA,iBAAW,aAAa,WAAW,KAAK,GAAG;AAC3C,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,SAAe;AACpB,eAAW,aAAa,WAAW,KAAK,GAAG;AAAA,EAC7C;AACF;","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@choksheak/ts-utils",
   "license": "The Unlicense",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Random Typescript utilities with support for full tree-shaking",
   "private": false,
   "scripts": {

package/src/dateTimeStr.ts

@@ -1,83 +1,82 @@
-export class DateTimeStr {
-  public static yyyyMmDd(dt = new Date(), separator = "-"): string {
-    const yr = dt.getFullYear();
-    const mth = dt.getMonth() + 1;
-    const day = dt.getDate();
+export function yyyyMmDd(dt = new Date(), separator = "-"): string {
+  const yr = dt.getFullYear();
+  const mth = dt.getMonth() + 1;
+  const day = dt.getDate();
 
-    return (
-      yr +
-      separator +
-      (mth < 10 ? "0" + mth : mth) +
-      separator +
-      (day < 10 ? "0" + day : day)
-    );
-  }
-
-  public static hhMmSs(dt = new Date(), separator = ":"): string {
-    const hr = dt.getHours();
-    const min = dt.getMinutes();
-    const sec = dt.getSeconds();
+  return (
+    yr +
+    separator +
+    (mth < 10 ? "0" + mth : mth) +
+    separator +
+    (day < 10 ? "0" + day : day)
+  );
+}
 
-    return (
-      (hr < 10 ? "0" + hr : hr) +
-      separator +
-      (min < 10 ? "0" + min : min) +
-      separator +
-      (sec < 10 ? "0" + sec : sec)
-    );
-  }
+export function hhMmSs(dt = new Date(), separator = ":"): string {
+  const hr = dt.getHours();
+  const min = dt.getMinutes();
+  const sec = dt.getSeconds();
 
-  public static hhMmSsMs(
-    dt = new Date(),
-    timeSeparator = ":",
-    msSeparator = ".",
-  ): string {
-    const ms = dt.getMilliseconds();
+  return (
+    (hr < 10 ? "0" + hr : hr) +
+    separator +
+    (min < 10 ? "0" + min : min) +
+    separator +
+    (sec < 10 ? "0" + sec : sec)
+  );
+}
 
-    return (
-      DateTimeStr.hhMmSs(dt, timeSeparator) +
-      msSeparator +
-      (ms < 10 ? "00" + ms : ms < 100 ? "0" + ms : ms)
-    );
-  }
+export function hhMmSsMs(
+  dt = new Date(),
+  timeSeparator = ":",
+  msSeparator = ".",
+): string {
+  const ms = dt.getMilliseconds();
 
-  public static tz(dt = new Date()): string {
-    if (dt.getTimezoneOffset() === 0) {
-      return "Z";
-    }
+  return (
+    hhMmSs(dt, timeSeparator) +
+    msSeparator +
+    (ms < 10 ? "00" + ms : ms < 100 ? "0" + ms : ms)
+  );
+}
 
-    const tzHours = dt.getTimezoneOffset() / 60;
-    return tzHours >= 0 ? "+" + tzHours : String(tzHours);
+export function tzShort(dt = new Date()): string {
+  if (dt.getTimezoneOffset() === 0) {
+    return "Z";
   }
 
-  /** Full local date/time string. */
-  public static local(
-    dt = new Date(),
-    dateSeparator = "-",
-    dtSeparator = " ",
-    timeSeparator = ":",
-    msSeparator = ".",
-  ): string {
-    return (
-      DateTimeStr.yyyyMmDd(dt, dateSeparator) +
-      dtSeparator +
-      DateTimeStr.hhMmSsMs(dt, timeSeparator, msSeparator) +
-      DateTimeStr.tz(dt)
-    );
-  }
+  const tzHours = dt.getTimezoneOffset() / 60;
+  return tzHours >= 0 ? "+" + tzHours : String(tzHours);
+}
 
-  /** Use the default ISO string function to keep things simple here. */
-  public static utc(dt = new Date()) {
-    return dt.toISOString();
-  }
+export function getLongMonthNameZeroIndexed(
+  month: number,
+  locales: Intl.LocalesArgument = "default",
+): string {
+  return new Date(2024, month, 15).toLocaleString(locales, {
+    month: "long",
+  });
+}
 
-  /** Default full local date+time string with full & concise info. */
-  public static get now() {
-    return DateTimeStr.local();
-  }
+export function getLongMonthNameOneIndexed(
+  month: number,
+  locales: Intl.LocalesArgument = "default",
+): string {
+  return getLongMonthNameZeroIndexed(month - 1, locales);
+}
 
-  /** Default full UTC date+time string with full & concise info. */
-  public static get utcNow() {
-    return DateTimeStr.utc();
-  }
+export function getShortMonthNameZeroIndexed(
+  month: number,
+  locales: Intl.LocalesArgument = "default",
+): string {
+  return new Date(2000, month, 15).toLocaleString(locales, {
+    month: "short",
+  });
+}
+
+export function getShortMonthNameOneIndexed(
+  month: number,
+  locales: Intl.LocalesArgument = "default",
+): string {
+  return getShortMonthNameZeroIndexed(month - 1, locales);
 }

package/src/duration.ts

@@ -0,0 +1,229 @@
+/**
+ * Bunch of miscellaneous constants and utility functions related to handling
+ * date and time durations.
+ *
+ * Note that month and year do not have fixed durations, and hence are excluded
+ * from this file.
+ */
+
+import {
+  MS_PER_SECOND,
+  SECONDS_PER_MINUTE,
+  MINUTES_PER_HOUR,
+  HOURS_PER_DAY,
+  MS_PER_DAY,
+  MS_PER_MINUTE,
+  MS_PER_HOUR,
+} from "./timeConstants";
+
+export type Duration = {
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  milliseconds?: number;
+};
+
+export type DurationType = keyof Duration;
+
+export const DURATION_TYPE_SEQUENCE: DurationType[] = [
+  "days",
+  "hours",
+  "minutes",
+  "seconds",
+  "milliseconds",
+];
+
+/**
+ * Follows the same format as Intl.DurationFormat.prototype.format().
+ *
+ * Short: 1 yr, 2 mths, 3 wks, 3 days, 4 hr, 5 min, 6 sec, 7 ms, 8 μs, 9 ns
+ * Long: 1 year, 2 months, 3 weeks, 3 days, 4 hours, 5 minutes, 6 seconds,
+ *       7 milliseconds, 8 microseconds, 9 nanoseconds
+ * Narrow: 1y 2mo 3w 3d 4h 5m 6s 7ms 8μs 9ns
+ */
+export type DurationStyle = "short" | "long" | "narrow";
+
+export type DurationSuffixMap = {
+  short: string;
+  shorts: string;
+  long: string;
+  longs: string;
+  narrow: string;
+};
+
+export type DurationSuffixType = keyof DurationSuffixMap;
+
+export const DURATION_STYLE_SUFFIX_MAP: Record<
+  DurationType,
+  DurationSuffixMap
+> = {
+  days: {
+    short: "day",
+    shorts: "days",
+    long: "day",
+    longs: "days",
+    narrow: "d",
+  },
+  hours: {
+    short: "hr",
+    shorts: "hrs",
+    long: "hour",
+    longs: "hours",
+    narrow: "h",
+  },
+  minutes: {
+    short: "min",
+    shorts: "mins",
+    long: "minute",
+    longs: "minutes",
+    narrow: "m",
+  },
+  seconds: {
+    short: "sec",
+    shorts: "secs",
+    long: "second",
+    longs: "seconds",
+    narrow: "s",
+  },
+  milliseconds: {
+    short: "ms",
+    shorts: "ms",
+    long: "millisecond",
+    longs: "milliseconds",
+    narrow: "ms",
+  },
+};
+
+function getDurationStyleForPlural(style: DurationStyle): DurationSuffixType {
+  return style == "short" ? "shorts" : style === "long" ? "longs" : style;
+}
+
+function getValueAndUnitSeparator(style: DurationStyle): string {
+  return style === "narrow" ? "" : " ";
+}
+
+function getDurationTypeSeparator(style: DurationStyle): string {
+  return style === "narrow" ? " " : ", ";
+}
+
+/**
+ * Convert a milliseconds duration into a Duration object. If the given ms is
+ * zero, then return an object with a single field of zero.
+ *
+ * durationTypeForZero - Defaults to 'milliseconds'
+ */
+export function msToDuration(
+  ms: number,
+  durationTypeForZero?: DurationType,
+): Duration {
+  if (ms === 0) {
+    durationTypeForZero = durationTypeForZero ?? "milliseconds";
+    return { [durationTypeForZero]: 0 };
+  }
+
+  const duration: Duration = {};
+
+  for (let i = 0; i < 1; i++) {
+    let seconds = Math.floor(ms / MS_PER_SECOND);
+    const millis = ms - seconds * MS_PER_SECOND;
+
+    if (millis > 0) {
+      duration["milliseconds"] = millis;
+    }
+
+    if (seconds === 0) {
+      break;
+    }
+
+    let minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
+    seconds -= minutes * SECONDS_PER_MINUTE;
+
+    if (seconds > 0) {
+      duration["seconds"] = seconds;
+    }
+
+    if (minutes === 0) {
+      break;
+    }
+
+    let hours = Math.floor(minutes / MINUTES_PER_HOUR);
+    minutes -= hours * MINUTES_PER_HOUR;
+
+    if (minutes > 0) {
+      duration["minutes"] = minutes;
+    }
+
+    if (hours === 0) {
+      break;
+    }
+
+    const days = Math.floor(hours / HOURS_PER_DAY);
+    hours -= days * HOURS_PER_DAY;
+
+    if (hours > 0) {
+      duration["hours"] = hours;
+    }
+
+    if (days > 0) {
+      duration["days"] = days;
+    }
+  }
+
+  return duration;
+}
+
+/**
+ * Returns the number of milliseconds for the given duration.
+ */
+export function durationToMs(duration: Duration): number {
+  const daysMs = (duration.days ?? 0) * MS_PER_DAY;
+  const hoursMs = (duration.hours ?? 0) * MS_PER_HOUR;
+  const minsMs = (duration.minutes ?? 0) * MS_PER_MINUTE;
+  const secsMs = (duration.seconds ?? 0) * MS_PER_SECOND;
+  const msMs = duration.milliseconds ?? 0;
+
+  return daysMs + hoursMs + minsMs + secsMs + msMs;
+}
+
+/**
+ * Format a given Duration object into a string. If the object has no fields,
+ * then returns an empty string.
+ *
+ * style - Defaults to 'short'
+ */
+export function formatDuration(duration: Duration, style?: DurationStyle) {
+  style = style ?? "short";
+  const stylePlural = getDurationStyleForPlural(style);
+
+  const space = getValueAndUnitSeparator(style);
+
+  const a: string[] = [];
+
+  for (const unit of DURATION_TYPE_SEQUENCE) {
+    const value = duration[unit];
+    if (value === undefined) continue;
+
+    const suffixMap = DURATION_STYLE_SUFFIX_MAP[unit];
+    const suffix = value === 1 ? suffixMap[style] : suffixMap[stylePlural];
+    a.push(value + space + suffix);
+  }
+
+  const separator = getDurationTypeSeparator(style);
+  return a.join(separator);
+}
+
+/**
+ * Convert a millisecond duration into a human-readable duration string.
+ *
+ * options.durationTypeForZero - Defaults to 'milliseconds'
+ * options.style - Defaults to 'short'
+ */
+export function readableDuration(
+  ms: number,
+  options?: { durationTypeForZero?: DurationType; style?: DurationStyle },
+): string {
+  const duration = msToDuration(ms, options?.durationTypeForZero);
+
+  return formatDuration(duration, options?.style);
+}

package/src/localStorageCache.ts

@@ -1,18 +1,63 @@
+import { Duration, durationToMs } from "./duration";
+
 /**
  * Simple local storage cache with support for auto-expiration.
  * Note that this works in the browser context only because nodejs does not
  * have local storage.
+ *
+ * Create a cache item accessor object with auto-expiration. The value will
+ * always be stored as a string by applying JSON.stringify(), and will be
+ * returned in the same object type by applying JSON.parse().
+ *
+ * In order to provide proper type-checking, please always specify the T
+ * type parameter. E.g. const item = storeItem<string>("name", 10_000);
+ *
+ * expires - Either a number in milliseconds, or a Duration object
  */
-export class LocalStorageCache {
-  public static setValue<T>(key: string, value: T, expireDeltaMs: number) {
-    const expireMs = Date.now() + expireDeltaMs;
+export function storeItem<T>(
+  key: string,
+  expires: number | Duration,
+  logError = true,
+  defaultValue?: T,
+) {
+  const expireDeltaMs =
+    typeof expires === "number" ? expires : durationToMs(expires);
+
+  return new CacheItem<T>(key, expireDeltaMs, logError, defaultValue);
+}
+
+class CacheItem<T> {
+  /**
+   * Create a cache item accessor object with auto-expiration.
+   */
+  public constructor(
+    public readonly key: string,
+    public readonly expireDeltaMs: number,
+    public readonly logError: boolean,
+    defaultValue: T | undefined,
+  ) {
+    if (defaultValue !== undefined) {
+      if (this.get() === undefined) {
+        this.set(defaultValue);
+      }
+    }
+  }
+
+  /**
+   * Set the value of this item with auto-expiration.
+   */
+  public set(value: T): void {
+    const expireMs = Date.now() + this.expireDeltaMs;
     const valueStr = JSON.stringify({ value, expireMs });
 
-    globalThis.localStorage.setItem(key, valueStr);
+    globalThis.localStorage.setItem(this.key, valueStr);
   }
 
-  public static getValue<T>(key: string, logError = true): T | undefined {
-    const jsonStr = globalThis.localStorage.getItem(key);
+  /**
+   * Get the value of this item, or undefined if value is not set or expired.
+   */
+  public get(): T | undefined {
+    const jsonStr = globalThis.localStorage.getItem(this.key);
 
     if (!jsonStr || typeof jsonStr !== "string") {
       return undefined;
@@ -29,41 +74,27 @@ export class LocalStorageCache {
         typeof obj.expireMs !== "number" ||
         Date.now() >= obj.expireMs
       ) {
-        globalThis.localStorage.removeItem(key);
+        globalThis.localStorage.removeItem(this.key);
         return undefined;
       }
 
       return obj.value;
     } catch (e) {
-      if (logError) {
-        console.error(`Found invalid storage value: ${key}=${jsonStr}:`, e);
+      if (this.logError) {
+        console.error(
+          `Found invalid storage value: ${this.key}=${jsonStr}:`,
+          e,
+        );
       }
-      globalThis.localStorage.removeItem(key);
+      globalThis.localStorage.removeItem(this.key);
       return undefined;
     }
   }
-}
 
-/** Same as above, but saves some config for reuse. */
-export class LocalStorageCacheItem<T> {
-  public constructor(
-    public readonly key: string,
-    public readonly expireDeltaMs: number,
-    public readonly logError = true,
-    defaultValue?: T,
-  ) {
-    if (defaultValue !== undefined) {
-      if (this.get() === undefined) {
-        this.set(defaultValue);
-      }
-    }
-  }
-
-  public set(value: T) {
-    LocalStorageCache.setValue(this.key, value, this.expireDeltaMs);
-  }
-
-  public get(): T | undefined {
-    return LocalStorageCache.getValue(this.key, this.logError);
+  /**
+   * Remove the value of this item.
+   */
+  public remove(): void {
+    globalThis.localStorage.removeItem(this.key);
   }
 }

package/src/timeConstants.ts

@@ -0,0 +1,22 @@
+/**
+ * Note that month and year do not have fixed durations, and hence are excluded
+ * from this file.
+ */
+
+export const MS_PER_SECOND = 1000;
+export const MS_PER_MINUTE = 60_000;
+export const MS_PER_HOUR = 3_600_000;
+export const MS_PER_DAY = 86_400_000;
+export const MS_PER_WEEK = 604_800_000;
+
+export const SECONDS_PER_MINUTE = 60;
+export const SECONDS_PER_HOUR = 3_600;
+export const SECONDS_PER_DAY = 86_400;
+export const SECONDS_PER_WEEK = 604_800;
+
+export const MINUTES_PER_HOUR = 60;
+export const MINUTES_PER_DAY = 1440;
+export const MINUTES_PER_WEEK = 10_080;
+
+export const HOURS_PER_DAY = 24;
+export const HOURS_PER_WEEK = 168;

package/timeConstants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Note that month and year do not have fixed durations, and hence are excluded
+ * from this file.
+ */
+export declare const MS_PER_SECOND = 1000;
+export declare const MS_PER_MINUTE = 60000;
+export declare const MS_PER_HOUR = 3600000;
+export declare const MS_PER_DAY = 86400000;
+export declare const MS_PER_WEEK = 604800000;
+export declare const SECONDS_PER_MINUTE = 60;
+export declare const SECONDS_PER_HOUR = 3600;
+export declare const SECONDS_PER_DAY = 86400;
+export declare const SECONDS_PER_WEEK = 604800;
+export declare const MINUTES_PER_HOUR = 60;
+export declare const MINUTES_PER_DAY = 1440;
+export declare const MINUTES_PER_WEEK = 10080;
+export declare const HOURS_PER_DAY = 24;
+export declare const HOURS_PER_WEEK = 168;

package/timeConstants.js

@@ -0,0 +1,70 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/timeConstants.ts
+var timeConstants_exports = {};
+__export(timeConstants_exports, {
+  HOURS_PER_DAY: () => HOURS_PER_DAY,
+  HOURS_PER_WEEK: () => HOURS_PER_WEEK,
+  MINUTES_PER_DAY: () => MINUTES_PER_DAY,
+  MINUTES_PER_HOUR: () => MINUTES_PER_HOUR,
+  MINUTES_PER_WEEK: () => MINUTES_PER_WEEK,
+  MS_PER_DAY: () => MS_PER_DAY,
+  MS_PER_HOUR: () => MS_PER_HOUR,
+  MS_PER_MINUTE: () => MS_PER_MINUTE,
+  MS_PER_SECOND: () => MS_PER_SECOND,
+  MS_PER_WEEK: () => MS_PER_WEEK,
+  SECONDS_PER_DAY: () => SECONDS_PER_DAY,
+  SECONDS_PER_HOUR: () => SECONDS_PER_HOUR,
+  SECONDS_PER_MINUTE: () => SECONDS_PER_MINUTE,
+  SECONDS_PER_WEEK: () => SECONDS_PER_WEEK
+});
+module.exports = __toCommonJS(timeConstants_exports);
+var MS_PER_SECOND = 1e3;
+var MS_PER_MINUTE = 6e4;
+var MS_PER_HOUR = 36e5;
+var MS_PER_DAY = 864e5;
+var MS_PER_WEEK = 6048e5;
+var SECONDS_PER_MINUTE = 60;
+var SECONDS_PER_HOUR = 3600;
+var SECONDS_PER_DAY = 86400;
+var SECONDS_PER_WEEK = 604800;
+var MINUTES_PER_HOUR = 60;
+var MINUTES_PER_DAY = 1440;
+var MINUTES_PER_WEEK = 10080;
+var HOURS_PER_DAY = 24;
+var HOURS_PER_WEEK = 168;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HOURS_PER_DAY,
+  HOURS_PER_WEEK,
+  MINUTES_PER_DAY,
+  MINUTES_PER_HOUR,
+  MINUTES_PER_WEEK,
+  MS_PER_DAY,
+  MS_PER_HOUR,
+  MS_PER_MINUTE,
+  MS_PER_SECOND,
+  MS_PER_WEEK,
+  SECONDS_PER_DAY,
+  SECONDS_PER_HOUR,
+  SECONDS_PER_MINUTE,
+  SECONDS_PER_WEEK
+});
+//# sourceMappingURL=timeConstants.js.map

package/timeConstants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/timeConstants.ts"],"sourcesContent":["/**\n * Note that month and year do not have fixed durations, and hence are excluded\n * from this file.\n */\n\nexport const MS_PER_SECOND = 1000;\nexport const MS_PER_MINUTE = 60_000;\nexport const MS_PER_HOUR = 3_600_000;\nexport const MS_PER_DAY = 86_400_000;\nexport const MS_PER_WEEK = 604_800_000;\n\nexport const SECONDS_PER_MINUTE = 60;\nexport const SECONDS_PER_HOUR = 3_600;\nexport const SECONDS_PER_DAY = 86_400;\nexport const SECONDS_PER_WEEK = 604_800;\n\nexport const MINUTES_PER_HOUR = 60;\nexport const MINUTES_PER_DAY = 1440;\nexport const MINUTES_PER_WEEK = 10_080;\n\nexport const HOURS_PER_DAY = 24;\nexport const HOURS_PER_WEEK = 168;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKO,IAAM,gBAAgB;AACtB,IAAM,gBAAgB;AACtB,IAAM,cAAc;AACpB,IAAM,aAAa;AACnB,IAAM,cAAc;AAEpB,IAAM,qBAAqB;AAC3B,IAAM,mBAAmB;AACzB,IAAM,kBAAkB;AACxB,IAAM,mBAAmB;AAEzB,IAAM,mBAAmB;AACzB,IAAM,kBAAkB;AACxB,IAAM,mBAAmB;AAEzB,IAAM,gBAAgB;AACtB,IAAM,iBAAiB;","names":[]}