@airtable/blocks 0.0.0-experimental-f52bc4e5e-20250709 → 0.0.0-experimental-3649c7162-20250904

package/dist/esm/base/models/grouped_record_query_result.js

@@ -0,0 +1,280 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _error_utils = require("../../shared/error_utils");
+var _record_query_result = _interopRequireDefault(require("./record_query_result"));
+var _object_pool = _interopRequireDefault(require("./object_pool"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks/models: RecordQueryResult */ /** */
+
+/** @hidden */
+// Even though we don't load the data, we still access it through `._data` so that
+// we can be ensured the model hasn't been deleted.
+
+/**
+ * Represents a group of records returned from a group query. See {@link RecordQueryResult} for main
+ * documentation.
+ *
+ * Do not instantiate. You can get instances of this class by calling
+ * `recordQueryResult.groups`.
+ *
+ * @docsPath models/query results/GroupedRecordQueryResult
+ * @hidden
+ */
+class GroupedRecordQueryResult extends _record_query_result.default {
+  /** @internal */
+  static _className = 'GroupedRecordQueryResult';
+
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * This includes groupLevel for all children & parent grouped layers, the getter
+   * returns only the groupLevels for this layer.
+   *
+   * @internal
+   */
+
+  // This is the ordered list of groups.
+  /** @internal */
+
+  // lazily generated set of record ids
+  /** @internal */
+  _recordIdsSet = null;
+
+  // lazily generated ordered array of recordIds
+  _orderedRecordIds = null;
+
+  /** @internal */
+
+  /** @internal */
+  constructor(parentQueryResult, groupData, groupLevel, normalizedOpts, sdk) {
+    super(sdk, normalizedOpts);
+    this.__groupedRecordQueryResultPool = new _object_pool.default(GroupedRecordQueryResult);
+    this._parentQueryResult = parentQueryResult;
+    this._groupData = groupData;
+    this._groupLevels = groupLevel;
+    const groupLevelDataSlicedForChildren = this._groupLevels.slice(1);
+    this._orderedChildrenGroups = groupData.groups ? groupData.groups.map(singleGroupData => {
+      const group = this.__groupedRecordQueryResultPool.getObjectForReuse(this, singleGroupData, groupLevelDataSlicedForChildren, normalizedOpts, sdk);
+      // Don't await the loading, let others check isDataLoaded.
+      // (it doesn't take any time anyway). Loading also strong retains.
+      group.loadDataAsync();
+      return group;
+    }) : null;
+  }
+
+  /**
+   * Gets children groups of this group (if any exist)
+   */
+  get groups() {
+    return this._orderedChildrenGroups;
+  }
+
+  /** @internal */
+  get groupLevel() {
+    return this._data.groupLevels[0];
+  }
+
+  /**
+   * Gets the fieldId that this group is grouped by
+   */
+  get fieldId() {
+    return this.groupLevel.fieldId;
+  }
+
+  /**
+   * Gets the field that this group is grouped by
+   */
+  get field() {
+    return this.parentTable.getFieldById(this.fieldId);
+  }
+
+  // TODO (SeanKeenan) This is needed because we can't always iterate down and find
+  // a record, it's possible to have "empty groups".
+  // getValue() {
+  // }
+
+  // TODO (SeanKeenan)
+  // getValueAsString() {
+  // }
+
+  /**
+   * @internal (since we may not be able to return parent model instances in the immutable models world)
+   * The table that records in this RecordQueryResult are part of
+   */
+  get parentTable() {
+    return this._parentQueryResult.parentTable;
+  }
+
+  /**
+   * Recursively gets all recordIds in the children groups, keeping recordIds in group order
+   *
+   * @internal
+   */
+  _computeRecordIds() {
+    // If we are a leaf node, return the raw recordIds
+    if (!this.groups) {
+      // Typescript can't infer if groups is empty visibleRecordIds must be populated
+      // but the extra safety isn't bad. (istanbul also can't ignore just the ??)
+      // istanbul ignore next
+      return this._data.groupData.visibleRecordIds ?? [];
+    }
+
+    // Otherwise build the recordId's from children groups
+    const recordIds = [];
+    for (const group of this.groups) {
+      recordIds.push(...group.recordIds);
+    }
+    return recordIds;
+  }
+
+  /**
+   * Anytime the recordIds to return could have changed, we clear this so that
+   * the next time the user requests recordIds it recomputes
+   *
+   * @internal
+   */
+  _invalidateComputedRecordIds() {
+    this._orderedRecordIds = null;
+  }
+
+  /**
+   * Ordered array of all the record ids inside this group, in group order.
+   * This returns all recordIds of all children groups (in grouped order).
+   * Watchable.
+   */
+  get recordIds() {
+    (0, _error_utils.invariant)(this.isDataLoaded, 'GroupedRecordQueryResult data is not loaded');
+    if (this._orderedRecordIds === null) {
+      this._orderedRecordIds = this._computeRecordIds();
+    }
+    return this._orderedRecordIds;
+  }
+
+  /**
+   * The fields that were used to create the parent RecordQueryResult that created this GroupedRecordQueryResult.
+   * This is separate from the field/fieldId property - which is the field this grouping is based upon.
+   * Null if fields were not specified, which means the RecordQueryResult
+   * will load all fields in the table.
+   */
+  get fields() {
+    (0, _error_utils.invariant)(this.isDataLoaded, 'GroupedRecordQueryResult data is not loaded');
+    return this._parentQueryResult.fields;
+  }
+
+  /** @inheritdoc */
+  watch(keys, callback, context) {
+    // TODO (SeanKeenan): This provides events even if they occur outside of this group
+    // This is an issue that needs to be fixed before this API is made public
+    const validKeys = this._parentQueryResult.watch(keys, callback, context);
+    return validKeys;
+  }
+
+  /** @inheritdoc */
+  unwatch(keys, callback, context) {
+    return this._parentQueryResult.unwatch(keys, callback, context);
+  }
+
+  /** @inheritdoc */
+  async loadDataAsync() {
+    await super.loadDataAsync();
+  }
+
+  /** @internal */
+  _getChangedKeysOnLoad() {
+    return this._parentQueryResult._getChangedKeysOnLoad();
+  }
+
+  /** @internal */
+  async _loadDataAsync() {
+    this._parentQueryResult.__groupedRecordQueryResultPool.registerObjectForReuseStrong(this);
+
+    // Ensure we invalidate our memoized computed recordIds whenever a relevant hook changes
+    // TODO: (SeanKeenan) At the moment this should never be relevant, because groups are recreated
+    // anytime the groups change - but this is how it should work once groups persist AND
+    // watching recordIds only changes if records in this group change.
+    // In the meantime this does ensure that a deleted GroupedRecordQuery with stale recordIds
+    // doesn't return the cached array.
+    this.watch(['recordIds', 'groups', 'groupLevels'], this._invalidateComputedRecordIds, this);
+    this.watch(['recordIds'], this._invalidateRecordIdsSet, this);
+    return this._getChangedKeysOnLoad();
+  }
+
+  /** @internal */
+  _unloadData() {
+    // Ensure we invalidate our memoized computed recordIds whenever a relevant hook changes
+    this.unwatch(['recordIds', 'groups', 'groupLevels'], this._invalidateComputedRecordIds, this);
+    this.unwatch(['recordIds'], this._invalidateRecordIdsSet, this);
+
+    // Invalidate both of the caches, as this object can no longer be accessed
+    this._invalidateComputedRecordIds();
+    this._invalidateRecordIdsSet();
+    this._unloadChildrenGroupsIfNeeded();
+    this._parentQueryResult.__groupedRecordQueryResultPool.unregisterObjectForReuseStrong(this);
+  }
+
+  /** @internal */
+  get __poolKey() {
+    // TODO (SeanKeenan) We don't have an actual groupId, but while id is unique; this should have id removed
+    return `${this._serializedOpts}::${this.id}`;
+  }
+
+  /**
+   * This model doesn't actually load data, but it does use the `_data`
+   * property so that checks for model deletion behave appropriately.
+   *
+   * This is considered deleted if the parent query result has been deleted.
+   *
+   * We return groupData, instead of precomputing all children groups because
+   * we perform the computation+caching lazily on request
+   *
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    if (this._parentQueryResult._dataOrNullIfDeleted === null) {
+      return null;
+    }
+    return {
+      groupData: this._groupData,
+      groupLevels: this._groupLevels
+    };
+  }
+
+  /** @inheritdoc */
+  get isDataLoaded() {
+    return this._parentQueryResult.isDataLoaded;
+  }
+
+  /** @internal */
+  _unloadChildrenGroupsIfNeeded() {
+    if (this._orderedChildrenGroups) {
+      for (const group of this._orderedChildrenGroups) {
+        group.unloadData();
+      }
+    }
+  }
+
+  /** @internal */
+  _invalidateRecordIdsSet() {
+    this._recordIdsSet = null;
+  }
+
+  /** @internal */
+  _getOrGenerateRecordIdsSet() {
+    // TODO (SeanKeenan): this logic is duplicated in tableOrViewQueryResult
+    if (!this._recordIdsSet) {
+      const recordIdsSet = {};
+      for (const recordId of this.recordIds) {
+        recordIdsSet[recordId] = true;
+      }
+      this._recordIdsSet = recordIdsSet;
+    }
+    return this._recordIdsSet;
+  }
+}
+var _default = exports.default = GroupedRecordQueryResult;