tessl/npm-promise

Bare bones Promises/A+ implementation with essential extensions for readable, performant asynchronous operation handling.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Extension Methods

Name: tessl/npm-promise
Author: tessl

Additional instance methods that extend the core Promise functionality beyond the Promises/A+ specification.

Capabilities

Promise.prototype.catch

Shorthand for attaching only a rejection handler to the promise.

/**
 * Attaches a rejection handler to the promise
 * @param {function} [onRejected] - Function to handle rejection
 * @returns {Promise} New promise for chaining
 */
Promise.prototype.catch(onRejected);

Usage Examples:

const Promise = require('promise');

// Basic error handling
promise
  .then(result => processResult(result))
  .catch(error => {
    console.error('Error occurred:', error.message);
    return 'default value'; // Recovery
  });

// Equivalent to .then(null, onRejected)
promise.catch(error => handleError(error));

// Error recovery chain  
promise
  .catch(error => {
    if (error.code === 'NETWORK_ERROR') {
      return retryOperation();
    }
    throw error; // Re-throw if can't handle
  })
  .then(result => console.log('Final result:', result));

Promise.prototype.done

Terminal handler that doesn't return a new promise and throws unhandled rejections globally.

/**
 * Terminal promise handler without returning new promise
 * @param {function} [onFulfilled] - Success handler
 * @param {function} [onRejected] - Error handler  
 * @returns {void} Does not return a promise
 */
Promise.prototype.done(onFulfilled, onRejected);

Usage Examples:

const Promise = require('promise');

// Terminal handling - no further chaining
promise.done(
  result => console.log('Success:', result),
  error => console.error('Error:', error)
);

// Just success handler
promise.done(result => {
  updateUI(result);
  // Any unhandled errors will be thrown globally
});

// No handlers - unhandled rejections throw globally
promise.done(); // Ensures rejection throws if not handled elsewhere

// Comparison with .then()
promise.then(handler);     // Returns new promise, can chain
promise.done(handler);     // Returns void, terminates chain

Promise.prototype.finally

Executes cleanup code regardless of promise outcome, without affecting the promise value.

/**
 * Executes cleanup code regardless of promise outcome
 * @param {function} onFinally - Cleanup function (receives no arguments)
 * @returns {Promise} Promise with same settlement as original
 */
Promise.prototype.finally(onFinally);

Usage Examples:

const Promise = require('promise');

// Basic cleanup
let isLoading = true;

fetchData()
  .then(data => processData(data))
  .catch(error => handleError(error))
  .finally(() => {
    isLoading = false;  // Always executed
    hideSpinner();
  });

// Resource cleanup
function performOperation() {
  const resource = acquireResource();
  
  return processWithResource(resource)
    .finally(() => {
      releaseResource(resource); // Always cleanup
    });
}

// Cleanup doesn't affect promise value
Promise.resolve('original value')
  .finally(() => {
    console.log('Cleanup');
    return 'cleanup value'; // Ignored
  })
  .then(value => {
    console.log(value); // "original value"
  });

// Cleanup can introduce delay
Promise.resolve('result')
  .finally(() => {
    return new Promise(resolve => setTimeout(resolve, 1000));
  })
  .then(value => {
    console.log(value); // "result" (after 1 second delay)
  });

Method Behavior Details

Error Propagation

catch(): Catches errors and allows recovery or re-throwing
done(): Unhandled errors are thrown globally (not caught by outer try/catch)
finally(): Errors in finally handler reject the returned promise

Return Values

catch(): Returns new promise, enables chaining
done(): Returns void, terminates promise chain
finally(): Returns promise with original value (unless finally handler rejects)

Timing

catch(): Executes when promise rejects
done(): Executes when promise settles, then terminates chain
finally(): Always executes after settlement, preserves original timing

Example comparing all three:

const Promise = require('promise');

promise
  .then(result => processResult(result))
  .catch(error => {
    console.log('Caught error:', error);
    return 'recovered'; // Continue chain with new value
  })
  .finally(() => {
    console.log('Cleanup'); // Always runs
  })
  .done(finalResult => {
    console.log('Final result:', finalResult);
    // Chain terminates here - no return value
  });

Install with Tessl CLI