@choksheak/ts-utils 0.1.8 → 0.2.0

package/src/duration.ts

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

package/src/kvStore.ts

@@ -168,12 +168,12 @@ export class KVStore {
   public async set<T>(
     key: string,
     value: T,
-    expireDeltaMs: number = this.defaultExpiryDeltaMs,
+    expiryDeltaMs: number = this.defaultExpiryDeltaMs,
   ): Promise<T> {
     const obj = {
       key,
       value,
-      expireMs: Date.now() + expireDeltaMs,
+      expireMs: Date.now() + expiryDeltaMs,
     };
 
     return await this.transact<T>(
@@ -380,3 +380,39 @@ export const kvStore = new KVStore(
   DEFAULT_DB_VERSION,
   DEFAULT_EXPIRY_DELTA_MS,
 );
+
+/**
+ * Class to represent one key in the store with a default expiration.
+ */
+class KvStoreItem<T> {
+  public constructor(
+    public readonly key: string,
+    public readonly defaultExpiryDeltaMs: number,
+    public readonly store = kvStore,
+  ) {}
+
+  public async get(): Promise<Awaited<T> | undefined> {
+    return await this.store.get(this.key);
+  }
+
+  public async set(
+    value: T,
+    expiryDeltaMs: number = this.defaultExpiryDeltaMs,
+  ): Promise<void> {
+    await this.store.set(this.key, value, expiryDeltaMs);
+  }
+
+  public async delete(): Promise<void> {
+    await this.store.delete(this.key);
+  }
+}
+
+/**
+ * Create a KV store item with a key and a default expiration.
+ */
+export function kvStoreItem<T>(
+  key: string,
+  defaultExpiryDeltaMs: number,
+): KvStoreItem<T> {
+  return new KvStoreItem<T>(key, defaultExpiryDeltaMs);
+}

package/src/localStorageCache.ts

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

package/src/nonEmpty.ts

@@ -3,6 +3,9 @@ import { isEmpty } from "./isEmpty";
 /**
  * Type asserts that `t` is truthy.
  * Throws an error if `t` is null or undefined.
+ *
+ * @param varName The variable name to include in the error to throw when t is
+ *   empty. Defaults to 'value'.
  */
 export function nonEmpty<T>(
   t: T | null | undefined | "" | 0 | -0 | 0n | false | typeof NaN,

package/src/nonNil.ts

@@ -1,6 +1,9 @@
 /**
  * Type asserts that `t` is neither null nor undefined.
  * Throws an error if `t` is null or undefined.
+ *
+ * @param varName The variable name to include in the error to throw when t is
+ *   nil. Defaults to 'value'.
  */
 export function nonNil<T>(t: T | null | undefined, varName = "value"): T {
   if (t === null || t === undefined) {

package/src/safeParseInt.ts

@@ -1,5 +1,8 @@
 /**
  * Returns 0 if the string is not a valid number.
+ *
+ * @param logError Log a console error if the given string is not a valid
+ *   number. Defaults to false (don't log anything).
  */
 export function safeParseInt(s: string, logError = false): number {
   const i = Number(s);

package/src/sleep.ts

@@ -1,3 +1,7 @@
+/**
+ * Sleep for a given number of milliseconds. Note that this method is async,
+ * so please remember to call it with await, like `await sleep(1000);`.
+ */
 export function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/src/timeConstants.ts

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

package/timeConstants.d.ts

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

package/timeConstants.js

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

package/timeConstants.js.map

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