@vltpkg/error-cause 0.0.0-0.1730724342581 → 0.0.0-10

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/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
-import { type IncomingMessage } from 'http';
+import type { IncomingHttpHeaders, IncomingMessage } from 'http';
 /**
  * Codification of vlt's Error.cause conventions
  *
@@ -7,15 +7,17 @@ import { type IncomingMessage } from 'http';
  * Several of these types are just very basic duck-typing, because referencing
  * internal types directly would create a workspace dependency cycle.
  */
-export type ErrorCauseObject = {
+export type ErrorCauseOptions = {
     /**
      * 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.
+     * 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.
      */
-    cause?: ErrorCause;
+    cause?: unknown;
     /** the name of something */
     name?: string;
     /** byte offset in a Buffer or file */
@@ -61,7 +63,7 @@ export type ErrorCauseObject = {
      * Array of valid options when something is not a valid option.
      * (For use in `did you mean X?` output.)
      */
-    validOptions?: any[];
+    validOptions?: unknown[];
     /**
      * message indicating what bit of work this might be a part of, what feature
      * needs to be implemented, etc. Eg, `{ todo: 'nested workspace support' }`.
@@ -71,18 +73,20 @@ export type ErrorCauseObject = {
      * A desired value that was not found, or a regular expression or other
      * pattern describing it.
      */
-    wanted?: any;
+    wanted?: unknown;
     /** actual value, which was not wanted */
-    found?: any;
+    found?: unknown;
     /** HTTP message, fetch.Response, or `@vltpkg/registry-client.CacheEntry` */
     response?: IncomingMessage | Response | {
         statusCode: number;
-        headers: Buffer[] | Record<string, string[] | string>;
-        text: () => string;
+        headers: Buffer[] | Record<string, string[] | string> | IncomingHttpHeaders;
+        text?: () => string;
         [k: number | string | symbol]: any;
     };
     /** string or URL object */
     url?: URL | string;
+    /** HTTP method */
+    method?: string;
     /** git repository remote or path */
     repository?: string;
     /** string or `@vltpkg/semver.Version` object */
@@ -110,9 +114,9 @@ export type ErrorCauseObject = {
         time?: Record<string, string>;
     };
     /** maximum value, which was exceeded */
-    max?: any;
+    max?: unknown;
     /** minimum value, which was not met */
-    min?: any;
+    min?: unknown;
 };
 export type DuckTypeManifest = Record<string, any> & {
     name?: string;
@@ -133,13 +137,75 @@ export type DuckTypeManifest = Record<string, any> & {
         }[];
     };
 };
-export type ErrorCause = Error | ErrorCauseObject;
+/**
+ * The input cause for the {@link error} functions. Can either be a plain error
+ * or an error cause options object.
+ */
+export type ErrorCause = Error | ErrorCauseOptions;
+/**
+ * The same as {@link ErrorCauseOptions} except where `cause` has been
+ * converted to an Error.
+ */
+export type ErrorCauseResult = Omit<ErrorCauseOptions, 'cause'> & {
+    cause?: Error;
+};
+/**
+ * An error with a cause property. Cause defaults to `unknown`.
+ */
+export type ErrorWithCause<T extends Error = Error, U = unknown> = T & {
+    cause: U;
+};
+/**
+ * An error with a cause property that is an Error.
+ */
+export type ErrorWithCauseError<T extends Error = Error> = ErrorWithCause<T, Error>;
+/**
+ * An error with a cause property that is an {@link ErrorCauseResult}.
+ */
+export type ErrorWithCauseObject<T extends Error = Error> = ErrorWithCause<T, ErrorCauseResult>;
+/**
+ * Helper util to convert unknown to a plain error. Not specifically
+ * related to error causes, but useful for error handling in general.
+ */
+export declare const asError: (er: unknown, fallbackMessage?: string) => Error;
+/**
+ * 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.
+ */
+export declare const isErrorWithCause: (er: unknown) => er is ErrorWithCause;
+export declare const errorCodes: readonly ["EEXIST", "EINTEGRITY", "EINVAL", "ELIFECYCLE", "EMAXREDIRECT", "ENEEDAUTH", "ENOENT", "ENOGIT", "ERESOLVE", "EUNKNOWN", "EUSAGE", "EREQUEST"];
 /**
  * Valid properties for the 'code' field in an Error cause.
  * Add new options to this list as needed.
  */
-export type Codes = 'EEXIST' | 'EINTEGRITY' | 'EINVAL' | 'ELIFECYCLE' | 'EMAXREDIRECT' | 'ENEEDAUTH' | 'ENOENT' | 'ENOGIT' | 'ERESOLVE' | 'EUNKNOWN' | 'EUSAGE';
-export declare const error: (message: string, cause?: ErrorCause, from?: ((...a: any[]) => any) | (new (...a: any[]) => any)) => Error;
-export declare const typeError: (message: string, cause?: ErrorCause, from?: ((...a: any[]) => any) | (new (...a: any[]) => any)) => Error;
-export declare const syntaxError: (message: string, cause?: ErrorCause, from?: ((...a: any[]) => any) | (new (...a: any[]) => any)) => Error;
+export type Codes = (typeof errorCodes)[number];
+/**
+ *  An error with a cause property that is an {@link ErrorCauseResult}
+ * and has a code property that is a {@link Codes}.
+ */
+export type ErrorWithCode<T extends Error = Error> = ErrorWithCause<T, Omit<ErrorCauseResult, 'code'> & {
+    code: Exclude<ErrorCauseResult['code'], undefined>;
+}>;
+/**
+ * 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 {@link ErrorCauseOptions} is optional, this should
+ * be sufficient to know the shape of the cause and use it in printing.
+ */
+export declare const isErrorWithCode: (er: unknown) => er is ErrorWithCode;
+export type From = Function;
+export type ErrorCtor<T extends Error> = new (message: string, options?: {
+    cause: Error | ErrorCauseResult;
+}) => T;
+export type ErrorResult<T extends Error = Error> = T | ErrorWithCauseError<TypeError> | ErrorWithCauseObject<TypeError>;
+export declare function error(message: string, cause?: undefined, from?: From): Error;
+export declare function error(message: string, cause: Error, from?: From): ErrorWithCauseError;
+export declare function error(message: string, cause: ErrorCauseOptions, from?: From): ErrorWithCauseObject;
+export declare function typeError(message: string, cause?: undefined, from?: From): TypeError;
+export declare function typeError(message: string, cause: Error, from?: From): ErrorWithCauseError<TypeError>;
+export declare function typeError(message: string, cause: ErrorCauseOptions, from?: From): ErrorWithCauseObject<TypeError>;
+export declare function syntaxError(message: string, cause?: undefined, from?: From): SyntaxError;
+export declare function syntaxError(message: string, cause: Error, from?: From): ErrorWithCauseError<SyntaxError>;
+export declare function syntaxError(message: string, cause: ErrorCauseOptions, from?: From): ErrorWithCauseObject<SyntaxError>;
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -1,10 +1,70 @@
-const create = (cls, defaultFrom, message, cause, from = defaultFrom) => {
-    const er = new cls(message, cause ? { cause } : undefined);
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    Error.captureStackTrace?.(er, from);
+/**
+ * Helper util to convert unknown to a plain error. Not specifically
+ * related to error causes, but useful for error handling in general.
+ */
+export const asError = (er, fallbackMessage = 'Unknown error') => er instanceof Error ? er : new Error(String(er) || fallbackMessage);
+/**
+ * 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.
+ */
+export const isErrorWithCause = (er) => er instanceof Error && 'cause' in er;
+export const errorCodes = [
+    'EEXIST',
+    'EINTEGRITY',
+    'EINVAL',
+    'ELIFECYCLE',
+    'EMAXREDIRECT',
+    'ENEEDAUTH',
+    'ENOENT',
+    'ENOGIT',
+    'ERESOLVE',
+    'EUNKNOWN',
+    'EUSAGE',
+    'EREQUEST',
+];
+const errorCodesSet = new Set(errorCodes);
+/**
+ * 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 {@link ErrorCauseOptions} is optional, this should
+ * be sufficient to know the shape of the cause and use it in printing.
+ */
+export const isErrorWithCode = (er) => isErrorWithCause(er) &&
+    !!er.cause &&
+    typeof er.cause === 'object' &&
+    'code' in er.cause &&
+    typeof er.cause.code === 'string' &&
+    errorCodesSet.has(er.cause.code);
+// `captureStackTrace` is non-standard so explicitly type it as possibly
+// undefined since it might be in browsers.
+const { captureStackTrace } = Error;
+function create(cls, defaultFrom, message, cause, from = defaultFrom) {
+    let er = null;
+    if (cause instanceof Error) {
+        er = new cls(message, { cause });
+    }
+    else if (cause && typeof cause === 'object') {
+        if ('cause' in cause) {
+            cause.cause = asError(cause.cause);
+        }
+        er = new cls(message, {
+            cause: cause,
+        });
+    }
+    else {
+        er = new cls(message);
+    }
+    captureStackTrace?.(er, from);
     return er;
-};
-export const error = (message, cause, from) => create(Error, error, message, cause, from);
-export const typeError = (message, cause, from) => create(TypeError, typeError, message, cause, from);
-export const syntaxError = (message, cause, from) => create(SyntaxError, syntaxError, message, cause, from);
+}
+export function error(message, cause, from) {
+    return create(Error, error, message, cause, from);
+}
+export function typeError(message, cause, from) {
+    return create(TypeError, typeError, message, cause, from);
+}
+export function syntaxError(message, cause, from) {
+    return create(SyntaxError, syntaxError, message, cause, from);
+}
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +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"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAyNA;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,EAAW,EACX,eAAe,GAAG,eAAe,EAC1B,EAAE,CACT,EAAE,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,eAAe,CAAC,CAAA;AAErE;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,EAAW,EAAwB,EAAE,CACpE,EAAE,YAAY,KAAK,IAAI,OAAO,IAAI,EAAE,CAAA;AAEtC,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,QAAQ;IACR,YAAY;IACZ,QAAQ;IACR,YAAY;IACZ,cAAc;IACd,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,UAAU;IACV,QAAQ;IACR,UAAU;CACF,CAAA;AAEV,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAA;AAmBzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAW,EAAuB,EAAE,CAClE,gBAAgB,CAAC,EAAE,CAAC;IACpB,CAAC,CAAC,EAAE,CAAC,KAAK;IACV,OAAO,EAAE,CAAC,KAAK,KAAK,QAAQ;IAC5B,MAAM,IAAI,EAAE,CAAC,KAAK;IAClB,OAAO,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;IACjC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,IAAa,CAAC,CAAA;AAM3C,wEAAwE;AACxE,2CAA2C;AAC3C,MAAM,EAAE,iBAAiB,EAAE,GAAG,KAE7B,CAAA;AAiCD,SAAS,MAAM,CACb,GAAiB,EACjB,WAAiB,EACjB,OAAe,EACf,KAAkB,EAClB,OAAa,WAAW;IAExB,IAAI,EAAE,GAAa,IAAI,CAAA;IACvB,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IAClC,CAAC;SAAM,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9C,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;YACrB,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACpC,CAAC;QACD,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE;YACpB,KAAK,EAAE,KAAyB;SACjC,CAAC,CAAA;IACJ,CAAC;SAAM,CAAC;QACN,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAA;IACvB,CAAC;IACD,iBAAiB,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC7B,OAAO,EAAE,CAAA;AACX,CAAC;AAiBD,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;AAiBD,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;AAiBD,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 ErrorCauseOptions = {\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?: unknown\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?: unknown[]\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?: unknown\n\n  /** actual value, which was not wanted */\n  found?: unknown\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  /** HTTP method */\n  method?: 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?: unknown\n\n  /** minimum value, which was not met */\n  min?: unknown\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\n/**\n * The input cause for the {@link error} functions. Can either be a plain error\n * or an error cause options object.\n */\nexport type ErrorCause = Error | ErrorCauseOptions\n\n/**\n * The same as {@link ErrorCauseOptions} except where `cause` has been\n * converted to an Error.\n */\nexport type ErrorCauseResult = Omit<ErrorCauseOptions, 'cause'> & {\n  cause?: Error\n}\n\n/**\n * An error with a cause property. Cause defaults to `unknown`.\n */\nexport type ErrorWithCause<\n  T extends Error = Error,\n  U = unknown,\n> = T & { cause: U }\n\n/**\n * An error with a cause property that is an Error.\n */\nexport type ErrorWithCauseError<T extends Error = Error> =\n  ErrorWithCause<T, Error>\n\n/**\n * An error with a cause property that is an {@link ErrorCauseResult}.\n */\nexport type ErrorWithCauseObject<T extends Error = Error> =\n  ErrorWithCause<T, ErrorCauseResult>\n\n/**\n * Helper util to convert unknown to a plain error. Not specifically\n * related to error causes, but useful for error handling in general.\n */\nexport const asError = (\n  er: unknown,\n  fallbackMessage = 'Unknown error',\n): Error =>\n  er instanceof Error ? er : new Error(String(er) || fallbackMessage)\n\n/**\n * Helper util to check if an error has any type of cause property.\n * Note that this does not mean it is a cause from this library,\n * just that it has a cause property.\n */\nexport const isErrorWithCause = (er: unknown): er is ErrorWithCause =>\n  er instanceof Error && 'cause' in er\n\nexport const errorCodes = [\n  'EEXIST',\n  'EINTEGRITY',\n  'EINVAL',\n  'ELIFECYCLE',\n  'EMAXREDIRECT',\n  'ENEEDAUTH',\n  'ENOENT',\n  'ENOGIT',\n  'ERESOLVE',\n  'EUNKNOWN',\n  'EUSAGE',\n  'EREQUEST',\n] as const\n\nconst errorCodesSet = new Set(errorCodes)\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 = (typeof errorCodes)[number]\n\n/**\n *  An error with a cause property that is an {@link ErrorCauseResult}\n * and has a code property that is a {@link Codes}.\n */\nexport type ErrorWithCode<T extends Error = Error> = ErrorWithCause<\n  T,\n  Omit<ErrorCauseResult, 'code'> & {\n    code: Exclude<ErrorCauseResult['code'], undefined>\n  }\n>\n\n/**\n * Type guard to check if an error has one of our error code properties.\n * Note that the type check only checks for the code property and value,\n * but since every property on {@link ErrorCauseOptions} is optional, this should\n * be sufficient to know the shape of the cause and use it in printing.\n */\nexport const isErrorWithCode = (er: unknown): er is ErrorWithCode =>\n  isErrorWithCause(er) &&\n  !!er.cause &&\n  typeof er.cause === 'object' &&\n  'code' in er.cause &&\n  typeof er.cause.code === 'string' &&\n  errorCodesSet.has(er.cause.code as Codes)\n\n// Use `Function` because that is the same type as `Error.captureStackTrace`\n// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type\nexport type From = Function\n\n// `captureStackTrace` is non-standard so explicitly type it as possibly\n// undefined since it might be in browsers.\nconst { captureStackTrace } = Error as {\n  captureStackTrace?: ErrorConstructor['captureStackTrace']\n}\n\nexport type ErrorCtor<T extends Error> = new (\n  message: string,\n  options?: { cause: Error | ErrorCauseResult },\n) => T\n\nexport type ErrorResult<T extends Error = Error> =\n  | T\n  | ErrorWithCauseError<TypeError>\n  | ErrorWithCauseObject<TypeError>\n\nfunction create<T extends Error>(\n  cls: ErrorCtor<T>,\n  defaultFrom: From,\n  message: string,\n  cause?: undefined,\n  from?: From,\n): T\nfunction create<T extends Error>(\n  cls: ErrorCtor<T>,\n  defaultFrom: From,\n  message: string,\n  cause?: Error,\n  from?: From,\n): ErrorWithCauseError<T>\nfunction create<T extends Error>(\n  cls: ErrorCtor<T>,\n  defaultFrom: From,\n  message: string,\n  cause?: ErrorCauseOptions,\n  from?: From,\n): ErrorWithCauseObject<T>\nfunction create<T extends Error>(\n  cls: ErrorCtor<T>,\n  defaultFrom: From,\n  message: string,\n  cause?: ErrorCause,\n  from: From = defaultFrom,\n) {\n  let er: T | null = null\n  if (cause instanceof Error) {\n    er = new cls(message, { cause })\n  } else if (cause && typeof cause === 'object') {\n    if ('cause' in cause) {\n      cause.cause = asError(cause.cause)\n    }\n    er = new cls(message, {\n      cause: cause as ErrorCauseResult,\n    })\n  } else {\n    er = new cls(message)\n  }\n  captureStackTrace?.(er, from)\n  return er\n}\n\nexport function error(\n  message: string,\n  cause?: undefined,\n  from?: From,\n): Error\nexport function error(\n  message: string,\n  cause: Error,\n  from?: From,\n): ErrorWithCauseError\nexport function error(\n  message: string,\n  cause: ErrorCauseOptions,\n  from?: From,\n): ErrorWithCauseObject\nexport function error(\n  message: string,\n  cause?: ErrorCause,\n  from?: From,\n): ErrorResult {\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: Error,\n  from?: From,\n): ErrorWithCauseError<TypeError>\nexport function typeError(\n  message: string,\n  cause: ErrorCauseOptions,\n  from?: From,\n): ErrorWithCauseObject<TypeError>\nexport function typeError(\n  message: string,\n  cause?: ErrorCause,\n  from?: From,\n): ErrorResult<TypeError> {\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: Error,\n  from?: From,\n): ErrorWithCauseError<SyntaxError>\nexport function syntaxError(\n  message: string,\n  cause: ErrorCauseOptions,\n  from?: From,\n): ErrorWithCauseObject<SyntaxError>\nexport function syntaxError(\n  message: string,\n  cause?: ErrorCause,\n  from?: From,\n): ErrorResult<SyntaxError> {\n  return create<SyntaxError>(\n    SyntaxError,\n    syntaxError,\n    message,\n    cause,\n    from,\n  )\n}\n"]}

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@vltpkg/error-cause",
   "description": "vlts Error.cause convention",
-  "version": "0.0.0-0.1730724342581",
+  "version": "0.0.0-10",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vltpkg/vltpkg.git",
+    "directory": "src/error-cause"
+  },
   "tshy": {
     "selfLink": false,
+    "liveDev": true,
     "dialects": [
       "esm"
     ],
@@ -13,19 +19,19 @@
     }
   },
   "devDependencies": {
-    "@eslint/js": "^9.8.0",
-    "@types/eslint__js": "^8.42.3",
-    "@types/node": "^22.4.1",
-    "eslint": "^9.8.0",
-    "prettier": "^3.3.2",
-    "tap": "^21.0.1",
+    "@eslint/js": "^9.25.0",
+    "@types/node": "^22.14.1",
+    "eslint": "^9.25.0",
+    "prettier": "^3.5.3",
+    "tap": "^21.1.0",
     "tshy": "^3.0.2",
-    "typescript": "^5.5.4",
-    "typescript-eslint": "^8.0.1"
+    "typedoc": "~0.27.6",
+    "typescript": "5.7.3",
+    "typescript-eslint": "^8.30.1"
   },
   "license": "BSD-2-Clause-Patent",
   "engines": {
-    "node": "20 || >=22"
+    "node": ">=22"
   },
   "tap": {
     "extends": "../../tap-config.yaml"
@@ -50,9 +56,9 @@
     "format:check": "prettier --check . --ignore-path ../../.prettierignore --cache",
     "lint": "eslint . --fix",
     "lint:check": "eslint .",
-    "presnap": "tshy",
     "snap": "tap",
-    "pretest": "tshy",
-    "test": "tap"
+    "test": "tap",
+    "posttest": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
   }
 }