Skip to content

Latest commit

 

History

History
117 lines (85 loc) · 3.59 KB

index.md

File metadata and controls

117 lines (85 loc) · 3.59 KB

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.

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.

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

Then import it back from snapshot.

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.

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

Then import it back from Uint8Array snapshot.

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.

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

Then import it back from Uint8Array snapshot.

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

Encoding format

The snapshot follows 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.

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

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

Symlink node

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

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