dinero.js 1.9.1

package/src/services/assert.js

@@ -0,0 +1,59 @@
+import { isPercentage, areValidRatios } from './helpers'
+
+/**
+ * Performs an assertion.
+ * @ignore
+ *
+ * @param  {Boolean} condition - The expression to assert.
+ * @param  {String}  errorMessage - The message to throw if the assertion fails
+ * @param  {ErrorConstructor}   [ErrorType=Error] - The error to throw if the assertion fails.
+ *
+ * @throws {Error} If `condition` returns `false`.
+ */
+export function assert(condition, errorMessage, ErrorType = Error) {
+  if (!condition) throw new ErrorType(errorMessage)
+}
+
+/**
+ * Asserts a value is a percentage.
+ * @ignore
+ *
+ * @param  {}  percentage - The percentage to test.
+ *
+ * @throws {RangeError} If `percentage` is out of range.
+ */
+export function assertPercentage(percentage) {
+  assert(
+    isPercentage(percentage),
+    'You must provide a numeric value between 0 and 100.',
+    RangeError
+  )
+}
+
+/**
+ * Asserts an array of ratios is valid.
+ * @ignore
+ *
+ * @param  {}  ratios - The ratios to test.
+ *
+ * @throws {TypeError} If `ratios` are invalid.
+ */
+export function assertValidRatios(ratios) {
+  assert(
+    areValidRatios(ratios),
+    'You must provide a non-empty array of numeric values greater than 0.',
+    TypeError
+  )
+}
+
+/**
+ * Asserts a value is an integer.
+ * @ignore
+ *
+ * @param  {}  number - The value to test.
+ *
+ * @throws {TypeError}
+ */
+export function assertInteger(number) {
+  assert(Number.isInteger(number), 'You must provide an integer.', TypeError)
+}

package/src/services/calculator.js

@@ -0,0 +1,122 @@
+import { isEven, isFloat, countFractionDigits, isHalf } from './helpers'
+
+export default function Calculator() {
+  const floatMultiply = (a, b) => {
+    const getFactor = number => Math.pow(10, countFractionDigits(number))
+    const factor = Math.max(getFactor(a), getFactor(b))
+    return (Math.round(a * factor) * Math.round(b * factor)) / (factor * factor)
+  }
+
+  const roundingModes = {
+    HALF_ODD(number) {
+      const rounded = Math.round(number)
+      return isHalf(number)
+        ? isEven(rounded)
+          ? rounded - 1
+          : rounded
+        : rounded
+    },
+    HALF_EVEN(number) {
+      const rounded = Math.round(number)
+      return isHalf(number)
+        ? isEven(rounded)
+          ? rounded
+          : rounded - 1
+        : rounded
+    },
+    HALF_UP(number) {
+      return Math.round(number)
+    },
+    HALF_DOWN(number) {
+      return isHalf(number) ? Math.floor(number) : Math.round(number)
+    },
+    HALF_TOWARDS_ZERO(number) {
+      return isHalf(number)
+        ? Math.sign(number) * Math.floor(Math.abs(number))
+        : Math.round(number)
+    },
+    HALF_AWAY_FROM_ZERO(number) {
+      return isHalf(number)
+        ? Math.sign(number) * Math.ceil(Math.abs(number))
+        : Math.round(number)
+    },
+    DOWN(number) {
+      return Math.floor(number)
+    }
+  }
+
+  return {
+    /**
+     * Returns the sum of two numbers.
+     * @ignore
+     *
+     * @param {Number} a - The first number to add.
+     * @param {Number} b - The second number to add.
+     *
+     * @return {Number}
+     */
+    add(a, b) {
+      return a + b
+    },
+    /**
+     * Returns the difference of two numbers.
+     * @ignore
+     *
+     * @param {Number} a - The first number to subtract.
+     * @param {Number} b - The second number to subtract.
+     *
+     * @return {Number}
+     */
+    subtract(a, b) {
+      return a - b
+    },
+    /**
+     * Returns the product of two numbers.
+     * @ignore
+     *
+     * @param {Number} a - The first number to multiply.
+     * @param {Number} b - The second number to multiply.
+     *
+     * @return {Number}
+     */
+    multiply(a, b) {
+      return isFloat(a) || isFloat(b) ? floatMultiply(a, b) : a * b
+    },
+    /**
+     * Returns the quotient of two numbers.
+     * @ignore
+     *
+     * @param {Number} a - The first number to divide.
+     * @param {Number} b - The second number to divide.
+     *
+     * @return {Number}
+     */
+    divide(a, b) {
+      return a / b
+    },
+    /**
+     * Returns the remainder of two numbers.
+     * @ignore
+     *
+     * @param  {Number} a - The first number to divide.
+     * @param  {Number} b - The second number to divide.
+     *
+     * @return {Number}
+     */
+    modulo(a, b) {
+      return a % b
+    },
+    /**
+     * Returns a rounded number based off a specific rounding mode.
+     * @ignore
+     *
+     * @param {Number} number - The number to round.
+     * @param {String} [roundingMode='HALF_EVEN'] - The rounding mode to use.
+     *
+     * @returns {Number}
+     */
+    round(number, roundingMode = 'HALF_EVEN') {
+      return roundingModes[roundingMode](number)
+    }
+  }
+}

package/src/services/currency-converter.js

@@ -0,0 +1,38 @@
+import { getJSON, flattenObject, isThenable } from './helpers'
+
+export default function CurrencyConverter(options) {
+  /* istanbul ignore next */
+  const mergeTags = (string = '', tags) => {
+    for (const tag in tags) {
+      string = string.replace(`{{${tag}}}`, tags[tag])
+    }
+    return string
+  }
+
+  /* istanbul ignore next */
+  const getRatesFromRestApi = (from, to) =>
+    getJSON(mergeTags(options.endpoint, { from, to }), {
+      headers: options.headers
+    })
+
+  return {
+    /**
+     * Returns the exchange rate.
+     * @ignore
+     *
+     * @param  {String} from - The base currency.
+     * @param  {String} to   - The destination currency.
+     *
+     * @return {Promise}
+     */
+    getExchangeRate(from, to) {
+      return (isThenable(options.endpoint)
+        ? options.endpoint
+        : getRatesFromRestApi(from, to)
+      ).then(
+        data =>
+          flattenObject(data)[mergeTags(options.propertyPath, { from, to })]
+      )
+    }
+  }
+}

package/src/services/format.js

@@ -0,0 +1,76 @@
+import Calculator from './calculator'
+import { isUndefined } from './helpers'
+
+const calculator = Calculator()
+
+export default function Format(format) {
+  const matches = /^(?:(\$|USD)?0(?:(,)0)?(\.)?(0+)?|0(?:(,)0)?(\.)?(0+)?\s?(dollar)?)$/gm.exec(
+    format
+  )
+
+  return {
+    /**
+     * Returns the matches.
+     * @ignore
+     *
+     * @return {Array}
+     */
+    getMatches() {
+      return matches !== null
+        ? matches.slice(1).filter(match => !isUndefined(match))
+        : []
+    },
+    /**
+     * Returns the amount of fraction digits to display.
+     * @ignore
+     *
+     * @return {Number}
+     */
+    getMinimumFractionDigits() {
+      const decimalPosition = match => match === '.'
+      return !isUndefined(this.getMatches().find(decimalPosition))
+        ? this.getMatches()[
+            calculator.add(this.getMatches().findIndex(decimalPosition), 1)
+          ].split('').length
+        : 0
+    },
+    /**
+     * Returns the currency display mode.
+     * @ignore
+     *
+     * @return {String}
+     */
+    getCurrencyDisplay() {
+      const modes = {
+        USD: 'code',
+        dollar: 'name',
+        $: 'symbol'
+      }
+      return modes[
+        this.getMatches().find(match => {
+          return match === 'USD' || match === 'dollar' || match === '$'
+        })
+      ]
+    },
+    /**
+     * Returns the formatting style.
+     * @ignore
+     *
+     * @return {String}
+     */
+    getStyle() {
+      return !isUndefined(this.getCurrencyDisplay(this.getMatches()))
+        ? 'currency'
+        : 'decimal'
+    },
+    /**
+     * Returns whether grouping should be used or not.
+     * @ignore
+     *
+     * @return {Boolean}
+     */
+    getUseGrouping() {
+      return !isUndefined(this.getMatches().find(match => match === ','))
+    }
+  }
+}

package/src/services/helpers.js

@@ -0,0 +1,193 @@
+/**
+ * Returns whether a value is numeric.
+ * @ignore
+ *
+ * @param  {} value - The value to test.
+ *
+ * @return {Boolean}
+ */
+export function isNumeric(value) {
+  return !isNaN(parseInt(value)) && isFinite(value)
+}
+
+/**
+ * Returns whether a value is a percentage.
+ * @ignore
+ *
+ * @param  {}  percentage - The percentage to test.
+ *
+ * @return {Boolean}
+ */
+export function isPercentage(percentage) {
+  return isNumeric(percentage) && percentage <= 100 && percentage >= 0
+}
+
+/**
+ * Returns whether an array of ratios is valid.
+ * @ignore
+ *
+ * @param  {}  ratios - The ratios to test.
+ *
+ * @return {Boolean}
+ */
+export function areValidRatios(ratios) {
+  return (
+    ratios.length > 0 &&
+    ratios.every(ratio => ratio >= 0) &&
+    ratios.some(ratio => ratio > 0)
+  )
+}
+
+/**
+ * Returns whether a value is even.
+ * @ignore
+ *
+ * @param  {Number} value - The value to test.
+ *
+ * @return {Boolean}
+ */
+export function isEven(value) {
+  return value % 2 === 0
+}
+
+/**
+ * Returns whether a value is a float.
+ * @ignore
+ *
+ * @param  {}  value - The value to test.
+ *
+ * @return {Boolean}
+ */
+export function isFloat(value) {
+  return isNumeric(value) && !Number.isInteger(value)
+}
+
+/**
+ * Returns how many fraction digits a number has.
+ * @ignore
+ *
+ * @param  {Number} [number=0] - The number to test.
+ *
+ * @return {Number}
+ */
+export function countFractionDigits(number = 0) {
+  const stringRepresentation = number.toString()
+  if (stringRepresentation.indexOf('e-') > 0) {
+    // It's too small for a normal string representation, e.g. 1e-7 instead of 0.00000001
+    return parseInt(stringRepresentation.split('e-')[1])
+  } else {
+    const fractionDigits = stringRepresentation.split('.')[1]
+    return fractionDigits ? fractionDigits.length : 0
+  }
+}
+
+/**
+ * Returns whether a number is half.
+ * @ignore
+ *
+ * @param {Number} number - The number to test.
+ *
+ * @return {Number}
+ */
+export function isHalf(number) {
+  return Math.abs(number) % 1 === 0.5
+}
+
+/**
+ * Fetches a JSON resource.
+ * @ignore
+ *
+ * @param  {String} url - The resource to fetch.
+ * @param  {Object} [options.headers] - The headers to pass.
+ *
+ * @throws {Error} If `request.status` is lesser than 200 or greater or equal to 400.
+ * @throws {Error} If network fails.
+ *
+ * @return {JSON}
+ */
+export function getJSON(url, options = {}) {
+  return new Promise((resolve, reject) => {
+    const request = Object.assign(new XMLHttpRequest(), {
+      onreadystatechange() {
+        if (request.readyState === 4) {
+          if (request.status >= 200 && request.status < 400)
+            resolve(JSON.parse(request.responseText))
+          else reject(new Error(request.statusText))
+        }
+      },
+      onerror() {
+        reject(new Error('Network error'))
+      }
+    })
+
+    request.open('GET', url, true)
+    setXHRHeaders(request, options.headers)
+    request.send()
+  })
+}
+
+/**
+ * Returns an XHR object with attached headers.
+ * @ignore
+ *
+ * @param {XMLHttpRequest} xhr - The XHR request to set headers to.
+ * @param {Object} headers - The headers to set.
+ *
+ * @return {XMLHttpRequest}
+ */
+export function setXHRHeaders(xhr, headers = {}) {
+  for (const header in headers) xhr.setRequestHeader(header, headers[header])
+  return xhr
+}
+
+/**
+ * Returns whether a value is undefined.
+ * @ignore
+ *
+ * @param {} value - The value to test.
+ *
+ * @return {Boolean}
+ */
+export function isUndefined(value) {
+  return typeof value === 'undefined'
+}
+
+/**
+ * Returns an object flattened to one level deep.
+ * @ignore
+ *
+ * @param {Object} object - The object to flatten.
+ * @param {String} separator - The separator to use between flattened nodes.
+ *
+ * @return {Object}
+ */
+export function flattenObject(object, separator = '.') {
+  const finalObject = {}
+  Object.entries(object).forEach(item => {
+    if (typeof item[1] === 'object') {
+      const flatObject = flattenObject(item[1])
+      Object.entries(flatObject).forEach(node => {
+        finalObject[item[0] + separator + node[0]] = node[1]
+      })
+    } else {
+      finalObject[item[0]] = item[1]
+    }
+  })
+  return finalObject
+}
+
+/**
+ * Returns whether a value is thenable.
+ * @ignore
+ *
+ * @param {} value - The value to test.
+ *
+ * @return {Boolean}
+ */
+export function isThenable(value) {
+  return (
+    Boolean(value) &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof value.then === 'function'
+  )
+}

package/src/services/settings.js

@@ -0,0 +1,62 @@
+/**
+ * Default values for all Dinero objects.
+ *
+ * You can override default values for all subsequent Dinero objects by changing them directly on the global `Dinero` object.
+ * Existing instances won't be affected.
+ *
+ * @property {Number} defaultAmount - The default amount for new Dinero objects (see {@link module:Dinero Dinero} for format).
+ * @property {String} defaultCurrency - The default currency for new Dinero objects (see {@link module:Dinero Dinero} for format).
+ * @property {Number} defaultPrecision - The default precision for new Dinero objects (see {@link module:Dinero Dinero} for format).
+ *
+ * @example
+ * // Will set currency to 'EUR' for all Dinero objects.
+ * Dinero.defaultCurrency = 'EUR'
+ *
+ * @type {Object}
+ */
+export const Defaults = {
+  defaultAmount: 0,
+  defaultCurrency: 'USD',
+  defaultPrecision: 2
+}
+
+/**
+ * Global settings for all Dinero objects.
+ *
+ * You can override global values for all subsequent Dinero objects by changing them directly on the global `Dinero` object.
+ * Existing instances won't be affected.
+ *
+ * @property {String}  globalLocale - The global locale for new Dinero objects (see {@link module:Dinero~setLocale setLocale} for format).
+ * @property {String}  globalFormat - The global format for new Dinero objects (see {@link module:Dinero~toFormat toFormat} for format).
+ * @property {String}  globalRoundingMode - The global rounding mode for new Dinero objects (see {@link module:Dinero~multiply multiply} or {@link module:Dinero~divide divide} for format).
+ * @property {String}  globalFormatRoundingMode - The global rounding mode to format new Dinero objects (see {@link module:Dinero~toFormat toFormat} or {@link module:Dinero~toRoundedUnit toRoundedUnit} for format).
+ * @property {(String|Promise)}  globalExchangeRatesApi.endpoint - The global exchange rate API endpoint for new Dinero objects, or the global promise that resolves to the exchanges rates (see {@link module:Dinero~convert convert} for format).
+ * @property {String}  globalExchangeRatesApi.propertyPath - The global exchange rate API property path for new Dinero objects (see {@link module:Dinero~convert convert} for format).
+ * @property {Object}  globalExchangeRatesApi.headers - The global exchange rate API headers for new Dinero objects (see {@link module:Dinero~convert convert} for format).
+ *
+ * @example
+ * // Will set locale to 'fr-FR' for all Dinero objects.
+ * Dinero.globalLocale = 'fr-FR'
+ * @example
+ * // Will set global exchange rate API parameters for all Dinero objects.
+ * Dinero.globalExchangeRatesApi = {
+ *  endpoint: 'https://yourexchangerates.api/latest?base={{from}}',
+ *  propertyPath: 'data.rates.{{to}}',
+ *  headers: {
+ *    'user-key': 'xxxxxxxxx'
+ *  }
+ * }
+ *
+ * @type {Object}
+ */
+export const Globals = {
+  globalLocale: 'en-US',
+  globalFormat: '$0,0.00',
+  globalRoundingMode: 'HALF_EVEN',
+  globalFormatRoundingMode: 'HALF_AWAY_FROM_ZERO',
+  globalExchangeRatesApi: {
+    endpoint: undefined,
+    headers: undefined,
+    propertyPath: undefined
+  }
+}

package/src/services/static.js

@@ -0,0 +1,103 @@
+/**
+ * Static methods for Dinero.
+ * @ignore
+ *
+ * @type {Object}
+ */
+export default {
+  /**
+   * Returns an array of Dinero objects, normalized to the same precision (the highest).
+   *
+   * @memberof module:Dinero
+   * @method
+   *
+   * @param {Dinero[]} objects - An array of Dinero objects
+   *
+   * @example
+   * // returns an array of Dinero objects
+   * // both with a precision of 3
+   * // and an amount of 1000
+   * Dinero.normalizePrecision([
+   *   Dinero({ amount: 100, precision: 2 }),
+   *   Dinero({ amount: 1000, precision: 3 })
+   * ])
+   *
+   * @return {Dinero[]}
+   */
+  normalizePrecision(objects) {
+    const highestPrecision = objects.reduce((a, b) =>
+      Math.max(a.getPrecision(), b.getPrecision())
+    )
+    return objects.map(object =>
+      object.getPrecision() !== highestPrecision
+        ? object.convertPrecision(highestPrecision)
+        : object
+    )
+  },
+  /**
+   * Returns the smallest Dinero object from an array of Dinero objects
+   *
+   * @memberof module:Dinero
+   * @method
+   *
+   * @param {Dinero[]} objects - An array of Dinero objects
+   *
+   * @example
+   * // returns the smallest Dinero object with amount of 500 from an array of Dinero objects with different precisions
+   * Dinero.minimum([
+   *   Dinero({ amount: 500, precision: 3 }),
+   *   Dinero({ amount: 100, precision: 2 })
+   * ])
+   * @example
+   * // returns the smallest Dinero object with amount of 50 from an array of Dinero objects
+   * Dinero.minimum([
+   *   Dinero({ amount: 50 }),
+   *   Dinero({ amount: 100 })
+   * ])
+   *
+   * @return {Dinero[]}
+   */
+  minimum(objects) {
+    const [firstObject, ...tailObjects] = objects
+    let currentMinimum = firstObject
+
+    tailObjects.forEach(obj => {
+      currentMinimum = currentMinimum.lessThan(obj) ? currentMinimum : obj
+    })
+
+    return currentMinimum
+  },
+  /**
+   * Returns the biggest Dinero object from an array of Dinero objects
+   *
+   * @memberof module:Dinero
+   * @method
+   *
+   * @param {Dinero[]} objects - An array of Dinero objects
+   *
+   * @example
+   * // returns the biggest Dinero object with amount of 20, from an array of Dinero objects with different precisions
+   * Dinero.maximum([
+   *   Dinero({ amount: 20, precision: 2 }),
+   *   Dinero({ amount: 150, precision: 3 })
+   * ])
+   * @example
+   * // returns the biggest Dinero object with amount of 100, from an array of Dinero objects
+   * Dinero.maximum([
+   *   Dinero({ amount: 100 }),
+   *   Dinero({ amount: 50 })
+   * ])
+   *
+   * @return {Dinero[]}
+   */
+  maximum(objects) {
+    const [firstObject, ...tailObjects] = objects
+    let currentMaximum = firstObject
+
+    tailObjects.forEach(obj => {
+      currentMaximum = currentMaximum.greaterThan(obj) ? currentMaximum : obj
+    })
+
+    return currentMaximum
+  }
+}