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

package/dist/esm/shared/global_config.js

@@ -0,0 +1,399 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _watchable = _interopRequireDefault(require("./watchable"));
+var _error_utils = require("./error_utils");
+var _mutations_core = require("./types/mutations_core");
+var _private_utils = require("./private_utils");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks: globalConfig */ /** */
+
+/**
+ * You can watch any top-level key in global config. Use '*' to watch every change.
+ */
+
+// NOTE: GlobalConfig is essentially a wrapper around a generic key-value store.
+// It's called GlobalConfig in order to convey two main points about its intended
+// usage:
+// 1) that it is synced 'globally' across clients (at some point we might make
+//    a UserConfig which would be scoped to an individual user), and
+// 2) that is should be used mainly for configuration of the block (kv store
+//    as a name seems a bit too vague in terms of intended usage).
+/**
+ * A key-value store for persisting configuration options for an extension installation.
+ *
+ * The contents will be synced in real-time to all logged-in users of the installation.
+ * Contents will not be updated in real-time when the installation is running in
+ * a publicly shared base.
+ *
+ * Any key can be watched to know when the value of the key changes. If you want your
+ * component to automatically re-render whenever any key on GlobalConfig changes, try using the
+ * {@link useGlobalConfig} hook.
+ *
+ * You should not need to construct this object yourself.
+ *
+ * The maximum allowed size for a given GlobalConfig instance is 150kB.
+ * The maximum number of keys for a given GlobalConfig instance is 1000.
+ *
+ * @docsPath models/GlobalConfig
+ */
+class GlobalConfig extends _watchable.default {
+  /** @internal */
+  static _className = 'GlobalConfig';
+  /** @internal */
+  static _isWatchableKey(key) {
+    // The user can store any arbitrary key in the global config, so there's
+    // not much we can do here to check if a key is valid.
+    return true;
+  }
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * @internal
+   */
+  constructor(initialKvValuesByKey, sdk) {
+    super();
+    this._kvStore = initialKvValuesByKey;
+    this._sdk = sdk;
+    this._airtableInterface = sdk.__airtableInterface;
+  }
+
+  /**
+   * @internal
+   */
+  __getTopLevelKey(key) {
+    if (Array.isArray(key)) {
+      return key[0];
+    }
+    return key;
+  }
+  /**
+   * @internal
+   */
+  _formatKeyAsPath(key) {
+    if (!Array.isArray(key)) {
+      return [key];
+    }
+    return key;
+  }
+
+  /**
+   * @internal
+   */
+  _validatePath(path, store) {
+    const validation = this._airtableInterface.globalConfigHelpers.validatePath(path, store);
+    if (!validation.isValid) {
+      return validation;
+    }
+    if (path[0] === '*') {
+      return {
+        isValid: false,
+        reason: "cannot use '*' as a top-level key"
+      };
+    }
+    return {
+      isValid: true
+    };
+  }
+  /**
+   * Get the value at a path. Throws an error if the path is invalid.
+   *
+   * Returns undefined if no value exists at that path.
+   *
+   * @param key A string for the top-level key, or an array of strings describing the path to the value.
+   * @example
+   * ```js
+   * import {useGlobalConfig} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const globalConfig = useGlobalConfig();
+   *     const topLevelValue = globalConfig.get('topLevelKey');
+   *     const nestedValue = globalConfig.get(['topLevelKey', 'nested', 'deeply']);
+   * }
+   * ```
+   */
+  get(key) {
+    const path = this._formatKeyAsPath(key);
+    const pathValidationResult = this._validatePath(path, this._kvStore);
+    if (!pathValidationResult.isValid) {
+      throw (0, _error_utils.spawnError)('Invalid globalConfig path: %s', pathValidationResult.reason);
+    }
+    const value = (0, _private_utils.getValueAtOwnPath)(this._kvStore, path);
+    // value is returned as `unknown` from getValueAtOwnPath, but we know it must be a `GlobalConfigValue | void`
+    return value;
+  }
+
+  /**
+   * Checks whether the current user has permission to set the given global config key.
+   *
+   * Accepts partial input, in the same format as {@link setAsync}.
+   * The more information provided, the more accurate the permissions check will be.
+   *
+   * Returns `{hasPermission: true}` if the current user can set the specified key,
+   * `{hasPermission: false, reasonDisplayString: string}` otherwise.  `reasonDisplayString` may
+   * be used to display an error message to the user.
+   *
+   * @param key A string for the top-level key, or an array of strings describing the path to set.
+   * @param value The value to set at the specified path. Use `undefined` to delete the value at the given path.
+   *
+   * @example
+   * ```js
+   * // Check if user can update a specific key and value.
+   * const setCheckResult =
+   *     globalConfig.checkPermissionsForSet('favoriteColor', 'purple');
+   * if (!setCheckResult.hasPermission) {
+   *     alert(setCheckResult.reasonDisplayString);
+   * }
+   *
+   * // Check if user can update a specific key without knowing the value
+   * const setKeyCheckResult =
+   *     globalConfig.checkPermissionsForSet('favoriteColor');
+   *
+   * // Check if user can update globalConfig without knowing key or value
+   * const setUnknownKeyCheckResult = globalConfig.checkPermissionsForSet();
+   * ```
+   */
+  checkPermissionsForSet(key, value) {
+    return this.checkPermissionsForSetPaths([{
+      path: key ? this._formatKeyAsPath(key) : undefined,
+      value
+    }]);
+  }
+  /**
+   * An alias for `globalConfig.checkPermissionsForSet(key, value).hasPermission`.
+   *
+   * Checks whether the current user has permission to set the given global config key.
+   *
+   * Accepts partial input, in the same format as {@link setAsync}.
+   * The more information provided, the more accurate the permissions check will be.
+   *
+   * @param key A string for the top-level key, or an array of strings describing the path to set.
+   * @param value The value to set at the specified path. Use `undefined` to delete the value at the given path.
+   *
+   * @example
+   * ```js
+   * // Check if user can update a specific key and value.
+   * const canSetFavoriteColorToPurple =
+   *     globalConfig.hasPermissionToSet('favoriteColor', 'purple');
+   * if (!canSetFavoriteColorToPurple) {
+   *     alert('Not allowed!');
+   * }
+   *
+   * // Check if user can update a specific key without knowing the value
+   * const canSetFavoriteColor = globalConfig.hasPermissionToSet('favoriteColor');
+   *
+   * // Check if user can update globalConfig without knowing key or value
+   * const canSetGlobalConfig = globalConfig.hasPermissionToSet();
+   * ```
+   */
+  hasPermissionToSet(key, value) {
+    return this.checkPermissionsForSet(key, value).hasPermission;
+  }
+  /**
+   * Sets a value at a path. Throws an error if the path or value is invalid.
+   *
+   * This action is asynchronous: `await` the returned promise if you wish to wait for the
+   * update to be persisted to Airtable servers.
+   *
+   * Updates are applied optimistically locally, so your change will be reflected in
+   * {@link GlobalConfig} before the promise resolves.
+   *
+   * @param key A string for the top-level key, or an array of strings describing the path to set.
+   * @param value The value to set at the specified path. Use `undefined` to delete the value at the given path.
+   * @example
+   * ```js
+   * import {useGlobalConfig} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const globalConfig = useGlobalConfig();
+   *     const updateFavoriteColorIfPossible = (color) => {
+   *         if (globalConfig.hasPermissionToSet('favoriteColor', color)) {
+   *             globalConfig.setAsync('favoriteColor', color);
+   *         }
+   *         // The update is now applied within your extension (eg will be
+   *         // reflected in globalConfig) but are still being saved to
+   *         // Airtable servers (e.g. may not be updated for other users yet)
+   *     }
+   *
+   *     const updateFavoriteColorIfPossibleAsync = async (color) => {
+   *         if (globalConfig.hasPermissionToSet('favoriteColor', color)) {
+   *             await globalConfig.setAsync('favoriteColor', color);
+   *         }
+   *         // globalConfig updates have been saved to Airtable servers.
+   *         alert('favoriteColor has been updated');
+   *     }
+   * }
+   * ```
+   */
+  async setAsync(key, value) {
+    const path = this._formatKeyAsPath(key);
+    await this.setPathsAsync([{
+      path,
+      value
+    }]);
+  }
+  /**
+   * Checks whether the current user has permission to perform the specified updates to global config.
+   *
+   * Accepts partial input, in the same format as {@link setPathsAsync}.
+   * The more information provided, the more accurate the permissions check will be.
+   *
+   * Returns `{hasPermission: true}` if the current user can set the specified key,
+   * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
+   * used to display an error message to the user.
+   *
+   * @param updates The paths and values to set.
+   * @example
+   * ```js
+   * // Check if user can update a specific keys and values.
+   * const setPathsCheckResult = globalConfig.checkPermissionsForSet([
+   *     {path: ['topLevelKey1', 'nestedKey1'], value: 'foo'},
+   *     {path: ['topLevelKey2', 'nestedKey2'], value: 'bar'},
+   * ]);
+   * if (!setPathsCheckResult.hasPermission) {
+   *     alert(setPathsCheckResult.reasonDisplayString);
+   * }
+   *
+   * // Check if user could potentially set globalConfig values.
+   * // Equivalent to globalConfig.checkPermissionsForSet()
+   * const setUnknownPathsCheckResult =
+   *     globalConfig.checkPermissionsForSetPaths();
+   * ```
+   */
+  checkPermissionsForSetPaths(updates) {
+    return this._sdk.__mutations.checkPermissionsForMutation({
+      type: _mutations_core.MutationTypesCore.SET_MULTIPLE_GLOBAL_CONFIG_PATHS,
+      updates: updates ? updates.map(_ref => {
+        let {
+          path,
+          value
+        } = _ref;
+        return {
+          path: path || undefined,
+          value
+        };
+      }) : undefined
+    });
+  }
+  /**
+   * An alias for `globalConfig.checkPermissionsForSetPaths(updates).hasPermission`.
+   *
+   * Checks whether the current user has permission to perform the specified updates to global
+   * config.
+   *
+   * Accepts partial input, in the same format as {@link setPathsAsync}.
+   * The more information provided, the more accurate the permissions check will be.
+   *
+   * @param updates The paths and values to set.
+   *
+   * @example
+   * ```js
+   * // Check if user can update a specific keys and values.
+   * const canSetPaths = globalConfig.hasPermissionToSetPaths([
+   *     {path: ['topLevelKey1', 'nestedKey1'], value: 'foo'},
+   *     {path: ['topLevelKey2', 'nestedKey2'], value: 'bar'},
+   * ]);
+   * if (!canSetPaths) {
+   *     alert('not allowed!');
+   * }
+   *
+   * // Check if user could potentially set globalConfig values.
+   * // Equivalent to globalConfig.hasPermissionToSet()
+   * const canSetAnyPaths = globalConfig.hasPermissionToSetPaths();
+   * ```
+   */
+  hasPermissionToSetPaths(updates) {
+    return this.checkPermissionsForSetPaths(updates).hasPermission;
+  }
+  /**
+   * Sets multiple values. Throws if any path or value is invalid.
+   *
+   * This action is asynchronous: `await` the returned promise if you wish to wait for the
+   * updates to be persisted to Airtable servers.
+   * Updates are applied optimistically locally, so your changes will be reflected in
+   * {@link GlobalConfig} before the promise resolves.
+   *
+   * @param updates The paths and values to set.
+   * @example
+   * ```js
+   * import {useGlobalConfig} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const globalConfig = useGlobalConfig();
+   *     const updates = [
+   *         {path: ['topLevelKey1', 'nestedKey1'], value: 'foo'},
+   *         {path: ['topLevelKey2', 'nestedKey2'], value: 'bar'},
+   *     ];
+   *
+   *     const applyUpdatesIfPossible = () => {
+   *         if (globalConfig.hasPermissionToSetPaths(updates)) {
+   *             globalConfig.setPathsAsync(updates);
+   *         }
+   *         // The updates are now applied within your extension (eg will be reflected in
+   *         // globalConfig) but are still being saved to Airtable servers (e.g. they
+   *         // may not be updated for other users yet)
+   *     }
+   *
+   *     const applyUpdatesIfPossibleAsync = async () => {
+   *         if (globalConfig.hasPermissionToSetPaths(updates)) {
+   *             await globalConfig.setPathsAsync(updates);
+   *         }
+   *         // globalConfig updates have been saved to Airtable servers.
+   *         alert('globalConfig has been updated');
+   *     }
+   * }
+   * ```
+   */
+  async setPathsAsync(updates) {
+    // Validate the updates. Usually applyMutationAsync performs validations, but globalConfig
+    // updates are a special case because it relies on internal globalConfig state to validate.
+    // We check here, instead of deeper (e.g. on the liveapp side) so the user
+    // gets a more useful error stack trace.
+    if (!this.hasPermissionToSetPaths(updates)) {
+      throw (0, _error_utils.spawnError)('Your permission level does not allow setting globalConfig values');
+    }
+    for (const update of updates) {
+      const pathValidation = this._validatePath(update.path, this._kvStore);
+      if (!pathValidation.isValid) {
+        throw (0, _error_utils.spawnError)('Invalid globalConfig path: %s', pathValidation.reason);
+      }
+    }
+    await this._sdk.__mutations.applyMutationAsync({
+      type: _mutations_core.MutationTypesCore.SET_MULTIPLE_GLOBAL_CONFIG_PATHS,
+      updates
+    });
+  }
+  /**
+   * @internal
+   * this shouldn't be called directly - instead, use this._sdk.__applyGlobalConfigUpdates()
+   */
+  __setMultipleKvPaths(updates) {
+    // This helper validates updates and throw errors if necessary.
+    // To avoid the case where an error is encountered after some updates have already been
+    // applied (where we'd have to crash the block instead of letting the developer catch the
+    // error), it doesn't mutate the current store: it returns newKvStore with changes applied.
+    const {
+      newKvStore,
+      changedTopLevelKeys
+    } = this._airtableInterface.globalConfigHelpers.validateAndApplyUpdates(updates, this._kvStore);
+
+    // The updates are all good! Replace our kvStore with the new version.
+    this._kvStore = newKvStore;
+
+    // Now loop over the top level keys to fire change events.
+    for (const key of changedTopLevelKeys) {
+      this._onChange(key);
+    }
+    if (changedTopLevelKeys.length) {
+      this._onChange('*');
+    }
+  }
+}
+var _default = exports.default = GlobalConfig;

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

@@ -0,0 +1,94 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _error_utils = require("../error_utils");
+var _watchable = _interopRequireDefault(require("../watchable"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks/models: Abstract models */ /** */
+
+/**
+ * Abstract superclass for all models. You won't use this class directly.
+ *
+ * @docsPath models/advanced/AbstractModel
+ */
+class AbstractModel extends _watchable.default {
+  /** @internal */
+  static _className = 'AbstractModel';
+  /**
+   * This method is essentially abstract, but as of this writing, TypeScript
+   * does not support abstract static methods. This necessitates a concrete
+   * implementation which must be explicitly ignored by the test coverage
+   * tooling.
+   *
+   * @internal
+   */
+  // istanbul ignore next
+  static _isWatchableKey(key) {
+    // Override to return whether `key` is a valid watchable key.
+    return false;
+  }
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * @internal
+   */
+  constructor(sdk, modelId) {
+    super();
+    (0, _error_utils.invariant)(typeof modelId === 'string', '%s id should be a string', this.constructor._className);
+    this._sdk = sdk;
+    this._baseData = sdk.__airtableInterface.sdkInitData.baseData;
+    this._id = modelId;
+  }
+  /**
+   * The ID for this model.
+   */
+  get id() {
+    return this._id;
+  }
+  /**
+   * @internal
+   */
+
+  /**
+   * @internal
+   */
+  get _data() {
+    const data = this._dataOrNullIfDeleted;
+    if (data === null) {
+      throw this._spawnErrorForDeletion();
+    }
+    return data;
+  }
+  /**
+   * `true` if the model has been deleted, and `false` otherwise.
+   *
+   * In general, it's best to avoid keeping a reference to an object past the
+   * current event loop, since it may be deleted and trying to access any data
+   * of a deleted object (other than its ID) will throw. But if you keep a
+   * reference, you can use `isDeleted` to check that it's safe to access the
+   * model's data.
+   */
+  get isDeleted() {
+    return this._dataOrNullIfDeleted === null;
+  }
+  /**
+   * @internal
+   */
+  _spawnErrorForDeletion() {
+    return (0, _error_utils.spawnError)('%s has been deleted', this.constructor._className);
+  }
+  /**
+   * A string representation of the model for use in debugging.
+   */
+  toString() {
+    return `[${this.constructor._className} ${this.id}]`;
+  }
+}
+var _default = exports.default = AbstractModel;