# Events

Source: https://developers.inkdrop.app/data-access/events

Provides the ability to subscribe to various events raised by the local database.

---

## All changes `onChange(callback)`

Invoke the given callback when the database has been changed.

### Parameters

- **callback** ((PouchDB.Core.ChangesResponseChange\<object>) => void)

  A function which is called with an object indicating the [changes feed](https://pouchdb.com/guides/changes.html#understanding-changes).

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onChange(changes => {
  console.log('Database has been changed', changes)
});

// Later, dispose
subscription.dispose();
```

---

## Note changes `onNoteChange(callback)`

Invoke the given callback when a note has been added, modified or deleted.

### Parameters

- **callback** ((PouchDB.Core.ChangesResponseChange\<Note>) => void)

  A function which is called with an object indicating the [changes feed](https://pouchdb.com/guides/changes.html#understanding-changes).

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onNoteChange(changes => {
  console.log('Note has been changed', changes)
});

// Later, dispose
subscription.dispose();
```

---

## Book changes `onBookChange(callback)`

Invoke the given callback when a notebook has been added, modified or deleted.

### Parameters

- **callback** ((PouchDB.Core.ChangesResponseChange\<Book>) => void)

  A function which is called with an object indicating the [changes feed](https://pouchdb.com/guides/changes.html#understanding-changes).

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onBookChange(changes => {
  console.log('Notebook has been changed', changes)
});

// Later, dispose
subscription.dispose();
```

---

## Tag changes `onTagChange(callback)`

Invoke the given callback when a tag has been added, modified or deleted.

### Parameters

- **callback** ((PouchDB.Core.ChangesResponseChange\<Tag>) => void)

  A function which is called with an object indicating the [changes feed](https://pouchdb.com/guides/changes.html#understanding-changes).

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onTagChange(changes => {
  console.log('Tag has been changed', changes)
});

// Later, dispose
subscription.dispose();
```

---

## Index build start `onIndexBuildStart(callback)`

Invoke the given callback when the app started building the search index.

### Parameters

- **callback** (() => void)

  A Function to be invoked.

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onIndexBuildStart(() => {
  console.log('Search index building has been started')
});

// Later, dispose
subscription.dispose();
```

---

## Index build progress `onIndexBuildProgress(callback)`

Invoke the given callback each time the app applied a batch of changes to the search index.
The callback receives an object with `prevSeq` (the sequence the run started from), `seq` (the sequence reached so far), and `latestSeq` (the database's update sequence when the run started).

### Parameters

- **callback** ((progress: object) => void)

  A function which is called with the progress.

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onIndexBuildProgress(progress => {
  console.log('Search index building:', progress.seq, '/', progress.latestSeq)
});

// Later, dispose
subscription.dispose();
```

---

## Index build end `onIndexBuildEnd(callback)`

Invoke the given callback when the app finished building the search index.

### Parameters

- **callback** (() => void)

  A Function to be invoked.

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onIndexBuildEnd(() => {
  console.log('Search index building has been finished')
});

// Later, dispose
subscription.dispose();
```

---

## Index build error `onIndexBuildError(callback)`

Invoke the given callback when the app failed to build the search index.

### Parameters

- **callback** ((error: Error) => void)

  A function which is called with an error.

### Returns

Returns a [Disposable][disposable] on which `.dispose()` can be called to unsubscribe.

```js
const db = env.localDB
const subscription = db.onIndexBuildError(error => {
  console.log('Search index building has failed', error)
});

// Later, dispose
subscription.dispose();
```

[disposable]: https://developers.inkdrop.app/event-subscription/disposable