Version 2.0.0 contains a bug fix. Therefore, please update to the latest version.
🪄 Efficiently remove, replace, set or default object properties.
Generally speaking - mimic the structure of the object to be mutated.
To remove a property, set its value to null or pass an object containing the property rule
set to null.
To set a property, pass it an object containing a value
property set to your desired value.
funset(object, { prop: { nestedprop: null } }); // Short for …
funset(object, {
prop: { rule: { nestedprop: { rule: null } } },
});
funset(object, {
prop: { value: new Date() },
});
rule
accepts either an array of objects, an object or null
.
When passing null
, the property will get removed. Otherwise, the object or the array passed will get treated as a path to an object.
value
holds what will get set to the property.
The value of a property may contain flags, such as deep
or default
, and the available modifies rule
and value
.
Applies your rule globally while only looking into the object of the property it got defined in.
Example:
funset(object, { prop: { deep: true, rule: null } });
The passed object will get searched for occurrences of property prop
. Findings will get removed - nested ones included.
The deep
flag may get used in combination with the default
flag.
Only sets the value if the property did not occur at the position of your property.
funset(object, { prop: { default: true, value: null } });
Treats the values of your property as if they were in a rule
modifier.
Passing the direct
flag will only be neccessary in the case of a nested property called value
or rule
. Otherwise, it is not required.
funset(object, { prop: { direct: true, value: null } });
The property value
of prop
will get removed.
The same behaviour can get achieved with the following.
funset(object, { prop: { rule: { value: null } } });
let object = { value: [[{ prop: 1 }]] };
funset(object, { value: { rule: { prop: null } } });
As seen in this example, brackets must not necessarily get set.
You cannot access the properties "direct" and "value" or "rule" in combination if nested. Alternatively, wrap them in a rule
modifier.
Example:
funset(
{ value: 1, rule: 1, direct: 1 }, // Object
{ value: null, rule: null, direct: null } // Modifier
); // No action required
funset(
{ prop: { value: 1, rule: 1, direct: 1 } }, // Object
{ prop: { rule: { value: null, rule: null, direct: null } } } // Modifier
); // See the modifier "rule" containing another set of modifiers
Find further examples at /src/__tests__/ or jump to section Usage.
import funset from 'fast-unset';
// const funset = require('fast-unset');
let object = {
secret: 'shhh',
morning: false,
child: [
[
{
morning: false,
secret: 'shhh',
child: {
morning: false,
},
},
],
],
nested: {
pin: 1234,
nested: {
anothersecret: 'shh',
},
},
};
let mofifier = {
secret: { deep: true, rule: null }, // Will remove all occurrences of property "secret"
child: { morning: { deep: true, rule: null } }, // Will remove all occurrences of property "morning" starting at property "child"
nested: {
pin: { value: null }, // Removes property "pin" of property "nested"
nested: { anothersecret: null }, // Will remove nested property "anothersecret"
},
// nested: {
// rule: [
// { pin: { value: null } },
// { nested: { rule: { anothersecret: { rule: null } } } },
// ],
// }, //! Also valid, though not recommended due to performance impact
};
let settings = {
clone: false, // Instead, working on a deep clone of the object
}; // Optional though
funset(object, mofifier, settings);
console.log(object);
/* Outputs the following …
{
morning: false,
child: [
[
{
child: {},
},
],
],
nested: {
pin: null,
nested: {},
},
}
*/
library | deep clone | result | runs sampled | performance | bundle size (min + gz) |
---|---|---|---|---|---|
fast-redact | false | 981,388 ops/sec ±0.57% | 93 | 21.9% | - |
unset-value | false | 2,252,566 ops/sec ±0.49% | 95 | 50.2% | 1.8 kB |
fast-unset | true | 2,300,278 ops/sec ±0.49% | 96 | 51.3% | 1.3 kB |
fast-unset | false | 4,451,021 ops/sec ±0.46% | 95 | 99.3% | 1.3 kB |
fast-unset (core) | false | 4,484,568 ops/sec ±0.40% | 92 | 100% | 600 B |
The tests provided may not cover all edge cases. Feel free to suggest new ones or report missing ones.
import { core } from 'fast-unset/dist/core';
// Same usage as funset while dropping argument `settings` and all argument type checking
import funset from 'fast-unset';
// const funset = require("fast-unset");
funset(input, modifier, settings) => Object
The function provided is constrained to the following arguments while always returning an object or throwing errors:
input
- required
- type: object or an array of objects
modifier
- required
- type: object or an array of objects
settings
- optional
- type: object
- valid options
clone
- defaults to false
- type: boolean
- description: creates a deep clone of
object
before continuing with the process
New ideas, as well as thoughts on this project and pull requests, are very welcome. Please make sure all tests pass before creating a pull request.
After forking, install all (dev-)dependencies by running the following.
npm i
Make sure husky is being installed too.
npm run prepare
And off we go …
Build this project with the following.
npm run build
Eventually, run your tests.
npm run test
npm run test:watch