@choksheak/ts-utils 0.2.0 → 0.2.1

package/dateTimeStr.d.ts

@@ -4,6 +4,13 @@ export type AnyDateTime = number | Date | string;
  * Date object (no conversion) into a Date object.
  */
 export declare function toDate(ts: AnyDateTime): Date;
+/**
+ * Returns a date in yyyy-MM format. E.g. '2000-01'.
+ *
+ * @param dt Specify a date object or default to the current date.
+ * @param separator Defaults to '-'.
+ */
+export declare function yyyyMm(dt?: Date, separator?: string): string;
 /**
  * Returns a date in yyyy-MM-dd format. E.g. '2000-01-02'.
  *
@@ -11,6 +18,13 @@ export declare function toDate(ts: AnyDateTime): Date;
  * @param separator Defaults to '-'.
  */
 export declare function yyyyMmDd(dt?: Date, separator?: string): string;
+/**
+ * Returns a date in hh:mm format. E.g. '01:02'.
+ *
+ * @param dt Specify a date object or default to the current date/time.
+ * @param separator Defaults to ':'.
+ */
+export declare function hhMm(dt?: Date, separator?: string): string;
 /**
  * Returns a date in hh:mm:ss format. E.g. '01:02:03'.
  *

package/dateTimeStr.js

@@ -25,10 +25,12 @@ __export(dateTimeStr_exports, {
   getLongMonthNameZeroIndexed: () => getLongMonthNameZeroIndexed,
   getShortMonthNameOneIndexed: () => getShortMonthNameOneIndexed,
   getShortMonthNameZeroIndexed: () => getShortMonthNameZeroIndexed,
+  hhMm: () => hhMm,
   hhMmSs: () => hhMmSs,
   hhMmSsMs: () => hhMmSsMs,
   toDate: () => toDate,
   tzShort: () => tzShort,
+  yyyyMm: () => yyyyMm,
   yyyyMmDd: () => yyyyMmDd
 });
 module.exports = __toCommonJS(dateTimeStr_exports);
@@ -38,17 +40,23 @@ function toDate(ts) {
   }
   return ts;
 }
-function yyyyMmDd(dt = /* @__PURE__ */ new Date(), separator = "-") {
+function yyyyMm(dt = /* @__PURE__ */ new Date(), separator = "-") {
   const yr = dt.getFullYear();
   const mth = dt.getMonth() + 1;
+  return yr + separator + (mth < 10 ? "0" + mth : mth);
+}
+function yyyyMmDd(dt = /* @__PURE__ */ new Date(), separator = "-") {
   const day = dt.getDate();
-  return yr + separator + (mth < 10 ? "0" + mth : mth) + separator + (day < 10 ? "0" + day : day);
+  return yyyyMm(dt, separator) + separator + (day < 10 ? "0" + day : day);
 }
-function hhMmSs(dt = /* @__PURE__ */ new Date(), separator = ":") {
+function hhMm(dt = /* @__PURE__ */ new Date(), separator = ":") {
   const hr = dt.getHours();
   const min = dt.getMinutes();
+  return (hr < 10 ? "0" + hr : hr) + separator + (min < 10 ? "0" + min : min);
+}
+function hhMmSs(dt = /* @__PURE__ */ new Date(), separator = ":") {
   const sec = dt.getSeconds();
-  return (hr < 10 ? "0" + hr : hr) + separator + (min < 10 ? "0" + min : min) + separator + (sec < 10 ? "0" + sec : sec);
+  return hhMm(dt, separator) + separator + (sec < 10 ? "0" + sec : sec);
 }
 function hhMmSsMs(dt = /* @__PURE__ */ new Date(), timeSeparator = ":", msSeparator = ".") {
   const ms = dt.getMilliseconds();
@@ -89,10 +97,12 @@ function getDisplayDateTime(ts) {
   getLongMonthNameZeroIndexed,
   getShortMonthNameOneIndexed,
   getShortMonthNameZeroIndexed,
+  hhMm,
   hhMmSs,
   hhMmSsMs,
   toDate,
   tzShort,
+  yyyyMm,
   yyyyMmDd
 });
 //# sourceMappingURL=dateTimeStr.js.map

package/dateTimeStr.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/dateTimeStr.ts"],"sourcesContent":["export type AnyDateTime = number | Date | string;\n\n/**\n * Convert a number (epoch milliseconds), string (parseable date/time), or\n * Date object (no conversion) into a Date object.\n */\nexport function toDate(ts: AnyDateTime): Date {\n  if (typeof ts === \"number\" || typeof ts === \"string\") {\n    return new Date(ts);\n  }\n\n  return ts;\n}\n\n/**\n * Returns a date in yyyy-MM-dd format. E.g. '2000-01-02'.\n *\n * @param dt Specify a date object or default to the current date.\n * @param separator Defaults to '-'.\n */\nexport 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\n/**\n * Returns a date in hh:mm:ss format. E.g. '01:02:03'.\n *\n * @param dt Specify a date object or default to the current date/time.\n * @param separator Defaults to ':'.\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\n/**\n * Returns a date in hh:mm:ss.SSS format. E.g. '01:02:03.004'.\n *\n * @param dt Specify a date object or default to the current date/time.\n * @param timeSeparator Separator for hh/mm/ss. Defaults to ':'.\n * @param msSeparator Separator before SSS. Defaults to '.'.\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\n/**\n * Returns the timezone string for the given date. E.g. '+8', '-3.5'.\n * Returns 'Z' for UTC.\n *\n * @param dt Specify a date object or default to the current date/time.\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\n/**\n * Returns the long month name, zero-indexed. E.g. 0 for 'January'.\n *\n * @param month Zero-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\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\n/**\n * Returns the long month name, one-indexed. E.g. 1 for 'January'.\n *\n * @param month One-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\n */\nexport function getLongMonthNameOneIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return getLongMonthNameZeroIndexed(month - 1, locales);\n}\n\n/**\n * Returns the short month name, zero-indexed. E.g. 0 for 'Jan'.\n *\n * @param month Zero-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\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\n/**\n * Returns the short month name, one-indexed. E.g. 1 for 'Jan'.\n *\n * @param month One-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\n */\nexport function getShortMonthNameOneIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return getShortMonthNameZeroIndexed(month - 1, locales);\n}\n\n/**\n * Returns a human-readable string date/time like '2025-01-01 22:31:16Z'.\n * Excludes the milliseconds assuming it is not necessary for display.\n */\nexport function getDisplayDateTime(ts: AnyDateTime) {\n  const iso = toDate(ts).toISOString();\n  const noMs = iso.slice(0, 19) + \"Z\";\n  return noMs.replace(\"T\", \" \");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMO,SAAS,OAAO,IAAuB;AAC5C,MAAI,OAAO,OAAO,YAAY,OAAO,OAAO,UAAU;AACpD,WAAO,IAAI,KAAK,EAAE;AAAA,EACpB;AAEA,SAAO;AACT;AAQO,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;AAQO,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;AASO,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;AAQO,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;AAQO,SAAS,4BACd,OACA,UAAgC,WACxB;AACR,SAAO,IAAI,KAAK,MAAM,OAAO,EAAE,EAAE,eAAe,SAAS;AAAA,IACvD,OAAO;AAAA,EACT,CAAC;AACH;AAQO,SAAS,2BACd,OACA,UAAgC,WACxB;AACR,SAAO,4BAA4B,QAAQ,GAAG,OAAO;AACvD;AAQO,SAAS,6BACd,OACA,UAAgC,WACxB;AACR,SAAO,IAAI,KAAK,KAAM,OAAO,EAAE,EAAE,eAAe,SAAS;AAAA,IACvD,OAAO;AAAA,EACT,CAAC;AACH;AAQO,SAAS,4BACd,OACA,UAAgC,WACxB;AACR,SAAO,6BAA6B,QAAQ,GAAG,OAAO;AACxD;AAMO,SAAS,mBAAmB,IAAiB;AAClD,QAAM,MAAM,OAAO,EAAE,EAAE,YAAY;AACnC,QAAM,OAAO,IAAI,MAAM,GAAG,EAAE,IAAI;AAChC,SAAO,KAAK,QAAQ,KAAK,GAAG;AAC9B;","names":[]}
+{"version":3,"sources":["../src/dateTimeStr.ts"],"sourcesContent":["export type AnyDateTime = number | Date | string;\n\n/**\n * Convert a number (epoch milliseconds), string (parseable date/time), or\n * Date object (no conversion) into a Date object.\n */\nexport function toDate(ts: AnyDateTime): Date {\n  if (typeof ts === \"number\" || typeof ts === \"string\") {\n    return new Date(ts);\n  }\n\n  return ts;\n}\n\n/**\n * Returns a date in yyyy-MM format. E.g. '2000-01'.\n *\n * @param dt Specify a date object or default to the current date.\n * @param separator Defaults to '-'.\n */\nexport function yyyyMm(dt = new Date(), separator = \"-\"): string {\n  const yr = dt.getFullYear();\n  const mth = dt.getMonth() + 1;\n\n  return yr + separator + (mth < 10 ? \"0\" + mth : mth);\n}\n\n/**\n * Returns a date in yyyy-MM-dd format. E.g. '2000-01-02'.\n *\n * @param dt Specify a date object or default to the current date.\n * @param separator Defaults to '-'.\n */\nexport function yyyyMmDd(dt = new Date(), separator = \"-\"): string {\n  const day = dt.getDate();\n\n  return yyyyMm(dt, separator) + separator + (day < 10 ? \"0\" + day : day);\n}\n\n/**\n * Returns a date in hh:mm format. E.g. '01:02'.\n *\n * @param dt Specify a date object or default to the current date/time.\n * @param separator Defaults to ':'.\n */\nexport function hhMm(dt = new Date(), separator = \":\"): string {\n  const hr = dt.getHours();\n  const min = dt.getMinutes();\n\n  return (hr < 10 ? \"0\" + hr : hr) + separator + (min < 10 ? \"0\" + min : min);\n}\n\n/**\n * Returns a date in hh:mm:ss format. E.g. '01:02:03'.\n *\n * @param dt Specify a date object or default to the current date/time.\n * @param separator Defaults to ':'.\n */\nexport function hhMmSs(dt = new Date(), separator = \":\"): string {\n  const sec = dt.getSeconds();\n\n  return hhMm(dt, separator) + separator + (sec < 10 ? \"0\" + sec : sec);\n}\n\n/**\n * Returns a date in hh:mm:ss.SSS format. E.g. '01:02:03.004'.\n *\n * @param dt Specify a date object or default to the current date/time.\n * @param timeSeparator Separator for hh/mm/ss. Defaults to ':'.\n * @param msSeparator Separator before SSS. Defaults to '.'.\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\n/**\n * Returns the timezone string for the given date. E.g. '+8', '-3.5'.\n * Returns 'Z' for UTC.\n *\n * @param dt Specify a date object or default to the current date/time.\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\n/**\n * Returns the long month name, zero-indexed. E.g. 0 for 'January'.\n *\n * @param month Zero-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\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\n/**\n * Returns the long month name, one-indexed. E.g. 1 for 'January'.\n *\n * @param month One-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\n */\nexport function getLongMonthNameOneIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return getLongMonthNameZeroIndexed(month - 1, locales);\n}\n\n/**\n * Returns the short month name, zero-indexed. E.g. 0 for 'Jan'.\n *\n * @param month Zero-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\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\n/**\n * Returns the short month name, one-indexed. E.g. 1 for 'Jan'.\n *\n * @param month One-indexed month.\n * @param locales Specify the locale, e.g. 'en-US', new Intl.Locale(\"en-US\").\n */\nexport function getShortMonthNameOneIndexed(\n  month: number,\n  locales: Intl.LocalesArgument = \"default\",\n): string {\n  return getShortMonthNameZeroIndexed(month - 1, locales);\n}\n\n/**\n * Returns a human-readable string date/time like '2025-01-01 22:31:16Z'.\n * Excludes the milliseconds assuming it is not necessary for display.\n */\nexport function getDisplayDateTime(ts: AnyDateTime) {\n  const iso = toDate(ts).toISOString();\n  const noMs = iso.slice(0, 19) + \"Z\";\n  return noMs.replace(\"T\", \" \");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMO,SAAS,OAAO,IAAuB;AAC5C,MAAI,OAAO,OAAO,YAAY,OAAO,OAAO,UAAU;AACpD,WAAO,IAAI,KAAK,EAAE;AAAA,EACpB;AAEA,SAAO;AACT;AAQO,SAAS,OAAO,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AAC/D,QAAM,KAAK,GAAG,YAAY;AAC1B,QAAM,MAAM,GAAG,SAAS,IAAI;AAE5B,SAAO,KAAK,aAAa,MAAM,KAAK,MAAM,MAAM;AAClD;AAQO,SAAS,SAAS,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AACjE,QAAM,MAAM,GAAG,QAAQ;AAEvB,SAAO,OAAO,IAAI,SAAS,IAAI,aAAa,MAAM,KAAK,MAAM,MAAM;AACrE;AAQO,SAAS,KAAK,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AAC7D,QAAM,KAAK,GAAG,SAAS;AACvB,QAAM,MAAM,GAAG,WAAW;AAE1B,UAAQ,KAAK,KAAK,MAAM,KAAK,MAAM,aAAa,MAAM,KAAK,MAAM,MAAM;AACzE;AAQO,SAAS,OAAO,KAAK,oBAAI,KAAK,GAAG,YAAY,KAAa;AAC/D,QAAM,MAAM,GAAG,WAAW;AAE1B,SAAO,KAAK,IAAI,SAAS,IAAI,aAAa,MAAM,KAAK,MAAM,MAAM;AACnE;AASO,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;AAQO,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;AAQO,SAAS,4BACd,OACA,UAAgC,WACxB;AACR,SAAO,IAAI,KAAK,MAAM,OAAO,EAAE,EAAE,eAAe,SAAS;AAAA,IACvD,OAAO;AAAA,EACT,CAAC;AACH;AAQO,SAAS,2BACd,OACA,UAAgC,WACxB;AACR,SAAO,4BAA4B,QAAQ,GAAG,OAAO;AACvD;AAQO,SAAS,6BACd,OACA,UAAgC,WACxB;AACR,SAAO,IAAI,KAAK,KAAM,OAAO,EAAE,EAAE,eAAe,SAAS;AAAA,IACvD,OAAO;AAAA,EACT,CAAC;AACH;AAQO,SAAS,4BACd,OACA,UAAgC,WACxB;AACR,SAAO,6BAA6B,QAAQ,GAAG,OAAO;AACxD;AAMO,SAAS,mBAAmB,IAAiB;AAClD,QAAM,MAAM,OAAO,EAAE,EAAE,YAAY;AACnC,QAAM,OAAO,IAAI,MAAM,GAAG,EAAE,IAAI;AAChC,SAAO,KAAK,QAAQ,KAAK,GAAG;AAC9B;","names":[]}

package/duration.d.ts

@@ -51,6 +51,10 @@ export declare function msToDuration(ms: number, durationTypeForZero?: DurationT
  * Returns the number of milliseconds for the given duration.
  */
 export declare function durationToMs(duration: Duration): number;
+/**
+ * Convenience function to return a duration given an ms or Duration.
+ */
+export declare function durationOrMsToMs(duration: number | Duration): number;
 /**
  * Format a given Duration object into a string. If the object has no fields,
  * then returns an empty string.

package/duration.js

@@ -22,6 +22,7 @@ var duration_exports = {};
 __export(duration_exports, {
   DURATION_STYLE_SUFFIX_MAP: () => DURATION_STYLE_SUFFIX_MAP,
   DURATION_TYPE_SEQUENCE: () => DURATION_TYPE_SEQUENCE,
+  durationOrMsToMs: () => durationOrMsToMs,
   durationToMs: () => durationToMs,
   formatDuration: () => formatDuration,
   msToDuration: () => msToDuration,
@@ -143,6 +144,9 @@ function durationToMs(duration) {
   const msMs = (_e = duration.milliseconds) != null ? _e : 0;
   return daysMs + hoursMs + minsMs + secsMs + msMs;
 }
+function durationOrMsToMs(duration) {
+  return typeof duration === "number" ? duration : durationToMs(duration);
+}
 function formatDuration(duration, style) {
   style = style != null ? style : "short";
   const stylePlural = getDurationStyleForPlural(style);
@@ -166,6 +170,7 @@ function readableDuration(ms, options) {
 0 && (module.exports = {
   DURATION_STYLE_SUFFIX_MAP,
   DURATION_TYPE_SEQUENCE,
+  durationOrMsToMs,
   durationToMs,
   formatDuration,
   msToDuration,

package/duration.js.map

@@ -1 +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. Weeks have fixed durations, but are excluded because we\n * use days as the max duration supported.\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\n/**\n * One of: days, hours, minutes, seconds, milliseconds\n */\nexport type DurationType = keyof Duration;\n\n/**\n * Order in which the duration type appears in the duration string.\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 with duration type\n * of durationTypeForZero.\n *\n * @param 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 * @param 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 * @param options.durationTypeForZero - Defaults to 'milliseconds'\n * @param 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":"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","names":[]}
+{"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. Weeks have fixed durations, but are excluded because we\n * use days as the max duration supported.\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\n/**\n * One of: days, hours, minutes, seconds, milliseconds\n */\nexport type DurationType = keyof Duration;\n\n/**\n * Order in which the duration type appears in the duration string.\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 with duration type\n * of durationTypeForZero.\n *\n * @param 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 * Convenience function to return a duration given an ms or Duration.\n */\nexport function durationOrMsToMs(duration: number | Duration): number {\n  return typeof duration === \"number\" ? duration : durationToMs(duration);\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 * @param 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 * @param options.durationTypeForZero - Defaults to 'milliseconds'\n * @param 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":"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","names":[]}

package/kvStore.d.ts

@@ -10,12 +10,19 @@
  * How to use?
  * Just use the `kvStore` global constant like the local storage.
  */
+import { Duration } from "./duration";
 /** One day in milliseconds. */
 export declare const MILLIS_PER_DAY = 86400000;
 /** 30 days in ms. */
 export declare const DEFAULT_EXPIRY_DELTA_MS: number;
 /** Do GC once per day. */
 export declare const GC_INTERVAL_MS = 86400000;
+type StoredObject<T> = {
+    key: string;
+    value: T;
+    storedMs: number;
+    expiryMs: number;
+};
 export declare class KVStoreField<T> {
     readonly store: KVStore;
     readonly key: string;
@@ -37,11 +44,12 @@ export declare class KVStore {
     constructor(dbName: string, dbVersion: number, defaultExpiryDeltaMs: number);
     private getOrCreateDb;
     private transact;
-    set<T>(key: string, value: T, expiryDeltaMs?: number): Promise<T>;
+    set<T>(key: string, value: T, expiryDeltaMs?: number | Duration): Promise<T>;
     /** Delete one or multiple keys. */
     delete(key: string | string[]): Promise<void>;
+    getStoredObject<T>(key: string): Promise<StoredObject<T> | undefined>;
     get<T>(key: string): Promise<T | undefined>;
-    forEach(callback: (key: string, value: unknown, expireMs: number) => void | Promise<void>): Promise<void>;
+    forEach(callback: (key: string, value: unknown, expiryMs: number) => void | Promise<void>): Promise<void>;
     /** Cannot be a getter because this needs to be async. */
     size(): Promise<number>;
     clear(): Promise<void>;
@@ -69,12 +77,18 @@ declare class KvStoreItem<T> {
     readonly defaultExpiryDeltaMs: number;
     readonly store: KVStore;
     constructor(key: string, defaultExpiryDeltaMs: number, store?: KVStore);
-    get(): Promise<Awaited<T> | undefined>;
+    /**
+     * Example usage:
+     *
+     *   const { value, storedMs, expiryMs } = await myKvItem.getStoredObject();
+     */
+    getStoredObject(): Promise<StoredObject<T> | undefined>;
+    get(): Promise<T | undefined>;
     set(value: T, expiryDeltaMs?: number): Promise<void>;
     delete(): Promise<void>;
 }
 /**
  * Create a KV store item with a key and a default expiration.
  */
-export declare function kvStoreItem<T>(key: string, defaultExpiryDeltaMs: number): KvStoreItem<T>;
+export declare function kvStoreItem<T>(key: string, defaultExpiration: number | Duration): KvStoreItem<T>;
 export {};

package/kvStore.js

@@ -49,6 +49,28 @@ __export(kvStore_exports, {
   kvStoreItem: () => kvStoreItem
 });
 module.exports = __toCommonJS(kvStore_exports);
+
+// 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;
+}
+function durationOrMsToMs(duration) {
+  return typeof duration === "number" ? duration : durationToMs(duration);
+}
+
+// src/kvStore.ts
 var DEFAULT_DB_NAME = "KVStore";
 var DEFAULT_DB_VERSION = 1;
 var STORE_NAME = "kvStore";
@@ -56,7 +78,7 @@ var MILLIS_PER_DAY = 864e5;
 var DEFAULT_EXPIRY_DELTA_MS = MILLIS_PER_DAY * 30;
 var GC_INTERVAL_MS = MILLIS_PER_DAY;
 function validateStoredObject(obj) {
-  if (!obj || typeof obj !== "object" || !("key" in obj) || typeof obj.key !== "string" || !("value" in obj) || obj.value === void 0 || !("expireMs" in obj) || typeof obj.expireMs !== "number" || Date.now() >= obj.expireMs) {
+  if (!obj || typeof obj !== "object" || !("key" in obj) || typeof obj.key !== "string" || !("value" in obj) || !("storedMs" in obj) || typeof obj.storedMs !== "number" || obj.value === void 0 || !("expiryMs" in obj) || typeof obj.expiryMs !== "number" || Date.now() >= obj.expiryMs) {
     return void 0;
   }
   return obj;
@@ -130,10 +152,12 @@ var KVStore = class {
   }
   set(_0, _1) {
     return __async(this, arguments, function* (key, value, expiryDeltaMs = this.defaultExpiryDeltaMs) {
+      const nowMs = Date.now();
       const obj = {
         key,
         value,
-        expireMs: Date.now() + expiryDeltaMs
+        storedMs: nowMs,
+        expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs)
       };
       return yield this.transact(
         "readwrite",
@@ -167,7 +191,7 @@ var KVStore = class {
       );
     });
   }
-  get(key) {
+  getStoredObject(key) {
     return __async(this, null, function* () {
       const stored = yield this.transact(
         "readonly",
@@ -188,7 +212,7 @@ var KVStore = class {
           this.gc();
           return void 0;
         }
-        return obj.value;
+        return obj;
       } catch (e) {
         console.error(`Invalid kv value: ${key}=${JSON.stringify(stored)}:`, e);
         yield this.delete(key);
@@ -197,6 +221,12 @@ var KVStore = class {
       }
     });
   }
+  get(key) {
+    return __async(this, null, function* () {
+      const obj = yield this.getStoredObject(key);
+      return obj == null ? void 0 : obj.value;
+    });
+  }
   forEach(callback) {
     return __async(this, null, function* () {
       yield this.transact("readonly", (objectStore, resolve, reject) => {
@@ -207,7 +237,7 @@ var KVStore = class {
             if (cursor.key) {
               const obj = validateStoredObject(cursor.value);
               if (obj) {
-                yield callback(String(cursor.key), obj.value, obj.expireMs);
+                yield callback(String(cursor.key), obj.value, obj.expiryMs);
               } else {
                 yield callback(String(cursor.key), void 0, 0);
               }
@@ -243,8 +273,8 @@ var KVStore = class {
   asMap() {
     return __async(this, null, function* () {
       const map = /* @__PURE__ */ new Map();
-      yield this.forEach((key, value, expireMs) => {
-        map.set(key, { value, expireMs });
+      yield this.forEach((key, value, expiryMs) => {
+        map.set(key, { value, expiryMs });
       });
       return map;
     });
@@ -279,8 +309,8 @@ var KVStore = class {
       this.lastGcMs = Date.now();
       const keysToDelete = [];
       yield this.forEach(
-        (key, value, expireMs) => __async(this, null, function* () {
-          if (value === void 0 || Date.now() >= expireMs) {
+        (key, value, expiryMs) => __async(this, null, function* () {
+          if (value === void 0 || Date.now() >= expiryMs) {
             keysToDelete.push(key);
           }
         })
@@ -310,6 +340,16 @@ var KvStoreItem = class {
     this.defaultExpiryDeltaMs = defaultExpiryDeltaMs;
     this.store = store;
   }
+  /**
+   * Example usage:
+   *
+   *   const { value, storedMs, expiryMs } = await myKvItem.getStoredObject();
+   */
+  getStoredObject() {
+    return __async(this, null, function* () {
+      return yield this.store.getStoredObject(this.key);
+    });
+  }
   get() {
     return __async(this, null, function* () {
       return yield this.store.get(this.key);
@@ -326,7 +366,8 @@ var KvStoreItem = class {
     });
   }
 };
-function kvStoreItem(key, defaultExpiryDeltaMs) {
+function kvStoreItem(key, defaultExpiration) {
+  const defaultExpiryDeltaMs = durationOrMsToMs(defaultExpiration);
   return new KvStoreItem(key, defaultExpiryDeltaMs);
 }
 // Annotate the CommonJS export names for ESM import in node:

package/kvStore.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/kvStore.ts"],"sourcesContent":["/**\n * Indexed DB key-value store with support for auto-expirations.\n *\n * Why use this?\n * 1. No need to worry about running out of storage.\n * 2. Extremely simple interface to use indexed DBs.\n * 3. Auto-expirations frees you from worrying about data clean-up.\n * 4. Any serializable data type can be stored (except undefined).\n *\n * How to use?\n * Just use the `kvStore` global constant like the local storage.\n */\n\n// Updating the DB name will cause all old entries to be gone.\nconst DEFAULT_DB_NAME = \"KVStore\";\n\n// Updating the version will cause all old entries to be gone.\nconst DEFAULT_DB_VERSION = 1;\n\n// Use a constant store name to keep things simple.\nconst STORE_NAME = \"kvStore\";\n\n/** One day in milliseconds. */\nexport const MILLIS_PER_DAY = 86_400_000;\n\n/** 30 days in ms. */\nexport const DEFAULT_EXPIRY_DELTA_MS = MILLIS_PER_DAY * 30;\n\n/** Do GC once per day. */\nexport const GC_INTERVAL_MS = MILLIS_PER_DAY;\n\ntype StoredObject<T> = {\n  key: string;\n  value: T;\n  expireMs: number;\n};\n\n/**\n * Parse a stored value string. Returns undefined if invalid or expired.\n * Throws an error if the string cannot be parsed as JSON.\n */\nfunction validateStoredObject<T>(\n  obj: StoredObject<T>,\n): StoredObject<T> | undefined {\n  if (\n    !obj ||\n    typeof obj !== \"object\" ||\n    !(\"key\" in obj) ||\n    typeof obj.key !== \"string\" ||\n    !(\"value\" in obj) ||\n    obj.value === undefined ||\n    !(\"expireMs\" in obj) ||\n    typeof obj.expireMs !== \"number\" ||\n    Date.now() >= obj.expireMs\n  ) {\n    return undefined;\n  }\n\n  return obj;\n}\n\n/** Add an `onerror` handler to the request. */\nfunction withOnError<T extends IDBRequest | IDBTransaction>(\n  request: T,\n  reject: (reason?: unknown) => void,\n): T {\n  request.onerror = (event) => {\n    reject(event);\n  };\n\n  return request;\n}\n\nexport class KVStoreField<T> {\n  public constructor(\n    public readonly store: KVStore,\n    public readonly key: string,\n  ) {}\n\n  public get(): Promise<T | undefined> {\n    return this.store.get(this.key);\n  }\n\n  public set(t: T): Promise<T> {\n    return this.store.set(this.key, t);\n  }\n\n  public delete(): Promise<void> {\n    return this.store.delete(this.key);\n  }\n}\n\n/**\n * You can create multiple KVStores if you want, but most likely you will only\n * need to use the default `kvStore` instance.\n */\nexport class KVStore {\n  // We'll init the DB only on first use.\n  private db: IDBDatabase | undefined;\n\n  // Local storage key name for the last GC completed timestamp.\n  public readonly gcMsStorageKey: string;\n\n  public constructor(\n    public readonly dbName: string,\n    public readonly dbVersion: number,\n    public readonly defaultExpiryDeltaMs: number,\n  ) {\n    this.gcMsStorageKey = `__kvStore:lastGcMs:${dbName}:v${dbVersion}:${STORE_NAME}`;\n  }\n\n  private async getOrCreateDb() {\n    if (!this.db) {\n      this.db = await new Promise<IDBDatabase>((resolve, reject) => {\n        const request = withOnError(\n          globalThis.indexedDB.open(this.dbName, this.dbVersion),\n          reject,\n        );\n\n        request.onupgradeneeded = (event) => {\n          const db = (event.target as unknown as { result: IDBDatabase })\n            .result;\n\n          // Create the store on DB init.\n          const objectStore = db.createObjectStore(STORE_NAME, {\n            keyPath: \"key\",\n          });\n\n          objectStore.createIndex(\"key\", \"key\", {\n            unique: true,\n          });\n        };\n\n        request.onsuccess = (event) => {\n          const db = (event.target as unknown as { result: IDBDatabase })\n            .result;\n          resolve(db);\n        };\n      });\n    }\n\n    return this.db;\n  }\n\n  private async transact<T>(\n    mode: IDBTransactionMode,\n    callback: (\n      objectStore: IDBObjectStore,\n      resolve: (t: T) => void,\n      reject: (reason?: unknown) => void,\n    ) => void,\n  ): Promise<T> {\n    const db = await this.getOrCreateDb();\n\n    return await new Promise<T>((resolve, reject) => {\n      const transaction = withOnError(db.transaction(STORE_NAME, mode), reject);\n\n      transaction.onabort = (event) => {\n        reject(event);\n      };\n\n      const objectStore = transaction.objectStore(STORE_NAME);\n\n      callback(objectStore, resolve, reject);\n    });\n  }\n\n  public async set<T>(\n    key: string,\n    value: T,\n    expiryDeltaMs: number = this.defaultExpiryDeltaMs,\n  ): Promise<T> {\n    const obj = {\n      key,\n      value,\n      expireMs: Date.now() + expiryDeltaMs,\n    };\n\n    return await this.transact<T>(\n      \"readwrite\",\n      (objectStore, resolve, reject) => {\n        const request = withOnError(objectStore.put(obj), reject);\n\n        request.onsuccess = () => {\n          resolve(value);\n\n          this.gc(); // check GC on every write\n        };\n      },\n    );\n  }\n\n  /** Delete one or multiple keys. */\n  public async delete(key: string | string[]): Promise<void> {\n    return await this.transact<void>(\n      \"readwrite\",\n      (objectStore, resolve, reject) => {\n        objectStore.transaction.oncomplete = () => {\n          resolve();\n        };\n\n        if (typeof key === \"string\") {\n          withOnError(objectStore.delete(key), reject);\n        } else {\n          for (const k of key) {\n            withOnError(objectStore.delete(k), reject);\n          }\n        }\n      },\n    );\n  }\n\n  public async get<T>(key: string): Promise<T | undefined> {\n    const stored = await this.transact<StoredObject<T> | undefined>(\n      \"readonly\",\n      (objectStore, resolve, reject) => {\n        const request = withOnError(objectStore.get(key), reject);\n\n        request.onsuccess = () => {\n          resolve(request.result);\n        };\n      },\n    );\n\n    if (!stored) {\n      return undefined;\n    }\n\n    try {\n      const obj = validateStoredObject(stored);\n      if (!obj) {\n        await this.delete(key);\n\n        this.gc(); // check GC on every read of an expired key\n\n        return undefined;\n      }\n\n      return obj.value;\n    } catch (e) {\n      console.error(`Invalid kv value: ${key}=${JSON.stringify(stored)}:`, e);\n      await this.delete(key);\n\n      this.gc(); // check GC on every read of an invalid key\n\n      return undefined;\n    }\n  }\n\n  public async forEach(\n    callback: (\n      key: string,\n      value: unknown,\n      expireMs: number,\n    ) => void | Promise<void>,\n  ): Promise<void> {\n    await this.transact<void>(\"readonly\", (objectStore, resolve, reject) => {\n      const request = withOnError(objectStore.openCursor(), reject);\n\n      request.onsuccess = async (event) => {\n        const cursor = (\n          event.target as unknown as { result: IDBCursorWithValue }\n        ).result;\n\n        if (cursor) {\n          if (cursor.key) {\n            const obj = validateStoredObject(cursor.value);\n            if (obj) {\n              await callback(String(cursor.key), obj.value, obj.expireMs);\n            } else {\n              await callback(String(cursor.key), undefined, 0);\n            }\n          }\n          cursor.continue();\n        } else {\n          resolve();\n        }\n      };\n    });\n  }\n\n  /** Cannot be a getter because this needs to be async. */\n  public async size() {\n    let count = 0;\n    await this.forEach(() => {\n      count++;\n    });\n    return count;\n  }\n\n  public async clear() {\n    const keys: string[] = [];\n    await this.forEach((key) => {\n      keys.push(key);\n    });\n\n    await this.delete(keys);\n  }\n\n  /** Mainly for debugging dumps. */\n  public async asMap(): Promise<Map<string, unknown>> {\n    const map = new Map<string, unknown>();\n    await this.forEach((key, value, expireMs) => {\n      map.set(key, { value, expireMs });\n    });\n    return map;\n  }\n\n  public get lastGcMs(): number {\n    const lastGcMsStr = globalThis.localStorage.getItem(this.gcMsStorageKey);\n    if (!lastGcMsStr) return 0;\n\n    const ms = Number(lastGcMsStr);\n    return isNaN(ms) ? 0 : ms;\n  }\n\n  public set lastGcMs(ms: number) {\n    globalThis.localStorage.setItem(this.gcMsStorageKey, String(ms));\n  }\n\n  /** Perform garbage-collection if due. */\n  public async gc() {\n    const lastGcMs = this.lastGcMs;\n\n    // Set initial timestamp - no need GC now.\n    if (!lastGcMs) {\n      this.lastGcMs = Date.now();\n      return;\n    }\n\n    if (Date.now() < lastGcMs + GC_INTERVAL_MS) {\n      return; // not due for next GC yet\n    }\n\n    // GC is due now, so run it.\n    await this.gcNow();\n  }\n\n  /** Perform garbage-collection immediately without checking. */\n  public async gcNow() {\n    console.log(`Starting kvStore GC on ${this.dbName} v${this.dbVersion}...`);\n\n    // Prevent concurrent GC runs.\n    this.lastGcMs = Date.now();\n\n    const keysToDelete: string[] = [];\n    await this.forEach(\n      async (key: string, value: unknown, expireMs: number) => {\n        if (value === undefined || Date.now() >= expireMs) {\n          keysToDelete.push(key);\n        }\n      },\n    );\n\n    if (keysToDelete.length) {\n      await this.delete(keysToDelete);\n    }\n\n    console.log(\n      `Finished kvStore GC on ${this.dbName} v${this.dbVersion} ` +\n        `- deleted ${keysToDelete.length} keys`,\n    );\n\n    // Mark the end time as last GC time.\n    this.lastGcMs = Date.now();\n  }\n\n  /** Get an independent store item with a locked key and value type. */\n  public field<T>(key: string) {\n    return new KVStoreField<T>(this, key);\n  }\n}\n\n/**\n * Default KV store ready for immediate use. You can create new instances if\n * you want, but most likely you will only need one store instance.\n */\nexport const kvStore = new KVStore(\n  DEFAULT_DB_NAME,\n  DEFAULT_DB_VERSION,\n  DEFAULT_EXPIRY_DELTA_MS,\n);\n\n/**\n * Class to represent one key in the store with a default expiration.\n */\nclass KvStoreItem<T> {\n  public constructor(\n    public readonly key: string,\n    public readonly defaultExpiryDeltaMs: number,\n    public readonly store = kvStore,\n  ) {}\n\n  public async get(): Promise<Awaited<T> | undefined> {\n    return await this.store.get(this.key);\n  }\n\n  public async set(\n    value: T,\n    expiryDeltaMs: number = this.defaultExpiryDeltaMs,\n  ): Promise<void> {\n    await this.store.set(this.key, value, expiryDeltaMs);\n  }\n\n  public async delete(): Promise<void> {\n    await this.store.delete(this.key);\n  }\n}\n\n/**\n * Create a KV store item with a key and a default expiration.\n */\nexport function kvStoreItem<T>(\n  key: string,\n  defaultExpiryDeltaMs: number,\n): KvStoreItem<T> {\n  return new KvStoreItem<T>(key, defaultExpiryDeltaMs);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/kvStore.ts","../src/timeConstants.ts","../src/duration.ts"],"sourcesContent":["/**\n * Indexed DB key-value store with support for auto-expirations.\n *\n * Why use this?\n * 1. No need to worry about running out of storage.\n * 2. Extremely simple interface to use indexed DBs.\n * 3. Auto-expirations frees you from worrying about data clean-up.\n * 4. Any serializable data type can be stored (except undefined).\n *\n * How to use?\n * Just use the `kvStore` global constant like the local storage.\n */\n\nimport { Duration, durationOrMsToMs } from \"./duration\";\n\n// Updating the DB name will cause all old entries to be gone.\nconst DEFAULT_DB_NAME = \"KVStore\";\n\n// Updating the version will cause all old entries to be gone.\nconst DEFAULT_DB_VERSION = 1;\n\n// Use a constant store name to keep things simple.\nconst STORE_NAME = \"kvStore\";\n\n/** One day in milliseconds. */\nexport const MILLIS_PER_DAY = 86_400_000;\n\n/** 30 days in ms. */\nexport const DEFAULT_EXPIRY_DELTA_MS = MILLIS_PER_DAY * 30;\n\n/** Do GC once per day. */\nexport const GC_INTERVAL_MS = MILLIS_PER_DAY;\n\ntype StoredObject<T> = {\n  key: string;\n  value: T;\n  storedMs: number;\n  expiryMs: number;\n};\n\n/**\n * Parse a stored value string. Returns undefined if invalid or expired.\n * Throws an error if the string cannot be parsed as JSON.\n */\nfunction validateStoredObject<T>(\n  obj: StoredObject<T>,\n): StoredObject<T> | undefined {\n  if (\n    !obj ||\n    typeof obj !== \"object\" ||\n    !(\"key\" in obj) ||\n    typeof obj.key !== \"string\" ||\n    !(\"value\" in obj) ||\n    !(\"storedMs\" in obj) ||\n    typeof obj.storedMs !== \"number\" ||\n    obj.value === undefined ||\n    !(\"expiryMs\" in obj) ||\n    typeof obj.expiryMs !== \"number\" ||\n    Date.now() >= obj.expiryMs\n  ) {\n    return undefined;\n  }\n\n  return obj;\n}\n\n/** Add an `onerror` handler to the request. */\nfunction withOnError<T extends IDBRequest | IDBTransaction>(\n  request: T,\n  reject: (reason?: unknown) => void,\n): T {\n  request.onerror = (event) => {\n    reject(event);\n  };\n\n  return request;\n}\n\nexport class KVStoreField<T> {\n  public constructor(\n    public readonly store: KVStore,\n    public readonly key: string,\n  ) {}\n\n  public get(): Promise<T | undefined> {\n    return this.store.get(this.key);\n  }\n\n  public set(t: T): Promise<T> {\n    return this.store.set(this.key, t);\n  }\n\n  public delete(): Promise<void> {\n    return this.store.delete(this.key);\n  }\n}\n\n/**\n * You can create multiple KVStores if you want, but most likely you will only\n * need to use the default `kvStore` instance.\n */\nexport class KVStore {\n  // We'll init the DB only on first use.\n  private db: IDBDatabase | undefined;\n\n  // Local storage key name for the last GC completed timestamp.\n  public readonly gcMsStorageKey: string;\n\n  public constructor(\n    public readonly dbName: string,\n    public readonly dbVersion: number,\n    public readonly defaultExpiryDeltaMs: number,\n  ) {\n    this.gcMsStorageKey = `__kvStore:lastGcMs:${dbName}:v${dbVersion}:${STORE_NAME}`;\n  }\n\n  private async getOrCreateDb() {\n    if (!this.db) {\n      this.db = await new Promise<IDBDatabase>((resolve, reject) => {\n        const request = withOnError(\n          globalThis.indexedDB.open(this.dbName, this.dbVersion),\n          reject,\n        );\n\n        request.onupgradeneeded = (event) => {\n          const db = (event.target as unknown as { result: IDBDatabase })\n            .result;\n\n          // Create the store on DB init.\n          const objectStore = db.createObjectStore(STORE_NAME, {\n            keyPath: \"key\",\n          });\n\n          objectStore.createIndex(\"key\", \"key\", {\n            unique: true,\n          });\n        };\n\n        request.onsuccess = (event) => {\n          const db = (event.target as unknown as { result: IDBDatabase })\n            .result;\n          resolve(db);\n        };\n      });\n    }\n\n    return this.db;\n  }\n\n  private async transact<T>(\n    mode: IDBTransactionMode,\n    callback: (\n      objectStore: IDBObjectStore,\n      resolve: (t: T) => void,\n      reject: (reason?: unknown) => void,\n    ) => void,\n  ): Promise<T> {\n    const db = await this.getOrCreateDb();\n\n    return await new Promise<T>((resolve, reject) => {\n      const transaction = withOnError(db.transaction(STORE_NAME, mode), reject);\n\n      transaction.onabort = (event) => {\n        reject(event);\n      };\n\n      const objectStore = transaction.objectStore(STORE_NAME);\n\n      callback(objectStore, resolve, reject);\n    });\n  }\n\n  public async set<T>(\n    key: string,\n    value: T,\n    expiryDeltaMs: number | Duration = this.defaultExpiryDeltaMs,\n  ): Promise<T> {\n    const nowMs = Date.now();\n    const obj: StoredObject<T> = {\n      key,\n      value,\n      storedMs: nowMs,\n      expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs),\n    };\n\n    return await this.transact<T>(\n      \"readwrite\",\n      (objectStore, resolve, reject) => {\n        const request = withOnError(objectStore.put(obj), reject);\n\n        request.onsuccess = () => {\n          resolve(value);\n\n          this.gc(); // check GC on every write\n        };\n      },\n    );\n  }\n\n  /** Delete one or multiple keys. */\n  public async delete(key: string | string[]): Promise<void> {\n    return await this.transact<void>(\n      \"readwrite\",\n      (objectStore, resolve, reject) => {\n        objectStore.transaction.oncomplete = () => {\n          resolve();\n        };\n\n        if (typeof key === \"string\") {\n          withOnError(objectStore.delete(key), reject);\n        } else {\n          for (const k of key) {\n            withOnError(objectStore.delete(k), reject);\n          }\n        }\n      },\n    );\n  }\n\n  public async getStoredObject<T>(\n    key: string,\n  ): Promise<StoredObject<T> | undefined> {\n    const stored = await this.transact<StoredObject<T> | undefined>(\n      \"readonly\",\n      (objectStore, resolve, reject) => {\n        const request = withOnError(objectStore.get(key), reject);\n\n        request.onsuccess = () => {\n          resolve(request.result);\n        };\n      },\n    );\n\n    if (!stored) {\n      return undefined;\n    }\n\n    try {\n      const obj = validateStoredObject(stored);\n      if (!obj) {\n        await this.delete(key);\n\n        this.gc(); // check GC on every read of an expired key\n\n        return undefined;\n      }\n\n      return obj;\n    } catch (e) {\n      console.error(`Invalid kv value: ${key}=${JSON.stringify(stored)}:`, e);\n      await this.delete(key);\n\n      this.gc(); // check GC on every read of an invalid key\n\n      return undefined;\n    }\n  }\n\n  public async get<T>(key: string): Promise<T | undefined> {\n    const obj = await this.getStoredObject<T>(key);\n\n    return obj?.value;\n  }\n\n  public async forEach(\n    callback: (\n      key: string,\n      value: unknown,\n      expiryMs: number,\n    ) => void | Promise<void>,\n  ): Promise<void> {\n    await this.transact<void>(\"readonly\", (objectStore, resolve, reject) => {\n      const request = withOnError(objectStore.openCursor(), reject);\n\n      request.onsuccess = async (event) => {\n        const cursor = (\n          event.target as unknown as { result: IDBCursorWithValue }\n        ).result;\n\n        if (cursor) {\n          if (cursor.key) {\n            const obj = validateStoredObject(cursor.value);\n            if (obj) {\n              await callback(String(cursor.key), obj.value, obj.expiryMs);\n            } else {\n              await callback(String(cursor.key), undefined, 0);\n            }\n          }\n          cursor.continue();\n        } else {\n          resolve();\n        }\n      };\n    });\n  }\n\n  /** Cannot be a getter because this needs to be async. */\n  public async size() {\n    let count = 0;\n    await this.forEach(() => {\n      count++;\n    });\n    return count;\n  }\n\n  public async clear() {\n    const keys: string[] = [];\n    await this.forEach((key) => {\n      keys.push(key);\n    });\n\n    await this.delete(keys);\n  }\n\n  /** Mainly for debugging dumps. */\n  public async asMap(): Promise<Map<string, unknown>> {\n    const map = new Map<string, unknown>();\n    await this.forEach((key, value, expiryMs) => {\n      map.set(key, { value, expiryMs });\n    });\n    return map;\n  }\n\n  public get lastGcMs(): number {\n    const lastGcMsStr = globalThis.localStorage.getItem(this.gcMsStorageKey);\n    if (!lastGcMsStr) return 0;\n\n    const ms = Number(lastGcMsStr);\n    return isNaN(ms) ? 0 : ms;\n  }\n\n  public set lastGcMs(ms: number) {\n    globalThis.localStorage.setItem(this.gcMsStorageKey, String(ms));\n  }\n\n  /** Perform garbage-collection if due. */\n  public async gc() {\n    const lastGcMs = this.lastGcMs;\n\n    // Set initial timestamp - no need GC now.\n    if (!lastGcMs) {\n      this.lastGcMs = Date.now();\n      return;\n    }\n\n    if (Date.now() < lastGcMs + GC_INTERVAL_MS) {\n      return; // not due for next GC yet\n    }\n\n    // GC is due now, so run it.\n    await this.gcNow();\n  }\n\n  /** Perform garbage-collection immediately without checking. */\n  public async gcNow() {\n    console.log(`Starting kvStore GC on ${this.dbName} v${this.dbVersion}...`);\n\n    // Prevent concurrent GC runs.\n    this.lastGcMs = Date.now();\n\n    const keysToDelete: string[] = [];\n    await this.forEach(\n      async (key: string, value: unknown, expiryMs: number) => {\n        if (value === undefined || Date.now() >= expiryMs) {\n          keysToDelete.push(key);\n        }\n      },\n    );\n\n    if (keysToDelete.length) {\n      await this.delete(keysToDelete);\n    }\n\n    console.log(\n      `Finished kvStore GC on ${this.dbName} v${this.dbVersion} ` +\n        `- deleted ${keysToDelete.length} keys`,\n    );\n\n    // Mark the end time as last GC time.\n    this.lastGcMs = Date.now();\n  }\n\n  /** Get an independent store item with a locked key and value type. */\n  public field<T>(key: string) {\n    return new KVStoreField<T>(this, key);\n  }\n}\n\n/**\n * Default KV store ready for immediate use. You can create new instances if\n * you want, but most likely you will only need one store instance.\n */\nexport const kvStore = new KVStore(\n  DEFAULT_DB_NAME,\n  DEFAULT_DB_VERSION,\n  DEFAULT_EXPIRY_DELTA_MS,\n);\n\n/**\n * Class to represent one key in the store with a default expiration.\n */\nclass KvStoreItem<T> {\n  public constructor(\n    public readonly key: string,\n    public readonly defaultExpiryDeltaMs: number,\n    public readonly store = kvStore,\n  ) {}\n\n  /**\n   * Example usage:\n   *\n   *   const { value, storedMs, expiryMs } = await myKvItem.getStoredObject();\n   */\n  public async getStoredObject(): Promise<StoredObject<T> | undefined> {\n    return await this.store.getStoredObject(this.key);\n  }\n\n  public async get(): Promise<T | undefined> {\n    return await this.store.get(this.key);\n  }\n\n  public async set(\n    value: T,\n    expiryDeltaMs: number = this.defaultExpiryDeltaMs,\n  ): Promise<void> {\n    await this.store.set(this.key, value, expiryDeltaMs);\n  }\n\n  public async delete(): Promise<void> {\n    await this.store.delete(this.key);\n  }\n}\n\n/**\n * Create a KV store item with a key and a default expiration.\n */\nexport function kvStoreItem<T>(\n  key: string,\n  defaultExpiration: number | Duration,\n): KvStoreItem<T> {\n  const defaultExpiryDeltaMs = durationOrMsToMs(defaultExpiration);\n\n  return new KvStoreItem<T>(key, defaultExpiryDeltaMs);\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. Weeks have fixed durations, but are excluded because we\n * use days as the max duration supported.\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\n/**\n * One of: days, hours, minutes, seconds, milliseconds\n */\nexport type DurationType = keyof Duration;\n\n/**\n * Order in which the duration type appears in the duration string.\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 with duration type\n * of durationTypeForZero.\n *\n * @param 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 * Convenience function to return a duration given an ms or Duration.\n */\nexport function durationOrMsToMs(duration: number | Duration): number {\n  return typeof duration === \"number\" ? duration : durationToMs(duration);\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 * @param 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 * @param options.durationTypeForZero - Defaults to 'milliseconds'\n * @param 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":"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","names":[]}

package/localStorageCache.d.ts

@@ -1,7 +1,8 @@
 import { Duration } from "./duration";
 export type StoredItem<T> = {
     value: T;
-    expireMs: number;
+    storedMs: number;
+    expiryMs: number;
 };
 /**
  * Simple local storage cache with support for auto-expiration.
@@ -35,7 +36,13 @@ declare class CacheItem<T> {
     /**
      * Set the value of this item with auto-expiration.
      */
-    set(value: T): void;
+    set(value: T, expiryDelta?: number | Duration): void;
+    /**
+     * Example usage:
+     *
+     *   const { value, storedMs, expiryMs } = await myItem.getStoredItem();
+     */
+    getStoredItem(): StoredItem<T> | undefined;
     /**
      * Get the value of this item, or undefined if value is not set or expired.
      */

package/localStorageCache.js

@@ -40,10 +40,13 @@ function durationToMs(duration) {
   const msMs = (_e = duration.milliseconds) != null ? _e : 0;
   return daysMs + hoursMs + minsMs + secsMs + msMs;
 }
+function durationOrMsToMs(duration) {
+  return typeof duration === "number" ? duration : durationToMs(duration);
+}
 
 // src/localStorageCache.ts
 function storeItem(key, expires, logError = true, defaultValue) {
-  const expireDeltaMs = typeof expires === "number" ? expires : durationToMs(expires);
+  const expireDeltaMs = durationOrMsToMs(expires);
   return new CacheItem(key, expireDeltaMs, logError, defaultValue);
 }
 var CacheItem = class {
@@ -59,27 +62,33 @@ var CacheItem = class {
   /**
    * Set the value of this item with auto-expiration.
    */
-  set(value) {
-    const expireMs = Date.now() + this.expireDeltaMs;
-    const toStore = { value, expireMs };
+  set(value, expiryDelta = this.expireDeltaMs) {
+    const nowMs = Date.now();
+    const toStore = {
+      value,
+      storedMs: nowMs,
+      expiryMs: nowMs + durationOrMsToMs(expiryDelta)
+    };
     const valueStr = JSON.stringify(toStore);
     globalThis.localStorage.setItem(this.key, valueStr);
   }
   /**
-   * Get the value of this item, or undefined if value is not set or expired.
+   * Example usage:
+   *
+   *   const { value, storedMs, expiryMs } = await myItem.getStoredItem();
    */
-  get() {
+  getStoredItem() {
     const jsonStr = globalThis.localStorage.getItem(this.key);
     if (!jsonStr) {
-      return this.defaultValue;
+      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) {
+      if (!obj || typeof obj !== "object" || !("value" in obj) || !("storedMs" in obj) || typeof obj.storedMs !== "number" || !("expiryMs" in obj) || typeof obj.expiryMs !== "number" || Date.now() >= obj.expiryMs) {
         this.remove();
-        return this.defaultValue;
+        return void 0;
       }
-      return obj.value;
+      return obj;
     } catch (e) {
       if (this.logError) {
         console.error(
@@ -88,9 +97,16 @@ var CacheItem = class {
         );
       }
       this.remove();
-      return this.defaultValue;
+      return void 0;
     }
   }
+  /**
+   * Get the value of this item, or undefined if value is not set or expired.
+   */
+  get() {
+    const stored = this.getStoredItem();
+    return stored !== void 0 ? stored.value : this.defaultValue;
+  }
   /**
    * Remove the value of this item.
    */

package/localStorageCache.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/localStorageCache.ts","../src/timeConstants.ts","../src/duration.ts"],"sourcesContent":["import { Duration, durationToMs } from \"./duration\";\n\nexport type StoredItem<T> = { value: T; expireMs: number };\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 * @param key The store key in local storage.\n * @param expires Either a number in milliseconds, or a Duration object\n * @param logError Log an error if we found an invalid object in the store.\n *   The invalid object is usually a string that cannot be parsed as JSON.\n * @param defaultValue Specify a default value to use for the object. Defaults\n *   to undefined.\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    public readonly defaultValue: T | undefined,\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 toStore: StoredItem<T> = { value, expireMs };\n    const valueStr = JSON.stringify(toStore);\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) {\n      return this.defaultValue;\n    }\n\n    try {\n      const obj: StoredItem<T> | undefined = JSON.parse(jsonStr);\n\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        this.remove();\n        return this.defaultValue;\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      this.remove();\n      return this.defaultValue;\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. Weeks have fixed durations, but are excluded because we\n * use days as the max duration supported.\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\n/**\n * One of: days, hours, minutes, seconds, milliseconds\n */\nexport type DurationType = keyof Duration;\n\n/**\n * Order in which the duration type appears in the duration string.\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 with duration type\n * of durationTypeForZero.\n *\n * @param 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 * @param 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 * @param options.durationTypeForZero - Defaults to 'milliseconds'\n * @param 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;;;ACkLnB,SAAS,aAAa,UAA4B;AA1LzD;AA2LE,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;;;AF3KO,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,UACA,cAChB;AAJgB;AACA;AACA;AACA;AAAA,EACf;AAAA;AAAA;AAAA;AAAA,EAKI,IAAI,OAAgB;AACzB,UAAM,WAAW,KAAK,IAAI,IAAI,KAAK;AACnC,UAAM,UAAyB,EAAE,OAAO,SAAS;AACjD,UAAM,WAAW,KAAK,UAAU,OAAO;AAEvC,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,SAAS;AACZ,aAAO,KAAK;AAAA,IACd;AAEA,QAAI;AACF,YAAM,MAAiC,KAAK,MAAM,OAAO;AAEzD,UACE,CAAC,OACD,OAAO,QAAQ,YACf,EAAE,WAAW,QACb,EAAE,cAAc,QAChB,OAAO,IAAI,aAAa,YACxB,KAAK,IAAI,KAAK,IAAI,UAClB;AACA,aAAK,OAAO;AACZ,eAAO,KAAK;AAAA,MACd;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,WAAK,OAAO;AACZ,aAAO,KAAK;AAAA,IACd;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,SAAe;AACpB,eAAW,aAAa,WAAW,KAAK,GAAG;AAAA,EAC7C;AACF;","names":[]}
+{"version":3,"sources":["../src/localStorageCache.ts","../src/timeConstants.ts","../src/duration.ts"],"sourcesContent":["import { Duration, durationOrMsToMs } from \"./duration\";\n\nexport type StoredItem<T> = { value: T; storedMs: number; expiryMs: number };\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 * @param key The store key in local storage.\n * @param expires Either a number in milliseconds, or a Duration object\n * @param logError Log an error if we found an invalid object in the store.\n *   The invalid object is usually a string that cannot be parsed as JSON.\n * @param defaultValue Specify a default value to use for the object. Defaults\n *   to undefined.\n */\nexport function storeItem<T>(\n  key: string,\n  expires: number | Duration,\n  logError = true,\n  defaultValue?: T,\n) {\n  const expireDeltaMs = durationOrMsToMs(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    public readonly defaultValue: T | undefined,\n  ) {}\n\n  /**\n   * Set the value of this item with auto-expiration.\n   */\n  public set(\n    value: T,\n    expiryDelta: number | Duration = this.expireDeltaMs,\n  ): void {\n    const nowMs = Date.now();\n    const toStore: StoredItem<T> = {\n      value,\n      storedMs: nowMs,\n      expiryMs: nowMs + durationOrMsToMs(expiryDelta),\n    };\n    const valueStr = JSON.stringify(toStore);\n\n    globalThis.localStorage.setItem(this.key, valueStr);\n  }\n\n  /**\n   * Example usage:\n   *\n   *   const { value, storedMs, expiryMs } = await myItem.getStoredItem();\n   */\n  public getStoredItem(): StoredItem<T> | undefined {\n    const jsonStr = globalThis.localStorage.getItem(this.key);\n\n    if (!jsonStr) {\n      return undefined;\n    }\n\n    try {\n      const obj: StoredItem<T> | undefined = JSON.parse(jsonStr);\n\n      if (\n        !obj ||\n        typeof obj !== \"object\" ||\n        !(\"value\" in obj) ||\n        !(\"storedMs\" in obj) ||\n        typeof obj.storedMs !== \"number\" ||\n        !(\"expiryMs\" in obj) ||\n        typeof obj.expiryMs !== \"number\" ||\n        Date.now() >= obj.expiryMs\n      ) {\n        this.remove();\n        return undefined;\n      }\n\n      return obj;\n    } catch (e) {\n      if (this.logError) {\n        console.error(\n          `Found invalid storage value: ${this.key}=${jsonStr}:`,\n          e,\n        );\n      }\n      this.remove();\n      return undefined;\n    }\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 stored = this.getStoredItem();\n\n    return stored !== undefined ? stored.value : this.defaultValue;\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. Weeks have fixed durations, but are excluded because we\n * use days as the max duration supported.\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\n/**\n * One of: days, hours, minutes, seconds, milliseconds\n */\nexport type DurationType = keyof Duration;\n\n/**\n * Order in which the duration type appears in the duration string.\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 with duration type\n * of durationTypeForZero.\n *\n * @param 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 * Convenience function to return a duration given an ms or Duration.\n */\nexport function durationOrMsToMs(duration: number | Duration): number {\n  return typeof duration === \"number\" ? duration : durationToMs(duration);\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 * @param 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 * @param options.durationTypeForZero - Defaults to 'milliseconds'\n * @param 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;;;ACkLnB,SAAS,aAAa,UAA4B;AA1LzD;AA2LE,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;AAKO,SAAS,iBAAiB,UAAqC;AACpE,SAAO,OAAO,aAAa,WAAW,WAAW,aAAa,QAAQ;AACxE;;;AFlLO,SAAS,UACd,KACA,SACA,WAAW,MACX,cACA;AACA,QAAM,gBAAgB,iBAAiB,OAAO;AAE9C,SAAO,IAAI,UAAa,KAAK,eAAe,UAAU,YAAY;AACpE;AAEA,IAAM,YAAN,MAAmB;AAAA;AAAA;AAAA;AAAA,EAIV,YACW,KACA,eACA,UACA,cAChB;AAJgB;AACA;AACA;AACA;AAAA,EACf;AAAA;AAAA;AAAA;AAAA,EAKI,IACL,OACA,cAAiC,KAAK,eAChC;AACN,UAAM,QAAQ,KAAK,IAAI;AACvB,UAAM,UAAyB;AAAA,MAC7B;AAAA,MACA,UAAU;AAAA,MACV,UAAU,QAAQ,iBAAiB,WAAW;AAAA,IAChD;AACA,UAAM,WAAW,KAAK,UAAU,OAAO;AAEvC,eAAW,aAAa,QAAQ,KAAK,KAAK,QAAQ;AAAA,EACpD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,gBAA2C;AAChD,UAAM,UAAU,WAAW,aAAa,QAAQ,KAAK,GAAG;AAExD,QAAI,CAAC,SAAS;AACZ,aAAO;AAAA,IACT;AAEA,QAAI;AACF,YAAM,MAAiC,KAAK,MAAM,OAAO;AAEzD,UACE,CAAC,OACD,OAAO,QAAQ,YACf,EAAE,WAAW,QACb,EAAE,cAAc,QAChB,OAAO,IAAI,aAAa,YACxB,EAAE,cAAc,QAChB,OAAO,IAAI,aAAa,YACxB,KAAK,IAAI,KAAK,IAAI,UAClB;AACA,aAAK,OAAO;AACZ,eAAO;AAAA,MACT;AAEA,aAAO;AAAA,IACT,SAAS,GAAG;AACV,UAAI,KAAK,UAAU;AACjB,gBAAQ;AAAA,UACN,gCAAgC,KAAK,GAAG,IAAI,OAAO;AAAA,UACnD;AAAA,QACF;AAAA,MACF;AACA,WAAK,OAAO;AACZ,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKO,MAAqB;AAC1B,UAAM,SAAS,KAAK,cAAc;AAElC,WAAO,WAAW,SAAY,OAAO,QAAQ,KAAK;AAAA,EACpD;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.2.0",
+  "version": "0.2.1",
   "description": "Random Typescript utilities with support for full tree-shaking",
   "private": false,
   "scripts": {

package/src/dateTimeStr.ts

@@ -13,43 +13,53 @@ export function toDate(ts: AnyDateTime): Date {
 }
 
 /**
- * Returns a date in yyyy-MM-dd format. E.g. '2000-01-02'.
+ * Returns a date in yyyy-MM format. E.g. '2000-01'.
  *
  * @param dt Specify a date object or default to the current date.
  * @param separator Defaults to '-'.
  */
-export function yyyyMmDd(dt = new Date(), separator = "-"): string {
+export function yyyyMm(dt = new Date(), separator = "-"): string {
   const yr = dt.getFullYear();
   const mth = dt.getMonth() + 1;
+
+  return yr + separator + (mth < 10 ? "0" + mth : mth);
+}
+
+/**
+ * Returns a date in yyyy-MM-dd format. E.g. '2000-01-02'.
+ *
+ * @param dt Specify a date object or default to the current date.
+ * @param separator Defaults to '-'.
+ */
+export function yyyyMmDd(dt = new Date(), separator = "-"): string {
   const day = dt.getDate();
 
-  return (
-    yr +
-    separator +
-    (mth < 10 ? "0" + mth : mth) +
-    separator +
-    (day < 10 ? "0" + day : day)
-  );
+  return yyyyMm(dt, separator) + separator + (day < 10 ? "0" + day : day);
 }
 
 /**
- * Returns a date in hh:mm:ss format. E.g. '01:02:03'.
+ * Returns a date in hh:mm format. E.g. '01:02'.
  *
  * @param dt Specify a date object or default to the current date/time.
  * @param separator Defaults to ':'.
  */
-export function hhMmSs(dt = new Date(), separator = ":"): string {
+export function hhMm(dt = new Date(), separator = ":"): string {
   const hr = dt.getHours();
   const min = dt.getMinutes();
+
+  return (hr < 10 ? "0" + hr : hr) + separator + (min < 10 ? "0" + min : min);
+}
+
+/**
+ * Returns a date in hh:mm:ss format. E.g. '01:02:03'.
+ *
+ * @param dt Specify a date object or default to the current date/time.
+ * @param separator Defaults to ':'.
+ */
+export function hhMmSs(dt = new Date(), separator = ":"): string {
   const sec = dt.getSeconds();
 
-  return (
-    (hr < 10 ? "0" + hr : hr) +
-    separator +
-    (min < 10 ? "0" + min : min) +
-    separator +
-    (sec < 10 ? "0" + sec : sec)
-  );
+  return hhMm(dt, separator) + separator + (sec < 10 ? "0" + sec : sec);
 }
 
 /**

package/src/duration.ts

@@ -194,6 +194,13 @@ export function durationToMs(duration: Duration): number {
   return daysMs + hoursMs + minsMs + secsMs + msMs;
 }
 
+/**
+ * Convenience function to return a duration given an ms or Duration.
+ */
+export function durationOrMsToMs(duration: number | Duration): number {
+  return typeof duration === "number" ? duration : durationToMs(duration);
+}
+
 /**
  * Format a given Duration object into a string. If the object has no fields,
  * then returns an empty string.

package/src/kvStore.ts

@@ -11,6 +11,8 @@
  * Just use the `kvStore` global constant like the local storage.
  */
 
+import { Duration, durationOrMsToMs } from "./duration";
+
 // Updating the DB name will cause all old entries to be gone.
 const DEFAULT_DB_NAME = "KVStore";
 
@@ -32,7 +34,8 @@ export const GC_INTERVAL_MS = MILLIS_PER_DAY;
 type StoredObject<T> = {
   key: string;
   value: T;
-  expireMs: number;
+  storedMs: number;
+  expiryMs: number;
 };
 
 /**
@@ -48,10 +51,12 @@ function validateStoredObject<T>(
     !("key" in obj) ||
     typeof obj.key !== "string" ||
     !("value" in obj) ||
+    !("storedMs" in obj) ||
+    typeof obj.storedMs !== "number" ||
     obj.value === undefined ||
-    !("expireMs" in obj) ||
-    typeof obj.expireMs !== "number" ||
-    Date.now() >= obj.expireMs
+    !("expiryMs" in obj) ||
+    typeof obj.expiryMs !== "number" ||
+    Date.now() >= obj.expiryMs
   ) {
     return undefined;
   }
@@ -168,12 +173,14 @@ export class KVStore {
   public async set<T>(
     key: string,
     value: T,
-    expiryDeltaMs: number = this.defaultExpiryDeltaMs,
+    expiryDeltaMs: number | Duration = this.defaultExpiryDeltaMs,
   ): Promise<T> {
-    const obj = {
+    const nowMs = Date.now();
+    const obj: StoredObject<T> = {
       key,
       value,
-      expireMs: Date.now() + expiryDeltaMs,
+      storedMs: nowMs,
+      expiryMs: nowMs + durationOrMsToMs(expiryDeltaMs),
     };
 
     return await this.transact<T>(
@@ -210,7 +217,9 @@ export class KVStore {
     );
   }
 
-  public async get<T>(key: string): Promise<T | undefined> {
+  public async getStoredObject<T>(
+    key: string,
+  ): Promise<StoredObject<T> | undefined> {
     const stored = await this.transact<StoredObject<T> | undefined>(
       "readonly",
       (objectStore, resolve, reject) => {
@@ -236,7 +245,7 @@ export class KVStore {
         return undefined;
       }
 
-      return obj.value;
+      return obj;
     } catch (e) {
       console.error(`Invalid kv value: ${key}=${JSON.stringify(stored)}:`, e);
       await this.delete(key);
@@ -247,11 +256,17 @@ export class KVStore {
     }
   }
 
+  public async get<T>(key: string): Promise<T | undefined> {
+    const obj = await this.getStoredObject<T>(key);
+
+    return obj?.value;
+  }
+
   public async forEach(
     callback: (
       key: string,
       value: unknown,
-      expireMs: number,
+      expiryMs: number,
     ) => void | Promise<void>,
   ): Promise<void> {
     await this.transact<void>("readonly", (objectStore, resolve, reject) => {
@@ -266,7 +281,7 @@ export class KVStore {
           if (cursor.key) {
             const obj = validateStoredObject(cursor.value);
             if (obj) {
-              await callback(String(cursor.key), obj.value, obj.expireMs);
+              await callback(String(cursor.key), obj.value, obj.expiryMs);
             } else {
               await callback(String(cursor.key), undefined, 0);
             }
@@ -300,8 +315,8 @@ export class KVStore {
   /** Mainly for debugging dumps. */
   public async asMap(): Promise<Map<string, unknown>> {
     const map = new Map<string, unknown>();
-    await this.forEach((key, value, expireMs) => {
-      map.set(key, { value, expireMs });
+    await this.forEach((key, value, expiryMs) => {
+      map.set(key, { value, expiryMs });
     });
     return map;
   }
@@ -345,8 +360,8 @@ export class KVStore {
 
     const keysToDelete: string[] = [];
     await this.forEach(
-      async (key: string, value: unknown, expireMs: number) => {
-        if (value === undefined || Date.now() >= expireMs) {
+      async (key: string, value: unknown, expiryMs: number) => {
+        if (value === undefined || Date.now() >= expiryMs) {
           keysToDelete.push(key);
         }
       },
@@ -391,7 +406,16 @@ class KvStoreItem<T> {
     public readonly store = kvStore,
   ) {}
 
-  public async get(): Promise<Awaited<T> | undefined> {
+  /**
+   * Example usage:
+   *
+   *   const { value, storedMs, expiryMs } = await myKvItem.getStoredObject();
+   */
+  public async getStoredObject(): Promise<StoredObject<T> | undefined> {
+    return await this.store.getStoredObject(this.key);
+  }
+
+  public async get(): Promise<T | undefined> {
     return await this.store.get(this.key);
   }
 
@@ -412,7 +436,9 @@ class KvStoreItem<T> {
  */
 export function kvStoreItem<T>(
   key: string,
-  defaultExpiryDeltaMs: number,
+  defaultExpiration: number | Duration,
 ): KvStoreItem<T> {
+  const defaultExpiryDeltaMs = durationOrMsToMs(defaultExpiration);
+
   return new KvStoreItem<T>(key, defaultExpiryDeltaMs);
 }

package/src/localStorageCache.ts

@@ -1,6 +1,6 @@
-import { Duration, durationToMs } from "./duration";
+import { Duration, durationOrMsToMs } from "./duration";
 
-export type StoredItem<T> = { value: T; expireMs: number };
+export type StoredItem<T> = { value: T; storedMs: number; expiryMs: number };
 
 /**
  * Simple local storage cache with support for auto-expiration.
@@ -27,8 +27,7 @@ export function storeItem<T>(
   logError = true,
   defaultValue?: T,
 ) {
-  const expireDeltaMs =
-    typeof expires === "number" ? expires : durationToMs(expires);
+  const expireDeltaMs = durationOrMsToMs(expires);
 
   return new CacheItem<T>(key, expireDeltaMs, logError, defaultValue);
 }
@@ -47,22 +46,31 @@ class CacheItem<T> {
   /**
    * Set the value of this item with auto-expiration.
    */
-  public set(value: T): void {
-    const expireMs = Date.now() + this.expireDeltaMs;
-    const toStore: StoredItem<T> = { value, expireMs };
+  public set(
+    value: T,
+    expiryDelta: number | Duration = this.expireDeltaMs,
+  ): void {
+    const nowMs = Date.now();
+    const toStore: StoredItem<T> = {
+      value,
+      storedMs: nowMs,
+      expiryMs: nowMs + durationOrMsToMs(expiryDelta),
+    };
     const valueStr = JSON.stringify(toStore);
 
     globalThis.localStorage.setItem(this.key, valueStr);
   }
 
   /**
-   * Get the value of this item, or undefined if value is not set or expired.
+   * Example usage:
+   *
+   *   const { value, storedMs, expiryMs } = await myItem.getStoredItem();
    */
-  public get(): T | undefined {
+  public getStoredItem(): StoredItem<T> | undefined {
     const jsonStr = globalThis.localStorage.getItem(this.key);
 
     if (!jsonStr) {
-      return this.defaultValue;
+      return undefined;
     }
 
     try {
@@ -72,15 +80,17 @@ class CacheItem<T> {
         !obj ||
         typeof obj !== "object" ||
         !("value" in obj) ||
-        !("expireMs" in obj) ||
-        typeof obj.expireMs !== "number" ||
-        Date.now() >= obj.expireMs
+        !("storedMs" in obj) ||
+        typeof obj.storedMs !== "number" ||
+        !("expiryMs" in obj) ||
+        typeof obj.expiryMs !== "number" ||
+        Date.now() >= obj.expiryMs
       ) {
         this.remove();
-        return this.defaultValue;
+        return undefined;
       }
 
-      return obj.value;
+      return obj;
     } catch (e) {
       if (this.logError) {
         console.error(
@@ -89,10 +99,19 @@ class CacheItem<T> {
         );
       }
       this.remove();
-      return this.defaultValue;
+      return undefined;
     }
   }
 
+  /**
+   * Get the value of this item, or undefined if value is not set or expired.
+   */
+  public get(): T | undefined {
+    const stored = this.getStoredItem();
+
+    return stored !== undefined ? stored.value : this.defaultValue;
+  }
+
   /**
    * Remove the value of this item.
    */