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

Synchronous Inspection

Name: tessl/npm-promise
Author: tessl

Optional methods for synchronously inspecting promise state. These methods are disabled by default for performance reasons and must be explicitly enabled.

Capabilities

Promise.enableSynchronous

Enables synchronous inspection methods on Promise.prototype.

/**
 * Enables synchronous inspection methods
 * Adds isPending, isFulfilled, isRejected, getValue, getReason, getState to prototype
 * @returns {void}
 */
Promise.enableSynchronous();

Usage Examples:

const Promise = require('promise');

// Enable synchronous inspection
Promise.enableSynchronous();

const resolved = Promise.resolve('hello');
const rejected = Promise.reject(new Error('failed'));
const pending = new Promise(() => {}); // Never resolves

console.log(resolved.isFulfilled()); // true
console.log(rejected.isRejected());  // true  
console.log(pending.isPending());    // true

Promise.disableSynchronous

Disables synchronous inspection methods by removing them from Promise.prototype.

/**
 * Disables synchronous inspection methods
 * Removes isPending, isFulfilled, isRejected, getValue, getReason, getState from prototype
 * @returns {void}
 */
Promise.disableSynchronous();

Usage Examples:

const Promise = require('promise');

Promise.enableSynchronous();
const promise = Promise.resolve('test');

console.log(typeof promise.isFulfilled); // 'function'

Promise.disableSynchronous();
console.log(typeof promise.isFulfilled); // 'undefined'

Instance Methods (Available after enableSynchronous)

isPending

Checks if the promise is still pending (not yet settled).

/**
 * Checks if promise is pending
 * @returns {boolean} True if promise is pending
 */
Promise.prototype.isPending();

isFulfilled

Checks if the promise has been fulfilled with a value.

/**
 * Checks if promise is fulfilled
 * @returns {boolean} True if promise is fulfilled
 */
Promise.prototype.isFulfilled();

isRejected

Checks if the promise has been rejected with a reason.

/**
 * Checks if promise is rejected
 * @returns {boolean} True if promise is rejected
 */
Promise.prototype.isRejected();

getValue

Synchronously retrieves the fulfillment value from a fulfilled promise.

/**
 * Gets the fulfillment value
 * @returns {*} The fulfillment value
 * @throws {Error} If promise is not fulfilled
 */
Promise.prototype.getValue();

getReason

Synchronously retrieves the rejection reason from a rejected promise.

/**
 * Gets the rejection reason
 * @returns {*} The rejection reason
 * @throws {Error} If promise is not rejected
 */
Promise.prototype.getReason();

getState

Gets the numeric state of the promise.

/**
 * Gets the promise state
 * @returns {number} 0=pending, 1=fulfilled, 2=rejected
 */
Promise.prototype.getState();

Usage Examples

Basic State Inspection

const Promise = require('promise');

Promise.enableSynchronous();

// Test different promise states
const promises = {
  resolved: Promise.resolve('success'),
  rejected: Promise.reject(new Error('failure')),
  pending: new Promise(() => {}) // Never settles
};

Object.entries(promises).forEach(([name, promise]) => {
  console.log(`${name}:`);
  console.log('  isPending:', promise.isPending());
  console.log('  isFulfilled:', promise.isFulfilled());
  console.log('  isRejected:', promise.isRejected());
  console.log('  getState:', promise.getState());
});

Safe Value/Reason Retrieval

const Promise = require('promise');

Promise.enableSynchronous();

function safeGetValue(promise) {
  if (promise.isFulfilled()) {
    return promise.getValue();
  } else if (promise.isRejected()) {
    return `Error: ${promise.getReason().message}`;
  } else {
    return 'Still pending';
  }
}

const promise1 = Promise.resolve('Hello World');
const promise2 = Promise.reject(new Error('Something failed'));

console.log(safeGetValue(promise1)); // "Hello World"
console.log(safeGetValue(promise2)); // "Error: Something failed"

Testing and Debugging

const Promise = require('promise');

Promise.enableSynchronous();

function debugPromise(promise, label) {
  console.log(`${label}:`);
  console.log(`  State: ${promise.getState()} (${getStateText(promise)})`);
  
  try {
    if (promise.isFulfilled()) {
      console.log(`  Value:`, promise.getValue());
    } else if (promise.isRejected()) {
      console.log(`  Reason:`, promise.getReason());
    }
  } catch (error) {
    console.log(`  Error accessing value/reason:`, error.message);
  }
}

function getStateText(promise) {
  if (promise.isPending()) return 'pending';
  if (promise.isFulfilled()) return 'fulfilled'; 
  if (promise.isRejected()) return 'rejected';
  return 'unknown';
}

// Debug promises at different states
debugPromise(Promise.resolve(42), 'Resolved Promise');
debugPromise(Promise.reject(new Error('test')), 'Rejected Promise');

Synchronous Testing

const Promise = require('promise');

Promise.enableSynchronous();

// Useful for unit tests
function createImmediatePromise(value, shouldReject = false) {
  return shouldReject ? Promise.reject(value) : Promise.resolve(value);
}

// Test synchronously
const success = createImmediatePromise('test data');
const failure = createImmediatePromise(new Error('test error'), true);

// Assert states immediately
console.assert(success.isFulfilled());
console.assert(success.getValue() === 'test data');

console.assert(failure.isRejected());
console.assert(failure.getReason().message === 'test error');

Performance Considerations

Disabled by default: Synchronous inspection adds overhead to all promises
Enable selectively: Only enable during development or testing
Production usage: Generally not recommended for production code
Alternative approaches: Consider using .then() and .catch() for normal promise handling

Error Conditions

const Promise = require('promise');

Promise.enableSynchronous();

const pending = new Promise(() => {});
const resolved = Promise.resolve('value');
const rejected = Promise.reject(new Error('reason'));

// These will throw errors:
try {
  pending.getValue();  // Error: Cannot get value of unfulfilled promise
} catch (e) {
  console.log(e.message);
}

try {
  resolved.getReason(); // Error: Cannot get rejection reason of non-rejected promise  
} catch (e) {
  console.log(e.message);
}

Install with Tessl CLI