@lichens-innovation/ts-common 1.6.2 → 1.7.0

package/dist/index.d.cts

@@ -0,0 +1,232 @@
+interface ToleranceArea {
+    flow: number;
+    toleranceRange: [number, number];
+}
+/**
+ * A chart point with required x and y coordinates.
+ */
+interface ChartPoint {
+    x: number;
+    y: number;
+}
+/**
+ * A chart point with optional nullable x and y coordinates.
+ */
+interface NullableChartPoint {
+    x?: number | null;
+    y?: number | null;
+}
+declare const getTickDomain: (ticks: number[]) => [number, number];
+declare const tickFormatter: (value: number) => string;
+declare const toToleranceLabel: (value: number) => string;
+declare const tooltipValueFormatter: (data?: unknown | null) => string;
+/**
+ * Rounds a raw value to a "nice" number for chart axis increments.
+ * Nice numbers are easy to read: 1, 2, 2.5, 5, or 10 multiplied by a power of 10.
+ *
+ * @param rawValue - The raw value to round to a nice number
+ * @returns A nice number close to the raw value
+ *
+ * @example
+ * roundToNiceNumber(0.7)  // returns 1
+ * roundToNiceNumber(3)    // returns 5
+ * roundToNiceNumber(17)   // returns 20
+ * roundToNiceNumber(80)   // returns 100
+ */
+declare const roundToNiceNumber: (rawValue: number) => number;
+/**
+ * Builds an array of "nice" tick values for a chart axis.
+ * The algorithm aims for approximately `targetTickCount` ticks with clean, readable values.
+ *
+ * @param max - The maximum value to display on the axis
+ * @param targetTickCount - The desired number of ticks (default: 10)
+ * @returns An array of tick values from 0 to at least `max`
+ */
+declare const buildTicksForChart: (max: number, targetTickCount?: number) => number[];
+
+interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+interface RgbaColor extends RgbColor {
+    a: number;
+}
+declare const rgbToHex: (r: number, g: number, b: number) => string;
+declare const hexToRgb: (hex: string) => RgbColor;
+declare const rgbaToHex: (color: RgbaColor) => string;
+declare const getOpacityHexValue: (opacity: number) => string;
+declare const rgbaToHexWithAlpha: (color: RgbaColor) => string;
+declare const rgbToString: (color: RgbColor) => string;
+declare const rgbaToString: (color: RgbaColor) => string;
+declare const getLuminance: (r: number, g: number, b: number) => number;
+declare const getContrastTextColor: (hexColor: string) => string;
+/**
+ * Normalized RGB color with values between 0 and 1.
+ * Useful for graphics libraries like Three.js.
+ */
+interface NormalizedRgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Convert a hex color string to normalized RGB values (0-1 range).
+ * @param hex - Hex color string (with or without # prefix)
+ * @returns Normalized RGB object with values between 0 and 1
+ */
+declare const hexToNormalizedRgb: (hex: string) => NormalizedRgb;
+/**
+ * Determine if a color is light or dark based on relative luminance.
+ * Useful for choosing contrasting text colors.
+ * @param hex - Hex color string
+ * @returns True if the color is considered light (luminance > 0.5)
+ */
+declare const isLightColor: (hex: string) => boolean;
+declare const getColorForPercentage: (percent: number) => string;
+
+type DateInput = Date | string | number | null;
+declare const dateAs_HHMMSS: (value?: DateInput) => string;
+declare const dateAs_YYYYMMDD: (value?: DateInput) => string;
+declare const dateAs_YYYYMMDD_HHMMSS: (value?: DateInput) => string;
+declare const nowAsTime: () => string;
+declare const nowAsDate: () => string;
+declare const nowAsDateTime: () => string;
+declare const nowAsDateTimeForFilename: () => string;
+/**
+ * Format a Unix timestamp (seconds since epoch) to a human-readable string.
+ * @param timestamp - Unix timestamp in seconds
+ * @param dateFormat - Date format string (default: "yyyy-MM-dd HH:mm:ss")
+ * @returns Formatted date string or "N/A" if invalid or zero.
+ */
+declare const formatUnixTimestamp: (timestamp: number, dateFormat?: string) => string;
+/**
+ * Get the current Unix timestamp in seconds.
+ * @returns Current Unix timestamp
+ */
+declare const getCurrentUnixTimestamp: () => number;
+/**
+ * Check if a Unix timestamp has expired (is in the past).
+ * @param timestamp - Unix timestamp in seconds
+ * @returns True if the timestamp is in the past
+ */
+declare const isExpiredTimestamp: (timestamp: number) => boolean;
+/**
+ * Check if a Unix timestamp is active (current or past).
+ * @param timestamp - Unix timestamp in seconds
+ * @returns True if the timestamp is current or in the past
+ */
+declare const isActiveTimestamp: (timestamp: number) => boolean;
+
+interface Dimensions {
+    width: number;
+    height: number;
+}
+
+declare const getErrorMessage: (error: unknown) => string;
+
+declare const isHttpSuccessStatus: (status?: number | null) => boolean;
+declare const isHttpClientErrorStatus: (status?: number | null) => boolean;
+declare const isHttpServerErrorStatus: (status?: number | null) => boolean;
+
+declare const toFixed: (value?: number | null, decimals?: number) => number;
+declare const roundUpToNearest10: (value?: number | null) => number;
+declare const getOrderOfMagnitudeExponent: (n?: number | null) => number;
+
+declare const REGEX_ALPHANUMERIC: RegExp;
+declare const REGEX_IPV4: RegExp;
+
+declare const isBlank: (str?: string | null) => str is null | undefined | "";
+declare const isNotBlank: (str?: string | null) => str is string;
+declare const isAlphanumeric: (value: string) => boolean;
+/**
+ * Removes diacritical marks (e.g., accents, umlauts) from a string.
+ * This method normalizes the input string to its canonical decomposition
+ * form (NFD) and removes any combining diacritical marks.
+ *
+ * @param {string} value - The input string to normalize.
+ * @returns {string} - The normalized string with diacritical marks removed.
+ *
+ * @example
+ * const result = removeDiacriticalMarks("Ça va très bien, n'est-ce pas?");
+ * console.log(result); // "Ca va tres bien, n'est-ce pas?"
+ */
+declare const removeDiacriticalMarks: (value: string) => string;
+/**
+ * Capitalize the first letter of a string.
+ * @param str - The input string
+ * @returns The string with the first character uppercased
+ */
+declare const capitalizeFirst: (str: string) => string;
+/**
+ * Count the number of words in a text string.
+ * Words are separated by whitespace.
+ * @param text - The text to count words in
+ * @returns The number of words found
+ */
+declare const countWords: (text: string) => number;
+/**
+ * Truncate a string to a maximum length, adding an ellipsis if truncated.
+ * @param str - The string to truncate
+ * @param maxLength - Maximum length before truncation
+ * @param ellipsis - The ellipsis string to append (default: "...")
+ * @returns The truncated string
+ */
+declare const truncate: (str: string, maxLength: number, ellipsis?: string) => string;
+
+declare const sleep: (milliseconds: number) => Promise<unknown>;
+
+declare const PeriodsInMS: {
+    readonly oneSecond: 1000;
+    readonly oneMinute: number;
+    readonly oneHour: number;
+    readonly oneDay: number;
+};
+
+declare const NO_OP: () => void;
+declare const isNullish: (value: unknown) => value is null | undefined;
+declare const isNumber: (value?: unknown | null) => value is number;
+declare const isString: (value?: unknown | null) => value is string;
+
+/** m³/s to gallons per minute */
+declare const M3PS_TO_GPM = 15850.3;
+/** Pascals to feet of head (1 Pa = 1 N/m²) */
+declare const PA_TO_FT = 0.000334553;
+/** Watts to Horsepower */
+declare const W_TO_HP = 0.00134102;
+/** meters to inches */
+declare const M_TO_INCHES = 39.3701;
+/** Hz to RPM (for synchronous speed) */
+declare const HZ_TO_RPM = 60;
+declare const fromM3psToGPM: (value?: number | null) => number;
+declare const fromPaToFt: (value?: number | null) => number;
+declare const fromWToHp: (value?: number | null) => number;
+declare const fromMToInches: (value?: number | null) => number;
+declare const fromHzToRpm: (value?: number | null) => number;
+
+declare const SCHEME_PREFIXES: {
+    readonly file: "file";
+    readonly content: "content";
+    readonly http: "http";
+    readonly https: "https";
+    readonly ftp: "ftp";
+    readonly ftps: "ftps";
+    readonly sftp: "sftp";
+    readonly smb: "smb";
+};
+declare const hasScheme: (uri?: string | null) => boolean;
+/**
+ * Extracts the base64 data from a data URI string.
+ * Data URIs have the format: data:[<mediatype>][;base64],<data>
+ * This function extracts everything after the first comma.
+ *
+ * @param dataUri - The data URI string (e.g., "data:image/png;base64,iVBORw0KG...")
+ * @returns The base64 data without the data URI prefix, or the original string if no comma is found
+ */
+declare const extractBase64FromDataUri: (dataUri: string) => string;
+
+declare const isWsClosable: (ws?: WebSocket | null) => ws is WebSocket;
+declare const isWsOpenOrConnecting: (ws?: WebSocket | null) => ws is WebSocket;
+declare const closeWebSocket: (ws?: WebSocket | null) => void;
+
+export { type ChartPoint, type DateInput, type Dimensions, HZ_TO_RPM, M3PS_TO_GPM, M_TO_INCHES, NO_OP, type NormalizedRgb, type NullableChartPoint, PA_TO_FT, PeriodsInMS, REGEX_ALPHANUMERIC, REGEX_IPV4, type RgbColor, type RgbaColor, SCHEME_PREFIXES, type ToleranceArea, W_TO_HP, buildTicksForChart, capitalizeFirst, closeWebSocket, countWords, dateAs_HHMMSS, dateAs_YYYYMMDD, dateAs_YYYYMMDD_HHMMSS, extractBase64FromDataUri, formatUnixTimestamp, fromHzToRpm, fromM3psToGPM, fromMToInches, fromPaToFt, fromWToHp, getColorForPercentage, getContrastTextColor, getCurrentUnixTimestamp, getErrorMessage, getLuminance, getOpacityHexValue, getOrderOfMagnitudeExponent, getTickDomain, hasScheme, hexToNormalizedRgb, hexToRgb, isActiveTimestamp, isAlphanumeric, isBlank, isExpiredTimestamp, isHttpClientErrorStatus, isHttpServerErrorStatus, isHttpSuccessStatus, isLightColor, isNotBlank, isNullish, isNumber, isString, isWsClosable, isWsOpenOrConnecting, nowAsDate, nowAsDateTime, nowAsDateTimeForFilename, nowAsTime, removeDiacriticalMarks, rgbToHex, rgbToString, rgbaToHex, rgbaToHexWithAlpha, rgbaToString, roundToNiceNumber, roundUpToNearest10, sleep, tickFormatter, toFixed, toToleranceLabel, tooltipValueFormatter, truncate };

package/dist/index.d.ts

@@ -1,2 +1,232 @@
-export * from "./utils";
-//# sourceMappingURL=index.d.ts.map
+interface ToleranceArea {
+    flow: number;
+    toleranceRange: [number, number];
+}
+/**
+ * A chart point with required x and y coordinates.
+ */
+interface ChartPoint {
+    x: number;
+    y: number;
+}
+/**
+ * A chart point with optional nullable x and y coordinates.
+ */
+interface NullableChartPoint {
+    x?: number | null;
+    y?: number | null;
+}
+declare const getTickDomain: (ticks: number[]) => [number, number];
+declare const tickFormatter: (value: number) => string;
+declare const toToleranceLabel: (value: number) => string;
+declare const tooltipValueFormatter: (data?: unknown | null) => string;
+/**
+ * Rounds a raw value to a "nice" number for chart axis increments.
+ * Nice numbers are easy to read: 1, 2, 2.5, 5, or 10 multiplied by a power of 10.
+ *
+ * @param rawValue - The raw value to round to a nice number
+ * @returns A nice number close to the raw value
+ *
+ * @example
+ * roundToNiceNumber(0.7)  // returns 1
+ * roundToNiceNumber(3)    // returns 5
+ * roundToNiceNumber(17)   // returns 20
+ * roundToNiceNumber(80)   // returns 100
+ */
+declare const roundToNiceNumber: (rawValue: number) => number;
+/**
+ * Builds an array of "nice" tick values for a chart axis.
+ * The algorithm aims for approximately `targetTickCount` ticks with clean, readable values.
+ *
+ * @param max - The maximum value to display on the axis
+ * @param targetTickCount - The desired number of ticks (default: 10)
+ * @returns An array of tick values from 0 to at least `max`
+ */
+declare const buildTicksForChart: (max: number, targetTickCount?: number) => number[];
+
+interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+interface RgbaColor extends RgbColor {
+    a: number;
+}
+declare const rgbToHex: (r: number, g: number, b: number) => string;
+declare const hexToRgb: (hex: string) => RgbColor;
+declare const rgbaToHex: (color: RgbaColor) => string;
+declare const getOpacityHexValue: (opacity: number) => string;
+declare const rgbaToHexWithAlpha: (color: RgbaColor) => string;
+declare const rgbToString: (color: RgbColor) => string;
+declare const rgbaToString: (color: RgbaColor) => string;
+declare const getLuminance: (r: number, g: number, b: number) => number;
+declare const getContrastTextColor: (hexColor: string) => string;
+/**
+ * Normalized RGB color with values between 0 and 1.
+ * Useful for graphics libraries like Three.js.
+ */
+interface NormalizedRgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Convert a hex color string to normalized RGB values (0-1 range).
+ * @param hex - Hex color string (with or without # prefix)
+ * @returns Normalized RGB object with values between 0 and 1
+ */
+declare const hexToNormalizedRgb: (hex: string) => NormalizedRgb;
+/**
+ * Determine if a color is light or dark based on relative luminance.
+ * Useful for choosing contrasting text colors.
+ * @param hex - Hex color string
+ * @returns True if the color is considered light (luminance > 0.5)
+ */
+declare const isLightColor: (hex: string) => boolean;
+declare const getColorForPercentage: (percent: number) => string;
+
+type DateInput = Date | string | number | null;
+declare const dateAs_HHMMSS: (value?: DateInput) => string;
+declare const dateAs_YYYYMMDD: (value?: DateInput) => string;
+declare const dateAs_YYYYMMDD_HHMMSS: (value?: DateInput) => string;
+declare const nowAsTime: () => string;
+declare const nowAsDate: () => string;
+declare const nowAsDateTime: () => string;
+declare const nowAsDateTimeForFilename: () => string;
+/**
+ * Format a Unix timestamp (seconds since epoch) to a human-readable string.
+ * @param timestamp - Unix timestamp in seconds
+ * @param dateFormat - Date format string (default: "yyyy-MM-dd HH:mm:ss")
+ * @returns Formatted date string or "N/A" if invalid or zero.
+ */
+declare const formatUnixTimestamp: (timestamp: number, dateFormat?: string) => string;
+/**
+ * Get the current Unix timestamp in seconds.
+ * @returns Current Unix timestamp
+ */
+declare const getCurrentUnixTimestamp: () => number;
+/**
+ * Check if a Unix timestamp has expired (is in the past).
+ * @param timestamp - Unix timestamp in seconds
+ * @returns True if the timestamp is in the past
+ */
+declare const isExpiredTimestamp: (timestamp: number) => boolean;
+/**
+ * Check if a Unix timestamp is active (current or past).
+ * @param timestamp - Unix timestamp in seconds
+ * @returns True if the timestamp is current or in the past
+ */
+declare const isActiveTimestamp: (timestamp: number) => boolean;
+
+interface Dimensions {
+    width: number;
+    height: number;
+}
+
+declare const getErrorMessage: (error: unknown) => string;
+
+declare const isHttpSuccessStatus: (status?: number | null) => boolean;
+declare const isHttpClientErrorStatus: (status?: number | null) => boolean;
+declare const isHttpServerErrorStatus: (status?: number | null) => boolean;
+
+declare const toFixed: (value?: number | null, decimals?: number) => number;
+declare const roundUpToNearest10: (value?: number | null) => number;
+declare const getOrderOfMagnitudeExponent: (n?: number | null) => number;
+
+declare const REGEX_ALPHANUMERIC: RegExp;
+declare const REGEX_IPV4: RegExp;
+
+declare const isBlank: (str?: string | null) => str is null | undefined | "";
+declare const isNotBlank: (str?: string | null) => str is string;
+declare const isAlphanumeric: (value: string) => boolean;
+/**
+ * Removes diacritical marks (e.g., accents, umlauts) from a string.
+ * This method normalizes the input string to its canonical decomposition
+ * form (NFD) and removes any combining diacritical marks.
+ *
+ * @param {string} value - The input string to normalize.
+ * @returns {string} - The normalized string with diacritical marks removed.
+ *
+ * @example
+ * const result = removeDiacriticalMarks("Ça va très bien, n'est-ce pas?");
+ * console.log(result); // "Ca va tres bien, n'est-ce pas?"
+ */
+declare const removeDiacriticalMarks: (value: string) => string;
+/**
+ * Capitalize the first letter of a string.
+ * @param str - The input string
+ * @returns The string with the first character uppercased
+ */
+declare const capitalizeFirst: (str: string) => string;
+/**
+ * Count the number of words in a text string.
+ * Words are separated by whitespace.
+ * @param text - The text to count words in
+ * @returns The number of words found
+ */
+declare const countWords: (text: string) => number;
+/**
+ * Truncate a string to a maximum length, adding an ellipsis if truncated.
+ * @param str - The string to truncate
+ * @param maxLength - Maximum length before truncation
+ * @param ellipsis - The ellipsis string to append (default: "...")
+ * @returns The truncated string
+ */
+declare const truncate: (str: string, maxLength: number, ellipsis?: string) => string;
+
+declare const sleep: (milliseconds: number) => Promise<unknown>;
+
+declare const PeriodsInMS: {
+    readonly oneSecond: 1000;
+    readonly oneMinute: number;
+    readonly oneHour: number;
+    readonly oneDay: number;
+};
+
+declare const NO_OP: () => void;
+declare const isNullish: (value: unknown) => value is null | undefined;
+declare const isNumber: (value?: unknown | null) => value is number;
+declare const isString: (value?: unknown | null) => value is string;
+
+/** m³/s to gallons per minute */
+declare const M3PS_TO_GPM = 15850.3;
+/** Pascals to feet of head (1 Pa = 1 N/m²) */
+declare const PA_TO_FT = 0.000334553;
+/** Watts to Horsepower */
+declare const W_TO_HP = 0.00134102;
+/** meters to inches */
+declare const M_TO_INCHES = 39.3701;
+/** Hz to RPM (for synchronous speed) */
+declare const HZ_TO_RPM = 60;
+declare const fromM3psToGPM: (value?: number | null) => number;
+declare const fromPaToFt: (value?: number | null) => number;
+declare const fromWToHp: (value?: number | null) => number;
+declare const fromMToInches: (value?: number | null) => number;
+declare const fromHzToRpm: (value?: number | null) => number;
+
+declare const SCHEME_PREFIXES: {
+    readonly file: "file";
+    readonly content: "content";
+    readonly http: "http";
+    readonly https: "https";
+    readonly ftp: "ftp";
+    readonly ftps: "ftps";
+    readonly sftp: "sftp";
+    readonly smb: "smb";
+};
+declare const hasScheme: (uri?: string | null) => boolean;
+/**
+ * Extracts the base64 data from a data URI string.
+ * Data URIs have the format: data:[<mediatype>][;base64],<data>
+ * This function extracts everything after the first comma.
+ *
+ * @param dataUri - The data URI string (e.g., "data:image/png;base64,iVBORw0KG...")
+ * @returns The base64 data without the data URI prefix, or the original string if no comma is found
+ */
+declare const extractBase64FromDataUri: (dataUri: string) => string;
+
+declare const isWsClosable: (ws?: WebSocket | null) => ws is WebSocket;
+declare const isWsOpenOrConnecting: (ws?: WebSocket | null) => ws is WebSocket;
+declare const closeWebSocket: (ws?: WebSocket | null) => void;
+
+export { type ChartPoint, type DateInput, type Dimensions, HZ_TO_RPM, M3PS_TO_GPM, M_TO_INCHES, NO_OP, type NormalizedRgb, type NullableChartPoint, PA_TO_FT, PeriodsInMS, REGEX_ALPHANUMERIC, REGEX_IPV4, type RgbColor, type RgbaColor, SCHEME_PREFIXES, type ToleranceArea, W_TO_HP, buildTicksForChart, capitalizeFirst, closeWebSocket, countWords, dateAs_HHMMSS, dateAs_YYYYMMDD, dateAs_YYYYMMDD_HHMMSS, extractBase64FromDataUri, formatUnixTimestamp, fromHzToRpm, fromM3psToGPM, fromMToInches, fromPaToFt, fromWToHp, getColorForPercentage, getContrastTextColor, getCurrentUnixTimestamp, getErrorMessage, getLuminance, getOpacityHexValue, getOrderOfMagnitudeExponent, getTickDomain, hasScheme, hexToNormalizedRgb, hexToRgb, isActiveTimestamp, isAlphanumeric, isBlank, isExpiredTimestamp, isHttpClientErrorStatus, isHttpServerErrorStatus, isHttpSuccessStatus, isLightColor, isNotBlank, isNullish, isNumber, isString, isWsClosable, isWsOpenOrConnecting, nowAsDate, nowAsDateTime, nowAsDateTimeForFilename, nowAsTime, removeDiacriticalMarks, rgbToHex, rgbToString, rgbaToHex, rgbaToHexWithAlpha, rgbaToString, roundToNiceNumber, roundUpToNearest10, sleep, tickFormatter, toFixed, toToleranceLabel, tooltipValueFormatter, truncate };