Wondering what’s next for npm?Check out our public roadmap! »

    forexy

    2.0.14 • Public • Published

    forexy

    dependencies npm CI Testing install size Code Scan Alerts Build Status Coverage Status

    A small, 'zero dependency' fast node.js package that delivers the latest forex rates for a given currency pair.

    Using npm:

    $ npm i --save forexy

    Usage and Examples

    To retrieve the latest forex rates for USD/GBP (US dollar to Great British Pound) we pass the two currency codes to the get() method. The get() method returns the current rate, in the first currency denomination (in this example in USD $).

    The currency pair are case insensitive and can be split using: a space, kept together, a forward slash /, or a dash -

    See Demo on runkit

    const Forexy = require("forexy");
    
    const currencyCheck = new Forexy();
    
    currencyCheck
      .get("USD/GBP") //case insensitive and in formats: "usdgbp", "usb gbp", "usd-gbp", "usd/gbp"
      .then((result) => {
        \tpair: console.log(`${currencyCheck.pair} rate is ${result}`);
      })
      .catch((err) => {
        console.error(`Error: ${err}`);
      });

    Output:

    USDGBP rate is 1.72342

    Promise

    Forexy returns a Promise, which allows you to use an async/await function, or then().catch().

    const currency = async (pair) => {
      try {
        let result = await currencyCheck.get(pair).then((rate) => rate);
        console.log(`USD/GBP rate is ${result}`);
      } catch (err) {
        console.error(`Error: ${err}`);
      }
    };
    
    currency("USD GBP");

    ...which is the same as

    currencyCheck
      .get("usdgbp")
      .then((result) => {
        console.log(`USD-GBP rate is ${result}`);
      })
      .catch((err) => {
        console.error(`Error: ${err}`);
      });

    Events

    Forexy also has a host of Events that you can use through the lifecycle process.

    fulldata

    Get a JSON object with all data.

    currencyCheck.on("fulldata", (data) => {
      //returned JSON of all data.
      console.log("on fulldata:" + JSON.stringify(data));
      //eg. {"rates":{"USDLSL":{"rate":15.140088,"timestamp":1607414291}},"code":200}
    });

    timestamp

    This returns a Date object, which can be further manipulated, this will be approximately the current timestamp.

    currencyCheck.on("timestamp", (data) => {
      //This returns a Date object.
      console.log("on timestamp:" + data); //Tues Dec 08 2021 20:51:10 GMT
    });

    pair

    Returns the currency pair values, in uppercase.

    currencyCheck.on("pair", (data) => {
      console.log("on pair:" + data); //USDGBP
    });

    statusCode

    currencyCheck.on("statusCode", (data) => {
      //If no errors then returns '200'
      console.log("on statusCode:" + data);
    });

    rate

    rate is the same as the default value returned from the get() method.

    currencyCheck.on("rate", (data) => {
      console.log("on rate:" + data);
      //eg. 1.2234
    });

    request

    Triggered before the request is made. Returns the currency pair value.

    currencyCheck.on("request", (data) => {
      //called before the request is made, returns the currency pair
      console.log("on request:" + data);
    });

    stream

    The same returned data as 'fulldata' but streamed.

    currencyCheck.on("stream", (data) => {
      //streamed data
      console.log("on stream: " + data);
    });

    Properties

    Forexy has constructor properties (prototypes), which get set during the last successful calling of the get() method.

    obj.timestamp

    This is an epoch timestamp. Convert it to a Date(obj.timestamp) object type to manipulate it as a Date.

    obj.pair

    Six characters of the two currency codes. For example, USDAUD (US Dollar against Australian Dollar).

    obj.rate

    A numeric float indicating the last returned rate for the given currency pair, for example, 1.7453

    obj.fulldata

    An object of all values returned from the last get().


    A Properties Example:

    const forex = new Forexy();
    
    const currency = async (pair) => {
      try {
        let result = await forex.get(pair).then((rate) => rate);
        console.log(
          `\nCurrency ${pair} rate is ${result}
          \ttimestamp:${Date(forex.timestamp)}
          \tpair:${forex.pair}  
          \trate:${forex.rate}         
          \tfulldata:${JSON.stringify(forex.fulldata)}
          `
        );
      } catch (err) {
        console.error(`Error: ${err}`);
      }
    };
    
    currency("USD NZD");

    output

    Currency USD NZD rate is 1.410037
            timestamp:timestamp:Sun Dec 13 2021 11:39:21 GMT
            pair:USDNZD
            rate:1.410037
            fulldata:{"rates":{"USDNZD":{"rate":1.410037,"timestamp":1607812505}},"code":200}
    

    Error Handling

    Forexy has built in Error Handling, which will catch any issues in development.

    Unsupported Forex Pairs

    Forexy currently only offers the most popular currency pairs. I plan to add more as the demand grows.

    If you enter an invalid currency pair, the promise will reject with a list of supported currency pairs available.

    If you use Forexy with async / await then wrap the call into a Try {} catch {}. Otherwise use the Promise then().catch(). Any Errors will be directed to the catch()

    const currency = async (pair) => {
      try {
        // code that we will 'try' to run
        let result = await currencyCheck.get("MONOPOLYMONEY");
      } catch (error) {
        // code to run if there are any problems
        console.error(`Error: ${err}`); //display Error message
      }
    };

    or using promise then().catch():

    currencyCheck
      .get("MONOPOLYMONEY")
      .then((result) => {
        // code to run if the promise returns a resolve()
      })
      .catch((err) => {
        // code to run if there are any problems
        console.error(`Error: ${err}`);
      });

    Supported Currency Pairs

    Since the introduction of version 1.1 I haven't found a currency that is not covered. Drop me a line if your currency pair isn't there, and I will look at getting it added. You can also raise a Github Issue.

    Version Changes

    • 1.0.x - Using an public free API, JSON returned is fixed.

    • 1.1.x - Setting up a Custom API, with the JSON customised for Forexy. Caching including to allow more traffic. Backwards compatible with v.1.0.x. A larger number of currency pair values available. New functionality to be added - coming very soon !

    • 2.0.x - Using the new Custom API under the hood, which is faster, allows for more hits and also returns better JSON data. Everything has remained backwards compatible. To Add new Properties and Events shortly. Note: To use version 1.0.x API, call the contructor with the following object: v:2. for example:

    const forex = new Forexy({ v: 1 }); //use version 1.0 API.

    Install

    npm i forexy

    DownloadsWeekly Downloads

    4

    Version

    2.0.14

    License

    ISC

    Unpacked Size

    12.7 kB

    Total Files

    3

    Last publish

    Collaborators

    • avatar