# ugly-adapter

> get promises out of standard callback APIs

Latest version **1.3.1** (published 2016-01-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install ugly-adapter
pnpm add ugly-adapter
yarn add ugly-adapter
bun add ugly-adapter
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.1 |
| Published | 2016-01-31 |
| First published | 2015-02-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | gregreimer@gmail.com |
| Maintainers | greim |
| Keywords | promise, callback, es6, es2015, es7, es2016, yield, thenable, yieldable, thunk, async, await, promisify, promify |

## Links

- npm: https://www.npmjs.com/package/ugly-adapter
- Repository: https://github.com/greim/ugly-adapter
- Homepage: https://github.com/greim/ugly-adapter#readme
- Issues: https://github.com/greim/ugly-adapter/issues
- npm.io page: https://npm.io/package/ugly-adapter

## Dependencies (1)

- [any-promise](https://npm.io/package/any-promise.md) ^1.0.0

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 1.3.1 (latest) — 2016-01-31
- 1.3.0 — 2016-01-31
- 1.2.0 — 2015-10-10
- 1.1.1 — 2015-07-28
- 1.1.0 — 2015-04-22
- 1.0.4 — 2015-02-19
- 1.0.3 — 2015-02-17
- 1.0.2 — 2015-02-17
- 1.0.1 — 2015-02-17
- 1.0.0 — 2015-02-17

## README

# Universal Callback => Promise Adapter

With [Koa](http://koajs.com/) and [ES7 async functions](https://jakearchibald.com/2014/es7-async-functions/) gaining prominence, the JavaScript world is poised to transition to promises.
That means we need a sane way to *promisify* callback-based APIs.
Rather than importing lots of different promisification wrappers for each API, this lib provides a single way to promisify every API.

## Install

```bash
npm install ugly-adapter
```

## Use

```js
import adapt from 'ugly-adapter';
...
var data = await adapt(fs.readFile, './data.txt', 'utf8');
```

This lib also exposes methods to make partial application easier.
Which is useful if you want to re-use an adapted version of a function.

```js
var read = adapt.part(fs.readFile);
var data1 = await read('./data1', 'utf8');
var data2 = await read('./data2', 'utf8');
```

# API

## Call a bare function: `adapt()`

Useful when you don't think a function cares about `this`.

```js
// signature
var promise = adapt(<function>, ...args)

// fs.readFile(path, enc, callback) example
adapt(fs.readFile, './data.txt', 'utf8').then(...)
```

## Call a method on an object: `adapt.method()`

Useful when you think a function definitely cares about `this`.

```js
// signature
var promise = adapt.method(<object>, <string>, ...args)

// user.authenticate(opts, callback) example
var user = new User()
adapt.method(user, 'authenticate', {
  userName: userName,
  password: password
}).then(...)
```

## Partially apply a bare function: `adapt.part()`

```js
// signature
var fn = adapt.part(<function>, ...args)

// example
var stat = adapt.part(fs.stat, './data.txt', 'utf8')
stat().then(...)
```

## Partially apply a method on an object: `adapt.method.part()`

```js
// signature
var fn = adapt.method.part(<object>, <string>, ...args)

// example
var user = new User()
var authenticate = adapt.method.part(user, 'authenticate')
authenticate({
  userName: userName,
  password: password
}).then(...)
```

A note about partial application.
You can basically move the `)(` around willy-nilly.

```js
// these behave identically
var promise = adapt.part(a,b,c)()
var promise = adapt.part(a,b)(c)
var promise = adapt.part(a)(b,c)
var promise = adapt.part()(a,b,c)
```

## Promify a library: `adapt.promify(lib)`

You can promisify entire library modules, such as `fs`.
It will return an object with all the same properties and functions.
The functions have the same signature—sans callback—and return promises.

```js
var adapt = require('ugly-adapter')
  , callbackFs = require('fs')
  , fs = adapt.promify(callbackFs);

fs.stat(...).then(...);
```

The above promifies every function in the `fs` module.
If you only want to promify a subset of functions, declare them in a whitelist.

```js
var adapt = require('ugly-adapter')
  , callbackFs = require('fs')
  , fs = adapt.promify(callbackFs, 'stat', 'readFile');

fs.stat(...).then(...);
fs.readFile(...).then(...);
fs.link(...).then(...); // error, wasn't in the whitelist!
```

# Async/Await Example

Now that we can convert callbacks to promises, we can write async functions everywhere.

```js
async function jsonReadFile(path, encoding) {
  let data = await adapt(fs.readFile, encoding);
  data = JSON.parse(data);
  return data;
}
```

# Any Promise

Ugly adapter uses [any-promise](https://github.com/kevinbeaty/any-promise) promises. This is something you can safely ignore and everything works normally. However, if you want to polyfill/replace your environment's Promise for whatever reason, this allows you swap in whatever conforming Promise you want and this library will use it.

---
_Source: https://npm.io/package/ugly-adapter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._