@airtable/blocks 1.18.1 → 1.18.2

package/dist/cjs/models/record_query_result.js

@@ -1,66 +1,44 @@
 "use strict";
 
+require("core-js/modules/es.symbol.js");
+require("core-js/modules/es.symbol.description.js");
+require("core-js/modules/es.array.from.js");
+require("core-js/modules/es.array.iterator.js");
+require("core-js/modules/es.array.slice.js");
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.regexp.exec.js");
+require("core-js/modules/es.regexp.to-string.js");
+require("core-js/modules/web.dom-collections.iterator.js");
 var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
-
-require("core-js/modules/es.symbol");
-
-require("core-js/modules/es.symbol.description");
-
-require("core-js/modules/es.array.iterator");
-
-require("core-js/modules/es.array.map");
-
-require("core-js/modules/es.object.to-string");
-
-require("core-js/modules/es.promise");
-
-require("core-js/modules/es.string.starts-with");
-
-require("core-js/modules/web.dom-collections.iterator");
-
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.normalizeSortsOrGroups = normalizeSortsOrGroups;
 exports.default = void 0;
-
+exports.normalizeSortsOrGroups = normalizeSortsOrGroups;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
-
-require("regenerator-runtime/runtime");
-
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
-
+var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
 var _possibleConstructorReturn2 = _interopRequireDefault(require("@babel/runtime/helpers/possibleConstructorReturn"));
-
-var _assertThisInitialized2 = _interopRequireDefault(require("@babel/runtime/helpers/assertThisInitialized"));
-
-var _getPrototypeOf2 = _interopRequireDefault(require("@babel/runtime/helpers/getPrototypeOf"));
-
 var _get2 = _interopRequireDefault(require("@babel/runtime/helpers/get"));
-
-var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
-
+var _getPrototypeOf2 = _interopRequireDefault(require("@babel/runtime/helpers/getPrototypeOf"));
 var _inherits2 = _interopRequireDefault(require("@babel/runtime/helpers/inherits"));
-
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
-
+require("core-js/modules/es.array.concat.js");
+require("core-js/modules/es.array.map.js");
+require("core-js/modules/es.string.starts-with.js");
 var _colors = _interopRequireDefault(require("../colors"));
-
 var _field = require("../types/field");
-
 var _private_utils = require("../private_utils");
-
 var _error_utils = require("../error_utils");
-
 var _abstract_model_with_async_data = _interopRequireDefault(require("./abstract_model_with_async_data"));
-
 var _field2 = _interopRequireDefault(require("./field"));
-
 var _record_coloring = require("./record_coloring");
-
-/** @module @airtable/blocks/models: RecordQueryResult */
-
-/** */
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+function _callSuper(t, o, e) { return o = (0, _getPrototypeOf2.default)(o), (0, _possibleConstructorReturn2.default)(t, _isNativeReflectConstruct() ? Reflect.construct(o, e || [], (0, _getPrototypeOf2.default)(t).constructor) : o.apply(t, e)); }
+function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); } catch (t) {} return (_isNativeReflectConstruct = function _isNativeReflectConstruct() { return !!t; })(); } /** @module @airtable/blocks/models: RecordQueryResult */ /** */
 var WatchableRecordQueryResultKeys = Object.freeze({
   records: 'records',
   recordIds: 'recordIds',
@@ -70,8 +48,9 @@ var WatchableRecordQueryResultKeys = Object.freeze({
   groupLevels: 'groupLevels',
   isDataLoaded: 'isDataLoaded'
 });
-var WatchableCellValuesInFieldKeyPrefix = 'cellValuesInField:'; // The string case is to accommodate cellValuesInField:$FieldId.
+var WatchableCellValuesInFieldKeyPrefix = 'cellValuesInField:';
 
+// The string case is to accommodate cellValuesInField:$FieldId.
 /**
  * A key in {@link RecordQueryResult} that can be watched
  * - `records`
@@ -82,35 +61,188 @@ var WatchableCellValuesInFieldKeyPrefix = 'cellValuesInField:'; // The string ca
  * - `cellValuesInField:{FIELD_ID}`
  */
 
+/** */
+
+/** @hidden */
+
+/**
+ * NormalizedGroupLevel is in airtable_interface
+ *
+ * @hidden
+ */
+
+/**
+ * View Config that can be set by developer
+ *
+ * @hidden
+ */
+
+/**
+ * Used to control what data is loaded in a {@link RecordQueryResult}. Used when creating a
+ * query result using `table/view.selectRecords()` and in convenience hooks {@link useRecords}.
+ *
+ * ## sorts
+ * Pass an array of sorts to control the order of records. The first sort in the array has the
+ * highest priority. If you don't specify sorts, the result will use the inherent order of the
+ * source model: the same order you'd see in the main UI for views and linked record fields, and
+ * an arbitrary (but stable) order for tables.
+ *
+ * Record creation time is used as a tiebreaker: pass an empty array to sort by creation time.
+ *
+ * ```js
+ * const opts = {
+ *     sorts: [
+ *         // sort by someField in ascending order...
+ *         {field: someField},
+ *         // then by someOtherField in descending order
+ *         {field: someOtherField, direction: 'desc'},
+ *     ]
+ * };
+ * const records = useRecords(table, opts);
+ * const queryResult = table.selectRecords(opts);
+ * ```
+ *
+ * ## fields
+ * Generally, it's a good idea to load as little data into your extension as possible - Airtable bases
+ * can get pretty big, and we have to keep all that information in memory and up to date if you ask
+ * for it. The fields option lets you make sure that only data relevant to you is loaded.
+ *
+ * You can specify fields with a {@link Field}, by ID, or by name:
+ * ```js
+ * const opts = {
+ *     fields: [
+ *         // we want to only load fieldA:
+ *         fieldA,
+ *         // the field with this id:
+ *         'fldXXXXXXXXXXXXXX',
+ *         // and the field named 'Rating':
+ *         'Rating',
+ *     ],
+ * };
+ * const records = useRecords(table, opts);
+ * const queryResult = table.selectRecords(opts);
+ * ```
+ *
+ * ## recordColorMode
+ * Just like a view in Airtable, you can control the colors of records in a field. There are three
+ * supported record color modes: none, by a view, and by a select field.
+ *
+ * ```js
+ * import {recordColoring} from '@airtable/blocks/models';
+ * // No record coloring:
+ * const opts = {
+ *     recordColorMode: recordColoring.modes.none(),
+ * };
+ *
+ * // Color according to the rules of a view:
+ * const opts = {
+ *     recordColorMode: recordColoring.modes.byView(someView),
+ * };
+ *
+ * // Color by a single select field:
+ * const opts = {
+ *     recordColorMode: recordColoring.modes.bySelectField(someSelectField),
+ * });
+ * ```
+ *
+ * You can access view coloring information directly from a {@link RecordQueryResult} or a
+ * {@link Record}, but you can only directly access single select coloring from a RecordQueryResult:
+ *
+ * ```
+ * const queryResult = table.selectRecords(opts);
+ * const records = useRecords(table, opts);
+ *
+ * // Returns based on opts coloring mode
+ * queryResult.getRecordColor(recordId);
+ *
+ * // Returns based on view
+ * // Will throw if you did not pass recordColoring.modes.byView(view) in opts
+ * records[0].getColorInView(view);
+ * ```
+ *
+ * Use `record.getCellValue(singleSelectField).color` to access the color of a single select field
+ * for a record.
+ *
+ * By default, views will have whichever coloring is set up in Airtable and tables won't have any
+ * record coloring:
+ *
+ * ```js
+ * // these two are the same:
+ * someView.selectRecords();
+ * someView.selectRecords({
+ *     recordColorMode: recordColoring.modes.byView(someView),
+ * });
+ *
+ * // as are these two:
+ * someTable.selectRecords();
+ * someTable.selectRecords({
+ *     recordColorMode: recordColoring.modes.none(),
+ * });
+ * ```
+ *
+ * */
+
+/**
+ * A subset of {@link RecordQueryResultOpts} used in {@link useRecordById} that omits sorts, as
+ * there is only a single record.
+ *
+ * See RecordQueryResultOpts for full details and examples.
+ *
+ * ```js
+ * const opts = {
+ *     fields: ['My field'],
+ *     recordColorMode: recordColoring.modes.byView(view),
+ * };
+ * const record = useRecordById(table, recordId, opts);
+ * */
+
+/**
+ * A subset of {@link RecordQueryResultOpts} used in {@link useRecordIds} that omits fields and
+ * recordColorMode, as record cell values and color are not accessible via this hook.
+ *
+ * See RecordQueryResultOpts for full details and examples.
+ *
+ * ```js
+ * const opts = {
+ *     sorts: [
+ *         // sort by someField in ascending order...
+ *         {field: someField},
+ *         // then by someOtherField in descending order
+ *         {field: someOtherField, direction: 'desc'},
+ *     ]
+ * };
+ * const recordIds = useRecordIds(table, opts);
+ * */
+
+/** @internal */
+
+/** @internal */
+
 /**
  * @internal
  */
 function _normalizeSortOrGroup(table, sortOrGroup) {
   var _sortOrGroup$directio;
-
   var field = table.__getFieldMatching(sortOrGroup.field);
-
   if (sortOrGroup.direction !== undefined && sortOrGroup.direction !== 'asc' && sortOrGroup.direction !== 'desc') {
     throw (0, _error_utils.spawnError)('Invalid sort direction: %s', sortOrGroup.direction);
   }
-
   return {
     fieldId: field.id,
     direction: (_sortOrGroup$directio = sortOrGroup.direction) !== null && _sortOrGroup$directio !== void 0 ? _sortOrGroup$directio : 'asc'
   };
 }
+
 /**
  * @internal
  */
-
-
 function normalizeSortsOrGroups(table, sortsOrGroups) {
   if (sortsOrGroups === undefined || sortsOrGroups === null) {
     return sortsOrGroups;
   }
-
   return sortsOrGroups.map(sortOrGroup => _normalizeSortOrGroup(table, sortOrGroup));
 }
+
 /**
  * A RecordQueryResult represents a set of records. It's a little bit like a one-off View in Airtable: it
  * contains a bunch of records, filtered to a useful subset of the records in the table. Those
@@ -159,136 +291,49 @@ function normalizeSortsOrGroups(table, sortsOrGroups) {
  *
  * @docsPath models/query results/RecordQueryResult
  */
-
-
-var RecordQueryResult =
-/*#__PURE__*/
-function (_AbstractModelWithAsy) {
-  (0, _inherits2.default)(RecordQueryResult, _AbstractModelWithAsy);
-  (0, _createClass2.default)(RecordQueryResult, null, [{
-    key: "_isWatchableKey",
-
-    /** @internal */
-    value: function _isWatchableKey(key) {
-      return (0, _private_utils.isEnumValue)(WatchableRecordQueryResultKeys, key) || key.startsWith(WatchableCellValuesInFieldKeyPrefix);
-    }
-    /** @internal */
-
-  }, {
-    key: "_shouldLoadDataForKey",
-    value: function _shouldLoadDataForKey(key) {
-      return key === RecordQueryResult.WatchableKeys.records || key === RecordQueryResult.WatchableKeys.recordIds || key === RecordQueryResult.WatchableKeys.cellValues || key === RecordQueryResult.WatchableKeys.recordColors || key === RecordQueryResult.WatchableKeys.groups || key === RecordQueryResult.WatchableKeys.groupLevels || key.startsWith(RecordQueryResult.WatchableCellValuesInFieldKeyPrefix);
-    }
-    /** @internal */
-
-  }, {
-    key: "_normalizeOpts",
-    value: function _normalizeOpts(table, recordStore, opts) {
-      var _normalizeSortsOrGrou;
-
-      var sorts = (_normalizeSortsOrGrou = normalizeSortsOrGroups(table, opts.sorts)) !== null && _normalizeSortsOrGrou !== void 0 ? _normalizeSortsOrGrou : null;
-      var fieldIdsOrNullIfAllFields = null;
-
-      if (opts.fields) {
-        (0, _error_utils.invariant)(Array.isArray(opts.fields), 'Must specify an array of fields');
-        fieldIdsOrNullIfAllFields = [];
-        var _iteratorNormalCompletion = true;
-        var _didIteratorError = false;
-        var _iteratorError = undefined;
-
-        try {
-          for (var _iterator = opts.fields[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
-            var fieldOrFieldIdOrFieldName = _step.value;
-
-            if (!fieldOrFieldIdOrFieldName) {
-              // Filter out false-y values so users of this API
-              // can conveniently list conditional fields, e.g. [field1, isFoo && field2]
-              continue;
-            }
-
-            if (typeof fieldOrFieldIdOrFieldName !== 'string' && !(fieldOrFieldIdOrFieldName instanceof _field2.default)) {
-              throw (0, _error_utils.spawnError)('Invalid value for field, expected a field, id, or name but got: %s', fieldOrFieldIdOrFieldName);
-            }
-
-            var field = table.__getFieldMatching(fieldOrFieldIdOrFieldName);
-
-            fieldIdsOrNullIfAllFields.push(field.id);
-          }
-        } catch (err) {
-          _didIteratorError = true;
-          _iteratorError = err;
-        } finally {
-          try {
-            if (!_iteratorNormalCompletion && _iterator.return != null) {
-              _iterator.return();
-            }
-          } finally {
-            if (_didIteratorError) {
-              throw _iteratorError;
-            }
-          }
-        }
-      }
-
-      var recordColorMode = opts.recordColorMode || _record_coloring.modes.none();
-
-      switch (recordColorMode.type) {
-        case _record_coloring.ModeTypes.NONE:
-          break;
-
-        case _record_coloring.ModeTypes.BY_SELECT_FIELD:
-          (0, _error_utils.invariant)(recordColorMode.selectField.type === _field.FieldType.SINGLE_SELECT, 'Invalid field for coloring records by select field: expected a %s, but got a %s', _field.FieldType.SINGLE_SELECT, recordColorMode.selectField.type);
-          (0, _error_utils.invariant)(recordColorMode.selectField.parentTable === table, 'Invalid field for coloring records by select field: the single select field is not in the same table as the records');
-
-          if (fieldIdsOrNullIfAllFields) {
-            fieldIdsOrNullIfAllFields.push(recordColorMode.selectField.id);
-          }
-
-          break;
-
-        case _record_coloring.ModeTypes.BY_VIEW:
-          (0, _error_utils.invariant)(recordColorMode.view.parentTable === table, 'Invalid view for coloring records from view: the view is not in the same table as the records');
-          break;
-
-        default:
-          throw (0, _error_utils.spawnError)('Unknown record coloring mode type: %s', (0, _private_utils.cast)(recordColorMode).type);
-      }
-
-      (0, _error_utils.invariant)(table.id === recordStore.tableId, 'record store and table must match');
-      return {
-        sorts,
-        fieldIdsOrNullIfAllFields,
-        recordColorMode,
-        table,
-        recordStore
-      };
-    }
-    /** @internal */
-
-  }]);
-
+var RecordQueryResult = /*#__PURE__*/function (_AbstractModelWithAsy) {
   /**
    * @internal
    */
   function RecordQueryResult(sdk, normalizedOpts) {
     var _this;
-
     (0, _classCallCheck2.default)(this, RecordQueryResult);
-    _this = (0, _possibleConstructorReturn2.default)(this, (0, _getPrototypeOf2.default)(RecordQueryResult).call(this, sdk, (0, _private_utils.getLocallyUniqueId)('RecordQueryResult')));
-    (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "_normalizedOpts", void 0);
-    (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "_recordStore", void 0);
-    (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "_recordColorChangeHandler", null);
+    _this = _callSuper(this, RecordQueryResult, [sdk, (0, _private_utils.getLocallyUniqueId)('RecordQueryResult')]);
+    /** @internal */
+    (0, _defineProperty2.default)(_this, "_normalizedOpts", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(_this, "_recordStore", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(_this, "_recordColorChangeHandler", null);
     _this._normalizedOpts = normalizedOpts;
     _this._recordStore = normalizedOpts.recordStore;
     return _this;
   }
+
   /**
    * @internal
    */
+  (0, _inherits2.default)(RecordQueryResult, _AbstractModelWithAsy);
+  return (0, _createClass2.default)(RecordQueryResult, [{
+    key: "_serializedOpts",
+    get: function get() {
+      return JSON.stringify([this._normalizedOpts.sorts, this._normalizedOpts.fieldIdsOrNullIfAllFields, this._normalizedOpts.table.id, (0, _record_coloring.serialize)(this._normalizedOpts.recordColorMode)]);
+    }
 
-
-  (0, _createClass2.default)(RecordQueryResult, [{
-    key: "getRecordByIdIfExists",
+    /**
+     * The records in this RecordQueryResult.
+     * Throws if data is not loaded yet.
+     * Can be watched.
+     */
+  }, {
+    key: "records",
+    get: function get() {
+      return this.recordIds.map(recordId => {
+        var record = this._recordStore.getRecordByIdIfExists(recordId);
+        (0, _error_utils.invariant)(record, 'Record missing in table');
+        return record;
+      });
+    }
 
     /**
      * Get a specific record in the query result, or null if that record doesn't exist or is
@@ -296,55 +341,54 @@ function (_AbstractModelWithAsy) {
      *
      * @param recordId the ID of the {@link Record} you want
      */
+  }, {
+    key: "getRecordByIdIfExists",
     value: function getRecordByIdIfExists(recordId) {
       var record = this._recordStore.getRecordByIdIfExists(recordId);
-
       if (!record || !this.hasRecord(record)) {
         return null;
       }
-
       return record;
     }
+
     /**
      * Get a specific record in the query result, or throws if that record doesn't exist or is
      * filtered out. Throws if data is not loaded yet. Watch using `'recordIds'`.
      *
      * @param recordId the ID of the {@link Record} you want
      */
-
   }, {
     key: "getRecordById",
     value: function getRecordById(recordId) {
       var record = this.getRecordByIdIfExists(recordId);
-
       if (!record) {
         throw (0, _error_utils.spawnError)('No record with ID %s in this query result', recordId);
       }
-
       return record;
     }
+
     /**
      * @internal
      */
-
   }, {
     key: "_getRecord",
     value: function _getRecord(recordOrRecordId) {
       return this.getRecordById(typeof recordOrRecordId === 'string' ? recordOrRecordId : recordOrRecordId.id);
     }
+
     /**
      * Check to see if a particular record or record id is present in this query result. Returns
      * false if the record has been deleted or is filtered out.
      *
      * @param recordOrRecordId the record or record id to check the presence of
      */
-
   }, {
     key: "hasRecord",
     value: function hasRecord(recordOrRecordId) {
       var recordId = typeof recordOrRecordId === 'string' ? recordOrRecordId : recordOrRecordId.id;
       return this._getOrGenerateRecordIdsSet()[recordId] === true;
     }
+
     /**
      * Get the {@link Color} of a specific record in the query result. Returns null if the record
      * has no color in this query result. Throws if the record isn't in the RecordQueryResult. Watch
@@ -352,45 +396,39 @@ function (_AbstractModelWithAsy) {
      *
      * @param recordOrRecordId the record or record ID you want the color of.
      */
-
   }, {
     key: "getRecordColor",
     value: function getRecordColor(recordOrRecordId) {
       var record = this._getRecord(recordOrRecordId);
-
       var recordColorMode = this._normalizedOpts.recordColorMode;
-
       switch (recordColorMode.type) {
         case _record_coloring.ModeTypes.NONE:
           return null;
-
         case _record_coloring.ModeTypes.BY_SELECT_FIELD:
           {
             if (recordColorMode.selectField.type !== _field.FieldType.SINGLE_SELECT) {
               return null;
             }
-
             var value = record.getCellValue(recordColorMode.selectField);
             return value && typeof value === 'object' && typeof value.color === 'string' ? (0, _private_utils.assertEnumValue)(_colors.default, value.color) : null;
           }
-
         case _record_coloring.ModeTypes.BY_VIEW:
           return this._recordStore.getViewDataStore(recordColorMode.view.id).getRecordColor(record);
         // istanbul ignore next
-
         default:
           throw (0, _error_utils.spawnError)('Unknown record coloring mode type: %s', (0, _private_utils.cast)(recordColorMode).type);
       }
     }
+
     /**
      * @internal
      */
-
   }, {
     key: "_onChangeIsDataLoaded",
     value: function _onChangeIsDataLoaded() {
       this._onChange(WatchableRecordQueryResultKeys.isDataLoaded);
     }
+
     /**
      * Get notified of changes to the query result.
      *
@@ -414,40 +452,27 @@ function (_AbstractModelWithAsy) {
      * @param callback a function to call when those keys change
      * @param context an optional context for `this` in `callback`.
      */
-
   }, {
     key: "watch",
     value: function watch(keys, callback, context) {
       var validKeys = (0, _get2.default)((0, _getPrototypeOf2.default)(RecordQueryResult.prototype), "watch", this).call(this, keys, callback, context);
-      var _iteratorNormalCompletion2 = true;
-      var _didIteratorError2 = false;
-      var _iteratorError2 = undefined;
-
+      var _iterator = _createForOfIteratorHelper(validKeys),
+        _step;
       try {
-        for (var _iterator2 = validKeys[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true) {
-          var key = _step2.value;
-
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var key = _step.value;
           if (key === WatchableRecordQueryResultKeys.recordColors) {
             this._watchRecordColorsIfNeeded();
           }
         }
       } catch (err) {
-        _didIteratorError2 = true;
-        _iteratorError2 = err;
+        _iterator.e(err);
       } finally {
-        try {
-          if (!_iteratorNormalCompletion2 && _iterator2.return != null) {
-            _iterator2.return();
-          }
-        } finally {
-          if (_didIteratorError2) {
-            throw _iteratorError2;
-          }
-        }
+        _iterator.f();
       }
-
       return validKeys;
     }
+
     /**
      * Unwatch keys watched with `.watch`.
      *
@@ -462,63 +487,47 @@ function (_AbstractModelWithAsy) {
      * @param callback the function passed to `.watch` for these keys
      * @param context the context that was passed to `.watch` for this `callback`
      */
-
   }, {
     key: "unwatch",
     value: function unwatch(keys, callback, context) {
       var validKeys = (0, _get2.default)((0, _getPrototypeOf2.default)(RecordQueryResult.prototype), "unwatch", this).call(this, keys, callback, context);
-      var _iteratorNormalCompletion3 = true;
-      var _didIteratorError3 = false;
-      var _iteratorError3 = undefined;
-
+      var _iterator2 = _createForOfIteratorHelper(validKeys),
+        _step2;
       try {
-        for (var _iterator3 = validKeys[Symbol.iterator](), _step3; !(_iteratorNormalCompletion3 = (_step3 = _iterator3.next()).done); _iteratorNormalCompletion3 = true) {
-          var key = _step3.value;
-
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var key = _step2.value;
           if (key === WatchableRecordQueryResultKeys.recordColors) {
             this._unwatchRecordColorsIfPossible();
           }
         }
       } catch (err) {
-        _didIteratorError3 = true;
-        _iteratorError3 = err;
+        _iterator2.e(err);
       } finally {
-        try {
-          if (!_iteratorNormalCompletion3 && _iterator3.return != null) {
-            _iterator3.return();
-          }
-        } finally {
-          if (_didIteratorError3) {
-            throw _iteratorError3;
-          }
-        }
+        _iterator2.f();
       }
-
       return validKeys;
     }
+
     /**
      * @internal
      */
-
   }, {
     key: "_watchRecordColorsIfNeeded",
     value: function _watchRecordColorsIfNeeded() {
       (0, _error_utils.invariant)(this._changeWatchersByKey[WatchableRecordQueryResultKeys.recordColors], 'method may only be called when `recordColors` key has been watched');
       var watchCount = this._changeWatchersByKey[WatchableRecordQueryResultKeys.recordColors].length;
-
       if (!this._recordColorChangeHandler && watchCount >= 1) {
         this._watchRecordColors();
       }
     }
+
     /**
      * @internal
      */
-
   }, {
     key: "_watchRecordColors",
     value: function _watchRecordColors() {
       var recordColorMode = this._normalizedOpts.recordColorMode;
-
       var handler = (model, key, recordIds) => {
         if (model === this) {
           this._onChange(WatchableRecordQueryResultKeys.recordColors, recordIds);
@@ -526,175 +535,207 @@ function (_AbstractModelWithAsy) {
           this._onChange(WatchableRecordQueryResultKeys.recordColors);
         }
       };
-
       switch (recordColorMode.type) {
         case _record_coloring.ModeTypes.NONE:
           break;
-
         case _record_coloring.ModeTypes.BY_SELECT_FIELD:
           this.watch("".concat(WatchableCellValuesInFieldKeyPrefix).concat(recordColorMode.selectField.id), handler);
           recordColorMode.selectField.watch('options', handler);
           break;
-
         case _record_coloring.ModeTypes.BY_VIEW:
           {
             this._recordStore.getViewDataStore(recordColorMode.view.id).watch('recordColors', handler);
-
             break;
           }
         // istanbul ignore next
-
         default:
           throw (0, _error_utils.spawnError)('Unknown record coloring mode type: %s', (0, _private_utils.cast)(recordColorMode).type);
       }
-
       this._recordColorChangeHandler = handler;
     }
+
     /**
      * @internal
      */
-
   }, {
     key: "_unwatchRecordColorsIfPossible",
     value: function _unwatchRecordColorsIfPossible() {
       var watchCount = (this._changeWatchersByKey[WatchableRecordQueryResultKeys.recordColors] || []).length;
-
       if (this._recordColorChangeHandler && watchCount === 0) {
         this._unwatchRecordColors();
       }
     }
+
     /**
      * @internal
      */
-
   }, {
     key: "_unwatchRecordColors",
     value: function _unwatchRecordColors() {
       var recordColorMode = this._normalizedOpts.recordColorMode;
       var handler = this._recordColorChangeHandler;
       (0, _error_utils.invariant)(handler, 'record color change handler must exist');
-
       switch (recordColorMode.type) {
         case _record_coloring.ModeTypes.NONE:
           break;
-
         case _record_coloring.ModeTypes.BY_SELECT_FIELD:
           this.unwatch("".concat(WatchableCellValuesInFieldKeyPrefix).concat(recordColorMode.selectField.id), handler);
           recordColorMode.selectField.unwatch('options', handler);
           break;
-
         case _record_coloring.ModeTypes.BY_VIEW:
           {
             if (!recordColorMode.view.isDeleted) {
               this._recordStore.getViewDataStore(recordColorMode.view.id).unwatch('recordColors', handler);
             }
-
             break;
           }
         // istanbul ignore next
-
         default:
           throw (0, _error_utils.spawnError)('Unknown record coloring mode type: %s', (0, _private_utils.cast)(recordColorMode).type);
       }
-
       this._recordColorChangeHandler = null;
     }
+
     /**
      * @internal
      */
-
   }, {
     key: "_loadRecordColorsAsync",
-    value: function _loadRecordColorsAsync() {
-      var recordColorMode;
-      return _regenerator.default.async(function _loadRecordColorsAsync$(_context) {
-        while (1) {
-          switch (_context.prev = _context.next) {
+    value: (function () {
+      var _loadRecordColorsAsync2 = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
+        var recordColorMode;
+        return _regenerator.default.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
             case 0:
               recordColorMode = this._normalizedOpts.recordColorMode;
               _context.t0 = recordColorMode.type;
               _context.next = _context.t0 === _record_coloring.ModeTypes.NONE ? 4 : _context.t0 === _record_coloring.ModeTypes.BY_SELECT_FIELD ? 5 : _context.t0 === _record_coloring.ModeTypes.BY_VIEW ? 6 : 9;
               break;
-
             case 4:
               return _context.abrupt("return");
-
             case 5:
               return _context.abrupt("return");
-
             case 6:
               _context.next = 8;
-              return _regenerator.default.awrap(this._recordStore.getViewDataStore(recordColorMode.view.id).loadDataAsync());
-
+              return this._recordStore.getViewDataStore(recordColorMode.view.id).loadDataAsync();
             case 8:
               return _context.abrupt("return");
-
             case 9:
               throw (0, _error_utils.spawnUnknownSwitchCaseError)('record color mode type', recordColorMode, 'type');
-
             case 10:
             case "end":
               return _context.stop();
           }
-        }
-      }, null, this);
-    }
+        }, _callee, this);
+      }));
+      function _loadRecordColorsAsync() {
+        return _loadRecordColorsAsync2.apply(this, arguments);
+      }
+      return _loadRecordColorsAsync;
+    }()
     /**
      * @internal
      */
-
+    )
   }, {
     key: "_unloadRecordColors",
     value: function _unloadRecordColors() {
       var recordColorMode = this._normalizedOpts.recordColorMode;
-
       switch (recordColorMode.type) {
         case _record_coloring.ModeTypes.NONE:
           return;
-
         case _record_coloring.ModeTypes.BY_SELECT_FIELD:
           // handled as part of fieldIdsOrNullIfAllFields
           return;
-
         case _record_coloring.ModeTypes.BY_VIEW:
           if (!recordColorMode.view.isDeleted) {
             this._recordStore.getViewDataStore(recordColorMode.view.id).unloadData();
           }
-
           break;
         // istanbul ignore next
-
         default:
           throw (0, _error_utils.spawnUnknownSwitchCaseError)('record color mode type', recordColorMode, 'type');
       }
     }
+  }], [{
+    key: "_isWatchableKey",
+    value: /** @internal */
+    function _isWatchableKey(key) {
+      return (0, _private_utils.isEnumValue)(WatchableRecordQueryResultKeys, key) || key.startsWith(WatchableCellValuesInFieldKeyPrefix);
+    }
+    /** @internal */
   }, {
-    key: "_serializedOpts",
-    get: function get() {
-      return JSON.stringify([this._normalizedOpts.sorts, this._normalizedOpts.fieldIdsOrNullIfAllFields, this._normalizedOpts.table.id, (0, _record_coloring.serialize)(this._normalizedOpts.recordColorMode)]);
+    key: "_shouldLoadDataForKey",
+    value: function _shouldLoadDataForKey(key) {
+      return key === RecordQueryResult.WatchableKeys.records || key === RecordQueryResult.WatchableKeys.recordIds || key === RecordQueryResult.WatchableKeys.cellValues || key === RecordQueryResult.WatchableKeys.recordColors || key === RecordQueryResult.WatchableKeys.groups || key === RecordQueryResult.WatchableKeys.groupLevels || key.startsWith(RecordQueryResult.WatchableCellValuesInFieldKeyPrefix);
     }
-    /**
-     * The records in this RecordQueryResult.
-     * Throws if data is not loaded yet.
-     * Can be watched.
-     */
 
+    /** @internal */
   }, {
-    key: "records",
-    get: function get() {
-      return this.recordIds.map(recordId => {
-        var record = this._recordStore.getRecordByIdIfExists(recordId);
-
-        (0, _error_utils.invariant)(record, 'Record missing in table');
-        return record;
-      });
+    key: "_normalizeOpts",
+    value: function _normalizeOpts(table, recordStore, opts) {
+      var _normalizeSortsOrGrou;
+      var sorts = (_normalizeSortsOrGrou = normalizeSortsOrGroups(table, opts.sorts)) !== null && _normalizeSortsOrGrou !== void 0 ? _normalizeSortsOrGrou : null;
+      var fieldIdsOrNullIfAllFields = null;
+      if (opts.fields) {
+        (0, _error_utils.invariant)(Array.isArray(opts.fields), 'Must specify an array of fields');
+        fieldIdsOrNullIfAllFields = [];
+        var _iterator3 = _createForOfIteratorHelper(opts.fields),
+          _step3;
+        try {
+          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+            var fieldOrFieldIdOrFieldName = _step3.value;
+            if (!fieldOrFieldIdOrFieldName) {
+              // Filter out false-y values so users of this API
+              // can conveniently list conditional fields, e.g. [field1, isFoo && field2]
+              continue;
+            }
+            if (typeof fieldOrFieldIdOrFieldName !== 'string' && !(fieldOrFieldIdOrFieldName instanceof _field2.default)) {
+              throw (0, _error_utils.spawnError)('Invalid value for field, expected a field, id, or name but got: %s', fieldOrFieldIdOrFieldName);
+            }
+            var field = table.__getFieldMatching(fieldOrFieldIdOrFieldName);
+            fieldIdsOrNullIfAllFields.push(field.id);
+          }
+        } catch (err) {
+          _iterator3.e(err);
+        } finally {
+          _iterator3.f();
+        }
+      }
+      var recordColorMode = opts.recordColorMode || _record_coloring.modes.none();
+      switch (recordColorMode.type) {
+        case _record_coloring.ModeTypes.NONE:
+          break;
+        case _record_coloring.ModeTypes.BY_SELECT_FIELD:
+          (0, _error_utils.invariant)(recordColorMode.selectField.type === _field.FieldType.SINGLE_SELECT, 'Invalid field for coloring records by select field: expected a %s, but got a %s', _field.FieldType.SINGLE_SELECT, recordColorMode.selectField.type);
+          (0, _error_utils.invariant)(recordColorMode.selectField.parentTable === table, 'Invalid field for coloring records by select field: the single select field is not in the same table as the records');
+          if (fieldIdsOrNullIfAllFields) {
+            fieldIdsOrNullIfAllFields.push(recordColorMode.selectField.id);
+          }
+          break;
+        case _record_coloring.ModeTypes.BY_VIEW:
+          (0, _error_utils.invariant)(recordColorMode.view.parentTable === table, 'Invalid view for coloring records from view: the view is not in the same table as the records');
+          break;
+        default:
+          throw (0, _error_utils.spawnError)('Unknown record coloring mode type: %s', (0, _private_utils.cast)(recordColorMode).type);
+      }
+      (0, _error_utils.invariant)(table.id === recordStore.tableId, 'record store and table must match');
+      return {
+        sorts,
+        fieldIdsOrNullIfAllFields,
+        recordColorMode,
+        table,
+        recordStore
+      };
     }
   }]);
-  return RecordQueryResult;
 }(_abstract_model_with_async_data.default);
-
+// Abstract properties - classes extending QueryResult must override these:
+/** @internal */
 (0, _defineProperty2.default)(RecordQueryResult, "_className", 'RecordQueryResult');
+// provided properties + methods:
+/** @internal */
 (0, _defineProperty2.default)(RecordQueryResult, "WatchableKeys", WatchableRecordQueryResultKeys);
+/** @internal */
 (0, _defineProperty2.default)(RecordQueryResult, "WatchableCellValuesInFieldKeyPrefix", WatchableCellValuesInFieldKeyPrefix);
-var _default = RecordQueryResult;
-exports.default = _default;
+var _default = exports.default = RecordQueryResult;