Skip to main content

@yarnpkg/fslib

A TypeScript library abstracting the Node filesystem APIs. We use it for three main reasons:

Type-safe paths

Our library has two path types, NativePath and PortablePath. Most interfaces only accept the later, and instances of the former need to be transformed back and forth using our type-safe utilities before being usable.

Custom filesystems

The FSLib implements various transparent filesystem layers for a variety of purposes. For instance we use it in Yarn in order to abstract away the zip archive manipulation logic, which is implemented in ZipFS and exposed through a Node-like interface (called FakeFS).

All FakeFS implementations can be transparently layered on top of the builtin Node fs module, and that's for instance how we can add support for in-zip package loading without you having to care about the exact package format.

Promisified API

All methods from the FakeFS interface are promisified by default (and suffixed for greater clarity, for instance we offer both readFileSync and readFilePromise).

Index

Functions

extendFs

normalizeLineEndings

  • normalizeLineEndings(originalContent: string, newContent: string): string
  • Parameters

    • originalContent: string
    • newContent: string

    Returns string

opendir

patchFs

setupCopyIndex

  • setupCopyIndex<P>(destinationFs: FakeFS<P>, linkStrategy: Pick<HardlinkFromIndexStrategy<P>, indexPath>): Promise<P>
  • Type parameters

    Parameters

    • destinationFs: FakeFS<P>
    • linkStrategy: Pick<HardlinkFromIndexStrategy<P>, indexPath>

    Returns Promise<P>

unwatchAllFiles

unwatchFile

watchFile

Type Aliases

BigIntStats

BigIntStats: NodeBigIntStats & { crc?: number }

BufferEncodingOrBuffer

BufferEncodingOrBuffer: BufferEncoding | buffer

CreateReadStreamOptions

CreateReadStreamOptions: Partial<{ encoding: BufferEncoding; fd: number }>

CreateWriteStreamOptions

CreateWriteStreamOptions: Partial<{ encoding: BufferEncoding; fd: number; flags: a }>

Dir

Dir<P>: { path: P; [asyncIterator]: any; close: any; closeSync: any; read: any; readSync: any }

Type parameters

Type declaration

  • readonlypath: P
  • [asyncIterator]: function

  • close: function
    • close(): Promise<void>
    • close(cb: NoParamCallback): void

    • Returns Promise<void>

  • closeSync: function
    • closeSync(): void

    • Returns void

  • read: function

  • readSync: function

Dirent

Dirent<T>: Omit<NodeDirent, name | path> & { name: Filename; path: T }

Type parameters

DirentNoPath

DirentNoPath: Omit<NodeDirent, name | path> & { name: Filename }

ExtractHintOptions

ExtractHintOptions: { relevantExtensions: Set<string> }

Type declaration

  • relevantExtensions: Set<string>

FSPath

FSPath<T>: T | number

Type parameters

Filename

Filename: string & { __pathType: PathType.File }

GetMountPointFn

GetMountPointFn: (path: PortablePath, prefixPath: PortablePath) => PortablePath | null

Type declaration

LinkStrategy

LinkStrategy<P>: HardlinkFromIndexStrategy<P>

Type parameters

  • P

MkdirOptions

MkdirOptions: Partial<{ mode: number; recursive: boolean }>

MountFSOptions

MountFSOptions<MountedFS>: { baseFs?: FakeFS<PortablePath>; factoryPromise: (baseFs: FakeFS<PortablePath>, path: PortablePath) => Promise<() => MountedFS>; factorySync: (baseFs: FakeFS<PortablePath>, path: PortablePath) => MountedFS; filter?: RegExp | null; getMountPoint: GetMountPointFn; magicByte?: number; maxAge?: number; maxOpenFiles?: number; typeCheck?: number | null; useCache?: boolean }

Type parameters

Type declaration

  • optionalbaseFs?: FakeFS<PortablePath>
  • factoryPromise: (baseFs: FakeFS<PortablePath>, path: PortablePath) => Promise<() => MountedFS>
  • factorySync: (baseFs: FakeFS<PortablePath>, path: PortablePath) => MountedFS

    Functions used to create the sub-filesystem to use when accessing specific paths.

  • optionalfilter?: RegExp | null
  • getMountPoint: GetMountPointFn

    A function that will be called to figure out the segment of a path that represents a mount point.

    It must return a strict prefix of the original path, or null if the path isn't part of a mount archive.

  • optionalmagicByte?: number
  • optionalmaxAge?: number

    Maximum age of the child filesystem, after which they will be discarded. Each new access resets this time.

    Only used if useCache is set to true.

  • optionalmaxOpenFiles?: number
  • optionaltypeCheck?: number | null
  • optionaluseCache?: boolean

NativePath

NativePath: string & { __pathType?: PathType.File | PathType.Native }

OpendirOptions

OpendirOptions: Partial<{ bufferSize: number; recursive: boolean }>

Path

PortablePath

PortablePath: string & { __pathType: PathType.File | PathType.Portable }

ReaddirOptions

ReaddirOptions: Partial<{ recursive: boolean; withFileTypes: boolean }>

RmdirOptions

RmdirOptions: Partial<{ maxRetries: number; recursive: boolean; retryDelay: number }>

StatWatcher

StatWatcher: EventEmitter & { ref: () => StatWatcher; unref: () => StatWatcher }

Stats

Stats: NodeStats & { crc?: number }

SymlinkType

SymlinkType: file | dir | junction

WatchCallback

WatchCallback: (eventType: string, filename: string) => void

Type declaration

    • (eventType: string, filename: string): void
    • Parameters

      • eventType: string
      • filename: string

      Returns void

WatchFileCallback

WatchFileCallback: (current: Stats, previous: Stats) => void

Type declaration

WatchFileOptions

WatchFileOptions: Partial<{ bigint: boolean; interval: number; persistent: boolean }>

WatchOptions

WatchOptions: Partial<{ encoding: BufferEncodingOrBuffer; persistent: boolean; recursive: boolean }> | BufferEncodingOrBuffer

Watcher

Watcher: { close: () => void; on: any }

Type declaration

  • close: () => void
      • (): void
      • Returns void

  • on: any

WriteFileOptions

WriteFileOptions: Partial<{ encoding: BufferEncoding; flag: string; mode: number }> | BufferEncoding

XFS

XFS: NodeFS & { detachTemp: any; mktempPromise: any; mktempSync: any; rmtempPromise: any; rmtempSync: any }

Variables

Filename

Filename: { env: Filename; home: Filename; lockfile: Filename; manifest: Filename; nodeModules: Filename; pnpCjs: Filename; pnpData: Filename; pnpEsmLoader: Filename; pnpJs: Filename; rc: Filename; virtual: Filename }

Type declaration

PortablePath

PortablePath: { dot: PortablePath; parent: PortablePath; root: PortablePath }

Type declaration

constnpath

npath: PathUtils<NativePath> & ConvertUtils = ...

constppath

ppath: PathUtils<PortablePath> & PortablePathGenerics = ...

constxfs

xfs: XFS = ...