@zairakai/js-utils 1.0.0

package/dist/number.cjs

@@ -0,0 +1,279 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/number.ts
+var number_exports = {};
+__export(number_exports, {
+  NumberHelper: () => NumberHelper,
+  Numberable: () => Numberable,
+  num: () => num
+});
+module.exports = __toCommonJS(number_exports);
+var Numberable = class {
+  /**
+   * Create a new Numberable instance.
+   *
+   * @param {unknown} value The initial value
+   */
+  constructor(value) {
+    this.value = Number(value ?? 0);
+    if (isNaN(this.value)) {
+      this.value = 0;
+    }
+  }
+  /**
+   * Get the raw number value.
+   *
+   * @returns {number} The raw value
+   */
+  toNumber() {
+    return this.value;
+  }
+  /**
+   * Alias for toNumber().
+   *
+   * @returns {number} The raw value
+   */
+  get() {
+    return this.value;
+  }
+  /**
+   * Format the number with locale-specific formatting.
+   *
+   * @param {number} [decimals=0] The number of decimal points
+   * @param {string} [locale='en-US'] The locale to use for formatting
+   * @returns {string} The formatted number
+   */
+  format(decimals = 0, locale = "en-US") {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals
+    }).format(this.value);
+  }
+  /**
+   * Format the number as currency.
+   *
+   * @param {string} [currency='USD'] The currency code (e.g., 'USD', 'EUR')
+   * @param {string} [locale='en-US'] The locale to use for formatting
+   * @returns {string} The formatted currency string
+   */
+  currency(currency = "USD", locale = "en-US") {
+    return new Intl.NumberFormat(locale, {
+      style: "currency",
+      currency
+    }).format(this.value);
+  }
+  /**
+   * Format the number as a percentage.
+   *
+   * @param {number} [decimals=0] The number of decimal points
+   * @param {string} [locale='en-US'] The locale to use for formatting
+   * @returns {string} The formatted percentage string
+   */
+  percentage(decimals = 0, locale = "en-US") {
+    return new Intl.NumberFormat(locale, {
+      style: "percent",
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals
+    }).format(this.value / 100);
+  }
+  /**
+   * Format the number as a human-readable file size.
+   *
+   * @param {number} [precision=2] The number of decimal points
+   * @returns {string} The formatted file size (e.g., "1.50 MB")
+   */
+  fileSize(precision = 2) {
+    if (0 === this.value) {
+      return "0 B";
+    }
+    const units = ["B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];
+    const i = Math.floor(Math.log(this.value) / Math.log(1024));
+    return `${parseFloat((this.value / Math.pow(1024, i)).toFixed(precision))} ${units[i]}`;
+  }
+  /**
+   * Abbreviate the number (e.g., 1K, 1M, 1B).
+   *
+   * @param {number} [precision=1] The number of decimal points
+   * @returns {string} The abbreviated number
+   */
+  abbreviate(precision = 1) {
+    if (1e3 > this.value) {
+      return String(this.value);
+    }
+    const units = ["", "K", "M", "B", "T"];
+    const i = Math.floor(Math.log10(this.value) / 3);
+    return `${parseFloat((this.value / Math.pow(1e3, i)).toFixed(precision))}${units[i]}`;
+  }
+  /**
+   * Add an ordinal suffix to the number (e.g., 1st, 2nd, 3rd).
+   *
+   * @returns {string} The number with its ordinal suffix
+   */
+  ordinal() {
+    const s = ["th", "st", "nd", "rd"];
+    const v = this.value % 100;
+    return this.value + (s[(v - 20) % 10] || s[v] || s[0]);
+  }
+  /**
+   * Clamp the number between a minimum and maximum value.
+   *
+   * @param {number} min The minimum value
+   * @param {number} max The maximum value
+   * @returns {this} The Numberable instance
+   */
+  clamp(min, max) {
+    this.value = Math.min(Math.max(this.value, min), max);
+    return this;
+  }
+  /**
+   * Check if the number is between a minimum and maximum value.
+   *
+   * @param {number} min The minimum value
+   * @param {number} max The maximum value
+   * @param {boolean} [inclusive=true] Whether to include the boundaries
+   * @returns {boolean} True if the number is between min and max
+   */
+  isBetween(min, max, inclusive = true) {
+    return inclusive ? this.value >= min && this.value <= max : this.value > min && this.value < max;
+  }
+  /**
+   * Add a value to the current number.
+   *
+   * @param {number} value The value to add
+   * @returns {this} The Numberable instance
+   */
+  add(value) {
+    this.value += value;
+    return this;
+  }
+  /**
+   * Subtract a value from the current number.
+   *
+   * @param {number} value The value to subtract
+   * @returns {this} The Numberable instance
+   */
+  sub(value) {
+    this.value -= value;
+    return this;
+  }
+  /**
+   * Multiply the current number by a value.
+   *
+   * @param {number} value The value to multiply by
+   * @returns {this} The Numberable instance
+   */
+  mul(value) {
+    this.value *= value;
+    return this;
+  }
+  /**
+   * Divide the current number by a value.
+   *
+   * @param {number} value The value to divide by
+   * @returns {this} The Numberable instance
+   */
+  div(value) {
+    if (0 !== value) {
+      this.value /= value;
+    }
+    return this;
+  }
+  /**
+   * Round the number to a specified precision.
+   *
+   * @param {number} [precision=0] The number of decimal points
+   * @returns {this} The Numberable instance
+   */
+  round(precision = 0) {
+    const factor = Math.pow(10, precision);
+    this.value = Math.round(this.value * factor) / factor;
+    return this;
+  }
+  /**
+   * Round the number up to a specified precision.
+   *
+   * @param {number} [precision=0] The number of decimal points
+   * @returns {this} The Numberable instance
+   */
+  ceil(precision = 0) {
+    const factor = Math.pow(10, precision);
+    this.value = Math.ceil(this.value * factor) / factor;
+    return this;
+  }
+  /**
+   * Round the number down to a specified precision.
+   *
+   * @param {number} [precision=0] The number of decimal points
+   * @returns {this} The Numberable instance
+   */
+  floor(precision = 0) {
+    const factor = Math.pow(10, precision);
+    this.value = Math.floor(this.value * factor) / factor;
+    return this;
+  }
+  /**
+   * Pipe the current Numberable instance to a callback.
+   *
+   * @param {Function} callback The callback to execute
+   * @returns {U} The result of the callback
+   */
+  pipe(callback) {
+    return callback(this);
+  }
+  /**
+   * Execute a callback if a condition is met.
+   *
+   * @param {boolean | Function} condition The condition to check
+   * @param {Function} callback The callback to execute if condition is true
+   * @returns {this} The Numberable instance
+   */
+  when(condition, callback) {
+    const shouldExecute = "function" === typeof condition ? condition() : condition;
+    if (shouldExecute) {
+      callback(this);
+    }
+    return this;
+  }
+};
+var num = (value) => {
+  return new Numberable(value);
+};
+var NumberHelper = {
+  /** Create a new Numberable instance */
+  of: (value) => new Numberable(value),
+  /** Format the number with locale-specific formatting */
+  format: (value, decimals = 0, locale = "en-US") => new Numberable(value).format(decimals, locale),
+  /** Format the number as currency */
+  currency: (value, currency = "USD", locale = "en-US") => new Numberable(value).currency(currency, locale),
+  /** Format the number as a percentage */
+  percentage: (value, decimals = 0, locale = "en-US") => new Numberable(value).percentage(decimals, locale),
+  /** Format the number as a human-readable file size */
+  fileSize: (value, precision = 2) => new Numberable(value).fileSize(precision),
+  /** Abbreviate the number */
+  abbreviate: (value, precision = 1) => new Numberable(value).abbreviate(precision),
+  /** Add an ordinal suffix to the number */
+  ordinal: (value) => new Numberable(value).ordinal()
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NumberHelper,
+  Numberable,
+  num
+});

package/dist/number.d.cts

@@ -0,0 +1,177 @@
+/**
+ * Fluent number manipulation class inspired by Laravel's Number and modern utilities.
+ */
+declare class Numberable {
+    protected value: number;
+    /**
+     * Create a new Numberable instance.
+     *
+     * @param {unknown} value The initial value
+     */
+    constructor(value: unknown);
+    /**
+     * Get the raw number value.
+     *
+     * @returns {number} The raw value
+     */
+    toNumber(): number;
+    /**
+     * Alias for toNumber().
+     *
+     * @returns {number} The raw value
+     */
+    get(): number;
+    /**
+     * Format the number with locale-specific formatting.
+     *
+     * @param {number} [decimals=0] The number of decimal points
+     * @param {string} [locale='en-US'] The locale to use for formatting
+     * @returns {string} The formatted number
+     */
+    format(decimals?: number, locale?: string): string;
+    /**
+     * Format the number as currency.
+     *
+     * @param {string} [currency='USD'] The currency code (e.g., 'USD', 'EUR')
+     * @param {string} [locale='en-US'] The locale to use for formatting
+     * @returns {string} The formatted currency string
+     */
+    currency(currency?: string, locale?: string): string;
+    /**
+     * Format the number as a percentage.
+     *
+     * @param {number} [decimals=0] The number of decimal points
+     * @param {string} [locale='en-US'] The locale to use for formatting
+     * @returns {string} The formatted percentage string
+     */
+    percentage(decimals?: number, locale?: string): string;
+    /**
+     * Format the number as a human-readable file size.
+     *
+     * @param {number} [precision=2] The number of decimal points
+     * @returns {string} The formatted file size (e.g., "1.50 MB")
+     */
+    fileSize(precision?: number): string;
+    /**
+     * Abbreviate the number (e.g., 1K, 1M, 1B).
+     *
+     * @param {number} [precision=1] The number of decimal points
+     * @returns {string} The abbreviated number
+     */
+    abbreviate(precision?: number): string;
+    /**
+     * Add an ordinal suffix to the number (e.g., 1st, 2nd, 3rd).
+     *
+     * @returns {string} The number with its ordinal suffix
+     */
+    ordinal(): string;
+    /**
+     * Clamp the number between a minimum and maximum value.
+     *
+     * @param {number} min The minimum value
+     * @param {number} max The maximum value
+     * @returns {this} The Numberable instance
+     */
+    clamp(min: number, max: number): this;
+    /**
+     * Check if the number is between a minimum and maximum value.
+     *
+     * @param {number} min The minimum value
+     * @param {number} max The maximum value
+     * @param {boolean} [inclusive=true] Whether to include the boundaries
+     * @returns {boolean} True if the number is between min and max
+     */
+    isBetween(min: number, max: number, inclusive?: boolean): boolean;
+    /**
+     * Add a value to the current number.
+     *
+     * @param {number} value The value to add
+     * @returns {this} The Numberable instance
+     */
+    add(value: number): this;
+    /**
+     * Subtract a value from the current number.
+     *
+     * @param {number} value The value to subtract
+     * @returns {this} The Numberable instance
+     */
+    sub(value: number): this;
+    /**
+     * Multiply the current number by a value.
+     *
+     * @param {number} value The value to multiply by
+     * @returns {this} The Numberable instance
+     */
+    mul(value: number): this;
+    /**
+     * Divide the current number by a value.
+     *
+     * @param {number} value The value to divide by
+     * @returns {this} The Numberable instance
+     */
+    div(value: number): this;
+    /**
+     * Round the number to a specified precision.
+     *
+     * @param {number} [precision=0] The number of decimal points
+     * @returns {this} The Numberable instance
+     */
+    round(precision?: number): this;
+    /**
+     * Round the number up to a specified precision.
+     *
+     * @param {number} [precision=0] The number of decimal points
+     * @returns {this} The Numberable instance
+     */
+    ceil(precision?: number): this;
+    /**
+     * Round the number down to a specified precision.
+     *
+     * @param {number} [precision=0] The number of decimal points
+     * @returns {this} The Numberable instance
+     */
+    floor(precision?: number): this;
+    /**
+     * Pipe the current Numberable instance to a callback.
+     *
+     * @param {Function} callback The callback to execute
+     * @returns {U} The result of the callback
+     */
+    pipe<U>(callback: (num: this) => U): U;
+    /**
+     * Execute a callback if a condition is met.
+     *
+     * @param {boolean | Function} condition The condition to check
+     * @param {Function} callback The callback to execute if condition is true
+     * @returns {this} The Numberable instance
+     */
+    when(condition: boolean | (() => boolean), callback: (num: this) => void): this;
+}
+/**
+ * Create a new fluent Numberable instance.
+ *
+ * @param {unknown} [value] The initial value
+ * @returns {Numberable} A new Numberable instance
+ */
+declare const num: (value?: unknown) => Numberable;
+/**
+ * Static methods for number manipulation.
+ */
+declare const NumberHelper: {
+    /** Create a new Numberable instance */
+    of: (value: unknown) => Numberable;
+    /** Format the number with locale-specific formatting */
+    format: (value: number, decimals?: number, locale?: string) => string;
+    /** Format the number as currency */
+    currency: (value: number, currency?: string, locale?: string) => string;
+    /** Format the number as a percentage */
+    percentage: (value: number, decimals?: number, locale?: string) => string;
+    /** Format the number as a human-readable file size */
+    fileSize: (value: number, precision?: number) => string;
+    /** Abbreviate the number */
+    abbreviate: (value: number, precision?: number) => string;
+    /** Add an ordinal suffix to the number */
+    ordinal: (value: number) => string;
+};
+
+export { NumberHelper, Numberable, num };

package/dist/number.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Fluent number manipulation class inspired by Laravel's Number and modern utilities.
+ */
+declare class Numberable {
+    protected value: number;
+    /**
+     * Create a new Numberable instance.
+     *
+     * @param {unknown} value The initial value
+     */
+    constructor(value: unknown);
+    /**
+     * Get the raw number value.
+     *
+     * @returns {number} The raw value
+     */
+    toNumber(): number;
+    /**
+     * Alias for toNumber().
+     *
+     * @returns {number} The raw value
+     */
+    get(): number;
+    /**
+     * Format the number with locale-specific formatting.
+     *
+     * @param {number} [decimals=0] The number of decimal points
+     * @param {string} [locale='en-US'] The locale to use for formatting
+     * @returns {string} The formatted number
+     */
+    format(decimals?: number, locale?: string): string;
+    /**
+     * Format the number as currency.
+     *
+     * @param {string} [currency='USD'] The currency code (e.g., 'USD', 'EUR')
+     * @param {string} [locale='en-US'] The locale to use for formatting
+     * @returns {string} The formatted currency string
+     */
+    currency(currency?: string, locale?: string): string;
+    /**
+     * Format the number as a percentage.
+     *
+     * @param {number} [decimals=0] The number of decimal points
+     * @param {string} [locale='en-US'] The locale to use for formatting
+     * @returns {string} The formatted percentage string
+     */
+    percentage(decimals?: number, locale?: string): string;
+    /**
+     * Format the number as a human-readable file size.
+     *
+     * @param {number} [precision=2] The number of decimal points
+     * @returns {string} The formatted file size (e.g., "1.50 MB")
+     */
+    fileSize(precision?: number): string;
+    /**
+     * Abbreviate the number (e.g., 1K, 1M, 1B).
+     *
+     * @param {number} [precision=1] The number of decimal points
+     * @returns {string} The abbreviated number
+     */
+    abbreviate(precision?: number): string;
+    /**
+     * Add an ordinal suffix to the number (e.g., 1st, 2nd, 3rd).
+     *
+     * @returns {string} The number with its ordinal suffix
+     */
+    ordinal(): string;
+    /**
+     * Clamp the number between a minimum and maximum value.
+     *
+     * @param {number} min The minimum value
+     * @param {number} max The maximum value
+     * @returns {this} The Numberable instance
+     */
+    clamp(min: number, max: number): this;
+    /**
+     * Check if the number is between a minimum and maximum value.
+     *
+     * @param {number} min The minimum value
+     * @param {number} max The maximum value
+     * @param {boolean} [inclusive=true] Whether to include the boundaries
+     * @returns {boolean} True if the number is between min and max
+     */
+    isBetween(min: number, max: number, inclusive?: boolean): boolean;
+    /**
+     * Add a value to the current number.
+     *
+     * @param {number} value The value to add
+     * @returns {this} The Numberable instance
+     */
+    add(value: number): this;
+    /**
+     * Subtract a value from the current number.
+     *
+     * @param {number} value The value to subtract
+     * @returns {this} The Numberable instance
+     */
+    sub(value: number): this;
+    /**
+     * Multiply the current number by a value.
+     *
+     * @param {number} value The value to multiply by
+     * @returns {this} The Numberable instance
+     */
+    mul(value: number): this;
+    /**
+     * Divide the current number by a value.
+     *
+     * @param {number} value The value to divide by
+     * @returns {this} The Numberable instance
+     */
+    div(value: number): this;
+    /**
+     * Round the number to a specified precision.
+     *
+     * @param {number} [precision=0] The number of decimal points
+     * @returns {this} The Numberable instance
+     */
+    round(precision?: number): this;
+    /**
+     * Round the number up to a specified precision.
+     *
+     * @param {number} [precision=0] The number of decimal points
+     * @returns {this} The Numberable instance
+     */
+    ceil(precision?: number): this;
+    /**
+     * Round the number down to a specified precision.
+     *
+     * @param {number} [precision=0] The number of decimal points
+     * @returns {this} The Numberable instance
+     */
+    floor(precision?: number): this;
+    /**
+     * Pipe the current Numberable instance to a callback.
+     *
+     * @param {Function} callback The callback to execute
+     * @returns {U} The result of the callback
+     */
+    pipe<U>(callback: (num: this) => U): U;
+    /**
+     * Execute a callback if a condition is met.
+     *
+     * @param {boolean | Function} condition The condition to check
+     * @param {Function} callback The callback to execute if condition is true
+     * @returns {this} The Numberable instance
+     */
+    when(condition: boolean | (() => boolean), callback: (num: this) => void): this;
+}
+/**
+ * Create a new fluent Numberable instance.
+ *
+ * @param {unknown} [value] The initial value
+ * @returns {Numberable} A new Numberable instance
+ */
+declare const num: (value?: unknown) => Numberable;
+/**
+ * Static methods for number manipulation.
+ */
+declare const NumberHelper: {
+    /** Create a new Numberable instance */
+    of: (value: unknown) => Numberable;
+    /** Format the number with locale-specific formatting */
+    format: (value: number, decimals?: number, locale?: string) => string;
+    /** Format the number as currency */
+    currency: (value: number, currency?: string, locale?: string) => string;
+    /** Format the number as a percentage */
+    percentage: (value: number, decimals?: number, locale?: string) => string;
+    /** Format the number as a human-readable file size */
+    fileSize: (value: number, precision?: number) => string;
+    /** Abbreviate the number */
+    abbreviate: (value: number, precision?: number) => string;
+    /** Add an ordinal suffix to the number */
+    ordinal: (value: number) => string;
+};
+
+export { NumberHelper, Numberable, num };

package/dist/number.js

@@ -0,0 +1,10 @@
+import {
+  NumberHelper,
+  Numberable,
+  num
+} from "./chunk-G7ZJ23DW.js";
+export {
+  NumberHelper,
+  Numberable,
+  num
+};