@vltpkg/error-cause 0.0.0-0.1730239248325 → 0.0.0-0.1730724342581
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 +2 -2
- package/dist/esm/index.d.ts.map +1 -1
- package/dist/esm/index.js.map +1 -1
- package/package.json +1 -1
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
|
|
1
|
+
import { type IncomingMessage } from 'http';
|
|
2
2
|
/**
|
|
3
3
|
* Codification of vlt's Error.cause conventions
|
|
4
4
|
*
|
|
@@ -138,7 +138,7 @@ export type ErrorCause = Error | ErrorCauseObject;
|
|
|
138
138
|
* Valid properties for the 'code' field in an Error cause.
|
|
139
139
|
* Add new options to this list as needed.
|
|
140
140
|
*/
|
|
141
|
-
export type Codes = 'EEXIST' | 'EINTEGRITY' | 'EINVAL' | 'ELIFECYCLE' | 'EMAXREDIRECT' | 'ENEEDAUTH' | 'ENOENT' | 'ENOGIT' | 'ERESOLVE' | 'EUNKNOWN';
|
|
141
|
+
export type Codes = 'EEXIST' | 'EINTEGRITY' | 'EINVAL' | 'ELIFECYCLE' | 'EMAXREDIRECT' | 'ENEEDAUTH' | 'ENOENT' | 'ENOGIT' | 'ERESOLVE' | 'EUNKNOWN' | 'EUSAGE';
|
|
142
142
|
export declare const error: (message: string, cause?: ErrorCause, from?: ((...a: any[]) => any) | (new (...a: any[]) => any)) => Error;
|
|
143
143
|
export declare const typeError: (message: string, cause?: ErrorCause, from?: ((...a: any[]) => any) | (new (...a: any[]) => any)) => Error;
|
|
144
144
|
export declare const syntaxError: (message: string, cause?: ErrorCause, from?: ((...a: any[]) => any) | (new (...a: any[]) => any)) => Error;
|
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,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
|
package/dist/esm/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAkMA,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 | 'EUSAGE'\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"]}
|