ast-get-object^4.2.6

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 with application-specific matching and collection or replacement logic. Its find() and get() helpers select entries and traversal indexes; they do not replace this package’s whole-object matching API.

A migration must account for GET mode’s array of matching objects and SET mode’s ordered replacement array, as well as cloning and traversal of nested matches. Test these behaviors against your application’s inputs before switching.

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

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

API — getObj()

The main function getObj() is imported like this:

It’s a function which takes three input arguments:

The program has two modes:

• if two arguments were passed, it is GET mode
• if three arguments were passed, it is SET mode

Now, the function’s output depends which mode is it on:

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

API — version

You can import version:

API — types

This package is written in TypeScript and exports the type UnknownValueObj — a plain object with string keys and values of any type — the shape of the keyValPair argument and of each element of replacementContentsArr.

import type { UnknownValueObj } from "ast-get-object";

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.

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 you’re OK in this case — there was one finding, and one replacement in the array “cartridge”.

Result of the above will be:

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

Permalink to changelogChangelog