toolbox-x 1.0.0

package/dist/converter-CmkcAppi.d.cts

@@ -0,0 +1,402 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Hn as Mutable, i as $Record, it as Numeric, zn as LooseLiteral } from "./object-Blq0Amdv.cjs";
+import { t as UNITS } from "./constants-VcRtQu0K.cjs";
+
+//#region src/converter/base.d.ts
+/**
+ * @description Base class providing common mathematical and formatting utilities
+ * for all unit converters (time, length, data, temperature, etc.).
+ */
+declare class $BaseConverter<Unit extends $Unit> {
+  protected readonly value: number;
+  protected readonly unit: Unit;
+  /**
+   * Convert value to other units
+   * @param value Number or numeric string value to convert.
+   * @param unit Optional base unit for the provided value.
+   */
+  constructor(value: Numeric, unit?: Unit);
+  /** @protected Returns a grammatically correct unit string, prefixed with the number value. */
+  protected $withPluralUnit(value?: number, unit?: $Unit): string;
+  /** @protected Rounds a numeric value to given decimal places. */
+  protected $round(value: number, decimals?: number): number;
+  /**
+   * @protected Shared formatter for all converters.
+   * @param value Converted value (already computed via `.to(target)`).
+   * @param target Target unit name.
+   * @param shortLabels Record of compact unit labels.
+   * @param options Formatting options.
+   * @returns Formatted string according to style (compact, plural, scientific).
+   */
+  protected $formatTo(value: number, target: Unit, shortLabels: Record<Unit, string>, options: FormatToOptions | undefined): string;
+  /**
+   * @instance Returns the numeric value.
+   * @returns The raw numeric value without unit.
+   */
+  valueOf(): number;
+  /**
+   * @instance Returns the numeric value.
+   * @returns The raw numeric value without unit.
+   */
+  getValue(): number;
+  /**
+   * @instance Returns the unit name.
+   * @returns The current unit.
+   */
+  getUnit(): Unit;
+  /**
+   * @instance Returns the original value with formatted pluralized unit.
+   * @returns A string like `"3 hours"` or `"1 minute"` or `"3"` if no unit is provided.
+   *
+   * @remarks
+   * - This method is automatically called when the instance is used in a string context.
+   * - For complex and versatile pluralization, please refer to {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/pluralizer pluralizer} or {@link https://toolbox.nazmul-nhb.dev/docs/classes/Pluralizer Pluralizer Class} instead.
+   */
+  toString(): string;
+  /**
+   * @instance Returns a plain object representation.
+   * @returns An object with value and unit.
+   */
+  toObject(): {
+    value: number;
+    unit: Unit;
+  };
+  /**
+   * @instance Converts to JSON representation.
+   * @returns JSON string of `{ value, unit }`.
+   */
+  toJSON(): string;
+  /** @instance Returns a new instance with the absolute value. */
+  abs(): this;
+  /**
+   * @instance Adds a numeric value (same unit assumed).
+   * @returns A new instance with updated value.
+   */
+  add(n: Numeric): this;
+  /**
+   * @instance Subtracts a numeric value (same unit assumed).
+   * @returns A new instance with updated value.
+   */
+  subtract(n: Numeric): this;
+  /**
+   * @instance Multiplies the value.
+   * @returns A new instance with updated value.
+   */
+  multiply(n: Numeric): this;
+  /**
+   * @instance Divides the value.
+   * @returns A new instance with updated value.
+   */
+  divide(n: Numeric): this;
+  /**
+   * @instance Rounds to given decimal places.
+   * @param decimals Number of decimal places to round. Default is `0`.
+   * @returns A new instance with rounded value.
+   */
+  round(decimals?: number): this;
+  /** @instance Returns whether this value is greater than another numeric value. */
+  gt(n: Numeric): boolean;
+  /** @instance Returns whether this value is less than another numeric value. */
+  lt(n: Numeric): boolean;
+  /** @instance Returns whether this value equals another numeric value. */
+  eq(n: Numeric): boolean;
+  /**
+   * @instance Returns a human-friendly formatted string with fixed decimals (if the value is fraction).
+   * @param decimals Number of decimal places for fractional value.
+   * @returns Formatted string with proper unit pluralization.
+   *
+   * @remarks For complex and versatile pluralization, please refer to {@link https://toolbox.nazmul-nhb.dev/docs/utilities/string/pluralizer pluralizer} or {@link https://toolbox.nazmul-nhb.dev/docs/classes/Pluralizer Pluralizer Class} instead.
+   */
+  format(decimals?: number): string;
+  /**
+   * @instance Returns all supported units.
+   * @returns Array of supported unit strings.
+   */
+  supportedUnits(): Units;
+  /**
+   * @instance Returns all supported units for a specific category.
+   * @param category Category to filter units by.
+   * @returns Tuple of supported units for the specified category.
+   */
+  supportedUnits<Cat extends Category>(category: Cat): UnitsTuple<Cat>;
+}
+//#endregion
+//#region src/converter/area.d.ts
+/**
+ * @class AreaConverter
+ * @description Handles conversions with smart `.to()`, `.toAll()`, and `.formatTo()`.
+ */
+declare class $Area extends $BaseConverter<$AreaUnit> {
+  #private;
+  /**
+   * Convert area value to other area units
+   * @param value Number or numeric string value to convert.
+   * @param unit Base area unit for the provided value.
+   */
+  constructor(value: Numeric, unit: $AreaUnit);
+  /**
+   * @instance Converts to target area unit.
+   * @param target Target area unit.
+   */
+  to(target: $AreaUnit): number;
+  /**
+   * @instance Converts to all area units.
+   * @returns Object with all unit conversions.
+   */
+  toAll(): $Record<$AreaUnit, number>;
+  /**
+   * @instance Formats the converted value and unit.
+   * @param target Target unit to format to.
+   * @param options Formatting options.
+   * @returns Formatted string like "5km²", "5.02 square-miles", or "5e+3 meter".
+   */
+  formatTo(target: $AreaUnit, options?: FormatToOptions): string;
+}
+//#endregion
+//#region src/converter/data.d.ts
+/**
+ * @class DataConverter
+ * @description Handles conversions with smart `.to()`, `.toAll()`, and `.formatTo()`.
+ */
+declare class $Data extends $BaseConverter<$DataUnit> {
+  #private;
+  /**
+   * Convert data value to other data units
+   * @param value Number or numeric string value to convert.
+   * @param unit Base data unit for the provided value.
+   */
+  constructor(value: Numeric, unit: $DataUnit);
+  /**
+   * @instance Converts to target data unit.
+   * @param target Target data unit.
+   */
+  to(target: $DataUnit): number;
+  /**
+   * @instance Converts to all data units.
+   * @returns Object with all unit conversions.
+   */
+  toAll(): $Record<$DataUnit, number>;
+  /**
+   * @instance Formats the converted value.
+   * @param target Target data unit.
+   * @param options Formatting options.
+   * @returns Formatted string like "256MB", "256 megabytes", or "2.56e+2 MB".
+   */
+  formatTo(target: $DataUnit, options?: FormatToOptions): string;
+}
+//#endregion
+//#region src/converter/length.d.ts
+/**
+ * @class LengthConverter
+ * @description Handles conversions with smart `.to()`, `.toAll()`, and `.formatTo()`.
+ */
+declare class $Length extends $BaseConverter<$LengthUnit> {
+  #private;
+  /**
+   * Convert length/distance value to other length/distance units
+   * @param value Number or numeric string value to convert.
+   * @param unit Base length/distance unit for the provided value.
+   */
+  constructor(value: Numeric, unit: $LengthUnit);
+  /**
+   * @instance Converts to target length/distance unit.
+   * @param target Target length/distance unit.
+   */
+  to(target: $LengthUnit): number;
+  /**
+   * @instance Converts to all data units.
+   * @returns Object with all unit conversions.
+   */
+  toAll(): $Record<$LengthUnit, number>;
+  /**
+   * @instance Formats the converted value and unit.
+   * @param target Target unit to format to.
+   * @param options Formatting options.
+   * @returns Formatted string like "5km", "5.12 miles", or "5e+3 meter".
+   */
+  formatTo(target: $LengthUnit, options?: FormatToOptions): string;
+}
+//#endregion
+//#region src/converter/mass.d.ts
+/**
+ * @class MassConverter
+ * @description Handles conversions with smart `.to()`, `.toAll()`, and `.formatTo()`.
+ */
+declare class $Mass extends $BaseConverter<$MassUnit> {
+  #private;
+  /**
+   * Convert mass value to other mass units
+   * @param value Number or numeric string value to convert.
+   * @param unit Base mass unit for the provided value.
+   */
+  constructor(value: Numeric, unit: $MassUnit);
+  /**
+   * @instance Converts to target mass unit.
+   * @param target Target mass unit.
+   */
+  to(target: $MassUnit): number;
+  /**
+   * @instance Converts to all mass units at once.
+   * @returns Object with all unit conversions.
+   */
+  toAll(): $Record<$MassUnit, number>;
+  /**
+   * @instance Formats the converted value and unit.
+   * @param target Target unit to format to.
+   * @param options Formatting options.
+   * @returns Formatted string like "5kg", "5.25 kilograms", or "5e+3 gram".
+   */
+  formatTo(target: $MassUnit, options?: FormatToOptions): string;
+}
+//#endregion
+//#region src/converter/temp.d.ts
+/**
+ * @class TemperatureConverter
+ * @description Handles conversions with smart `.to()`, `.toAll()`, and `.formatTo()`.
+ */
+declare class $Temperature extends $BaseConverter<$TempUnit> {
+  #private;
+  /**
+   * Convert temperature value to other temperature units
+   * @param value Number or numeric string value to convert.
+   * @param unit Base temperature unit for the provided value.
+   */
+  constructor(value: Numeric, unit: $TempUnit);
+  /**
+   * @instance Converts to target temperature unit.
+   * @param target Target temperature unit.
+   */
+  to(target: $TempUnit): number;
+  /**
+   * @instance Converts to all temperature units at once.
+   * @returns Object with all unit conversions.
+   */
+  toAll(): $Record<$TempUnit, number>;
+  /**
+   * @instance Formats the converted value and unit.
+   * @param target Target unit to format to.
+   * @param options Formatting options.
+   * @returns Formatted string like "95°F", "5.25 kelvins", or "5e+3 celsius".
+   */
+  formatTo(target: $TempUnit, options?: FormatToOptions): string;
+}
+//#endregion
+//#region src/converter/time.d.ts
+/**
+ * @class TimeConverter
+ * @description Handles conversions with smart `.to()`, `.toAll()`, and `.formatTo()`.
+ */
+declare class $Time extends $BaseConverter<$TimeUnit> {
+  #private;
+  /**
+   * Convert time value to other time units
+   * @param value Number or numeric string value to convert.
+   * @param unit Base time unit for the provided value.
+   */
+  constructor(value: Numeric, unit: $TimeUnit);
+  /**
+   * @instance Converts to target time unit.
+   * @param target Target time unit.
+   */
+  to(target: $TimeUnit): number;
+  /**
+   * @instance Converts to all time units at once.
+   * @returns Object with all unit conversions.
+   */
+  toAll(): $Record<$TimeUnit, number>;
+  /**
+   * @instance Formats the converted value and unit.
+   * @param target Target unit to format to.
+   * @param options Formatting options.
+   * @returns Formatted string like "5h", "5.25 hours", or "5e+3 minute".
+   */
+  formatTo(target: $TimeUnit, options?: FormatToOptions): string;
+}
+//#endregion
+//#region src/converter/volume.d.ts
+/**
+ * @class VolumeConverter
+ * @description Handles conversions with smart `.to()`, `.toAll()`, and `.formatTo()`.
+ */
+declare class $Volume extends $BaseConverter<$VolumeUnit> {
+  #private;
+  /**
+   * Convert volume value to other volume units
+   * @param value Number or numeric string value to convert.
+   * @param unit Base volume unit for the provided value.
+   */
+  constructor(value: Numeric, unit: $VolumeUnit);
+  /**
+   * @instance Converts to target volume unit.
+   * @param target Target volume unit.
+   */
+  to(target: $VolumeUnit): number;
+  /**
+   * @instance Converts to target volume unit.
+   * @param target Target volume unit.
+   */
+  toAll(): $Record<$VolumeUnit, number>;
+  /**
+   * @instance Formats the converted value and unit.
+   * @param target Target unit to format to.
+   * @param options Formatting options.
+   * @returns Formatted string like "5m³", "5.25 cubic-meters", or "5e+3 meter".
+   */
+  formatTo(target: $VolumeUnit, options?: FormatToOptions): string;
+}
+//#endregion
+//#region src/types/converter.d.ts
+/** - Type for Record of Units */
+type UnitsRecord = typeof UNITS;
+/** * Category of units supported by the converter. */
+type Category = keyof UnitsRecord;
+/** * Map of unit categories to their respective units. */
+type UnitMap = { [Key in Category]: UnitsRecord[Key][number] };
+/** * Union type of all supported units. May include any other strings. */
+type $Unit = LooseLiteral<UnitMap[Category]>;
+/** * Type for array of all Units */
+type Units = Array<UnitMap[Category]>;
+/** * Tuple type for Units in a specific Category */
+type UnitsTuple<Cat extends Category> = Mutable<UnitsRecord[Cat]>;
+/** * Infer the category of a given unit type `U`. */
+type InferCategory<U extends $Unit> = { [K in Category]: U extends UnitMap[K] ? K : never }[Category];
+/** * Infer Units belong to a specific Category */
+type CategoryUnits<Cat extends Category> = UnitMap[Cat];
+/** * Type for the returned converter instance based on the provided unit `U`. */
+type Converted<U extends $Unit> = InferCategory<U> extends never ? $BaseConverter<U> : InferCategory<U> extends 'area' ? $Area : InferCategory<U> extends 'time' ? $Time : InferCategory<U> extends 'length' ? $Length : InferCategory<U> extends 'mass' ? $Mass : InferCategory<U> extends 'data' ? $Data : InferCategory<U> extends 'temp' ? $Temperature : InferCategory<U> extends 'volume' ? $Volume : $BaseConverter<U>;
+/** * Options for formatting converted values for unit converter method(s). */
+type FormatToOptions = {
+  /** Style of formatting. Default is `'plural'`. */style?: 'compact' | 'scientific' | 'plural'; /** Number of decimal places to include. Default is `2`. */
+  decimals?: number;
+};
+/** Union type for all the area units */
+type $AreaUnit = UnitMap['area'];
+/** Union type for all the data units */
+type $DataUnit = UnitMap['data'];
+/** Union type for all the length/distance units */
+type $LengthUnit = UnitMap['length'];
+/** Union type for all the mass units */
+type $MassUnit = UnitMap['mass'];
+/** Union type for all the temperature units */
+type $TempUnit = UnitMap['temp'];
+/** Union type for all the time units */
+type $TimeUnit = UnitMap['time'];
+/** Union type for all the volume units */
+type $VolumeUnit = UnitMap['volume'];
+//#endregion
+export { $Data as C, $Length as S, UnitsTuple as _, $TempUnit as a, $Temperature as b, $VolumeUnit as c, Converted as d, FormatToOptions as f, UnitsRecord as g, Units as h, $MassUnit as i, Category as l, UnitMap as m, $DataUnit as n, $TimeUnit as o, InferCategory as p, $LengthUnit as r, $Unit as s, $AreaUnit as t, CategoryUnits as u, $Volume as v, $Area as w, $Mass as x, $Time as y };