or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdconstants-and-utilities.mdfilesystem-abstractions.mdfilesystem-implementations.mdindex.mdpath-handling.md
tile.json

tessl/npm-yarnpkg--fslib

A TypeScript library abstracting the Node filesystem APIs with virtual filesystems and cross-platform path handling

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@yarnpkg/fslib@3.1.x

To install, run

npx @tessl/cli install tessl/npm-yarnpkg--fslib@3.1.0

index.mddocs/

@yarnpkg/fslib

A comprehensive filesystem abstraction library that provides cross-platform filesystem operations with support for virtual filesystems, path utilities, and filesystem compositions. This library is the foundation for Yarn's filesystem operations and offers a unified API for working with different filesystem implementations.

Package Information

  • Name: @yarnpkg/fslib
  • Type: TypeScript Library
  • Language: TypeScript
  • Installation: npm install @yarnpkg/fslib or yarn add @yarnpkg/fslib

Core Imports

The package provides several key entry points for different functionalities:

// Main filesystem abstractions and implementations
import {
  FakeFS, BasePortableFakeFS,
  NodeFS, NodePathFS, VirtualFS, JailFS, CwdFS, 
  MountFS, AliasFS, LazyFS, PosixFS, ProxiedFS, NoFS
} from '@yarnpkg/fslib';

// Extended filesystem with temporary file operations
import { xfs, type XFS } from '@yarnpkg/fslib';

// Path utilities for cross-platform path handling
import { 
  npath, ppath,
  type PortablePath, type NativePath, type Filename, type Path, type FSPath
} from '@yarnpkg/fslib';

// Constants, errors, and statistics utilities
import { constants, errors, statUtils } from '@yarnpkg/fslib';

// Algorithm utilities and filesystem patching
import { 
  setupCopyIndex, opendir, CustomDir,
  watchFile, unwatchFile, unwatchAllFiles,
  patchFs, extendFs
} from '@yarnpkg/fslib';

Basic Usage

Working with the Extended Filesystem (XFS)

The most common entry point is the xfs instance, which provides all standard filesystem operations plus temporary file management:

import { xfs, ppath } from '@yarnpkg/fslib';

// Read and write files
const content = await xfs.readFilePromise('/path/to/file.txt', 'utf8');
await xfs.writeFilePromise('/path/to/output.txt', content);

// Work with directories
await xfs.mkdirPromise('/new/directory', { recursive: true });
const files = await xfs.readdirPromise('/directory');

// Temporary file operations
const tempDir = await xfs.mktempPromise();
await xfs.writeFilePromise(ppath.join(tempDir, 'temp.txt'), 'data');
await xfs.rmtempPromise(); // Clean up all temp directories

Cross-Platform Path Handling

Use ppath for portable paths and npath for platform-native paths:

import { ppath, npath, type PortablePath } from '@yarnpkg/fslib';

// Portable paths (always use forward slashes)
const portablePath = ppath.join('/base' as PortablePath, 'sub/file.txt');
const resolved = ppath.resolve('/current' as PortablePath, '../relative/path');

// Convert between portable and native paths
const nativePath = npath.fromPortablePath(portablePath);
const backToPortable = npath.toPortablePath(nativePath);

Virtual Filesystem Operations

Create in-memory filesystems for testing or isolated operations:

import { VirtualFS, ppath } from '@yarnpkg/fslib';

const vfs = new VirtualFS();
await vfs.mkdirPromise('/virtual' as PortablePath, { recursive: true });
await vfs.writeFilePromise('/virtual/file.txt' as PortablePath, 'content');
const content = await vfs.readFilePromise('/virtual/file.txt' as PortablePath, 'utf8');

Architecture

The library is built around several key concepts:

Filesystem Abstractions

  • FakeFS: Abstract base class providing the complete filesystem interface
  • BasePortableFakeFS: Base class for portable path filesystems
  • ProxiedFS: Base for filesystem decorators that proxy to other filesystems

Filesystem Implementations

  • NodeFS: Direct interface to Node.js filesystem
  • VirtualFS: In-memory filesystem implementation
  • JailFS: Security-focused filesystem restricting access to a specific directory
  • CwdFS: Filesystem operating relative to a specific working directory
  • MountFS: Combines multiple filesystems into a unified view

Path System

  • Portable Paths: Cross-platform paths using forward slashes
  • Native Paths: Platform-specific paths
  • Path Utilities: Comprehensive path manipulation functions

Capabilities

Path Handling and Utilities

Cross-platform path manipulation with type safety and conversion utilities.

Key APIs:

// Join and resolve paths
const joined = ppath.join('/base' as PortablePath, 'sub', 'file.txt');
const resolved = ppath.resolve('/current' as PortablePath, '../file.txt');

// Path analysis
const isAbs = ppath.isAbsolute('/absolute/path' as PortablePath);
const relative = ppath.relative('/from' as PortablePath, '/to/file.txt' as PortablePath);
const dirname = ppath.dirname('/path/to/file.txt' as PortablePath);

Detailed documentation: Path Handling

Filesystem Abstractions and Interfaces

Core filesystem interfaces and base classes for building filesystem implementations.

Key APIs:

import { FakeFS, type Stats, type Dirent } from '@yarnpkg/fslib';

// Standard filesystem operations available on all implementations
abstract class FakeFS<P extends Path> {
  abstract readFilePromise(p: P, encoding?: BufferEncoding): Promise<string | Buffer>;
  abstract writeFilePromise(p: P, content: string | Buffer): Promise<void>;
  abstract mkdirPromise(p: P, options?: MkdirOptions): Promise<void>;
  abstract readdirPromise(p: P, options?: ReaddirOptions): Promise<string[] | Dirent<P>[]>;
}

Detailed documentation: Filesystem Abstractions

Filesystem Implementations

Concrete filesystem implementations for different use cases.

Key APIs:

// Real filesystem access
import { NodeFS } from '@yarnpkg/fslib';
const nodeFs = new NodeFS();

// Virtual in-memory filesystem
import { VirtualFS } from '@yarnpkg/fslib';
const virtualFs = new VirtualFS();

// Security-restricted filesystem
import { JailFS } from '@yarnpkg/fslib';
const jailedFs = new JailFS('/safe/directory' as PortablePath, { baseFs: nodeFs });

Detailed documentation: Filesystem Implementations

Constants, Errors, and Utilities

File mode constants, error factories, and statistics utilities.

Key APIs:

import { constants, errors, statUtils } from '@yarnpkg/fslib';

// File mode constants
const isDirectory = (mode: number) => (mode & constants.S_IFMT) === constants.S_IFDIR;

// Error creation
throw errors.ENOENT('File not found: /missing/file.txt');

// Statistics utilities
const stats = statUtils.makeDefaultStats();
const areEqual = statUtils.areStatsEqual(stats1, stats2);

Detailed documentation: Constants and Utilities

Advanced Features and Algorithms

Advanced filesystem operations, patching, and algorithm utilities.

Key APIs:

// Filesystem patching
import { patchFs, extendFs } from '@yarnpkg/fslib';
import * as fs from 'fs';
const patchedFs = patchFs(fs, customFileSystem);

// Extended filesystem with temp file management
import { xfs } from '@yarnpkg/fslib';
const tempDir = await xfs.mktempPromise();
await xfs.rmtempPromise();

// Directory operations
import { opendir, CustomDir } from '@yarnpkg/fslib';
const dir = await opendir(filesystem, '/path' as PortablePath);

Detailed documentation: Advanced Features

Related Documentation