It appears that the code provided is quite extensive for this particular issue.

One suggestion would be to organize the list of nodes into an array of nodes still available for adding children, sorted by their depth levels. We can initiate with a starting node at depth 0 and eventually retrieve the children of the initial node upon completion.

If maintaining the 'depth' properties on the nodes is not a concern, then the solution presented should suffice. Otherwise, wrapping it in a straightforward function to recursively eliminate these properties would be necessary.

Below is one version of a potential solution:

A revised version of the code snippet...

.as-console-wrapper {max-height: 100% !important; top: 0}

The key challenge lies in sustaining the current list of open arrays. This is achieved by identifying the last node in the list with a lesser depth level than the current node, appending the current node as its child, truncating the list at that point, and incorporating the current node into it. The progression of this array can be tracked as we continually add nodes based on your examples.

// Updated list illustration 
[
  {depth: 0, headings: [], text: null}
]
// Subsequent additions demonstrated...

I trust that this proposed solution is notably simpler compared to your existing approach. Nevertheless, I acknowledge not having delved deeply into your method as it appeared rather convoluted for a problem of moderate complexity.

After delving into Typescript, I successfully tackled this challenge.

Although I lack expertise in this language, the code functions well. A more seasoned individual may be able to optimize it further.

The objective was to transform any list of H1..6 into a Hierarchy and then filter to generate a helpful Table of Content.

Screenshot of Output

https://i.sstatic.net/wqGf5.png

Heading.ts

export default class Heading {
  text: string;
  slug: string;
  depth: number;
  sequence: number;

  parent: Heading | null;
  headings: Heading[] | null;

  constructor(text: string, slug: string, depth: number, sequence: number) {
    this.text = text;
    this.slug = slug;
    this.depth = depth;
    this.sequence = sequence;

    this.parent = null;
    this.headings = null;
  }

  add_heading(heading: Heading) {
    heading.parent = this;
    if (this.headings === null) {
      this.headings = [];
    }
    this.headings.push(heading);
  }

  root() {
    return this.depth === 0;
  }

  valid() {
    return this.depth > 0;
  }

  data() {
    let result: any = {
      text: this.text,
      slug: this.slug,
      depth: this.depth,
      sequence: this.sequence,
      headings: this.headings?.map((h) => h.data()),
    };
    return result;
  }
}

CreateToc.ts

import Heading from './heading';

export default class CreateToc {
  toc: Heading;
  current_heading: Heading;

  constructor() {
    this.toc = new Heading("*", '-', 0, -1);
    this.current_heading = this.toc;
  }

  process(astro_headings: any[]) {
    astro_headings.forEach((astro_heading, index) => {
      let heading = new Heading(
        astro_heading.text,
        astro_heading.slug,
        astro_heading.depth,
        index
      );
      this.process_heading(heading);
    });
    return this.data();
  }

  debug() {
    console.log(JSON.stringify(this.data(), null, 2));
  }

  private data() {
    return (this.toc.headings || []).map((h) => h.data());
  }

  private process_heading(heading: Heading) {
    if (heading.depth > this.current_heading.depth) {
      this.add_child_heading(heading);
    } else if (heading.depth === this.current_heading.depth) {
      this.add_sibling_heading(heading);
    } else if (heading.depth < this.current_heading.depth) {
      this.add_upstream_heading(heading);
    }
  }

  private add_child_heading(heading: Heading) {
    this.current_heading.add_heading(heading);
    this.current_heading = heading;
  }

  private add_sibling_heading(heading: Heading) {
    if (this.current_heading!.parent === null) {
      return;
    }
    this.current_heading = this.current_heading.parent;
    this.add_child_heading(heading);
  }

  private add_upstream_heading(heading: Heading) {
    while (this.current_heading.valid() && heading.depth < this.current_heading.depth) {
      if (this.current_heading.parent === null) {
        throw new Error("current_heading.parent is null");
      }

      this.current_heading = this.current_heading.parent;
    }

    // There is no upstream heading to attach to, so just add a new root node
    if (this.current_heading.root()) {
      return this.add_child_heading(heading);
    }

    this.add_sibling_heading(heading);
  }
}

Example Usage

let filterHeadings = headings
  .filter((heading) => heading.depth === 2 || heading.depth === 3)

let tocHeadings = (new CreateToc()).process(filterHeadings);

Sample Data

[
  {
    "text": "Traits for data variation",
    "slug": "traits-for-data-variation",
    "depth": 2,
    "sequence": 0,
    "headings": [
      {
        "text": "User with role flag",
        "slug": "user-with-role-flag",
        "depth": 3,
        "sequence": 1
      },
      {
        "text": "Blog article in draft mode",
        "slug": "blog-article-in-draft-mode",
        "depth": 3,
        "sequence": 2
      }
    ]
  },
  {
    "text": "Enum Traits (non ActiveRecord)",
    "slug": "enum-traits-non-activerecord",
    "depth": 2,
    "sequence": 3,
    "headings": [
      {
        "text": "#traits_for_enums",
        "slug": "traits_for_enums",
        "depth": 3,
        "sequence": 4
      }
    ]
  },
  {
    "text": "Get a list of available traits",
    "slug": "get-a-list-of-available-traits",
    "depth": 2,
    "sequence": 5,
    "headings": [
      {
        "text": "#defined_traits",
        "slug": "defined_traits",
        "depth": 3,
        "sequence": 6
      }
    ]
  },
  {
    "text": "Global traits",
    "slug": "global-traits",
    "depth": 2,
    "sequence": 7
  }
]