@zthun/helpful-fn 9.11.6 → 9.11.8

package/dist/index.js

@@ -40,7 +40,7 @@ import { startOfToday, parse, formatDate } from 'date-fns';
     return ZHorizontalAnchor;
 }({});
 
-function _define_property$6(obj, key, value) {
+function _define_property$7(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -113,10 +113,45 @@ function _define_property$6(obj, key, value) {
     /**
    * Initializes a new instance of this object.
    */ constructor(){
-        _define_property$6(this, "_messages", []);
+        _define_property$7(this, "_messages", []);
     }
 }
 
+/**
+ * Gets whether the candidate can represent an enumeration object of type TEnum.
+ *
+ * This is mostly helpful for type guarding value options in a type.
+ *
+ * @param enumeration -
+ *        The enumeration object that contains the values.
+ * @param candidate -
+ *        The candidate to check.
+ *
+ * @returns
+ *        True if candidate can represents one of the white listed
+ *        object values in enumeration.
+ */ function isEnum(enumeration, candidate) {
+    return candidate != null && (typeof candidate === "string" || typeof candidate === "number") && Object.values(enumeration).includes(candidate);
+}
+
+/**
+ * Attempts to cast the candidate to an enumeration value.
+ *
+ * @param enumeration -
+ *        The enumeration type.
+ * @param candidate -
+ *        The candidate to cast to the enum type.
+ * @param fallback -
+ *        The fallback to use in the case that candidate
+ *        cannot represent the enumeration type.
+ *
+ * @returns
+ *        The candidate if candidate represents the enumeration type,
+ *        or fallback in the case that it does not.
+ */ function castEnum(enumeration, candidate, fallback) {
+    return isEnum(enumeration, candidate) ? candidate : fallback;
+}
+
 /**
  * Puts a . in front of name if one is not already there.
  *
@@ -159,6 +194,44 @@ function _define_property$6(obj, key, value) {
     return `.${normalized}`;
 }
 
+/**
+ * Attempts to cast candidate to a number.
+ *
+ * This method assumes you want an actual number and
+ * not NaN.  In the case that candidate results in
+ * NaN, then the fallback condition applies.
+ *
+ * @param candidate -
+ *        The candidate to cast.
+ *
+ * @returns
+ *        The casted number or undefined in the cast
+ *        that casting candidate would result in NaN.
+ */ /**
+ * Attempts to cast candidate to a number.
+ *
+ * This method assumes you want an actual number and
+ * not NaN.  In the case that candidate results in
+ * NaN, then the fallback condition applies.
+ *
+ * @param candidate -
+ *        The candidate to cast.
+ * @param fallback -
+ *        The fallback value in the case that the result
+ *        of casting candidate would result in NaN
+ *
+ * @returns
+ *        The casted number or fallback in the cast
+ *        that casting candidate would result in NaN.
+ */ function castNumber(candidate, fallback) {
+    try {
+        const casted = Number(candidate);
+        return Number.isNaN(casted) ? fallback : casted;
+    } catch  {
+        return fallback;
+    }
+}
+
 /**
  * Calculates the total number of buckets you need to
  * store a number of items where each bucket can hold a
@@ -527,6 +600,96 @@ function _define_property$6(obj, key, value) {
     return candidate == null || candidateType === "object" && Object.keys(candidate).length === 0;
 }
 
+/**
+ * Information for an enum value.
+ *
+ * This is useful for front end development when
+ * you want to map an enumeration like value to
+ * things like a display name, description, and
+ * avatar.  ECMAScript does not support decorators
+ * for literal fields so this is an alternative
+ * to describe that kind of information.
+ *
+ * This is similar to Metadata from helpful-query,
+ * but it's much more specific and specialized
+ * to enumerations.
+ */ function _define_property$6(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Builds information for an enum.
+ */ class ZEnumInfoBuilder {
+    /**
+   * The display name of the enum.
+   *
+   * @param name -
+   *        The display name of the enum.
+   *
+   * @returns
+   *        This object.
+   */ name(name) {
+        this._metadata.name = name;
+        return this;
+    }
+    /**
+   * Text description of the enum.
+   *
+   * @param description -
+   *        Text description of what the value means.
+   *
+   * @returns
+   *        This object.
+   */ description(description) {
+        this._metadata.description = description;
+        return this;
+    }
+    /**
+   * The avatar representation of the enum.
+   *
+   * @param avatar -
+   *        The avatar representation of what the value
+   *        is.  This can be anything but should be related
+   *        to the framework it is being developed for.
+   *
+   * @returns
+   *        This object.
+   */ avatar(avatar) {
+        this._metadata.avatar = avatar;
+        return this;
+    }
+    /**
+   * Returns a shallow copy of the metadata.
+   *
+   * @returns
+   *        A shallow copy of the metadata.
+   */ build() {
+        return {
+            ...this._metadata
+        };
+    }
+    /**
+   * Initializes a new instance of this object.
+   *
+   * @param value -
+   *        The value to initialize with.
+   */ constructor(value){
+        _define_property$6(this, "_metadata", void 0);
+        this._metadata = {
+            value
+        };
+    }
+}
+
 const BYTES_PER_KIBIBYTE = 1024;
 const BYTES_PER_MEBIBYTE = 1048576; // 1024 ^ 2
 const BYTES_PER_GIBIBYTE = 1073741824; // 1024 ^ 3
@@ -1979,5 +2142,5 @@ function _define_property(obj, key, value) {
     return tryFallback(()=>JSON.parse(buffer), fallback);
 }
 
-export { $global, ZAssert, ZDateFormats, ZDeserializeJson, ZDeserializeTry, ZHorizontalAnchor, ZLazy, ZOrientation, ZQuadrilateralBuilder, ZQuadrilateralCornersBuilder, ZRectangle, ZSerializeJson, ZVerticalAnchor, bash, castExtension, commaJoinDefined, countBuckets, createError, createGuid, css, cssJoinDefined, culture, cultures, detokenize, firstDefined, firstTruthy, firstWhere, formatDateTime, gib, gibibytes, guessDateTime, html, isEmptyObject, javascript, joinDefined, js, kib, kibibytes, markdown, md, mebibytes, mib, optional, parseDateTime, pebibytes, peel, peelBetween, pib, pickBy, pickDataAttributes, pickDefined, pickEvents, pipeJoinDefined, purge, required, semiColonJoinDefined, setFirst, sh, sleep, spaceJoinDefined, tag, tebibytes, tib, timeZones, tryFallback, tryFallbackAsync, tryJsonParse, ts, typescript, userTimeZone, zsh };
+export { $global, ZAssert, ZDateFormats, ZDeserializeJson, ZDeserializeTry, ZEnumInfoBuilder, ZHorizontalAnchor, ZLazy, ZOrientation, ZQuadrilateralBuilder, ZQuadrilateralCornersBuilder, ZRectangle, ZSerializeJson, ZVerticalAnchor, bash, castEnum, castExtension, castNumber, commaJoinDefined, countBuckets, createError, createGuid, css, cssJoinDefined, culture, cultures, detokenize, firstDefined, firstTruthy, firstWhere, formatDateTime, gib, gibibytes, guessDateTime, html, isEmptyObject, isEnum, javascript, joinDefined, js, kib, kibibytes, markdown, md, mebibytes, mib, optional, parseDateTime, pebibytes, peel, peelBetween, pib, pickBy, pickDataAttributes, pickDefined, pickEvents, pipeJoinDefined, purge, required, semiColonJoinDefined, setFirst, sh, sleep, spaceJoinDefined, tag, tebibytes, tib, timeZones, tryFallback, tryFallbackAsync, tryJsonParse, ts, typescript, userTimeZone, zsh };
 //# sourceMappingURL=index.js.map