custom-fs

custom-fs

A class for making your own version of fs with custom features such as a promise API and a virtual, in-memory caching system.

Status: works as specified, but only implements a handful of the fs methods. PRs welcome.

import CustomFS from 'custom-fs';

const fs = new CustomFS(options);

Options

The default set of options will give you an fs that is mostly compatible with the default fs module.

underlying (string, default: 'graceful-fs')

• name of the module to use as the underlying fs

callbacks (boolean, default: true)

• whether to enable the traditional Node-style callback API

promises (boolean, default: true)

• whether to return a promise from asynchronous methods like writeFile

autoResolve (boolean, default: true)

• allows you to specify paths as arrays of parts, to be resolved using path.resolve

base (string/array, default: process.cwd())

• allows you to specify a custom base from which to resolve relative paths

virtual (boolean/object, default: false)

• behave as an in-memory filesystem, optionally sync'd to a disk directory.
• see below for full settings.

Virtual filesystems

You can use the virtual option to make it an in-memory filesystem. This can also be made to sync its contents to or from a disk directory, so it can be used as a cache.

For a purely in-memory filesystem, set virtual to true. For more options, use an object.

A

Sub-options for virtual

• sync (object) – specifies disk-syncing options:

  • from (string/array) - makes it a sync-from-disk virtual filesystem, reading from the given directory. When .ready() is called for the first time, fs will load all files within the given directory into memory and continue to watch that directory for changes using sane. With a sync-from-disk fs, all write operations (writeFile etc.) are prohibited. Whenever you read a file, it will read from the in-memory store. If you try to read from outside the given directory, it will thrown an error.
  • saneOptions (object, optional) – in conjunction with from, you can specify options to pass to sane.
  • to (string/array) - path to automatically sync all changes to. Cannot be used in conjunction with from or watch – a virtual filesystem can only sync in one direction, or not at all. Recursively loads the contents of the given folder into memory on startup, then allows you to write to it.
  • keepEmptyDirs (boolean) – by default, if using sync.to, empty directories will be removed whenever the last file is removed from them. Set this option to true if you don't want this. Has no effect if not using sync.to.

• events (boolean, default true) – whether to emit events about files contents changing. Events are:

  • 'changing' – this fires to let you know a file's contents have changed in the in-memory store. (If there is a sync.to folder, the real path on disk won't necessarily have changed yet.) Payload is a Change instance.
  • 'changed' – when a file's contents have changed in memory – and changed on disk if applicable (i.e. if there's a sync.to). This always fires after the changing event. (In purely virtual filesystems, 'changed' will fire immediately after 'changing'.) Payload is a Change instance (exactly the same object as was passed to changing).
  • limit (string or number, default '100mB') – a pretty-bytes-compatible string, or a number of bytes. If the cumulative filesize of all the buffers stored in memory ever exceeds this limit, an error will be thrown.

getFiles()

On a virtual filesystem, you can call fs.getFiles() to retrieve an array of files currently in the virtual store. Each item in the array is an object with the keyss file (a file path) and contents (a buffer).

Waiting for it to be ready

If you've constructed a virtual fs that syncs to or from a disk directory, you may optionally wait for it to be ready (all files loaded into memory, plus disk watcher intialised in the case of a sync-from-disk fs) before using it for the first time, using fs.ready().then(...).

This method is called internally automatically when you call readFile or writeFile or similar, so there's no need to use it unless you want to get a syncing virtual filesystem up and running ahead of time.

Files outside the sync directory

With sync.to, if you write a file outside this directory, it will error.

Other stuff

If virtual is enabled, any call to writeFile also gets a value (as your callback's second arg, and/or as the fulfillment value of the promise).

• if the file's contents actually changed as a result of the write, you'll get a change object (see below).
• if the file's contents didn't change, you'll get null.