# xfn

> Extends a function object with configured versions of itself.

Latest version **1.0.0** (published 2018-05-22) · MIT license · 0 weekly downloads

## Install

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

## 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.0.0 |
| Published | 2018-05-22 |
| First published | 2018-02-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=7.0.0 |
| Dependencies | 11 |
| Unpacked size | 8.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | John Lamansky |
| Maintainers | lamansky |
| Keywords | extend, function, property, plural, options, presets |

## Links

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

## Dependencies (11)

- [jfn](https://npm.io/package/jfn.md) ^1.0.0
- [qfn](https://npm.io/package/qfn.md) ^1.0.1
- [sbo](https://npm.io/package/sbo.md) ^1.1.0
- [wfn](https://npm.io/package/wfn.md) ^1.0.0
- [arrify](https://npm.io/package/arrify.md) ^1.0.1
- [unarray](https://npm.io/package/unarray.md) ^1.0.0
- [plainify](https://npm.io/package/plainify.md) ^1.0.0
- [array-pad](https://npm.io/package/array-pad.md) 0.0.1
- [is-plain-object](https://npm.io/package/is-plain-object.md) ^2.0.4
- [entries-iterator](https://npm.io/package/entries-iterator.md) ^1.4.0
- [@lamansky/is-number](https://npm.io/package/@lamansky/is-number.md) ^1.0.0

## Recent versions

- 1.0.0 (latest) — 2018-05-22
- 0.0.0 — 2018-02-03

## README

# Extended Function (xfn)

Extends a function object with configured versions of itself.

## Installation

Requires [Node.js](https://nodejs.org/) 7.0.0 or above.

```bash
npm i xfn
```

## Tutorial

### Singular/Plural

`xfn` simplifies the process of creating singular and plural versions of the same function (e.g. `get()` and `get.all()`). The function that you write is the plural version, and `xfn` creates the singular version. The following example uses `each` as the name of the plural function:

```javascript
const xfn = require('xfn')

const getFirstOf = xfn({
  pluralProp: 'each',
  pluralReturn: true,
}, arrs => arrs.map(arr => arr[0]))

const arr = [[1, 2], ['a', 'b']]

getFirstOf(arr) // [1, 2]
getFirstOf.each(arr) // [[1], ['a']]
```

The first call treats `arr` as a single array, while the second call treats `arr` as an array of arrays.

### Preset Options

`xfn` lets you create subfunctions that have certain options preconfigured. For example, you can replace `fn(arg, {option: true})` with `fn.option(arg)`.

```javascript
const getOwnProperty = require('get-own-property')
const xfn = require('xfn')

const get = xfn({
  optionArg: 2, // The index of the parameter that contains the options
  optionProps: {own: {own: true}},
}, (obj, key, {own} = {}) => own ? getOwnProperty(obj, key) : obj[key])

class Cls {
  get inherited () { return 123 }
}

const obj = new Cls()
obj.mine = 456

get(obj, 'mine') // 456
get(obj, 'inherited') // 123
get.own(obj, 'mine') // 456
get.own(obj, 'inherited') // undefined
```

## API

The module exports a single function.

### Parameters

1. Object argument:
    * Optional: `pluralArg` (positive integer): The zero-based index of the argument that should be singularized if `pluralProp` is set. Defaults to `0`.
    * Optional: `pluralFirst` (boolean): If `true`, the `pluralProp` comes before the `optionProps` when they are both set. Defaults to `false`. (For example: a `pluralProp` of `all` and an `optionProps` key of `in` will result in a property chain of `all.in()` if `true`, or `in.all()` if `false`.)
    * Optional: `pluralProp` (string or symbol): If set, the returned function will be a singularized version of `fn`, and the original `fn` will be attached to the `pluralProp` property of the returned function (e.g. if `pluralProp` is set to `'all'` and the returned function is assigned to the variable `get`, the available functions will be `get()` and `get.all()`).
    * Optional: `pluralReturn` (boolean): Only applies if `pluralProp` is set. Set to `true` if `fn` returns an array of one result per argument. (This will cause the one-element result array to be unwrapped when the singularized function is called.) Set to `false` if `fn` returns a result that does not correspond to the number of arguments. Defaults to `false`.
    * Required if `optionProps` is set: `optionArg` (positive integer): The zero-based index of the argument into which the preconfigured options of `optionProps` should be inserted.
    * Optional: `optionProps` (object or Map): A collection whose keys are the desired `fn` property keys and whose values are the option objects that should be merged into the plain object argument at index `optionArg`.
    * Optional: `sbo` (object or false): Options to be passed to the [`sbo`](https://github.com/lamansky/sbo) module (which adds support for the bind operator), or `false` if you do not want the `sbo` module applied.
2. `fn` (function): The main function that should be extended on the basis of the arguments in the first parameter.

### Return Value

A function object with `pluralProp` and/or `optionProps` properties.

## Related

This module is part of the `fn` family of modules.

* [efn](https://github.com/lamansky/efn): Extracted Function
* [ffn](https://github.com/lamansky/ffn): Filtering Function
* [jfn](https://github.com/lamansky/jfn): Joined Function
* [mfn](https://github.com/lamansky/mfn): Memoized Function
* [ofn](https://github.com/lamansky/ofn): Overloaded Function
* [pfn](https://github.com/lamansky/pfn): Possible Function
* [qfn](https://github.com/lamansky/qfn): Qualified Function
* [vfn](https://github.com/lamansky/vfn): Variadic Function
* [wfn](https://github.com/lamansky/wfn): Wrapper Function

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