@nejs/basic-extensions 2.6.0 → 2.8.0

package/dist/cjs/{newClasses → classes}/iterable.js

@@ -1,16 +1,4 @@
 "use strict";
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _Iterable_elements, _Iterator_mapEach, _Iterator_iterable, _Iterator_iterator;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IteratorExtensions = exports.IterableExtensions = exports.Iterator = exports.Iterable = void 0;
 const extension_1 = require("@nejs/extension");
@@ -21,6 +9,11 @@ const extension_1 = require("@nejs/extension");
  * `for...of` loops and other standard JavaScript iteration mechanisms.
  */
 class Iterable {
+    /**
+     * Private field to store the elements of the iterable.
+     * @private
+     */
+    #elements = [];
     /**
      * Constructs an instance of Iterable. It can be initialized with either an
      * iterable object (such as an array, Set, Map, string, or any object
@@ -36,17 +29,12 @@ class Iterable {
      * not an iterable.
      */
     constructor(elementsOrFirstElement, ...moreElements) {
-        /**
-         * Private field to store the elements of the iterable.
-         * @private
-         */
-        _Iterable_elements.set(this, []);
         if (elementsOrFirstElement != null &&
             typeof elementsOrFirstElement[Symbol.iterator] === 'function') {
-            __classPrivateFieldSet(this, _Iterable_elements, [...elementsOrFirstElement, ...moreElements], "f");
+            this.#elements = [...elementsOrFirstElement, ...moreElements];
         }
         else {
-            __classPrivateFieldSet(this, _Iterable_elements, [elementsOrFirstElement, ...moreElements], "f");
+            this.#elements = [elementsOrFirstElement, ...moreElements];
         }
     }
     /**
@@ -56,8 +44,8 @@ class Iterable {
      *
      * @returns {Generator} A generator that yields each element of the iterable.
      */
-    *[(_Iterable_elements = new WeakMap(), Symbol.iterator)]() {
-        for (const element of __classPrivateFieldGet(this, _Iterable_elements, "f")) {
+    *[Symbol.iterator]() {
+        for (const element of this.#elements) {
             yield element;
         }
     }
@@ -68,7 +56,7 @@ class Iterable {
      * @returns {Array} An array containing all the elements of the iterable.
      */
     get asArray() {
-        return __classPrivateFieldGet(this, _Iterable_elements, "f");
+        return this.#elements;
     }
     /**
      * Ensures that the constructor of this object instance's name
@@ -105,6 +93,13 @@ exports.Iterable = Iterable;
  * `[Symbol.iterator]` property assigned to a generator function.
  */
 class Iterator {
+    /**
+     * A private function that when provided has the following signature:
+     * `function mapEach(entry) -> entry`. This allows any changes to be made
+     * to each element, conditionally and programmatically, as needed before
+     * they are returned to the called code.
+     */
+    #mapEach = undefined;
     /**
      * Creates a new `Iterator` object instance.
      *
@@ -114,43 +109,12 @@ class Iterator {
      * takes an entry as input and receives one as output.
      */
     constructor(iterable, mapEach) {
-        /**
-         * A private function that when provided has the following signature:
-         * `function mapEach(entry) -> entry`. This allows any changes to be made
-         * to each element, conditionally and programmatically, as needed before
-         * they are returned to the called code.
-         */
-        _Iterator_mapEach.set(this, undefined
-        /**
-         * Creates a new `Iterator` object instance.
-         *
-         * @param {object} iterable any object that has a `[Symbol.iterator]`
-         * property assigned to a generator function.
-         * @param {function} mapEach when provided `mapEach` is a callback that
-         * takes an entry as input and receives one as output.
-         */
-        );
-        /**
-         * The object from which its iterator functionality is derived.
-         *
-         * @type {object}
-         * @private
-         */
-        _Iterator_iterable.set(this, null);
-        /**
-         * The results of a call to the iterable's `[Symbol.iterator]`
-         * generator function.
-         *
-         * @type {object}
-         * @private
-         */
-        _Iterator_iterator.set(this, null);
         if (!iterable || !Reflect.has(iterable, Symbol.iterator)) {
             throw new TypeError('Value used to instantiate Iterator is not iterable');
         }
-        __classPrivateFieldSet(this, _Iterator_iterable, iterable, "f");
-        __classPrivateFieldSet(this, _Iterator_iterator, iterable[Symbol.iterator](), "f");
-        __classPrivateFieldSet(this, _Iterator_mapEach, typeof mapEach === 'function' ? mapEach : undefined, "f");
+        this.#iterable = iterable;
+        this.#iterator = iterable[Symbol.iterator]();
+        this.#mapEach = typeof mapEach === 'function' ? mapEach : undefined;
     }
     /**
      * Returns a new `Array` derived from the iterable this object
@@ -160,7 +124,7 @@ class Iterator {
      * iterable. The method is generated from `Array.from()`
      */
     get asArray() {
-        return Array.from(__classPrivateFieldGet(this, _Iterator_iterable, "f"));
+        return Array.from(this.#iterable);
     }
     /**
      * Returns the actual iterable object passed to the constructor that
@@ -169,7 +133,7 @@ class Iterator {
      * @returns {object} the object containing the `[Symbol.iterator]`
      */
     get iterable() {
-        return __classPrivateFieldGet(this, _Iterator_iterable, "f");
+        return this.#iterable;
     }
     /**
      * The function retrieves the next value in the iterator. If the
@@ -179,14 +143,14 @@ class Iterator {
      * @returns {any} the next value
      */
     next() {
-        const input = __classPrivateFieldGet(this, _Iterator_iterator, "f").next();
+        const input = this.#iterator.next();
         let output = input;
         if (output.done) {
             return { value: undefined, done: true };
         }
         else {
-            if (__classPrivateFieldGet(this, _Iterator_mapEach, "f") && typeof __classPrivateFieldGet(this, _Iterator_mapEach, "f") === 'function') {
-                output.value = __classPrivateFieldGet(this, _Iterator_mapEach, "f").call(this, input.value);
+            if (this.#mapEach && typeof this.#mapEach === 'function') {
+                output.value = this.#mapEach(input.value);
             }
             return { value: output.value, done: false };
         }
@@ -196,7 +160,7 @@ class Iterator {
      * iterated over again.
      */
     reset() {
-        __classPrivateFieldSet(this, _Iterator_iterator, __classPrivateFieldGet(this, _Iterator_iterable, "f")[Symbol.iterator](), "f");
+        this.#iterator = this.#iterable[Symbol.iterator]();
     }
     /**
      * The existence of this symbol on the object instances, indicates that
@@ -206,7 +170,7 @@ class Iterator {
      * @returns {Iterator} this is returned since this object is already
      * conforming to the expected JavaScript Iterator interface
      */
-    [(_Iterator_mapEach = new WeakMap(), _Iterator_iterable = new WeakMap(), _Iterator_iterator = new WeakMap(), Symbol.iterator)]() {
+    [Symbol.iterator]() {
         return this;
     }
     /**
@@ -218,6 +182,21 @@ class Iterator {
     get [Symbol.toStringTag]() {
         return this.constructor.name;
     }
+    /**
+     * The object from which its iterator functionality is derived.
+     *
+     * @type {object}
+     * @private
+     */
+    #iterable = null;
+    /**
+     * The results of a call to the iterable's `[Symbol.iterator]`
+     * generator function.
+     *
+     * @type {object}
+     * @private
+     */
+    #iterator = null;
 }
 exports.Iterator = Iterator;
 exports.IterableExtensions = new extension_1.Extension(Iterable);

package/dist/cjs/classes/iterable.js.map

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

package/dist/cjs/classes/param.parser.d.ts

@@ -0,0 +1,227 @@
+export class ParamParser {
+    /**
+     * Attempts to parse the given parameters using the provided parsers, throwing an
+     * error if no valid parser is found. This method serves as a convenience wrapper
+     * around `safeTryParsers`, enforcing strict parsing by automatically enabling
+     * error throwing on failure.
+     *
+     * @param {any[]} parameters - The parameters to be parsed.
+     * @param {Function[]} parsers - An array of `ParamParser` subclasses to attempt
+     * parsing with.
+     * @returns {Object} An object containing the parsing result, with a `success`
+     * property indicating if parsing was successful, and a `data` property containing
+     * the parsed data if successful.
+     * @example
+     * const parameters = ['param1', 'param2'];
+     * const parsers = [Parser1, Parser2];
+     * const result = ParamParser.tryParsers(parameters, parsers);
+     * if (result.success) {
+     *   console.log('Parsing successful:', result.data);
+     * } else {
+     *   console.error('Parsing failed.');
+     * }
+     */
+    static tryParsers(parameters: any[], parsers: Function[]): Object;
+    /**
+     * Tries parsing `parameters` with each parser in `parsers`. If
+     * `throwOnFail` is true, throws an error when validation fails or
+     * no valid parser is found.
+     *
+     * This method attempts to parse the given parameters using the
+     * provided list of parsers. It validates the input to ensure both
+     * `parameters` and `parsers` are arrays and that `parsers`
+     * contains at least one valid `ParamParser` subclass. If
+     * `throwOnFail` is set to true, it will throw specific errors for
+     * invalid inputs or when no parser succeeds. Otherwise, it returns
+     * an object indicating the success status and the result of
+     * parsing, if successful.
+     *
+     * @param {any[]} parameters - The parameters to be parsed.
+     * @param {Function[]} parsers - An array of `ParamParser`
+     * subclasses to attempt parsing with.
+     * @param {boolean} [throwOnFail=false] - Whether to throw an
+     * error on failure.
+     * @returns {{success: boolean, data: any}} An object with a
+     * `success` flag and `data` containing the parsing result, if
+     * successful.
+     * @throws {ParametersMustBeArrayError} If `parameters` or
+     * `parsers` are not arrays when `throwOnFail` is true.
+     * @throws {ParsersArrayMustContainParsersError} If `parsers`
+     * does not contain at least one valid `ParamParser` subclass
+     * when `throwOnFail` is true.
+     * @throws {NoValidParsersFound} If no valid parser is found
+     * and `throwOnFail` is true.
+     * @example
+     * const parameters = ['param1', 'param2'];
+     * const parsers = [Parser1, Parser2];
+     * const result = ParamParser.safeTryParsers(
+     *   parameters, parsers, true
+     * );
+     *
+     * if (result.success) {
+     *   console.log('Parsing successful:', result.data);
+     * } else {
+     *   console.error('Parsing failed.');
+     * }
+     */
+    static safeTryParsers(parameters: any[], parsers: Function[], throwOnFail?: boolean | undefined): {
+        success: boolean;
+        data: any;
+    };
+    /**
+     * A custom error class that signifies no valid parsers were found
+     * during the parsing process. This error is thrown when all
+     * parsers fail to parse the given parameters and the `throwOnFail`
+     * flag is set to true in the `safeTryParsers` method.
+     *
+     * @returns {Function} A class extending Error, representing a
+     * specific error when no valid parsers are found.ound.
+     *
+     * @example
+     * try {
+     *   const result = ParamParser.safeTryParsers(
+     *     parameters, parsers, true
+     *   );
+     * } catch (error) {
+     *   if (error instanceof ParamParser.NoValidParsersFound) {
+     *     console.error(
+     *       'No valid parsers could process the parameters.'
+     *     );
+     *   }
+     * }
+     */
+    static get NoValidParsersFound(): Function;
+    /**
+     * Represents an error thrown when the parameters provided to a method
+     * are not in an array format as expected. This class extends the
+     * native JavaScript `Error` class, allowing for instances of this
+     * error to be thrown and caught using standard error handling
+     * mechanisms in JavaScript.
+     *
+     * This error is specifically used in scenarios where a method
+     * expects its arguments to be provided as an array, and the
+     * validation of those arguments fails because they were not
+     * provided in an array format. It serves as a clear indicator
+     * of the nature of the error to developers, enabling them to
+     * quickly identify and rectify the issue in their code.
+     *
+     * @example
+     * try {
+     *   ParamParser.safeTryParsers(nonArrayParameters, parsers, true);
+     * } catch (error) {
+     *   if (error instanceof ParamParser.ParametersMustBeArrayError) {
+     *     console.error('Parameters must be provided as an array.');
+     *   }
+     * }
+     */
+    static get ParametersMustBeArrayError(): {
+        new (message?: string | undefined): {
+            name: string;
+            message: string;
+            stack?: string | undefined;
+            cause?: unknown;
+        };
+        new (message?: string | undefined, options?: ErrorOptions | undefined): {
+            name: string;
+            message: string;
+            stack?: string | undefined;
+            cause?: unknown;
+        };
+        captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+        prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+        stackTraceLimit: number;
+    };
+    /**
+     * A custom error class indicating that the parsers array does not
+     * contain valid parser functions. This error is thrown when the
+     * validation of parsers within `ParamParser.safeTryParsers` fails
+     * to find any instance that is a subclass of `ParamParser`. It
+     * extends the native JavaScript `Error` class, allowing it to be
+     * thrown and caught using standard error handling mechanisms.
+     *
+     * This error serves as a clear indicator to developers that the
+     * provided array of parsers does not meet the expected criteria,
+     * specifically that it must contain at least one valid parser
+     * that extends `ParamParser`. This ensures that the parsing
+     * process can be executed with at least one valid parser function.
+     *
+     * @example
+     * try {
+     *   ParamParser.safeTryParsers(parameters, [], true);
+     * } catch (error) {
+     *   const { ParsersArrayMustContainParsersError } = ParamParser
+     *   if (error instanceof ParsersArrayMustContainParsersError) {
+     *     console.error(
+     *       'The parsers array must contain at least one valid parser.'
+     *     );
+     *   }
+     * }
+     */
+    static get ParsersArrayMustContainParsersError(): {
+        new (message?: string | undefined): {
+            name: string;
+            message: string;
+            stack?: string | undefined;
+            cause?: unknown;
+        };
+        new (message?: string | undefined, options?: ErrorOptions | undefined): {
+            name: string;
+            message: string;
+            stack?: string | undefined;
+            cause?: unknown;
+        };
+        captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+        prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+        stackTraceLimit: number;
+    };
+    /**
+     * Constructs an instance of ParamParser. It takes in parameters, an optional
+     * validator function, and an optional parser function. The parameters are
+     * validated and if successful, parsed.
+     *
+     * @param {any[]} parameters - Arguments passed in by the process.
+     * @param {((any[]) => boolean)?} [validator=() => {}] - An optional function
+     * to specify a validator without subclassing ParamParser. It should return
+     * a boolean indicating the validity of the parameters.
+     * @param {((any[]) => object)?} [parser=() => {}] - An optional function to
+     * specify a parser without subclassing ParamParser. It should return an
+     * object after parsing the input parameters.
+     *
+     * @example
+     * const parameters = ['param1', 'param2']
+     * const validator = params => params.every(param => typeof param === 'string')
+     * const parser = params => ({ params })
+     * const paramParser = new ParamParser(parameters, validator, parser)
+     * if (paramParser.success) {
+     *   console.log('Parsing successful:', paramParser.results)
+     * } else {
+     *   console.error('Parsing failed.')
+     * }
+     */
+    constructor(parameters: any[], validator?: () => void, parser?: () => void);
+    args: any[];
+    parser: () => void;
+    validator: () => void;
+    result: any;
+    success: boolean;
+    results: object | undefined;
+    /**
+     * @param {object} args arguments that were previously validated
+     * by either the overloaded validate() method or the supplied
+     * validator closure.
+     * @returns {object} returns the output object, or an empty
+     * object, after parsing the input arguments or parameters.
+     */
+    parse(args: object): object;
+    /**
+     * Walk the arguments and determine if the supplied input is
+     * a valid parsing.
+     *
+     * @param {any[]} args arguments supplied by the process.
+     * @returns {boolean} `true` if the validation is successful,
+     * `false` otherwise.
+     */
+    validate(args: any[]): boolean;
+}
+export const ParamParserExtensions: Extension;
+import { Extension } from '@nejs/extension';

package/dist/cjs/classes/param.parser.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParamParserExtensions = exports.ParamParser = void 0;
+const extension_1 = require("@nejs/extension");
+class ParamParser {
+    /**
+     * Constructs an instance of ParamParser. It takes in parameters, an optional
+     * validator function, and an optional parser function. The parameters are
+     * validated and if successful, parsed.
+     *
+     * @param {any[]} parameters - Arguments passed in by the process.
+     * @param {((any[]) => boolean)?} [validator=() => {}] - An optional function
+     * to specify a validator without subclassing ParamParser. It should return
+     * a boolean indicating the validity of the parameters.
+     * @param {((any[]) => object)?} [parser=() => {}] - An optional function to
+     * specify a parser without subclassing ParamParser. It should return an
+     * object after parsing the input parameters.
+     *
+     * @example
+     * const parameters = ['param1', 'param2']
+     * const validator = params => params.every(param => typeof param === 'string')
+     * const parser = params => ({ params })
+     * const paramParser = new ParamParser(parameters, validator, parser)
+     * if (paramParser.success) {
+     *   console.log('Parsing successful:', paramParser.results)
+     * } else {
+     *   console.error('Parsing failed.')
+     * }
+     */
+    constructor(parameters, validator = () => { }, parser = () => { }) {
+        this.args = parameters;
+        this.parser = parser;
+        this.validator = validator;
+        this.result = undefined;
+        this.success = this.validate(this.args);
+        if (this.success) {
+            this.results = this.parse(this.args);
+        }
+    }
+    /**
+     * @param {object} args arguments that were previously validated
+     * by either the overloaded validate() method or the supplied
+     * validator closure.
+     * @returns {object} returns the output object, or an empty
+     * object, after parsing the input arguments or parameters.
+     */
+    parse(args) {
+        return this.parser?.(args);
+    }
+    /**
+     * Walk the arguments and determine if the supplied input is
+     * a valid parsing.
+     *
+     * @param {any[]} args arguments supplied by the process.
+     * @returns {boolean} `true` if the validation is successful,
+     * `false` otherwise.
+     */
+    validate(args) {
+        return this.validator?.(args);
+    }
+    /**
+     * Attempts to parse the given parameters using the provided parsers, throwing an
+     * error if no valid parser is found. This method serves as a convenience wrapper
+     * around `safeTryParsers`, enforcing strict parsing by automatically enabling
+     * error throwing on failure.
+     *
+     * @param {any[]} parameters - The parameters to be parsed.
+     * @param {Function[]} parsers - An array of `ParamParser` subclasses to attempt
+     * parsing with.
+     * @returns {Object} An object containing the parsing result, with a `success`
+     * property indicating if parsing was successful, and a `data` property containing
+     * the parsed data if successful.
+     * @example
+     * const parameters = ['param1', 'param2'];
+     * const parsers = [Parser1, Parser2];
+     * const result = ParamParser.tryParsers(parameters, parsers);
+     * if (result.success) {
+     *   console.log('Parsing successful:', result.data);
+     * } else {
+     *   console.error('Parsing failed.');
+     * }
+     */
+    static tryParsers(parameters, parsers) {
+        return this.safeTryParsers(parameters, parsers, true);
+    }
+    /**
+     * Tries parsing `parameters` with each parser in `parsers`. If
+     * `throwOnFail` is true, throws an error when validation fails or
+     * no valid parser is found.
+     *
+     * This method attempts to parse the given parameters using the
+     * provided list of parsers. It validates the input to ensure both
+     * `parameters` and `parsers` are arrays and that `parsers`
+     * contains at least one valid `ParamParser` subclass. If
+     * `throwOnFail` is set to true, it will throw specific errors for
+     * invalid inputs or when no parser succeeds. Otherwise, it returns
+     * an object indicating the success status and the result of
+     * parsing, if successful.
+     *
+     * @param {any[]} parameters - The parameters to be parsed.
+     * @param {Function[]} parsers - An array of `ParamParser`
+     * subclasses to attempt parsing with.
+     * @param {boolean} [throwOnFail=false] - Whether to throw an
+     * error on failure.
+     * @returns {{success: boolean, data: any}} An object with a
+     * `success` flag and `data` containing the parsing result, if
+     * successful.
+     * @throws {ParametersMustBeArrayError} If `parameters` or
+     * `parsers` are not arrays when `throwOnFail` is true.
+     * @throws {ParsersArrayMustContainParsersError} If `parsers`
+     * does not contain at least one valid `ParamParser` subclass
+     * when `throwOnFail` is true.
+     * @throws {NoValidParsersFound} If no valid parser is found
+     * and `throwOnFail` is true.
+     * @example
+     * const parameters = ['param1', 'param2'];
+     * const parsers = [Parser1, Parser2];
+     * const result = ParamParser.safeTryParsers(
+     *   parameters, parsers, true
+     * );
+     *
+     * if (result.success) {
+     *   console.log('Parsing successful:', result.data);
+     * } else {
+     *   console.error('Parsing failed.');
+     * }
+     */
+    static safeTryParsers(parameters, parsers, throwOnFail = false) {
+        if (!Array.isArray(parameters) || !Array.isArray(parsers)) {
+            if (throwOnFail) {
+                throw new this.ParametersMustBeArrayError(`${this.name}.tryParsers must receive two arrays as args`);
+            }
+        }
+        if (!parsers.some(parser => parser?.prototype instanceof ParamParser &&
+            typeof parser === 'function')) {
+            if (throwOnFail) {
+                throw new this.ParsersArrayMustContainParsersError(`${this.name}.tryParsers parsers argument must contain at least one ` +
+                    `ParamParser derived class`);
+            }
+        }
+        let success = false;
+        let result = undefined;
+        for (let Parser of parsers) {
+            const parser = new Parser(parameters);
+            if (parser.success) {
+                success = true;
+                result = parser.result;
+                break;
+            }
+        }
+        if (!success && throwOnFail) {
+            throw new this.NoValidParsersFound('No valid parsers found');
+        }
+        return { success, data: result };
+    }
+    /**
+     * A custom error class that signifies no valid parsers were found
+     * during the parsing process. This error is thrown when all
+     * parsers fail to parse the given parameters and the `throwOnFail`
+     * flag is set to true in the `safeTryParsers` method.
+     *
+     * @returns {Function} A class extending Error, representing a
+     * specific error when no valid parsers are found.ound.
+     *
+     * @example
+     * try {
+     *   const result = ParamParser.safeTryParsers(
+     *     parameters, parsers, true
+     *   );
+     * } catch (error) {
+     *   if (error instanceof ParamParser.NoValidParsersFound) {
+     *     console.error(
+     *       'No valid parsers could process the parameters.'
+     *     );
+     *   }
+     * }
+     */
+    static get NoValidParsersFound() {
+        return class NoValidParsersFound extends Error {
+        };
+    }
+    /**
+     * Represents an error thrown when the parameters provided to a method
+     * are not in an array format as expected. This class extends the
+     * native JavaScript `Error` class, allowing for instances of this
+     * error to be thrown and caught using standard error handling
+     * mechanisms in JavaScript.
+     *
+     * This error is specifically used in scenarios where a method
+     * expects its arguments to be provided as an array, and the
+     * validation of those arguments fails because they were not
+     * provided in an array format. It serves as a clear indicator
+     * of the nature of the error to developers, enabling them to
+     * quickly identify and rectify the issue in their code.
+     *
+     * @example
+     * try {
+     *   ParamParser.safeTryParsers(nonArrayParameters, parsers, true);
+     * } catch (error) {
+     *   if (error instanceof ParamParser.ParametersMustBeArrayError) {
+     *     console.error('Parameters must be provided as an array.');
+     *   }
+     * }
+     */
+    static get ParametersMustBeArrayError() {
+        return class ParametersMustBeArrayError extends Error {
+        };
+    }
+    /**
+     * A custom error class indicating that the parsers array does not
+     * contain valid parser functions. This error is thrown when the
+     * validation of parsers within `ParamParser.safeTryParsers` fails
+     * to find any instance that is a subclass of `ParamParser`. It
+     * extends the native JavaScript `Error` class, allowing it to be
+     * thrown and caught using standard error handling mechanisms.
+     *
+     * This error serves as a clear indicator to developers that the
+     * provided array of parsers does not meet the expected criteria,
+     * specifically that it must contain at least one valid parser
+     * that extends `ParamParser`. This ensures that the parsing
+     * process can be executed with at least one valid parser function.
+     *
+     * @example
+     * try {
+     *   ParamParser.safeTryParsers(parameters, [], true);
+     * } catch (error) {
+     *   const { ParsersArrayMustContainParsersError } = ParamParser
+     *   if (error instanceof ParsersArrayMustContainParsersError) {
+     *     console.error(
+     *       'The parsers array must contain at least one valid parser.'
+     *     );
+     *   }
+     * }
+     */
+    static get ParsersArrayMustContainParsersError() {
+        return class ParsersArrayMustContainParsersError extends Error {
+        };
+    }
+}
+exports.ParamParser = ParamParser;
+exports.ParamParserExtensions = new extension_1.Extension(ParamParser);
+//# sourceMappingURL=param.parser.js.map

package/dist/cjs/classes/param.parser.js.map

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