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

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

@@ -0,0 +1,553 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getLinkedTableId = exports.default = void 0;
+var _field_core = require("../../shared/types/field_core");
+var _error_utils = require("../../shared/error_utils");
+var _record_query_result = _interopRequireDefault(require("./record_query_result"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks/models: RecordQueryResult */ /** */
+
+const getLinkedTableId = field => {
+  const options = field.options;
+  const linkedTableId = options && options.linkedTableId;
+  (0, _error_utils.invariant)(typeof linkedTableId === 'string', 'linkedTableId must exist');
+  return linkedTableId;
+};
+
+/** internal */
+exports.getLinkedTableId = getLinkedTableId;
+/**
+ * Represents a set of records from a LinkedRecord cell value. See {@link RecordQueryResult} for main
+ * documentation.
+ *
+ * Do not instantiate. You can get instances of this class by calling
+ * `record.selectLinkedRecordsFromCell`.
+ *
+ * @docsPath models/query results/LinkedRecordsQueryResult
+ */
+class LinkedRecordsQueryResult extends _record_query_result.default {
+  /** @internal */
+  static _className = 'LinkedRecordsQueryResult';
+
+  // the record containing the linked-record cell this is a query of.
+  /** @internal */
+
+  // the cell's field in the record
+  /** @internal */
+
+  // the table we're linking to
+  /** @internal */
+
+  // the records store for the origin table
+  /** @internal */
+
+  // the records store for the linked table
+  /** @internal */
+
+  // a RecordQueryResult containing all the rows in the linked table
+  /** @internal */
+
+  // is the query result currently valid. if the field config changes to link
+  // to another table or not be a linked record field at all, isValid will
+  // become false. once a LinkedRecordsQueryResult has become invalid, it will
+  // not become valid again.
+  /** @internal */
+  _isValid = true;
+  // a lazily-generated set of the record ids in the result set.
+  /** @internal */
+  _computedRecordIdsSet = null;
+  // a lazily-generated array of the record ids in the query result.
+  /** @internal */
+  _computedFilteredSortedRecordIds = null;
+  // how many times has each 'cellValuesInField:$FieldId' been watched?
+  /** @internal */
+  _cellValueChangeHandlerByFieldId = {};
+
+  /** @internal */
+  constructor(record, field, normalizedOpts, sdk) {
+    super(sdk, normalizedOpts);
+    (0, _error_utils.invariant)(record.parentTable === field.parentTable, 'record and field must belong to the same table');
+    this._record = record;
+    this._field = field;
+    this._linkedTable = normalizedOpts.table;
+    this._originRecordStore = this._sdk.base.__getRecordStore(this._record.parentTable.id);
+    this._linkedRecordStore = normalizedOpts.recordStore;
+
+    // we could rely on RecordQueryResult's reuse pool to make sure we get back
+    // the same RecordQueryResult every time, but that would make it much harder
+    // to make sure we unwatch everything from the old RecordQueryResult if e.g.
+    // the field config changes to point at a different table
+    this._linkedQueryResult = this._linkedTable.__tableOrViewQueryResultPool.getObjectForReuse(this._sdk, this._linkedTable, normalizedOpts);
+  }
+
+  /**
+   * Is the query result currently valid? This value always starts as 'true',
+   * but can become false if the record from which this result was created is
+   * deleted, if the field is deleted, if the field config changes to link to
+   * a different table, or if the field config changes to link to a type
+   * other than MULTIPLE_RECORD_LINKS. Once `isValid` has become false, it
+   * will never become true again. Many fields will throw on attempting to
+   * access them, and watches will no longer fire.
+   */
+  get isValid() {
+    return this._isValid;
+  }
+
+  /**
+   * The table that records in this RecordQueryResult are part of
+   *
+   * @internal (since we may not be able to return parent model instances in the immutable models world)
+   */
+  get parentTable() {
+    (0, _error_utils.invariant)(this.isValid, 'LinkedRecordsQueryResult is no longer valid');
+    return this._linkedTable;
+  }
+
+  /**
+   * Ordered array of all the linked record ids. Watchable.
+   */
+  get recordIds() {
+    (0, _error_utils.invariant)(this.isValid, 'LinkedRecordsQueryResult is no longer valid');
+    (0, _error_utils.invariant)(this.isDataLoaded, 'LinkedRecordsQueryResult data is not loaded');
+
+    // record ids are lazily generated
+    this._generateComputedDataIfNeeded();
+    (0, _error_utils.invariant)(this._computedFilteredSortedRecordIds, 'no recordIds');
+    return this._computedFilteredSortedRecordIds;
+  }
+
+  /**
+   * Ordered array of all the linked records. Watchable.
+   */
+  get records() {
+    (0, _error_utils.invariant)(this.isValid, 'LinkedRecordsQueryResult is no longer valid');
+    return this.recordIds.map(recordId => {
+      const record = this._linkedRecordStore.getRecordByIdIfExists(recordId);
+      (0, _error_utils.invariant)(record, 'No record for id: %s', recordId);
+      return record;
+    });
+  }
+
+  /**
+   * The fields that were used to create this LinkedRecordsQueryResult.
+   */
+  get fields() {
+    (0, _error_utils.invariant)(this.isValid, 'LinkedRecordsQueryResult is no longer valid');
+    return this._linkedQueryResult.fields;
+  }
+
+  /** @inheritdoc */
+  watch(keys, callback, context) {
+    (0, _error_utils.invariant)(this.isValid, 'cannot watch an invalid LinkedRecordsQueryResult');
+    const validKeys = super.watch(keys, callback, context);
+    for (const key of validKeys) {
+      if (key === _record_query_result.default.WatchableKeys.cellValues) {
+        this._watchLinkedQueryCellValuesIfNeededAfterWatch();
+      }
+      if (key.startsWith(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix)) {
+        const fieldId = key.substring(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix.length);
+        this._watchLinkedQueryCellValuesInFieldIfNeededAfterWatch(fieldId);
+      }
+    }
+    return validKeys;
+  }
+
+  /** @inheritdoc */
+  unwatch(keys, callback, context) {
+    const arrayKeys = Array.isArray(keys) ? keys : [keys];
+    for (const key of arrayKeys) {
+      if (key === _record_query_result.default.WatchableKeys.cellValues) {
+        this._unwatchLinkedQueryCellValuesIfPossibleBeforeUnwatch();
+      }
+      if (key.startsWith(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix)) {
+        const fieldId = key.substring(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix.length);
+        this._unwatchLinkedQueryCellValuesInFieldIfPossibleBeforeUnwatch(fieldId);
+      }
+    }
+    return super.unwatch(arrayKeys, callback, context);
+  }
+
+  /** @inheritdoc */
+  async loadDataAsync() {
+    await super.loadDataAsync();
+
+    // This condition cannot be deterministically reproduced in the testing
+    // environment.
+    // istanbul ignore if
+    if (!this.isDataLoaded) {
+      // data still might not be loaded after the promise resolves if the
+      // linked table changed. in that case, call again:
+      await this.loadDataAsync();
+      // there has to be an unloadData call for every loadDataAsync call.
+      // call it here to offset calling loadDataAsync a second time
+      this.unloadData();
+    }
+  }
+
+  /** @internal */
+  async _loadDataAsync() {
+    this._record.__linkedRecordsQueryResultPool.registerObjectForReuseStrong(this);
+    this._watchOrigin();
+    this._watchLinkedQueryResult();
+    const initiallyLoaded = this._linkedQueryResult.isDataLoaded;
+    await Promise.all([this._sdk.base.__getRecordStore(this._record.parentTable.id).loadCellValuesInFieldIdsAsync([this._field.id]), this._linkedQueryResult.loadDataAsync(), this._loadRecordColorsAsync()]);
+    this._invalidateComputedData();
+    const changedKeys = ['records', 'recordIds', 'recordColors'];
+
+    // If the linked query result was not initially loaded, then the
+    // `cellValues` event will be emitted via `_onLinkedCellValuesChange`.
+    // Otherwise, it must be explicitly included here in order to promote
+    // consistency.
+    if (initiallyLoaded) {
+      changedKeys.push('cellValues');
+    }
+    const fieldIds = this._normalizedOpts.fieldIdsOrNullIfAllFields || this.parentTable.fields.map(field => field.id);
+    for (const fieldId of fieldIds) {
+      changedKeys.push(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix + fieldId);
+    }
+    return changedKeys;
+  }
+
+  /** @internal */
+  _unloadData() {
+    // The inverse of this condition cannot be deterministically reproduced
+    // in the testing environment.
+    // istanbul ignore else
+    if (this.isValid) {
+      this._record.__linkedRecordsQueryResultPool.unregisterObjectForReuseStrong(this);
+      this._unwatchOrigin();
+      this._unwatchLinkedQueryResult();
+      this._originRecordStore.unloadCellValuesInFieldIds([this._field.id]);
+      this._linkedQueryResult.unloadData();
+      this._unloadRecordColors();
+      this._invalidateComputedData();
+    }
+  }
+
+  /**
+   * the key used to identify this query result in ObjectPool
+   *
+   * @hidden
+   */
+  get __poolKey() {
+    return `${this._serializedOpts}::${this._field.id}::${this._linkedTable.id}::${this.isValid}`;
+  }
+
+  /** @internal */
+  get _cellValuesWatchCount() {
+    return (this._changeWatchersByKey[_record_query_result.default.WatchableKeys.cellValues] || []).length;
+  }
+
+  /** @internal */
+  _watchLinkedQueryCellValuesIfNeededAfterWatch() {
+    if (this._cellValuesWatchCount === 1) {
+      this._watchLinkedQueryCellValues();
+    }
+  }
+
+  /** @internal */
+  _unwatchLinkedQueryCellValuesIfPossibleBeforeUnwatch() {
+    if (this._cellValuesWatchCount === 1 && this.isValid) {
+      this._unwatchLinkedQueryCellValues();
+    }
+  }
+
+  /** @internal */
+  get _cellValueWatchCountByFieldId() {
+    const countByFieldId = {};
+    const watchKeys = Object.keys(this._changeWatchersByKey).filter(key => {
+      return key.startsWith(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix);
+    });
+    for (const watchKey of watchKeys) {
+      const fieldId = watchKey.slice(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix.length);
+      countByFieldId[fieldId] = this._changeWatchersByKey[watchKey].length;
+    }
+    return countByFieldId;
+  }
+
+  /** @internal */
+  _watchLinkedQueryCellValuesInFieldIfNeededAfterWatch(fieldId) {
+    if (this._cellValueWatchCountByFieldId[fieldId] === 1 && this.isValid) {
+      this._watchLinkedQueryCellValuesInField(fieldId);
+    }
+  }
+
+  /** @internal */
+  _unwatchLinkedQueryCellValuesInFieldIfPossibleBeforeUnwatch(fieldId) {
+    (0, _error_utils.invariant)(this._cellValueWatchCountByFieldId[fieldId], "cellValuesInField:%s over-free'd", fieldId);
+    if (this._cellValueWatchCountByFieldId[fieldId] === 1 && this.isValid) {
+      this._unwatchLinkedQueryCellValuesInField(fieldId);
+    }
+  }
+
+  /** @internal */
+  _watchOrigin() {
+    // if the cell values in the record change, we need to invalidate our
+    // cached data and notify watchers
+    this._record.watch(`cellValueInField:${this._field.id}`, this._onOriginCellValueChange, this);
+    // if the field config changes, we need to invalidate cached data,
+    // and potentially start watching a different table
+    this._field.watch('type', this._onOriginFieldConfigChange, this);
+    this._field.watch('options', this._onOriginFieldConfigChange, this);
+    // if the underlying record is deleted, we need to invalidate this
+    // result
+    this._originRecordStore.watch('recordIds', this._onOriginRecordsChange, this);
+    // if the linked field in the origin table is deleted, we need to
+    // invalidate this result
+    this._record.parentTable.watch('fields', this._onOriginFieldsChange, this);
+  }
+
+  /** @internal */
+  _unwatchOrigin() {
+    this._record.unwatch(`cellValueInField:${this._field.id}`, this._onOriginCellValueChange, this);
+    this._field.unwatch('type', this._onOriginFieldConfigChange, this);
+    this._field.unwatch('options', this._onOriginFieldConfigChange, this);
+    this._originRecordStore.unwatch('recordIds', this._onOriginRecordsChange, this);
+    this._record.parentTable.unwatch('fields', this._onOriginFieldsChange, this);
+  }
+
+  /** @internal */
+  _watchLinkedQueryResult() {
+    // in the linked table, all we care about is the set of recordIds.
+    // this watch fire when they're added/removed and when they change
+    // order. we only care about order, because add/remove is handled by
+    // watching the origin record
+    this._linkedQueryResult.watch('recordIds', this._onLinkedRecordIdsChange, this);
+  }
+
+  /** @internal */
+  _unwatchLinkedQueryResult() {
+    this._linkedQueryResult.unwatch('recordIds', this._onLinkedRecordIdsChange, this);
+  }
+
+  /** @internal */
+  _watchLinkedQueryCellValues() {
+    this._linkedQueryResult.watch('cellValues', this._onLinkedCellValuesChange, this);
+  }
+
+  /** @internal */
+  _unwatchLinkedQueryCellValues() {
+    this._linkedQueryResult.unwatch('cellValues', this._onLinkedCellValuesChange, this);
+  }
+
+  /** @internal */
+  _watchLinkedQueryCellValuesInField(fieldId) {
+    this._linkedQueryResult.watch(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix + fieldId, this._getOnLinkedCellValuesInFieldChange(fieldId), this);
+  }
+
+  /** @internal */
+  _unwatchLinkedQueryCellValuesInField(fieldId) {
+    this._linkedQueryResult.unwatch(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix + fieldId, this._getOnLinkedCellValuesInFieldChange(fieldId), this);
+  }
+
+  /** @internal */
+  _onLinkedRecordIdsChange() {
+    if (!this.isDataLoaded || this._record.isDeleted) {
+      //TODO(jamesmoody-at): Adding this._dataOrNullIfDeleted as an exit condition here is a temporary fix to address an issue where
+      // we are not reseting isValid to true while restoring deleted records that contain linked record fields. It seems the only way
+      // to do this is by creating a new LinkRecordsQueryResult instance but it seems like we might be reusing the original instance
+      // that we've already set isValid to false with. We'll need to do more investigating to figure out the right way to restore these
+      // records while keeping the behavior of isValid consistent
+      return;
+    }
+    (0, _error_utils.invariant)(this.isValid, 'watch key change event whilst invalid');
+    this._invalidateComputedData();
+
+    // we don't actually know at this stage whether anything changed or
+    // not. it may have done though, so notify watchers
+    this._onChange('records');
+    this._onChange('recordIds');
+  }
+
+  /**
+   * This model doesn't use the `_data` computed property it inherits from
+   * AbstractModel. It implements the following method only so that internal
+   * checks for model deletion behave appropriately (the data itself is
+   * inconsequential).
+   *
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    if (this._record.isDeleted || this._linkedRecordStore.isDeleted) {
+      return null;
+    }
+    return {};
+  }
+
+  /** @internal */
+  _onLinkedCellValuesChange(queryResult, key, changes) {
+    (0, _error_utils.invariant)(this.isValid, 'watch key change event whilst invalid');
+    if (changes && changes.fieldIds && changes.recordIds) {
+      const recordIdsSet = this._getOrGenerateRecordIdsSet();
+      const recordIds = changes.recordIds.filter(id => recordIdsSet[id] === true);
+      if (recordIds.length) {
+        this._onChange('cellValues', {
+          fieldIds: changes.fieldIds,
+          recordIds
+        });
+      }
+    } else {
+      this._onChange('cellValues');
+    }
+  }
+
+  /** @internal */
+  _getOnLinkedCellValuesInFieldChange(fieldId) {
+    if (!this._cellValueChangeHandlerByFieldId[fieldId]) {
+      this._cellValueChangeHandlerByFieldId[fieldId] = (queryResult, key, recordIds) => {
+        (0, _error_utils.invariant)(this.isValid, 'watch key change event whilst invalid');
+
+        // The linked record may finish loading before its parent. In
+        // that case, the appropriate events will be triggered by the
+        // `_loadDataAsync` method.
+        if (!this.isDataLoaded) {
+          return;
+        }
+
+        // The `else` branch will only be reached when the underlying
+        // `RecordOrViewQueryResult` is loaded, unloaded, and then
+        // loaded again. Because that query result is not directly
+        // exposed to consumers, the condition can only be met when the
+        // SDK is misused (e.g. repeatedly freeing related query
+        // results). The `else` branch attempts to handle that
+        // situation in a logical way, but it is not tested because it
+        // is fundamentally invalid.
+        // istanbul ignore else
+        if (Array.isArray(recordIds)) {
+          const recordIdsSet = this._getOrGenerateRecordIdsSet();
+          const filteredRecordIds = recordIds.filter(id => typeof id === 'string' && recordIdsSet[id] === true);
+          if (filteredRecordIds.length) {
+            this._onChange(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix + fieldId, filteredRecordIds);
+          }
+        } else {
+          this._onChange(_record_query_result.default.WatchableCellValuesInFieldKeyPrefix + fieldId);
+        }
+      };
+    }
+    return this._cellValueChangeHandlerByFieldId[fieldId];
+  }
+
+  /** @internal */
+  _onOriginCellValueChange() {
+    if (!this.isDataLoaded || this._field.isDeleted) {
+      //TODO(jamesmoody-at): Adding this._dataOrNullIfDeleted as an exit condition here is a temporary fix to address an issue where
+      // we are not resetting isValid to true while restoring deleted records that contain linked record fields. It seems the only way
+      // to do this is by creating a new LinkRecordsQueryResult instance but it seems like we might be reusing the original instance
+      // that we've already set isValid to false with. We'll need to do more investigating to figure out the right way to restore these
+      // records while keeping the behavior of isValid consistent
+      return;
+    }
+    (0, _error_utils.invariant)(this.isValid, 'watch key change event whilst invalid');
+
+    // when the origin cell value (listing all the linked records) changes,
+    // invalidate all the data we have stored - we need to completely
+    // regenerate it
+    this._invalidateComputedData();
+
+    // notify watchers that our set of linked records has changed
+    this._onChange('records');
+    this._onChange('recordIds');
+  }
+
+  /** @internal */
+  _onOriginRecordsChange() {
+    if (this._record.isDeleted) {
+      this._isValid = false;
+    }
+  }
+
+  /** @internal */
+  _onOriginFieldsChange() {
+    if (this._field.isDeleted) {
+      this._isValid = false;
+    }
+  }
+
+  /** @internal */
+  _onOriginFieldConfigChange() {
+    (0, _error_utils.invariant)(this.isValid, 'watch key change event whilst invalid');
+    const type = this._field.type;
+    if (type !== _field_core.FieldType.MULTIPLE_RECORD_LINKS) {
+      this._invalidateQueryResult();
+      return;
+    }
+    const linkedTableId = getLinkedTableId(this._field);
+    if (linkedTableId !== this._linkedTable.id) {
+      this._invalidateQueryResult();
+      return;
+    }
+  }
+
+  /** @internal */
+  _invalidateQueryResult() {
+    if (this.isDataLoaded) {
+      this._unloadData();
+    }
+    if (this._cellValuesWatchCount > 0) {
+      this._unwatchLinkedQueryCellValues();
+    }
+    for (const fieldId of Object.keys(this._cellValueWatchCountByFieldId)) {
+      this._unwatchLinkedQueryCellValuesInField(fieldId);
+    }
+    this._isValid = false;
+    this._onChange('records');
+    this._onChange('recordIds');
+  }
+
+  /** @internal */
+  _invalidateComputedData() {
+    this._computedRecordIdsSet = null;
+    this._computedFilteredSortedRecordIds = null;
+  }
+
+  /** @internal */
+  _generateComputedDataIfNeeded() {
+    if (!this._computedRecordIdsSet) {
+      this._generateComputedData();
+    }
+  }
+
+  /** @internal */
+  _generateComputedData() {
+    const recordIdsSet = {};
+    const rawCellValue = this._record.getCellValue(this._field);
+    const cellValue = rawCellValue === null ? [] : rawCellValue;
+    (0, _error_utils.invariant)(Array.isArray(cellValue), 'cellValue should be array');
+    for (const linkedRecord of cellValue) {
+      (0, _error_utils.invariant)(linkedRecord && typeof linkedRecord === 'object', 'linked record should be object');
+      const recordId = linkedRecord.id;
+      (0, _error_utils.invariant)(typeof recordId === 'string', 'id should be present');
+
+      // We need to use the query result as the source of truth for
+      // recordIds, since when the client deletes a record from the linked
+      // table, we update it optimistically but the origin cell value
+      // doesn't update until receiving the push payload.
+      if (this._linkedQueryResult.hasRecord(recordId)) {
+        recordIdsSet[recordId] = true;
+      }
+    }
+    this._computedRecordIdsSet = recordIdsSet;
+    if (this._normalizedOpts.sorts && this._normalizedOpts.sorts.length) {
+      // when sorts are present, record order comes from the query result
+      this._computedFilteredSortedRecordIds = this._linkedQueryResult.recordIds.filter(recordId => recordIdsSet[recordId] === true);
+    } else {
+      // with no sorts, record order is the same as in the cell in the
+      // main Airtable UI. Since we generated recordIdsSet by iterating
+      // over the cell value, we're guaranteed that the key order matches
+      // the linked record order in the cell.
+      this._computedFilteredSortedRecordIds = Object.keys(recordIdsSet);
+    }
+  }
+
+  /** @internal */
+  _getOrGenerateRecordIdsSet() {
+    this._generateComputedDataIfNeeded();
+    const recordIdsSet = this._computedRecordIdsSet;
+    (0, _error_utils.invariant)(recordIdsSet, 'recordIdsSet must exist');
+    return recordIdsSet;
+  }
+}
+var _default = exports.default = LinkedRecordsQueryResult;