pn

library1.1.0jsnpmunverified

pn is a JavaScript library that provides Promise-returning wrappers for the Node.js standard library functions that traditionally use callbacks. Released in its current form (v1.1.0) in 2016, it aimed to bridge the gap before native `async/await` and `util.promisify` were standard in Node.js. It operates by returning a Promise only if no callback is supplied, allowing existing callback-based code to function without modification. The library handles various 'odd cases' in Node.js APIs, such as functions that return multiple values via callback or those that return an object while also taking a callback. Its release cadence is effectively inactive, with the last update in 2016. While functional, modern Node.js environments (v8+ for `util.promisify`, v7.6+ for `async/await`) have native alternatives that are generally preferred.

http-networking

npm install pn

github ↗package ↗

INSTALL

IMPORT

SIG · PN

http-networkingjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import fs from 'pn/fs';

✗ const fs = require('fs');

To use the promisified 'fs' module, import specifically from 'pn/fs'. The package primarily uses CommonJS `require` syntax in its documentation, but modern bundlers often handle `import` statements for CJS modules. Importing 'fs' directly will yield the standard Node.js callback-based module.

child_process

✓ import child_process from 'pn/child_process';

✗ const child_process = require('child_process');

Import specific Node.js modules via the 'pn/' prefix. Functions like 'execFile' return a 'ChildProcess' object with a non-enumerable 'promise' field, which resolves to an object containing 'stdout' and 'stderr'.

customPromiseType

✓ require('pn/_promise')(MyPromise);

✗ import { _promise } from 'pn';

To specify a custom Promise implementation (e.g., 'prfun'), use the CommonJS require pattern for 'pn/_promise' and pass your Promise constructor. This is a global configuration and only needs to be done once.

Demonstrates writing a file using a Promise and a callback, and executing a child process with Promise-based handling of stdout/stderr.

import fs from 'pn/fs'; import child_process from 'pn/child_process'; async function runExample() { console.log('--- File Write Example ---'); try { await fs.writeFile('foo.txt', 'Hello pn!', 'utf-8'); console.log('File "foo.txt" written successfully via Promise.'); } catch (err) { console.error('Error writing file:', err); } // Callback usage still works fs.writeFile('bar.txt', 'Hello with callback!', 'utf-8', (err) => { if (err) console.error('Error writing file (callback):', err); else console.log('File "bar.txt" written successfully via callback.'); }); console.log('\n--- Child Process Example ---'); try { const cp = child_process.execFile('node', ['-e', 'console.log("Hello from child!"); console.error("Error from child!");']); console.log(`Child process started with PID: ${cp.pid}`); const result = await cp.promise; console.log('Child process finished.'); console.log('Stdout:', result.stdout.trim()); console.log('Stderr:', result.stderr.trim()); } catch (err) { console.error('Error executing child process:', err); } } runExample();

Debug

Known issues

breakingThe `crypto.randomBytes` and `crypto.pseudoRandomBytes` methods are changed to be always asynchronous when promisified. For synchronous behavior, `pn` introduces `randomBytesSync` and `pseudoRandomBytesSync`. This is a direct breaking change from the original Node.js `crypto` API where these methods could be synchronous if no callback was provided.

fix

Use `require('pn/crypto').randomBytesSync()` or `require('pn/crypto').pseudoRandomBytesSync()` for synchronous operations, or `await require('pn/crypto').randomBytes()` for asynchronous promise-based usage.

affects: >=1.0.0

gotchaFor Node.js APIs where the callback receives multiple value arguments (e.g., `dns.lookupService` returning `hostname` and `service`), the promisified version will resolve with an object containing named fields for each value, such as `{ hostname, service }`.

fix

Access resolved values as properties of the returned object (e.g., `result.hostname`, `result.service`) instead of expecting multiple arguments in a `.then()` handler.

affects: >=1.0.0

gotchaMethods that return an object *and* take a callback (e.g., `child_process.execFile`, `http.request`) will return the original object. The Promise corresponding to the callback resolution is attached as a non-enumerable field named `promise` on that returned object.

fix

Access the Promise via `returnedObject.promise` to await its resolution, for example, `const cp = child_process.execFile(...); await cp.promise;`.

affects: >=1.0.0

gotchaThe library relies on `global.Promise` being available. In very old Node.js environments (pre-0.11) or environments without a native Promise implementation, `pn` will not function correctly unless a Promise polyfill (like `core-js` or `es6-shim`) is loaded *before* `pn`.

fix

Ensure a Promise polyfill is loaded by `require('es6-shim');` or similar at the entry point of your application if targeting environments without native Promises.

affects: <1.0.0

Errors

Common errors & fixes

TypeError: global.Promise is not a constructor

Attempting to use `pn` in an environment where `global.Promise` is undefined or not a valid Promise constructor, typically an older Node.js version without a polyfill.

fix

Load a Promise polyfill like `es6-shim` or `core-js` before `pn`: `require('es6-shim'); var fs = require('pn/fs');`

crypto.randomBytes is not a function (or similar type error for randomBytes/pseudoRandomBytes)

After `pn` promisifies the `crypto` module, `randomBytes` becomes an asynchronous Promise-returning function. If you are expecting the original synchronous behavior without a callback, the API has changed.

fix

For synchronous operations, use the `pn` specific synchronous variants: `require('pn/crypto').randomBytesSync(...)` or `require('pn/crypto').pseudoRandomBytesSync(...)`.

UnhandledPromiseRejectionWarning: Unhandled promise rejection.

A Promise returned by a `pn` promisified function rejected (e.g., due to an error in the underlying Node.js API), but the rejection was not caught by a `.catch()` block or `try...catch` in an `async` function.

fix

Always chain a `.catch(err => { /* handle error */ })` to Promise chains or wrap `await` calls in `try...catch` blocks to handle potential errors.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/cscott/node-pn ↗

packagehttps://www.npmjs.com/package/pn ↗