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

package/dist/esm/shared/models/field_core.js

@@ -0,0 +1,288 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FieldCore = void 0;
+var _field_core = require("../types/field_core");
+var _private_utils = require("../private_utils");
+var _abstract_model = _interopRequireDefault(require("./abstract_model"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// This doesn't follow our enum naming conventions because we want the keys
+// to mirror the method/getter names on the model class.
+const WatchableFieldKeys = Object.freeze({
+  name: 'name',
+  type: 'type',
+  options: 'options',
+  isComputed: 'isComputed',
+  description: 'description',
+  isFieldSynced: 'isFieldSynced'
+});
+
+/**
+ * All the watchable keys in a field.
+ * - `name`
+ * - `type`
+ * - `options`
+ * - `isComputed`
+ * - `description`
+ */
+
+/** @hidden */
+class FieldCore extends _abstract_model.default {
+  /** @internal */
+  static _className = 'FieldCore';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableFieldKeys, key);
+  }
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * @internal
+   */
+  constructor(sdk, parentTable, fieldId) {
+    super(sdk, fieldId);
+    this._parentTable = parentTable;
+    this._cachedFieldTypeConfigOrNull = null;
+  }
+
+  /**
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    const tableData = this._baseData.tablesById[this.parentTable.id];
+    return tableData?.fieldsById[this._id] ?? null;
+  }
+  /**
+   * The table that this field belongs to. Should never change because fields aren't moved between tables.
+   *
+   * @internal (since we may not be able to return parent model instances in the immutable models world)
+   * @example
+   * ```js
+   * const field = myTable.getFieldByName('Name');
+   * console.log(field.parentTable.id === myTable.id);
+   * // => true
+   * ```
+   */
+  get parentTable() {
+    return this._parentTable;
+  }
+  /**
+   * The name of the field. Can be watched.
+   *
+   * @example
+   * ```js
+   * console.log(myField.name);
+   * // => 'Name'
+   * ```
+   */
+  get name() {
+    return this._data.name;
+  }
+  /**
+   * The type of the field. Can be watched.
+   *
+   * @example
+   * ```js
+   * console.log(myField.type);
+   * // => 'singleLineText'
+   * ```
+   */
+  get type() {
+    const {
+      type
+    } = this._getCachedConfigFromFieldTypeProvider();
+    // We intend to switch from "lookup" to "multipleLookupValues", but need to support both
+    // until the transition is complete. See <https://airtable.quip.com/VxaMAmAfUscs> for more.
+    // @ts-ignore
+    if (type === 'lookup') {
+      return _field_core.FieldType.MULTIPLE_LOOKUP_VALUES;
+    } else {
+      return type;
+    }
+  }
+  /**
+   * The configuration options of the field. The structure of the field's
+   * options depend on the field's type. `null` if the field has no options.
+   * See {@link FieldType} for more information on the options for each field
+   * type. Can be watched.
+   *
+   * @see {@link FieldType}
+   * @example
+   * ```js
+   * import {FieldType} from '@airtable/blocks/[placeholder-path]/models';
+   *
+   * if (myField.type === FieldType.CURRENCY) {
+   *     console.log(myField.options.symbol);
+   *     // => '$'
+   * }
+   * ```
+   */
+  get options() {
+    const {
+      options
+    } = this._getCachedConfigFromFieldTypeProvider();
+
+    // TODO: In the next breaking release freeze (inside of the cache) and replace
+    // FieldOptions with readonly<FieldOptions>.
+    // Today this is required because we re-use the fieldTypeProvider.getConfig response.
+    return options ? (0, _private_utils.cloneDeep)(options) : null;
+  }
+
+  // We use a cached response from FieldTypeProvider because getting the config can
+  // be an expensive operation. In particular when fieldConfigs are extremely large
+  // (eg: Select fields with lots of select options)
+  _getCachedConfigFromFieldTypeProvider() {
+    if (this._cachedFieldTypeConfigOrNull !== null) {
+      return this._cachedFieldTypeConfigOrNull;
+    }
+    const airtableInterface = this._sdk.__airtableInterface;
+    const appInterface = this._sdk.__appInterface;
+    this._cachedFieldTypeConfigOrNull = airtableInterface.fieldTypeProvider.getConfig(appInterface, this._data, this.parentTable.__getFieldNamesById());
+    return this._cachedFieldTypeConfigOrNull;
+  }
+  _clearCachedConfig() {
+    this._cachedFieldTypeConfigOrNull = null;
+  }
+
+  /**
+   * The type and options of the field to make type narrowing `FieldOptions` easier.
+   * See {@link FieldType} for more information on the options for each field type.
+   *
+   * @see {@link FieldConfig}
+   * @example
+   * const fieldConfig = field.config;
+   * if (fieldConfig.type === FieldType.SINGLE_SELECT) {
+   *     return fieldConfig.options.choices;
+   * } else if (fieldConfig.type === FieldType.MULTIPLE_LOOKUP_VALUES && fieldConfig.options.isValid) {
+   *     if (fieldConfig.options.result.type === FieldType.SINGLE_SELECT) {
+   *         return fieldConfig.options.result.options.choices;
+   *     }
+   * }
+   * return DEFAULT_CHOICES;
+   */
+  get config() {
+    return {
+      type: this.type,
+      options: this.options
+    };
+  }
+
+  /**
+   * `true` if this field is synced, `false` otherwise. A field is
+   * "synced" if it's source is from another airtable base or external data source
+   * like Google Calendar, Jira, etc..
+   *
+   * @hidden
+   */
+  get isFieldSynced() {
+    return this._data.isSynced ?? false;
+  }
+
+  /**
+   * `true` if this field is computed, `false` otherwise. A field is
+   * "computed" if it's value is not set by user input (e.g. autoNumber, formula,
+   * etc.). Can be watched
+   *
+   * @example
+   * ```js
+   * console.log(mySingleLineTextField.isComputed);
+   * // => false
+   * console.log(myAutoNumberField.isComputed);
+   * // => true
+   * ```
+   */
+  get isComputed() {
+    const airtableInterface = this._sdk.__airtableInterface;
+    return airtableInterface.fieldTypeProvider.isComputed(this._data);
+  }
+  /**
+   * `true` if this field is its parent table's primary field, `false` otherwise.
+   * Should never change because the primary field of a table cannot change.
+   */
+  get isPrimaryField() {
+    return this.id === this.parentTable.primaryField.id;
+  }
+
+  /**
+   * The description of the field, if it has one. Can be watched.
+   *
+   * @example
+   * ```js
+   * console.log(myField.description);
+   * // => 'This is my field'
+   * ```
+   */
+  get description() {
+    return this._data.description;
+  }
+  /**
+   * Attempt to parse a given string and return a valid cell value for the field's current config.
+   * Returns `null` if unable to parse the given string.
+   *
+   * @param string The string to parse.
+   * @example
+   * ```js
+   * const inputString = '42';
+   * const cellValue = myNumberField.convertStringToCellValue(inputString);
+   * console.log(cellValue === 42);
+   * // => true
+   * ```
+   */
+  convertStringToCellValue(string) {
+    const airtableInterface = this._sdk.__airtableInterface;
+    const appInterface = this._sdk.__appInterface;
+    const cellValue = airtableInterface.fieldTypeProvider.convertStringToCellValue(appInterface, string, this._data,
+    // The opt parseDateCellValueInColumnTimeZone is used here to ensure date string
+    // inputs are interpreted correctly according to the `timeZone` of the dateTime field.
+    {
+      parseDateCellValueInColumnTimeZone: this.type === _field_core.FieldType.DATE_TIME
+    });
+
+    // Temporarily bail out of validating computed values (since validation will crash)
+    // while we work out if we actually have to validate or not. Ideally we just delete all
+    // the validation
+    // TODO(emma): delete me or tidy me up
+    if (this.isComputed) {
+      return cellValue;
+    }
+
+    // TODO(emma): do we need to validate here?
+    const validationResult = airtableInterface.fieldTypeProvider.validateCellValueForUpdate(appInterface, cellValue, null, this._data);
+    if (validationResult.isValid) {
+      return cellValue;
+    } else {
+      return null;
+    }
+  }
+  /**
+   * @internal
+   */
+  __triggerOnChangeForDirtyPaths(dirtyPaths) {
+    // Always clear the cached config when anything on the field data model changes
+    this._clearCachedConfig();
+    if (dirtyPaths.name) {
+      this._onChange(WatchableFieldKeys.name);
+    }
+    if (dirtyPaths.type) {
+      this._onChange(WatchableFieldKeys.type);
+
+      // TODO: it would be better if we only trigger this when
+      // we know isComputed changed.
+      this._onChange(WatchableFieldKeys.isComputed);
+    }
+    if (dirtyPaths.typeOptions) {
+      this._onChange(WatchableFieldKeys.options);
+    }
+    if (dirtyPaths.description) {
+      this._onChange(WatchableFieldKeys.description);
+    }
+    if (dirtyPaths.isSynced) {
+      this._onChange(WatchableFieldKeys.isFieldSynced);
+    }
+  }
+}
+exports.FieldCore = FieldCore;

package/dist/esm/shared/models/mutations_core.js

@@ -0,0 +1,343 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MutationsCore = exports.MUTATIONS_MAX_BATCH_SIZE = void 0;
+var _mutations_core = require("../types/mutations_core");
+var _error_utils = require("../error_utils");
+var _private_utils = require("../private_utils");
+// Limit for how many items can be updated from a single batch mutation.
+// This is number of records for MULTIPLE_RECORDS type mutations, and number of global config paths
+// for SET_MULTIPLE_GLOBAL_CONFIG_PATHS.
+// Same limit is enforced liveapp-side
+const MUTATIONS_MAX_BATCH_SIZE = exports.MUTATIONS_MAX_BATCH_SIZE = 50;
+
+// Liveapp requests must be under 2mb in size: we enforce a 1.9mb limit here to allow space for
+// the other parts of the request
+const MUTATIONS_MAX_BODY_SIZE = 1.9 * 1024 * 1024;
+const MUTATION_HOLD_FOR_MS = 100;
+
+/** @hidden */
+class MutationsCore {
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @hidden */
+  constructor(sdk, session, base, applyModelChanges, applyGlobalConfigUpdates) {
+    this._airtableInterface = sdk.__airtableInterface;
+    this._session = session;
+    this._sdk = sdk;
+    this._base = base;
+    this._applyModelChanges = applyModelChanges;
+    this._applyGlobalConfigUpdates = applyGlobalConfigUpdates;
+  }
+
+  /** @hidden */
+  async applyMutationAsync(mutation) {
+    this._assertMutationIsValid(mutation);
+    // Limit check is after validity check so that we display errors for when users pass in
+    // objects correctly (eg updating linked records cell value to be a record object) -
+    // otherwise the limit check will fail due to circular objects being converted to JSON first
+    this._assertMutationUnderLimits(mutation);
+    const permissionCheck = this.checkPermissionsForMutation(mutation);
+    if (!permissionCheck.hasPermission) {
+      throw (0, _error_utils.spawnError)('Cannot apply %s mutation: %s', mutation.type, permissionCheck.reasonDisplayString);
+    }
+    const didApplyOptimisticUpdates = this._applyOptimisticUpdatesForMutation(mutation);
+    try {
+      await this._getAirtableInterfaceAsAirtableInterfaceCore().applyMutationAsync(mutation, {
+        holdForMs: MUTATION_HOLD_FOR_MS
+      });
+    } catch (err) {
+      if (didApplyOptimisticUpdates) {
+        // if we applied optimistic updates, we can't gracefully handle a promise rejection
+        // here - we can't un-apply optimistic updates, so the SDK's internal data model is
+        // in an unexpected state. Instead of letting this promise get rejected, throw an
+        // error after an async gap to crash the block, and make this promise await
+        // something that will never resolve so we don't run any of the developers error-
+        // handling code.
+        setTimeout(() => {
+          throw err;
+        }, 0);
+        await new Promise(() => {});
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  /** @hidden */
+  checkPermissionsForMutation(mutation) {
+    return this._getAirtableInterfaceAsAirtableInterfaceCore().checkPermissionsForMutation(mutation, this._base.__getBaseData());
+  }
+
+  // Not really sure why this is necessary. It seems like all callsites could just use
+  // this._airtableInterface directly, but TS complains.
+  /** @hidden */
+  _getAirtableInterfaceAsAirtableInterfaceCore() {
+    return this._airtableInterface;
+  }
+
+  /** @internal */
+  _assertMutationUnderLimits(mutation) {
+    // Two limits to check here:
+    // - for record-related mutations, it isn't above MUTATIONS_MAX_BATCH_SIZE
+    // - mutation payload size won't exceed liveapp request payload size limit
+    // Requests are sent as form-encoded utf-8 (1 byte characters)
+    if (encodeURIComponent(JSON.stringify(mutation)).length > MUTATIONS_MAX_BODY_SIZE) {
+      throw (0, _error_utils.spawnError)('Request exceeds maximum size limit of %s bytes', MUTATIONS_MAX_BODY_SIZE);
+    }
+    if (this._doesMutationExceedBatchSizeLimit(mutation)) {
+      throw (0, _error_utils.spawnError)('Request exceeds maximum batch size limit of %s items', MUTATIONS_MAX_BATCH_SIZE);
+    }
+  }
+
+  /** @internal */
+  _applyOptimisticUpdatesForMutation(mutation) {
+    // GlobalConfig updates are different to other mutations (on models): for models, we
+    // only apply optimistic updates if the relevant models are loaded, whereas for
+    // SET_MULTIPLE_GLOBAL_CONFIG_PATHS we always apply optimistic updates.
+    if (mutation.type === _mutations_core.MutationTypesCore.SET_MULTIPLE_GLOBAL_CONFIG_PATHS) {
+      // Not sure why this cast is necessary, but TS complains without it.
+      const _mutation = mutation;
+      this._applyGlobalConfigUpdates(_mutation.updates);
+      return true;
+    }
+    const modelChanges = this._getOptimisticModelChangesForMutation(mutation);
+    if (modelChanges.length > 0) {
+      this._applyModelChanges(modelChanges);
+      return true;
+    }
+    return false;
+  }
+
+  /** @internal */
+  _doesMutationExceedBatchSizeLimit(mutation) {
+    switch (mutation.type) {
+      case _mutations_core.MutationTypesCore.SET_MULTIPLE_RECORDS_CELL_VALUES:
+      case _mutations_core.MutationTypesCore.CREATE_MULTIPLE_RECORDS:
+        return mutation.records.length > MUTATIONS_MAX_BATCH_SIZE;
+      case _mutations_core.MutationTypesCore.DELETE_MULTIPLE_RECORDS:
+        return mutation.recordIds.length > MUTATIONS_MAX_BATCH_SIZE;
+      case _mutations_core.MutationTypesCore.SET_MULTIPLE_GLOBAL_CONFIG_PATHS:
+        return mutation.updates.length > MUTATIONS_MAX_BATCH_SIZE;
+      // The "default" case cannot be reached because this method is only
+      // invoked after the mutation type has been validated.
+      // istanbul ignore next
+      default:
+        return false;
+    }
+  }
+
+  /** @internal */
+  _assertFieldIsValidForMutation(field) {
+    if (field.isComputed) {
+      throw (0, _error_utils.spawnError)("Can't set cell values: Field '%s' is computed and cannot be set", field.name);
+    }
+  }
+
+  /** @internal */
+  _assertMutationIsValid(mutation) {
+    // We call validate the data (including any cell values) because if the data required for
+    // us to do that is already loaded in the block, we can error out before applying
+    // optimistic updates or sending the update to liveapp. That means that the error is
+    // recoverable. Once we apply optimistic updates, if liveapp rejects the update then we
+    // can't recover from that - we have to crash the block. We _could_ skip over these
+    // validations - it wouldn't cause issues outside of the block frame. But running them
+    // gives us slightly more confidence that we can do something other than completely crash
+    // the block in the event of an invalid mutation.
+
+    const appInterface = this._sdk.__appInterface;
+    switch (mutation.type) {
+      case _mutations_core.MutationTypesCore.SET_MULTIPLE_RECORDS_CELL_VALUES:
+        {
+          const {
+            tableId,
+            records
+          } = mutation;
+          const table = this._base.getTableByIdIfExists(tableId);
+          if (!table) {
+            throw (0, _error_utils.spawnError)("Can't set cell values: No table with id %s exists", tableId);
+          }
+
+          // For every mutation, we check that we're not trying to set fields that we don't support
+          // mutations for yet. When record data is loaded, we also check that the record we're
+          // updating actually exists and that the cell values are valid.
+          const recordStore = this._base.__getRecordStore(tableId);
+          const checkedFieldIds = new Set();
+          for (const record of records) {
+            let existingRecord = null;
+            if (this._isRecordStoreReadyForMutations(recordStore)) {
+              existingRecord = recordStore.getRecordByIdIfExists(record.id);
+              if (!existingRecord) {
+                throw (0, _error_utils.spawnError)("Can't set cell values: No record with id %s exists", record.id);
+              }
+            }
+            for (const fieldId of Object.keys(record.cellValuesByFieldId)) {
+              const field = table.getFieldByIdIfExists(fieldId);
+              if (!field) {
+                throw (0, _error_utils.spawnError)("Can't set cell values: No field with id %s exists in table '%s'", fieldId, table.name);
+              }
+              if (!checkedFieldIds.has(fieldId)) {
+                this._assertFieldIsValidForMutation(field);
+                checkedFieldIds.add(fieldId);
+              }
+              if (existingRecord && this._isFieldAvailableForMutation(recordStore, field.id)) {
+                const validationResult = this._airtableInterface.fieldTypeProvider.validateCellValueForUpdate(appInterface, record.cellValuesByFieldId[fieldId], existingRecord._getRawCellValue(field), field._data);
+                if (!validationResult.isValid) {
+                  throw (0, _error_utils.spawnError)("Can't set cell values: invalid cell value for field '%s'.\n%s", field.name, validationResult.reason);
+                }
+              }
+            }
+          }
+          return;
+        }
+      case _mutations_core.MutationTypesCore.DELETE_MULTIPLE_RECORDS:
+        {
+          const {
+            tableId,
+            recordIds
+          } = mutation;
+          const table = this._base.getTableByIdIfExists(tableId);
+          if (!table) {
+            throw (0, _error_utils.spawnError)("Can't delete records: No table with id %s exists", tableId);
+          }
+          const recordStore = this._base.__getRecordStore(tableId);
+          if (this._isRecordStoreReadyForMutations(recordStore)) {
+            for (const recordId of recordIds) {
+              const record = recordStore.getRecordByIdIfExists(recordId);
+              if (!record) {
+                throw (0, _error_utils.spawnError)("Can't delete records: No record with id %s exists in table '%s'", recordId, table.name);
+              }
+            }
+          }
+          return;
+        }
+      case _mutations_core.MutationTypesCore.CREATE_MULTIPLE_RECORDS:
+        {
+          const {
+            tableId,
+            records
+          } = mutation;
+          const checkedFieldIds = new Set();
+          const table = this._base.getTableByIdIfExists(tableId);
+          if (!table) {
+            throw (0, _error_utils.spawnError)("Can't create records: No table with id %s exists", tableId);
+          }
+          for (const record of records) {
+            for (const fieldId of Object.keys(record.cellValuesByFieldId)) {
+              const field = table.getFieldByIdIfExists(fieldId);
+              if (!field) {
+                throw (0, _error_utils.spawnError)("Can't create records: No field with id %s exists in table '%s'", fieldId, table.name);
+              }
+              if (!checkedFieldIds.has(fieldId)) {
+                this._assertFieldIsValidForMutation(field);
+                checkedFieldIds.add(fieldId);
+              }
+
+              // Current cell value is null since the record doesn't exist.
+              const validationResult = this._airtableInterface.fieldTypeProvider.validateCellValueForUpdate(appInterface, record.cellValuesByFieldId[fieldId], null, field._data);
+              if (!validationResult.isValid) {
+                throw (0, _error_utils.spawnError)("Can't create records: invalid cell value for field '%s'.\n%s", field.name, validationResult.reason);
+              }
+            }
+          }
+          return;
+        }
+      case _mutations_core.MutationTypesCore.SET_MULTIPLE_GLOBAL_CONFIG_PATHS:
+        {
+          // globalConfig update is a special case: globalConfig handles validation before
+          // invoking this mutation, since it relies on internal state to validate the
+          // paths being set.
+          return;
+        }
+      default:
+        throw (0, _error_utils.spawnError)('unhandled mutation type: %s', mutation.type);
+    }
+  }
+
+  /** @internal */
+  _getOptimisticModelChangesForMutation(mutation) {
+    switch (mutation.type) {
+      case _mutations_core.MutationTypesCore.SET_MULTIPLE_RECORDS_CELL_VALUES:
+        {
+          const {
+            tableId,
+            records
+          } = mutation;
+          const recordStore = this._base.__getRecordStore(tableId);
+          return records.flatMap(record => Object.keys(record.cellValuesByFieldId).filter(fieldId => this._isFieldAvailableForMutation(recordStore, fieldId)).map(fieldId => ({
+            path: ['tablesById', tableId, 'recordsById', record.id, 'cellValuesByFieldId', fieldId],
+            value: record.cellValuesByFieldId[fieldId]
+          })));
+        }
+      case _mutations_core.MutationTypesCore.DELETE_MULTIPLE_RECORDS:
+        {
+          const {
+            tableId,
+            recordIds
+          } = mutation;
+          return recordIds.map(recordId => ({
+            path: ['tablesById', tableId, 'recordsById', recordId],
+            value: undefined
+          }));
+        }
+      case _mutations_core.MutationTypesCore.CREATE_MULTIPLE_RECORDS:
+        {
+          const {
+            tableId,
+            records
+          } = mutation;
+          const recordStore = this._base.__getRecordStore(tableId);
+          return records.map(record => {
+            // Only apply optimistic changes for fields that are "available" for mutation
+            const filteredCellValuesByFieldId = {};
+            for (const [fieldId, cellValue] of (0, _private_utils.entries)(record.cellValuesByFieldId)) {
+              if (this._isFieldAvailableForMutation(recordStore, fieldId)) {
+                filteredCellValuesByFieldId[fieldId] = cellValue;
+              }
+            }
+            return {
+              path: ['tablesById', tableId, 'recordsById', record.id],
+              value: {
+                ...this._getDefaultRecordProperties(),
+                id: record.id,
+                cellValuesByFieldId: filteredCellValuesByFieldId
+              }
+            };
+          });
+        }
+
+      // The following branch is unreachable because this method's only
+      // call site is preceded by an explicit guard for this condition.
+      // istanbul ignore next
+      case _mutations_core.MutationTypesCore.SET_MULTIPLE_GLOBAL_CONFIG_PATHS:
+        {
+          throw (0, _error_utils.spawnError)('attempting to generate model updates for SET_MULTIPLE_GLOBAL_CONFIG_PATH');
+        }
+
+      // The following branch is unreachable because this method's only
+      // call site is preceded by an explicit guard for this condition.
+      // istanbul ignore next
+      default:
+        throw (0, _error_utils.spawnError)('unhandled mutation type: %s', mutation.type);
+    }
+  }
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+}
+exports.MutationsCore = MutationsCore;