@zelgadis87/utils-core 4.3.5 → 4.4.1

package/esbuild/index.mjs

@@ -162,7 +162,329 @@ var require_lib = __commonJS({
   }
 });
 
-// src/types/arrays.ts
+// src/async/Deferred.ts
+var DeferredCanceledError = class extends Error {
+  constructor() {
+    super("Execution canceled");
+  }
+};
+var Deferred = class {
+  _pending;
+  _internals;
+  get pending() {
+    return this._pending;
+  }
+  /** @deprecated: Use resolve, then and catch directly; use asPromise to return a promise type. */
+  get promise() {
+    return this._internals.promise;
+  }
+  constructor() {
+    this._pending = true;
+    this._internals = this.createInternals();
+  }
+  resolve(val) {
+    if (!this._pending)
+      throw new Error("Illegal state exception");
+    this.resolveIfPending(val);
+  }
+  reject(reason) {
+    if (!this._pending)
+      throw new Error("Illegal state exception");
+    this.rejectIfPending(reason);
+  }
+  cancel() {
+    if (!this._pending)
+      throw new Error("Illegal state exception");
+    this.cancelIfPending();
+  }
+  resolveIfPending(val) {
+    if (!this._pending)
+      return;
+    this._pending = false;
+    this._internals.resolve(val);
+  }
+  rejectIfPending(reason) {
+    if (!this._pending)
+      return;
+    this._pending = false;
+    this._internals.reject(reason);
+  }
+  cancelIfPending() {
+    if (!this._pending)
+      return;
+    this.reject(new DeferredCanceledError());
+  }
+  then(onFulfilled, onRejected) {
+    return this._internals.promise.then(onFulfilled, onRejected);
+  }
+  catch(onRejected) {
+    return this._internals.promise.catch(onRejected);
+  }
+  finally(onfinally) {
+    return this._internals.promise.finally(onfinally);
+  }
+  asPromise() {
+    return this;
+  }
+  asCancelablePromise() {
+    return this;
+  }
+  createInternals() {
+    let resolveSelf, rejectSelf;
+    const promise = new Promise((resolve, reject) => {
+      resolveSelf = resolve;
+      rejectSelf = reject;
+    });
+    return {
+      promise,
+      resolve: resolveSelf,
+      reject: rejectSelf
+    };
+  }
+  get [Symbol.toStringTag]() {
+    return "[object Deferred]";
+  }
+};
+var Deferred_default = Deferred;
+
+// src/async/RateThrottler.ts
+var RateThrottler = class {
+  constructor(_frequency) {
+    this._frequency = _frequency;
+    const initialOffset = this.cooldown.divideBy(_frequency.times);
+    this._availableSlots = new Array(_frequency.times).fill(0).map((_, i) => TimeInstant.now().addMs(i * initialOffset.ms));
+    this._waitingRequests = [];
+  }
+  _availableSlots;
+  _waitingRequests;
+  get cooldown() {
+    return this._frequency.period;
+  }
+  async execute(fn) {
+    const wrappedFn = async () => {
+      const slot = this._availableSlots.shift();
+      try {
+        return slot.promise().then(() => fn());
+      } finally {
+        this._availableSlots.push(TimeInstant.now().addDuration(this.cooldown));
+        if (this._waitingRequests.length > 0) this._waitingRequests.shift().resolve();
+      }
+    };
+    if (this._availableSlots.length > 0) {
+      return wrappedFn();
+    } else {
+      const waitingRequest = new Deferred_default();
+      this._waitingRequests.push(waitingRequest);
+      return waitingRequest.then(() => wrappedFn());
+    }
+  }
+};
+function throttle(fn, frequence) {
+  const semaphore = new RateThrottler(frequence);
+  return (...t) => {
+    return semaphore.execute(async () => fn(...t));
+  };
+}
+
+// src/async/Semaphore.ts
+var Semaphore = class {
+  constructor(_availableSlots = 1) {
+    this._availableSlots = _availableSlots;
+    this._queuedRequests = [];
+  }
+  _queuedRequests;
+  _inProgress = 0;
+  async _awaitSlot() {
+    if (this._availableSlots > 0) {
+      this._availableSlots -= 1;
+      this._inProgress += 1;
+      return void 0;
+    } else {
+      const deferred = new Deferred_default();
+      this._queuedRequests.push(deferred);
+      return deferred.asPromise();
+    }
+  }
+  _releaseSlot() {
+    const waitingSlotToResolve = this._queuedRequests.shift();
+    if (waitingSlotToResolve) {
+      waitingSlotToResolve.resolve();
+    } else {
+      this._availableSlots += 1;
+      this._inProgress -= 1;
+    }
+  }
+  async execute(fn, cooldown = TimeDuration.ZERO) {
+    return this._awaitSlot().then(() => fn()).finally(() => {
+      void cooldown.promise().then(() => this._releaseSlot());
+    });
+  }
+  get availableSlots() {
+    return this._availableSlots;
+  }
+  get queueSize() {
+    return this._queuedRequests.length;
+  }
+  get inProgressSize() {
+    return this._inProgress;
+  }
+};
+
+// src/utils/arrays/groupBy.ts
+function groupByString(arr, field) {
+  return groupByStringWith(arr, (t) => t[field]);
+}
+function groupByNumber(arr, field) {
+  return groupByNumberWith(arr, (t) => t[field]);
+}
+function groupByBoolean(arr, field) {
+  return groupByBooleanWith(arr, (t) => t[field]);
+}
+function groupBySymbol(arr, field) {
+  return groupBySymbolWith(arr, (t) => t[field]);
+}
+function groupByStringWith(arr, getter) {
+  return doGroupByWith(arr, getter);
+}
+function groupByNumberWith(arr, getter) {
+  return doGroupByWith(arr, getter);
+}
+function groupByBooleanWith(arr, getter) {
+  return doGroupByWith(arr, (item) => getter(item) ? "true" : "false");
+}
+function groupBySymbolWith(arr, getter) {
+  return doGroupByWith(arr, getter);
+}
+function doGroupByWith(arr, getter) {
+  return arr.reduce((dict, cur) => {
+    const key = getter(cur);
+    if (key !== null && key !== void 0) {
+      const arr2 = dict[key] ?? [];
+      arr2.push(cur);
+      dict[key] = arr2;
+    }
+    return dict;
+  }, {});
+}
+
+// src/utils/arrays/indexBy.ts
+function indexByString(arr, field) {
+  return indexByStringWith(arr, (t) => t[field]);
+}
+function indexByNumber(arr, field) {
+  return indexByNumberWith(arr, (t) => t[field]);
+}
+function indexBySymbol(arr, field) {
+  return indexBySymbolWith(arr, (t) => t[field]);
+}
+function indexByStringWith(arr, getter) {
+  return doIndexByWith(arr, getter);
+}
+function indexByNumberWith(arr, getter) {
+  return doIndexByWith(arr, getter);
+}
+function indexBySymbolWith(arr, getter) {
+  return doIndexByWith(arr, getter);
+}
+function doIndexByWith(arr, getter) {
+  return arr.reduce((dict, cur) => {
+    const key = getter(cur);
+    if (key !== null && key !== void 0)
+      dict[key] = cur;
+    return dict;
+  }, {});
+}
+
+// src/utils/arrays/statistics.ts
+function average(arr) {
+  const f = 1 / arr.length;
+  return arr.reduce((tot, cur) => tot + cur * f, 0);
+}
+function sum(arr) {
+  return arr.reduce((tot, cur) => tot + cur, 0);
+}
+function sumBy(arr, getter) {
+  return sum(arr.map(getter));
+}
+function min(arr) {
+  if (arr.length === 0) throw new Error("Cannot calculate value on empty array");
+  return arr.reduce((min2, cur) => cur < min2 ? cur : min2);
+}
+function minBy(arr, getter) {
+  return min(arr.map(getter));
+}
+function max(arr) {
+  if (arr.length === 0) throw new Error("Cannot calculate value on empty array");
+  return arr.reduce((max2, cur) => cur > max2 ? cur : max2);
+}
+function maxBy(arr, getter) {
+  return max(arr.map(getter));
+}
+
+// src/utils/functions/bindThis.ts
+function bindThis(fn, _this) {
+  return fn.bind(_this);
+}
+
+// src/utils/functions/constant.ts
+function constant(v) {
+  return () => v;
+}
+function identity(t) {
+  return t;
+}
+var constantNull = constant(null);
+var constantTrue = constant(true);
+var constantFalse = constant(false);
+var constantZero = constant(0);
+var constantOne = constant(1);
+
+// src/utils/functions/iff.ts
+function iff(firstPredicate, valueIfTrue) {
+  if (firstPredicate === true || firstPredicate instanceof Function && firstPredicate() === true) {
+    const ret = {
+      elseIf: () => ret,
+      otherwise: () => valueIfTrue
+    };
+    return ret;
+  } else {
+    const ret = {
+      elseIf: (elseIf, valueIfElseIfTrue) => iff(elseIf, valueIfElseIfTrue),
+      otherwise: (valueIfElse) => valueIfElse
+    };
+    return ret;
+  }
+}
+
+// src/utils/functions.ts
+function isFunction(t) {
+  return typeof t === "function";
+}
+function noop() {
+}
+
+// src/utils/arrays/uniqBy.ts
+function uniq(arr) {
+  return uniqBy(arr, identity);
+}
+function uniqBy(arr, getter) {
+  return arr.reduce((dict, cur) => {
+    const key = getter(cur);
+    if (dict.keys.includes(key)) {
+      return dict;
+    } else {
+      return {
+        keys: [...dict.keys, key],
+        values: [...dict.values, cur]
+      };
+    }
+  }, { keys: [], values: [] }).values;
+}
+function uniqByKey(arr, key) {
+  return uniqBy(arr, (item) => item[key]);
+}
+
+// src/utils/arrays.ts
 function ensureArray(t) {
   return t instanceof Array ? t : [t];
 }
@@ -207,11 +529,15 @@ function extendArrayWith(arr, propsFn) {
 function reverse(arr) {
   return [...arr].reverse();
 }
-function head(arr, defaultValue = null) {
+function first(arr, defaultValue = null) {
   return arr.length ? arr[0] : defaultValue;
 }
 function last(arr, defaultValue = null) {
-  return head(reverse(arr), defaultValue);
+  return arr.length ? arr[arr.length - 1] : defaultValue;
+}
+var head = first;
+function tail(arr) {
+  return arr.length ? arr.slice(1) : [];
 }
 function sortedArray(arr, sortFn) {
   return [...arr].sort(sortFn);
@@ -226,7 +552,7 @@ function flatMapTruthys(arr, mapper) {
   return arr.flatMap(mapper).filter((value) => value !== void 0);
 }
 
-// src/types/booleans.ts
+// src/utils/booleans.ts
 function isTrue(x) {
   return x === true;
 }
@@ -234,7 +560,19 @@ function isFalse(x) {
   return x === false;
 }
 
-// src/types/errors.ts
+// src/utils/errors/withTryCatch.ts
+function withTryCatch(fn) {
+  try {
+    return [fn(), void 0];
+  } catch (e) {
+    return [void 0, asError(e)];
+  }
+}
+async function withTryCatchAsync(fn) {
+  return fn().then((value) => [value, void 0], (e) => [void 0, asError(e)]);
+}
+
+// src/utils/errors.ts
 function asError(e) {
   if (e === void 0 || e === null)
     return new Error("Void message");
@@ -250,22 +588,39 @@ function isError(e) {
   return e instanceof Error;
 }
 
-// src/types/functions.ts
-function isFunction(t) {
-  return typeof t === "function";
-}
-
-// src/types/json.ts
+// src/utils/json.ts
 function tryToParseJson(jsonContent) {
-  try {
-    const data = JSON.parse(jsonContent);
-    return [data, null];
-  } catch (err) {
-    return [null, asError(err)];
+  return withTryCatch(() => JSON.parse(jsonContent));
+}
+function jsonCloneDeep(a) {
+  if (null === a || "object" !== typeof a) return a;
+  if (a instanceof Date) {
+    return new Date(a.getTime());
+  } else if (a instanceof Array) {
+    const copy = [];
+    for (let i = 0, len = a.length; i < len; i++) {
+      copy[i] = jsonCloneDeep(a[i]);
+    }
+    return copy;
+  } else if (a instanceof Object) {
+    const copy = {};
+    for (let attr in a) {
+      if (a.hasOwnProperty(attr))
+        copy[attr] = jsonCloneDeep(a[attr]);
+    }
+    return copy;
   }
+  throw new Error("Unable to copy obj! Its type isn't supported.");
 }
+function omitFromJsonObject(o, ...keys) {
+  return keys.reduce((obj, key) => {
+    delete obj[key];
+    return obj;
+  }, { ...o });
+}
+var omit = omitFromJsonObject;
 
-// src/types/nulls.ts
+// src/utils/nulls.ts
 function ensureDefined(v, name = "value") {
   if (isDefined(v))
     return v;
@@ -291,7 +646,26 @@ function ifNullOrUndefined(source, callback) {
     callback();
 }
 
-// src/types/numbers.ts
+// src/utils/numbers/round.ts
+var roundModes = {
+  "toNearest": Math.round,
+  "toLower": Math.floor,
+  "toUpper": Math.ceil,
+  "towardsZero": (n) => n > 0 ? Math.floor(n) : Math.ceil(n),
+  "awayFromZero": (n) => n > 0 ? Math.ceil(n) : Math.floor(n)
+};
+function round(n, precision = 0, mode = "toNearest") {
+  const base = 10;
+  const power = Math.pow(base, precision);
+  return roundModes[mode](n * power) / power;
+}
+var roundToNearest = (n, precision = 0) => round(n, precision, "toNearest");
+var roundToLower = (n, precision = 0) => round(n, precision, "toLower");
+var roundToUpper = (n, precision = 0) => round(n, precision, "toUpper");
+var roundTowardsZero = (n, precision = 0) => round(n, precision, "towardsZero");
+var roundAwayFromZero = (n, precision = 0) => round(n, precision, "awayFromZero");
+
+// src/utils/numbers.ts
 function ensurePositiveNumber(v, name = "value") {
   if (v !== void 0 && v !== null && v > 0)
     return v;
@@ -336,8 +710,19 @@ function isNegativeNumber(v) {
 function isZero(v) {
   return v === 0;
 }
+function clamp(n, min2, max2) {
+  if (min2 === null || max2 === null || n === null || isNaN(min2) || isNaN(max2) || isNaN(n) || min2 > max2)
+    throw new Error();
+  if (n > max2) {
+    return max2;
+  } else if (n < min2) {
+    return min2;
+  } else {
+    return n;
+  }
+}
 
-// src/types/promises.ts
+// src/utils/promises.ts
 function asPromise(promisable) {
   return Promise.resolve(promisable);
 }
@@ -355,61 +740,37 @@ function delayPromise(duration) {
   return (result) => duration.promise().then(() => result);
 }
 
-// src/types/records.ts
-function dictToList(obj) {
-  return Object.keys(obj).map((key) => obj[key]);
+// src/utils/random.ts
+function randomInterval(min2, max2) {
+  return Math.floor(Math.random() * (max2 - min2 + 1) + min2);
 }
-function pick(o, keys) {
-  return keys.reduce((obj, key) => {
-    obj[key] = o[key];
-    return obj;
-  }, {});
+function randomPercentage(min2, max2) {
+  return randomInterval(min2, max2) / 100;
 }
 
-// src/types/strings.ts
-function hashCode(str) {
-  let hash = 0;
-  for (let i = 0; i < str.length; ++i)
-    hash = Math.imul(31, hash) + str.charCodeAt(i);
-  return hash | 0;
-}
-function repeat(char, times) {
-  return times > 0 ? range(0, times - 1).map((_) => char).join("") : "";
-}
-function capitalizeWord(word) {
-  return word[0].toUpperCase() + word.substring(1).toLowerCase();
-}
-function splitWords(text, regEx = /\s+/) {
-  return text.split(regEx).filter((t) => t.length > 0);
-}
-function stringToNumber(s) {
-  if (isNullOrUndefined(s))
-    return null;
-  return Number(s);
-}
-function pad(str, n, char, where = "left") {
-  const length = ensureDefined(str).length;
-  if (length >= ensureDefined(n)) return str;
-  if (ensureDefined(char).length !== 1)
-    throw new Error("Illegal pad character");
-  const padding = repeat(char, n - length);
-  return (where === "left" ? padding : "") + str + (where === "right" ? padding : "");
+// src/utils/records/entries.ts
+function dictToEntries(obj) {
+  return Object.entries(obj);
 }
-function padLeft(str, n, char) {
-  return pad(str, n, char, "left");
+function entriesToDict(entries) {
+  return Object.fromEntries(entries);
 }
-function padRight(str, n, char) {
-  return pad(str, n, char, "right");
+function mapEntries(dict, mapper) {
+  return entriesToDict(dictToEntries(dict).map((entry) => mapper(entry)));
 }
-function ellipsis(str, maxLength, padChar, padWhere = "left") {
-  if (maxLength < 4)
-    throw new Error("Invalid argument maxLength");
-  if (str.length <= maxLength) {
-    return pad(str, maxLength, padChar, padWhere);
-  } else {
-    return str.substring(0, maxLength - 3) + "...";
-  }
+
+// src/utils/records.ts
+function dictToList(obj) {
+  return Object.keys(obj).map((key) => obj[key]);
+}
+function pick(o, keys) {
+  return keys.reduce((obj, key) => {
+    obj[key] = o[key];
+    return obj;
+  }, {});
 }
+
+// src/utils/strings/StringParts.ts
 var StringParts = class _StringParts {
   _parts;
   constructor(...parts) {
@@ -432,8 +793,8 @@ var StringParts = class _StringParts {
     return this._parts;
   }
   get tail() {
-    const [_first, ...tail] = this.parts;
-    return tail;
+    const [_first, ...tail2] = this.parts;
+    return tail2;
   }
   get first() {
     return this._parts[0] ?? null;
@@ -494,7 +855,70 @@ var StringParts = class _StringParts {
   };
 };
 
-// src/Lazy.ts
+// src/utils/strings.ts
+function hashCode(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; ++i)
+    hash = Math.imul(31, hash) + str.charCodeAt(i);
+  return hash | 0;
+}
+function repeat(char, times) {
+  return times > 0 ? range(0, times - 1).map((_) => char).join("") : "";
+}
+function capitalizeWord(word) {
+  return word[0].toUpperCase() + word.substring(1).toLowerCase();
+}
+function splitWords(text, regEx = /\s+/) {
+  return text.split(regEx).filter((t) => t.length > 0);
+}
+function stringToNumber(s) {
+  if (isNullOrUndefined(s))
+    return null;
+  return Number(s);
+}
+function pad(str, n, char, where = "left") {
+  const length = ensureDefined(str).length;
+  if (length >= ensureDefined(n)) return str;
+  if (ensureDefined(char).length !== 1)
+    throw new Error("Illegal pad character");
+  const padding = repeat(char, n - length);
+  return (where === "left" ? padding : "") + str + (where === "right" ? padding : "");
+}
+function padLeft(str, n, char) {
+  return pad(str, n, char, "left");
+}
+function padRight(str, n, char) {
+  return pad(str, n, char, "right");
+}
+function ellipsis(str, maxLength, padChar, padWhere = "left") {
+  if (maxLength < 4)
+    throw new Error("Invalid argument maxLength");
+  if (str.length <= maxLength) {
+    return pad(str, maxLength, padChar, padWhere);
+  } else {
+    return str.substring(0, maxLength - 3) + "...";
+  }
+}
+function pluralize(n, singular, plural) {
+  if (!singular || !singular.length)
+    throw new Error();
+  if (n === 1)
+    return singular;
+  plural = plural ?? singular + "s";
+  const firstUppercase = singular.charAt(0) === singular.charAt(0).toUpperCase();
+  if (firstUppercase) {
+    const PLURAL = plural.toUpperCase();
+    const isAllUppercase = plural === PLURAL;
+    plural = isAllUppercase ? PLURAL : plural.charAt(0).toUpperCase() + plural.slice(1).toLowerCase();
+  }
+  return plural;
+}
+function wrapWithString(str, delimiter) {
+  return delimiter + str + delimiter;
+}
+var wrap = wrapWithString;
+
+// src/lazy/Lazy.ts
 var Lazy = class _Lazy {
   _value = void 0;
   _initialized = false;
@@ -552,7 +976,7 @@ var Lazy = class _Lazy {
   }
 };
 
-// src/LazyAsync.ts
+// src/lazy/LazyAsync.ts
 var LazyAsync = class _LazyAsync {
   _promise = void 0;
   _pending = false;
@@ -755,101 +1179,6 @@ var TimeBase = class {
   }
 };
 
-// src/async/Deferred.ts
-var DeferredCanceledError = class extends Error {
-  constructor() {
-    super("Execution canceled");
-  }
-};
-var Deferred = class {
-  _pending;
-  _internals;
-  get pending() {
-    return this._pending;
-  }
-  /** @deprecated: Use resolve, then and catch directly; use asPromise to return a promise type. */
-  get promise() {
-    return this._internals.promise;
-  }
-  constructor() {
-    this._pending = true;
-    this._internals = this.createInternals();
-  }
-  resolve(val) {
-    if (!this._pending)
-      throw new Error("Illegal state exception");
-    this.resolveIfPending(val);
-  }
-  reject(reason) {
-    if (!this._pending)
-      throw new Error("Illegal state exception");
-    this.rejectIfPending(reason);
-  }
-  cancel() {
-    if (!this._pending)
-      throw new Error("Illegal state exception");
-    this.cancelIfPending();
-  }
-  resolveIfPending(val) {
-    if (!this._pending)
-      return;
-    this._pending = false;
-    this._internals.resolve(val);
-  }
-  rejectIfPending(reason) {
-    if (!this._pending)
-      return;
-    this._pending = false;
-    this._internals.reject(reason);
-  }
-  cancelIfPending() {
-    if (!this._pending)
-      return;
-    this.reject(new DeferredCanceledError());
-  }
-  then(onFulfilled, onRejected) {
-    return this._internals.promise.then(onFulfilled, onRejected);
-  }
-  catch(onRejected) {
-    return this._internals.promise.catch(onRejected);
-  }
-  finally(onfinally) {
-    return this._internals.promise.finally(onfinally);
-  }
-  asPromise() {
-    return this;
-  }
-  asCancelablePromise() {
-    return this;
-  }
-  createInternals() {
-    let resolveSelf, rejectSelf;
-    const promise = new Promise((resolve, reject) => {
-      resolveSelf = resolve;
-      rejectSelf = reject;
-    });
-    return {
-      promise,
-      resolve: resolveSelf,
-      reject: rejectSelf
-    };
-  }
-  get [Symbol.toStringTag]() {
-    return "[object Deferred]";
-  }
-};
-var Deferred_default = Deferred;
-
-// src/random/randomInterval.ts
-function randomInterval(min2, max2) {
-  return Math.floor(Math.random() * (max2 - min2 + 1) + min2);
-}
-
-// src/random/randomPercentage.ts
-function randomPercentage(min2, max2) {
-  return randomInterval(min2, max2) / 100;
-}
-
 // src/time/TimeDuration.ts
 var TimeDuration = class _TimeDuration extends TimeBase {
   constructor(value, unit) {
@@ -1514,10 +1843,6 @@ function isTimeInstant(x) {
 }
 var TimeInstant_default = TimeInstant;
 
-// src/utils/noop.ts
-function noop() {
-}
-
 // src/Logger.ts
 var LEVELS = ["log", "debug", "info", "warn", "error"];
 var timestamp = () => TimeInstant_default.now().asTimeString();
@@ -1649,115 +1974,25 @@ var Optional = class _Optional {
       throw new ErrorCannotInstantiatePresentOptionalWithEmptyValue();
     return new _Optional(t);
   }
-  static ofNullable(t) {
-    return new _Optional(t);
-  }
-};
-var ErrorGetEmptyOptional = class extends Error {
-  constructor() {
-    super("Cannot retrieve a value from an EmptyOptional.");
-  }
-};
-var ErrorSetEmptyOptional = class extends Error {
-  constructor() {
-    super("Cannot set a null or undefined value.");
-  }
-};
-var ErrorCannotInstantiatePresentOptionalWithEmptyValue = class extends Error {
-  constructor() {
-    super("Cannot initialize a PresentOptional with a null or undefined value.");
-  }
-};
-
-// src/async/RateThrottler.ts
-var RateThrottler = class {
-  constructor(_frequency) {
-    this._frequency = _frequency;
-    const initialOffset = this.cooldown.divideBy(_frequency.times);
-    this._availableSlots = new Array(_frequency.times).fill(0).map((_, i) => TimeInstant.now().addMs(i * initialOffset.ms));
-    this._waitingRequests = [];
-  }
-  _availableSlots;
-  _waitingRequests;
-  get cooldown() {
-    return this._frequency.period;
-  }
-  async execute(fn) {
-    const wrappedFn = async () => {
-      const slot = this._availableSlots.shift();
-      try {
-        return slot.promise().then(() => fn());
-      } finally {
-        this._availableSlots.push(TimeInstant.now().addDuration(this.cooldown));
-        if (this._waitingRequests.length > 0) this._waitingRequests.shift().resolve();
-      }
-    };
-    if (this._availableSlots.length > 0) {
-      return wrappedFn();
-    } else {
-      const waitingRequest = new Deferred_default();
-      this._waitingRequests.push(waitingRequest);
-      return waitingRequest.then(() => wrappedFn());
-    }
-  }
-};
-
-// src/async/Semaphore.ts
-var Semaphore = class {
-  constructor(_availableSlots = 1) {
-    this._availableSlots = _availableSlots;
-    this._queuedRequests = [];
-  }
-  _queuedRequests;
-  _inProgress = 0;
-  async _awaitSlot() {
-    if (this._availableSlots > 0) {
-      this._availableSlots -= 1;
-      this._inProgress += 1;
-      return void 0;
-    } else {
-      const deferred = new Deferred_default();
-      this._queuedRequests.push(deferred);
-      return deferred.asPromise();
-    }
-  }
-  _releaseSlot() {
-    const waitingSlotToResolve = this._queuedRequests.shift();
-    if (waitingSlotToResolve) {
-      waitingSlotToResolve.resolve();
-    } else {
-      this._availableSlots += 1;
-      this._inProgress -= 1;
-    }
-  }
-  async execute(fn, cooldown = TimeDuration.ZERO) {
-    return this._awaitSlot().then(() => fn()).finally(() => {
-      void cooldown.promise().then(() => this._releaseSlot());
-    });
-  }
-  get availableSlots() {
-    return this._availableSlots;
+  static ofNullable(t) {
+    return new _Optional(t);
   }
-  get queueSize() {
-    return this._queuedRequests.length;
+};
+var ErrorGetEmptyOptional = class extends Error {
+  constructor() {
+    super("Cannot retrieve a value from an EmptyOptional.");
   }
-  get inProgressSize() {
-    return this._inProgress;
+};
+var ErrorSetEmptyOptional = class extends Error {
+  constructor() {
+    super("Cannot set a null or undefined value.");
+  }
+};
+var ErrorCannotInstantiatePresentOptionalWithEmptyValue = class extends Error {
+  constructor() {
+    super("Cannot initialize a PresentOptional with a null or undefined value.");
   }
 };
-
-// src/utils/constant.ts
-function constant(v) {
-  return () => v;
-}
-function identity(t) {
-  return t;
-}
-var constantNull = constant(null);
-var constantTrue = constant(true);
-var constantFalse = constant(false);
-var constantZero = constant(0);
-var constantOne = constant(1);
 
 // src/sorting/ComparisonChain.ts
 var defaultCompareValueOptions = {
@@ -2095,7 +2330,7 @@ var top = (fns, arr, n) => {
 var bottom = (fns, arr, n) => {
   return sort(fns, arr).slice(-Math.max(0, n)).reverse();
 };
-var first = (fns, arr) => {
+var first2 = (fns, arr) => {
   return arr.length ? top(fns, arr, 1)[0] : null;
 };
 var last2 = (fns, arr) => {
@@ -2125,7 +2360,7 @@ function doCreateWithFunctions(fns) {
       return bottom(fns, arr, n);
     },
     first: (arr) => {
-      return first(fns, arr);
+      return first2(fns, arr);
     },
     last: (arr) => {
       return last2(fns, arr);
@@ -2207,264 +2442,6 @@ var TimeRange = class _TimeRange {
   }
 };
 
-// src/utils/bindThis.ts
-function bindThis(fn, _this) {
-  return fn.bind(_this);
-}
-
-// src/utils/entries.ts
-function dictToEntries(obj) {
-  return Object.entries(obj);
-}
-function entriesToDict(entries) {
-  return Object.fromEntries(entries);
-}
-function mapEntries(dict, mapper) {
-  return entriesToDict(dictToEntries(dict).map((entry) => mapper(entry)));
-}
-
-// src/utils/groupBy.ts
-function groupByString(arr, field) {
-  return groupByStringWith(arr, (t) => t[field]);
-}
-function groupByNumber(arr, field) {
-  return groupByNumberWith(arr, (t) => t[field]);
-}
-function groupByBoolean(arr, field) {
-  return groupByBooleanWith(arr, (t) => t[field]);
-}
-function groupBySymbol(arr, field) {
-  return groupBySymbolWith(arr, (t) => t[field]);
-}
-function groupByStringWith(arr, getter) {
-  return doGroupByWith(arr, getter);
-}
-function groupByNumberWith(arr, getter) {
-  return doGroupByWith(arr, getter);
-}
-function groupByBooleanWith(arr, getter) {
-  return doGroupByWith(arr, (item) => getter(item) ? "true" : "false");
-}
-function groupBySymbolWith(arr, getter) {
-  return doGroupByWith(arr, getter);
-}
-function doGroupByWith(arr, getter) {
-  return arr.reduce((dict, cur) => {
-    const key = getter(cur);
-    if (key !== null && key !== void 0) {
-      const arr2 = dict[key] ?? [];
-      arr2.push(cur);
-      dict[key] = arr2;
-    }
-    return dict;
-  }, {});
-}
-
-// src/utils/iff.ts
-function iff(firstPredicate, valueIfTrue) {
-  if (firstPredicate === true || firstPredicate instanceof Function && firstPredicate() === true) {
-    const ret = {
-      elseIf: () => ret,
-      otherwise: () => valueIfTrue
-    };
-    return ret;
-  } else {
-    const ret = {
-      elseIf: (elseIf, valueIfElseIfTrue) => iff(elseIf, valueIfElseIfTrue),
-      otherwise: (valueIfElse) => valueIfElse
-    };
-    return ret;
-  }
-}
-
-// src/utils/indexBy.ts
-function indexByString(arr, field) {
-  return indexByStringWith(arr, (t) => t[field]);
-}
-function indexByNumber(arr, field) {
-  return indexByNumberWith(arr, (t) => t[field]);
-}
-function indexBySymbol(arr, field) {
-  return indexBySymbolWith(arr, (t) => t[field]);
-}
-function indexByStringWith(arr, getter) {
-  return doIndexByWith(arr, getter);
-}
-function indexByNumberWith(arr, getter) {
-  return doIndexByWith(arr, getter);
-}
-function indexBySymbolWith(arr, getter) {
-  return doIndexByWith(arr, getter);
-}
-function doIndexByWith(arr, getter) {
-  return arr.reduce((dict, cur) => {
-    const key = getter(cur);
-    if (key !== null && key !== void 0)
-      dict[key] = cur;
-    return dict;
-  }, {});
-}
-
-// src/utils/jsonCloneDeep.ts
-function jsonCloneDeep(a) {
-  if (null === a || "object" !== typeof a) return a;
-  if (a instanceof Date) {
-    return new Date(a.getTime());
-  } else if (a instanceof Array) {
-    const copy = [];
-    for (let i = 0, len = a.length; i < len; i++) {
-      copy[i] = jsonCloneDeep(a[i]);
-    }
-    return copy;
-  } else if (a instanceof Object) {
-    const copy = {};
-    for (let attr in a) {
-      if (a.hasOwnProperty(attr))
-        copy[attr] = jsonCloneDeep(a[attr]);
-    }
-    return copy;
-  }
-  throw new Error("Unable to copy obj! Its type isn't supported.");
-}
-
-// src/utils/math.ts
-function clamp(n, min2, max2) {
-  if (min2 === null || max2 === null || n === null || isNaN(min2) || isNaN(max2) || isNaN(n) || min2 > max2)
-    throw new Error();
-  if (n > max2) {
-    return max2;
-  } else if (n < min2) {
-    return min2;
-  } else {
-    return n;
-  }
-}
-function average(arr) {
-  const f = 1 / arr.length;
-  return arr.reduce((tot, cur) => tot + cur * f, 0);
-}
-function sum(arr) {
-  return arr.reduce((tot, cur) => tot + cur, 0);
-}
-function sumBy(arr, getter) {
-  return sum(arr.map(getter));
-}
-function min(arr) {
-  if (arr.length === 0) throw new Error("Cannot calculate value on empty array");
-  return arr.reduce((min2, cur) => cur < min2 ? cur : min2);
-}
-function minBy(arr, getter) {
-  return min(arr.map(getter));
-}
-function max(arr) {
-  if (arr.length === 0) throw new Error("Cannot calculate value on empty array");
-  return arr.reduce((max2, cur) => cur > max2 ? cur : max2);
-}
-function maxBy(arr, getter) {
-  return max(arr.map(getter));
-}
-
-// src/utils/omit.ts
-function omit(o, ...keys) {
-  return keys.reduce((obj, key) => {
-    delete obj[key];
-    return obj;
-  }, { ...o });
-}
-
-// src/utils/round.ts
-var roundModes = {
-  "toNearest": Math.round,
-  "toLower": Math.floor,
-  "toUpper": Math.ceil,
-  "towardsZero": (n) => n > 0 ? Math.floor(n) : Math.ceil(n),
-  "awayFromZero": (n) => n > 0 ? Math.ceil(n) : Math.floor(n)
-};
-function round(n, precision = 0, mode = "toNearest") {
-  const base = 10;
-  const power = Math.pow(base, precision);
-  return roundModes[mode](n * power) / power;
-}
-var roundToNearest = (n, precision = 0) => round(n, precision, "toNearest");
-var roundToLower = (n, precision = 0) => round(n, precision, "toLower");
-var roundToUpper = (n, precision = 0) => round(n, precision, "toUpper");
-var roundTowardsZero = (n, precision = 0) => round(n, precision, "towardsZero");
-var roundAwayFromZero = (n, precision = 0) => round(n, precision, "awayFromZero");
-
-// src/utils/sortBy.ts
-function sortBy(keyOrGetter, direction = "ASC", nulls = "LAST") {
-  const directionNum = direction === "ASC" ? -1 : 1;
-  const nullsNum = nulls === "LAST" ? -1 : 1;
-  const sortByNum = (a, b) => {
-    if (a === b)
-      return -1;
-    const aDefined = !(a === null || a === void 0 || isNaN(a));
-    const bDefined = !(b === null || b === void 0 || isNaN(b));
-    if (!aDefined && !bDefined)
-      return -1;
-    if (aDefined !== bDefined)
-      return nullsNum * (aDefined ? 1 : -1);
-    return (a > b ? -1 : 1) * directionNum;
-  };
-  if (typeof keyOrGetter === "function") {
-    return (a, b) => sortByNum(keyOrGetter(a), keyOrGetter(b));
-  } else {
-    return (a, b) => sortByNum(a[keyOrGetter], b[keyOrGetter]);
-  }
-}
-
-// src/utils/throttle.ts
-function throttle(fn, frequence) {
-  const semaphore = new RateThrottler(frequence);
-  return (...t) => {
-    return semaphore.execute(async () => fn(...t));
-  };
-}
-
-// src/utils/uniqBy.ts
-function uniqBy(arr, getter) {
-  return arr.reduce((dict, cur) => {
-    const key = getter(cur);
-    if (dict.keys.includes(key)) {
-      return dict;
-    } else {
-      return {
-        keys: [...dict.keys, key],
-        values: [...dict.values, cur]
-      };
-    }
-  }, { keys: [], values: [] }).values;
-}
-
-// src/utils/uniq.ts
-function uniq(arr) {
-  return uniqBy(arr, identity);
-}
-
-// src/utils/uniqByKey.ts
-function uniqByKey(arr, key) {
-  return uniqBy(arr, (item) => item[key]);
-}
-
-// src/utils/withTryCatch.ts
-function withTryCatch(fn) {
-  try {
-    return fn();
-  } catch (e) {
-    return asError(e);
-  }
-}
-
-// src/utils/withTryCatchAsync.ts
-async function withTryCatchAsync(fn) {
-  return fn().catch((e) => asError(e));
-}
-
-// src/utils/wrap.ts
-function wrap(str, delimiter) {
-  return delimiter + str + delimiter;
-}
-
 // src/upgrade/errors.ts
 var UnavailableUpgradeError = class extends Error {
   constructor(data, from, to) {
@@ -2646,6 +2623,7 @@ export {
   extendArray,
   extendArrayWith,
   fill,
+  first,
   flatMapTruthys,
   groupByBoolean,
   groupByBooleanWith,
@@ -2696,10 +2674,12 @@ export {
   multiplyBy,
   noop,
   omit,
+  omitFromJsonObject,
   pad,
   padLeft,
   padRight,
   pick,
+  pluralize,
   promiseSequence,
   randomInterval,
   randomPercentage,
@@ -2712,12 +2692,12 @@ export {
   roundToNearest,
   roundToUpper,
   roundTowardsZero,
-  sortBy,
   sortedArray,
   splitWords,
   stringToNumber,
   sum,
   sumBy,
+  tail,
   throttle,
   tryToParseJson,
   uniq,
@@ -2726,5 +2706,6 @@ export {
   upsert,
   withTryCatch,
   withTryCatchAsync,
-  wrap
+  wrap,
+  wrapWithString
 };