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

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

@@ -0,0 +1,482 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.WatchableBaseKeys = exports.BaseCore = void 0;
+var _private_utils = require("../private_utils");
+var _error_utils = require("../error_utils");
+var _abstract_model = _interopRequireDefault(require("./abstract_model"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// How these model classes work:
+//
+// The single instance of the Base class maintains a reference to a plain JS
+// object that contains all the data (baseData). All the other model classes
+// receive a reference to baseData and traverse it to expose the data.
+//
+// As changes come in from liveapp, Base will apply them to the plain JS object.
+// Since the other model classes have a reference to the same object, they'll
+// always be accessing the most up-to-date values.
+//
+// Be careful not to return a reference to any non-primitive subtree of baseData,
+// since the block developer could mutate it and we'll end up out of sync with
+// liveapp.
+
+const WatchableBaseKeys = exports.WatchableBaseKeys = Object.freeze({
+  name: 'name',
+  tables: 'tables',
+  collaborators: 'collaborators',
+  schema: 'schema',
+  color: 'color'
+});
+
+/**
+ * Any key in base that can be watched:
+ * - `name`: the name of the base
+ * - `tables`: the order of tables in the base
+ * - `collaborators`: all the collaborators in the base
+ * - `schema`: the base schema (essentially everything except for record data)
+ */
+
+/** @internal */
+
+/** @internal */
+
+/** @hidden */
+class BaseCore extends _abstract_model.default {
+  /** @internal */
+  static _className = 'BaseCore';
+  /** @internal */
+  static _isWatchableKey(key) {
+    return (0, _private_utils.isEnumValue)(WatchableBaseKeys, key);
+  }
+  /** @internal */
+
+  /** @internal */
+  _tableRecordStoresByTableId = {};
+  /** @internal */
+
+  /** @internal */
+  _collaboratorIdsByNameAndEmail = null;
+  /**
+   * @internal
+   */
+  constructor(sdk) {
+    super(sdk, sdk.__airtableInterface.sdkInitData.baseData.id);
+    this._tableModelsById = {}; // Table instances are lazily created by getTableById.
+    this.__billingPlanGrouping = sdk.__airtableInterface.sdkInitData.baseData.billingPlanGrouping;
+  }
+
+  /**
+   * Aliased to communicate stability for internal use by Sdk code.
+   *
+   * @internal
+   */
+  get __sdk() {
+    return this._sdk;
+  }
+
+  /**
+   * @internal
+   */
+  get _dataOrNullIfDeleted() {
+    return this._baseData;
+  }
+  /**
+   * The name of the base.
+   *
+   * @example
+   * ```js
+   * import {useBase} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const base = useBase();
+   *     console.log('The name of your base is', base.name);
+   * }
+   * ```
+   */
+  get name() {
+    return this._data.name;
+  }
+
+  /**
+   * The workspace id of the base.
+   *
+   * @example
+   * ```js
+   * import {useBase} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const base = useBase();
+   *     console.log('The workspace id of your base is', base.workspaceId);
+   * }
+   * ```
+   */
+  get workspaceId() {
+    return this._data.workspaceId;
+  }
+
+  /**
+   * The color of the base.
+   *
+   * @example
+   * ```js
+   * import {colorUtils, useBase} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const base = useBase();
+   *     return (
+   *         <div style={{backgroundColor: colorUtils.getHexForColor(base.color)}}>
+   *             This div's background is the same color as the base background
+   *         </div>
+   *     );
+   * }
+   * ```
+   */
+  get color() {
+    return this._data.color;
+  }
+
+  /**
+   * The tables in this base. Can be watched to know when tables are created, deleted, or reordered in the base.
+   *
+   * @example
+   * ```js
+   * import {useBase} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const base = useBase();
+   *     console.log(`You have ${base.tables.length} tables`);
+   * }
+   * ```
+   */
+  get tables() {
+    // TODO(kasra): cache and freeze this so it isn't O(n)
+    const tables = [];
+    for (const tableId of this._iterateTableIds()) {
+      const table = this.getTableByIdIfExists(tableId);
+      // NOTE: A table's ID may be in tableOrder without the table appearing
+      // in tablesById, in which case getTableById will return null. This
+      // happens if table was just created by the user, since we
+      // wait for the push payload to deliver the table schema.
+      if (table) {
+        tables.push(table);
+      }
+    }
+    return tables;
+  }
+
+  /** @internal */
+
+  /** @internal */
+
+  /** @internal */
+
+  /**
+   * The users who have access to this base.
+   *
+   * @example
+   * ```js
+   * import {useBase} from '@airtable/blocks/[placeholder-path]/ui';
+   *
+   * function MyApp() {
+   *     const base = useBase();
+   *     console.log(base.activeCollaborators[0].email);
+   * }
+   * ```
+   */
+  get activeCollaborators() {
+    return this._data.activeCollaboratorIds.map(collaboratorId => this.getCollaboratorById(collaboratorId));
+  }
+  /**
+   * The user matching the given ID, or `null` if that user does not exist or does not have access
+   * to this base.
+   *
+   * @param collaboratorId The ID of the user.
+   */
+  getCollaboratorByIdIfExists(collaboratorId) {
+    const collaboratorsById = this._data.collaboratorsById;
+    return (0, _private_utils.has)(collaboratorsById, collaboratorId) ? collaboratorsById[collaboratorId] : null;
+  }
+  /**
+   * The user matching the given ID. Throws if that user does not exist
+   * or does not have access to this base. Use {@link getCollaboratorByIdIfExists}
+   * instead if you are unsure whether a collaborator with the given ID exists
+   * and has access to this base.
+   *
+   * @param collaboratorId The ID of the user.
+   */
+  getCollaboratorById(collaboratorId) {
+    const collaborator = this.getCollaboratorByIdIfExists(collaboratorId);
+    if (!collaborator) {
+      throw (0, _error_utils.spawnError)("No collaborator with ID %s has access to base '%s'", collaboratorId, this.name);
+    }
+    return collaborator;
+  }
+  /**
+   * The user matching the given ID, name, or email address. Returns null if that user does not
+   * exist or does not have access to this base.
+   *
+   * 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 getCollaboratorByIdIfExists} method instead.
+   *
+   * @param collaboratorIdOrNameOrEmail The ID of the user.
+   */
+  getCollaboratorIfExists(idOrNameOrEmail) {
+    const collaboratorById = this.getCollaboratorByIdIfExists(idOrNameOrEmail);
+    if (collaboratorById) {
+      return collaboratorById;
+    }
+    if (!this._collaboratorIdsByNameAndEmail) {
+      this._collaboratorIdsByNameAndEmail = new Map();
+      for (const [id, {
+        email,
+        name
+      }] of (0, _private_utils.entries)(this._data.collaboratorsById)) {
+        this._collaboratorIdsByNameAndEmail.set(email, id);
+        // we prevent `@` in names so theoretically we shouldn't encounter any collisions
+        // between names and emails, but names themselves may not be unique. as we build the
+        // name hash, we only add new values rather than overwrite existing ones. this means
+        // that we'll prefer emails to names in the event of a collision.
+        if (name && !this._collaboratorIdsByNameAndEmail.has(name)) {
+          this._collaboratorIdsByNameAndEmail.set(name, id);
+        }
+      }
+    }
+    const idForNameOrEmail = this._collaboratorIdsByNameAndEmail.get(idOrNameOrEmail);
+    if (idForNameOrEmail !== undefined) {
+      return this.getCollaboratorById(idForNameOrEmail);
+    }
+    return null;
+  }
+  /**
+   * The user matching the given ID, name, or email address. Throws if that user does not exist
+   * or does not have access to this base. Use {@link getCollaboratorIfExists} instead if you are
+   * unsure whether a collaborator with the given ID exists and has access to this base.
+   *
+   * 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 getCollaboratorById} method instead.
+   *
+   * @param collaboratorIdOrNameOrEmail The ID of the user.
+   */
+  getCollaborator(idOrNameOrEmail) {
+    const collaborator = this.getCollaboratorIfExists(idOrNameOrEmail);
+    if (!collaborator) {
+      throw (0, _error_utils.spawnError)("No collaborator with ID, name, or email of '%s' is in base '%s'", idOrNameOrEmail, this.name);
+    }
+    return collaborator;
+  }
+  /**
+   * @internal
+   */
+  __getBaseData() {
+    return this._data;
+  }
+  /**
+   * The table matching the given ID, or `null` if that table does not exist in this base.
+   *
+   * @param tableId The ID of the table.
+   */
+  getTableByIdIfExists(tableId) {
+    if (!this._data.tablesById[tableId]) {
+      return null;
+    } else {
+      if (!this._tableModelsById[tableId]) {
+        this._tableModelsById[tableId] = this._constructTable(tableId);
+      }
+      return this._tableModelsById[tableId];
+    }
+  }
+  /**
+   * The table matching the given ID. Throws if that table does not exist in this base. Use
+   * {@link getTableByIdIfExists} instead if you are unsure whether a table exists with the given
+   * ID.
+   *
+   * @param tableId The ID of the table.
+   */
+  getTableById(tableId) {
+    const table = this.getTableByIdIfExists(tableId);
+    if (!table) {
+      throw (0, _error_utils.spawnError)("No table with ID %s in base '%s'", tableId, this.name);
+    }
+    return table;
+  }
+  /**
+   * The table matching the given name, or `null` if no table exists with that name in this base.
+   *
+   * @param tableName The name of the table you're looking for.
+   */
+  getTableByNameIfExists(tableName) {
+    for (const [tableId, tableData] of (0, _private_utils.entries)(this._data.tablesById)) {
+      if (tableData.name === tableName) {
+        return this.getTableByIdIfExists(tableId);
+      }
+    }
+    return null;
+  }
+  /**
+   * The table matching the given name. Throws if no table exists with that name in this base. Use
+   * {@link getTableByNameIfExists} instead if you are unsure whether a table exists with the
+   * given name.
+   *
+   * @param tableName The name of the table you're looking for.
+   */
+  getTableByName(tableName) {
+    const table = this.getTableByNameIfExists(tableName);
+    if (!table) {
+      throw (0, _error_utils.spawnError)("No table named '%s' in base '%s'", tableName, this.name);
+    }
+    return table;
+  }
+  /**
+   * The table matching the given ID or name. Returns `null` if no matching table exists within
+   * this base.
+   *
+   * 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 getTableByIdIfExists} or
+   * {@link getTableByNameIfExists} methods instead.
+   *
+   * @param tableIdOrName The ID or name of the table you're looking for.
+   */
+  getTableIfExists(tableIdOrName) {
+    return this.getTableByIdIfExists(tableIdOrName) ?? this.getTableByNameIfExists(tableIdOrName);
+  }
+  /**
+   * The table matching the given ID or name. Throws if no matching table exists within this base.
+   * Use {@link getTableIfExists} instead if you are unsure whether a table 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 getTableById} or {@link getTableByName} methods
+   * instead.
+   *
+   * @param tableIdOrName The ID or name of the table you're looking for.
+   */
+  getTable(tableIdOrName) {
+    const table = this.getTableIfExists(tableIdOrName);
+    if (!table) {
+      throw (0, _error_utils.spawnError)("No table with ID or name '%s' in base '%s'", tableIdOrName, this.name);
+    }
+    return table;
+  }
+
+  /**
+   * Returns the maximum number of records allowed in each table of this base.
+   */
+  getMaxRecordsPerTable() {
+    return this._data.maxRowsPerTable ?? 100000;
+  }
+
+  /**
+   * @internal
+   */
+  __getRecordStore(tableId) {
+    if ((0, _private_utils.has)(this._tableRecordStoresByTableId, tableId)) {
+      return this._tableRecordStoresByTableId[tableId];
+    }
+    (0, _error_utils.invariant)(this._data.tablesById[tableId], 'table must exist');
+    const newRecordStore = this._constructRecordStore(this._sdk, tableId);
+    this._tableRecordStoresByTableId[tableId] = newRecordStore;
+    return newRecordStore;
+  }
+
+  /**
+   * @internal
+   */
+  __triggerOnChangeForChangedPaths(changedPaths) {
+    let didSchemaChange = false;
+    if (changedPaths.name) {
+      this._onChange(WatchableBaseKeys.name);
+      didSchemaChange = true;
+    }
+    if (changedPaths.color) {
+      this._onChange(WatchableBaseKeys.color);
+      didSchemaChange = true;
+    }
+    const {
+      tablesById
+    } = changedPaths;
+    if (tablesById) {
+      if ((0, _private_utils.isDeepEqual)(tablesById, {
+        _isDirty: true
+      })) {
+        // If the changedPath is that tablesById is dirty in general, we need to
+        // trigger a schema change event. This happens in interface blocks
+        // when we reinitialize the tablesById as a whole due to the QueryModels
+        // changing. See https://github.com/Hyperbase/hyperbase/blob/b50a8992d333bcef3c906d61886fc69727a8e94b/client/components/blocks/block_frame.tsx#L645
+        didSchemaChange = true;
+      } else {
+        for (const [tableId, dirtyTablePaths] of (0, _private_utils.entries)(tablesById)) {
+          const table = this.getTableByIdIfExists(tableId);
+          if (table && dirtyTablePaths) {
+            const didTableSchemaChange = table.__triggerOnChangeForDirtyPaths(dirtyTablePaths);
+            if (didTableSchemaChange) {
+              didSchemaChange = true;
+            }
+          }
+        }
+      }
+    }
+    if (changedPaths.collaboratorsById || changedPaths.activeCollaboratorIds) {
+      this._onChange(WatchableBaseKeys.collaborators);
+    }
+    if (changedPaths.appInterface) {
+      didSchemaChange = true;
+    }
+    if (didSchemaChange) {
+      this._onChange(WatchableBaseKeys.schema);
+    }
+  }
+  /**
+   * @internal
+   */
+  __applyChangesWithoutTriggeringEvents(changes) {
+    // Internal method.
+    // After applying all changes, changedPaths will have the same shape as
+    // the subset of this._data that changed. For example, if some table's
+    // name changes, changedPaths will be {tablesById: {tbl123: name: {_isDirty: true}}}.
+    // Use it to call __triggerOnChangeForChangedPaths to trigger change events for
+    // effected models
+    const changedPaths = {};
+    for (const change of changes) {
+      this._applyChange(change.path, change.value, changedPaths);
+    }
+    return changedPaths;
+  }
+  /**
+   * @internal
+   */
+  _applyChange(path, value, changedPathsByRef) {
+    let dataSubtree = this._data;
+    let dirtySubtree = changedPathsByRef;
+    for (let i = 0; i < path.length - 1; i++) {
+      const part = path[i];
+      if (!dataSubtree[part]) {
+        // Certain fields are stored sparsely (e.g. cellValuesByFieldId),
+        // so create an object on demand if needed.
+        dataSubtree[part] = {};
+      }
+      dataSubtree = dataSubtree[part];
+      if (!dirtySubtree[part]) {
+        dirtySubtree[part] = {};
+      }
+      (0, _error_utils.invariant)(dirtySubtree[part], 'dirtySubtree');
+      dirtySubtree = dirtySubtree[part];
+    }
+    const lastPathPart = path[path.length - 1];
+    const didChange = !(0, _private_utils.isDeepEqual)(dataSubtree[lastPathPart], value);
+    if (value === undefined) {
+      delete dataSubtree[lastPathPart];
+    } else {
+      dataSubtree[lastPathPart] = value;
+    }
+    if (didChange) {
+      if (!dirtySubtree[lastPathPart]) {
+        dirtySubtree[lastPathPart] = {};
+      }
+      (0, _error_utils.invariant)(dirtySubtree[lastPathPart], 'dirtySubtree');
+      dirtySubtree[lastPathPart]._isDirty = true;
+    }
+  }
+}
+exports.BaseCore = BaseCore;