# safe-extend

> safe extend (Simple function to extend objects)

Latest version **3.0.6** (published 2019-05-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install safe-extend
pnpm add safe-extend
yarn add safe-extend
bun add safe-extend
```

## 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.6 |
| Published | 2019-05-28 |
| First published | 2018-03-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 10.3 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | nimojs |
| Maintainers | grifree, nimojs |
| Keywords | extend, safe-extend |

## Links

- npm: https://www.npmjs.com/package/safe-extend
- Repository: https://github.com/onface/safe-extend
- Homepage: https://github.com/onface/safe-extend#readme
- Issues: https://github.com/onface/safe-extend/issues
- npm.io page: https://npm.io/package/safe-extend

## Dependencies (1)

- [extend](https://npm.io/package/extend.md) 3.0.1

## Recent versions

- 3.0.6 (latest) — 2019-05-28
- 3.0.5 — 2018-04-27
- 3.0.4 — 2018-04-08
- 3.0.3 — 2018-03-21
- 3.0.2 — 2018-03-21
- 3.0.1 — 2018-03-21

## README

# safe-extend

---

1. Javascript is always pass by value, but when a variable refers to an object (including arrays), the "value" is a reference to the object.

2. Changing the value of a variable never changes the underlying primitive or object, it just points the variable to a new primitive or object.

3. However, changing a property of an object referenced by a variable does change the underlying object.

When you use [extend](https://www.npmjs.com/package/extend), you will encounter the above problem. safe-extend has deep copy all the parameters, so it avoids this problem.

**Thanks to ljharb and justmoon.**

**Notes:** safe-extend are based entirely on [extend](https://www.npmjs.com/package/extend). This is just a syntactic sugar.

```shell
npm install safe-extend
```

```js
var target = {a:1}
var obj = {b:2}

safeExtend(true, target, obj)
// equal
extend(
    true,
    extend(true, {}, target),
    extend(true, {}, obj)
)


safeExtend.clone(target) // deep copy
// equal
var emptyData = Array.isArray(target)? []: {}
extend(true, emptyData, target)
```

---

`extend` is a port of the classic extend() method from jQuery. It behaves as you expect. It is simple, tried and true.

Notes:

* Since Node.js >= 4,
  [`Object.assign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign)
  now offers the same functionality natively (but without the "deep copy" option).
  See [ECMAScript 2015 (ES6) in Node.js](https://nodejs.org/en/docs/es6).
* Some native implementations of `Object.assign` in both Node.js and many
  browsers (since NPM modules are for the browser too) may not be fully
  spec-compliant.
  Check [`object.assign`](https://www.npmjs.com/package/object.assign) module for
  a compliant candidate.

## Installation

``` sh
npm install safe-extend
```

## Usage

**Syntax:** extend **(** [`deep`], `target`, `object1`, [`objectN`] **)**

*Extend one object with one or more others, returning the modified object.*

**Example:**

``` js
var extend = require('safe-extend');
extend(targetObject, object1, object2);
```

Keep in mind that the target object will be modified, and will be returned from extend().

If a boolean true is specified as the first argument, extend performs a deep copy, recursively copying any objects it finds. Otherwise, the copy will share structure with the original object(s).
Undefined properties are not copied. However, properties inherited from the object's prototype will be copied over.
Warning: passing `false` as the first argument is not supported.

### Arguments

* `deep` *Boolean* (optional)
If set, the merge becomes recursive (i.e. deep copy).
* `target`	*Object*
The object to extend.
* `object1`	*Object*
The object that will be merged into the first.
* `objectN` *Object* (Optional)
More objects to merge into the first.

## License

`extend` is licensed under the MIT License.
`safe-extend` is licensed under the MIT License

## Acknowledgements

All credit to the jQuery authors for perfecting this amazing utility.

Ported to Node.js by [Stefan Thomas][github-justmoon] with contributions by [Jonathan Buchanan][github-insin] and [Jordan Harband][github-ljharb].

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