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

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

@@ -0,0 +1,520 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.WatchableTableKeys = void 0;
+var _table_core = require("../../shared/models/table_core");
+var _error_utils = require("../../shared/error_utils");
+var _private_utils = require("../../shared/private_utils");
+var _mutations = require("../types/mutations");
+var _record_query_result = _interopRequireDefault(require("./record_query_result"));
+var _field = _interopRequireDefault(require("./field"));
+var _table_or_view_query_result = _interopRequireDefault(require("./table_or_view_query_result"));
+var _view = _interopRequireDefault(require("./view"));
+var _object_pool = _interopRequireDefault(require("./object_pool"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @module @airtable/blocks/models: Table */ /** */
+
+// This doesn't follow our enum naming conventions because we want the keys
+// to mirror the method/getter names on the model class.
+const WatchableTableKeys = exports.WatchableTableKeys = Object.freeze({
+  ..._table_core.WatchableTableKeysCore,
+  views: 'views'
+});
+
+/**
+ * A key in {@link Table} that can be watched.
+ * - `name`
+ * - `description`
+ * - `fields`
+ * - `views`
+ */
+
+/**
+ * Model class representing a table. Every {@link Base} has one or more tables.
+ *
+ * @docsPath models/Table
+ */
+class Table extends _table_core.TableCore {
+  /** @internal */
+  static _className = 'Table';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableTableKeys, key);
+  }
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+  constructor(parentBase, recordStore, tableId, sdk) {
+    super(parentBase, recordStore, tableId, sdk);
+    this._viewModelsById = {}; // View instances are lazily created by getViewById.
+    this.__tableOrViewQueryResultPool = new _object_pool.default(_table_or_view_query_result.default);
+  }
+
+  /** @internal */
+  _constructField(fieldId) {
+    return new _field.default(this.parentBase.__sdk, this, fieldId);
+  }
+
+  /**
+   * The URL for the table. You can visit this URL in the browser to be taken to the table in the Airtable UI.
+   *
+   * @example
+   * ```js
+   * console.log(myTable.url);
+   * // => 'https://airtable.com/appxxxxxxxxxxxxxx/tblxxxxxxxxxxxxxx'
+   * ```
+   */
+  get url() {
+    return this._sdk.__airtableInterface.urlConstructor.getTableUrl(this.id);
+  }
+
+  // Experimental, do not document yet. Allows fetching default cell values for
+  // a table or view. Before documenting, we should explore making this synchronous.
+  /**
+   * @internal
+   */
+  // istanbul ignore next
+  async getDefaultCellValuesByFieldIdAsync(opts) {
+    const viewId = opts && opts.view ? opts.view.id : null;
+    const cellValuesByFieldId = await this._sdk.__airtableInterface.fetchDefaultCellValuesByFieldIdAsync(this._id, viewId);
+    return cellValuesByFieldId;
+  }
+
+  /**
+   * The views in this table. Can be watched to know when views are created,
+   * deleted, or reordered.
+   *
+   * @example
+   * ```js
+   * console.log(`This table has ${myTable.views.length} views`);
+   * ```
+   */
+  get views() {
+    // TODO(kasra): cache and freeze this so it isn't O(n)
+    const views = [];
+    this._data.viewOrder.forEach(viewId => {
+      const view = this.getViewById(viewId);
+      views.push(view);
+    });
+    return views;
+  }
+  /**
+   * Gets the view matching the given ID, or `null` if that view does not exist in this table.
+   *
+   * @param viewId The ID of the view.
+   * @example
+   * ```js
+   * const viewId = 'viwxxxxxxxxxxxxxx';
+   * const view = myTable.getViewByIdIfExists(viewId);
+   * if (view !== null) {
+   *     console.log(view.name);
+   * } else {
+   *     console.log('No view exists with that ID');
+   * }
+   * ```
+   */
+  getViewByIdIfExists(viewId) {
+    if (!this._data.viewsById[viewId]) {
+      return null;
+    } else {
+      if (!this._viewModelsById[viewId]) {
+        this._viewModelsById[viewId] = new _view.default(this._sdk, this, this._recordStore.getViewDataStore(viewId), viewId);
+      }
+      return this._viewModelsById[viewId];
+    }
+  }
+  /**
+   * Gets the view matching the given ID. Throws if that view does not exist in this table. Use
+   * {@link getViewByIdIfExists} instead if you are unsure whether a view exists with the given
+   * ID.
+   *
+   * @param viewId The ID of the view.
+   * @example
+   * ```js
+   * const viewId = 'viwxxxxxxxxxxxxxx';
+   * const view = myTable.getViewById(viewId);
+   * console.log(view.name);
+   * // => 'Grid view'
+   * ```
+   */
+  getViewById(viewId) {
+    const view = this.getViewByIdIfExists(viewId);
+    if (!view) {
+      throw (0, _error_utils.spawnError)("No view with ID %s in table '%s'", viewId, this.name);
+    }
+    return view;
+  }
+  /**
+   * Gets the view matching the given name, or `null` if no view exists with that name in this
+   * table.
+   *
+   * @param viewName The name of the view you're looking for.
+   * @example
+   * ```js
+   * const view = myTable.getViewByNameIfExists('Name');
+   * if (view !== null) {
+   *     console.log(view.id);
+   * } else {
+   *     console.log('No view exists with that name');
+   * }
+   * ```
+   */
+  getViewByNameIfExists(viewName) {
+    for (const [viewId, viewData] of (0, _private_utils.entries)(this._data.viewsById)) {
+      if (viewData.name === viewName) {
+        return this.getViewByIdIfExists(viewId);
+      }
+    }
+    return null;
+  }
+  /**
+   * Gets the view matching the given name. Throws if no view exists with that name in this table.
+   * Use {@link getViewByNameIfExists} instead if you are unsure whether a view exists with the
+   * given name.
+   *
+   * @param viewName The name of the view you're looking for.
+   * @example
+   * ```js
+   * const view = myTable.getViewByName('Name');
+   * console.log(view.id);
+   * // => 'viwxxxxxxxxxxxxxx'
+   * ```
+   */
+  getViewByName(viewName) {
+    const view = this.getViewByNameIfExists(viewName);
+    if (!view) {
+      throw (0, _error_utils.spawnError)("No view named '%s' in table '%s'", viewName, this.name);
+    }
+    return view;
+  }
+  /**
+   * The view matching the given ID or name. Returns `null` if no matching view exists within
+   * this table.
+   *
+   * This method is convenient when building an extension for a specific base, but for more generic
+   * extensions the best practice is to use the {@link getViewByIdIfExists} or
+   * {@link getViewByNameIfExists} methods instead.
+   *
+   * @param viewIdOrName The ID or name of the view you're looking for.
+   */
+  getViewIfExists(viewIdOrName) {
+    return this.getViewByIdIfExists(viewIdOrName) ?? this.getViewByNameIfExists(viewIdOrName);
+  }
+  /**
+   * The view matching the given ID or name. Throws if no matching view exists within this table.
+   * Use {@link getViewIfExists} instead if you are unsure whether a view exists with the given
+   * name/ID.
+   *
+   * This method is convenient when building an extension for a specific base, but for more generic
+   * extensions the best practice is to use the {@link getViewById} or {@link getViewByName} methods
+   * instead.
+   *
+   * @param viewIdOrName The ID or name of the view you're looking for.
+   */
+  getView(viewIdOrName) {
+    const view = this.getViewIfExists(viewIdOrName);
+    if (!view) {
+      throw (0, _error_utils.spawnError)("No view with ID or name '%s' in table '%s'", viewIdOrName, this.name);
+    }
+    return view;
+  }
+  /**
+   * Select records from the table. Returns a {@link RecordQueryResult}.
+   *
+   * Consider using {@link useRecords} or {@link useRecordIds} instead, unless you need the
+   * features of a QueryResult (e.g. `queryResult.getRecordById`). Record hooks handle
+   * loading/unloading and updating your UI automatically, but manually `select`ing records is
+   * useful for one-off data processing.
+   *
+   * @param opts Options for the query, such as sorts and fields.
+   * @example
+   * ```js
+   * import {useBase, useRecords} from '@airtable/blocks/base/ui';
+   * import React from 'react';
+   *
+   * function TodoList() {
+   *     const base = useBase();
+   *     const table = base.getTableByName('Tasks');
+   *
+   *     const queryResult = table.selectRecords();
+   *     const records = useRecords(queryResult);
+   *
+   *     return (
+   *         <ul>
+   *             {records.map(record => (
+   *                 <li key={record.id}>
+   *                     {record.name || 'Unnamed record'}
+   *                 </li>
+   *             ))}
+   *         </ul>
+   *     );
+   * }
+   * ```
+   */
+  selectRecords(opts) {
+    const normalizedOpts = _record_query_result.default._normalizeOpts(this, this._recordStore, opts || {});
+    return this.__tableOrViewQueryResultPool.getObjectForReuse(this._sdk, this, normalizedOpts);
+  }
+  /**
+   * Select and load records from the table. Returns a {@link RecordQueryResult} promise where
+   * record data has been loaded.
+   *
+   * Consider using {@link useRecords} or {@link useRecordIds} instead, unless you need the
+   * features of a QueryResult (e.g. `queryResult.getRecordById`). Record hooks handle
+   * loading/unloading and updating your UI automatically, but manually `select`ing records is
+   * useful for one-off data processing.
+   *
+   * Once you've finished with your query, remember to call `queryResult.unloadData()`.
+   *
+   * @param opts Options for the query, such as sorts and fields.
+   * @example
+   * ```js
+   * async function logRecordCountAsync(table) {
+   *     const query = await table.selectRecordsAsync();
+   *     console.log(query.recordIds.length);
+   *     query.unloadData();
+   * }
+   * ```
+   */
+  async selectRecordsAsync(opts) {
+    const queryResult = this.selectRecords(opts);
+    await queryResult.loadDataAsync();
+    return queryResult;
+  }
+  /**
+   * Returns the first view in the table where the type is one of `allowedViewTypes`, or `null` if
+   * no such view exists in the table.
+   *
+   * @param allowedViewTypes An array of view types or a single view type to match against.
+   * @param preferredViewOrViewId If a view or view ID is supplied and that view exists & has the
+   * correct type, that view will be returned before checking the other views in the table.
+   * @example
+   * ```js
+   * import {ViewType} from '@airtable/blocks/base/models';
+   * const firstCalendarView = myTable.getFirstViewOfType(ViewType.CALENDAR);
+   * if (firstCalendarView !== null) {
+   *     console.log(firstCalendarView.name);
+   * } else {
+   *     console.log('No calendar views exist in the table');
+   * }
+   * ```
+   */
+  getFirstViewOfType(allowedViewTypes, preferredViewOrViewId) {
+    if (!Array.isArray(allowedViewTypes)) {
+      allowedViewTypes = (0, _private_utils.cast)([allowedViewTypes]);
+    }
+    if (preferredViewOrViewId) {
+      const preferredView = this.getViewByIdIfExists(typeof preferredViewOrViewId === 'string' ? preferredViewOrViewId : preferredViewOrViewId.id);
+      if (preferredView && allowedViewTypes.includes(preferredView.type)) {
+        return preferredView;
+      }
+    }
+    return this.views.find(view => {
+      return allowedViewTypes.includes(view.type);
+    }) ?? null;
+  }
+  /**
+   * @internal
+   */
+  __getViewMatching(viewOrViewIdOrViewName) {
+    let view;
+    if (viewOrViewIdOrViewName instanceof _view.default) {
+      if (viewOrViewIdOrViewName.parentTable.id !== this.id) {
+        throw (0, _error_utils.spawnError)("View '%s' is from a different table than table '%s'", viewOrViewIdOrViewName.name, this.name);
+      }
+      view = viewOrViewIdOrViewName;
+    } else {
+      view = this.getViewByIdIfExists(viewOrViewIdOrViewName) || this.getViewByNameIfExists(viewOrViewIdOrViewName);
+      if (view === null) {
+        throw (0, _error_utils.spawnError)("View '%s' does not exist in table '%s'", viewOrViewIdOrViewName, this.name);
+      }
+    }
+    if (view.isDeleted) {
+      throw (0, _error_utils.spawnError)("View '%s' was deleted from table '%s'", view.name, this.name);
+    }
+    return view;
+  }
+
+  /**
+   * Checks whether the current user has permission to create a field in this table.
+   *
+   * Accepts partial input, in the same format as {@link createFieldAsync}.
+   *
+   * Returns `{hasPermission: true}` if the current user can update the specified record,
+   * `{hasPermission: false, reasonDisplayString: string}` otherwise. `reasonDisplayString` may be
+   * used to display an error message to the user.
+   *
+   * @param name name for the field. must be case-insensitive unique for the table
+   * @param type type for the field
+   * @param options options for the field. omit for fields without writable options
+   * @param description description for the field. omit to leave blank
+   *
+   * @example
+   * ```js
+   * const createFieldCheckResult = table.checkPermissionsForCreateField();
+   *
+   * if (!createFieldCheckResult.hasPermission) {
+   *     alert(createFieldCheckResult.reasonDisplayString);
+   * }
+   * ```
+   */
+  checkPermissionsForCreateField(name, type, options, description) {
+    return this._sdk.__mutations.checkPermissionsForMutation({
+      type: _mutations.MutationTypes.CREATE_SINGLE_FIELD,
+      tableId: this.id,
+      id: undefined,
+      // Generated in createFieldAsync.
+      name,
+      config: type ? {
+        type: type,
+        // In field.options we translate options to null when it's undefined (no options),
+        // but the mutation expects config to match the PublicApiConfig, where it's
+        // not present at all (options: undefined will fail validation).
+        ...(options ? {
+          options
+        } : null)
+      } : undefined,
+      description
+    });
+  }
+
+  /**
+   * An alias for `checkPermissionsForCreateField(name, type, options, description).hasPermission`.
+   *
+   * Checks whether the current user has permission to create a field in this table.
+   *
+   * Accepts partial input, in the same format as {@link createFieldAsync}.
+   *
+   * @param name name for the field. must be case-insensitive unique for the table
+   * @param type type for the field
+   * @param options options for the field. omit for fields without writable options
+   * @param description description for the field. omit to leave blank
+   *
+   * @example
+   * ```js
+   * const canCreateField = table.hasPermissionToCreateField();
+   *
+   * if (!canCreateField) {
+   *     alert('not allowed!');
+   * }
+   * ```
+   */
+  hasPermissionToCreateField(name, type, options, description) {
+    return this.checkPermissionsForCreateField(name, type, options, description).hasPermission;
+  }
+
+  /**
+   * Creates a new field.
+   *
+   * Similar to creating a field from the Airtable UI, the new field will not be visible
+   * in views that have other hidden fields and views that are publicly shared.
+   *
+   * Throws an error if the user does not have permission to create a field, if invalid
+   * name, type or options are provided, or if creating fields of this 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 new records, new fields are **not** created
+   * optimistically locally. You must `await` the returned promise before using the new
+   * field in your extension.
+   *
+   * @param name name for the field. must be case-insensitive unique
+   * @param type type for the field
+   * @param options options for the field. omit for fields without writable options
+   * @param description description for the field. is optional and will be `''` if not specified
+   * or if specified as `null`.
+   *
+   * @example
+   * ```js
+   * async function createNewSingleLineTextField(table, name) {
+   *     if (table.hasPermissionToCreateField(name, FieldType.SINGLE_LINE_TEXT)) {
+   *         await table.createFieldAsync(name, FieldType.SINGLE_LINE_TEXT);
+   *     }
+   * }
+   *
+   * async function createNewCheckboxField(table, name) {
+   *     const options = {
+   *         icon: 'check',
+   *         color: 'greenBright',
+   *     };
+   *     if (table.hasPermissionToCreateField(name, FieldType.CHECKBOX, options)) {
+   *         await table.createFieldAsync(name, FieldType.CHECKBOX, options);
+   *     }
+   * }
+   *
+   * async function createNewDateField(table, name) {
+   *     const options = {
+   *         dateFormat: {
+   *             name: 'iso',
+   *         },
+   *     };
+   *     if (table.hasPermissionToCreateField(name, FieldType.DATE, options)) {
+   *         await table.createFieldAsync(name, FieldType.DATE, options);
+   *     }
+   * }
+   * ```
+   */
+  async createFieldAsync(name, type, options, description) {
+    const fieldId = this._sdk.__airtableInterface.idGenerator.generateFieldId();
+    await this._sdk.__mutations.applyMutationAsync({
+      type: _mutations.MutationTypes.CREATE_SINGLE_FIELD,
+      tableId: this.id,
+      id: fieldId,
+      name,
+      config: {
+        type: type,
+        // In field.options we translate options to null when it's undefined (no options),
+        // but the mutation expects config to match the PublicApiConfig, where it's
+        // not present at all (options: undefined will fail validation).
+        ...(options ? {
+          options
+        } : null)
+      },
+      // Coerce undefined to null so that only old SDKs pass "undefined" for description
+      // '' is permitted, as we already set empty descriptions to '' when editing descriptions
+      // from the UI
+      description: description ?? null
+    });
+    return this.getFieldById(fieldId);
+  }
+
+  /** @internal */
+  __triggerOnChangeForDirtyPaths(dirtyPaths) {
+    let didTableSchemaChange = false;
+    if (super.__triggerOnChangeForDirtyPaths(dirtyPaths)) {
+      didTableSchemaChange = true;
+    }
+    if (dirtyPaths.viewOrder) {
+      this._onChange(WatchableTableKeys.views);
+      didTableSchemaChange = true;
+
+      // Clean up deleted views
+      for (const [viewId, viewModel] of (0, _private_utils.entries)(this._viewModelsById)) {
+        if (viewModel.isDeleted) {
+          delete this._viewModelsById[viewId];
+        }
+      }
+    }
+    if (dirtyPaths.viewsById) {
+      for (const [viewId, dirtyViewPaths] of (0, _private_utils.entries)(dirtyPaths.viewsById)) {
+        // Directly access from _viewModelsById to avoid creating
+        // a view model if it doesn't already exist. If it doesn't exist,
+        // nothing can be subscribed to any events on it.
+        const view = this._viewModelsById[viewId];
+        if (view) {
+          const didViewSchemaChange = view.__triggerOnChangeForDirtyPaths(dirtyViewPaths);
+          if (didViewSchemaChange) {
+            didTableSchemaChange = true;
+          }
+        }
+      }
+    }
+    return didTableSchemaChange;
+  }
+}
+var _default = exports.default = Table;