node-fsapi

A small, POSIX-like filesystem API for Node.js, written in TypeScript. It provides an in-memory filesystem and building blocks to combine filesystems: mounting, chroot, read-only views and tracing.

npm install @k13engineering/fsapi

Example

import { createRamFileSystem, createConvenienceApi } from "@k13engineering/fsapi";

const fileSystem = createRamFileSystem();
const api = createConvenienceApi({ fileSystem });

await api.mkdirOrThrow({ filepath: "/etc/app", recursive: true });
await api.writeFileOrThrow({ filepath: "/etc/app/config", data: new TextEncoder().encode("debug=1") });

const data = await api.readFileOrThrow({ filepath: "/etc/app/config" });

Concepts

Errors are values. Operations return { errno: undefined, ...result } on success and { errno } on failure, using Linux errno values (EErrno). Exceptions are only thrown for programming errors, such as paths that are not normalised (see below). The *OrThrow convenience functions throw errors created by createErrorFromErrno, which carry errno and code properties.

Paths are absolute and normalised. Every path must start with /, must not end with / (except / itself), and must not contain //, . or ... Violations throw.

Symlinks are never followed. Opening a path opens the entry itself, as with O_NOFOLLOW. A path through a symlinked directory fails with ENOTDIR. Resolving symlinks is left to the caller.

Files are created first, then linked. create*FileHandle() creates an unnamed node. fileHandle.link({ filepath }) gives it a name, and calling link again creates a hard link.

Inodes are identified by dev, ino and generation. stat reports all three. The generation tells apart inodes that got the same number one after another, so the three together identify an inode for its whole lifetime, e.g. as the key of a cache. A filesystem that never reuses inode numbers, like the RAM filesystem, may report 0.

IO goes through IO handles. fileHandle.openIO({ actions: { read, write } }) returns an IO handle with read, writev, pread, pwritev, lseek, truncate and getdents.

Watching

fileHandle.watch() reports changes of the handle's inode. The watch keeps working after the handle is closed, until close() is called on it:

const watch = fileHandle.watch({
  events: { content: true, attributes: true, entries: true, access: false },
  onChanged: ({ change }) => {
    // change.content, change.contentRanges, change.attributes, change.entries, change.access
  },
  onRemoved: () => {
    // the last link of the inode was removed
  }
});

watch.close();

| Event | Reported when | | --- | --- | | content | the data of a regular file is written or truncated; contentRanges lists the bytes that changed, or is undefined if they are not known | | attributes | the mode, owner, size, link count, mtime or ctime changes | | entries | entries of a directory are added, removed or renamed | | access | the atime changes, e.g. by reading; leave it out unless needed, or reading what changed reports a change again |

The guarantees:

• Nothing is missed. Every change is reported once it is visible. Changes may be reported that did not happen, so treat a change as a reason to look again.
• Callbacks are asynchronous. They are never called within the operation that changed the inode, and changes in the meantime are merged into one call.
• Removal is exact. onRemoved is called once, when the last link of the inode is removed, and nothing is called afterwards.
• Paths are not watched. Renaming or removing an entry is reported as entries of its directory. To notice that a path leads somewhere else, watch the directories along it.
• Watching cannot fail. A filesystem that cannot tell what changed emulates it with createPollingWatchEmulation(), which reports all events of every watch on each poll, and detects removal through the link count. createWatchHub() does the merging and delivery for filesystems that report changes themselves.

Watch, then read: create the watch before reading the state it is about, so that no change falls between the two.

Filesystems and wrappers

| Function | Description | | --- | --- | | createRamFileSystem() | In-memory filesystem with regular files, directories, symlinks, device nodes, fifos and sockets. Device nodes, fifos and sockets cannot be opened for IO. | | createVirtualFileSystem(mapping) | Mounts filesystems at paths, e.g. { "/": rootFs, "/mnt": otherFs }. Hard links and renames across mounts fail with EXDEV. | | createChroot({ fileSystem, newRoot }) | Restricts a filesystem to a subdirectory. | | createReadOnlyFileSystem({ fileSystem }) | Turns a read-only implementation into a TFilesystem that rejects modifications with EROFS. | | createSentinel({ fsapi }) | Validates all paths before they reach the wrapped filesystem. Used by ramfs and vfs. | | createFileSystemTracer({ fileSystem, logger }) | Logs every operation with its parameters and result. | | createStubFileSystem(), createStubExceptionFileSystem() | Implement nothing, returning ENOSYS or throwing. They are useful as a base for partial implementations. |

Convenience API

createConvenienceApi({ fileSystem }) provides path-based functions, each with an *OrThrow variant:

readFile, writeFile, mkdir (optionally recursive), readdir, lstat, exists, unlink, rmdir, rename, symlink, readlink, chmod, chown, utimens, createBlockDeviceNode and createCharacterDeviceNode.

None of them follow symlinks.

Constants

• EErrno, errnoName({ errno }): Linux errno values and their names.
• openFlags: Linux open() flags for the running architecture. Some values differ between x86, arm and powerpc. createOpenFlags({ arch }) returns the flags for a given Node.js process.arch value.
• EWhence: SEEK_SET, SEEK_CUR and SEEK_END for lseek.

Development

npm ci
npm run build
npm run type-check
npm run test
npm run lint

License

LGPL-2.1-only