@vltpkg/error-cause 0.0.0-0.1730239248325 → 0.0.0-2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -18
- package/dist/esm/index.d.ts +60 -9
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js +30 -5
- package/dist/esm/index.js.map +1 -1
- package/package.json +19 -12
package/README.md
CHANGED
|
@@ -1,9 +1,31 @@
|
|
|
1
|
-
|
|
1
|
+
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
`Error.cause` conventions.
|
|
3
|
+
# @vltpkg/error-cause
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
Utility functions for `Error` creation to help enforce vlt's `Error.cause` conventions.
|
|
6
|
+
|
|
7
|
+
**[Usage](#usage)**
|
|
8
|
+
·
|
|
9
|
+
**[Error Reporting](#challenges-of-error-reporting)**
|
|
10
|
+
·
|
|
11
|
+
**[Conventions](#conventions)**
|
|
12
|
+
·
|
|
13
|
+
**[Error Types](#error-types)**
|
|
14
|
+
|
|
15
|
+
## Why
|
|
16
|
+
|
|
17
|
+
Most node programs have a mishmash of error codes and various
|
|
18
|
+
`Error` subtypes, all in different shapes, making error handling
|
|
19
|
+
and reporting more difficult at the top level. This negatively
|
|
20
|
+
impacts debugging and user experience.
|
|
21
|
+
|
|
22
|
+
The JavaScript `Error` constructor has a [`cause`
|
|
23
|
+
option](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)
|
|
24
|
+
which is supported since Node 16.9. We should use it!
|
|
25
|
+
|
|
26
|
+
This module makes that easy.
|
|
27
|
+
|
|
28
|
+
## Usage
|
|
7
29
|
|
|
8
30
|
```js
|
|
9
31
|
import { error, typeError } from '@vltpkg/error-cause'
|
|
@@ -50,19 +72,6 @@ The functions will create an error object with a `cause` property
|
|
|
50
72
|
if set, and the type checks will ensure that the `cause` object
|
|
51
73
|
matches vlt's conventions.
|
|
52
74
|
|
|
53
|
-
## Why
|
|
54
|
-
|
|
55
|
-
Most node programs have a mishmash of error codes and various
|
|
56
|
-
`Error` subtypes, all in different shapes, making error handling
|
|
57
|
-
and reporting more difficult at the top level. This negatively
|
|
58
|
-
impacts debugging and user experience.
|
|
59
|
-
|
|
60
|
-
The JavaScript `Error` constructor has a [`cause`
|
|
61
|
-
option](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)
|
|
62
|
-
which is supported since Node 16.9. We should use it!
|
|
63
|
-
|
|
64
|
-
This module makes that easy.
|
|
65
|
-
|
|
66
75
|
## Challenges of Error Reporting
|
|
67
76
|
|
|
68
77
|
- Provide enough information to be useful. On full inspection, we
|
|
@@ -274,7 +283,7 @@ Just use the `Error` classes defined in the language. Additional
|
|
|
274
283
|
information about error causes should be on the `cause` property,
|
|
275
284
|
not implicit in the constructor type.
|
|
276
285
|
|
|
277
|
-
|
|
286
|
+
I.e. do not do this:
|
|
278
287
|
|
|
279
288
|
```
|
|
280
289
|
class VersionError extends Error {
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { IncomingMessage } from 'http';
|
|
1
|
+
import type { IncomingHttpHeaders, IncomingMessage } from 'http';
|
|
2
2
|
/**
|
|
3
3
|
* Codification of vlt's Error.cause conventions
|
|
4
4
|
*
|
|
@@ -13,9 +13,11 @@ export type ErrorCauseObject = {
|
|
|
13
13
|
* always be an `Error` object that was previously thrown. Note
|
|
14
14
|
* that the `cause` on an Error itself might _also_ be a
|
|
15
15
|
* previously thrown error, if no additional information could be
|
|
16
|
-
* usefully added beyond improving the message.
|
|
16
|
+
* usefully added beyond improving the message. It is typed as `unknown`
|
|
17
|
+
* because we use `useUnknownInCatchVariables` so this makes it easier
|
|
18
|
+
* to rethrow a caught error without recasting it.
|
|
17
19
|
*/
|
|
18
|
-
cause?: ErrorCause;
|
|
20
|
+
cause?: ErrorCause | unknown;
|
|
19
21
|
/** the name of something */
|
|
20
22
|
name?: string;
|
|
21
23
|
/** byte offset in a Buffer or file */
|
|
@@ -77,8 +79,8 @@ export type ErrorCauseObject = {
|
|
|
77
79
|
/** HTTP message, fetch.Response, or `@vltpkg/registry-client.CacheEntry` */
|
|
78
80
|
response?: IncomingMessage | Response | {
|
|
79
81
|
statusCode: number;
|
|
80
|
-
headers: Buffer[] | Record<string, string[] | string
|
|
81
|
-
text
|
|
82
|
+
headers: Buffer[] | Record<string, string[] | string> | IncomingHttpHeaders;
|
|
83
|
+
text?: () => string;
|
|
82
84
|
[k: number | string | symbol]: any;
|
|
83
85
|
};
|
|
84
86
|
/** string or URL object */
|
|
@@ -134,12 +136,61 @@ export type DuckTypeManifest = Record<string, any> & {
|
|
|
134
136
|
};
|
|
135
137
|
};
|
|
136
138
|
export type ErrorCause = Error | ErrorCauseObject;
|
|
139
|
+
/**
|
|
140
|
+
* An error with a cause that is a direct error cause object and not another
|
|
141
|
+
* nested error.
|
|
142
|
+
*/
|
|
143
|
+
export type ErrorWithCauseObject = Error & {
|
|
144
|
+
cause: ErrorCauseObject;
|
|
145
|
+
};
|
|
146
|
+
/**
|
|
147
|
+
* A TypeError with a cause that is a direct error cause object and not
|
|
148
|
+
* another nested error
|
|
149
|
+
*/
|
|
150
|
+
/**
|
|
151
|
+
* If it is any sort of plain-ish object, assume its an error cause
|
|
152
|
+
* because all properties of the cause are optional.
|
|
153
|
+
*/
|
|
154
|
+
export declare const isErrorCauseObject: (v: unknown) => v is ErrorCauseObject;
|
|
155
|
+
/**
|
|
156
|
+
* Type guard for {@link ErrorWithCauseObject} type
|
|
157
|
+
*/
|
|
158
|
+
export declare const isErrorRoot: (er: unknown) => er is ErrorWithCauseObject;
|
|
159
|
+
export declare const asErrorCause: (er: unknown) => ErrorCause;
|
|
137
160
|
/**
|
|
138
161
|
* Valid properties for the 'code' field in an Error cause.
|
|
139
162
|
* Add new options to this list as needed.
|
|
140
163
|
*/
|
|
141
|
-
export type Codes = 'EEXIST' | 'EINTEGRITY' | 'EINVAL' | 'ELIFECYCLE' | 'EMAXREDIRECT' | 'ENEEDAUTH' | 'ENOENT' | 'ENOGIT' | 'ERESOLVE' | 'EUNKNOWN';
|
|
142
|
-
export
|
|
143
|
-
export declare
|
|
144
|
-
export declare
|
|
164
|
+
export type Codes = 'EEXIST' | 'EINTEGRITY' | 'EINVAL' | 'ELIFECYCLE' | 'EMAXREDIRECT' | 'ENEEDAUTH' | 'ENOENT' | 'ENOGIT' | 'ERESOLVE' | 'EUNKNOWN' | 'EUSAGE';
|
|
165
|
+
export type From = ((...a: any[]) => any) | (new (...a: any[]) => any);
|
|
166
|
+
export declare function error(message: string, cause?: undefined, from?: From): Error;
|
|
167
|
+
export declare function error(message: string, cause: ErrorCauseObject, from?: From): Error & {
|
|
168
|
+
cause: ErrorCauseObject;
|
|
169
|
+
};
|
|
170
|
+
export declare function error(message: string, cause: Error, from?: From): Error & {
|
|
171
|
+
cause: Error;
|
|
172
|
+
};
|
|
173
|
+
export declare function error(message: string, cause: ErrorCause, from?: From): Error & {
|
|
174
|
+
cause: ErrorCause;
|
|
175
|
+
};
|
|
176
|
+
export declare function typeError(message: string, cause?: undefined, from?: From): TypeError;
|
|
177
|
+
export declare function typeError(message: string, cause: ErrorCauseObject, from?: From): TypeError & {
|
|
178
|
+
cause: ErrorCauseObject;
|
|
179
|
+
};
|
|
180
|
+
export declare function typeError(message: string, cause: Error, from?: From): TypeError & {
|
|
181
|
+
cause: Error;
|
|
182
|
+
};
|
|
183
|
+
export declare function typeError(message: string, cause: ErrorCause, from?: From): TypeError & {
|
|
184
|
+
cause: ErrorCause;
|
|
185
|
+
};
|
|
186
|
+
export declare function syntaxError(message: string, cause?: undefined, from?: From): SyntaxError;
|
|
187
|
+
export declare function syntaxError(message: string, cause: ErrorCauseObject, from?: From): SyntaxError & {
|
|
188
|
+
cause: ErrorCauseObject;
|
|
189
|
+
};
|
|
190
|
+
export declare function syntaxError(message: string, cause: Error, from?: From): SyntaxError & {
|
|
191
|
+
cause: Error;
|
|
192
|
+
};
|
|
193
|
+
export declare function syntaxError(message: string, cause: ErrorCause, from?: From): SyntaxError & {
|
|
194
|
+
cause: ErrorCause;
|
|
195
|
+
};
|
|
145
196
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/esm/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/esm/index.js
CHANGED
|
@@ -1,10 +1,35 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* A TypeError with a cause that is a direct error cause object and not
|
|
3
|
+
* another nested error
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* If it is any sort of plain-ish object, assume its an error cause
|
|
7
|
+
* because all properties of the cause are optional.
|
|
8
|
+
*/
|
|
9
|
+
export const isErrorCauseObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
|
|
10
|
+
/**
|
|
11
|
+
* Type guard for {@link ErrorWithCauseObject} type
|
|
12
|
+
*/
|
|
13
|
+
export const isErrorRoot = (er) => er instanceof Error && isErrorCauseObject(er.cause);
|
|
14
|
+
export const asErrorCause = (er) => er instanceof Error ? er
|
|
15
|
+
: isErrorCauseObject(er) ? er
|
|
16
|
+
// otherwise, make an error of the stringified message
|
|
17
|
+
: new Error(
|
|
18
|
+
// eslint-disable-next-line @typescript-eslint/no-base-to-string
|
|
19
|
+
er == null ? 'Unknown error' : String(er) || 'Unknown error');
|
|
20
|
+
function create(cls, defaultFrom, message, cause, from = defaultFrom) {
|
|
2
21
|
const er = new cls(message, cause ? { cause } : undefined);
|
|
3
22
|
// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
|
|
4
23
|
Error.captureStackTrace?.(er, from);
|
|
5
24
|
return er;
|
|
6
|
-
}
|
|
7
|
-
export
|
|
8
|
-
|
|
9
|
-
|
|
25
|
+
}
|
|
26
|
+
export function error(message, cause, from) {
|
|
27
|
+
return create(Error, error, message, cause, from);
|
|
28
|
+
}
|
|
29
|
+
export function typeError(message, cause, from) {
|
|
30
|
+
return create(TypeError, typeError, message, cause, from);
|
|
31
|
+
}
|
|
32
|
+
export function syntaxError(message, cause, from) {
|
|
33
|
+
return create(SyntaxError, syntaxError, message, cause, from);
|
|
34
|
+
}
|
|
10
35
|
//# sourceMappingURL=index.js.map
|
package/dist/esm/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAiMA,MAAM,MAAM,GAAG,CACb,GAAiB,EACjB,WAAgE,EAChE,OAAe,EACf,KAAkB,EAClB,OAEiC,WAAW,EAC5C,EAAE;IACF,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC1D,uEAAuE;IACvE,KAAK,CAAC,iBAAiB,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IACnC,OAAO,EAAE,CAAA;AACX,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,OAAe,EACf,KAAkB,EAClB,IAA0D,EAC1D,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;AAE/C,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,OAAe,EACf,KAAkB,EAClB,IAA0D,EAC1D,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;AAEvD,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,OAAe,EACf,KAAkB,EAClB,IAA0D,EAC1D,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA","sourcesContent":["import type { IncomingMessage } from 'http'\n\n/**\n * Codification of vlt's Error.cause conventions\n *\n * Add new properties to this list as needed.\n *\n * Several of these types are just very basic duck-typing, because referencing\n * internal types directly would create a workspace dependency cycle.\n */\nexport type ErrorCauseObject = {\n /**\n * The `cause` field within a `cause` object should\n * always be an `Error` object that was previously thrown. Note\n * that the `cause` on an Error itself might _also_ be a\n * previously thrown error, if no additional information could be\n * usefully added beyond improving the message.\n */\n cause?: ErrorCause\n\n /** the name of something */\n name?: string\n\n /** byte offset in a Buffer or file */\n offset?: number\n\n /**\n * This should only be a string code that we set. See {@link Codes} for\n * the supported options. Lower-level system codes like `ENOENT` should\n * remain on the errors that generated them.\n */\n code?: Codes\n\n /** target of a file system operation */\n path?: string\n\n /**\n * file path origin of a resolution that failed, for example in the case\n * of `file://` specifiers.\n */\n from?: string\n\n /** path on disk that is being written, linked, or extracted to */\n target?: string\n\n /** Spec object/string relevant to an operation that failed */\n spec?:\n | string\n | {\n type: 'file' | 'git' | 'registry' | 'remote' | 'workspace'\n spec: string\n [k: number | string | symbol]: any\n }\n\n /** exit code of a process, or HTTP response status code */\n status?: number | null\n\n /** null or a signal that a process received */\n signal?: NodeJS.Signals | null\n\n /** the root of a project */\n projectRoot?: string\n\n /** the current working directory of a process */\n cwd?: string\n\n /** a command being run in a child process */\n command?: string\n\n /** the arguments passed to a process */\n args?: string[]\n\n /** standard output from a process */\n stdout?: Buffer | string | null\n\n /** standard error from a process */\n stderr?: Buffer | string | null\n\n /**\n * Array of valid options when something is not a valid option.\n * (For use in `did you mean X?` output.)\n */\n validOptions?: any[]\n\n /**\n * message indicating what bit of work this might be a part of, what feature\n * needs to be implemented, etc. Eg, `{ todo: 'nested workspace support' }`.\n */\n todo?: string\n\n /**\n * A desired value that was not found, or a regular expression or other\n * pattern describing it.\n */\n wanted?: any\n\n /** actual value, which was not wanted */\n found?: any\n\n /** HTTP message, fetch.Response, or `@vltpkg/registry-client.CacheEntry` */\n response?:\n | IncomingMessage\n | Response\n | {\n statusCode: number\n headers: Buffer[] | Record<string, string[] | string>\n text: () => string\n [k: number | string | symbol]: any\n }\n\n /** string or URL object */\n url?: URL | string\n\n /** git repository remote or path */\n repository?: string\n\n /** string or `@vltpkg/semver.Version` object */\n version?:\n | string\n | {\n raw: string\n major: number\n minor: number\n patch: number\n [k: number | string | symbol]: any\n }\n\n /** string or `@vltpkg/semver.Range` object */\n range?:\n | string\n | {\n raw: string\n isAny: boolean\n includePrerelease: boolean\n [k: number | string | symbol]: any\n }\n\n /** a package manifest, either from `package.json` or a registry */\n manifest?: DuckTypeManifest\n\n /** registry top-level package document */\n packument?: {\n name: string\n 'dist-tags': Record<string, string>\n versions: Record<string, DuckTypeManifest>\n time?: Record<string, string>\n }\n\n /** maximum value, which was exceeded */\n max?: any\n\n /** minimum value, which was not met */\n min?: any\n}\n\nexport type DuckTypeManifest = Record<string, any> & {\n name?: string\n version?: string\n deprecated?: string\n engines?: Record<string, string>\n os?: string[] | string\n arch?: string[] | string\n dist?: {\n integrity?: string\n shasum?: string\n tarball?: string\n fileCount?: number\n unpackedSize?: number\n signatures?: {\n keyid: string\n sig: string\n }[]\n }\n}\n\nexport type ErrorCause = Error | ErrorCauseObject\n\n/**\n * Valid properties for the 'code' field in an Error cause.\n * Add new options to this list as needed.\n */\nexport type Codes =\n | 'EEXIST'\n | 'EINTEGRITY'\n | 'EINVAL'\n | 'ELIFECYCLE'\n | 'EMAXREDIRECT'\n | 'ENEEDAUTH'\n | 'ENOENT'\n | 'ENOGIT'\n | 'ERESOLVE'\n | 'EUNKNOWN'\n\nconst create = (\n cls: typeof Error,\n defaultFrom: ((...a: any[]) => any) | (new (...a: any[]) => any),\n message: string,\n cause?: ErrorCause,\n from:\n | ((...a: any[]) => any)\n | (new (...a: any[]) => any) = defaultFrom,\n) => {\n const er = new cls(message, cause ? { cause } : undefined)\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n Error.captureStackTrace?.(er, from)\n return er\n}\n\nexport const error = (\n message: string,\n cause?: ErrorCause,\n from?: ((...a: any[]) => any) | (new (...a: any[]) => any),\n) => create(Error, error, message, cause, from)\n\nexport const typeError = (\n message: string,\n cause?: ErrorCause,\n from?: ((...a: any[]) => any) | (new (...a: any[]) => any),\n) => create(TypeError, typeError, message, cause, from)\n\nexport const syntaxError = (\n message: string,\n cause?: ErrorCause,\n from?: ((...a: any[]) => any) | (new (...a: any[]) => any),\n) => create(SyntaxError, syntaxError, message, cause, from)\n"]}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA4LA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,CAAU,EACa,EAAE,CACzB,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAEnD;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,EAAW,EACiB,EAAE,CAC9B,EAAE,YAAY,KAAK,IAAI,kBAAkB,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;AAErD,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAW,EAAc,EAAE,CACtD,EAAE,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE;IACxB,CAAC,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;QAC3B,sDAAsD;QACxD,CAAC,CAAC,IAAI,KAAK;QACP,gEAAgE;QAChE,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,eAAe,CAC7D,CAAA;AAoDL,SAAS,MAAM,CACb,GAAiB,EACjB,WAAgE,EAChE,OAAe,EACf,KAAkB,EAClB,OAAa,WAAW;IAExB,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC1D,uEAAuE;IACvE,KAAK,CAAC,iBAAiB,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IACnC,OAAO,EAAE,CAAA;AACX,CAAC;AAwBD,MAAM,UAAU,KAAK,CACnB,OAAe,EACf,KAAkB,EAClB,IAAW;IAEX,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;AACnD,CAAC;AAsBD,MAAM,UAAU,SAAS,CACvB,OAAe,EACf,KAAkB,EAClB,IAAW;IAEX,OAAO,MAAM,CAAY,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;AACtE,CAAC;AAsBD,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,KAAkB,EAClB,IAAW;IAEX,OAAO,MAAM,CACX,WAAW,EACX,WAAW,EACX,OAAO,EACP,KAAK,EACL,IAAI,CACL,CAAA;AACH,CAAC","sourcesContent":["import type { IncomingHttpHeaders, IncomingMessage } from 'http'\n\n/**\n * Codification of vlt's Error.cause conventions\n *\n * Add new properties to this list as needed.\n *\n * Several of these types are just very basic duck-typing, because referencing\n * internal types directly would create a workspace dependency cycle.\n */\nexport type ErrorCauseObject = {\n /**\n * The `cause` field within a `cause` object should\n * always be an `Error` object that was previously thrown. Note\n * that the `cause` on an Error itself might _also_ be a\n * previously thrown error, if no additional information could be\n * usefully added beyond improving the message. It is typed as `unknown`\n * because we use `useUnknownInCatchVariables` so this makes it easier\n * to rethrow a caught error without recasting it.\n */\n cause?: ErrorCause | unknown // eslint-disable-line @typescript-eslint/no-redundant-type-constituents\n\n /** the name of something */\n name?: string\n\n /** byte offset in a Buffer or file */\n offset?: number\n\n /**\n * This should only be a string code that we set. See {@link Codes} for\n * the supported options. Lower-level system codes like `ENOENT` should\n * remain on the errors that generated them.\n */\n code?: Codes\n\n /** target of a file system operation */\n path?: string\n\n /**\n * file path origin of a resolution that failed, for example in the case\n * of `file://` specifiers.\n */\n from?: string\n\n /** path on disk that is being written, linked, or extracted to */\n target?: string\n\n /** Spec object/string relevant to an operation that failed */\n spec?:\n | string\n | {\n type: 'file' | 'git' | 'registry' | 'remote' | 'workspace'\n spec: string\n [k: number | string | symbol]: any\n }\n\n /** exit code of a process, or HTTP response status code */\n status?: number | null\n\n /** null or a signal that a process received */\n signal?: NodeJS.Signals | null\n\n /** the root of a project */\n projectRoot?: string\n\n /** the current working directory of a process */\n cwd?: string\n\n /** a command being run in a child process */\n command?: string\n\n /** the arguments passed to a process */\n args?: string[]\n\n /** standard output from a process */\n stdout?: Buffer | string | null\n\n /** standard error from a process */\n stderr?: Buffer | string | null\n\n /**\n * Array of valid options when something is not a valid option.\n * (For use in `did you mean X?` output.)\n */\n validOptions?: any[]\n\n /**\n * message indicating what bit of work this might be a part of, what feature\n * needs to be implemented, etc. Eg, `{ todo: 'nested workspace support' }`.\n */\n todo?: string\n\n /**\n * A desired value that was not found, or a regular expression or other\n * pattern describing it.\n */\n wanted?: any\n\n /** actual value, which was not wanted */\n found?: any\n\n /** HTTP message, fetch.Response, or `@vltpkg/registry-client.CacheEntry` */\n response?:\n | IncomingMessage\n | Response\n | {\n statusCode: number\n headers:\n | Buffer[]\n | Record<string, string[] | string>\n | IncomingHttpHeaders\n text?: () => string\n [k: number | string | symbol]: any\n }\n\n /** string or URL object */\n url?: URL | string\n\n /** git repository remote or path */\n repository?: string\n\n /** string or `@vltpkg/semver.Version` object */\n version?:\n | string\n | {\n raw: string\n major: number\n minor: number\n patch: number\n [k: number | string | symbol]: any\n }\n\n /** string or `@vltpkg/semver.Range` object */\n range?:\n | string\n | {\n raw: string\n isAny: boolean\n includePrerelease: boolean\n [k: number | string | symbol]: any\n }\n\n /** a package manifest, either from `package.json` or a registry */\n manifest?: DuckTypeManifest\n\n /** registry top-level package document */\n packument?: {\n name: string\n 'dist-tags': Record<string, string>\n versions: Record<string, DuckTypeManifest>\n time?: Record<string, string>\n }\n\n /** maximum value, which was exceeded */\n max?: any\n\n /** minimum value, which was not met */\n min?: any\n}\n\nexport type DuckTypeManifest = Record<string, any> & {\n name?: string\n version?: string\n deprecated?: string\n engines?: Record<string, string>\n os?: string[] | string\n arch?: string[] | string\n dist?: {\n integrity?: string\n shasum?: string\n tarball?: string\n fileCount?: number\n unpackedSize?: number\n signatures?: {\n keyid: string\n sig: string\n }[]\n }\n}\n\nexport type ErrorCause = Error | ErrorCauseObject\n\n/**\n * An error with a cause that is a direct error cause object and not another\n * nested error.\n */\nexport type ErrorWithCauseObject = Error & { cause: ErrorCauseObject }\n\n/**\n * A TypeError with a cause that is a direct error cause object and not\n * another nested error\n */\n\n/**\n * If it is any sort of plain-ish object, assume its an error cause\n * because all properties of the cause are optional.\n */\nexport const isErrorCauseObject = (\n v: unknown,\n): v is ErrorCauseObject =>\n !!v && typeof v === 'object' && !Array.isArray(v)\n\n/**\n * Type guard for {@link ErrorWithCauseObject} type\n */\nexport const isErrorRoot = (\n er: unknown,\n): er is ErrorWithCauseObject =>\n er instanceof Error && isErrorCauseObject(er.cause)\n\nexport const asErrorCause = (er: unknown): ErrorCause =>\n er instanceof Error ? er\n : isErrorCauseObject(er) ? er\n // otherwise, make an error of the stringified message\n : new Error(\n // eslint-disable-next-line @typescript-eslint/no-base-to-string\n er == null ? 'Unknown error' : String(er) || 'Unknown error',\n )\n\n/**\n * Valid properties for the 'code' field in an Error cause.\n * Add new options to this list as needed.\n */\nexport type Codes =\n | 'EEXIST'\n | 'EINTEGRITY'\n | 'EINVAL'\n | 'ELIFECYCLE'\n | 'EMAXREDIRECT'\n | 'ENEEDAUTH'\n | 'ENOENT'\n | 'ENOGIT'\n | 'ERESOLVE'\n | 'EUNKNOWN'\n | 'EUSAGE'\n\ntype ErrorCtor<T extends Error> = new (\n message: string,\n options?: { cause: ErrorCause },\n) => T\n\nfunction create<T extends Error>(\n cls: ErrorCtor<T>,\n defaultFrom: ((...a: any[]) => any) | (new (...a: any[]) => any),\n message: string,\n cause?: undefined,\n from?: From,\n): T\nfunction create<T extends Error>(\n cls: ErrorCtor<T>,\n defaultFrom: ((...a: any[]) => any) | (new (...a: any[]) => any),\n message: string,\n cause?: ErrorCauseObject,\n from?: From,\n): T & { cause: ErrorCauseObject }\nfunction create<T extends Error>(\n cls: ErrorCtor<T>,\n defaultFrom: ((...a: any[]) => any) | (new (...a: any[]) => any),\n message: string,\n cause?: Error,\n from?: From,\n): T & { cause: Error }\nfunction create<T extends Error>(\n cls: ErrorCtor<T>,\n defaultFrom: ((...a: any[]) => any) | (new (...a: any[]) => any),\n message: string,\n cause?: ErrorCause,\n from?: From,\n): T & { cause: ErrorCause }\nfunction create<T extends Error>(\n cls: ErrorCtor<T>,\n defaultFrom: ((...a: any[]) => any) | (new (...a: any[]) => any),\n message: string,\n cause?: ErrorCause,\n from: From = defaultFrom,\n) {\n const er = new cls(message, cause ? { cause } : undefined)\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n Error.captureStackTrace?.(er, from)\n return er\n}\n\nexport type From = ((...a: any[]) => any) | (new (...a: any[]) => any)\n\nexport function error(\n message: string,\n cause?: undefined,\n from?: From,\n): Error\nexport function error(\n message: string,\n cause: ErrorCauseObject,\n from?: From,\n): Error & { cause: ErrorCauseObject }\nexport function error(\n message: string,\n cause: Error,\n from?: From,\n): Error & { cause: Error }\nexport function error(\n message: string,\n cause: ErrorCause,\n from?: From,\n): Error & { cause: ErrorCause }\nexport function error(\n message: string,\n cause?: ErrorCause,\n from?: From,\n) {\n return create(Error, error, message, cause, from)\n}\n\nexport function typeError(\n message: string,\n cause?: undefined,\n from?: From,\n): TypeError\nexport function typeError(\n message: string,\n cause: ErrorCauseObject,\n from?: From,\n): TypeError & { cause: ErrorCauseObject }\nexport function typeError(\n message: string,\n cause: Error,\n from?: From,\n): TypeError & { cause: Error }\nexport function typeError(\n message: string,\n cause: ErrorCause,\n from?: From,\n): TypeError & { cause: ErrorCause }\nexport function typeError(\n message: string,\n cause?: ErrorCause,\n from?: From,\n) {\n return create<TypeError>(TypeError, typeError, message, cause, from)\n}\n\nexport function syntaxError(\n message: string,\n cause?: undefined,\n from?: From,\n): SyntaxError\nexport function syntaxError(\n message: string,\n cause: ErrorCauseObject,\n from?: From,\n): SyntaxError & { cause: ErrorCauseObject }\nexport function syntaxError(\n message: string,\n cause: Error,\n from?: From,\n): SyntaxError & { cause: Error }\nexport function syntaxError(\n message: string,\n cause: ErrorCause,\n from?: From,\n): SyntaxError & { cause: ErrorCause }\nexport function syntaxError(\n message: string,\n cause?: ErrorCause,\n from?: From,\n) {\n return create<SyntaxError>(\n SyntaxError,\n syntaxError,\n message,\n cause,\n from,\n )\n}\n"]}
|
package/package.json
CHANGED
|
@@ -1,9 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vltpkg/error-cause",
|
|
3
3
|
"description": "vlts Error.cause convention",
|
|
4
|
-
"version": "0.0.0-
|
|
4
|
+
"version": "0.0.0-2",
|
|
5
|
+
"repository": {
|
|
6
|
+
"type": "git",
|
|
7
|
+
"url": "git+https://github.com/vltpkg/vltpkg.git",
|
|
8
|
+
"directory": "src/error-cause"
|
|
9
|
+
},
|
|
5
10
|
"tshy": {
|
|
6
11
|
"selfLink": false,
|
|
12
|
+
"liveDev": true,
|
|
7
13
|
"dialects": [
|
|
8
14
|
"esm"
|
|
9
15
|
],
|
|
@@ -13,19 +19,20 @@
|
|
|
13
19
|
}
|
|
14
20
|
},
|
|
15
21
|
"devDependencies": {
|
|
16
|
-
"@eslint/js": "^9.
|
|
22
|
+
"@eslint/js": "^9.20.0",
|
|
17
23
|
"@types/eslint__js": "^8.42.3",
|
|
18
|
-
"@types/node": "^22.
|
|
19
|
-
"eslint": "^9.
|
|
20
|
-
"prettier": "^3.
|
|
21
|
-
"tap": "^21.0
|
|
24
|
+
"@types/node": "^22.13.1",
|
|
25
|
+
"eslint": "^9.20.0",
|
|
26
|
+
"prettier": "^3.4.2",
|
|
27
|
+
"tap": "^21.1.0",
|
|
22
28
|
"tshy": "^3.0.2",
|
|
23
|
-
"
|
|
24
|
-
"typescript
|
|
29
|
+
"typedoc": "0.27.6",
|
|
30
|
+
"typescript": "5.7.3",
|
|
31
|
+
"typescript-eslint": "^8.23.0"
|
|
25
32
|
},
|
|
26
33
|
"license": "BSD-2-Clause-Patent",
|
|
27
34
|
"engines": {
|
|
28
|
-
"node": "
|
|
35
|
+
"node": ">=22"
|
|
29
36
|
},
|
|
30
37
|
"tap": {
|
|
31
38
|
"extends": "../../tap-config.yaml"
|
|
@@ -50,9 +57,9 @@
|
|
|
50
57
|
"format:check": "prettier --check . --ignore-path ../../.prettierignore --cache",
|
|
51
58
|
"lint": "eslint . --fix",
|
|
52
59
|
"lint:check": "eslint .",
|
|
53
|
-
"presnap": "tshy",
|
|
54
60
|
"snap": "tap",
|
|
55
|
-
"
|
|
56
|
-
"
|
|
61
|
+
"test": "tap",
|
|
62
|
+
"posttest": "tsc --noEmit",
|
|
63
|
+
"typecheck": "tsc --noEmit"
|
|
57
64
|
}
|
|
58
65
|
}
|