@vltpkg/error-cause 0.0.0-7 → 0.0.0-9

package/dist/esm/index.d.ts

@@ -7,7 +7,7 @@ import type { IncomingHttpHeaders, 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
@@ -17,7 +17,7 @@ export type ErrorCauseObject = {
      * because we use `useUnknownInCatchVariables` so this makes it easier
      * to rethrow a caught error without recasting it.
      */
-    cause?: ErrorCause | unknown;
+    cause?: unknown;
     /** the name of something */
     name?: string;
     /** byte offset in a Buffer or file */
@@ -63,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' }`.
@@ -73,9 +73,9 @@ 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;
@@ -112,9 +112,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;
@@ -135,62 +135,75 @@ export type DuckTypeManifest = Record<string, any> & {
         }[];
     };
 };
-export type ErrorCause = Error | ErrorCauseObject;
 /**
- * An error with a cause that is a direct error cause object and not another
- * nested error.
+ * The input cause for the {@link error} functions. Can either be a plain error
+ * or an error cause options object.
  */
-export type ErrorWithCauseObject = Error & {
-    cause: ErrorCauseObject;
+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;
 };
 /**
- * A TypeError with a cause that is a direct error cause object and not
- * another nested error
+ * An error with a cause property that is an Error.
  */
+export type ErrorWithCauseError<T extends Error = Error> = ErrorWithCause<T, Error>;
 /**
- * If it is any sort of plain-ish object, assume its an error cause
- * because all properties of the cause are optional.
+ * An error with a cause property that is an {@link ErrorCauseResult}.
  */
-export declare const isErrorCauseObject: (v: unknown) => v is ErrorCauseObject;
+export type ErrorWithCauseObject<T extends Error = Error> = ErrorWithCause<T, ErrorCauseResult>;
 /**
- * Type guard for {@link ErrorWithCauseObject} type
+ * 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 isErrorRoot: (er: unknown) => er is ErrorWithCauseObject;
-export declare const asErrorCause: (er: unknown) => ErrorCause;
+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"];
 /**
  * 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 type From = ((...a: any[]) => any) | (new (...a: any[]) => any);
+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: ErrorCauseObject, from?: From): Error & {
-    cause: ErrorCauseObject;
-};
-export declare function error(message: string, cause: Error, from?: From): Error & {
-    cause: Error;
-};
-export declare function error(message: string, cause: ErrorCause, from?: From): Error & {
-    cause: ErrorCause;
-};
+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: ErrorCauseObject, from?: From): TypeError & {
-    cause: ErrorCauseObject;
-};
-export declare function typeError(message: string, cause: Error, from?: From): TypeError & {
-    cause: Error;
-};
-export declare function typeError(message: string, cause: ErrorCause, from?: From): TypeError & {
-    cause: ErrorCause;
-};
+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: ErrorCauseObject, from?: From): SyntaxError & {
-    cause: ErrorCauseObject;
-};
-export declare function syntaxError(message: string, cause: Error, from?: From): SyntaxError & {
-    cause: Error;
-};
-export declare function syntaxError(message: string, cause: ErrorCause, from?: From): SyntaxError & {
-    cause: ErrorCause;
-};
+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,26 +1,60 @@
 /**
- * A TypeError with a cause that is a direct error cause object and not
- * another nested error
+ * 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);
 /**
- * If it is any sort of plain-ish object, assume its an error cause
- * because all properties of the cause are optional.
+ * 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 isErrorCauseObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export const isErrorWithCause = (er) => er instanceof Error && 'cause' in er;
+export const errorCodes = [
+    'EEXIST',
+    'EINTEGRITY',
+    'EINVAL',
+    'ELIFECYCLE',
+    'EMAXREDIRECT',
+    'ENEEDAUTH',
+    'ENOENT',
+    'ENOGIT',
+    'ERESOLVE',
+    'EUNKNOWN',
+    'EUSAGE',
+];
+const errorCodesSet = new Set(errorCodes);
 /**
- * Type guard for {@link ErrorWithCauseObject} type
+ * 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 isErrorRoot = (er) => er instanceof Error && isErrorCauseObject(er.cause);
-export const asErrorCause = (er) => er instanceof Error ? er
-    : isErrorCauseObject(er) ? er
-        // otherwise, make an error of the stringified message
-        : new Error(
-        // eslint-disable-next-line @typescript-eslint/no-base-to-string
-        er == null ? 'Unknown error' : String(er) || 'Unknown error');
+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) {
-    const er = new cls(message, cause ? { cause } : undefined);
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    Error.captureStackTrace?.(er, from);
+    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 function error(message, cause, from) {

package/dist/esm/index.js.map

@@ -1 +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"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAsNA;;;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;CACA,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  /** 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] 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,7 +1,7 @@
 {
   "name": "@vltpkg/error-cause",
   "description": "vlts Error.cause convention",
-  "version": "0.0.0-7",
+  "version": "0.0.0-9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",