VfsError.ts overview

Filesystem and configuration errors for @effect-vfs/core. Every failure a volume, caller, handle, snapshot codec, delta codec, or live store reports is a VfsError whose code says what went wrong, whose operation names the verb or constructor, and which may name the offending option field, the path it was addressing, and the underlying cause it classifies. Live-volume registry capacity additionally reports Effect's native Cause.ExceededCapacityError.

Since v0.6.0

constructors

make

Builds a VfsError whose type carries its code, so a service can fail with a narrowed alias such as StoreFailure or ArgumentFailure without a cast. An absent field, path or cause stays absent.

Example

import { VfsError } from "@effect-vfs/core"
 
const failure: VfsError.StoreFailure = VfsError.make({ code: "Storage", operation: "MyStore.load" })
 
console.log(failure.message)
// MyStore.load failed with Storage

Signature

declare const make: <C extends VfsCode>(props: Props<C>) => VfsError & { readonly code: C }

Source

Since v0.6.0

errors

VfsError (class)

A failure reported by any part of the virtual filesystem.

Example

import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
import { Effect } from "effect"
import * as BunCrypto from "@effect/platform-bun/BunCrypto"
 
const program = Effect.gen(function* () {
  const fs = yield* (yield* Vfs.make()).caller()
 
  return yield* fs
    .readFile("/missing")
    .pipe(Effect.catchTag("VfsError", (error) => Effect.succeed(`${error.operation}: ${error.code}`)))
})
 
Effect.runPromise(program.pipe(Effect.provide(BunCrypto.layer))).then(console.log)
// readFile: NotFound

Signature

export declare class VfsError extends Schema.TaggedError<VfsError>()("VfsError", {
  /** What went wrong. */
  code: VfsCode,
  /** The verb or constructor that failed. */
  operation: Schema.String,
  /** The option or input area the failure concerns, when one is known. */
  field: Schema.optionalKey(Schema.String),
  /** The path the operation was addressing, when it named one. */
  path: Schema.optionalKey(ErrorPath),
  /** The underlying failure this error classifies, when one exists. */
  cause: Schema.optionalKey(Schema.Defect()),
}) {}

Source

Since v0.6.0

models

ArgumentFailure (type alias)

A VfsError reporting a rejected option, always InvalidArgument with the offending field.

Signature

type ArgumentFailure = VfsError & { readonly code: "InvalidArgument" }

Source

Since v0.6.0

DeltaCode (type alias)

The code a delta reports when its base does not match.

Signature

export type DeltaCode = "BaseMismatch"

Source

Since v0.6.0

FsCode (type alias)

A code an operation on a volume, caller, or handle reports.

Signature

export type FsCode =
  | "NotFound"
  | "AlreadyExists"
  | "NotEmpty"
  | "NotDirectory"
  | "AccessDenied"
  | "NotPermitted"
  | "InvalidHandle"
  | "ForeignHandle"
  | "InvalidReference"
  | "ForeignReference"
  | "StaleReference"
  | "ClosedCaller"
  | "InvalidArgument"
  | "InvalidPathEncoding"
  | "PathTooLong"
  | "NoSpace"
  | "IsDirectory"
  | "FileTooLarge"
  | "NoData"
  | "SymlinkLoop"
  | "UnrepresentableName"
  | "StorageRejected"
  | "OutcomeUnknown"
  | "VolumeUnavailable"
  | "VolumeBusy"

Source

Since v0.6.0

FsFailure (type alias)

A VfsError whose code is one an operation on a volume, caller, or handle reports.

Signature

type FsFailure = VfsError & { readonly code: FsCode }

Source

Since v0.6.0

ImageCode (type alias)

A code a snapshot, fixture, live image, or delta codec reports.

Signature

export type ImageCode =
  "InvalidEncoding" | "UnsupportedVersion" | "InvalidStructure" | "LimitExceeded"

Source

Since v0.6.0

ImageFailure (type alias)

A VfsError whose code is one a snapshot, fixture, live image, or delta codec reports.

Signature

type ImageFailure = VfsError & { readonly code: ImageCode }

Source

Since v0.6.0

Props (interface)

What a VfsError is built from: a code, the operation that failed, and whichever of field, path and cause apply.

Signature

export interface Props<C extends VfsCode> {
  readonly code: C
  readonly operation: string
  readonly field?: string | undefined
  readonly path?: BytePath | undefined
  readonly cause?: unknown
}

Source

Since v0.6.0

StoreCode (type alias)

A code a live image store reports while opening or recovering a volume.

Signature

export type StoreCode = "Storage" | "Ownership" | "IncompatibleStore" | "CorruptStore"

Source

Since v0.6.0

StoreFailure (type alias)

A VfsError whose code is one a live image store reports.

Signature

type StoreFailure = VfsError & { readonly code: StoreCode }

Source

Since v0.6.0

VfsCode (type alias)

Every code a VfsError can carry.

Signature

export type VfsCode =
  | "NotFound"
  | "AlreadyExists"
  | "NotEmpty"
  | "NotDirectory"
  | "AccessDenied"
  | "NotPermitted"
  | "InvalidHandle"
  | "ForeignHandle"
  | "InvalidReference"
  | "ForeignReference"
  | "StaleReference"
  | "ClosedCaller"
  | "InvalidArgument"
  | "InvalidPathEncoding"
  | "PathTooLong"
  | "NoSpace"
  | "IsDirectory"
  | "FileTooLarge"
  | "NoData"
  | "SymlinkLoop"
  | "UnrepresentableName"
  | "StorageRejected"
  | "OutcomeUnknown"
  | "VolumeUnavailable"
  | "VolumeBusy"
  | "InvalidEncoding"
  | "UnsupportedVersion"
  | "InvalidStructure"
  | "LimitExceeded"
  | "BaseMismatch"
  | "Storage"
  | "Ownership"
  | "IncompatibleStore"
  | "CorruptStore"

Source

Since v0.6.0

schemas

DeltaCode

Schema for the code a delta reports when its base does not match.

Signature

declare const DeltaCode: Schema.Literals<readonly ["BaseMismatch"]>

Source

Since v0.6.0

ErrorPath

Schema for the path an error names, carried as an opaque BytePath and encoded as base64 bytes so the error survives a wire.

Signature

declare const ErrorPath: Schema.decodeTo<Schema.declare<BytePath, BytePath>, Schema.Uint8ArrayFromBase64, never, never>

Source

Since v0.6.0

FsCode

Schema for the codes an operation on a volume, caller, or handle reports.

Signature

declare const FsCode: Schema.Literals<
  readonly [
    "NotFound",
    "AlreadyExists",
    "NotEmpty",
    "NotDirectory",
    "AccessDenied",
    "NotPermitted",
    "InvalidHandle",
    "ForeignHandle",
    "InvalidReference",
    "ForeignReference",
    "StaleReference",
    "ClosedCaller",
    "InvalidArgument",
    "InvalidPathEncoding",
    "PathTooLong",
    "NoSpace",
    "IsDirectory",
    "FileTooLarge",
    "NoData",
    "SymlinkLoop",
    "UnrepresentableName",
    "StorageRejected",
    "OutcomeUnknown",
    "VolumeUnavailable",
    "VolumeBusy"
  ]
>

Source

Since v0.6.0

ImageCode

Schema for the codes a snapshot, fixture, live image, or delta codec reports.

Signature

declare const ImageCode: Schema.Literals<
  readonly ["InvalidEncoding", "UnsupportedVersion", "InvalidStructure", "LimitExceeded"]
>

Source

Since v0.6.0

StoreCode

Schema for the codes a live image store reports while opening or recovering a volume.

Signature

declare const StoreCode: Schema.Literals<readonly ["Storage", "Ownership", "IncompatibleStore", "CorruptStore"]>

Source

Since v0.6.0

VfsCode

Schema for every code a VfsError can carry.

Signature

declare const VfsCode: Schema.Literals<
  readonly [
    "NotFound",
    "AlreadyExists",
    "NotEmpty",
    "NotDirectory",
    "AccessDenied",
    "NotPermitted",
    "InvalidHandle",
    "ForeignHandle",
    "InvalidReference",
    "ForeignReference",
    "StaleReference",
    "ClosedCaller",
    "InvalidArgument",
    "InvalidPathEncoding",
    "PathTooLong",
    "NoSpace",
    "IsDirectory",
    "FileTooLarge",
    "NoData",
    "SymlinkLoop",
    "UnrepresentableName",
    "StorageRejected",
    "OutcomeUnknown",
    "VolumeUnavailable",
    "VolumeBusy",
    "InvalidEncoding",
    "UnsupportedVersion",
    "InvalidStructure",
    "LimitExceeded",
    "BaseMismatch",
    "Storage",
    "Ownership",
    "IncompatibleStore",
    "CorruptStore"
  ]
>

Source

Since v0.6.0