@airtable/blocks 0.0.0-experimental-20e3506bd-20250428

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

@@ -0,0 +1,329 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FieldCore = void 0;
+require("core-js/modules/es.symbol.js");
+require("core-js/modules/es.symbol.description.js");
+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 _getPrototypeOf2 = _interopRequireDefault(require("@babel/runtime/helpers/getPrototypeOf"));
+var _inherits2 = _interopRequireDefault(require("@babel/runtime/helpers/inherits"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _field = require("../types/field");
+var _private_utils = require("../private_utils");
+var _abstract_model = _interopRequireDefault(require("./abstract_model"));
+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; })(); }
+// This doesn't follow our enum naming conventions because we want the keys
+// to mirror the method/getter names on the model class.
+var 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 */
+var FieldCore = exports.FieldCore = /*#__PURE__*/function (_AbstractModel) {
+  /**
+   * @internal
+   */
+  function FieldCore(sdk, parentTable, fieldId) {
+    var _this;
+    (0, _classCallCheck2.default)(this, FieldCore);
+    _this = _callSuper(this, FieldCore, [sdk, fieldId]);
+    /** @internal */
+    (0, _defineProperty2.default)(_this, "_parentTable", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(_this, "_cachedFieldTypeConfigOrNull", void 0);
+    _this._parentTable = parentTable;
+    _this._cachedFieldTypeConfigOrNull = null;
+    return _this;
+  }
+
+  /**
+   * @internal
+   */
+  (0, _inherits2.default)(FieldCore, _AbstractModel);
+  return (0, _createClass2.default)(FieldCore, [{
+    key: "_dataOrNullIfDeleted",
+    get: function get() {
+      var _tableData$fieldsById;
+      var tableData = this._baseData.tablesById[this.parentTable.id];
+      return (_tableData$fieldsById = tableData === null || tableData === void 0 ? void 0 : tableData.fieldsById[this._id]) !== null && _tableData$fieldsById !== void 0 ? _tableData$fieldsById : 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
+     * ```
+     */
+  }, {
+    key: "parentTable",
+    get: function get() {
+      return this._parentTable;
+    }
+    /**
+     * The name of the field. Can be watched.
+     *
+     * @example
+     * ```js
+     * console.log(myField.name);
+     * // => 'Name'
+     * ```
+     */
+  }, {
+    key: "name",
+    get: function get() {
+      return this._data.name;
+    }
+    /**
+     * The type of the field. Can be watched.
+     *
+     * @example
+     * ```js
+     * console.log(myField.type);
+     * // => 'singleLineText'
+     * ```
+     */
+  }, {
+    key: "type",
+    get: function get() {
+      var _this$_getCachedConfi = this._getCachedConfigFromFieldTypeProvider(),
+        type = _this$_getCachedConfi.type;
+      // 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.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.
+     * Can be watched.
+     *
+     * @see {@link FieldType}
+     * @example
+     * ```js
+     * import {FieldType} from '@airtable/blocks/models';
+     *
+     * if (myField.type === FieldType.CURRENCY) {
+     *     console.log(myField.options.symbol);
+     *     // => '$'
+     * }
+     * ```
+     */
+  }, {
+    key: "options",
+    get: function get() {
+      var _this$_getCachedConfi2 = this._getCachedConfigFromFieldTypeProvider(),
+        options = _this$_getCachedConfi2.options;
+
+      // 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)
+  }, {
+    key: "_getCachedConfigFromFieldTypeProvider",
+    value: function _getCachedConfigFromFieldTypeProvider() {
+      if (this._cachedFieldTypeConfigOrNull !== null) {
+        return this._cachedFieldTypeConfigOrNull;
+      }
+      var airtableInterface = this._sdk.__airtableInterface;
+      var appInterface = this._sdk.__appInterface;
+      this._cachedFieldTypeConfigOrNull = airtableInterface.fieldTypeProvider.getConfig(appInterface, this._data, this.parentTable.__getFieldNamesById());
+      return this._cachedFieldTypeConfigOrNull;
+    }
+  }, {
+    key: "_clearCachedConfig",
+    value: function _clearCachedConfig() {
+      this._cachedFieldTypeConfigOrNull = null;
+    }
+
+    /**
+     * The type and options of the field to make type narrowing `FieldOptions` easier.
+     *
+     * @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;
+     */
+  }, {
+    key: "config",
+    get: function get() {
+      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
+     */
+  }, {
+    key: "isFieldSynced",
+    get: function get() {
+      var _this$_data$isSynced;
+      return (_this$_data$isSynced = this._data.isSynced) !== null && _this$_data$isSynced !== void 0 ? _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
+     * ```
+     */
+  }, {
+    key: "isComputed",
+    get: function get() {
+      var 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.
+     */
+  }, {
+    key: "isPrimaryField",
+    get: function get() {
+      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'
+     * ```
+     */
+  }, {
+    key: "description",
+    get: function get() {
+      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
+     * ```
+     */
+  }, {
+    key: "convertStringToCellValue",
+    value: function convertStringToCellValue(string) {
+      var airtableInterface = this._sdk.__airtableInterface;
+      var appInterface = this._sdk.__appInterface;
+      var 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.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?
+      var validationResult = airtableInterface.fieldTypeProvider.validateCellValueForUpdate(appInterface, cellValue, null, this._data);
+      if (validationResult.isValid) {
+        return cellValue;
+      } else {
+        return null;
+      }
+    }
+    /**
+     * @internal
+     */
+  }, {
+    key: "__triggerOnChangeForDirtyPaths",
+    value: function __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);
+      }
+    }
+  }], [{
+    key: "_isWatchableKey",
+    value: /** @internal */
+    function _isWatchableKey(key) {
+      return (0, _private_utils.isEnumValue)(WatchableFieldKeys, key);
+    }
+  }]);
+}(_abstract_model.default);
+/** @internal */
+(0, _defineProperty2.default)(FieldCore, "_className", 'FieldCore');

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

@@ -0,0 +1,171 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MutationsCore = exports.MUTATIONS_MAX_BATCH_SIZE = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.promise.js");
+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 _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _mutations_core = require("../types/mutations_core");
+var _error_utils = require("../error_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
+var 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
+var MUTATIONS_MAX_BODY_SIZE = 1.9 * 1024 * 1024;
+var MUTATION_HOLD_FOR_MS = 100;
+
+/** @hidden */
+var MutationsCore = exports.MutationsCore = /*#__PURE__*/function () {
+  /** @hidden */
+  function MutationsCore(sdk, session, base, applyModelChanges, applyGlobalConfigUpdates) {
+    (0, _classCallCheck2.default)(this, MutationsCore);
+    /** @internal */
+    (0, _defineProperty2.default)(this, "_airtableInterface", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(this, "_session", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(this, "_sdk", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(this, "_base", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(this, "_applyModelChanges", void 0);
+    /** @internal */
+    (0, _defineProperty2.default)(this, "_applyGlobalConfigUpdates", void 0);
+    this._airtableInterface = sdk.__airtableInterface;
+    this._session = session;
+    this._sdk = sdk;
+    this._base = base;
+    this._applyModelChanges = applyModelChanges;
+    this._applyGlobalConfigUpdates = applyGlobalConfigUpdates;
+  }
+
+  /** @hidden */
+  return (0, _createClass2.default)(MutationsCore, [{
+    key: "applyMutationAsync",
+    value: (function () {
+      var _applyMutationAsync = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(mutation) {
+        var permissionCheck, didApplyOptimisticUpdates;
+        return _regenerator.default.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              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);
+              permissionCheck = this.checkPermissionsForMutation(mutation);
+              if (permissionCheck.hasPermission) {
+                _context.next = 5;
+                break;
+              }
+              throw (0, _error_utils.spawnError)('Cannot apply %s mutation: %s', mutation.type, permissionCheck.reasonDisplayString);
+            case 5:
+              didApplyOptimisticUpdates = this._applyOptimisticUpdatesForMutation(mutation);
+              _context.prev = 6;
+              _context.next = 9;
+              return this._getAirtableInterfaceAsAirtableInterfaceCore().applyMutationAsync(mutation, {
+                holdForMs: MUTATION_HOLD_FOR_MS
+              });
+            case 9:
+              _context.next = 20;
+              break;
+            case 11:
+              _context.prev = 11;
+              _context.t0 = _context["catch"](6);
+              if (!didApplyOptimisticUpdates) {
+                _context.next = 19;
+                break;
+              }
+              // 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 _context.t0;
+              }, 0);
+              _context.next = 17;
+              return new Promise(() => {});
+            case 17:
+              _context.next = 20;
+              break;
+            case 19:
+              throw _context.t0;
+            case 20:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee, this, [[6, 11]]);
+      }));
+      function applyMutationAsync(_x) {
+        return _applyMutationAsync.apply(this, arguments);
+      }
+      return applyMutationAsync;
+    }() /** @hidden */)
+  }, {
+    key: "checkPermissionsForMutation",
+    value: function 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 */
+  }, {
+    key: "_getAirtableInterfaceAsAirtableInterfaceCore",
+    value: function _getAirtableInterfaceAsAirtableInterfaceCore() {
+      return this._airtableInterface;
+    }
+
+    /** @internal */
+  }, {
+    key: "_assertMutationUnderLimits",
+    value: function _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 */
+  }, {
+    key: "_applyOptimisticUpdatesForMutation",
+    value: function _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.
+        var _mutation = mutation;
+        this._applyGlobalConfigUpdates(_mutation.updates);
+        return true;
+      }
+      var modelChanges = this._getOptimisticModelChangesForMutation(mutation);
+      if (modelChanges.length > 0) {
+        this._applyModelChanges(modelChanges);
+        return true;
+      }
+      return false;
+    }
+
+    /** @internal */
+  }]);
+}();