tessl/npm-yarnpkg--fslib

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@yarnpkg/fslib

Name: tessl/npm-yarnpkg--fslib
Author: tessl

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

tessl/npm-yarnpkg--fslib

@yarnpkg/fslib

Package Information

Core Imports

Basic Usage

Working with the Extended Filesystem (XFS)

Cross-Platform Path Handling

Virtual Filesystem Operations

Architecture

Filesystem Abstractions

Filesystem Implementations

Path System

Capabilities

Path Handling and Utilities

Filesystem Abstractions and Interfaces

Filesystem Implementations

Constants, Errors, and Utilities

Advanced Features and Algorithms

Related Documentation