ast-get-values-by-key^2.8.1

Read or edit parsed HTML (or AST in general)

Install via npm

npm i ast-get-values-by-key

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

Consume via a require():

const getAllValuesByKey = require("ast-get-values-by-key");

or as an ES Module:

import getAllValuesByKey from "ast-get-values-by-key";

Install as a script, via CDN

Put this in your HTML:

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

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

const getAllValuesByKey = astGetValuesByKey;

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

Trivia

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

In monorepo, one other package, json-variables, consumes this package.

§ Quick Take

import { strict as assert } from "assert";
import getAllValuesByKey from "ast-get-values-by-key";

// GETTER
// ======

// returns "object-path" notation paths where arrays use dots:
assert.deepEqual(
  getAllValuesByKey(
    {
      parsed: [
        {
          tag: "html",
        },
      ],
    },
    "tag" // value to search for
  ),
  [{ val: "html", path: "parsed.0.tag" }]
);

// SETTER
// ======

assert.deepEqual(
  getAllValuesByKey(
    {
      parsed: [
        {
          tag: "html",
        },
      ],
      foo: {
        tag: null,
      },
      bar: {
        tag: null,
      },
    },
    "tag", // value to search for
    [123, 456] // pot of values to pick from (one result not enough)
  ),
  {
    parsed: [
      {
        tag: 123,
      },
    ],
    foo: {
      tag: 456,
    },
    bar: {
      tag: null, // value pot was depleted and there was nothing left to put here
    },
  }
);

⬆ back to top

§ Examples

program example: Replace All Null's in Keys amount With Zero, but Only under orders

⬆ back to top

§ Purpose

There are many ways to work with AST's — huge nested trees of objects and arrays. This program is one of possible ways.

Two arguments triggers the GET mode — it returns an array of objects with value-path findings.

If you map that into desired values array and run it again, this time putting desired values as third input argument, you get the SET mode.

⬆ back to top

§ API

getAllValuesByKey(input, whatToFind, replacement)

If two arguments are given, it's getter. You'll receive an array of zero or more plain objects with keys: val and path, where path follows object-path notation.
If three arguments are given, it's setter. You'll receive a copy of original input, changed accordingly.

This library does not mutate any input arguments.