Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 

README.md

jQuery.extendext

npm version jsDelivr CDN Build Status

jQuery.extend with configurable behaviour for arrays.

Isn't $.extend good enough ?

Well, it's actually pretty good, and is generally sufficient, but it merges arrays in a strange way depending of what you want. Example:

var DEFAULTS = {
  operators: ['AND', 'OR', 'XOR']
};

var config = {
  operators: ['OR', 'XOR']
};

config = $.extend(true, {}, DEFAULTS, config);

When executing this code, one will expects to get config.operators = ['OR', 'XOR'], but instead you get ['OR', 'XOR', 'XOR], because $.extend merges arrays like objects as per spec.

Other deep merging utilities I found either have the same behaviour or perform both merge and append on array values (nrf110/deepmerge for example).

Usage

jQuery.extendext.js contains a new $.extendext function with the exact same behaviour as $.extend if not additional config is provided.

The difference is that it accepts a optional second string argument to specify how arrays should be merged.

jQuery.extendext([deep ,][arrayMode ,] target, object1 [, objectN ] )
  • deep boolean — If true, the merge becomes recursive (aka. deep copy).
  • arrayMode string — Specify the arrays merge operation, either replace, concat, extend or default
  • target object — The object to extend. It will receive the new properties.
  • object1 object — An object containing additional properties to merge in.
  • objectN object — Additional objects containing properties to merge in.

"replace" mode

In this mode, every Array values in target is replaced by a copy of the same value found in objectN. The copy is recursive if deep is true.

var DEFAULTS = {
  operators: ['AND', 'OR', 'XOR']
};

var config = {
  operators: ['OR', 'XOR']
};

config = $.extendext(true, 'replace', {}, DEFAULTS, config);

assert.deepEqual(config, {
  operators: ['OR', 'XOR']
}) // true;

"concat" mode

In this mode, Arrays found in both target and objectN are always concatenated. If deep is true, a recursive copy of each value if concatenated instead of the value itself.

var DEFAULTS = {
  operators: ['AND', 'OR', 'XOR']
};

var config = {
  operators: ['OR', 'XOR']
};

config = $.extendext(true, 'concat', {}, DEFAULTS, config);

assert.deepEqual(config, {
  operators: ['AND', 'OR', 'XOR', 'OR', 'XOR']
}) // true;

"extend" mode

This is how nrf110/deepmerge works. In this mode, Arrays values are treated a bit differently:

  • If plain objects are found at the same position in both target and objectN they are merged recursively or not (depending on deep option).
  • Otherwise, if the value in objectN is not found in target, it is pushed at the end of the array.
var DEFAULTS = {
  operators: ['AND', 'OR', 'XOR']
};

var config = {
  operators: ['XOR', 'NAND']
};

config = $.extendext(true, 'extend', {}, DEFAULTS, config);

assert.deepEqual(config, {
  operators: ['AND', 'OR', 'XOR', 'NAND']
}) // true;

"default" mode

Same as $.extend.

var DEFAULTS = {
  operators: ['AND', 'OR', 'XOR']
};

var config = {
  operators: ['OR', 'XOR']
};

config = $.extendext(true, 'default', {}, DEFAULTS, config);

assert.deepEqual(config, {
  operators: ['OR', 'XOR', 'XOR']
}) // true;

Tests

A jest test suite is provided in tests directory.

$.extendext is tested against core jQuery tests for $.extend and nrf110/deepmerge tests (with the difference that extendext, like extend, modifies the first argument where deepmerge does not touch it).

About

jQuery.extend with configurable behaviour for arrays

Resources

License

You can’t perform that action at this time.