kew: Lightweight Promise Library

Common errors

• ReferenceError: Q is not defined

  cause The `kew` library was not correctly imported or its export was not assigned to the `Q` variable.
  fix Ensure `const Q = require('kew');` is present and correctly scoped before `Q` is used.

• TypeError: kew is not a function

  cause Attempting to invoke the `kew` module directly as a function (e.g., `new kew()`) instead of accessing its exported `Q` object.
  fix Access the `Q` object after requiring the module: `const Q = require('kew'); const promise = Q.resolve('value');`

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax (e.g., `import Q from 'kew'`) in a Node.js CommonJS environment.
  fix Use the CommonJS `require` syntax: `const Q = require('kew');`

Warnings

• breaking kew implements only a subset of features found in other promise libraries like Q. Developers migrating from other promise libraries or expecting full Promise A+ compliance may encounter missing functionalities or different behaviors.
  Fix: Thoroughly review kew's documentation and source code to confirm feature availability. For modern applications, consider using native ES6 Promises or actively maintained alternatives.
• gotcha The kew library is abandoned, with its last release (v0.7.0) several years ago. This means it receives no further updates, bug fixes, or security patches, making it unsuitable for new projects or critical production environments.
  Fix: Migrate to a currently maintained promise library or utilize native ES6 Promises (supported in Node.js v6+).
• gotcha kew is a CommonJS-only module and does not natively support ES Modules (ESM) `import`/`export` syntax. Attempting to use `import Q from 'kew'` directly in an ESM context will fail.
  Fix: For CommonJS projects, use `const Q = require('kew')`. For ESM projects, consider using a different, actively maintained promise library that supports ESM, or native `Promise`.
• gotcha kew predates modern JavaScript features like `async/await`. While its promises can interoperate with `async/await` if 'promisified' using utility functions (e.g., Node.js `util.promisify`), it does not offer direct support for these constructs, leading to less ergonomic code compared to native promises.
  Fix: Wrap kew promise-returning functions with `util.promisify` if necessary, or refactor to use native ES6 Promises for direct `async/await` compatibility.
• gotcha The package does not ship with TypeScript declaration files (.d.ts). This makes it challenging to use in TypeScript projects without manually creating declaration files or resorting to `any` types.
  Fix: Consider creating a custom `kew.d.ts` file or migrating to a promise library that provides TypeScript support out-of-the-box.

Install

• npm install kew npm
• yarn add kew yarn
• pnpm add kew pnpm

Imports

• Q
  wrong:

  import Q from 'kew'

  correct:

  const Q = require('kew')

  kew is a CommonJS-only library. Attempting to use ESM `import` syntax will result in a `SyntaxError` in Node.js environments unless a transpilation step is used, which is generally not recommended for this abandoned library.
• defer
  wrong:

  import { defer } from 'kew'

  correct:

  const Q = require('kew'); const deferred = Q.defer();

  All core functionality, including the `defer` method, is exposed as properties on the main `Q` object exported by the module. There are no named exports for individual methods.
• PromiseConstructor
  wrong:

  import { Promise } from 'kew'

  correct:

  const Q = require('kew'); const promise = Q.resolve('value');

  kew provides its own promise constructor via the `Q` object. It does not export a `Promise` class directly. Modern applications should generally use the native global `Promise` constructor.

Quickstart

Demonstrates `Q.resolve()`, `Q.defer()`, handling deferred promises, and using `makeNodeResolver()` to integrate with Node.js-style callbacks, including error handling.

const Q = require('kew');

// 1. Create a promise from a literal value
const successPromise = Q.resolve('Hello from kew!');

successPromise.then(function(message) {
  console.log('Resolved with:', message);
});

// 2. Create a deferred promise and resolve it later
const myDeferred = Q.defer();

setTimeout(function() {
  myDeferred.resolve('Delayed success!');
}, 500);

myDeferred.promise.then(function(result) {
  console.log('Deferred resolved with:', result);
});

// 3. Handle node-style callbacks with makeNodeResolver
function getNodeStyleData(id, callback) {
  setTimeout(() => {
    if (id === 1) {
      callback(null, { id: 1, name: 'Item 1' });
    } else {
      callback(new Error('Item not found!'));
    }
  }, 200);
}

const dataDefer = Q.defer();
getNodeStyleData(1, dataDefer.makeNodeResolver());

dataDefer.promise
  .then(function(obj) {
    console.log('Node-style callback success:', obj);
  })
  .fail(function(e) {
    console.error('Node-style callback error:', e.message);
  });

const errorDefer = Q.defer();
getNodeStyleData(2, errorDefer.makeNodeResolver());

errorDefer.promise
  .then(function(obj) {
    console.log('Node-style callback success (should not happen):', obj);
  })
  .fail(function(e) {
    console.error('Node-style callback error (expected):', e.message);
  });