ast-get-object^3.0.1

Getter/setter for nested parsed HTML AST's, querying objects by key/value pairs

Install via npm

npm i ast-get-object

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required:

import { getObj } from "ast-get-object";

If you need a legacy version which works with require, use version 2.1.0:

"ast-get-object": "2.1.0",

Install as a script, via CDN

Put this in your HTML:

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

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

const { getObj } = astGetObject;

Trivia

This program has 20 assertions in its unit tests. That's less than all unit test assertions' median (48) and less than geometric mean (70).

Purpose

It is a helper function to extract plain objects by certain key-value pairs (if two input arguments given) OR to replace those findings (if three input arguments given).

↑ back to top

API

getObj(
  input,
  keyValPairObj,
  [replacementContentsArr]
)

In other words, it's a function which takes two or three input arguments.

↑ back to top

Input argument	Type	Obligatory?	Description
`input`	Whatever	yes	AST tree, or object or array or whatever. Can be deeply-nested.
`keyValPairObj`	Plain object	yes	Key/value pairs to look for.
`replacementContentsArr`	Arrray	no	The array of new values to set the findings objects. Those values can even be massive nested trees of plain objects and arrays. It doesn't matter.

API - Output

Output depends on is it GET mode — 2 arguments, or SET mode — 3 arguments.

If it's GET mode, result will be an array of parent objects that hold key/value pairs you asked.
If it's SET mode, result will be of the same type as your input, but with all plain objects that had your key/value pairs replaced with contents of third, replacement array. Mind you, if you will supply too few elements in the replacements array, this library won't do anything to those findings.

↑ back to top

For example, reading or querying parsed trees (GET)

Let's GET all plain objects that contain key tag and value meta. In a true parsed-HTML fashion, everything is in an array, and there are other plain objects around:

const result = getObj(
  [
    // <- search in this, the first argument, in this case, a nested array
    {
      tag: "meta",
      content: "UTF-8",
      something: "else",
    },
    {
      tag: "title",
      attrs: "Text of the title",
    },
  ],
  {
    // <- search for this object, the second argument
    tag: "meta",
  }
);

result — each parent object that holds your requested key/value pair(s) is put into an array:

[
  {
    tag: "meta",
    content: "UTF-8",
    something: "else",
  },
];

All findings are always wrapped in an array, even if there's just one finding as above.

↑ back to top

Writing-over example (SET)

Task: take this nested array of plain objects:

[
  {
    tag: ["two", "values"],
    content: "UTF-8",
    something: "else",
  },
  {
    tag: "title",
    attrs: "Text of the title",
  },
];

Find all plain objects that contain key tag and value ['two', 'values'] (so value is an array!).

Replace all those plain objects with:

{
  tag: ['three', 'values', 'here'],
  content: 'UTF-8',
  something: 'else'
}

Solution:

getObj(
  [
    {
      tag: ["two", "values"],
      content: "UTF-8",
      something: "else",
    },
    {
      tag: "title",
      attrs: "Text of the title",
    },
  ],
  {
    tag: ["two", "values"],
  },
  [
    {
      tag: ["three", "values", "here"],
      content: "UTF-8",
      something: "else",
    },
  ]
);

PS. Notice that replacement is put into an array. Also, keep in mind that array is like a cartridge — it will expect a separate value for each finding, so we're OK in this case — there was one finding, and one replacement in our array "cartridge".

Result of the above will be:

[
  {
    tag: ["three", "values", "here"],
    content: "UTF-8",
    something: "else",
  },
  {
    tag: "title",
    attrs: "Text of the title",
  },
];