@getdashfy/utils 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# `@getdashfy/utils`
+
+> Formatting and utility functions for Dashfy - numbers, currencies, bytes, dates, times, strings, platform detection, and more.
+
+## Introduction
+
+`@getdashfy/utils` provides formatting and utility functions for Dashfy dashboards. It includes:
+
+- **Format** - A flexible format API inspired by [Numeral.js](https://numeraljs.com) for numbers, dates, times, bytes, and more
+- **Error** - Safe error message extraction
+- **Function** - Utilities for common patterns
+- **Object** - Safe nested property access
+- **Platform** - Environment detection and OS helpers
+- **String** - String manipulation and display helpers
+- **Libs** - Re-export of [date-fns](https://date-fns.org)
+
+## Install
+
+Install with your favorite package manager:
+
+#### `npm`
+
+```bash
+npm install @getdashfy/utils
+```
+
+#### `pnpm`
+
+```bash
+pnpm add @getdashfy/utils
+```
+
+#### `yarn`
+
+```bash
+yarn add @getdashfy/utils
+```
+
+#### `bun`
+
+```bash
+bun add @getdashfy/utils
+```
+
+## Quick Start
+
+```ts
+import { format, debounce, get, truncate, isClient } from '@getdashfy/utils'
+
+// Format numbers with thousands separators
+format(1000, '0,0')
+// '1,000'
+
+// Format compact notation
+format(1500000, '0.0a')
+// '1.5M'
+
+// Format relative dates
+format(new Date(), 'relative')
+// 'less than a minute ago'
+
+// Safely access nested object properties
+get({ user: { name: 'John' } }, 'user.name')
+// 'John'
+
+// Truncate a long string
+truncate('This is a long title that needs trimming', 20)
+// 'This is a long title...'
+
+// Debounce a function call
+const debouncedSearch = debounce((query: string) => fetchResults(query), 300)
+
+// Check execution environment
+isClient // true in browser
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Watch mode
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+
+# Type check
+pnpm typecheck
+```
+
+## Community
+
+Join the community on [Dashfy's Discord server](https://dashfy.dev/discord) to discuss the project, ask questions, or get help.
+
+Join the conversation on X (Twitter) and follow [@dashfydev](https://x.com/dashfydev) for updates and announcements.
+
+## License
+
+This project is licensed under the AGPL-3.0 License - see the [LICENSE](./LICENSE) file for details.

package/dist/index.cjs

@@ -0,0 +1,497 @@
+'use strict';
+
+var dateFns = require('date-fns');
+var prettyBytes = require('pretty-bytes');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var dateFns__namespace = /*#__PURE__*/_interopNamespace(dateFns);
+var prettyBytes__default = /*#__PURE__*/_interopDefault(prettyBytes);
+
+// src/index.ts
+
+// src/error/error.ts
+function isErrorWithMessage(error) {
+  return typeof error === "object" && error !== null && "message" in error && typeof error.message === "string";
+}
+function toErrorWithMessage(maybeError) {
+  if (isErrorWithMessage(maybeError)) {
+    return maybeError;
+  }
+  try {
+    return new Error(JSON.stringify(maybeError));
+  } catch {
+    return new Error(String(maybeError));
+  }
+}
+function getErrorMessage(error) {
+  return toErrorWithMessage(error).message;
+}
+
+// src/format/core.ts
+var defaultLocale;
+function setDefaultLocale(locale) {
+  defaultLocale = locale;
+}
+function getDefaultLocale() {
+  return defaultLocale;
+}
+function resolveLocale(options) {
+  return options?.locale ?? defaultLocale;
+}
+function handleZeroNull(value, options, formatFn) {
+  if (value === null || value === void 0) {
+    if (options?.nullFormat !== void 0) {
+      return options.nullFormat;
+    }
+    return null;
+  }
+  if (typeof value === "number" && value === 0 && options?.zeroFormat !== void 0) {
+    return options.zeroFormat;
+  }
+  return formatFn(value);
+}
+
+// src/format/bytes.ts
+function formatBytes(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const byteCount = typeof valueToFormat === "bigint" ? Number(valueToFormat) : valueToFormat;
+    const locale = resolveLocale(options);
+    return prettyBytes__default.default(byteCount, {
+      binary: options?.binary,
+      bits: options?.bits,
+      signed: options?.signed,
+      locale: locale ? Array.isArray(locale) ? locale[0] : locale : false,
+      minimumFractionDigits: options?.minimumFractionDigits,
+      maximumFractionDigits: options?.maximumFractionDigits
+    });
+  });
+  const fallbackValue = value === null || value === void 0 ? 0 : typeof value === "bigint" ? Number(value) : value;
+  return result ?? prettyBytes__default.default(fallbackValue);
+}
+function formatBytesPerSecond(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const byteCount = typeof valueToFormat === "bigint" ? Number(valueToFormat) : valueToFormat;
+    const locale = resolveLocale(options);
+    return `${prettyBytes__default.default(byteCount, {
+      binary: options?.binary,
+      bits: options?.bits,
+      signed: options?.signed,
+      locale: locale ? Array.isArray(locale) ? locale[0] : locale : false,
+      minimumFractionDigits: options?.minimumFractionDigits,
+      maximumFractionDigits: options?.maximumFractionDigits
+    })}/s`;
+  });
+  const fallbackValue = value === null || value === void 0 ? 0 : typeof value === "bigint" ? Number(value) : value;
+  return result ?? `${prettyBytes__default.default(fallbackValue)}/s`;
+}
+
+// src/format/currency.ts
+function formatCurrency(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const locale = resolveLocale(options);
+    const formatOptions = {
+      style: "currency",
+      currency: options?.currency ?? "USD",
+      minimumFractionDigits: options?.minimumFractionDigits,
+      maximumFractionDigits: options?.maximumFractionDigits ?? 2
+    };
+    return new Intl.NumberFormat(locale, formatOptions).format(valueToFormat);
+  });
+  const fallbackResult = new Intl.NumberFormat(resolveLocale(options), {
+    style: "currency",
+    currency: options?.currency ?? "USD"
+  }).format(value);
+  return result ?? fallbackResult;
+}
+function formatDate(value, options) {
+  const date = value instanceof Date ? value : typeof value === "number" ? new Date(value * 1e3) : new Date(value);
+  const pattern = options?.format ?? "MMM d, yyyy";
+  return dateFns.format(date, pattern);
+}
+function formatRelativeTime(value, options) {
+  const date = value instanceof Date ? value : typeof value === "number" ? new Date(value * 1e3) : new Date(value);
+  return dateFns.formatDistanceToNow(date, { addSuffix: options?.addSuffix ?? true });
+}
+
+// src/format/exponential.ts
+function formatExponential(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const locale = resolveLocale(options);
+    const formatOptions = {
+      notation: "scientific",
+      minimumFractionDigits: options?.minimumFractionDigits,
+      maximumFractionDigits: options?.maximumFractionDigits ?? 2
+    };
+    return new Intl.NumberFormat(locale, formatOptions).format(valueToFormat);
+  });
+  const fallbackResult = new Intl.NumberFormat(resolveLocale(options), {
+    notation: "scientific"
+  }).format(value);
+  return result ?? fallbackResult;
+}
+
+// src/format/list.ts
+function formatList(items, options) {
+  if (items.length === 0) {
+    return "";
+  }
+  const locale = resolveLocale(options);
+  return new Intl.ListFormat(locale, {
+    type: options?.type ?? "conjunction",
+    style: options?.style ?? "long"
+  }).format(items);
+}
+
+// src/format/number.ts
+function formatNumber(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const locale = resolveLocale(options);
+    const opts = {
+      minimumFractionDigits: options?.minimumFractionDigits,
+      maximumFractionDigits: options?.maximumFractionDigits ?? (valueToFormat % 1 === 0 ? 0 : 2),
+      ...options?.notation && { notation: options.notation },
+      ...options?.compactDisplay && { compactDisplay: options.compactDisplay }
+    };
+    return new Intl.NumberFormat(locale, opts).format(valueToFormat);
+  });
+  const fallbackResult = new Intl.NumberFormat(resolveLocale(options)).format(value);
+  return result ?? fallbackResult;
+}
+
+// src/format/ordinal.ts
+function formatOrdinal(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const locale = resolveLocale(options);
+    const roundedValue = Math.round(valueToFormat);
+    const intl = new Intl.NumberFormat(locale, {
+      minimumFractionDigits: options?.minimumFractionDigits,
+      maximumFractionDigits: options?.maximumFractionDigits ?? 0
+    });
+    const ord = typeof Intl.PluralRules !== "undefined" ? new Intl.PluralRules(locale, { type: "ordinal" }).select(roundedValue) : "other";
+    const suffixes = {
+      one: "st",
+      two: "nd",
+      few: "rd",
+      other: "th"
+    };
+    return `${intl.format(roundedValue)}${suffixes[ord] ?? "th"}`;
+  });
+  return result ?? `${value}th`;
+}
+
+// src/format/percent.ts
+function formatPercent(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const toFormat = options?.scaleBy100 !== false ? valueToFormat : valueToFormat / 100;
+    const locale = resolveLocale(options);
+    const opts = {
+      style: "percent",
+      minimumFractionDigits: options?.minimumFractionDigits,
+      maximumFractionDigits: options?.maximumFractionDigits ?? 0
+    };
+    return new Intl.NumberFormat(locale, opts).format(toFormat);
+  });
+  const fallbackResult = new Intl.NumberFormat(resolveLocale(options), { style: "percent" }).format(
+    value
+  );
+  return result ?? fallbackResult;
+}
+
+// src/format/temperature.ts
+function formatTemperature(value, options) {
+  const result = handleZeroNull(value, options, (valueToFormat) => {
+    const locale = resolveLocale(options);
+    const unit = options?.unit ?? "celsius";
+    const maxFrac = options?.maximumFractionDigits ?? 0;
+    const minFrac = options?.minimumFractionDigits;
+    if (unit === "kelvin") {
+      const opts2 = {
+        minimumFractionDigits: minFrac,
+        maximumFractionDigits: maxFrac
+      };
+      return `${new Intl.NumberFormat(locale, opts2).format(valueToFormat)} K`;
+    }
+    const unitKey = unit === "celsius" ? "celsius" : "fahrenheit";
+    const opts = {
+      style: "unit",
+      unit: unitKey,
+      minimumFractionDigits: minFrac,
+      maximumFractionDigits: maxFrac
+    };
+    return new Intl.NumberFormat(locale, opts).format(valueToFormat);
+  });
+  const fallbackResult = new Intl.NumberFormat(resolveLocale(options), {
+    style: "unit",
+    unit: "celsius"
+  }).format(value);
+  return result ?? fallbackResult;
+}
+function formatTime(seconds, options) {
+  const result = handleZeroNull(seconds, options, (secondsToFormat) => {
+    if (options?.style === "long" || options?.style === void 0) {
+      const duration = dateFns.intervalToDuration({ start: 0, end: secondsToFormat * 1e3 });
+      const formatted = dateFns.formatDuration(duration, {
+        format: options?.includeSeconds !== false ? ["hours", "minutes", "seconds"] : ["hours", "minutes"]
+      });
+      return formatted || "0 seconds";
+    }
+    const h = Math.floor(secondsToFormat / 3600);
+    const m = Math.floor((secondsToFormat - h * 3600) / 60);
+    const sec = Math.round(secondsToFormat - h * 3600 - m * 60);
+    const pad = (value) => value < 10 ? `0${value}` : String(value);
+    return `${pad(h)}:${pad(m)}:${pad(sec)}`;
+  });
+  return result ?? "0:00:00";
+}
+function formatTimeCompact(seconds, options) {
+  const result = handleZeroNull(seconds, options, (secondsToFormat) => {
+    const days = Math.floor(secondsToFormat / 86400);
+    const hours = Math.floor(secondsToFormat % 86400 / 3600);
+    const minutes = Math.floor(secondsToFormat % 3600 / 60);
+    const parts = [];
+    if (days > 0) {
+      parts.push(`${days}d`);
+    }
+    if (hours > 0) {
+      parts.push(`${hours}h`);
+    }
+    if (minutes > 0) {
+      parts.push(`${minutes}m`);
+    }
+    return parts.length > 0 ? parts.join(" ") : "0m";
+  });
+  return result ?? "0m";
+}
+
+// src/format/format.ts
+function format(value, formatString, options) {
+  if (value === null || value === void 0) {
+    if (options?.nullFormat !== void 0) {
+      return options.nullFormat;
+    }
+    return "";
+  }
+  const str = formatString.trim().toLowerCase();
+  if (str === "ordinal" || str === "0o") {
+    return formatOrdinal(Number(value), options);
+  }
+  if (str === "relative") {
+    const date = value instanceof Date ? value : typeof value === "number" ? new Date(value * 1e3) : new Date(value);
+    return formatRelativeTime(date, { ...options, addSuffix: true });
+  }
+  if (str === "list") {
+    return formatList(value, options);
+  }
+  if (str === "exponential" || str === "0.00e+0" || /e[+-]/.test(str)) {
+    return formatExponential(Number(value), options);
+  }
+  if (/\$|currency/.test(str)) {
+    const currency = str.includes("\u20AC") ? "EUR" : str.includes("\xA3") ? "GBP" : "USD";
+    return formatCurrency(Number(value), { ...options, currency });
+  }
+  if (/%|percent/.test(str)) {
+    const decimals2 = /\.(0+)/.exec(str)?.[1]?.length ?? 0;
+    return formatPercent(Number(value), {
+      ...options,
+      maximumFractionDigits: decimals2
+    });
+  }
+  if (str === "bps" || str.endsWith("/s")) {
+    const binary = str.includes("ib");
+    return formatBytesPerSecond(typeof value === "bigint" ? value : Number(value), {
+      ...options,
+      binary
+    });
+  }
+  if (/0\s?i?b|bytes/.test(str)) {
+    const binary = str.includes("ib");
+    return formatBytes(typeof value === "bigint" ? value : Number(value), {
+      ...options,
+      binary
+    });
+  }
+  if (str === "uptime" && typeof value === "number") {
+    return formatTimeCompact(value, options);
+  }
+  if ((str === "time" || str === "duration") && typeof value === "number") {
+    return formatTime(value, { ...options, style: "long" });
+  }
+  if (/[:]/.test(str) && typeof value === "number") {
+    return formatTime(value, { ...options, style: "short" });
+  }
+  if (/temp|°|celsius|fahrenheit|kelvin/.test(str)) {
+    const unit = str.includes("f") ? "fahrenheit" : str.includes("k") ? "kelvin" : "celsius";
+    return formatTemperature(Number(value), { ...options, unit });
+  }
+  if (/date|short|long|iso/.test(str)) {
+    const date = value instanceof Date ? value : typeof value === "number" ? new Date(value * 1e3) : new Date(value);
+    if (str === "short") {
+      return formatDate(date, { ...options, format: "MMM d" });
+    }
+    if (str === "long") {
+      return formatDate(date, { ...options, format: "MMMM d, yyyy" });
+    }
+    if (str === "iso") {
+      return formatDate(date, { ...options, format: "yyyy-MM-dd'T'HH:mm:ss" });
+    }
+    return formatDate(date, options);
+  }
+  const num = typeof value === "number" ? value : typeof value === "bigint" ? Number(value) : Number.parseFloat(String(value));
+  if (Number.isNaN(num)) {
+    return options?.nullFormat ?? "";
+  }
+  const decimals = /\.(0+)/.exec(str)?.[1]?.length ?? 0;
+  const compact = /a|abbrev/.test(str);
+  if (compact) {
+    return formatNumber(num, {
+      ...options,
+      notation: "compact",
+      compactDisplay: str.includes(" ") ? "long" : "short",
+      maximumFractionDigits: decimals || 1
+    });
+  }
+  return formatNumber(num, {
+    ...options,
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals
+  });
+}
+
+// src/function/debounce.ts
+function debounce(func, wait) {
+  let timeout = null;
+  return function executedFunction(...args) {
+    const later = () => {
+      timeout = null;
+      func(...args);
+    };
+    if (timeout !== null) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(later, wait);
+  };
+}
+
+// src/object/get.ts
+function get(obj, path) {
+  const keys = path.split(".");
+  let result = obj;
+  for (const key of keys) {
+    if (result && typeof result === "object" && key in result) {
+      result = result[key];
+    } else {
+      return void 0;
+    }
+  }
+  return result;
+}
+
+// src/platform/env.ts
+var isDevelopment = process.env.NODE_ENV === "development";
+var isProduction = process.env.NODE_ENV === "production";
+var isTest = process.env.NODE_ENV === "test";
+
+// src/platform/os.ts
+var isMac = typeof navigator !== "undefined" && navigator.platform.toUpperCase().includes("MAC");
+var modKey = isMac ? "\u2318" : "Ctrl";
+
+// src/platform/runtime.ts
+var isClient = typeof window !== "undefined";
+var isServer = typeof window === "undefined";
+
+// src/string/stringifyValue.ts
+function stringifyValue(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
+// src/string/truncate.ts
+function truncate(str, length) {
+  if (str.length <= length) {
+    return str;
+  }
+  return `${str.slice(0, length)}...`;
+}
+
+// src/string/valueToDisplayString.ts
+function valueToDisplayString(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (value === void 0) {
+    return "undefined";
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return `Array(${value.length})`;
+  }
+  if (typeof value === "object") {
+    return `Object(${Object.keys(value).length})`;
+  }
+  return String(value);
+}
+
+exports.dateFns = dateFns__namespace;
+exports.debounce = debounce;
+exports.format = format;
+exports.formatBytes = formatBytes;
+exports.formatBytesPerSecond = formatBytesPerSecond;
+exports.formatCurrency = formatCurrency;
+exports.formatDate = formatDate;
+exports.formatExponential = formatExponential;
+exports.formatList = formatList;
+exports.formatNumber = formatNumber;
+exports.formatOrdinal = formatOrdinal;
+exports.formatPercent = formatPercent;
+exports.formatRelativeTime = formatRelativeTime;
+exports.formatTemperature = formatTemperature;
+exports.formatTime = formatTime;
+exports.formatTimeCompact = formatTimeCompact;
+exports.get = get;
+exports.getDefaultLocale = getDefaultLocale;
+exports.getErrorMessage = getErrorMessage;
+exports.isClient = isClient;
+exports.isDevelopment = isDevelopment;
+exports.isMac = isMac;
+exports.isProduction = isProduction;
+exports.isServer = isServer;
+exports.isTest = isTest;
+exports.modKey = modKey;
+exports.setDefaultLocale = setDefaultLocale;
+exports.stringifyValue = stringifyValue;
+exports.truncate = truncate;
+exports.valueToDisplayString = valueToDisplayString;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map