# GlobalConfig

**Kind:** Class

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
`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.

```js
import {globalConfig} from '@airtable/blocks';
```

## Methods

### `checkPermissionsForSet(key?, value?)`

Checks whether the current user has permission to set the given global config key.

Accepts partial input, in the same format as `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.

**Parameters:**
- `key?` (`PartialGlobalConfigKey`) — A string for the top-level key, or an array of strings describing the path to set.
- `value?` (`GlobalConfigValue`) — The value to set at the specified path. Use `undefined` to delete the value at the given path.

**Returns:** `PermissionCheckResult`

```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();
```

### `checkPermissionsForSetPaths(updates?)`

Checks whether the current user has permission to perform the specified updates to global config.

Accepts partial input, in the same format as `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.

**Parameters:**
- `updates?` (`ReadonlyArray<PartialGlobalConfigUpdate>`) — The paths and values to set.

**Returns:** `PermissionCheckResult`

```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();
```

### `get(key)`

Get the value at a path. Throws an error if the path is invalid.

Returns undefined if no value exists at that path.

**Parameters:**
- `key` (`GlobalConfigKey`) — A string for the top-level key, or an array of strings describing the path to the value.

**Returns:** `unknown`

```js
import {globalConfig} from '@airtable/blocks';

const topLevelValue = globalConfig.get('topLevelKey');
const nestedValue = globalConfig.get(['topLevelKey', 'nested', 'deeply']);
```

### `hasPermissionToSet(key?, 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 `setAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `key?` (`PartialGlobalConfigKey`) — A string for the top-level key, or an array of strings describing the path to set.
- `value?` (`GlobalConfigValue`) — The value to set at the specified path. Use `undefined` to delete the value at the given path.

**Returns:** `boolean`

```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();
```

### `hasPermissionToSetPaths(updates?)`

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 `setPathsAsync`.
The more information provided, the more accurate the permissions check will be.

**Parameters:**
- `updates?` (`ReadonlyArray<PartialGlobalConfigUpdate>`) — The paths and values to set.

**Returns:** `boolean`

```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();
```

### `setAsync(key, value?)`

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
`GlobalConfig` before the promise resolves.

**Parameters:**
- `key` (`GlobalConfigKey`) — A string for the top-level key, or an array of strings describing the path to set.
- `value?` (`GlobalConfigValue`) — The value to set at the specified path. Use `undefined` to delete the value at the given path.

**Returns:** `Promise<void>`

```js
import {globalConfig} from '@airtable/blocks';

function updateFavoriteColorIfPossible(color) {
    if (globalConfig.hasPermissionToSetPaths('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)
}

async function updateFavoriteColorIfPossibleAsync(color) {
    if (globalConfig.hasPermissionToSet('favoriteColor', color)) {
        await globalConfig.setAsync('favoriteColor', color);
    }
    // globalConfig updates have been saved to Airtable servers.
    alert('favoriteColor has been updated');
}
```

### `setPathsAsync(updates)`

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
`GlobalConfig` before the promise resolves.

**Parameters:**
- `updates` (`Array<GlobalConfigUpdate>`) — The paths and values to set.

**Returns:** `Promise<void>`

```js
import {globalConfig} from '@airtable/blocks';

const updates = [
    {path: ['topLevelKey1', 'nestedKey1'], value: 'foo'},
    {path: ['topLevelKey2', 'nestedKey2'], value: 'bar'},
];

function 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)
}

async function applyUpdatesIfPossibleAsync() {
    if (globalConfig.hasPermissionToSetPaths(updates)) {
        await globalConfig.setPathsAsync(updates);
    }
    // globalConfig updates have been saved to Airtable servers.
    alert('globalConfig has been updated');
}
```

### `unwatch(keys, callback, context?)`

Unwatch keys watched with `.watch`.

Should be called with the same arguments given to `.watch`.

Returns the array of keys that were unwatched.

**Parameters:**
- `keys` (`WatchableGlobalConfigKey | ReadonlyArray<WatchableGlobalConfigKey>`) — the keys to unwatch
- `callback` (`object`) — the function passed to `.watch` for these keys
- `context?` (`FlowAnyObject | null`) — the context that was passed to `.watch` for this `callback`

**Returns:** `Array<WatchableGlobalConfigKey>`

### `watch(keys, callback, context?)`

Get notified of changes to the model.

Every call to `.watch` should have a matching call to `.unwatch`.

Returns the array of keys that were watched.

**Parameters:**
- `keys` (`WatchableGlobalConfigKey | ReadonlyArray<WatchableGlobalConfigKey>`) — the keys to watch
- `callback` (`object`) — a function to call when those keys change
- `context?` (`FlowAnyObject | null`) — an optional context for `this` in `callback`.

**Returns:** `Array<WatchableGlobalConfigKey>`