Add legacyNotifyOrder. Improve comments.

lib/mixins/property-effects.js

@@ -19,7 +19,7 @@ import { camelToDashCase, dashToCamelCase } from '../utils/case-map.js';
 import { PropertyAccessors } from './property-accessors.js';
 /* for annotated effects */
 import { TemplateStamp } from './template-stamp.js';
-import { sanitizeDOMValue, legacyUndefined, legacyNoBatch } from '../utils/settings.js';
+import { sanitizeDOMValue, legacyUndefined, legacyNoBatch, legacyNotifyOrder } from '../utils/settings.js';
 
 // Monotonically increasing unique ID used for de-duping effects triggered
 // from multiple properties in the same turn
@@ -1495,6 +1495,9 @@ export const PropertyEffects = dedupingMixin(superClass => {
         }
         if (legacyNoBatch) {
           this._invalidateProperties();
+          // Returning false here means "the change was already handled, no need
+          // to invalidate"
+          return false;
         }
         return true;
       }
@@ -1561,7 +1564,9 @@ export const PropertyEffects = dedupingMixin(superClass => {
         // The first time this element is being flushed, propagate pending
         // data down the tree first; this approximates 1.x's distributeConfig
         this._propagatePropertyChanges(this.__dataPending, {}, false);
-        // Flushing clients causes this element to become __dataReady
+        // Flushing clients recurses, running the initial call to
+        // `_flushProperties` down the tree.  It also causes this element to
+        // become __dataReady, enabling effects to run.
         this._flushClients();
         // Capture element data and flush properties one-by one to defeat
         // Polymer 2.x's batched _propertiesChanged scheme; this approximates
@@ -1744,10 +1749,14 @@ export const PropertyEffects = dedupingMixin(superClass => {
       this._flushClients();
       // Reflect properties
       runEffects(this, this[TYPES.REFLECT], changedProps, oldProps, hasPaths);
+      // Notify properties to host (1.x order)
+      if (notifyProps && legacyNotifyOrder) {
+        runNotifyEffects(this, notifyProps, changedProps, oldProps, hasPaths);
+      }
       // Observe properties
       runEffects(this, this[TYPES.OBSERVE], changedProps, oldProps, hasPaths);
-      // Notify properties to host
-      if (notifyProps) {
+      // Notify properties to host (2.x order)
+      if (notifyProps && !legacyNotifyOrder) {
         runNotifyEffects(this, notifyProps, changedProps, oldProps, hasPaths);
       }
       // Clear temporary cache at end of turn

lib/utils/settings.js

@@ -195,3 +195,21 @@ export let legacyNoBatch = false;
 export const setLegacyNoBatch = function(useLegacyNoBatch) {
   legacyNoBatch = useLegacyNoBatch;
 };
+
+/**
+ * Setting to revert to the legacy Polymer 1 order for when notifying properties
+ * fire change events with respect to other effects.  In Polymer 1.x they fire
+ * before observers; in 2.x they fire after all other effect types.
+ */
+export let legacyNotifyOrder = false;
+
+/**
+ * Sets `legacyNotifyOrder` globally for all elements to enable legacy
+ * notify order.
+ *
+ * @param {boolean} useLegacyNotifyOrder enable or disable legacy notify order
+ * @return {void}
+ */
+export const setLegacyNotifyOrder = function(useLegacyNotifyOrder) {
+  legacyNotifyOrder = useLegacyNotifyOrder;
+};

test/unit/property-effects.html

@@ -26,12 +26,12 @@
 <script type="module">
 import './property-effects-elements.js';
 import { Polymer, html } from '../../polymer-legacy.js';
-import { setSanitizeDOMValue, sanitizeDOMValue, setLegacyOptimizations, legacyUndefined, setLegacyUndefined, legacyNoBatch, setLegacyNoBatch } from '../../lib/utils/settings.js';
+import { setSanitizeDOMValue, sanitizeDOMValue, setLegacyOptimizations, legacyUndefined, setLegacyUndefined, legacyNoBatch, setLegacyNoBatch, legacyNotifyOrder, setLegacyNotifyOrder } from '../../lib/utils/settings.js';
 import { PropertyEffects } from '../../lib/mixins/property-effects.js';
 
 setLegacyUndefined(Boolean(window.location.search.match('legacyUndefined'))); 
 setLegacyNoBatch(Boolean(window.location.search.match('legacyNoBatch')));
-
+setLegacyNotifyOrder(Boolean(window.location.search.match('legacyNotifyOrder')));
 
 suite('single-element binding effects', function() {
 
@@ -1374,6 +1374,11 @@
       'notify'      // as observed by grand-parent
     ];
 
+    if (legacyNotifyOrder) {
+      expected = expected.slice(0, -1);
+      expected.splice(4, 0, 'notify');
+    }
+
     assert.deepEqual(el.invocations, expected);
   });
 });