@alextheman/utility 5.12.0 → 5.13.0

package/dist/internal/index.d.cts

@@ -1,19 +1,92 @@
 import { ExecaMethod } from "execa";
 
-//#region src/root/functions/miscellaneous/sayHello.d.ts
+//#region src/root/types/CreateEnumType.d.ts
 /**
- * Returns a string representing the lyrics to the package's theme song, Commit To You
+ * Get the value types from a const object so the object can behave similarly to an enum.
  *
- * [Pls listen!](https://www.youtube.com/watch?v=mH-Sg-8EnxM)
+ * @category Types
  *
- * @returns The lyrics string in markdown format.
+ * @template ObjectType - The type of the object to get the value types for.
  */
-declare function sayHello(): string;
+type CreateEnumType<ObjectType extends Record<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
+//#endregion
+//#region src/root/types/IsTypeArgumentString.d.ts
+type IsTypeArgumentString<Argument extends string> = Argument;
+//#endregion
+//#region src/root/types/NullableOnCondition.d.ts
+/**
+ * Resolves to the given type if the first type is `true`, otherwise resolves to `null`
+ *
+ * @category Types
+ *
+ * @param Condition - The condition to check.
+ * @param ResolvedTypeIfTrue - The type to resolve to if the condition may be `true`.
+ */
+type NullableOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | null;
+//#endregion
+//#region src/v6/CodeError.d.ts
+interface ExpectErrorOptions$1<ErrorCode extends string = string> {
+  expectedCode?: ErrorCode;
+}
+/**
+ * Represents errors that can be described using a standardised error code, and a human-readable error message.
+ *
+ * @category Types
+ *
+ * @template ErrorCode The type of the standardised error code.
+ */
+declare class CodeError<ErrorCode extends string = string> extends Error {
+  code: ErrorCode;
+  /**
+   * @param code - A standardised code (e.g. UNEXPECTED_DATA).
+   * @param message  - A human-readable error message (e.g. The data provided is invalid).
+   * @param options - Extra options to pass to super Error constructor.
+   */
+  constructor(code: ErrorCode, message?: string, options?: ErrorOptions);
+  /**
+   * Checks whether the given input may have been caused by a CodeError.
+   *
+   * @param input - The input to check.
+   *
+   * @returns `true` if the input is a CodeError, and `false` otherwise. The type of the input will also be narrowed down to CodeError if `true`.
+   */
+  static check(input: unknown): input is CodeError<string>;
+  protected static checkCaughtError<ErrorCode extends string = string>(this: typeof CodeError, error: unknown, options?: ExpectErrorOptions$1<ErrorCode>): CodeError;
+  /**
+   * Gets the thrown `CodeError` from a given function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
+   *
+   * @param errorFunction - The function expected to throw the error.
+   * @param options - Extra options to apply.
+   *
+   * @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+   * @throws {Error} If no `CodeError` was thrown by the `errorFunction`
+   *
+   * @returns The `CodeError` that was thrown by the `errorFunction`
+   */
+  static expectError<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => unknown, options?: ExpectErrorOptions$1<ErrorCode>): CodeError;
+  /**
+   * Gets the thrown `CodeError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
+   *
+   * @param errorFunction - The function expected to throw the error.
+   * @param options - Extra options to apply.
+   *
+   * @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+   * @throws {Error} If no `CodeError` was thrown by the `errorFunction`
+   *
+   * @returns The `CodeError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions$1<ErrorCode>): Promise<CodeError>;
+}
 //#endregion
-//#region src/root/types/DataError.d.ts
-interface ExpectErrorOptions {
-  expectedCode?: string;
+//#region src/v6/DataError.d.ts
+type DefaultDataErrorCode = "INVALID_DATA";
+interface ExpectErrorOptions<ErrorCode extends string = DefaultDataErrorCode> {
+  expectedCode?: ErrorCode | DefaultDataErrorCode;
 }
+declare const DataErrorCode: {
+  readonly INVALID_DATA: "INVALID_DATA";
+};
+type DataErrorCode = CreateEnumType<typeof DataErrorCode>;
 /**
  * Represents errors you may get that may've been caused by a specific piece of data.
  *
@@ -21,8 +94,7 @@ interface ExpectErrorOptions {
  *
  * @template DataType - The type of the data that caused the error.
  */
-declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<PropertyKey, unknown>> extends Error {
-  code: string;
+declare class DataError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode> extends CodeError<ErrorCode | DataErrorCode> {
   data: DataType;
   /**
    * @param data - The data that caused the error.
@@ -30,8 +102,7 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    * @param message  - A human-readable error message (e.g. The data provided is invalid).
    * @param options - Extra options to pass to super Error constructor.
    */
-  constructor(data: DataType, code?: string, message?: string, options?: ErrorOptions);
-  private static checkCaughtError;
+  constructor(data: DataType, code?: ErrorCode | DefaultDataErrorCode, message?: string, options?: ErrorOptions);
   /**
    * Checks whether the given input may have been caused by a DataError.
    *
@@ -39,7 +110,7 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    *
    * @returns `true` if the input is a DataError, and `false` otherwise. The type of the input will also be narrowed down to DataError if `true`.
    */
-  static check<DataType extends Record<PropertyKey, unknown> = Record<PropertyKey, unknown>>(input: unknown): input is DataError<DataType>;
+  static check<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode>(input: unknown): input is DataError<DataType, ErrorCode>;
   /**
    * Gets the thrown `DataError` from a given function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
    *
@@ -51,7 +122,7 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    *
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
-  static expectError(errorFunction: () => unknown, options?: ExpectErrorOptions): DataError;
+  static expectError<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): DataError<DataType, ErrorCode>;
   /**
    * Gets the thrown `DataError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
    *
@@ -63,33 +134,9 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    *
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
-  static expectErrorAsync(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions): Promise<DataError>;
+  static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError<DataType, ErrorCode>>;
 }
 //#endregion
-//#region src/root/types/CreateEnumType.d.ts
-/**
- * Get the value types from a const object so the object can behave similarly to an enum.
- *
- * @category Types
- *
- * @template ObjectType - The type of the object to get the value types for.
- */
-type CreateEnumType<ObjectType extends Record<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
-//#endregion
-//#region src/root/types/IsTypeArgumentString.d.ts
-type IsTypeArgumentString<Argument extends string> = Argument;
-//#endregion
-//#region src/root/types/NullableOnCondition.d.ts
-/**
- * Resolves to the given type if the first type is `true`, otherwise resolves to `null`
- *
- * @category Types
- *
- * @param Condition - The condition to check.
- * @param ResolvedTypeIfTrue - The type to resolve to if the condition may be `true`.
- */
-type NullableOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | null;
-//#endregion
 //#region src/internal/DependencyGroup.d.ts
 declare const DependencyGroup: {
   readonly DEPENDENCIES: "dependencies";
@@ -131,7 +178,10 @@ declare const ModuleType: {
 type ModuleType = CreateEnumType<typeof ModuleType>;
 //#endregion
 //#region src/internal/packageJsonNotFoundError.d.ts
-declare function packageJsonNotFoundError(packagePath: string): DataError;
+interface PackageJsonNotFoundErrorPayload {
+  packagePath: string;
+}
+declare function packageJsonNotFoundError(packagePath: string): DataError<PackageJsonNotFoundErrorPayload, "PACKAGE_JSON_NOT_FOUND">;
 //#endregion
 //#region src/internal/PackageManager.d.ts
 declare const PackageManager: {
@@ -143,6 +193,16 @@ type PackageManager = CreateEnumType<typeof PackageManager>;
 //#region src/internal/parseJsonFromStdout.d.ts
 declare function parseJsonFromStdout(stdout: string): Record<string, unknown>;
 //#endregion
+//#region src/internal/sayHello.d.ts
+/**
+ * Returns a string representing the lyrics to the package's theme song, Commit To You
+ *
+ * [Pls listen!](https://www.youtube.com/watch?v=mH-Sg-8EnxM)
+ *
+ * @returns The lyrics string in markdown format.
+ */
+declare function sayHello(): string;
+//#endregion
 //#region src/internal/setupPackageEndToEnd.d.ts
 interface SetupPackageEndToEndOptions {
   dependencyGroup?: DependencyGroup;
@@ -152,4 +212,4 @@ declare function setupPackageEndToEnd(temporaryPath: string, packageManager: Pac
   cwd: string;
 }>>;
 //#endregion
-export { DependencyGroup, type IsTypeArgumentString, ModuleType, PackageManager, getDependenciesFromGroup, getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, packageJsonNotFoundError, parseJsonFromStdout, sayHello, setupPackageEndToEnd };
+export { DependencyGroup, type IsTypeArgumentString, ModuleType, type PackageJsonNotFoundErrorPayload, PackageManager, getDependenciesFromGroup, getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, packageJsonNotFoundError, parseJsonFromStdout, sayHello, setupPackageEndToEnd };

package/dist/internal/index.d.ts

@@ -1,19 +1,92 @@
 import z from "zod";
 import { ExecaMethod } from "execa";
-//#region src/root/functions/miscellaneous/sayHello.d.ts
+//#region src/root/types/CreateEnumType.d.ts
 /**
- * Returns a string representing the lyrics to the package's theme song, Commit To You
+ * Get the value types from a const object so the object can behave similarly to an enum.
  *
- * [Pls listen!](https://www.youtube.com/watch?v=mH-Sg-8EnxM)
+ * @category Types
  *
- * @returns The lyrics string in markdown format.
+ * @template ObjectType - The type of the object to get the value types for.
  */
-declare function sayHello(): string;
+type CreateEnumType<ObjectType extends Record<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
+//#endregion
+//#region src/root/types/IsTypeArgumentString.d.ts
+type IsTypeArgumentString<Argument extends string> = Argument;
+//#endregion
+//#region src/root/types/NullableOnCondition.d.ts
+/**
+ * Resolves to the given type if the first type is `true`, otherwise resolves to `null`
+ *
+ * @category Types
+ *
+ * @param Condition - The condition to check.
+ * @param ResolvedTypeIfTrue - The type to resolve to if the condition may be `true`.
+ */
+type NullableOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | null;
+//#endregion
+//#region src/v6/CodeError.d.ts
+interface ExpectErrorOptions$1<ErrorCode extends string = string> {
+  expectedCode?: ErrorCode;
+}
+/**
+ * Represents errors that can be described using a standardised error code, and a human-readable error message.
+ *
+ * @category Types
+ *
+ * @template ErrorCode The type of the standardised error code.
+ */
+declare class CodeError<ErrorCode extends string = string> extends Error {
+  code: ErrorCode;
+  /**
+   * @param code - A standardised code (e.g. UNEXPECTED_DATA).
+   * @param message  - A human-readable error message (e.g. The data provided is invalid).
+   * @param options - Extra options to pass to super Error constructor.
+   */
+  constructor(code: ErrorCode, message?: string, options?: ErrorOptions);
+  /**
+   * Checks whether the given input may have been caused by a CodeError.
+   *
+   * @param input - The input to check.
+   *
+   * @returns `true` if the input is a CodeError, and `false` otherwise. The type of the input will also be narrowed down to CodeError if `true`.
+   */
+  static check(input: unknown): input is CodeError<string>;
+  protected static checkCaughtError<ErrorCode extends string = string>(this: typeof CodeError, error: unknown, options?: ExpectErrorOptions$1<ErrorCode>): CodeError;
+  /**
+   * Gets the thrown `CodeError` from a given function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
+   *
+   * @param errorFunction - The function expected to throw the error.
+   * @param options - Extra options to apply.
+   *
+   * @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+   * @throws {Error} If no `CodeError` was thrown by the `errorFunction`
+   *
+   * @returns The `CodeError` that was thrown by the `errorFunction`
+   */
+  static expectError<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => unknown, options?: ExpectErrorOptions$1<ErrorCode>): CodeError;
+  /**
+   * Gets the thrown `CodeError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `CodeError` if no error thrown.
+   *
+   * @param errorFunction - The function expected to throw the error.
+   * @param options - Extra options to apply.
+   *
+   * @throws {Error} Any other errors thrown by the `errorFunction` that are not a `CodeError`.
+   * @throws {Error} If no `CodeError` was thrown by the `errorFunction`
+   *
+   * @returns The `CodeError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions$1<ErrorCode>): Promise<CodeError>;
+}
 //#endregion
-//#region src/root/types/DataError.d.ts
-interface ExpectErrorOptions {
-  expectedCode?: string;
+//#region src/v6/DataError.d.ts
+type DefaultDataErrorCode = "INVALID_DATA";
+interface ExpectErrorOptions<ErrorCode extends string = DefaultDataErrorCode> {
+  expectedCode?: ErrorCode | DefaultDataErrorCode;
 }
+declare const DataErrorCode: {
+  readonly INVALID_DATA: "INVALID_DATA";
+};
+type DataErrorCode = CreateEnumType<typeof DataErrorCode>;
 /**
  * Represents errors you may get that may've been caused by a specific piece of data.
  *
@@ -21,8 +94,7 @@ interface ExpectErrorOptions {
  *
  * @template DataType - The type of the data that caused the error.
  */
-declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<PropertyKey, unknown>> extends Error {
-  code: string;
+declare class DataError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode> extends CodeError<ErrorCode | DataErrorCode> {
   data: DataType;
   /**
    * @param data - The data that caused the error.
@@ -30,8 +102,7 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    * @param message  - A human-readable error message (e.g. The data provided is invalid).
    * @param options - Extra options to pass to super Error constructor.
    */
-  constructor(data: DataType, code?: string, message?: string, options?: ErrorOptions);
-  private static checkCaughtError;
+  constructor(data: DataType, code?: ErrorCode | DefaultDataErrorCode, message?: string, options?: ErrorOptions);
   /**
    * Checks whether the given input may have been caused by a DataError.
    *
@@ -39,7 +110,7 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    *
    * @returns `true` if the input is a DataError, and `false` otherwise. The type of the input will also be narrowed down to DataError if `true`.
    */
-  static check<DataType extends Record<PropertyKey, unknown> = Record<PropertyKey, unknown>>(input: unknown): input is DataError<DataType>;
+  static check<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode>(input: unknown): input is DataError<DataType, ErrorCode>;
   /**
    * Gets the thrown `DataError` from a given function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
    *
@@ -51,7 +122,7 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    *
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
-  static expectError(errorFunction: () => unknown, options?: ExpectErrorOptions): DataError;
+  static expectError<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): DataError<DataType, ErrorCode>;
   /**
    * Gets the thrown `DataError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `DataError` if no error thrown.
    *
@@ -63,33 +134,9 @@ declare class DataError<DataType extends Record<PropertyKey, unknown> = Record<P
    *
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
-  static expectErrorAsync(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions): Promise<DataError>;
+  static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError<DataType, ErrorCode>>;
 }
 //#endregion
-//#region src/root/types/CreateEnumType.d.ts
-/**
- * Get the value types from a const object so the object can behave similarly to an enum.
- *
- * @category Types
- *
- * @template ObjectType - The type of the object to get the value types for.
- */
-type CreateEnumType<ObjectType extends Record<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
-//#endregion
-//#region src/root/types/IsTypeArgumentString.d.ts
-type IsTypeArgumentString<Argument extends string> = Argument;
-//#endregion
-//#region src/root/types/NullableOnCondition.d.ts
-/**
- * Resolves to the given type if the first type is `true`, otherwise resolves to `null`
- *
- * @category Types
- *
- * @param Condition - The condition to check.
- * @param ResolvedTypeIfTrue - The type to resolve to if the condition may be `true`.
- */
-type NullableOnCondition<Condition extends boolean, ResolvedTypeIfTrue> = Condition extends true ? ResolvedTypeIfTrue : ResolvedTypeIfTrue | null;
-//#endregion
 //#region src/internal/DependencyGroup.d.ts
 declare const DependencyGroup: {
   readonly DEPENDENCIES: "dependencies";
@@ -131,7 +178,10 @@ declare const ModuleType: {
 type ModuleType = CreateEnumType<typeof ModuleType>;
 //#endregion
 //#region src/internal/packageJsonNotFoundError.d.ts
-declare function packageJsonNotFoundError(packagePath: string): DataError;
+interface PackageJsonNotFoundErrorPayload {
+  packagePath: string;
+}
+declare function packageJsonNotFoundError(packagePath: string): DataError<PackageJsonNotFoundErrorPayload, "PACKAGE_JSON_NOT_FOUND">;
 //#endregion
 //#region src/internal/PackageManager.d.ts
 declare const PackageManager: {
@@ -143,6 +193,16 @@ type PackageManager = CreateEnumType<typeof PackageManager>;
 //#region src/internal/parseJsonFromStdout.d.ts
 declare function parseJsonFromStdout(stdout: string): Record<string, unknown>;
 //#endregion
+//#region src/internal/sayHello.d.ts
+/**
+ * Returns a string representing the lyrics to the package's theme song, Commit To You
+ *
+ * [Pls listen!](https://www.youtube.com/watch?v=mH-Sg-8EnxM)
+ *
+ * @returns The lyrics string in markdown format.
+ */
+declare function sayHello(): string;
+//#endregion
 //#region src/internal/setupPackageEndToEnd.d.ts
 interface SetupPackageEndToEndOptions {
   dependencyGroup?: DependencyGroup;
@@ -152,4 +212,4 @@ declare function setupPackageEndToEnd(temporaryPath: string, packageManager: Pac
   cwd: string;
 }>>;
 //#endregion
-export { DependencyGroup, type IsTypeArgumentString, ModuleType, PackageManager, getDependenciesFromGroup, getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, packageJsonNotFoundError, parseJsonFromStdout, sayHello, setupPackageEndToEnd };
+export { DependencyGroup, type IsTypeArgumentString, ModuleType, type PackageJsonNotFoundErrorPayload, PackageManager, getDependenciesFromGroup, getExpectedTgzName, getPackageJsonContents, getPackageJsonPath, packageJsonNotFoundError, parseJsonFromStdout, sayHello, setupPackageEndToEnd };