@zthun/helpful-fn 9.11.6 → 9.11.8

package/dist/cast/cast-enum.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Attempts to cast the candidate to an enumeration value.
+ *
+ * @param enumeration -
+ *        The enumeration type.
+ * @param candidate -
+ *        The candidate to cast to the enum type.
+ *
+ * @returns
+ *        The candidate if candidate represents the enumeration type,
+ *        or undefined in the case that it does not.
+ */
+export declare function castEnum<TEnum extends Record<string, string | number>>(enumeration: TEnum, candidate: unknown): TEnum[keyof TEnum] | undefined;
+/**
+ * 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.
+ */
+export declare function castEnum<TEnum extends Record<string, string | number>>(enumeration: TEnum, candidate: unknown, fallback: TEnum[keyof TEnum]): TEnum[keyof TEnum];

package/dist/cast/cast-number.d.mts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export declare function castNumber(candidate: unknown): number | undefined;
+/**
+ * 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.
+ */
+export declare function castNumber(candidate: unknown, fallback: number): number;

package/dist/date/calendar-month.d.mts

@@ -5,17 +5,17 @@
  * since it's easy to be off by 1 when specifying
  * a month index.
  */
-export declare const CalendarMonth: Readonly<{
-    January: 0;
-    February: 1;
-    March: 2;
-    April: 3;
-    May: 4;
-    June: 5;
-    July: 6;
-    August: 7;
-    September: 8;
-    October: 9;
-    November: 10;
-    December: 11;
-}>;
+export declare enum ZCalendarMonth {
+    January = 0,
+    February = 1,
+    March = 2,
+    April = 3,
+    May = 4,
+    June = 5,
+    July = 6,
+    August = 7,
+    September = 8,
+    October = 9,
+    November = 10,
+    December = 11
+}

package/dist/enum/enum-info.d.mts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+export interface IZEnumInformation<TEnum> {
+    /**
+     * The display name of the enum value.
+     */
+    name?: string;
+    /**
+     * The avatar representation of the enum.
+     *
+     * This can be anything and is contextual of how
+     * this object is used.
+     */
+    avatar?: any;
+    /**
+     * The description of the enum value.
+     */
+    description?: string;
+    /**
+     * The value being described.
+     */
+    value: TEnum;
+}
+/**
+ * Builds information for an enum.
+ */
+export declare class ZEnumInfoBuilder<TEnum> {
+    private _metadata;
+    /**
+     * Initializes a new instance of this object.
+     *
+     * @param value -
+     *        The value to initialize with.
+     */
+    constructor(value: TEnum);
+    /**
+     * The display name of the enum.
+     *
+     * @param name -
+     *        The display name of the enum.
+     *
+     * @returns
+     *        This object.
+     */
+    name(name: string): this;
+    /**
+     * Text description of the enum.
+     *
+     * @param description -
+     *        Text description of what the value means.
+     *
+     * @returns
+     *        This object.
+     */
+    description(description: string): 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: any): this;
+    /**
+     * Returns a shallow copy of the metadata.
+     *
+     * @returns
+     *        A shallow copy of the metadata.
+     */
+    build(): IZEnumInformation<TEnum>;
+}

package/dist/enum/is-enum.d.mts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export declare function isEnum<TEnum extends Record<string, string | number>>(enumeration: TEnum, candidate: unknown): candidate is TEnum[keyof TEnum];

package/dist/index.cjs

@@ -44,7 +44,7 @@ const dateFns = require('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,
@@ -117,10 +117,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.
  *
@@ -163,6 +198,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
@@ -531,6 +604,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
@@ -1988,6 +2151,7 @@ exports.ZAssert = ZAssert;
 exports.ZDateFormats = ZDateFormats;
 exports.ZDeserializeJson = ZDeserializeJson;
 exports.ZDeserializeTry = ZDeserializeTry;
+exports.ZEnumInfoBuilder = ZEnumInfoBuilder;
 exports.ZHorizontalAnchor = ZHorizontalAnchor;
 exports.ZLazy = ZLazy;
 exports.ZOrientation = ZOrientation;
@@ -1997,7 +2161,9 @@ exports.ZRectangle = ZRectangle;
 exports.ZSerializeJson = ZSerializeJson;
 exports.ZVerticalAnchor = ZVerticalAnchor;
 exports.bash = bash;
+exports.castEnum = castEnum;
 exports.castExtension = castExtension;
+exports.castNumber = castNumber;
 exports.commaJoinDefined = commaJoinDefined;
 exports.countBuckets = countBuckets;
 exports.createError = createError;
@@ -2016,6 +2182,7 @@ exports.gibibytes = gibibytes;
 exports.guessDateTime = guessDateTime;
 exports.html = html;
 exports.isEmptyObject = isEmptyObject;
+exports.isEnum = isEnum;
 exports.javascript = javascript;
 exports.joinDefined = joinDefined;
 exports.js = js;