Skip to content
packageserror-causereference

@vltpkg/error-cause

Type Aliases

Codes

type Codes = (typeof errorCodes)[number]

Defined in: index.ts:253

Valid properties for the ‘code’ field in an Error cause. Add new options to this list as needed.

DuckTypeManifest

type DuckTypeManifest = Record<string, any> & object

Defined in: index.ts:161

Type declaration

arch?
optional arch: string[] | string;
deprecated?
optional deprecated: string;
dist?
optional dist: object;
dist.fileCount?
optional dist.fileCount: number;
dist.integrity?
optional dist.integrity: string;
dist.shasum?
optional dist.shasum: string;
dist.signatures?
optional dist.signatures: object[];
dist.tarball?
optional dist.tarball: string;
dist.unpackedSize?
optional dist.unpackedSize: number;
engines?
optional engines: Record<string, string>;
name?
optional name: string;
os?
optional os: string[] | string;
version?
optional version: string;

ErrorCause

type ErrorCause = Error | ErrorCauseOptions

Defined in: index.ts:185

The input cause for the error functions. Can either be a plain error or an error cause options object.

ErrorCauseOptions

type ErrorCauseOptions = object

Defined in: index.ts:11

Codification of vlt’s Error.cause conventions

Add new properties to this list as needed.

Several of these types are just very basic duck-typing, because referencing internal types directly would create a workspace dependency cycle.

Type declaration

args?
optional args: string[];

the arguments passed to a process

cause?
optional cause: unknown;

The cause field within a cause object should always be an Error object that was previously thrown. Note that the cause on an Error itself might also be a previously thrown error, if no additional information could be usefully added beyond improving the message. It is typed as unknown because we use useUnknownInCatchVariables so this makes it easier to rethrow a caught error without recasting it.

code?
optional code: Codes;

This should only be a string code that we set. See Codes for the supported options. Lower-level system codes like ENOENT should remain on the errors that generated them.

command?
optional command: string;

a command being run in a child process

cwd?
optional cwd: string;

the current working directory of a process

found?
optional found: unknown;

actual value, which was not wanted

from?
optional from: string;

file path origin of a resolution that failed, for example in the case of file:// specifiers.

manifest?
optional manifest: DuckTypeManifest;

a package manifest, either from package.json or a registry

max?
optional max: unknown;

maximum value, which was exceeded

min?
optional min: unknown;

minimum value, which was not met

name?
optional name: string;

the name of something

offset?
optional offset: number;

byte offset in a Buffer or file

packument?
optional packument: object;

registry top-level package document

packument.dist-tags
packument.dist-tags: Record<string, string>;
packument.name
packument.name: string;
packument.time?
optional packument.time: Record<string, string>;
packument.versions
packument.versions: Record<string, DuckTypeManifest>;
path?
optional path: string;

target of a file system operation

projectRoot?
optional projectRoot: string;

the root of a project

range?
optional range:
  | string
  | {
[k: string | number | symbol]: any;   includePrerelease: boolean;
  isAny: boolean;
  raw: string;
};

string or @vltpkg/semver.Range object

repository?
optional repository: string;

git repository remote or path

response?
optional response:
  | IncomingMessage
  | Response
  | {
[k: string | number | symbol]: any;   headers:   | Buffer[]
     | Record<string, string[] | string>
     | IncomingHttpHeaders;
  statusCode: number;
  text: () => string;
};

HTTP message, fetch.Response, or @vltpkg/registry-client.CacheEntry

signal?
optional signal: NodeJS.Signals | null;

null or a signal that a process received

spec?
optional spec:
  | string
  | {
[k: string | number | symbol]: any;   spec: string;
  type: "file" | "git" | "registry" | "remote" | "workspace";
};

Spec object/string relevant to an operation that failed

status?
optional status: number | null;

exit code of a process, or HTTP response status code

stderr?
optional stderr: Buffer | string | null;

standard error from a process

stdout?
optional stdout: Buffer | string | null;

standard output from a process

target?
optional target: string;

path on disk that is being written, linked, or extracted to

todo?
optional todo: string;

message indicating what bit of work this might be a part of, what feature needs to be implemented, etc. Eg, { todo: 'nested workspace support' }.

url?
optional url: URL | string;

string or URL object

validOptions?
optional validOptions: unknown[];

Array of valid options when something is not a valid option. (For use in did you mean X? output.)

version?
optional version:
  | string
  | {
[k: string | number | symbol]: any;   major: number;
  minor: number;
  patch: number;
  raw: string;
};

string or @vltpkg/semver.Version object

wanted?
optional wanted: unknown;

A desired value that was not found, or a regular expression or other pattern describing it.

ErrorCauseResult

type ErrorCauseResult = Omit<ErrorCauseOptions, 'cause'> & object

Defined in: index.ts:191

The same as ErrorCauseOptions except where cause has been converted to an Error.

Type declaration

cause?
optional cause: Error;

ErrorCtor()<T>

type ErrorCtor<T> = (message, options?) => T

Defined in: index.ts:290

Type Parameters

• T extends Error

Parameters

message

string

options?
cause

Error | ErrorCauseResult

Returns

T

ErrorResult<T>

type ErrorResult<T> =
  | T
  | ErrorWithCauseError<TypeError>
  | ErrorWithCauseObject<TypeError>

Defined in: index.ts:295

Type Parameters

• T extends Error = Error

ErrorWithCause<T, U>

type ErrorWithCause<T, U> = T & object

Defined in: index.ts:198

An error with a cause property. Cause defaults to unknown.

Type declaration

cause
cause: U

Type Parameters

• T extends Error = Error

• U = unknown

ErrorWithCauseError<T>

type ErrorWithCauseError<T> = ErrorWithCause<T, Error>

Defined in: index.ts:206

An error with a cause property that is an Error.

Type Parameters

• T extends Error = Error

ErrorWithCauseObject<T>

type ErrorWithCauseObject<T> = ErrorWithCause<T, ErrorCauseResult>

Defined in: index.ts:212

An error with a cause property that is an ErrorCauseResult.

Type Parameters

• T extends Error = Error

ErrorWithCode<T>

type ErrorWithCode<T> = ErrorWithCause<
  T,
  Omit<ErrorCauseResult, 'code'> & object
>

Defined in: index.ts:259

An error with a cause property that is an ErrorCauseResult and has a code property that is a Codes.

Type Parameters

• T extends Error = Error

From

type From = Function

Defined in: index.ts:282

Variables

errorCodes

const errorCodes: readonly [
  'EEXIST',
  'EINTEGRITY',
  'EINVAL',
  'ELIFECYCLE',
  'EMAXREDIRECT',
  'ENEEDAUTH',
  'ENOENT',
  'ENOGIT',
  'ERESOLVE',
  'EUNKNOWN',
  'EUSAGE',
]

Defined in: index.ts:233

Functions

asError()

function asError(er, fallbackMessage): Error

Defined in: index.ts:219

Helper util to convert unknown to a plain error. Not specifically related to error causes, but useful for error handling in general.

Parameters

er

unknown

fallbackMessage

string = 'Unknown error'

Returns

Error

error()

Call Signature

function error(message, cause?, from?): Error

Defined in: index.ts:345

Parameters
message

string

cause?

undefined

from?

Function

Returns

Error

Call Signature

function error(message, cause, from?): ErrorWithCauseError

Defined in: index.ts:350

Parameters
message

string

cause

Error

from?

Function

Returns

ErrorWithCauseError

Call Signature

function error(message, cause, from?): ErrorWithCauseObject

Defined in: index.ts:355

Parameters
message

string

cause

ErrorCauseOptions

from?

Function

Returns

ErrorWithCauseObject

isErrorWithCause()

function isErrorWithCause(er): er is ErrorWithCause<Error, unknown>

Defined in: index.ts:230

Helper util to check if an error has any type of cause property. Note that this does not mean it is a cause from this library, just that it has a cause property.

Parameters

er

unknown

Returns

er is ErrorWithCause<Error, unknown>

isErrorWithCode()

function isErrorWithCode(er): er is ErrorWithCode<Error>

Defined in: index.ts:272

Type guard to check if an error has one of our error code properties. Note that the type check only checks for the code property and value, but since every property on ErrorCauseOptions is optional, this should be sufficient to know the shape of the cause and use it in printing.

Parameters

er

unknown

Returns

er is ErrorWithCode<Error>

syntaxError()

Call Signature

function syntaxError(message, cause?, from?): SyntaxError

Defined in: index.ts:391

Parameters
message

string

cause?

undefined

from?

Function

Returns

SyntaxError

Call Signature

function syntaxError(
  message,
  cause,
  from?,
): ErrorWithCauseError<SyntaxError>

Defined in: index.ts:396

Parameters
message

string

cause

Error

from?

Function

Returns

ErrorWithCauseError<SyntaxError>

Call Signature

function syntaxError(
  message,
  cause,
  from?,
): ErrorWithCauseObject<SyntaxError>

Defined in: index.ts:401

Parameters
message

string

cause

ErrorCauseOptions

from?

Function

Returns

ErrorWithCauseObject<SyntaxError>

typeError()

Call Signature

function typeError(message, cause?, from?): TypeError

Defined in: index.ts:368

Parameters
message

string

cause?

undefined

from?

Function

Returns

TypeError

Call Signature

function typeError(
  message,
  cause,
  from?,
): ErrorWithCauseError<TypeError>

Defined in: index.ts:373

Parameters
message

string

cause

Error

from?

Function

Returns

ErrorWithCauseError<TypeError>

Call Signature

function typeError(
  message,
  cause,
  from?,
): ErrorWithCauseObject<TypeError>

Defined in: index.ts:378

Parameters
message

string

cause

ErrorCauseOptions

from?

Function

Returns

ErrorWithCauseObject<TypeError>