tessl/npm-q

A comprehensive promise library implementing CommonJS Promises/A,B,D specifications for JavaScript

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core Promise Creation

Name: tessl/npm-q
Author: tessl

Core functions for creating and managing promises from values, errors, callback functions, and other asynchronous operations.

Capabilities

Main Q Function

The primary function for creating promises from any value, including thenables and existing promises.

/**
 * Creates a promise from a value, thenable, or existing promise
 * @param value - Any value to convert to a promise
 * @returns Promise wrapping the value
 */
function Q(value);

Usage Examples:

const Q = require("q");

// Create promise from value
const valuePromise = Q("Hello");

// Create promise from thenable
const thenable = { then: (resolve) => resolve("World") };
const thenablePromise = Q(thenable);

// Pass through existing promise
const existingPromise = Q.resolve("Existing");
const passedPromise = Q(existingPromise); // Same promise returned

Deferred Creation

Creates deferred objects that provide manual control over promise resolution.

/**
 * Creates a deferred object with promise, resolve, and reject methods
 * @returns Deferred object with promise property and control methods
 */
function Q.defer();

interface Deferred {
  promise: Promise;
  resolve(value: any): void;
  reject(reason: any): void;
  setEstimate(estimate: number): void;
  makeNodeResolver(unpack?: boolean): Function;
}

Usage Examples:

const Q = require("q");

// Create and control deferred
const deferred = Q.defer();

setTimeout(() => {
  if (Math.random() > 0.5) {
    deferred.resolve("Success!");
  } else {
    deferred.reject(new Error("Failed"));
  }
}, 1000);

deferred.promise
  .then(value => console.log(value))
  .catch(error => console.error(error));

// Node.js callback integration
const nodeCallback = deferred.makeNodeResolver();
fs.readFile("file.txt", nodeCallback);

Promise Rejection

Creates promises that are already rejected with the specified error.

/**
 * Creates a promise rejected with the given error
 * @param error - Error or reason for rejection
 * @returns Promise rejected with the error
 */
function Q.reject(error);

Usage Examples:

const Q = require("q");

// Create rejected promise
const rejected = Q.reject(new Error("Operation failed"));

// Use in conditional logic
function validateInput(input) {
  if (!input) {
    return Q.reject(new Error("Input required"));
  }
  return Q.resolve(input.toUpperCase());
}

Promise Constructor

Constructor function for creating promises with a resolver function.

/**
 * Promise constructor that takes a resolver function
 * @param resolver - Function receiving resolve and reject callbacks
 * @returns New promise instance
 */
function Q.Promise(resolver);

Usage Examples:

const Q = require("q");

// Create promise with constructor
const promise = new Q.Promise((resolve, reject) => {
  const xhr = new XMLHttpRequest();
  xhr.open("GET", "/api/data");
  xhr.onload = () => {
    if (xhr.status === 200) {
      resolve(JSON.parse(xhr.responseText));
    } else {
      reject(new Error(`HTTP ${xhr.status}`));
    }
  };
  xhr.onerror = () => reject(new Error("Network error"));
  xhr.send();
});

Try Function Execution

Executes a function and returns a promise for its result, catching any synchronous errors.

/**
 * Calls function and returns promise for result or error
 * @param callback - Function to execute
 * @returns Promise for function result or rejection if error thrown
 */
function Q.try(callback);

Usage Examples:

const Q = require("q");

// Safe function execution
const result = Q.try(() => {
  return JSON.parse(inputString);
});

result
  .then(data => console.log("Parsed:", data))
  .catch(error => console.error("Parse error:", error));

// With parameters
function safeDivide(a, b) {
  return Q.try(() => {
    if (b === 0) throw new Error("Division by zero");
    return a / b;
  });
}

Promise Static Methods

Static methods available on the Promise constructor for ES6 compatibility.

/**
 * Static versions of Q functions available on Q.Promise
 */
Q.Promise.all(promises);     // Static version of Q.all
Q.Promise.race(promises);    // Static version of Q.race  
Q.Promise.resolve(value);    // Static version of Q()
Q.Promise.reject(reason);    // Static version of Q.reject

Usage Examples:

const Q = require("q");

// Use static methods
const allPromise = Q.Promise.all([
  Q.resolve(1),
  Q.resolve(2),
  Q.resolve(3)
]);

const racePromise = Q.Promise.race([
  Q.delay("fast", 100),
  Q.delay("slow", 500)
]);

Install with Tessl CLI