# beforefn

> Execute a function before a function.

Latest version **3.0.1** (published 2015-12-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install beforefn
pnpm add beforefn
yarn add beforefn
bun add beforefn
```

## 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 | 3.0.1 |
| Published | 2015-12-26 |
| First published | 2014-06-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Tim Oxley |
| Maintainers | timoxley |
| Keywords | aspect, aop, functional, oriented |

## Links

- npm: https://www.npmjs.com/package/beforefn
- Repository: https://github.com/timoxley/beforefn
- Issues: https://github.com/timoxley/beforefn/issues
- npm.io page: https://npm.io/package/beforefn

## Recent versions

- 3.0.1 (latest) — 2015-12-26
- 2.3.1 — 2014-08-17
- 2.3.0 — 2014-07-09
- 2.2.0 — 2014-06-18
- 2.1.0 — 2014-06-18
- 2.0.0 — 2014-06-17
- 1.0.0 — 2014-06-17

## README

# beforefn

### Execute a function before a function.

[![Build Status](https://travis-ci.org/timoxley/beforefn.svg)](https://travis-ci.org/timoxley/beforefn)

```js
var before = require('beforefn')

// replace user.save with a function that executes
// customBeheviour() before every .save  call
user.save = before(user.save, function() {
  customBehaviour()
})

// roughly equivalent to
var oldSave = user.oldSave
user.save = function() {
  customBehaviour()
  return oldSave.apply(this, arguments)
}
```

## API Facts

* `beforefn` returns a new Function.
* Original arguments will be passed as the second argument to the before function.
* Original function will be passed as the third argument to the before function.
* Properties and prototype are only inherited if you use `before.inherit`. Function arity will not be preserved.
* To use with a constructor function, you'll need to use `before.inherit`.

## Differences between beforefn 2.x and 3.x

`beforefn` 3.x no longer inherits properties from the function you're
wrapping. In many cases this is not needed, and the inheritance slows
down beforefn by ~300%. Blame V8.

## Examples

```js

var user = {
  name: 'tim oxley',
  save: function() {
    // save routine
  },
  formatName: function() {
    this.name = this.name.toUpperCase()
  }
}

// always calls 'user.formatName' before 'user.save'
user.save = before(user.save, user.formatName)

console.log(user.name) // => tim oxley
user.save()
console.log(user.name) // => TIM OXLEY

```

### Modify arguments

```js
function add(a, b) {
  return a + b
}

var addByTen = before(add, function fn(a, b) {
  fn.args = fn.args.map(function(x) { return x * 10 })
})

console.log(add(1,2)) // => 3
console.log(addByTen(1,2)) // => 30

```

### Fix context

```js

var user = {
  name: 'hodor',
  speak: function() {
    return this.name
  }
}

user.speak = before(user.speak, function() {
  this.name = this.name[0].toUpperCase() + this.name.slice(1)
}, user)


console.log(user.speak()) // => 'Hodor'

// Reset name
user.name = 'hodor'

// Original function runs in call-time context
console.log(user.speak.call({name: 'bran'})) // => 'bran'

// But the before function runs in context set when defined
console.log(user.name) // => 'Hodor'

```

### Adjust Context

```js

var user = {
  name: 'hodor',
  speak: function() {
    return this.name
  }
}

user.speak = before(user.speak, function fn() {
  // make 'this' in all 'befores' effectively immutable
  fn.context = Object.create(this)
})

user.speak = before(user.speak, function fn() {
  this.name = this.name[0].toUpperCase() + this.name.slice(1)
}, user)


console.log(speak()) // => 'Hodor'

// the 'this' was altered when the function ran,
// but the original object is unmodified due to
// the Object.create(this)

console.log(user.name) // => 'hodor'

```

## Performance

As of `beforefn` 2.2.0, `beforefn` performs comparably to a manually replaced function. 

```
iterations 700000
...
366ms - manually replaced function
299ms - using before function
...
```

```js

test('manually replaced function', function() {
  var user = setup()
  var s = user.speak
  user.speak = function() {
    this.name = this.name.toUpperCase()
    return s.apply(this, arguments)
  }
  user.speak()
})

test('using before function', function() {
  var user = setup()
  function a() {
    this.name = this.name.toUpperCase()
  }
  user.speak = before(user.speak, a)
  user.speak()
})
```
Other runnable benchmarks are located in [bench/index](/bench/index).

## See Also

* [timoxley/guardfn](http://github.com/timoxley/guardfn)
* [timoxley/afterfn](http://github.com/timoxley/afterfn)
* [timoxley/namefn](http://github.com/timoxley/namefn)

## License

MIT

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