@vltpkg/error-cause 0.0.0-3 → 0.0.0-5

package/README.md

@@ -2,25 +2,22 @@
 
 # @vltpkg/error-cause
 
-Utility functions for `Error` creation to help enforce vlt's `Error.cause` conventions.
+Utility functions for `Error` creation to help enforce vlt's
+`Error.cause` conventions.
 
-**[Usage](#usage)**
-·
-**[Error Reporting](#challenges-of-error-reporting)**
-·
-**[Conventions](#conventions)**
-·
-**[Error Types](#error-types)**
+**[Usage](#usage)** ·
+**[Error Reporting](#challenges-of-error-reporting)** ·
+**[Conventions](#conventions)** · **[Error Types](#error-types)**
 
 ## Why
 
-Most node programs have a mishmash of error codes and various
-`Error` subtypes, all in different shapes, making error handling
-and reporting more difficult at the top level. This negatively
-impacts debugging and user experience.
+Most node programs have a mishmash of error codes and various `Error`
+subtypes, all in different shapes, making error handling and reporting
+more difficult at the top level. This negatively impacts debugging and
+user experience.
 
-The JavaScript `Error` constructor has a [`cause`
-option](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)
+The JavaScript `Error` constructor has a
+[`cause` option](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)
 which is supported since Node 16.9. We should use it!
 
 This module makes that easy.
@@ -68,62 +65,60 @@ const checkBar = () => {
 }
 ```
 
-The functions will create an error object with a `cause` property
-if set, and the type checks will ensure that the `cause` object
-matches vlt's conventions.
+The functions will create an error object with a `cause` property if
+set, and the type checks will ensure that the `cause` object matches
+vlt's conventions.
 
 ## Challenges of Error Reporting
 
 - Provide enough information to be useful. On full inspection, we
-  should ideally always get back to not just the initial error
-  that was thrown, but also all locations where the error might
-  have been caught and handled in some way.
+  should ideally always get back to not just the initial error that
+  was thrown, but also all locations where the error might have been
+  caught and handled in some way.
 - Do not provide more information than is useful. Eg,
-  `console.error(er)` should not fill the entire scrollback
-  buffer.
-- New modules and libraries should have minimal friction in
-  creating a new style of error when needed. This means, minimize
-  the amount that any module needs to know about the errors
-  raised by any other module, including especially top-level
-  error handling.
-- _Some_ information about the error must be known to our
-  top-level error handler, so that it can usefully report errors
-  and suggest corrections.
+  `console.error(er)` should not fill the entire scrollback buffer.
+- New modules and libraries should have minimal friction in creating a
+  new style of error when needed. This means, minimize the amount that
+  any module needs to know about the errors raised by any other
+  module, including especially top-level error handling.
+- _Some_ information about the error must be known to our top-level
+  error handler, so that it can usefully report errors and suggest
+  corrections.
 
 ## Solution
 
 - A strictly upheld convention of Error object creation using the
   `cause` property.
-- Top level error handler can have special logic where necessary
-  for known error codes, but will still be able to do something
-  more useful when an Error object follows our conventions, even
-  if it's not a code that it knows.
+- Top level error handler can have special logic where necessary for
+  known error codes, but will still be able to do something more
+  useful when an Error object follows our conventions, even if it's
+  not a code that it knows.
 
 ## Conventions
 
-The following conventions should be followed for all `Error`
-creation and handling throughout the vlt codebase.
+The following conventions should be followed for all `Error` creation
+and handling throughout the vlt codebase.
 
 - **If you can't help, get out of the way.** Just let throws pass
   through to the top when nothing can be done to assist.
 - **Add information by using thrown error as `cause`.** Use a
   previously-thrown error as the `cause` option.
-- **Add even more info with a double-`cause`.** If more info can
-  be added to a prior throw, nest the `cause` properties like
+- **Add even more info with a double-`cause`.** If more info can be
+  added to a prior throw, nest the `cause` properties like
   `{ some, other, info, cause: priorError }`.
 - **Always set `cause`, even if no prior error.** Use a plain-old
   JavaScript object following our field conventions.
 - **Rare exception: synthetic ErrnoException style errors.** If we are
   doing something that is similar to a system operation, it's
   sometimes ok to mimic node's pattern.
-- **Do not subclass `Error`.** Just create a plain old Error, and
-  set the `cause` with additional information.
+- **Do not subclass `Error`.** Just create a plain old Error, and set
+  the `cause` with additional information.
 
 ### If you can't help, don't get in the way.
 
-Whenever possible, if no remediation or extra information can
-usefully be added, it's best to just not handle errors and let
-them be raised at the higher level. For example, instead of this:
+Whenever possible, if no remediation or extra information can usefully
+be added, it's best to just not handle errors and let them be raised
+at the higher level. For example, instead of this:
 
 ```
 let data
@@ -142,9 +137,9 @@ const data = await readFile(someFile)
 
 ### Add information by using thrown error as `cause`.
 
-If we can add information or do something else useful for the
-user in understanding the problem, do so by creating a new
-`Error` and setting the original thrown error as the `cause`.
+If we can add information or do something else useful for the user in
+understanding the problem, do so by creating a new `Error` and setting
+the original thrown error as the `cause`.
 
 ```js
 let data
@@ -158,9 +153,9 @@ try {
 
 ### Add even more info with a double-`cause`.
 
-If we can add even more information, that should ideally _not_ be
-put on the Error we throw, but on a `cause` object. Because
-`cause` objects can nest, we can do something like this:
+If we can add even more information, that should ideally _not_ be put
+on the Error we throw, but on a `cause` object. Because `cause`
+objects can nest, we can do something like this:
 
 ```js
 let data
@@ -204,27 +199,25 @@ throw error('could not resolve', {
 })
 ```
 
-This makes any big objects easily skipped if we want to just
-output the error with `console.error()` or something, but still
-preserves any debugging information that might be useful all the
-way down the chain.
+This makes any big objects easily skipped if we want to just output
+the error with `console.error()` or something, but still preserves any
+debugging information that might be useful all the way down the chain.
 
 ### Rare exception: synthetic ErrnoException style errors.
 
-In some rare low-level cases, there are operations we perform
-that are very similar to a node filesystem operation.
+In some rare low-level cases, there are operations we perform that are
+very similar to a node filesystem operation.
 
 For example, the `@vltpkg/which` module raises an error that is
-intentionally similar to node's filesystem `ENOENT` errors,
-because that is semantically sensible.
+intentionally similar to node's filesystem `ENOENT` errors, because
+that is semantically sensible.
 
-In those cases, the error _must_ follow node's conventions as
-close as possible. If we feel the need to add additional
-information beyond a known system error code, string path, etc.,
-or if the message isn't one that is typically raised by the
-underlying system, then it's a good sign that we ought to be
-creating an `Error` with a `cause` so that it can be reported
-more usefully.
+In those cases, the error _must_ follow node's conventions as close as
+possible. If we feel the need to add additional information beyond a
+known system error code, string path, etc., or if the message isn't
+one that is typically raised by the underlying system, then it's a
+good sign that we ought to be creating an `Error` with a `cause` so
+that it can be reported more usefully.
 
 In such cases, this is fine:
 
@@ -246,11 +239,11 @@ throw Object.assign(new Error('could not resolve'), {
 })
 ```
 
-**Do not** copy properties from a lower-level error or cause onto
-the new cause object. That is unnecessary, and obscures the
-origin of problems. Instead, just include the lower-level error
-as the `cause` property. If you already have a low-level error,
-you don't need to invent a synthetic one!
+**Do not** copy properties from a lower-level error or cause onto the
+new cause object. That is unnecessary, and obscures the origin of
+problems. Instead, just include the lower-level error as the `cause`
+property. If you already have a low-level error, you don't need to
+invent a synthetic one!
 
 For example, do not do this:
 
@@ -280,8 +273,8 @@ try {
 ### Do not subclass `Error`.
 
 Just use the `Error` classes defined in the language. Additional
-information about error causes should be on the `cause` property,
-not implicit in the constructor type.
+information about error causes should be on the `cause` property, not
+implicit in the constructor type.
 
 I.e. do not do this:
 
@@ -308,33 +301,33 @@ throw error('Could not version', { version })
 All of these are optional. Additional fields may be used where
 appropriate, and should be added to this list over time.
 
-- `cause` - 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.
+- `cause` - 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.
 - `name` - String. The name of something.
 - `offset` - Number. The offset in a Buffer or file where we are
   trying to read or write.
 - `registry` - String or URL. A package registry.
-- `code` - This must be a string if set, and should
-  only be present if it's one of our creation, not a code raised
-  on a system error. Eg, `ERESOLVE`, not `ENOENT`.
+- `code` - This must be a string if set, and should only be present if
+  it's one of our creation, not a code raised on a system error. Eg,
+  `ERESOLVE`, not `ENOENT`.
 - `path` - The target of a file system operation.
 - `target` - path on disk that is being written or extracted to
-- `spec` - a `@vltpkg/spec.Spec` object relevant to the operation
-  that failed.
-- `from` - string. The file path origin of a resolution that
-  failed, for example in the case of relative `file:` specifiers.
-- `status` - Number or null. Either the exit code of a process or
-  an HTTP response status code.
-- `signal` - `NodeJS.Signals` string or null, indicating the
-  signal that terminated a process.
+- `spec` - a `@vltpkg/spec.Spec` object relevant to the operation that
+  failed.
+- `from` - string. The file path origin of a resolution that failed,
+  for example in the case of relative `file:` specifiers.
+- `status` - Number or null. Either the exit code of a process or an
+  HTTP response status code.
+- `signal` - `NodeJS.Signals` string or null, indicating the signal
+  that terminated a process.
 - `validOptions` - Array of valid options when something is not a
   valid option. (For use in `did you mean X?` output.)
-- `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' }`.
+- `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' }`.
 - `wanted` - A desired value that was not found, or a regular
   expression or other pattern describing it.
 - `found` - The actual value, which was not wanted.
@@ -354,9 +347,9 @@ todo: 'nested workspace support' }`.
 
 - If there is a _type_ problem with an argument, for example a
   `string` was expected and a `number` was provided, throw a
-  `TypeError`. **Do not** use it for a value that is the correct
-  type but otherwise invalid, such as a `string` argument that is
-  actually a `string` but does not match an expected pattern.
+  `TypeError`. **Do not** use it for a value that is the correct type
+  but otherwise invalid, such as a `string` argument that is actually
+  a `string` but does not match an expected pattern.
 - If the type is fine, but a parsed string is invalid and not
   parseable, use `SyntaxError`.
 - In all other cases, use `Error`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/error-cause",
   "description": "vlts Error.cause convention",
-  "version": "0.0.0-3",
+  "version": "0.0.0-5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",