The Electron team is currently undergoing an initiative to convert callback-based functions in Electron to return Promises. During this transition period, both the callback and Promise-based versions of these functions will work correctly, and will both be documented.

To enable deprecation warnings for these updated functions, use the [`process.enablePromiseAPIs` runtime flag](../process.md#processenablepromiseapis).

When a majority of affected functions are migrated, this flag will be enabled by default and all developers will be able to see these deprecation warnings. At that time, the callback-based versions will also be removed from documentation. This document will be continuously updated as more functions are converted.

- [app.importCertificate(options, callback)](https://github.com/electron/electron/blob/master/docs/api/app.md#importCertificate)

- [contents.print([options], [callback])](https://github.com/electron/electron/blob/master/docs/api/web-contents.md#print)

A `Boolean` that controls whether or not deprecation warnings are printed to `stderr` when

formerly callback-based APIs converted to Promises are invoked using callbacks. Setting this to `true`

will enable deprecation warnings.

// deprecate a callback-based function in favor of one returning a Promise

promisify: <T extends (...args: any[]) => any>(fn: T): T => {

const fnName = fn.name || 'function'

const oldName = `${fnName} with callbacks`

const newName = `${fnName} with Promises`

const warn = warnOnce(oldName, newName)

return function (this: any, ...params: any[]) {

let cb: Function | undefined

if (params.length > 0 && typeof params[params.length - 1] === 'function') {

cb = params.pop()

}

const promise = fn.apply(this, params)

if (!cb) return promise

if (process.enablePromiseAPIs) warn()

return promise

.then((res: any) => {

process.nextTick(() => {

cb!.length === 2 ? cb!(null, res) : cb!(res)

})

return res

}, (err: Error) => {

process.nextTick(() => {

cb!.length === 2 ? cb!(err) : cb!()

})

throw err

})

} as T

},

// convertPromiseValue: Temporarily disabled until it's used

// deprecate a callback-based function in favor of one returning a Promise

promisifyMultiArg: <T extends (...args: any[]) => any>(fn: T /* convertPromiseValue: (v: any) => any */): T => {

const fnName = fn.name || 'function'

const oldName = `${fnName} with callbacks`

const newName = `${fnName} with Promises`

const warn = warnOnce(oldName, newName)

return function (this: any, ...params) {

let cb: Function | undefined

if (params.length > 0 && typeof params[params.length - 1] === 'function') {

cb = params.pop()

}

const promise = fn.apply(this, params)

if (!cb) return promise

if (process.enablePromiseAPIs) warn()

return promise

.then((res: any) => {

process.nextTick(() => {

// eslint-disable-next-line standard/no-callback-literal

cb!.length > 2 ? cb!(null, ...res) : cb!(...res)

})

}, (err: Error) => {

process.nextTick(() => cb!(err))

})

} as T

},

describe('promisify', () => {

const expected = 'Hello, world!'

let promiseFunc: (param: any) => Promise<any>

let warnings: string[]

const enableCallbackWarnings = () => {

warnings = []

deprecate.setHandler(warning => warnings.push(warning))

process.enablePromiseAPIs = true

}

beforeEach(() => {

deprecate.setHandler(null)

process.throwDeprecation = true

promiseFunc = param => new Promise((resolve) => resolve(param))

})

it('acts as a pass-through for promise-based invocations', async () => {

enableCallbackWarnings()

promiseFunc = deprecate.promisify(promiseFunc)

const actual = await promiseFunc(expected)

expect(actual).to.equal(expected)

expect(warnings).to.have.lengthOf(0)

})

it('only calls back an error if the callback is called with (err, data)', async () => {

enableCallbackWarnings()

const erringPromiseFunc = deprecate.promisify(

() => new Promise((resolve, reject) => {

reject(new Error('fail'))

})

)

{

const [err, data] = await new Promise(resolve => {

(erringPromiseFunc as any)((err: Error | undefined, data: any) => {

resolve([err, data])

}).catch(() => { /* silence deprecation warning */ })

})

expect(data).to.be.undefined()

expect(err).to.be.an.instanceOf(Error).with.property('message', 'fail')

}

{

const data = await new Promise(resolve => {

(erringPromiseFunc as any)((data: any) => { resolve(data) })

.catch(() => { /* silence deprecation warning */ })

})

expect(data).to.be.undefined()

}

})

it('warns exactly once for callback-based invocations', (done) => {

enableCallbackWarnings()

promiseFunc = deprecate.promisify(promiseFunc)

let callbackCount = 0

const invocationCount = 3

const callback = (actual: number) => {

expect(actual).to.equal(expected)

expect(warnings).to.have.lengthOf(1)

expect(warnings[0]).to.include('promiseFunc')

callbackCount += 1

if (callbackCount === invocationCount) {

done()

}

}

for (let i = 0; i < invocationCount; i += 1) {

(promiseFunc as any)(expected, callback)

}

})

})

promisify<T extends (...args: any[]) => any>(fn: T): T;

// convertPromiseValue: Temporarily disabled until it's used

promisifyMultiArg<T extends (...args: any[]) => any>(fn: T, /*convertPromiseValue: (v: any) => any*/): T;