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

package/dist/cjs/base/models/field.js

@@ -0,0 +1,427 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+require("core-js/modules/es.array.filter.js");
+require("core-js/modules/es.array.iterator.js");
+require("core-js/modules/es.object.to-string.js");
+require("core-js/modules/es.set.js");
+require("core-js/modules/web.dom-collections.iterator.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 _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_core = require("../../shared/models/field_core");
+var _mutations = require("../types/mutations");
+var _private_utils = require("../../shared/private_utils");
+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: Field */ /** */
+/**
+ * Model class representing a field in a table.
+ *
+ * @example
+ * ```js
+ * import {base} from '@airtable/blocks';
+ *
+ * const table = base.getTableByName('Table 1');
+ * const field = table.getFieldByName('Name');
+ * console.log('The type of this field is', field.type);
+ * ```
+ * @docsPath models/Field
+ */
+var Field = /*#__PURE__*/function (_FieldCore) {
+  function Field() {
+    (0, _classCallCheck2.default)(this, Field);
+    return _callSuper(this, Field, arguments);
+  }
+  (0, _inherits2.default)(Field, _FieldCore);
+  return (0, _createClass2.default)(Field, [{
+    key: "availableAggregators",
+    get:
+    // The following method is untested because its implementation resists
+    // testing and because it is expected to be redesigned.
+    // istanbul ignore next
+    /**
+     * A list of available aggregators given this field's configuration.
+     *
+     * @example
+     * ```js
+     * const fieldAggregators = myField.availableAggregators;
+     * ```
+     */
+    function get() {
+      var airtableInterface = this._sdk.__airtableInterface;
+      var availableAggregatorKeysSet = new Set(airtableInterface.aggregators.getAvailableAggregatorKeysForField(this._data));
+      var _require = require('./models'),
+        aggregators = _require.aggregators;
+      return (0, _private_utils.values)(aggregators).filter(aggregator => {
+        return availableAggregatorKeysSet.has(aggregator.key);
+      });
+    }
+    // The following method is untested because its implementation resists
+    // testing and because it is expected to be redesigned.
+    // istanbul ignore next
+    /**
+     * Checks if the given aggregator is available for this field.
+     *
+     * @param aggregator The aggregator object or aggregator key.
+     * @example
+     * ```js
+     * import {aggregators} from '@airtable/blocks/models';
+     * const aggregator = aggregators.totalAttachmentSize;
+     *
+     * // Using an aggregator object
+     * console.log(myAttachmentField.isAggregatorAvailable(aggregator));
+     * // => true
+     *
+     * // Using an aggregator key
+     * console.log(myTextField.isAggregatorAvailable('totalAttachmentSize'));
+     * // => false
+     * ```
+     */
+  }, {
+    key: "isAggregatorAvailable",
+    value: function isAggregatorAvailable(aggregator) {
+      var aggregatorKey = typeof aggregator === 'string' ? aggregator : aggregator.key;
+      var airtableInterface = this._sdk.__airtableInterface;
+      var availableAggregatorKeys = airtableInterface.aggregators.getAvailableAggregatorKeysForField(this._data);
+      return availableAggregatorKeys.some(key => key === aggregatorKey);
+    }
+
+    /**
+     * Checks whether the current user has permission to perform the given name update.
+     *
+     * Accepts partial input, in the same format as {@link updateNameAsync}.
+     *
+     * Returns `{hasPermission: true}` if the current user can update the specified field,
+     * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
+     * used to display an error message to the user.
+     *
+     * @param name new name for the field
+     *
+     * @example
+     * ```js
+     * const updateFieldCheckResult = field.checkPermissionsForUpdateName();
+     *
+     * if (!updateFieldCheckResult.hasPermission) {
+     *     alert(updateFieldCheckResult.reasonDisplayString);
+     * }
+     * ```
+     */
+  }, {
+    key: "checkPermissionsForUpdateName",
+    value: function checkPermissionsForUpdateName(name) {
+      return this._sdk.__mutations.checkPermissionsForMutation({
+        type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_NAME,
+        tableId: this.parentTable.id,
+        id: this.id,
+        name
+      });
+    }
+
+    /**
+     * An alias for `checkPermissionsForUpdateName(options).hasPermission`.
+     *
+     * Checks whether the current user has permission to perform the name update.
+     *
+     * Accepts partial input, in the same format as {@link updateNameAsync}.
+     *
+     * @param name new name for the field
+     *
+     * @example
+     * ```js
+     * const canUpdateField = field.hasPermissionToUpdateName();
+     *
+     * if (!canUpdateField) {
+     *     alert('not allowed!');
+     * }
+     * ```
+     */
+  }, {
+    key: "hasPermissionToUpdateName",
+    value: function hasPermissionToUpdateName(name) {
+      return this.checkPermissionsForUpdateName(name).hasPermission;
+    }
+
+    /**
+     * Updates the name for this field.
+     *
+     * Throws an error if the user does not have permission to update the field, or if an invalid
+     * name is provided.
+     *
+     * This action is asynchronous. Unlike updates to cell values, updates to field name are
+     * **not** applied optimistically locally. You must `await` the returned promise before
+     * relying on the change in your extension.
+     *
+     * @param name new name for the field
+     *
+     * @example
+     * ```js
+     * await myTextField.updateNameAsync('My New Name');
+     * ```
+     */
+  }, {
+    key: "updateNameAsync",
+    value: (function () {
+      var _updateNameAsync = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee(name) {
+        return _regenerator.default.wrap(function _callee$(_context) {
+          while (1) switch (_context.prev = _context.next) {
+            case 0:
+              _context.next = 2;
+              return this._sdk.__mutations.applyMutationAsync({
+                type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_NAME,
+                tableId: this.parentTable.id,
+                id: this.id,
+                name
+              });
+            case 2:
+            case "end":
+              return _context.stop();
+          }
+        }, _callee, this);
+      }));
+      function updateNameAsync(_x) {
+        return _updateNameAsync.apply(this, arguments);
+      }
+      return updateNameAsync;
+    }()
+    /**
+     * Checks whether the current user has permission to perform the given description update.
+     *
+     * Accepts partial input, in the same format as {@link updateDescriptionAsync}.
+     *
+     * Returns `{hasPermission: true}` if the current user can update the specified field,
+     * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
+     * used to display an error message to the user.
+     *
+     * @param description new description for the field
+     *
+     * @example
+     * ```js
+     * const updateFieldCheckResult = field.checkPermissionsForUpdateDescription();
+     *
+     * if (!updateFieldCheckResult.hasPermission) {
+     *     alert(updateFieldCheckResult.reasonDisplayString);
+     * }
+     * ```
+     */
+    )
+  }, {
+    key: "checkPermissionsForUpdateDescription",
+    value: function checkPermissionsForUpdateDescription(description) {
+      return this._sdk.__mutations.checkPermissionsForMutation({
+        type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_DESCRIPTION,
+        tableId: this.parentTable.id,
+        id: this.id,
+        description
+      });
+    }
+
+    /**
+     * An alias for `checkPermissionsForUpdateDescription(options).hasPermission`.
+     *
+     * Checks whether the current user has permission to perform the description update.
+     *
+     * Accepts partial input, in the same format as {@link updateDescriptionAsync}.
+     *
+     * @param description new description for the field
+     *
+     * @example
+     * ```js
+     * const canUpdateField = field.hasPermissionToUpdateDescription();
+     *
+     * if (!canUpdateField) {
+     *     alert('not allowed!');
+     * }
+     * ```
+     */
+  }, {
+    key: "hasPermissionToUpdateDescription",
+    value: function hasPermissionToUpdateDescription(description) {
+      return this.checkPermissionsForUpdateDescription(description).hasPermission;
+    }
+
+    /**
+     * Updates the description for this field.
+     *
+     * To remove an existing description, pass `''` as the new description.
+     * `null` is also accepted and will be coerced to `''` for consistency with field creation.
+     *
+     * Throws an error if the user does not have permission to update the field, or if an invalid
+     * description is provided.
+     *
+     * This action is asynchronous. Unlike updates to cell values, updates to field descriptions are
+     * **not** applied optimistically locally. You must `await` the returned promise before
+     * relying on the change in your extension.
+     *
+     * @param description new description for the field
+     *
+     * @example
+     * ```js
+     * await myTextField.updateDescriptionAsync('This is a text field');
+     * ```
+     */
+  }, {
+    key: "updateDescriptionAsync",
+    value: (function () {
+      var _updateDescriptionAsync = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee2(description) {
+        return _regenerator.default.wrap(function _callee2$(_context2) {
+          while (1) switch (_context2.prev = _context2.next) {
+            case 0:
+              _context2.next = 2;
+              return this._sdk.__mutations.applyMutationAsync({
+                type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_DESCRIPTION,
+                tableId: this.parentTable.id,
+                id: this.id,
+                description
+              });
+            case 2:
+            case "end":
+              return _context2.stop();
+          }
+        }, _callee2, this);
+      }));
+      function updateDescriptionAsync(_x2) {
+        return _updateDescriptionAsync.apply(this, arguments);
+      }
+      return updateDescriptionAsync;
+    }()
+    /**
+     * Checks whether the current user has permission to perform the given options update.
+     *
+     * Accepts partial input, in the same format as {@link updateOptionsAsync}.
+     *
+     * Returns `{hasPermission: true}` if the current user can update the specified field,
+     * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
+     * used to display an error message to the user.
+     *
+     * @param options new options for the field
+     *
+     * @example
+     * ```js
+     * const updateFieldCheckResult = field.checkPermissionsForUpdateOptions();
+     *
+     * if (!updateFieldCheckResult.hasPermission) {
+     *     alert(updateFieldCheckResult.reasonDisplayString);
+     * }
+     * ```
+     */
+    )
+  }, {
+    key: "checkPermissionsForUpdateOptions",
+    value: function checkPermissionsForUpdateOptions(options) {
+      return this._sdk.__mutations.checkPermissionsForMutation({
+        type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_CONFIG,
+        tableId: this.parentTable.id,
+        id: this.id,
+        config: {
+          type: this.type,
+          options: options
+        }
+      });
+    }
+
+    /**
+     * An alias for `checkPermissionsForUpdateOptions(options).hasPermission`.
+     *
+     * Checks whether the current user has permission to perform the options update.
+     *
+     * Accepts partial input, in the same format as {@link updateOptionsAsync}.
+     *
+     * @param options new options for the field
+     *
+     * @example
+     * ```js
+     * const canUpdateField = field.hasPermissionToUpdateOptions();
+     *
+     * if (!canUpdateField) {
+     *     alert('not allowed!');
+     * }
+     * ```
+     */
+  }, {
+    key: "hasPermissionToUpdateOptions",
+    value: function hasPermissionToUpdateOptions(options) {
+      return this.checkPermissionsForUpdateOptions(options).hasPermission;
+    }
+
+    /**
+     * Updates the options for this field.
+     *
+     * Throws an error if the user does not have permission to update the field, if invalid
+     * options are provided, if this field has no writable options, or if updates to this field
+     * type is not supported.
+     *
+     * Refer to {@link FieldType} for supported field types, the write format for options, and
+     * other specifics for certain field types.
+     *
+     * This action is asynchronous. Unlike updates to cell values, updates to field options are
+     * **not** applied optimistically locally. You must `await` the returned promise before
+     * relying on the change in your extension.
+     *
+     * Optionally, you can pass an `opts` object as the second argument. See {@link UpdateFieldOptionsOpts}
+     * for available options.
+     *
+     * @param options new options for the field
+     * @param opts optional options to affect the behavior of the update
+     *
+     * @example
+     * ```js
+     * async function addChoiceToSelectField(selectField, nameForNewOption) {
+     *     const updatedOptions = {
+     *         choices: [
+     *             ...selectField.options.choices,
+     *             {name: nameForNewOption},
+     *         ]
+     *     };
+     *
+     *     if (selectField.hasPermissionToUpdateOptions(updatedOptions)) {
+     *         await selectField.updateOptionsAsync(updatedOptions);
+     *     }
+     * }
+     * ```
+     */
+  }, {
+    key: "updateOptionsAsync",
+    value: (function () {
+      var _updateOptionsAsync = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee3(options) {
+        var opts,
+          _args3 = arguments;
+        return _regenerator.default.wrap(function _callee3$(_context3) {
+          while (1) switch (_context3.prev = _context3.next) {
+            case 0:
+              opts = _args3.length > 1 && _args3[1] !== undefined ? _args3[1] : {};
+              _context3.next = 3;
+              return this._sdk.__mutations.applyMutationAsync({
+                type: _mutations.MutationTypes.UPDATE_SINGLE_FIELD_CONFIG,
+                tableId: this.parentTable.id,
+                id: this.id,
+                config: {
+                  type: this.type,
+                  options: options
+                },
+                opts
+              });
+            case 3:
+            case "end":
+              return _context3.stop();
+          }
+        }, _callee3, this);
+      }));
+      function updateOptionsAsync(_x3) {
+        return _updateOptionsAsync.apply(this, arguments);
+      }
+      return updateOptionsAsync;
+    }())
+  }]);
+}(_field_core.FieldCore);
+/** @internal */
+(0, _defineProperty2.default)(Field, "_className", 'Field');
+var _default = exports.default = Field;