@vltpkg/error-cause 0.0.0-0.1730239248325

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) vlt technology, Inc.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+   Subject to the terms and conditions of this license, each copyright holder and contributor hereby grants to those receiving rights under this license a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except for failure to satisfy the conditions of this license) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer this software, where such license applies only to those patent claims, already acquired or hereafter acquired, licensable by such copyright holder or contributor that are necessarily infringed by:
+
+(a) their Contribution(s) (the licensed copyrights of copyright holders and non-copyrightable additions of contributors, in source or binary form) alone; or
+(b) combination of their Contribution(s) with the work of authorship to which such Contribution(s) was added by such copyright holder or contributor, if, at the time the Contribution is added, such addition causes such combination to be necessarily infringed. The patent license shall not apply to any other combinations which include the Contribution.
+Except as expressly stated above, no rights or licenses from any copyright holder or contributor is granted under this license, whether expressly, by implication, estoppel or otherwise.
+
+DISCLAIMER
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,353 @@
+# `@vltpkg/error-cause`
+
+Utility functions for `Error` creation to help enforce vlt's
+`Error.cause` conventions.
+
+## USAGE
+
+```js
+import { error, typeError } from '@vltpkg/error-cause'
+
+// create an error when a lower-level thing fails
+try {
+  doSomethign()
+} catch (er) {
+  throw error('The something for the whatever failed', er)
+}
+
+// create an error with some extra information
+if (!thing.valid) {
+  throw error('the thing is not valid', {
+    code: 'EINVAL',
+    found: thing,
+  })
+}
+
+// create an error from a lower-level error with extra info
+try {
+  doSomethign(thing)
+} catch (er) {
+  throw error('the thing is not valid', {
+    code: 'EINVAL',
+    found: thing,
+    cause: er,
+  })
+}
+
+// create an error and prune some stack frames
+// use this when we want to report the location of a
+// function call, not its internals.
+const checkBar = () => {
+  if (!bar) {
+    // will report from the checkBar() call, not here.
+    throw error('no bar', { found: bar, wanted: true }, 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.
+
+## 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.
+
+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.
+
+## 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.
+- 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.
+
+## 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.
+
+## Conventions
+
+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
+  `{ 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.
+
+### 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:
+
+```
+let data
+try {
+  data = await readFile(someFile)
+} catch (er) {
+  throw new Error('could not read some file!')
+}
+```
+
+this is preferred:
+
+```js
+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`.
+
+```js
+let data
+try {
+  data = await readFile(someFile, 'utf8')
+} catch (er) {
+  // adds semantic information about what the file was for
+  throw error('The lock file was not found', er)
+}
+```
+
+### 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:
+
+```js
+let data
+try {
+  data = await readFile(someFile, 'utf8')
+} catch (er) {
+  throw error(`could not resolve '${name}'`, {
+    // extra data about the situation
+    // it's ok to put big noisy objects in here, not on the error
+    // object itself!
+    name,
+    spec,
+    target,
+    // original error that was thrown
+    cause: er,
+  })
+}
+```
+
+### Always set `cause`, even if no prior error.
+
+Instead of this:
+
+```
+throw Object.assign(new Error('could not resolve'), {
+  code: 'ERESOLVE',
+  from,
+  spec,
+  registry,
+})
+```
+
+Do this instead:
+
+```js
+throw error('could not resolve', {
+  code: 'ERESOLVE',
+  from,
+  spec,
+  registry,
+})
+```
+
+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.
+
+For example, the `@vltpkg/which` module raises an error that is
+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 such cases, this is fine:
+
+```js
+// identical to the error thrown by node's fs
+throw Object.assign(new Error('not found'), {
+  path: someFile,
+  code: 'ENOENT',
+})
+```
+
+But this is way out of bounds and makes no sense:
+
+```
+throw Object.assign(new Error('could not resolve'), {
+  code: 'EPERM',
+  spec,
+  config: someHugeConfigObjectOrSomething,
+})
+```
+
+**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:
+
+```
+let data
+try {
+  data = await readFile(lockFile, 'utf8')
+} catch (er) {
+  throw error('lockfile not found', {
+    code: er.code,
+    path: er.path,
+  })
+}
+```
+
+Instead, do this:
+
+```js
+let data
+try {
+  data = await readFile(lockFile, 'utf8')
+} catch (er) {
+  throw new Error('lockfile not found', { cause: er })
+}
+```
+
+### 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.
+
+Ie, do not do this:
+
+```
+class VersionError extends Error {
+  version?: Version
+  constructor(version: Version | string) {
+    super('Could not version')
+    this.version = Version.parse(version)
+  }
+}
+// ...
+throw new VersionError(myVersion)
+```
+
+Instead, do this:
+
+```js
+throw error('Could not version', { version })
+```
+
+## `cause` Field Conventions
+
+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.
+- `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`.
+- `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.
+- `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' }`.
+- `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.
+- `max` - A maximum value, which was exceeded.
+- `min` - A minimum value, which was not met.
+- `response` - An HTTP response or
+  `@vltpkg/registry-client.CacheEntry`
+- `url` - A string or URL object
+- `repository` - String git repository remote
+- `version` - string or `@vltpkg/semver.Version`
+- `range` - string or `@vltpkg/semver.Range`
+- `manifest` - `@vltpkg/pick-manifest.Manifest`
+- `packument` - `@vltpkg/pick-manifest.Packument`
+- `cwd` - The current working directory of a process that failed
+
+## Error Types
+
+- 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.
+- 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

@@ -0,0 +1,145 @@
+import type { IncomingMessage } from 'http';
+/**
+ * Codification of vlt's Error.cause conventions
+ *
+ * Add new properties to this list as needed.
+ *
+ * Several of these types are just very basic duck-typing, because referencing
+ * internal types directly would create a workspace dependency cycle.
+ */
+export type ErrorCauseObject = {
+    /**
+     * 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?: ErrorCause;
+    /** the name of something */
+    name?: string;
+    /** byte offset in a Buffer or file */
+    offset?: number;
+    /**
+     * This should only be a string code that we set. See {@link Codes} for
+     * the supported options. Lower-level system codes like `ENOENT` should
+     * remain on the errors that generated them.
+     */
+    code?: Codes;
+    /** target of a file system operation */
+    path?: string;
+    /**
+     * file path origin of a resolution that failed, for example in the case
+     * of `file://` specifiers.
+     */
+    from?: string;
+    /** path on disk that is being written, linked, or extracted to */
+    target?: string;
+    /** Spec object/string relevant to an operation that failed */
+    spec?: string | {
+        type: 'file' | 'git' | 'registry' | 'remote' | 'workspace';
+        spec: string;
+        [k: number | string | symbol]: any;
+    };
+    /** exit code of a process, or HTTP response status code */
+    status?: number | null;
+    /** null or a signal that a process received */
+    signal?: NodeJS.Signals | null;
+    /** the root of a project */
+    projectRoot?: string;
+    /** the current working directory of a process */
+    cwd?: string;
+    /** a command being run in a child process */
+    command?: string;
+    /** the arguments passed to a process */
+    args?: string[];
+    /** standard output from a process */
+    stdout?: Buffer | string | null;
+    /** standard error from a process */
+    stderr?: Buffer | string | null;
+    /**
+     * Array of valid options when something is not a valid option.
+     * (For use in `did you mean X?` output.)
+     */
+    validOptions?: any[];
+    /**
+     * 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;
+    /**
+     * A desired value that was not found, or a regular expression or other
+     * pattern describing it.
+     */
+    wanted?: any;
+    /** actual value, which was not wanted */
+    found?: any;
+    /** HTTP message, fetch.Response, or `@vltpkg/registry-client.CacheEntry` */
+    response?: IncomingMessage | Response | {
+        statusCode: number;
+        headers: Buffer[] | Record<string, string[] | string>;
+        text: () => string;
+        [k: number | string | symbol]: any;
+    };
+    /** string or URL object */
+    url?: URL | string;
+    /** git repository remote or path */
+    repository?: string;
+    /** string or `@vltpkg/semver.Version` object */
+    version?: string | {
+        raw: string;
+        major: number;
+        minor: number;
+        patch: number;
+        [k: number | string | symbol]: any;
+    };
+    /** string or `@vltpkg/semver.Range` object */
+    range?: string | {
+        raw: string;
+        isAny: boolean;
+        includePrerelease: boolean;
+        [k: number | string | symbol]: any;
+    };
+    /** a package manifest, either from `package.json` or a registry */
+    manifest?: DuckTypeManifest;
+    /** registry top-level package document */
+    packument?: {
+        name: string;
+        'dist-tags': Record<string, string>;
+        versions: Record<string, DuckTypeManifest>;
+        time?: Record<string, string>;
+    };
+    /** maximum value, which was exceeded */
+    max?: any;
+    /** minimum value, which was not met */
+    min?: any;
+};
+export type DuckTypeManifest = Record<string, any> & {
+    name?: string;
+    version?: string;
+    deprecated?: string;
+    engines?: Record<string, string>;
+    os?: string[] | string;
+    arch?: string[] | string;
+    dist?: {
+        integrity?: string;
+        shasum?: string;
+        tarball?: string;
+        fileCount?: number;
+        unpackedSize?: number;
+        signatures?: {
+            keyid: string;
+            sig: string;
+        }[];
+    };
+};
+export type ErrorCause = Error | ErrorCauseObject;
+/**
+ * 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';
+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;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/esm/index.js

@@ -0,0 +1,10 @@
+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);
+    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);
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAiMA,MAAM,MAAM,GAAG,CACb,GAAiB,EACjB,WAAgE,EAChE,OAAe,EACf,KAAkB,EAClB,OAEiC,WAAW,EAC5C,EAAE;IACF,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC1D,uEAAuE;IACvE,KAAK,CAAC,iBAAiB,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IACnC,OAAO,EAAE,CAAA;AACX,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,OAAe,EACf,KAAkB,EAClB,IAA0D,EAC1D,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;AAE/C,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,OAAe,EACf,KAAkB,EAClB,IAA0D,EAC1D,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;AAEvD,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,OAAe,EACf,KAAkB,EAClB,IAA0D,EAC1D,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA","sourcesContent":["import type { IncomingMessage } from 'http'\n\n/**\n * Codification of vlt's Error.cause conventions\n *\n * Add new properties to this list as needed.\n *\n * Several of these types are just very basic duck-typing, because referencing\n * internal types directly would create a workspace dependency cycle.\n */\nexport type ErrorCauseObject = {\n  /**\n   * The `cause` field within a `cause` object should\n   * always be an `Error` object that was previously thrown. Note\n   * that the `cause` on an Error itself might _also_ be a\n   * previously thrown error, if no additional information could be\n   * usefully added beyond improving the message.\n   */\n  cause?: ErrorCause\n\n  /** the name of something */\n  name?: string\n\n  /** byte offset in a Buffer or file */\n  offset?: number\n\n  /**\n   * This should only be a string code that we set. See {@link Codes} for\n   * the supported options. Lower-level system codes like `ENOENT` should\n   * remain on the errors that generated them.\n   */\n  code?: Codes\n\n  /** target of a file system operation */\n  path?: string\n\n  /**\n   * file path origin of a resolution that failed, for example in the case\n   * of `file://` specifiers.\n   */\n  from?: string\n\n  /** path on disk that is being written, linked, or extracted to */\n  target?: string\n\n  /** Spec object/string relevant to an operation that failed */\n  spec?:\n    | string\n    | {\n        type: 'file' | 'git' | 'registry' | 'remote' | 'workspace'\n        spec: string\n        [k: number | string | symbol]: any\n      }\n\n  /** exit code of a process, or HTTP response status code */\n  status?: number | null\n\n  /** null or a signal that a process received */\n  signal?: NodeJS.Signals | null\n\n  /** the root of a project */\n  projectRoot?: string\n\n  /** the current working directory of a process */\n  cwd?: string\n\n  /** a command being run in a child process */\n  command?: string\n\n  /** the arguments passed to a process */\n  args?: string[]\n\n  /** standard output from a process */\n  stdout?: Buffer | string | null\n\n  /** standard error from a process */\n  stderr?: Buffer | string | null\n\n  /**\n   * Array of valid options when something is not a valid option.\n   * (For use in `did you mean X?` output.)\n   */\n  validOptions?: any[]\n\n  /**\n   * message indicating what bit of work this might be a part of, what feature\n   * needs to be implemented, etc. Eg, `{ todo: 'nested workspace support' }`.\n   */\n  todo?: string\n\n  /**\n   * A desired value that was not found, or a regular expression or other\n   * pattern describing it.\n   */\n  wanted?: any\n\n  /** actual value, which was not wanted */\n  found?: any\n\n  /** HTTP message, fetch.Response, or `@vltpkg/registry-client.CacheEntry` */\n  response?:\n    | IncomingMessage\n    | Response\n    | {\n        statusCode: number\n        headers: Buffer[] | Record<string, string[] | string>\n        text: () => string\n        [k: number | string | symbol]: any\n      }\n\n  /** string or URL object */\n  url?: URL | string\n\n  /** git repository remote or path */\n  repository?: string\n\n  /** string or `@vltpkg/semver.Version` object */\n  version?:\n    | string\n    | {\n        raw: string\n        major: number\n        minor: number\n        patch: number\n        [k: number | string | symbol]: any\n      }\n\n  /** string or `@vltpkg/semver.Range` object */\n  range?:\n    | string\n    | {\n        raw: string\n        isAny: boolean\n        includePrerelease: boolean\n        [k: number | string | symbol]: any\n      }\n\n  /** a package manifest, either from `package.json` or a registry */\n  manifest?: DuckTypeManifest\n\n  /** registry top-level package document */\n  packument?: {\n    name: string\n    'dist-tags': Record<string, string>\n    versions: Record<string, DuckTypeManifest>\n    time?: Record<string, string>\n  }\n\n  /** maximum value, which was exceeded */\n  max?: any\n\n  /** minimum value, which was not met */\n  min?: any\n}\n\nexport type DuckTypeManifest = Record<string, any> & {\n  name?: string\n  version?: string\n  deprecated?: string\n  engines?: Record<string, string>\n  os?: string[] | string\n  arch?: string[] | string\n  dist?: {\n    integrity?: string\n    shasum?: string\n    tarball?: string\n    fileCount?: number\n    unpackedSize?: number\n    signatures?: {\n      keyid: string\n      sig: string\n    }[]\n  }\n}\n\nexport type ErrorCause = Error | ErrorCauseObject\n\n/**\n * Valid properties for the 'code' field in an Error cause.\n * Add new options to this list as needed.\n */\nexport type Codes =\n  | 'EEXIST'\n  | 'EINTEGRITY'\n  | 'EINVAL'\n  | 'ELIFECYCLE'\n  | 'EMAXREDIRECT'\n  | 'ENEEDAUTH'\n  | 'ENOENT'\n  | 'ENOGIT'\n  | 'ERESOLVE'\n  | 'EUNKNOWN'\n\nconst create = (\n  cls: typeof Error,\n  defaultFrom: ((...a: any[]) => any) | (new (...a: any[]) => any),\n  message: string,\n  cause?: ErrorCause,\n  from:\n    | ((...a: any[]) => any)\n    | (new (...a: any[]) => any) = defaultFrom,\n) => {\n  const er = new cls(message, cause ? { cause } : undefined)\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  Error.captureStackTrace?.(er, from)\n  return er\n}\n\nexport const error = (\n  message: string,\n  cause?: ErrorCause,\n  from?: ((...a: any[]) => any) | (new (...a: any[]) => any),\n) => create(Error, error, message, cause, from)\n\nexport const typeError = (\n  message: string,\n  cause?: ErrorCause,\n  from?: ((...a: any[]) => any) | (new (...a: any[]) => any),\n) => create(TypeError, typeError, message, cause, from)\n\nexport const syntaxError = (\n  message: string,\n  cause?: ErrorCause,\n  from?: ((...a: any[]) => any) | (new (...a: any[]) => any),\n) => create(SyntaxError, syntaxError, message, cause, from)\n"]}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@vltpkg/error-cause",
+  "description": "vlts Error.cause convention",
+  "version": "0.0.0-0.1730239248325",
+  "tshy": {
+    "selfLink": false,
+    "dialects": [
+      "esm"
+    ],
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
+  },
+  "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",
+    "tshy": "^3.0.2",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.0.1"
+  },
+  "license": "BSD-2-Clause-Patent",
+  "engines": {
+    "node": "20 || >=22"
+  },
+  "tap": {
+    "extends": "../../tap-config.yaml"
+  },
+  "prettier": "../../.prettierrc.js",
+  "module": "./dist/esm/index.js",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "format": "prettier --write . --log-level warn --ignore-path ../../.prettierignore --cache",
+    "format:check": "prettier --check . --ignore-path ../../.prettierignore --cache",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "presnap": "tshy",
+    "snap": "tap",
+    "pretest": "tshy",
+    "test": "tap"
+  }
+}