Creating a namespace-like organization in a google apps script library

Question

I was looking into building a toolset using google apps script. The problem with this is that as far as I can tell in only allows one level of organization. You can create a Library called Stopwatch and call methods Stopwatch.start() and Stopwatch.stop() which is pretty cool.

What I had in mind though was something more like Utils.Stopwatch().start() and Utils.Timer.start() etc. I think it's certainly possible in javascript, but in order to keep breaking Apps Script autocomplete function it needs to be added in a certain format. Below is example an example of doing it wrong (gives an error) but perhaps saves some time. It's based on this article.

/**
* A stopwatch object.
* @return {Object} The stopwatch methods
*/
function Stopwatch() 
{
  var current;

  /**
  * Stop the stopwatch.
  * @param {Time} time in miliseconds
  */
  function timeInSeconds_(time)
  {
    return time/1000;
  }

  return 
    {
      /**
      * Start the stopwatch.
      */
      start: function() 
      {
        var time = new Date().getTime();
        current = timeInSeconds_(time);
      },

      /**
      * Stop the stopwatch.
      * @return {decimal} time passed since calling 
      *    start (in seconds)
      */
      stop: function() 
      {
        var time = new Date().getTime();
        var difference = timeInSeconds_(time) - this.current;
        return difference.toFixed(3);
      }
    };
}

Thanks

Answer 1

You can submit feature requests here:

http://code.google.com/p/google-apps-script-issues/issues/list

Answer 2

Until such functionality is natively supported by Google you can define empty functions with annotations on the same level as your constructor function. You can even keep your original code structure. This would enable auto-complete in the editor. Plus you'll get auto-generated documentation for your library, e.g. https://script.google.com/macros/library/versions/d/YOUR_PROJECT_KEY

Example:

/**
* Constructor.
* @constructor
* @param {String} apiKey Doxument API key
* @param {String} apiToken Doxument API token
*/    
function DoxumentApi(apiKey, apiToken) {
  // public api
  return {
        get: function(id, params) {
          var httpResponse = execute('/docs/' + id + '.json?' + buildQuery(params));
          return parse(httpResponse);
        }
    }
}

/**
* Get document record.
* @param {String} id document id
* @param {Object=} params optional. extra get params
* @return {Object} Document object
*/    
function get(id, params) {}

Answer 3

It doesn't work yet but the team does know about it. Until then you will need to document your libraries on a site. I guess you could also put the methods in the description. It really is a great start for the new service but I was with you about 5 minutes in and already wanting more. ;)

Answer 4

What about using OO?

It look very well organized and it's easy to document.

/**
 * A stopwatch Class.
 *
 * @constructor
 */
function Stopwatch() {
  this.current =  new Date().getTime();
}

/**
 * Starts the stopwatch
 */
Stopwatch.prototype.start = function(){
  this.current = new Date().getTime();
};

/**
 * Stops the stopwatch
 *
 * @return {number} Number of seconds since Stopwatch was started
 */
Stopwatch.prototype.stop = function(){
  return ((new Date().getTime()) - this.current) / 1000;
};

Example. In case your lib is imported as Utils.

var s = new Utils.Stopwatch();
s.start();

// (...) 

Logger.log(s.stop());

PS: This is untested code.

As a side effect you could have multiple Stopwatches, each one maintaining it's own local variable current

UPDATE

Although this is correctly documented following JSDoc it currently doesn't autocomplete the methods with Google Apps Script.