DeferredAsyncValue

Overview

The DeferredAsyncValue class is a custom utility designed for managing asynchronous operations in JavaScript, providing a flexible way to handle success and failure scenarios with a promise-like interface. It introduces a more controlled mechanism to deal with asynchronous workflow, especially useful when you need fine-grained control over when and how callbacks are invoked after an asynchronous operation completes.

Key Features

• Deferred Execution: Allows deferring the resolution or rejection of an asynchronous operation until needed.
• Custom Default Values: Supports specifying default values for successful results or reasons for failure.
• Callback Management: Automatically manages and executes registered success or failure callbacks.
• Promise Compatibility: Exposes a result property that behaves like a Promise, facilitating chaining and error handling.

Usage

Installation

• Install using npm or yarn:

npm install @charming-choose/deferred-async-value
# or
yarn add @charming-choose/deferred-async-value

Basic Usage

import DeferredAsyncValue from '@charming-choose/deferred-async-value';

// Create an instance of DeferredAsyncValue
const asyncValue = new DeferredAsyncValue();

// Register callbacks
asyncValue.result.then(data => {
  console.log('Success:', data);
}).catch(error => {
  console.log('Failed:', error);
});

// Simulate an async operation completion
setTimeout(() => {
  asyncValue.success('Operation completed!');
}, 2000);

Methods & Properties

• result: A Promise that resolves or rejects based on the state of the async operation.
• success(arg?): Call this method to mark the operation as successful, optionally passing a value.
• fail(reason?): Call this method to mark the operation as failed, optionally passing a reason.
• reset: Resets the DeferredAsyncValue object to its initial state.

Types & Interfaces

• DeferredStatus: Represents the three states of an async operation ('resolved', 'rejected', 'pending').
• Callback: A type representing a generic callback function accepting an optional argument of type T.
• TypeDeferredAsyncValue<T, U>: An interface describing the structure of the DeferredAsyncValue instance.

Why Use DeferredAsyncValue?

This class is particularly beneficial in scenarios where you want more control over the timing of resolving or rejecting promises, especially in complex async flows where you may need to wait for multiple dependencies or handle UI updates more precisely.

Compatibility

Compatible with modern JavaScript environments supporting ES6 and TypeScript.

Contribution

Feel free to contribute improvements or report issues related to this utility class.

License

MIT License. See LICENSE file for more details.