@alextheman/utility 5.13.1 → 5.14.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { DotenvParseOutput } from "dotenv";
-import z$1, { ZodError, ZodType, z } from "zod";
+import z, { ZodCoercedDate, ZodCoercedNumber, ZodError, ZodType, z as z$1 } from "zod";
 
 //#region src/root/constants/FILE_PATH_REGEX.d.ts
 declare const FILE_PATH_PATTERN: string;
@@ -626,7 +626,7 @@ declare class VersionNumber {
    */
   toString(): string;
 }
-declare const zodVersionNumber: z$1.ZodType<VersionNumber>;
+declare const zodVersionNumber: z.ZodType<VersionNumber>;
 //#endregion
 //#region src/root/types/ArrayElement.d.ts
 /**
@@ -806,159 +806,6 @@ type VersionType = CreateEnumType<typeof VersionType>;
  */
 declare function parseVersionType(input: unknown): VersionType;
 //#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/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.
- *
- * @category Types
- *
- * @template DataType - The type of the data that caused the error.
- */
-declare class DataError$1<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode> extends CodeError<ErrorCode | DataErrorCode> {
-  data: DataType;
-  /**
-   * @param data - The data that caused the error.
-   * @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(data: DataType, code?: ErrorCode | DefaultDataErrorCode, message?: string, options?: ErrorOptions);
-  /**
-   * Checks whether the given input may have been caused by a DataError.
-   *
-   * @param input - The input to check.
-   *
-   * @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 object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode>(input: unknown): input is DataError$1<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.
-   *
-   * @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 `DataError`.
-   * @throws {Error} If no `DataError` was thrown by the `errorFunction`
-   *
-   * @returns The `DataError` that was thrown by the `errorFunction`
-   */
-  static expectError<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): DataError$1<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.
-   *
-   * @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 `DataError`.
-   * @throws {Error} If no `DataError` was thrown by the `errorFunction`
-   *
-   * @returns The `DataError` that was thrown by the `errorFunction`
-   */
-  static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError$1<DataType, ErrorCode>>;
-}
-//#endregion
-//#region src/root/functions/parsers/zod/parseZodSchema.d.ts
-/**
- * An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
- *
- * NOTE: Use `parseZodSchemaAsync` if your schema includes an asynchronous function.
- *
- * @category Parsers
- *
- * @template SchemaType - The Zod schema type.
- * @template ErrorType - The type of error to throw on invalid data.
- *
- * @param schema - The Zod schema to use in parsing.
- * @param input - The data to parse.
- * @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
- *
- * @throws {DataErrorCode} If the given data cannot be parsed according to the schema.
- *
- * @returns The parsed data from the Zod schema.
- */
-declare function parseZodSchema<SchemaType extends ZodType, ErrorType extends Error = DataError$1>(schema: SchemaType, input: unknown, onError?: ErrorType | ((zodError: ZodError) => ErrorType | void)): z.infer<SchemaType>;
-//#endregion
-//#region src/root/functions/parsers/zod/parseZodSchemaAsync.d.ts
-/**
- * An alternative function to zodSchema.parseAsync() that can be used to strictly parse asynchronous Zod schemas.
- *
- * @category Parsers
- *
- * @template SchemaType - The Zod schema type.
- * @template ErrorType - The type of error to throw on invalid data.
- *
- * @param schema - The Zod schema to use in parsing.
- * @param input - The data to parse.
- * @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
- *
- * @throws {DataError} If the given data cannot be parsed according to the schema.
- *
- * @returns The parsed data from the Zod schema.
- */
-declare function parseZodSchemaAsync<SchemaType extends ZodType, ErrorType extends Error = DataError$1>(schema: SchemaType, input: unknown, onError?: ErrorType | ((zodError: ZodError) => ErrorType | void)): Promise<z.infer<SchemaType>>;
-//#endregion
 //#region src/root/functions/recursive/deepCopy.d.ts
 /**
  * Deeply copies an object or array such that all child objects/arrays are also copied.
@@ -1264,4 +1111,176 @@ declare function normaliseIndents(strings: TemplateStringsArray, ...interpolatio
  */
 declare const normalizeIndents: typeof normaliseIndents;
 //#endregion
-export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, type StringListToArrayOptions, ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };
+//#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/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.
+ *
+ * @category Types
+ *
+ * @template DataType - The type of the data that caused the error.
+ */
+declare class DataError$1<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode> extends CodeError<ErrorCode | DataErrorCode> {
+  data: DataType;
+  /**
+   * @param data - The data that caused the error.
+   * @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(data: DataType, code?: ErrorCode | DefaultDataErrorCode, message?: string, options?: ErrorOptions);
+  /**
+   * Checks whether the given input may have been caused by a DataError.
+   *
+   * @param input - The input to check.
+   *
+   * @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 object = Record<PropertyKey, unknown>, ErrorCode extends string = DataErrorCode>(input: unknown): input is DataError$1<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.
+   *
+   * @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 `DataError`.
+   * @throws {Error} If no `DataError` was thrown by the `errorFunction`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectError<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): DataError$1<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.
+   *
+   * @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 `DataError`.
+   * @throws {Error} If no `DataError` was thrown by the `errorFunction`
+   *
+   * @returns The `DataError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = DefaultDataErrorCode>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError$1<DataType, ErrorCode>>;
+}
+//#endregion
+//#region src/root/zod/parseZodSchema.d.ts
+/**
+ * An alternative function to zodSchema.parse() that can be used to strictly parse Zod schemas.
+ *
+ * NOTE: Use `parseZodSchemaAsync` if your schema includes an asynchronous function.
+ *
+ * @category Parsers
+ *
+ * @deprecated Please use `az.with(schema).parse(input)` instead.
+ *
+ * @template SchemaType - The Zod schema type.
+ * @template ErrorType - The type of error to throw on invalid data.
+ *
+ * @param schema - The Zod schema to use in parsing.
+ * @param input - The data to parse.
+ * @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
+ *
+ * @throws {DataErrorCode} If the given data cannot be parsed according to the schema.
+ *
+ * @returns The parsed data from the Zod schema.
+ */
+declare function parseZodSchema<SchemaType extends ZodType, ErrorType extends Error = DataError$1>(schema: SchemaType, input: unknown, onError?: ErrorType | ((zodError: ZodError) => ErrorType | void)): z$1.infer<SchemaType>;
+//#endregion
+//#region src/root/zod/parseZodSchemaAsync.d.ts
+/**
+ * An alternative function to zodSchema.parseAsync() that can be used to strictly parse asynchronous Zod schemas.
+ *
+ * @category Parsers
+ *
+ * @deprecated Please use `az.with(schema).parseAsync(input)` instead.
+ *
+ * @template SchemaType - The Zod schema type.
+ * @template ErrorType - The type of error to throw on invalid data.
+ *
+ * @param schema - The Zod schema to use in parsing.
+ * @param input - The data to parse.
+ * @param onError - A custom error to throw on invalid data (defaults to `DataError`). May either be the error itself, or a function that returns the error or nothing. If nothing is returned, the default error is thrown instead.
+ *
+ * @throws {DataError} If the given data cannot be parsed according to the schema.
+ *
+ * @returns The parsed data from the Zod schema.
+ */
+declare function parseZodSchemaAsync<SchemaType extends ZodType, ErrorType extends Error = DataError$1>(schema: SchemaType, input: unknown, onError?: ErrorType | ((zodError: ZodError) => ErrorType | void)): Promise<z$1.infer<SchemaType>>;
+//#endregion
+//#region src/root/zod/zodFieldWrapper.d.ts
+declare function zodFieldWrapper<SchemaType extends ZodType<unknown, string | null>>(schema: SchemaType): ZodType<z.infer<SchemaType>, string>;
+//#endregion
+//#region src/root/zod/az.d.ts
+declare const az: {
+  field: typeof zodFieldWrapper;
+  fieldNumber: () => ZodCoercedNumber<string | null>;
+  versionNumber: () => ZodType<VersionNumber, unknown>;
+  fieldDate: () => ZodCoercedDate<string | null>;
+  with: <SchemaType extends ZodType>(schema: SchemaType) => {
+    parse: <ErrorType extends Error = DataError$1<Record<PropertyKey, unknown>, "INVALID_DATA">>(input: unknown, error?: ErrorType | ((zodError: z.ZodError<unknown>) => void | ErrorType)) => ReturnType<typeof parseZodSchema<SchemaType, ErrorType>>;
+    parseAsync: <ErrorType extends Error = DataError$1<Record<PropertyKey, unknown>, "INVALID_DATA">>(input: unknown, error?: ErrorType | ((zodError: z.ZodError<unknown>) => void | ErrorType)) => ReturnType<typeof parseZodSchemaAsync<SchemaType, ErrorType>>;
+  };
+};
+//#endregion
+export { APIError, type ArrayElement, type CallReturnType, CamelToKebabOptions, type CreateEnumType, type CreateFormDataOptions, type CreateFormDataOptionsNullableResolution, type CreateFormDataOptionsUndefinedOrNullResolution, DataError, type DisallowUndefined, Env, FILE_PATH_PATTERN, FILE_PATH_REGEX, type FormDataArrayResolutionStrategy, type FormDataNullableResolutionStrategy, type HTTPErrorCode, type IgnoreCase, type IsTypeArgumentString, KebabToCamelOptions, type NonUndefined, NormaliseIndentsFunction, NormaliseIndentsOptions, NormalizeIndentsFunction, NormalizeIndentsOptions, type NullableOnCondition, ONE_DAY_IN_MILLISECONDS, type OptionalOnCondition, ParallelTuple, RecordKey, RemoveUndefined, type StringListToArrayOptions, ToTitleCaseOptions, UUID_PATTERN, UUID_REGEX, VERSION_NUMBER_PATTERN, VERSION_NUMBER_REGEX, VersionNumber, type FormatOptionsBase as VersionNumberToStringOptions, VersionType, addDaysToDate, appendSemicolon, az, calculateMonthlyDifference, camelToKebab, convertFileToBase64, createFormData, createTemplateStringsArray, deepCopy, deepFreeze, escapeRegexPattern, fillArray, formatDateAndTime, getRandomNumber, getRecordKeys, getStringsAndInterpolations, httpErrorCodeLookup, interpolate, interpolateObjects, isAnniversary, isLeapYear, isMonthlyMultiple, isOrdered, isSameDate, isTemplateStringsArray, kebabToCamel, normaliseIndents, normalizeIndents, omitProperties, paralleliseArrays, parseBoolean, parseEnv, parseFormData, parseIntStrict, parseUUID, parseVersionType, parseZodSchema, parseZodSchemaAsync, randomiseArray, range, removeDuplicates, removeUndefinedFromObject, sayHello, stringListToArray, stringifyDotenv, toTitleCase, truncate, wait, zodVersionNumber };