In Node, what contract must a function satisfy for util.promisify(fn) to produce a working promise version, and what is the util.promisify.custom symbol for?

## The convention promisify encodes `util.promisify` is Node's mechanised version of the hand-written error-first wrapper. It assumes exactly one thing about the function you hand it: the **last argument is a callback**, and that callback is invoked as `(err, value)` — a truthy first argument means failure, and a falsy one means the second argument is the result. ```js import { promisify } from 'node:util'; import fs from 'node:fs'; const readFile = promisify(fs.readFile); const text = await readFile('package.json', 'utf8'); ``` The returned function forwards every argument you pass, appends its own callback, and returns a promise that rejects with `err` or fulfils with `value`. Passing something that is not a function throws a `TypeError`. ## What the generated wrapper does and does not carry over **Only the first result survives.** The generated callback keeps the second argument and discards anything after it. For an API whose callback is `(err, a, b)`, the promisified form silently loses `b`. **The receiver comes from the call site.** The wrapper invokes the original with whatever `this` the wrapper itself was called on. So `obj.readIt = promisify(obj.readIt)` keeps working as a method, but pulling a method off an object and calling it bare loses the receiver exactly as the callback version would — bind it first if the implementation depends on `this`. **Own property descriptors are copied** from the original onto the wrapper, so incidental properties hanging off the function survive. ## Functions that do not fit Two classes of API break the contract: - Callbacks with **no error parameter**. The historical `fs.exists(path, (exists) => ...)` calls back with a boolean. Promisified generically, a `true` would be treated as an error and reject. - Callbacks with **several meaningful results**, like `child_process.exec(cmd, (err, stdout, stderr) => ...)`, where dropping `stderr` would be a real loss. ## util.promisify.custom For those cases the function itself can advertise a bespoke promise implementation: ```js import { promisify } from 'node:util'; function readSetting(key, cb) { // legacy: cb(value) with no error slot setTimeout(() => cb(key.length), 0); } readSetting[promisify.custom] = (key) => new Promise((resolve) => readSetting(key, resolve)); const readSettingAsync = promisify(readSetting); await readSettingAsync('theme'); // uses the custom implementation ``` `promisify.custom` is a well-known symbol — `Symbol.for('nodejs.util.promisify.custom')` — so the registration is cross-realm and any copy of `util` recognises it. When `promisify` sees that property it returns its value directly instead of generating a wrapper, and it throws a `TypeError` if the property is present but not a function. Node uses this internally: `child_process.exec` promisifies to a promise for `{ stdout, stderr }`, and `fs.exists` promisifies to a boolean-yielding function rather than an error-first one. The practical consequence for a library author is that shipping a `promisify.custom` implementation is how you make a legacy callback API behave sensibly under `await` without changing its signature. ## Prefer a first-party promise API Promisifying is a bridge, not a destination. Node now ships promise-native modules and you should reach for those first: ```js import { readFile } from 'node:fs/promises'; import { setTimeout as sleep } from 'node:timers/promises'; ``` `node:fs/promises`, `node:timers/promises`, and `node:dns/promises` are designed as promise APIs rather than translated ones, so they return richer objects, avoid per-call wrapper allocation, and accept options — such as an abort signal — that a mechanical translation of the callback form could never expose. ## The reverse direction `util.callbackify` goes the other way: it takes an `async` function and returns one that accepts an error-first callback, which is how you expose modern code to a legacy caller. Its one quirk is that if the async function rejects with a falsy reason, `callbackify` wraps it so the callback still receives a truthy error — otherwise the caller's `if (err)` check would miss the failure. ## What an interviewer is testing Mostly whether you know that promisification is a **convention adapter**, not magic: it works because Node standardised callback shape, it fails precisely where that standard was not followed, and the escape hatch is a documented symbol rather than a special case in the runtime.