📎 Note

Version 2.0.0 contains a bug fix. Therefore, please update to the latest version.

fast-unset

🪄 Efficiently remove, replace, set or default object properties.

Index

• Note
• fast-unset
  • Index
• Usage
  • Deleting properties
  • Setting values
  • Modifiers
    • rule
    • value
  • Flags
    • deep
    • default
    • direct
  • Working with arrays
  • Known limitattions
• Example
• Benchmarking
• Tests
• Treeshaking
• API Reference
• Contribute
  • Getting started

Usage

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.

Deleting properties

funset(object, { prop: { nestedprop: null } }); // Short for …
funset(object, {
	prop: { rule: { nestedprop: { rule: null } } },
});

Setting values

funset(object, {
	prop: { value: new Date() },
});

Modifiers

rule

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

value holds what will get set to the property.

Flags

The value of a property may contain flags, such as deep or default, and the available modifies rule and value.

deep

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.

default

Only sets the value if the property did not occur at the position of your property.

funset(object, { prop: { default: true, value: null } });

direct

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 } } });

Working with arrays

let object = { value: [[{ prop: 1 }]] };

funset(object, { value: { rule: { prop: null } } });

As seen in this example, brackets must not necessarily get set.

Known limitattions

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

Example

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: {},
		},
	}

*/

Benchmarking

⚠️ Note that results may differ on different devices, runs and use cases. Also, when bundling packages, bundle sizes depend on the configuration you use.

| 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 |

Tests

The tests provided may not cover all edge cases. Feel free to suggest new ones or report missing ones.

Treeshaking

import { core } from 'fast-unset/dist/core';
// Same usage as funset while dropping argument `settings` and all argument type checking

API Reference

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

Contribute

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.

Getting started

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