@putkoff/abstract-utilities 1.0.29 → 1.0.32

package/dist/cjs/index.js

@@ -1831,6 +1831,28 @@ function get_splitext(filePath) {
     const filename = pathBrowserify.basename(filePath, ext);
     return { filename, ext };
 }
+/**
+ * Returns the path of `targetPath` relative to `basePath`.
+ * Normalizes separators for consistent web and server environments.
+ *
+ * @param basePath - The base directory you want to compare from.
+ * @param targetPath - The full path of the file/directory.
+ * @returns A normalized relative path (e.g., "subdir/file.txt").
+ */
+function get_relative_path(basePath, targetPath) {
+    try {
+        // Compute the relative path using Node's native path.relative
+        let rel = pathBrowserify.relative(basePath, targetPath);
+        // Normalize to POSIX-style slashes for consistency (especially on Windows)
+        rel = rel.split(pathBrowserify.sep).join('/');
+        // Avoid empty string (happens if both paths are identical)
+        return rel || '.';
+    }
+    catch (err) {
+        console.error(`[get_relative_path] Error computing relative path`, err);
+        return targetPath;
+    }
+}
 /**
  * Join multiple path segments, normalizing leading/trailing slashes.
  *
@@ -2018,7 +2040,6 @@ function exponential(i, k) {
     return i * (10 ** (k));
 }
 
-// Time
 const SECOND = 1;
 const ZEPTOSECOND = exponential(SECOND, -21);
 const ATTOSECOND = exponential(SECOND, -18);
@@ -2042,66 +2063,147 @@ const SECONDS_PER_DAY = DAY;
 const PI = Math.PI;
 const PI2 = 2 * PI;
 // Distance
-const M_IN_KM = 1000;
-const M_IN_MI = 1609.34;
-const M_IN_FT = 0.3048;
-const KM_IN_M = 1 / M_IN_KM;
-const MI_IN_M = 1 / M_IN_MI;
-const FT_IN_M = 1 / M_IN_FT;
+const METERS_PER_KM = 1000;
+const METERS_PER_MILE = 1609.34;
+const METERS_PER_FOOT = 0.3048;
+const KMS_PER_METER = 1 / METERS_PER_KM;
+const MILES_PER_METER = 1 / METERS_PER_MILE;
+const FEET_PER_METER = 1 / METERS_PER_FOOT;
 const MIN_IN_S = 1 / MINUTE;
 const HOUR_IN_S = 1 / HOUR;
 const DAY_IN_S = 1 / DAY;
 const YEAR_IN_S = 1 / YEAR;
 const MONTH_IN_S = 1 / MONTH;
-const MiPerH_TO_MPerS = M_IN_MI * HOUR_IN_S;
+const MiPerH_TO_MPerS = METERS_PER_MILE * HOUR_IN_S;
 const MPerS_TO_MiPerH = 1 / MiPerH_TO_MPerS;
 
-// Conversion helpers
-const toMeters = (v, unit) => {
-    switch (unit) {
-        case 'km': return v * M_IN_KM;
-        case 'mi': return v * M_IN_MI;
-        case 'ft': return v * M_IN_FT;
-        default: return v; // meters
-    }
+// conversions.ts
+/*───────────────────────────────────────────────────────────────
+  🧭 CANONICAL MAPPINGS
+───────────────────────────────────────────────────────────────*/
+const DIST_ALIASES = {
+    m: "m", meter: "m", meters: "m",
+    km: "km", kms: "km", kilometer: "km", kilometers: "km",
+    mi: "mi", mile: "mi", miles: "mi",
+    ft: "ft", f: "ft", foot: "ft", feet: "ft",
 };
-const toSeconds = (v, unit) => {
-    switch (unit) {
-        case 'min': return v * MINUTE;
-        case 'h': return v * HOUR;
-        case 'day': return v * DAY;
-        default: return v;
-    }
+const TIME_ALIASES = {
+    s: "s", sec: "s", second: "s", seconds: "s",
+    min: "min", m: "min", minute: "min", minutes: "min",
+    h: "h", hr: "h", hour: "h", hours: "h",
+    day: "day", d: "day", days: "day",
 };
-const fromMeters = (d, unit) => {
-    switch (unit) {
-        case 'km': return d / M_IN_KM;
-        case 'mi': return d / M_IN_MI;
-        case 'ft': return d / M_IN_FT;
-        default: return d; // meters
-    }
+const DIST_FACTORS = {
+    m: 1,
+    km: METERS_PER_KM,
+    mi: METERS_PER_MILE,
+    ft: METERS_PER_FOOT,
 };
-const velocityToMs = (value, unit) => {
-    switch (unit) {
-        case 'km/s': return value * M_IN_KM;
-        case 'mph': return value * MiPerH_TO_MPerS; // 1 mph = 0.44704 m/s
-        case 'ft/s': return value * M_IN_FT; // 1 ft/s = 0.3048 m/s
-        default: return value; // m/s
-    }
+const TIME_FACTORS = {
+    s: 1,
+    min: MINUTE,
+    h: HOUR,
+    day: DAY,
 };
-const velocityFromMs = (value, unit) => {
-    switch (unit) {
-        case 'km/s': return value * KM_IN_M;
-        case 'mph': return value * MPerS_TO_MiPerH;
-        case 'ft/s': return value * FT_IN_M;
-        default: return value;
-    }
+/*───────────────────────────────────────────────────────────────
+  🔍 CANONICALIZATION HELPERS
+───────────────────────────────────────────────────────────────*/
+function canonDist(u) {
+    const key = (u !== null && u !== void 0 ? u : "m").toString().toLowerCase();
+    const canon = DIST_ALIASES[key];
+    if (!canon)
+        throw new Error(`Unknown distance unit: ${u}`);
+    return canon;
+}
+function canonTime(u) {
+    const key = (u !== null && u !== void 0 ? u : "s").toString().toLowerCase();
+    const canon = TIME_ALIASES[key];
+    if (!canon)
+        throw new Error(`Unknown time unit: ${u}`);
+    return canon;
+}
+/*───────────────────────────────────────────────────────────────
+  ⚖️ NORMALIZATION HELPERS
+───────────────────────────────────────────────────────────────*/
+function distanceToMeters(d, unit) {
+    const u = canonDist(unit);
+    return safeMultiply(d, DIST_FACTORS[u]);
+}
+function metersToDistance(v, unit) {
+    const u = canonDist(unit);
+    return safeDivide(v, DIST_FACTORS[u]);
+}
+function timeToSeconds(t, unit) {
+    const u = canonTime(unit);
+    return safeMultiply(t, TIME_FACTORS[u]);
+}
+function secondsToTime(v, unit) {
+    const u = canonTime(unit);
+    return safeDivide(v, TIME_FACTORS[u]);
+}
+/*───────────────────────────────────────────────────────────────
+  🚀 SPEED CONVERSIONS (normalize / unnormalize)
+───────────────────────────────────────────────────────────────*/
+function speedToMps(v, distUnit, timeUnit) {
+    const du = canonDist(distUnit);
+    const tu = canonTime(timeUnit);
+    return v * (DIST_FACTORS[du] / TIME_FACTORS[tu]);
+}
+function mpsToSpeed(vMps, distUnit, timeUnit) {
+    const du = canonDist(distUnit);
+    const tu = canonTime(timeUnit);
+    return vMps * (TIME_FACTORS[tu] / DIST_FACTORS[du]);
+}
+/*───────────────────────────────────────────────────────────────
+  🎯 UNIVERSAL CONVERTERS
+───────────────────────────────────────────────────────────────*/
+function convertDistance({ d, fromDist, toDist, vOnly = true, }) {
+    const m = distanceToMeters(d, fromDist);
+    const D = canonDist(toDist !== null && toDist !== void 0 ? toDist : "m");
+    const out = metersToDistance(m, D);
+    return vOnly ? out : { d: out, D };
+}
+function convertTime({ t, fromTime, toTime, vOnly = true, }) {
+    const sec = timeToSeconds(t, fromTime);
+    const T = canonTime(toTime !== null && toTime !== void 0 ? toTime : "s");
+    const out = secondsToTime(sec, T);
+    return vOnly ? out : { t: out, T };
+}
+function convertSpeed({ v, fromDist, fromTime, toDist, toTime, vOnly = true, }) {
+    const mps = speedToMps(v, fromDist, fromTime);
+    const d = canonDist(toDist !== null && toDist !== void 0 ? toDist : "m");
+    const t = canonTime(toTime !== null && toTime !== void 0 ? toTime : "s");
+    const out = mpsToSpeed(mps, d, t);
+    return vOnly ? out : { v: out, d, t };
+}
+const DistanceConverter = {
+    normalize: distanceToMeters,
+    unnormalize: metersToDistance,
+};
+const TimeConverter = {
+    normalize: timeToSeconds,
+    unnormalize: secondsToTime,
 };
-const fromMps = (v, dist_unit, time_unit) => {
-    const dist_conv = toMeters(1, dist_unit);
-    const time_conv = toSeconds(1, time_unit);
-    return v * (time_conv / dist_conv);
+const SpeedConverter = {
+    normalize: (v, [du, tu]) => speedToMps(v, du, tu),
+    unnormalize: (v, [du, tu]) => mpsToSpeed(v, du, tu),
 };
+/*───────────────────────────────────────────────────────────────
+  🧩 COMPATIBILITY WRAPPERS (legacy aliases)
+───────────────────────────────────────────────────────────────*/
+const toMeters = distanceToMeters;
+const fromMeters = metersToDistance;
+const toSeconds = timeToSeconds;
+const fromSeconds = secondsToTime;
+const velocityToMs = (value, unit) => speedToMps(value, unit, "s");
+const velocityFromMs = (value, unit) => mpsToSpeed(value, unit, "s");
+/** Non-canonical helper for arbitrary rate conversion, e.g. ft/day → m/s */
+const fromMps = (v, dist_unit, time_unit) => mpsToSpeed(v, dist_unit, time_unit);
+/*───────────────────────────────────────────────────────────────
+  📊 UTILITIES
+───────────────────────────────────────────────────────────────*/
+const isFiniteNum = (x) => Number.isFinite(x);
+const fmt = (n, digits = 2) => isFiniteNum(n) ? n.toFixed(digits) : "N/A";
 
 function Button(_a) {
     var { children, color = 'gray', variant = 'default', className = '' } = _a, rest = __rest(_a, ["children", "color", "variant", "className"]);
@@ -2272,26 +2374,29 @@ exports.DAY = DAY;
 exports.DAY_IN_S = DAY_IN_S;
 exports.DECISECOND = DECISECOND;
 exports.DEV_PREFIX = DEV_PREFIX;
+exports.DIST_ALIASES = DIST_ALIASES;
+exports.DIST_FACTORS = DIST_FACTORS;
 exports.DOMAIN_NAME = DOMAIN_NAME;
+exports.DistanceConverter = DistanceConverter;
+exports.FEET_PER_METER = FEET_PER_METER;
 exports.FEMTOSECOND = FEMTOSECOND;
-exports.FT_IN_M = FT_IN_M;
 exports.HOUR = HOUR;
 exports.HOUR_IN_S = HOUR_IN_S;
 exports.Input = Input;
-exports.KM_IN_M = KM_IN_M;
+exports.KMS_PER_METER = KMS_PER_METER;
 exports.MEDIA_TYPES = MEDIA_TYPES;
+exports.METERS_PER_FOOT = METERS_PER_FOOT;
+exports.METERS_PER_KM = METERS_PER_KM;
+exports.METERS_PER_MILE = METERS_PER_MILE;
 exports.MICROSECOND = MICROSECOND;
+exports.MILES_PER_METER = MILES_PER_METER;
 exports.MILISECOND = MILISECOND;
 exports.MIME_TYPES = MIME_TYPES;
 exports.MINUTE = MINUTE;
 exports.MIN_IN_S = MIN_IN_S;
-exports.MI_IN_M = MI_IN_M;
 exports.MONTH = MONTH;
 exports.MONTH_IN_S = MONTH_IN_S;
 exports.MPerS_TO_MiPerH = MPerS_TO_MiPerH;
-exports.M_IN_FT = M_IN_FT;
-exports.M_IN_KM = M_IN_KM;
-exports.M_IN_MI = M_IN_MI;
 exports.MiPerH_TO_MPerS = MiPerH_TO_MPerS;
 exports.NANOSECOND = NANOSECOND;
 exports.PI = PI;
@@ -2304,7 +2409,11 @@ exports.SECONDS_PER_DAY = SECONDS_PER_DAY;
 exports.SECONDS_PER_HOUR = SECONDS_PER_HOUR;
 exports.SECONDS_PER_MINUTE = SECONDS_PER_MINUTE;
 exports.SUB_DIR = SUB_DIR;
+exports.SpeedConverter = SpeedConverter;
 exports.Spinner = Spinner;
+exports.TIME_ALIASES = TIME_ALIASES;
+exports.TIME_FACTORS = TIME_FACTORS;
+exports.TimeConverter = TimeConverter;
 exports.YEAR = YEAR;
 exports.YEAR_IN_S = YEAR_IN_S;
 exports.ZEPTOSECOND = ZEPTOSECOND;
@@ -2319,6 +2428,8 @@ exports.assure_number = assure_number;
 exports.assure_string = assure_string;
 exports.callStorage = callStorage;
 exports.callWindowMethod = callWindowMethod;
+exports.canonDist = canonDist;
+exports.canonTime = canonTime;
 exports.capitalize = capitalize;
 exports.capitalize_str = capitalize_str;
 exports.checkResponse = checkResponse;
@@ -2326,10 +2437,14 @@ exports.cleanArray = cleanArray;
 exports.cleanText = cleanText;
 exports.confirmType = confirmType;
 exports.confirm_type = confirm_type;
+exports.convertDistance = convertDistance;
+exports.convertSpeed = convertSpeed;
+exports.convertTime = convertTime;
 exports.create_list_string = create_list_string;
 exports.currentUsername = currentUsername;
 exports.currentUsernames = currentUsernames;
 exports.decodeJwt = decodeJwt;
+exports.distanceToMeters = distanceToMeters;
 exports.eatAll = eatAll;
 exports.eatEnd = eatEnd;
 exports.eatInner = eatInner;
@@ -2346,9 +2461,11 @@ exports.exponential = exponential;
 exports.fetchIndexHtml = fetchIndexHtml;
 exports.fetchIndexHtmlContainer = fetchIndexHtmlContainer;
 exports.fetchIt = fetchIt;
+exports.fmt = fmt;
 exports.formatNumber = formatNumber;
 exports.fromMeters = fromMeters;
 exports.fromMps = fromMps;
+exports.fromSeconds = fromSeconds;
 exports.geAuthsUtilsDirectory = geAuthsUtilsDirectory;
 exports.geBackupsUtilsDirectory = geBackupsUtilsDirectory;
 exports.geConstantsUtilsDirectory = geConstantsUtilsDirectory;
@@ -2416,11 +2533,13 @@ exports.get_keyword_string = get_keyword_string;
 exports.get_media_exts = get_media_exts;
 exports.get_media_map = get_media_map;
 exports.get_mime_type = get_mime_type;
+exports.get_relative_path = get_relative_path;
 exports.get_splitext = get_splitext;
 exports.get_window = get_window;
 exports.get_window_location = get_window_location;
 exports.get_window_parts = get_window_parts;
 exports.get_window_pathname = get_window_pathname;
+exports.isFiniteNum = isFiniteNum;
 exports.isLoggedIn = isLoggedIn;
 exports.isMediaType = isMediaType;
 exports.isNum = isNum;
@@ -2431,6 +2550,8 @@ exports.is_media_type = is_media_type;
 exports.loadConfig = loadConfig;
 exports.make_path = make_path;
 exports.make_sanitized_path = make_sanitized_path;
+exports.metersToDistance = metersToDistance;
+exports.mpsToSpeed = mpsToSpeed;
 exports.normalizeUrl = normalizeUrl;
 exports.parseResult = parseResult;
 exports.path_to_url = path_to_url;
@@ -2445,7 +2566,10 @@ exports.safeMultiply = safeMultiply;
 exports.safeNums = safeNums;
 exports.safeStorage = safeStorage;
 exports.sanitizeFilename = sanitizeFilename;
+exports.secondsToTime = secondsToTime;
+exports.speedToMps = speedToMps;
 exports.stripPrefixes = stripPrefixes;
+exports.timeToSeconds = timeToSeconds;
 exports.toMeters = toMeters;
 exports.toSeconds = toSeconds;
 exports.truncateString = truncateString;