@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

Classes

• AliasFS
• BasePortableFakeFS
• CustomDir
• CwdFS
• FakeFS
• JailFS
• LazyFS
• MountFS
• NoFS
• NodeFS
• PosixFS
• ProxiedFS
• VirtualFS

Functions

• extendFs
• normalizeLineEndings
• opendir
• patchFs
• setupCopyIndex
• unwatchAllFiles
• unwatchFile
• watchFile

Interfaces

• FormatInputPathObject
• MountableFS
• ParsedPath
• PathUtils
• StatOptions
• StatSyncOptions

Namespaces

• constants
• errors
• statUtils

Type Aliases

• BigIntStats
• BufferEncodingOrBuffer
• CreateReadStreamOptions
• CreateWriteStreamOptions
• Dir
• Dirent
• DirentNoPath
• ExtractHintOptions
• FSPath
• Filename
• GetMountPointFn
• LinkStrategy
• MkdirOptions
• MountFSOptions
• NativePath
• OpendirOptions
• Path
• PortablePath
• ReaddirOptions
• RmOptions
• RmdirOptions
• StatWatcher
• Stats
• SymlinkType
• WatchCallback
• WatchFileCallback
• WatchFileOptions
• WatchOptions
• Watcher
• WriteFileOptions
• XFS

Variables

• Filename
• PortablePath
• npath
• ppath
• xfs

Functions

extendFs

• extendFs(realFs: __module, fakeFs: FakeFS<NativePath>): typeof fs

• Parameters

  • realFs: __module

  • fakeFs: FakeFS<NativePath>

  Returns typeof fs

normalizeLineEndings

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

• Parameters

  • originalContent: string

  • newContent: string

  Returns string

opendir

• opendir<P>(fakeFs: FakeFS<P>, path: P, entries: Filename[], opts?: CustomDirOptions): CustomDir<P>

• Type parameters

  • P: Path

  Parameters

  • fakeFs: FakeFS<P>

  • path: P

  • entries: Filename[]

  • optionalopts: CustomDirOptions

  Returns CustomDir<P>

patchFs

• patchFs(patchedFs: __module, fakeFs: FakeFS<NativePath>): void

• Parameters

  • patchedFs: __module

  • fakeFs: FakeFS<NativePath>

  Returns void

setupCopyIndex

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

• Type parameters

  • P: Path

  Parameters

  • destinationFs: FakeFS<P>

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

  Returns Promise<P>

unwatchAllFiles

• unwatchAllFiles(fakeFs: FakeFS<Path>): void

• Parameters

  • fakeFs: FakeFS<Path>

  Returns void

unwatchFile

• unwatchFile<P>(fakeFs: FakeFS<P>, path: P, cb?: WatchFileCallback): void

• Type parameters

  • P: Path

  Parameters

  • fakeFs: FakeFS<P>

  • path: P

  • optionalcb: WatchFileCallback

  Returns void

watchFile

• watchFile<P>(fakeFs: FakeFS<P>, path: P, a: WatchFileCallback | Partial<{ bigint: boolean; interval: number; persistent: boolean }>, b?: WatchFileCallback): CustomStatWatcher<P>

• Type parameters

  • P: Path

  Parameters

  • fakeFs: FakeFS<P>

  • path: P

  • a: WatchFileCallback | Partial<{ bigint: boolean; interval: number; persistent: boolean }>

  • optionalb: WatchFileCallback

  Returns CustomStatWatcher<P>

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

• P: Path

Type declaration

• readonlypath: P

• [asyncIterator]: function

  • [asyncIterator](): AsyncIterableIterator<DirentNoPath>

  ---

  • Returns AsyncIterableIterator<DirentNoPath>

• close: function

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

  ---

  • Returns Promise<void>

• closeSync: function

  • closeSync(): void

  ---

  • Returns void

• read: function

  • read(): Promise<null | DirentNoPath>
  • read(cb: (err: null | ErrnoException, dirent: null | DirentNoPath) => void): void

  ---

  • Returns Promise<null | DirentNoPath>

• readSync: function

  • readSync(): null | DirentNoPath

  ---

  • Returns null | DirentNoPath

Dirent

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

Type parameters

• T: Path

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

• T: Path

Filename

Filename: string & { __pathType: PathType.File }

GetMountPointFn

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

Type declaration

• • (path: PortablePath, prefixPath: PortablePath): PortablePath | null

  • Parameters

    • path: PortablePath

    • prefixPath: PortablePath

    Returns PortablePath | null

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

• MountedFS: MountableFS

Type declaration

• optionalbaseFs?: FakeFS<PortablePath>

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

  • • (baseFs: FakeFS<PortablePath>, path: PortablePath): Promise<() => MountedFS>

    • Parameters

      • baseFs: FakeFS<PortablePath>

      • path: PortablePath

      Returns Promise<() => MountedFS>

• factorySync: (baseFs: FakeFS<PortablePath>, path: PortablePath) => MountedFS

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

  • • (baseFs: FakeFS<PortablePath>, path: PortablePath): MountedFS

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

      ---

      Parameters

      • baseFs: FakeFS<PortablePath>

      • path: PortablePath

      Returns MountedFS

• 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

Path: PortablePath | NativePath

PortablePath

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

ReaddirOptions

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

RmOptions

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

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

• • (current: Stats, previous: Stats): void

  • Parameters

    • current: Stats

    • previous: Stats

    Returns void

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

• env: Filename

• home: Filename

• lockfile: Filename

• manifest: Filename

• nodeModules: Filename

• pnpCjs: Filename

• pnpData: Filename

• pnpEsmLoader: Filename

• pnpJs: Filename

  @deprecated

• rc: Filename

• virtual: Filename

PortablePath

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

Type declaration

• dot: PortablePath

• parent: PortablePath

• root: PortablePath

constnpath

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

constppath

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

constxfs

xfs: XFS = ...