@nejs/basic-extensions 2.21.5 → 2.22.6

package/dist/cjs/classes/deferred.d.ts

@@ -1,146 +0,0 @@
-/**
- * Deferreds, which were first introduced by jQuery for browsers in the early
- * 2000s, are a way to manage asynchronous operations. They have been widely
- * used and replicated by engineers since then. Although the Promise class in
- * modern JavaScript provides a static method called `withResolvers` that
- * returns an object with similar properties to a Deferred, it is not directly
- * supported by Node.js.
- *
- * ```
- * const withResolvers = Promise.withResolvers()
- * Reflect.has(withResolvers, 'promise') // true
- * Reflect.has(withResolvers, 'resolve') // true
- * Reflect.has(withResolvers, 'reject')  // true
- * ```
- *
- * This Deferred class extends the Promise class, allowing it to capture the
- * value or reason for easy access after resolution, akin to
- * {@link Promise.withResolvers}. As it extends {@link Promise}, it is
- * 'thenable' and works with `await` as if it were a native Promise. This
- * allows seamless integration with code expecting Promise-like objects.
- */
-export class Deferred extends Promise<any> {
-    /**
-     * A getter for the species symbol which returns a custom DeferredPromise
-     * class. This class extends from Deferred and is used to ensure that the
-     * constructor signature matches that of a Promise. The executor function
-     * passed to the constructor of this class is used to initialize the Deferred
-     * object with resolve and reject functions, similar to how a Promise would
-     * be initialized.
-     *
-     * @returns {DeferredPromise} A DeferredPromise class that extends Deferred.
-     */
-    static get [Symbol.species](): DeferredPromise;
-    /**
-     * The constructor for Deferred instances. By default, a new Deferred will
-     * have three important properties: `promise`, `resolve`, and `reject`.
-     *
-     * The constructor takes an object called `options`. It can have the
-     * following properties:
-     *
-     * ```
-     * interface BaseDeferredOptions {
-     *   // Deferreds store the value or reason. To turn this off, pass true
-     *   // to this option.
-     *   doNotTrackAnswers?: boolean;
-     * }
-     *
-     * interface ResolveDeferredOptions {
-     *   // Passing in an option object with a resolve value will auto resolve
-     *   // the Deferred with your value. An error will be raised if both
-     *   // resolve and reject are supplied at the same time.
-     *   resolve?: (value: any) => void;
-     * }
-     *
-     * interface RejectDeferredOptions {
-     *   // Passing in an option object with a reject reason will auto reject
-     *   // the Deferred with your reason. An error will be raised if both
-     *   // resolve and reject are supplied at the same time.
-     *   reject?: (reason: any) => void;
-     * }
-     *
-     * type DeferredOptions = BaseDeferredOptions &
-     *   (ResolveDeferredOptions | RejectDeferredOptions)
-     * ```
-     *
-     * @param {object} options see above for examples on supported options, but
-     * when supplied, the constructor can take instructions on how to auto
-     * resolve or reject the deferred created here.
-     */
-    constructor(options: object);
-    /**
-     * When the Deferred is settled with {@link Deferred.resolve}, the `value`
-     * passed to that function will be set here as well.
-     *
-     * @type {*}
-     */
-    value: any;
-    /**
-     * When the Deferred is settled with {@link Deferred.reject}, the `reason`
-     * passed to that rejection will also be stored here.
-     *
-     * @type {*}
-     */
-    reason: any;
-    /**
-     * Returns a boolean value that indicates whether or not this Deferred
-     * has been settled (either resolve or reject have been invoked).
-     *
-     * @returns {boolean} `true` if either {@link Deferred.resolve} or
-     * {@link Deferred.reject} have been invoked; `false` otherwise
-     */
-    get settled(): boolean;
-    /**
-     * A getter that returns a boolean indicating whether the Deferred instance
-     * was rejected. This property can be used to check if the Deferred has been
-     * settled with a rejection. It is particularly useful in scenarios where
-     * the resolution status of the Deferred needs to be checked without
-     * accessing the rejection reason or invoking any additional logic.
-     *
-     * @returns {boolean} `true` if the Deferred was rejected, otherwise `false`.
-     */
-    get wasRejected(): boolean;
-    /**
-     * A getter that returns a boolean indicating whether the Deferred instance
-     * was resolved. This property is useful for checking if the Deferred has been
-     * settled with a resolution, allowing for checks on the Deferred's status
-     * without needing to access the resolved value or trigger any additional
-     * logic.
-     *
-     * @returns {boolean} `true` if the Deferred was resolved, otherwise `false`.
-     */
-    get wasResolved(): boolean;
-    /**
-     * Accessor for the promise managed by this Deferred instance.
-     *
-     * This getter provides access to the internal promise which is controlled
-     * by the Deferred's resolve and reject methods. It allows external code to
-     * attach callbacks for the resolution or rejection of the Deferred without
-     * the ability to directly resolve or reject it.
-     *
-     * @returns {Promise} The promise controlled by this Deferred instance.
-     */
-    get promise(): Promise<any>;
-    /**
-     * Resolves the Deferred with the given value. If the value is a thenable
-     * (i.e., has a "then" method), the Deferred will "follow" that thenable,
-     * adopting its eventual state; otherwise, the Deferred will be fulfilled
-     * with the value. This function behaves the same as Promise.resolve.
-     *
-     * @param {*} value - The value to resolve the Deferred with.
-     * @returns {Promise} A Promise that is resolved with the given value.
-     */
-    resolve(value: any): Promise<any>;
-    /**
-     * Rejects the Deferred with the given reason. This function behaves the
-     * same as Promise.reject. The Deferred will be rejected with the provided
-     * reason.
-     *
-     * @param {*} reason - The reason to reject the Deferred with.
-     * @returns {Promise} A Promise that is rejected with the given reason.
-     */
-    reject(reason: any): Promise<any>;
-    #private;
-}
-export const DeferredExtension: Extension;
-import { Extension } from '@nejs/extension';

package/dist/cjs/classes/deferred.js

@@ -1,291 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeferredExtension = exports.Deferred = void 0;
-const extension_1 = require("@nejs/extension");
-/**
- * Deferreds, which were first introduced by jQuery for browsers in the early
- * 2000s, are a way to manage asynchronous operations. They have been widely
- * used and replicated by engineers since then. Although the Promise class in
- * modern JavaScript provides a static method called `withResolvers` that
- * returns an object with similar properties to a Deferred, it is not directly
- * supported by Node.js.
- *
- * ```
- * const withResolvers = Promise.withResolvers()
- * Reflect.has(withResolvers, 'promise') // true
- * Reflect.has(withResolvers, 'resolve') // true
- * Reflect.has(withResolvers, 'reject')  // true
- * ```
- *
- * This Deferred class extends the Promise class, allowing it to capture the
- * value or reason for easy access after resolution, akin to
- * {@link Promise.withResolvers}. As it extends {@link Promise}, it is
- * 'thenable' and works with `await` as if it were a native Promise. This
- * allows seamless integration with code expecting Promise-like objects.
- */
-class Deferred extends Promise {
-    /**
-     * The promise backing this deferred object. Created when the constructor
-     * runs, this promise is what all `Promise.prototype` functions are routed
-     * to.
-     *
-     * @type {Promise}
-     */
-    #promise = null;
-    /**
-     * The reject() resolver that will be assigned when a new instance is
-     * created. Invoking this function with or without a `reason` will cause
-     * the deferred's promise to be settled.
-     *
-     * @type {function}
-     */
-    #reject = null;
-    /**
-     * The resolve() resolver that will be assigned when a new instance is
-     * created. Invoking this function with or without a `value` will cause
-     * the deferred's promise to be settled.
-     *
-     * @type {function}
-     */
-    #resolve = null;
-    #rejected = false;
-    #resolved = false;
-    /**
-     * When the Deferred is settled with {@link Deferred.resolve}, the `value`
-     * passed to that function will be set here as well.
-     *
-     * @type {*}
-     */
-    value = null;
-    /**
-     * When the Deferred is settled with {@link Deferred.reject}, the `reason`
-     * passed to that rejection will also be stored here.
-     *
-     * @type {*}
-     */
-    reason = null;
-    /**
-     * When either {@link Deferred.resolve} or {@link Deferred.reject} are called,
-     * this property is set to `true`. Its current status at any time can be
-     * queried using the {@link Deferred.settled} getter.
-     *
-     * @type {boolean}
-     */
-    #settled = false;
-    /**
-     * The constructor for Deferred instances. By default, a new Deferred will
-     * have three important properties: `promise`, `resolve`, and `reject`.
-     *
-     * The constructor takes an object called `options`. It can have the
-     * following properties:
-     *
-     * ```
-     * interface BaseDeferredOptions {
-     *   // Deferreds store the value or reason. To turn this off, pass true
-     *   // to this option.
-     *   doNotTrackAnswers?: boolean;
-     * }
-     *
-     * interface ResolveDeferredOptions {
-     *   // Passing in an option object with a resolve value will auto resolve
-     *   // the Deferred with your value. An error will be raised if both
-     *   // resolve and reject are supplied at the same time.
-     *   resolve?: (value: any) => void;
-     * }
-     *
-     * interface RejectDeferredOptions {
-     *   // Passing in an option object with a reject reason will auto reject
-     *   // the Deferred with your reason. An error will be raised if both
-     *   // resolve and reject are supplied at the same time.
-     *   reject?: (reason: any) => void;
-     * }
-     *
-     * type DeferredOptions = BaseDeferredOptions &
-     *   (ResolveDeferredOptions | RejectDeferredOptions)
-     * ```
-     *
-     * @param {object} options see above for examples on supported options, but
-     * when supplied, the constructor can take instructions on how to auto
-     * resolve or reject the deferred created here.
-     */
-    constructor(options) {
-        // Check if options is an object, if not, assign an empty object to config
-        const config = (options && typeof (options) === 'object'
-            ? options
-            : {});
-        // Throw an error if both resolve and reject options are provided
-        if (config?.resolve && config?.reject) {
-            throw new TypeError('resolve and reject options cannot be simultaneously provided');
-        }
-        // Create an empty object to store the resolve and reject functions
-        let _resolve, _reject;
-        // Create a new promise and assign its resolve and reject functions to resolvers
-        super((resolve, reject) => {
-            _resolve = resolve;
-            _reject = reject;
-            if (config?.executor && typeof (config?.executor) === 'function') {
-                config?.executor(resolve, reject);
-            }
-        });
-        // Define the resolve function for the Deferred instance
-        this.#resolve = (value) => {
-            // If doNotTrackAnswers is not set to true, store the value
-            if (config?.doNotTrackAnswers !== true) {
-                this.value = value;
-            }
-            // Mark the Deferred instance as settled
-            this.#settled = true;
-            // Mark the Deferred instance as resolved
-            this.#resolved = true;
-            // Resolve the promise with the provided value
-            return _resolve(value);
-        };
-        // Define the reject function for the Deferred instance
-        this.#reject = async (reason) => {
-            // If doNotTrackAnswers is not set to true, store the reason
-            if (config?.doNotTrackAnswers !== true) {
-                this.reason = reason;
-            }
-            // Mark the Deferred instance as settled
-            this.#settled = true;
-            // Mark the Deferred as being rejected.
-            this.#rejected = true;
-            // Reject the promise with the provided reason
-            return _reject(reason);
-        };
-        this.#promise = this;
-        // If a resolve option is provided, resolve the Deferred instance with it
-        if (config?.resolve) {
-            this.#resolve(config?.resolve);
-        }
-        // If a reject option is provided, reject the Deferred instance with it
-        else if (config?.reject) {
-            this.#reject(config?.reject);
-        }
-    }
-    /**
-     * Returns a boolean value that indicates whether or not this Deferred
-     * has been settled (either resolve or reject have been invoked).
-     *
-     * @returns {boolean} `true` if either {@link Deferred.resolve} or
-     * {@link Deferred.reject} have been invoked; `false` otherwise
-     */
-    get settled() {
-        return this.#settled;
-    }
-    /**
-     * A getter that returns a boolean indicating whether the Deferred instance
-     * was rejected. This property can be used to check if the Deferred has been
-     * settled with a rejection. It is particularly useful in scenarios where
-     * the resolution status of the Deferred needs to be checked without
-     * accessing the rejection reason or invoking any additional logic.
-     *
-     * @returns {boolean} `true` if the Deferred was rejected, otherwise `false`.
-     */
-    get wasRejected() {
-        return this.#rejected;
-    }
-    /**
-     * A getter that returns a boolean indicating whether the Deferred instance
-     * was resolved. This property is useful for checking if the Deferred has been
-     * settled with a resolution, allowing for checks on the Deferred's status
-     * without needing to access the resolved value or trigger any additional
-     * logic.
-     *
-     * @returns {boolean} `true` if the Deferred was resolved, otherwise `false`.
-     */
-    get wasResolved() {
-        return this.#resolved;
-    }
-    /**
-     * Accessor for the promise managed by this Deferred instance.
-     *
-     * This getter provides access to the internal promise which is controlled
-     * by the Deferred's resolve and reject methods. It allows external code to
-     * attach callbacks for the resolution or rejection of the Deferred without
-     * the ability to directly resolve or reject it.
-     *
-     * @returns {Promise} The promise controlled by this Deferred instance.
-     */
-    get promise() {
-        return this.#promise;
-    }
-    /**
-     * Resolves the Deferred with the given value. If the value is a thenable
-     * (i.e., has a "then" method), the Deferred will "follow" that thenable,
-     * adopting its eventual state; otherwise, the Deferred will be fulfilled
-     * with the value. This function behaves the same as Promise.resolve.
-     *
-     * @param {*} value - The value to resolve the Deferred with.
-     * @returns {Promise} A Promise that is resolved with the given value.
-     */
-    resolve(value) {
-        return this.#resolve(value);
-    }
-    /**
-     * Rejects the Deferred with the given reason. This function behaves the
-     * same as Promise.reject. The Deferred will be rejected with the provided
-     * reason.
-     *
-     * @param {*} reason - The reason to reject the Deferred with.
-     * @returns {Promise} A Promise that is rejected with the given reason.
-     */
-    reject(reason) {
-        return this.#reject(reason);
-    }
-    /**
-     * Customizes the output of `util.inspect` on instances of Deferred when
-     * used in Node.js. This method is invoked by Node.js's `util.inspect`
-     * utility to format the inspection output of a Deferred instance.
-     *
-     * The output includes the state of the Deferred (resolved, rejected, or
-     * unsettled) along with the resolved value or rejection reason, if
-     * applicable. This provides a quick, readable status of the Deferred
-     * instance directly in the console or debugging tools.
-     *
-     * @param {number} depth The depth to which `util.inspect` will recurse.
-     * @param {object} options Formatting options provided by `util.inspect`.
-     * @param {function} inspect Reference to the `util.inspect` function.
-     * @returns {string} A formatted string representing the Deferred instance.
-     */
-    [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
-        return [
-            '\x1b[1mDeferred [\x1b[22;3mPromise\x1b[23;1m]\x1b[22m ',
-            '{ ',
-            (this.settled
-                ? (this.wasResolved
-                    ? `resolved with \x1b[32m${this.value}\x1b[39m`
-                    : `rejected with \x1b[31m${this.reason?.message ?? this.reason}\x1b[39m`)
-                : '\x1b[33munsettled valued or reason\x1b[39m'),
-            ' }'
-        ].join('');
-    }
-    /**
-     * A getter for the species symbol which returns a custom DeferredPromise
-     * class. This class extends from Deferred and is used to ensure that the
-     * constructor signature matches that of a Promise. The executor function
-     * passed to the constructor of this class is used to initialize the Deferred
-     * object with resolve and reject functions, similar to how a Promise would
-     * be initialized.
-     *
-     * @returns {DeferredPromise} A DeferredPromise class that extends Deferred.
-     */
-    static get [Symbol.species]() {
-        return class DeferredPromise extends Deferred {
-            /**
-             * The constructor for the DeferredPromise class.
-             * It takes an executor function which is used to initialize the Deferred.
-             *
-             * @param {Function} executor - A function that is passed with the resolve
-             * and reject functions. The executor is expected to initialize the
-             * Deferred by calling resolve or reject at some point.
-             */
-            constructor(executor) {
-                super({ executor });
-            }
-        };
-    }
-}
-exports.Deferred = Deferred;
-exports.DeferredExtension = new extension_1.Extension(Deferred);
-//# sourceMappingURL=deferred.js.map

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

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