object-delete-key^1.9.38

Delete keys from all arrays or plain objects, nested within anything, by key or by value or by both, and clean up afterwards. Accepts wildcards.

Install globally, via npm

npm i object-delete-key

The default is exported, so instead of "deleteKey" below, you can name the consumed function however you want.

Consume via a require():

const deleteKey = require("object-delete-key");

or as an ES Module:

import deleteKey from "object-delete-key";

Install as a script, via CDN

Put this in your HTML:

<script src="https://cdn.jsdelivr.net/npm/object-delete-key/dist/object-delete-key.umd.js">

Then, you’ll get a global variable objectDeleteKey in your Global object and you consume it like this:

const deleteKey = objectDeleteKey;

This deleteKey is your main function. See its API in the main section.

Trivia

This program has 63 assertions in its unit tests. That's more than all unit test assertions' median (52) but less than geometric mean (71).

In monorepo, one other package, object-delete-key, consumes this package.

§ Quick Take

import { strict as assert } from "assert";
import deleteKey from "object-delete-key";

// deleting key 'c', with value 'd'
assert.deepEqual(
  deleteKey(
    {
      a: "b",
      c: "d",
    },
    {
      key: "c",
      val: "d",
    }
  ),
  { a: "b" }
);

// deleting key 'b' with value - array ['c', 'd']
assert.deepEqual(
  deleteKey(
    {
      a: { e: [{ b: ["c", "d"] }] },
      b: ["c", "d"],
    },
    {
      key: "b",
      val: ["c", "d"],
    }
  ),
  {}
);
// notice program cleaned after itself, it didn't leave empty "a" key

⬆ back to top

§ Examples

⬆ back to top

§ Deleting

Three modes:

Delete all key/value pairs found in any nested plain objects where key equals value.
Delete all key/value pairs found in any nested plain objects where key is equal to a certain thing. value doesn't matter.
Delete all key/value pairs found in any nested plain objects where value is equal to a certain thing. key doesn't matter.

This library accepts anything as input, including parsed HTML, which is deeply nested arrays of plain objects, arrays and strings. You can feed anything as input into this library - if it's traversable, it will be traversed and searched for your key and/or value in any plain objects.

If you want to delete any nested objects that contain certain key/value pair(s), check out ast-delete-object.

⬆ back to top

§ API

deleteKey(input, options)

In other words, it's a function which takes two input arguments, both obligatory.

The input arguments are not mutated; this package clones them first before using.

⬆ back to top

§ API - Input

Input argument	Type	Obligatory?	Description
`input`	Whatever	yes	AST tree, or object or array or whatever. Can be deeply-nested.
`options`	Object	yes	Options object. See its key arrangement below.

`options` object's key	Type	Obligatory?	Default	Description
`key`	String	no^	n/a	Key to find and delete.
`val`	Whatever	no^	n/a	Key's value to find and delete. Can be a massively nested AST tree or whatever.
`cleanup`	Boolean	no	true	Should this package delete any empty carcases of arrays/objects left after deletion?
`only`	String	no	`any`	Default setting will delete from both arrays and objects. If you want to delete from plain objects only, set this to one of "object-type" values below. If you want to delete keys from arrays only, set this to one of "array-type" values below. In this case "key" means array element's value and "value" is not meant to be used.

^ - at least one, key or val must be present.

⬆ back to top

§ Accepted `opts.only` values

Interpreted as "array-type"	Interpreted as "object-type"	Interpreted as "any" type
`array`	`object`	`any`
`arrays`	`objects`	`all`
`arr`	`obj`	`everything`
`aray`	`ob`	`both`
`arr`	`o`	`either`
`a`		`each`
		`whatever`
		`e`

If opts.only is set to any string longer than zero characters and is not case-insensitively equal to one of the above, the object-delete-key will throw an error.

We want to relieve users from having to check the documentation for opts.only values.

⬆ back to top