@zthun/helpful-fn 9.11.5 → 9.11.7

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/culture/culture.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Returns the users current culture (locale).
+ *
+ * @returns
+ *        The current locale.
+ */
+export declare function culture(): string;
+/**
+ * Returns all supported cultures.
+ *
+ * @returns
+ *        A list of currently supported culture codes.
+ */
+export declare function cultures(): string[];

package/dist/culture/locale-lookup.d.mts

@@ -0,0 +1,17 @@
+import { enAU, enCA, enGB, enIE, enIN, enNZ, enUS, enZA, ja } from 'date-fns/locale';
+/**
+ * Supported locales from date-fns.
+ *
+ * This should not be exported.  This is an internal helper.
+ */
+export declare const LocaleLookup: {
+    [enAU.code]: import('date-fns/locale').Locale;
+    [enCA.code]: import('date-fns/locale').Locale;
+    [enGB.code]: import('date-fns/locale').Locale;
+    [enIE.code]: import('date-fns/locale').Locale;
+    [enIN.code]: import('date-fns/locale').Locale;
+    [enNZ.code]: import('date-fns/locale').Locale;
+    [enUS.code]: import('date-fns/locale').Locale;
+    [enZA.code]: import('date-fns/locale').Locale;
+    [ja.code]: import('date-fns/locale').Locale;
+};

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

@@ -0,0 +1,21 @@
+/**
+ * The index offsets for the original roman calendar months.
+ *
+ * This is helpful when creating dates from numbers
+ * since it's easy to be off by 1 when specifying
+ * a month index.
+ */
+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/date/date-time.d.mts

@@ -0,0 +1,38 @@
+/**
+ * Represents a value for a date time object.
+ */
+export type ZDateTime = string | Date | number | null | undefined;
+/**
+ * Options for performing operations on a {@link ZDateTime} object.
+ */
+export type ZDateTimeOptions<T> = {
+    /**
+     * The string format to output.
+     */
+    format?: string;
+    /**
+     * A list of supported formats when guessing a date.
+     *
+     * If this is falsy, then the standard formats in
+     * {@link ZDateFormats} is used.
+     */
+    supportedFormats?: string[];
+    /**
+     * The culture language to use.
+     *
+     * If this is not specified, then you can assume
+     * that the user's system culture is used.
+     */
+    culture?: string;
+    /**
+     * The timezone to force.
+     *
+     * If this is not specified, then you can assume the
+     * user's current timezone.
+     */
+    timeZone?: string;
+    /**
+     * An optional fallback value for invalid date formats or bad parsing.
+     */
+    fallback?: T;
+};

package/dist/date/format-date.d.mts

@@ -0,0 +1,52 @@
+import { ZDateTime, ZDateTimeOptions } from '../date/date-time.mjs';
+/**
+ * Basic date formats that are common for storage and usage.
+ */
+export declare enum ZDateFormats {
+    /**
+     * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format with date only.
+     *
+     * Using this should imply midnight user timezone.
+     */
+    IsoDateOnly = "yyyy-MM-dd",
+    /**
+     * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format with time only.
+     */
+    IsoTimeOnly = "HH:mm:ss.SSS",
+    /**
+     * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format without timezone specifier.
+     */
+    IsoNoTimeZone = "yyyy-MM-dd'T'HH:mm:ss.SSS",
+    /**
+     * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format.
+     */
+    Iso = "yyyy-MM-dd'T'HH:mm:ss.SSSXX",
+    /**
+     * Users local date (locale specific).
+     */
+    LocalDate = "P",
+    /**
+     * User local time (locale specific).
+     */
+    LocalTime = "p",
+    /**
+     * Date and time formatted with user specific locale.
+     */
+    LocalDateTime = "Pp"
+}
+/**
+ * Formats a given value.
+ *
+ * @param value -
+ *        The value to format.
+ * @param options -
+ *        The given options for the format.
+ *
+ * @returns
+ *        If value is null or undefined, then the empty string is returned.
+ *        If value is a string, then the date is guessed from the string and
+ *        reformatted to the format specified by options.  Otherwise,
+ *        the date or number specified by value is formatted to the culture,
+ *        timezone, and format specified in the options.
+ */
+export declare function formatDateTime(value: ZDateTime, options?: ZDateTimeOptions<string>): string;

package/dist/date/guess-date.d.mts

@@ -0,0 +1,11 @@
+import { ZDateTime, ZDateTimeOptions } from '../date/date-time.mjs';
+/**
+ * Similar to {@link parseDateTime} but tries multiple supported formats.
+ *
+ * @param value -
+ *        The value to parse that may result in a date.
+ * @param options -
+ *        The options for guessing the date.  These will be forwarded to parse
+ *        for processing.
+ */
+export declare function guessDateTime(value: ZDateTime, options?: ZDateTimeOptions<Date | null>): Date | null;

package/dist/date/parse-date.d.mts

@@ -0,0 +1,21 @@
+import { ZDateTime, ZDateTimeOptions } from '../date/date-time.mjs';
+/**
+ * Parses a string value back to a date format.
+ *
+ *
+ * @param value -
+ *        The value to parse
+ * @param options -
+ *        The options to parse with.  The most important option here is format.
+ *        If the format is not specified, then the standard zoned ISO 8601
+ *        format is used.  The timezone is also used in the case the date
+ *        does not supply it for string values.  If the timezone is not specified
+ *        then the users timezone is assumed.  Finally, the cultural local will
+ *        default to the users current culture if not specified.
+ *
+ * @returns
+ *        The date object parsed from the value.  Returns null
+ *        if the value parsed with the given options results in an
+ *        invalid date.
+ */
+export declare function parseDateTime(value: ZDateTime, options?: ZDateTimeOptions<Date | null>): Date | null;

package/dist/date/timezone.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Returns the user's current timezone.
+ *
+ * @returns
+ *        The users current timezone.
+ */
+export declare function userTimeZone(): string;
+/**
+ * Returns the list of all supported timezones.
+ *
+ * @returns
+ *        A list of all timezone values.
+ */
+export declare function timeZones(): string[];

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

@@ -3,6 +3,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const uuid = require('uuid');
+const locale = require('date-fns/locale');
+const tz = require('@date-fns/tz');
+const dateFns = require('date-fns');
 
 /**
  * Represents a targeted point along a y axis.
@@ -118,6 +121,41 @@ function _define_property$6(obj, key, value) {
     }
 }
 
+/**
+ * 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.
  *
@@ -160,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
@@ -301,6 +377,187 @@ function _define_property$6(obj, key, value) {
  * ```
  */ const createGuid = uuid.v4;
 
+/**
+ * Supported locales from date-fns.
+ *
+ * This should not be exported.  This is an internal helper.
+ */ const LocaleLookup = {
+    [locale.enAU.code]: locale.enAU,
+    [locale.enCA.code]: locale.enCA,
+    [locale.enGB.code]: locale.enGB,
+    [locale.enIE.code]: locale.enIE,
+    [locale.enIN.code]: locale.enIN,
+    [locale.enNZ.code]: locale.enNZ,
+    [locale.enUS.code]: locale.enUS,
+    [locale.enZA.code]: locale.enZA,
+    [locale.ja.code]: locale.ja
+};
+
+/**
+ * Returns the users current culture (locale).
+ *
+ * @returns
+ *        The current locale.
+ */ function culture() {
+    const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+    return locale;
+}
+/**
+ * Returns all supported cultures.
+ *
+ * @returns
+ *        A list of currently supported culture codes.
+ */ function cultures() {
+    return Object.keys(LocaleLookup);
+}
+
+/**
+ * Returns the user's current timezone.
+ *
+ * @returns
+ *        The users current timezone.
+ */ function userTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+/**
+ * Returns the list of all supported timezones.
+ *
+ * @returns
+ *        A list of all timezone values.
+ */ function timeZones() {
+    return Intl.supportedValuesOf("timeZone");
+}
+
+/**
+ * Parses a string value back to a date format.
+ *
+ *
+ * @param value -
+ *        The value to parse
+ * @param options -
+ *        The options to parse with.  The most important option here is format.
+ *        If the format is not specified, then the standard zoned ISO 8601
+ *        format is used.  The timezone is also used in the case the date
+ *        does not supply it for string values.  If the timezone is not specified
+ *        then the users timezone is assumed.  Finally, the cultural local will
+ *        default to the users current culture if not specified.
+ *
+ * @returns
+ *        The date object parsed from the value.  Returns null
+ *        if the value parsed with the given options results in an
+ *        invalid date.
+ */ function parseDateTime(value, options = {}) {
+    const { fallback = null } = options;
+    if (value == null) {
+        return fallback;
+    }
+    if (typeof value === "number") {
+        const candidate = new Date(value);
+        return Number.isNaN(candidate.getTime()) ? fallback : candidate;
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? fallback : value;
+    }
+    const { format = ZDateFormats.Iso, culture: culture$1 = culture(), timeZone = userTimeZone() } = options;
+    const locale = LocaleLookup[culture$1];
+    const reference = new tz.TZDate(dateFns.startOfToday()).withTimeZone(timeZone);
+    const result = dateFns.parse(value, format, reference, {
+        locale
+    });
+    return Number.isNaN(result.getTime()) ? fallback : result;
+}
+
+/**
+ * Similar to {@link parseDateTime} but tries multiple supported formats.
+ *
+ * @param value -
+ *        The value to parse that may result in a date.
+ * @param options -
+ *        The options for guessing the date.  These will be forwarded to parse
+ *        for processing.
+ */ function guessDateTime(value, options = {}) {
+    const { fallback = null } = options;
+    if (value == null) {
+        return fallback;
+    }
+    const { supportedFormats = Object.values(ZDateFormats) } = options;
+    for (const fmt of supportedFormats){
+        const inner = {
+            ...options
+        };
+        inner.format = fmt;
+        const result = parseDateTime(value, inner);
+        if (result != null) {
+            return result;
+        }
+    }
+    return fallback;
+}
+
+/**
+ * Basic date formats that are common for storage and usage.
+ */ var ZDateFormats = /*#__PURE__*/ function(ZDateFormats) {
+    /**
+   * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format with date only.
+   *
+   * Using this should imply midnight user timezone.
+   */ ZDateFormats["IsoDateOnly"] = "yyyy-MM-dd";
+    /**
+   * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format with time only.
+   */ ZDateFormats["IsoTimeOnly"] = "HH:mm:ss.SSS";
+    /**
+   * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format without timezone specifier.
+   */ ZDateFormats["IsoNoTimeZone"] = "yyyy-MM-dd'T'HH:mm:ss.SSS";
+    /**
+   * Standard {@link https://en.wikipedia.org/wiki/ISO_8601 | ISO-8601} format.
+   */ ZDateFormats["Iso"] = "yyyy-MM-dd'T'HH:mm:ss.SSSXX";
+    /**
+   * Users local date (locale specific).
+   */ ZDateFormats["LocalDate"] = "P";
+    /**
+   * User local time (locale specific).
+   */ ZDateFormats["LocalTime"] = "p";
+    /**
+   * Date and time formatted with user specific locale.
+   */ ZDateFormats["LocalDateTime"] = "Pp";
+    return ZDateFormats;
+}({});
+/**
+ * Formats a given value.
+ *
+ * @param value -
+ *        The value to format.
+ * @param options -
+ *        The given options for the format.
+ *
+ * @returns
+ *        If value is null or undefined, then the empty string is returned.
+ *        If value is a string, then the date is guessed from the string and
+ *        reformatted to the format specified by options.  Otherwise,
+ *        the date or number specified by value is formatted to the culture,
+ *        timezone, and format specified in the options.
+ */ function formatDateTime(value, options = {}) {
+    const { format = "Pp", culture: culture$1 = culture(), timeZone = userTimeZone(), fallback = "" } = options;
+    let date;
+    if (value == null) {
+        date = null;
+    } else if (typeof value === "string") {
+        date = guessDateTime(value, {
+            ...options,
+            fallback: null
+        });
+    } else {
+        date = new Date(value);
+    }
+    if (date == null || Number.isNaN(date.getTime())) {
+        return fallback;
+    }
+    const withTz = new tz.TZDate(date, timeZone);
+    return dateFns.formatDate(withTz, format, {
+        locale: LocaleLookup[culture$1]
+    });
+}
+
 /**
  * Does replacement of interpolation, ${}, tokens in a string.
  *
@@ -1801,6 +2058,7 @@ function _define_property(obj, key, value) {
 
 exports.$global = $global;
 exports.ZAssert = ZAssert;
+exports.ZDateFormats = ZDateFormats;
 exports.ZDeserializeJson = ZDeserializeJson;
 exports.ZDeserializeTry = ZDeserializeTry;
 exports.ZHorizontalAnchor = ZHorizontalAnchor;
@@ -1812,21 +2070,28 @@ 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;
 exports.createGuid = createGuid;
 exports.css = css;
 exports.cssJoinDefined = cssJoinDefined;
+exports.culture = culture;
+exports.cultures = cultures;
 exports.detokenize = detokenize;
 exports.firstDefined = firstDefined;
 exports.firstTruthy = firstTruthy;
 exports.firstWhere = firstWhere;
+exports.formatDateTime = formatDateTime;
 exports.gib = gib;
 exports.gibibytes = gibibytes;
+exports.guessDateTime = guessDateTime;
 exports.html = html;
 exports.isEmptyObject = isEmptyObject;
+exports.isEnum = isEnum;
 exports.javascript = javascript;
 exports.joinDefined = joinDefined;
 exports.js = js;
@@ -1837,6 +2102,7 @@ exports.md = md;
 exports.mebibytes = mebibytes;
 exports.mib = mib;
 exports.optional = optional;
+exports.parseDateTime = parseDateTime;
 exports.pebibytes = pebibytes;
 exports.peel = peel;
 exports.peelBetween = peelBetween;
@@ -1856,10 +2122,12 @@ exports.spaceJoinDefined = spaceJoinDefined;
 exports.tag = tag;
 exports.tebibytes = tebibytes;
 exports.tib = tib;
+exports.timeZones = timeZones;
 exports.tryFallback = tryFallback;
 exports.tryFallbackAsync = tryFallbackAsync;
 exports.tryJsonParse = tryJsonParse;
 exports.ts = ts;
 exports.typescript = typescript;
+exports.userTimeZone = userTimeZone;
 exports.zsh = zsh;
 //# sourceMappingURL=index.cjs.map