@choksheak/ts-utils 0.2.0 → 0.2.2

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\n/** A shortened duration string useful for logging timings. */\nexport function elapsed(ms: number): string {\n  // Use long format for 1 minute or over.\n  if (ms > MS_PER_MINUTE) {\n    return readableDuration(ms);\n  }\n\n  // Use seconds format for over 100ms.\n  if (ms > 100) {\n    return `${(ms / 1000).toFixed(3)}s`;\n  }\n\n  // Use milliseconds format.\n  return ms + \"ms\";\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.2",
   "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.
@@ -235,3 +242,19 @@ export function readableDuration(
 
   return formatDuration(duration, options?.style);
 }
+
+/** A shortened duration string useful for logging timings. */
+export function elapsed(ms: number): string {
+  // Use long format for 1 minute or over.
+  if (ms > MS_PER_MINUTE) {
+    return readableDuration(ms);
+  }
+
+  // Use seconds format for over 100ms.
+  if (ms > 100) {
+    return `${(ms / 1000).toFixed(3)}s`;
+  }
+
+  // Use milliseconds format.
+  return ms + "ms";
+}

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.
    */

package/src/timer.ts

@@ -0,0 +1,33 @@
+import { elapsed } from "./duration";
+
+export class Timer {
+  public startMs: number;
+  public endMs = 0;
+
+  public constructor() {
+    this.startMs = Date.now();
+  }
+
+  public stop(): void {
+    this.endMs = Date.now();
+  }
+
+  public restart(): void {
+    this.endMs = 0;
+    this.startMs = Date.now();
+  }
+
+  public elapsedMs(): number {
+    const stopMs = this.endMs || Date.now();
+    return stopMs - this.startMs;
+  }
+
+  public toString(): string {
+    return elapsed(this.elapsedMs());
+  }
+}
+
+/** Shorthand for `new Timer()` to make this easier to use. */
+export function timer(): Timer {
+  return new Timer();
+}

package/timer.d.ts

@@ -0,0 +1,11 @@
+export declare class Timer {
+    startMs: number;
+    endMs: number;
+    constructor();
+    stop(): void;
+    restart(): void;
+    elapsedMs(): number;
+    toString(): string;
+}
+/** Shorthand for `new Timer()` to make this easier to use. */
+export declare function timer(): Timer;

package/timer.js

@@ -0,0 +1,189 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/timer.ts
+var timer_exports = {};
+__export(timer_exports, {
+  Timer: () => Timer,
+  timer: () => timer
+});
+module.exports = __toCommonJS(timer_exports);
+
+// src/timeConstants.ts
+var MS_PER_SECOND = 1e3;
+var MS_PER_MINUTE = 6e4;
+var SECONDS_PER_MINUTE = 60;
+var MINUTES_PER_HOUR = 60;
+var HOURS_PER_DAY = 24;
+
+// src/duration.ts
+var DURATION_TYPE_SEQUENCE = [
+  "days",
+  "hours",
+  "minutes",
+  "seconds",
+  "milliseconds"
+];
+var DURATION_STYLE_SUFFIX_MAP = {
+  days: {
+    short: "day",
+    shorts: "days",
+    long: "day",
+    longs: "days",
+    narrow: "d"
+  },
+  hours: {
+    short: "hr",
+    shorts: "hrs",
+    long: "hour",
+    longs: "hours",
+    narrow: "h"
+  },
+  minutes: {
+    short: "min",
+    shorts: "mins",
+    long: "minute",
+    longs: "minutes",
+    narrow: "m"
+  },
+  seconds: {
+    short: "sec",
+    shorts: "secs",
+    long: "second",
+    longs: "seconds",
+    narrow: "s"
+  },
+  milliseconds: {
+    short: "ms",
+    shorts: "ms",
+    long: "millisecond",
+    longs: "milliseconds",
+    narrow: "ms"
+  }
+};
+function getDurationStyleForPlural(style) {
+  return style == "short" ? "shorts" : style === "long" ? "longs" : style;
+}
+function getValueAndUnitSeparator(style) {
+  return style === "narrow" ? "" : " ";
+}
+function getDurationTypeSeparator(style) {
+  return style === "narrow" ? " " : ", ";
+}
+function msToDuration(ms, durationTypeForZero) {
+  if (ms === 0) {
+    durationTypeForZero = durationTypeForZero != null ? durationTypeForZero : "milliseconds";
+    return { [durationTypeForZero]: 0 };
+  }
+  const duration = {};
+  for (let i = 0; i < 1; i++) {
+    let seconds = Math.floor(ms / MS_PER_SECOND);
+    const millis = ms - seconds * MS_PER_SECOND;
+    if (millis > 0) {
+      duration["milliseconds"] = millis;
+    }
+    if (seconds === 0) {
+      break;
+    }
+    let minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
+    seconds -= minutes * SECONDS_PER_MINUTE;
+    if (seconds > 0) {
+      duration["seconds"] = seconds;
+    }
+    if (minutes === 0) {
+      break;
+    }
+    let hours = Math.floor(minutes / MINUTES_PER_HOUR);
+    minutes -= hours * MINUTES_PER_HOUR;
+    if (minutes > 0) {
+      duration["minutes"] = minutes;
+    }
+    if (hours === 0) {
+      break;
+    }
+    const days = Math.floor(hours / HOURS_PER_DAY);
+    hours -= days * HOURS_PER_DAY;
+    if (hours > 0) {
+      duration["hours"] = hours;
+    }
+    if (days > 0) {
+      duration["days"] = days;
+    }
+  }
+  return duration;
+}
+function formatDuration(duration, style) {
+  style = style != null ? style : "short";
+  const stylePlural = getDurationStyleForPlural(style);
+  const space = getValueAndUnitSeparator(style);
+  const a = [];
+  for (const unit of DURATION_TYPE_SEQUENCE) {
+    const value = duration[unit];
+    if (value === void 0) continue;
+    const suffixMap = DURATION_STYLE_SUFFIX_MAP[unit];
+    const suffix = value === 1 ? suffixMap[style] : suffixMap[stylePlural];
+    a.push(value + space + suffix);
+  }
+  const separator = getDurationTypeSeparator(style);
+  return a.join(separator);
+}
+function readableDuration(ms, options) {
+  const duration = msToDuration(ms, options == null ? void 0 : options.durationTypeForZero);
+  return formatDuration(duration, options == null ? void 0 : options.style);
+}
+function elapsed(ms) {
+  if (ms > MS_PER_MINUTE) {
+    return readableDuration(ms);
+  }
+  if (ms > 100) {
+    return `${(ms / 1e3).toFixed(3)}s`;
+  }
+  return ms + "ms";
+}
+
+// src/timer.ts
+var Timer = class {
+  constructor() {
+    this.endMs = 0;
+    this.startMs = Date.now();
+  }
+  stop() {
+    this.endMs = Date.now();
+  }
+  restart() {
+    this.endMs = 0;
+    this.startMs = Date.now();
+  }
+  elapsedMs() {
+    const stopMs = this.endMs || Date.now();
+    return stopMs - this.startMs;
+  }
+  toString() {
+    return elapsed(this.elapsedMs());
+  }
+};
+function timer() {
+  return new Timer();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Timer,
+  timer
+});
+//# sourceMappingURL=timer.js.map