# MirrorDrive
`Mirrordrive` computes diffs between two drive-like APIs and applies them efficiently. It is the helper that powers sync flows between [Hyperdrive](/p2p/reference/building-blocks/hyperdrive) and [Localdrive](/p2p/reference/helpers/localdrive), including the `drive.mirror(...)` shortcut on Hyperdrive. A `MirrorDrive` instance is itself an async iterable, so iterating it with `for await (const diff of mirror)` drives the diff/copy pass and yields one diff object per entry. For source and release notes, see the [mirror-drive repository](https://github.com/holepunchto/mirror-drive).
## Async iteration [#async-iteration]
#### `for await (const diff of mirror)` [#for-await-const-diff-of-mirror]
`MirrorDrive` is itself an async iterable. Iterating it with `for await` drives the entire diff/copy pass; each yield produces one `{ op, key, bytesRemoved, bytesAdded }` object where `op` is `'add'`, `'change'`, or `'remove'`, plus `'equal'` when `includeEquals` is set.
```js
for await (const diff of mirror) {
console.log(diff.op, diff.key)
}
```
## Option patterns [#option-patterns]
#### `transformers` [#transformers]
[API definition on GitHub](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L88)
* Returns: A copy pipeline hook. Each transformer is a function `(key) => stream | null`; returning `null` skips that transform for the current file.
* Example:
```js
const mirror = new MirrorDrive(src, dst, {
transformers: [
(key) => key.endsWith('.txt') ? myTransformStream() : null
]
})
```
#### `entries` [#entries]
[API definition on GitHub](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L87)
* Returns: A fixed list of entries to mirror instead of reading them from `src.list(...)`. When this option is used, `prefix` is ignored.
* Example:
```js
const entries = [{ key: '/index.html' }, { key: '/styles.css' }]
const mirror = new MirrorDrive(src, dst, { entries })
```
#### `metadataEquals` [#metadataequals]
[API definition on GitHub](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L85)
* Returns: A predicate used to decide whether metadata changes should count as a diff when both drives support metadata.
* Example:
```js
const mirror = new MirrorDrive(src, dst, {
metadataEquals(left, right) {
return JSON.stringify(left) === JSON.stringify(right)
}
})
```
## Install [#install]
```sh
npm i mirror-drive
```
## Quickstart [#quickstart]
```js
import Corestore from 'corestore'
import Hyperdrive from 'hyperdrive'
import Localdrive from 'localdrive'
import MirrorDrive from 'mirror-drive'
const store = new Corestore('./storage')
const src = new Localdrive('./site')
const dst = new Hyperdrive(store)
await dst.ready()
const mirror = new MirrorDrive(src, dst, { prune: true })
for await (const diff of mirror) {
console.log(diff)
}
```
## API Reference [#api-reference]
### Constructor and lifecycle [#constructor-and-lifecycle]
#### `new MirrorDrive(src, dst, [options])` [#new-mirrordrivesrc-dst-options]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L72)
Creates a mirror instance to efficiently move `src` drive into `dst` drive.
| Parameter | Type | Default | Description |
| --------- | --------------------------------------------------------------------- | ------- | --------------------------------------------------- |
| `src` | [`Hyperdrive\|Localdrive`](/p2p/reference/building-blocks/hyperdrive) | — | Source drive to read from. |
| `dst` | [`Hyperdrive\|Localdrive`](/p2p/reference/building-blocks/hyperdrive) | — | Destination drive to write into (must be writable). |
| `options` | [`MirrorDriveOptions`](#mirrordriveoptions) | `{}` | Mirror options. |
#### `await mirror.done()` [#await-mirrordone]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L131)
It starts processing all the diffing until is done.
* Returns: [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) — Resolves when all diffs have been processed.
```js
const mirror = new MirrorDrive(src, dst)
await mirror.done()
console.log(mirror.count) // { files: 3, add: 2, remove: 0, change: 1 }
```
### Mirror state [#mirror-state]
#### `mirror.count` [#mirrorcount]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L90)
It counts the total files proccessed, added, removed, and changed.
* Returns: `{ files: number, add: number, remove: number, change: number }`
#### `mirror.bytesAdded` [#mirrorbytesadded]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L92)
The total number of bytes copied into the destination so far.
* Returns: `number`
#### `mirror.bytesRemoved` [#mirrorbytesremoved]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L91)
The total number of bytes removed from the destination so far.
* Returns: `number`
#### `mirror.finished` [#mirrorfinished]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L94)
`true` once the mirror pass has completed.
* Returns: `boolean`
#### `mirror.preloaded` [#mirrorpreloaded]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L81)
`true` once any configured preload phase has fetched the block maps it needs and estimated its download size. The blob ranges themselves may still be downloading.
* Returns: `boolean`
#### `mirror.peers` [#mirrorpeers]
[src](https://github.com/holepunchto/mirror-drive/blob/v1.14.2/index.js#L113)
The source drive's current peer list when `src.core` exists, otherwise an empty array.
* Returns: [`Array