# `snapshot` utility

The `snapshot` utility allows to create `fs` file system directory or file
snapshots. It recursively creates a snapshot of the specified directory. Later the
snapshot can be unpacked back into some directory. It supports symlinks.

## Usage

The functionality is exposed as a collection of utility functions.

```ts
import * as snapshot from 'memfs/lib/snapshot';
```

- `snapshot.toSnapshotSync()` — returns POJO snapshot synchronously.
- `snapshot.toSnapshot()` — returns POJO snapshot asynchronously.
- `snapshot.fromSnapshotSync()` — imports POJO snapshot synchronously.
- `snapshot.fromSnapshot()` — imports POJO snapshot asynchronously.
- `snapshot.toBinarySnapshotSync()` — returns CBOR `Uint8Array` snapshot synchronously.
- `snapshot.toBinarySnapshot()` — returns CBOR `Uint8Array` snapshot asynchronously.
- `snapshot.fromBinarySnapshotSync()` — imports CBOR `Uint8Array` snapshot synchronously.
- `snapshot.fromBinarySnapshot()` — imports CBOR `Uint8Array` snapshot asynchronously.
- `snapshot.toJsonSnapshotSync()` — returns JSON `Uint8Array` snapshot synchronously.
- `snapshot.toJsonSnapshot()` — returns JSON `Uint8Array` snapshot asynchronously.
- `snapshot.fromJsonSnapshotSync()` — imports JSON `Uint8Array` snapshot synchronously.
- `snapshot.fromJsonSnapshot()` — imports JSON `Uint8Array` snapshot asynchronously.

## POJO snapshot

You can convert any folder of an `fs`-like file system into a POJO snapshot.

```ts
const snap = snapshot.toSnapshotSync({ fs, path });
const snap = await snapshot.toSnapshot({ fs: fs.promises, path });
```

Then import it back from snapshot.

```ts
snapshot.fromSnapshotSync(snap, { fs, path });
await snapshot.fromSnapshot(snap, { fs: fs.promises, path });
```

## Binary snapshot

Binary snapshots are encoded as CBOR `Uint8Array` buffers. You can convert any
folder of an `fs`-like file system into a `Uint8Array` snapshot.

```ts
const uint8 = snapshot.toBinarySnapshotSync({ fs, path });
const uint8 = await snapshot.toBinarySnapshot({ fs: fs.promises, path });
```

Then import it back from `Uint8Array` snapshot.

```ts
snapshot.fromBinarySnapshotSync(uint8, { fs, path });
await snapshot.fromBinarySnapshot(uint8, { fs: fs.promises, path });
```

## JSON snapshot

JSON snapshots use JSON encoding, but they also support binary data. The binary
data is encoded as Base64 data URL strings. The resulting JSON is returned as
`Uint8Array` buffer.

You can convert any folder of an `fs`-like file system into a `Uint8Array` snapshot.

```ts
const uint8 = snapshot.toJsonSnapshotSync({ fs, path });
const uint8 = await snapshot.toJsonSnapshot({ fs: fs.promises, path });
```

Then import it back from `Uint8Array` snapshot.

```ts
snapshot.fromJsonSnapshotSync(uint8, { fs, path });
await snapshot.fromJsonSnapshot(uint8, { fs: fs.promises, path });
```

## Encoding format

The snapshot follows [Compact JSON](https://jsonjoy.com/specs/compact-json) encoding
scheme, where each node is encoded as an array tuple, where the first element
is the node type.

### Directory node

Directory nodes are have type `0`, the second tuple element is the metadata object, and
the third element is a map of child nodes.

```ts
[
  0,
  {},
  {
    file: [1, {}, new Uint8Array([1, 2, 3])],
  },
];
```

### File node

File nodes have type `1`, the second tuple element is the metadata object, and
the third element is the file content encoded as `Uint8Array`.

```ts
[1, {}, new Uint8Array([1, 2, 3])];
```

### Symlink node

Symlink nodes have type `2`, the second tuple element is the metadata object.

```ts
[2, { target: 'file' }];
```