Using Polymer with Closure Compiler - Part 2: Maximizing Renaming

This is the second post in a 3-part series about using Polymer with Closure Compiler

• Part 1: Type Information
• Part 3: Renaming in Templates

UPDATE: goog.reflect.objectProperty is now available as part of the 20160619 compiler and library releases.

---

Closure Compiler's ADVANCED mode property renaming and dead code elimination put it in a class all its own. In ADVANCED mode, the compiler performs “whole world” optimizations. Polymer apps can take advantage of these optimizations without losing functionality.

How Closure Compiler Renames Properties

Closure Compiler property renaming occurs in two primary ways. The first is quite straightforward: all properties with the same name are renamed in the same way. This is ideal because it doesn't require any type information to work. All instances of .foo are renamed .a regardless of on which object they are defined. However, if any property with the same name is found on any object in the externs, the compiler cannot rename it with this strategy. The more extern properties included in your compilation, the fewer properties can be renamed with this method.

The second method for property renaming was created to address the shortcomings in the first method. Here, the compiler uses type information to rename properties so that they are unique. This way, the first method can happily rename them as they no longer share the name of an extern property. This method is called type-based renaming and as its name suggests, it can only work with proper type information. It will decline to rename a property if it finds the same property on an object for which it cannot determine type information. The better type information provided, the better this method works.

Finally, for property renaming to work at all, properties must be consistently referenced. Properties accessed using an array style bracket notation (such as foo['bar']) are called quoted properties and they will never be renamed. Properties accessed using a dot notation (such as foo.bar) are called dotted properties and may be renamed. Your code can break if you access the same property using both methods - so make sure you choose one and are consistent.

Renaming Polymer Properties

The Polymer library itself is considered an external library. A well maintained externs file for Polymer is hosted within the compiler repository (and distributed in the npm version). Lifecycle methods (such as created , ready , attached , etc) are externally defined and therefore not renameable. Also, as mentioned in part 1 of this series , declared properties defined as part of Polymer's properties object can never be renamed.

That leaves non-lifecycle standard properties as eligible for renaming - as long as they are not quoted. However, since Polymer's listeners and observers are specified as strings, that breaks the consistent access rule for properties and forces you to quote those properties. There are, however, other options.

Observers and Listeners

A Polymer element declares a property observer like:

Polymer({
  is: 'foo-bar',

  properties: {
    foo: {
      type:String,
      observer: 'fooChanged_'
    }
  }

  /** @private */
  'fooChanged_': function(oldValue, newValue) {}
});

In this case, our fooChanged_ method is a private implementation detail. Renaming it would be ideal. However for that to be possible, we would need to have access to the renamed name of fooChanged_ as a string. Closure Library has a primitive that Closure Compiler understands to help in just this case: goog.reflect.object.

By using goog.reflect.object we can rename the keys of an object literal in the same way that our Polymer element is renamed. After renaming, we can use goog.object.transpose to swap the object keys and values enabling us to easily lookup the name of our now renamed property.

var FooBarElement = Polymer({
  is: 'foo-bar',

  properties: {
    foo: {
      type: String,
      observer: FooBarRenamedProperties['fooChanged_']
    }
  }

  /** @private */
  fooChanged_: function(oldValue, newValue) {}
});

var FooBarRenamedProperties = goog.object.transpose(
  goog.reflect.object(FooBarElement, {
    fooChanged_: 'fooChanged_'
  })
);

We can use the same technique to rename listener methods:

var FooBarElement = Polymer({
  is: 'foo-bar',

  listeners: {
    'tap': FooBarRenamedProperties['tapped_']
  }

  /** @param {!Event} evt */
  tapped_: function(evt) {}
});

var FooBarRenamedProperties = goog.object.transpose(
  goog.reflect.object(FooBarElement, {
    tapped_: 'tapped_'
  })
);

Triggering Property Change Events

Polymer provides three different methods to indicate that a property has changed and data-binding expressions should be re-evaluated: set, notifyPath and notifySplices. All three have one unfortunate thing in common: they require us to specify the property name as a string. This would also break the consistent access rule for properties and once again we need access to the renamed property as a string. While the goog.object.transpose(goog.reflect.object(typeName, {})) technique would also work for this case, it requires us to know the globally accessible type name of the object. In this case, Closure Library has another primitive to help: goog.reflect.objectProperty . This method is very new. As of this writing, goog.reflect.objectProperty has yet to be released in either Closure Compiler or Closure Library (though it should be soon). goog.reflect.objectProperty allows us to call the notification methods with a renamed string.

Polymer({
  is: 'foo-bar',

  baz:'Original Value',

  attached: function() {
    setTimeout((function() {
      this.baz = 'New Value';
      this.notifyPath(
          goog.reflect.objectProperty('baz', this), this.baz);
    }).bind(this), 1000);
  }
});

goog.reflect.objectProperty simply returns the string name (first argument) in uncompiled mode. Its use comes solely as a Closure Compiler primitive where the compiler replaces the entire call with simply a string of the renamed property.

Summary

By reserving Polymer's declared properties for cases where the special functionality offered is actually needed, quite a bit of renaming can be obtained on an element. In addition, use of goog.reflect.object and goog.reflect.objectProperty allows us to rename properties which are required to be used with strings.

However now we find ourselves in a case where all this renaming has broken references in our template data-binding expressions. Time for Part 3: Renaming in Polymer Templates.

Posted by Chad Killingsworth, JS Engineer for Jack Henry and Associates, Closure Compiler committer