ast-delete-object^4.2.7

This package is retired. The published package, documentation, examples, and changelog remain available.

Retirement

This package has been retired and is no longer maintained.

For new tree transformations, use the ast-monkey traversal API and define which objects your application removes. ast-compare can help implement subset matching, and the traversal’s DELETE token removes a visited entry.

This requires a migration: ast-delete-object matches whole objects, accepts different input shapes, and returns an empty object when the root matches. Preserve the matching rules and root behavior your application needs in tests before switching.

The API documentation below is archived. Archived examples, the changelog, and the published package on npm remain available.

Purpose

It deletes objects in AST if all given keys-value pairs are matched.

API — deleteObj()

The main function deleteObj() is imported like this:

It’s a function which takes three input arguments:

None of the input arguments will be mutated by this program, we have unit tests to prove that.

The Optional Options Object has the following shape:

Here are all defaults in one place for copying:

The function will return the clone of first input argument with relevant elements deleted.

API — defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — version

You can import version:

API — types

This package is written in TypeScript and exports the following types:

import type { JsonArray, JsonObject, JsonValue, Opts } from "ast-delete-object";

opts.matchKeysStrictly

If you want the search to be strict, that is to require the key set to match exactly, use options object, matchKeysStrictly: true:

import { deleteObj } from "ast-delete-object";
let res = deleteObj(
  [
    "elem1",
    {
      findme1: "zzz",
      findme2: "yyy",
      somethingelse: "qqq", // <--- this key will block deletion
    },
    "elem2",
  ],
  {
    findme1: "zzz",
    findme2: "yyy",
  },
  {
    matchKeysStrictly: true, // <--- strict matching
  },
);
console.log("res = " + JSON.stringify(res, null, 4));
// => nothing changes!
// [
//   'elem1',
//   {
//     findme1: 'zzz',
//     findme2: 'yyy',
//     somethingelse: 'qqq'
//   },
//   'elem2'
// ]

In example above, object was not deleted because strict matching ignored it because of unrecognised key somethingelse.

opts.hungryForWhitespace

This is a library to deal with AST’s, and they usually have lots of white space. Often there are many elements that contains only spaces, tabs or line breaks. Sometimes you want to pretend that those elements containing white space don’t exist, so deletion is more aggressive regarding the white space.

For example, notice how looking for a blank plain object also catches other objects that contain only empty space:

import deleteObj from "ast-delete-object";
let res = deleteObj(
  [
    { a: "\n" },
    {
      key3: "val3",
      key4: "val4",
    },
    { b: "   " },
    { c: "" },
  ],
  {},
  { matchKeysStrictly: false, hungryForWhitespace: true },
);
console.log("res = " + JSON.stringify(res, null, 4));
// =>  [{
//      key3: 'val3',
//      key4: 'val4'
//    }]

Context

Originally, this program was created to help us delete unused CSS (as objects) from parsed HTML (AST tree) in email-comb. Since then, we’ve rewritten email-comb to process the code without parsing, without AST. email-comb became faster by magnitude (milliseconds instead of seconds/minutes).

Permalink to changelogChangelog