Skip to main content Link Search Menu Expand Document (external link)

FileSystem overview

Added in v1.0.0


Table of contents


constructor

FileDescriptor

Signature

export declare const FileDescriptor: any

Added in v1.0.0

WatchEventCreate

Signature

export declare const WatchEventCreate: Data.Case.Constructor<WatchEvent.Create, "_tag">

Added in v1.0.0

WatchEventRemove

Signature

export declare const WatchEventRemove: Data.Case.Constructor<WatchEvent.Remove, "_tag">

Added in v1.0.0

WatchEventUpdate

Signature

export declare const WatchEventUpdate: Data.Case.Constructor<WatchEvent.Update, "_tag">

Added in v1.0.0

make

Signature

export declare const make: (
  impl: Omit<FileSystem, "exists" | "readFileString" | "stream" | "sink" | "writeFileString">
) => FileSystem

Added in v1.0.0

makeNoop

Create a no-op file system that can be used for testing.

Signature

export declare const makeNoop: (fileSystem: Partial<FileSystem>) => FileSystem

Added in v1.0.0

file watcher

WatchBackend (class)

Signature

export declare class WatchBackend

Added in v1.0.0

guard

isFile

Signature

export declare const isFile: (u: unknown) => u is File

Added in v1.0.0

layers

layerNoop

Create a no-op file system that can be used for testing.

Signature

export declare const layerNoop: (fileSystem: Partial<FileSystem>) => Layer<FileSystem>

Added in v1.0.0

model

File (interface)

Signature

export interface File {
  readonly [FileTypeId]: FileTypeId
  readonly fd: File.Descriptor
  readonly stat: Effect.Effect<File.Info, PlatformError>
  readonly seek: (offset: SizeInput, from: SeekMode) => Effect.Effect<void>
  readonly read: (buffer: Uint8Array) => Effect.Effect<Size, PlatformError>
  readonly readAlloc: (size: SizeInput) => Effect.Effect<Option<Uint8Array>, PlatformError>
  readonly truncate: (length?: SizeInput) => Effect.Effect<void, PlatformError>
  readonly write: (buffer: Uint8Array) => Effect.Effect<Size, PlatformError>
  readonly writeAll: (buffer: Uint8Array) => Effect.Effect<void, PlatformError>
}

Added in v1.0.0

FileSystem (interface)

Signature

export interface FileSystem {
  /**
   * Check if a file can be accessed.
   * You can optionally specify the level of access to check for.
   */
  readonly access: (path: string, options?: AccessFileOptions) => Effect.Effect<void, PlatformError>
  /**
   * Copy a file or directory from `fromPath` to `toPath`.
   *
   * Equivalent to `cp -r`.
   */
  readonly copy: (fromPath: string, toPath: string, options?: CopyOptions) => Effect.Effect<void, PlatformError>
  /**
   * Copy a file from `fromPath` to `toPath`.
   */
  readonly copyFile: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>
  /**
   * Change the permissions of a file.
   */
  readonly chmod: (path: string, mode: number) => Effect.Effect<void, PlatformError>
  /**
   * Change the owner and group of a file.
   */
  readonly chown: (path: string, uid: number, gid: number) => Effect.Effect<void, PlatformError>
  /**
   * Check if a path exists.
   */
  readonly exists: (path: string) => Effect.Effect<boolean, PlatformError>
  /**
   * Create a hard link from `fromPath` to `toPath`.
   */
  readonly link: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>
  /**
   * Create a directory at `path`. You can optionally specify the mode and
   * whether to recursively create nested directories.
   */
  readonly makeDirectory: (path: string, options?: MakeDirectoryOptions) => Effect.Effect<void, PlatformError>
  /**
   * Create a temporary directory.
   *
   * By default the directory will be created inside the system's default
   * temporary directory, but you can specify a different location by setting
   * the `directory` option.
   *
   * You can also specify a prefix for the directory name by setting the
   * `prefix` option.
   */
  readonly makeTempDirectory: (options?: MakeTempDirectoryOptions) => Effect.Effect<string, PlatformError>
  /**
   * Create a temporary directory inside a scope.
   *
   * Functionally equivalent to `makeTempDirectory`, but the directory will be
   * automatically deleted when the scope is closed.
   */
  readonly makeTempDirectoryScoped: (options?: MakeTempDirectoryOptions) => Effect.Effect<string, PlatformError, Scope>
  /**
   * Create a temporary file.
   * The directory creation is functionally equivalent to `makeTempDirectory`.
   * The file name will be a randomly generated string.
   */
  readonly makeTempFile: (options?: MakeTempFileOptions) => Effect.Effect<string, PlatformError>
  /**
   * Create a temporary file inside a scope.
   *
   * Functionally equivalent to `makeTempFile`, but the file will be
   * automatically deleted when the scope is closed.
   */
  readonly makeTempFileScoped: (options?: MakeTempFileOptions) => Effect.Effect<string, PlatformError, Scope>
  /**
   * Open a file at `path` with the specified `options`.
   *
   * The file handle will be automatically closed when the scope is closed.
   */
  readonly open: (path: string, options?: OpenFileOptions) => Effect.Effect<File, PlatformError, Scope>
  /**
   * List the contents of a directory.
   *
   * You can recursively list the contents of nested directories by setting the
   * `recursive` option.
   */
  readonly readDirectory: (path: string, options?: ReadDirectoryOptions) => Effect.Effect<Array<string>, PlatformError>
  /**
   * Read the contents of a file.
   */
  readonly readFile: (path: string) => Effect.Effect<Uint8Array, PlatformError>
  /**
   * Read the contents of a file.
   */
  readonly readFileString: (path: string, encoding?: string) => Effect.Effect<string, PlatformError>
  /**
   * Read the destination of a symbolic link.
   */
  readonly readLink: (path: string) => Effect.Effect<string, PlatformError>
  /**
   * Resolve a path to its canonicalized absolute pathname.
   */
  readonly realPath: (path: string) => Effect.Effect<string, PlatformError>
  /**
   * Remove a file or directory.
   */
  readonly remove: (path: string, options?: RemoveOptions) => Effect.Effect<void, PlatformError>
  /**
   * Rename a file or directory.
   */
  readonly rename: (oldPath: string, newPath: string) => Effect.Effect<void, PlatformError>
  /**
   * Create a writable `Sink` for the specified `path`.
   */
  readonly sink: (path: string, options?: SinkOptions) => Sink<void, Uint8Array, never, PlatformError>
  /**
   * Get information about a file at `path`.
   */
  readonly stat: (path: string) => Effect.Effect<File.Info, PlatformError>
  /**
   * Create a readable `Stream` for the specified `path`.
   *
   * Changing the `bufferSize` option will change the internal buffer size of
   * the stream. It defaults to `4`.
   *
   * The `chunkSize` option will change the size of the chunks emitted by the
   * stream. It defaults to 64kb.
   *
   * Changing `offset` and `bytesToRead` will change the offset and the number
   * of bytes to read from the file.
   */
  readonly stream: (path: string, options?: StreamOptions) => Stream<Uint8Array, PlatformError>
  /**
   * Create a symbolic link from `fromPath` to `toPath`.
   */
  readonly symlink: (fromPath: string, toPath: string) => Effect.Effect<void, PlatformError>
  /**
   * Truncate a file to a specified length. If the `length` is not specified,
   * the file will be truncated to length `0`.
   */
  readonly truncate: (path: string, length?: SizeInput) => Effect.Effect<void, PlatformError>
  /**
   * Change the file system timestamps of the file at `path`.
   */
  readonly utimes: (path: string, atime: Date | number, mtime: Date | number) => Effect.Effect<void, PlatformError>
  /**
   * Watch a directory or file for changes
   */
  readonly watch: (path: string) => Stream<WatchEvent, PlatformError>
  /**
   * Write data to a file at `path`.
   */
  readonly writeFile: (path: string, data: Uint8Array, options?: WriteFileOptions) => Effect.Effect<void, PlatformError>
  /**
   * Write a string to a file at `path`.
   */
  readonly writeFileString: (
    path: string,
    data: string,
    options?: WriteFileStringOptions
  ) => Effect.Effect<void, PlatformError>
}

Added in v1.0.0

OpenFlag (type alias)

Signature

export type OpenFlag = "r" | "r+" | "w" | "wx" | "w+" | "wx+" | "a" | "ax" | "a+" | "ax+"

Added in v1.0.0

SeekMode (type alias)

Signature

export type SeekMode = "start" | "current"

Added in v1.0.0

WatchEvent (type alias)

Signature

export type WatchEvent = WatchEvent.Create | WatchEvent.Update | WatchEvent.Remove

Added in v1.0.0

WatchEvent (namespace)

Added in v1.0.0

Create (interface)

Signature

export interface Create {
  readonly _tag: "Create"
  readonly path: string
}

Added in v1.0.0

Remove (interface)

Signature

export interface Remove {
  readonly _tag: "Remove"
  readonly path: string
}

Added in v1.0.0

Update (interface)

Signature

export interface Update {
  readonly _tag: "Update"
  readonly path: string
}

Added in v1.0.0

options

AccessFileOptions (interface)

Signature

export interface AccessFileOptions {
  readonly ok?: boolean
  readonly readable?: boolean
  readonly writable?: boolean
}

Added in v1.0.0

CopyOptions (interface)

Signature

export interface CopyOptions {
  readonly overwrite?: boolean
  readonly preserveTimestamps?: boolean
}

Added in v1.0.0

MakeDirectoryOptions (interface)

Signature

export interface MakeDirectoryOptions {
  readonly recursive?: boolean
  readonly mode?: number
}

Added in v1.0.0

MakeTempDirectoryOptions (interface)

Signature

export interface MakeTempDirectoryOptions {
  readonly directory?: string
  readonly prefix?: string
}

Added in v1.0.0

MakeTempFileOptions (interface)

Signature

export interface MakeTempFileOptions {
  readonly directory?: string
  readonly prefix?: string
}

Added in v1.0.0

OpenFileOptions (interface)

Signature

export interface OpenFileOptions {
  readonly flag?: OpenFlag
  readonly mode?: number
}

Added in v1.0.0

ReadDirectoryOptions (interface)

Signature

export interface ReadDirectoryOptions {
  readonly recursive?: boolean
}

Added in v1.0.0

RemoveOptions (interface)

Signature

export interface RemoveOptions {
  /**
   * When `true`, you can recursively remove nested directories.
   */
  readonly recursive?: boolean
  /**
   * When `true`, exceptions will be ignored if `path` does not exist.
   */
  readonly force?: boolean
}

Added in v1.0.0

SinkOptions (interface)

Signature

export interface SinkOptions extends OpenFileOptions {}

Added in v1.0.0

StreamOptions (interface)

Signature

export interface StreamOptions {
  readonly bufferSize?: number
  readonly bytesToRead?: SizeInput
  readonly chunkSize?: SizeInput
  readonly offset?: SizeInput
}

Added in v1.0.0

WriteFileOptions (interface)

Signature

export interface WriteFileOptions {
  readonly flag?: OpenFlag
  readonly mode?: number
}

Added in v1.0.0

WriteFileStringOptions (interface)

Signature

export interface WriteFileStringOptions {
  readonly flag?: OpenFlag
  readonly mode?: number
}

Added in v1.0.0

sizes

GiB

Signature

export declare const GiB: (n: number) => Size

Added in v1.0.0

KiB

Signature

export declare const KiB: (n: number) => Size

Added in v1.0.0

MiB

Signature

export declare const MiB: (n: number) => Size

Added in v1.0.0

PiB

Signature

export declare const PiB: (n: number) => Size

Added in v1.0.0

Size

Signature

export declare const Size: (bytes: SizeInput) => Size

Added in v1.0.0

Size (type alias)

Represents a size in bytes.

Signature

export type Size = Brand.Branded<bigint, "Size">

Added in v1.0.0

SizeInput (type alias)

Represents a size in bytes.

Signature

export type SizeInput = bigint | number | Size

Added in v1.0.0

TiB

Signature

export declare const TiB: (n: number) => Size

Added in v1.0.0

tag

FileSystem

Signature

export declare const FileSystem: Tag<FileSystem, FileSystem>

Added in v1.0.0

type id

FileTypeId

Signature

export declare const FileTypeId: typeof FileTypeId

Added in v1.0.0

FileTypeId (type alias)

Signature

export type FileTypeId = typeof FileTypeId

Added in v1.0.0

utils

File (namespace)

Added in v1.0.0

Info (interface)

Signature

export interface Info {
  readonly type: Type
  readonly mtime: Option<Date>
  readonly atime: Option<Date>
  readonly birthtime: Option<Date>
  readonly dev: number
  readonly ino: Option<number>
  readonly mode: number
  readonly nlink: Option<number>
  readonly uid: Option<number>
  readonly gid: Option<number>
  readonly rdev: Option<number>
  readonly size: Size
  readonly blksize: Option<Size>
  readonly blocks: Option<number>
}

Added in v1.0.0

Descriptor (type alias)

Signature

export type Descriptor = Brand.Branded<number, "FileDescriptor">

Added in v1.0.0

Type (type alias)

Signature

export type Type =
  | "File"
  | "Directory"
  | "SymbolicLink"
  | "BlockDevice"
  | "CharacterDevice"
  | "FIFO"
  | "Socket"
  | "Unknown"

Added in v1.0.0