SystemErrorError data for a platform or system operation failure.
When to use
Use when you need normalized reason data for a platform or system operation failure, including the operation details.
Details
The error records a normalized _tag, the module and method that failed,
and optional details such as the syscall, path or descriptor, description,
and original cause. It is usually wrapped in PlatformError.
export class class SystemErrorclass SystemError {
message: string;
name: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: SystemErrorTag;
module: string;
method: string;
description: string | undefined;
syscall: string | undefined;
pathOrDescriptor: string | number | undefined;
}
Error data for a platform or system operation failure.
When to use
Use when you need normalized reason data for a platform or system operation
failure, including the operation details.
Details
The error records a normalized _tag, the module and method that failed,
and optional details such as the syscall, path or descriptor, description,
and original cause. It is usually wrapped in PlatformError.
SystemError extends import DataData.const Error: new <
A extends Record<string, any> = {}
>(
args: Types.VoidIfEmpty<{
readonly [P in keyof A]: A[P]
}>
) => Cause.YieldableError & Readonly<A>
Provides a base class for yieldable errors.
When to use
Use when you need yieldable errors that do not need tag-based
discrimination.
Details
Extends Cause.YieldableError, so instances can be yielded inside
Effect.gen to fail the enclosing effect. Fields are passed as a single
object; when there are no fields the argument is optional. If a message
field is provided, it becomes the error's .message.
Example (Defining a yieldable error)
import { Data, Effect } from "effect"
class NetworkError extends Data.Error<{
readonly code: number
readonly message: string
}> {}
const program = Effect.gen(function*() {
return yield* new NetworkError({ code: 500, message: "timeout" })
})
// The effect fails with a NetworkError
Effect.runSync(Effect.exit(program))
Error<{
_tag: SystemErrorTag_tag: type SystemErrorTag =
| "AlreadyExists"
| "BadResource"
| "Busy"
| "InvalidData"
| "NotFound"
| "PermissionDenied"
| "TimedOut"
| "UnexpectedEof"
| "Unknown"
| "WouldBlock"
| "WriteZero"
Normalized category for failures reported by platform or system operations.
When to use
Use to type or match the normalized _tag on SystemError values reported
by platform operations.
Details
The tags group lower-level platform errors into a stable set such as
NotFound, PermissionDenied, TimedOut, and Unknown.
SystemErrorTag
module: stringmodule: string
method: stringmethod: string
description?: string | undefineddescription?: string | undefined
syscall?: string | undefinedsyscall?: string | undefined
pathOrDescriptor?: string | number | undefinedpathOrDescriptor?: string | number | undefined
cause?: unknowncause?: unknown
}> {
/**
* Formats the normalized system error tag with operation and path details.
*
* **When to use**
*
* Use to read the formatted error message for a normalized system failure.
*
* @since 4.0.0
*/
override get SystemError.message: stringFormats the normalized system error tag with operation and path details.
When to use
Use to read the formatted error message for a normalized system failure.
message(): string {
return `${this._tag: SystemErrorTag_tag}: ${this.module: stringmodule}.${this.method: stringmethod}${
this.pathOrDescriptor?: string | number | undefinedpathOrDescriptor !== var undefinedundefined ? ` (${this.pathOrDescriptor?: string | numberpathOrDescriptor})` : ""
}${this.description?: string | undefineddescription ? `: ${this.description?: stringdescription}` : ""}`
}
}