util.ts

Overview

The util.ts file provides utility classes and functions primarily focused on processing and organizing graph nodes and edges into groups called "combos." It includes:

• A KeyGenerator class to generate single-character keys sequentially.

• A Converter class to classify graph nodes based on their edge relationships and assign them to combos.

• Utility functions to verify data existence and to build nodes and combos from community data.

This file is intended for use in applications dealing with graph data structures, where nodes are grouped into clusters (combos) based on connectivity or community membership. It helps prepare data for visualization or further graph processing.

Classes and Functions

Class: KeyGenerator

A utility class that generates sequential single-character keys ('a' to 'z').

Properties

Constructor

constructor()

Initializes the chars array with all lowercase English letters ('a' to 'z').

Methods

• generateKey(): string

  Returns the next character key in sequence. For example, first call returns 'a', second 'b', and so on.

  Usage example:

  const kg = new KeyGenerator();
  console.log(kg.generateKey()); // Output: 'a'
  console.log(kg.generateKey()); // Output: 'b'
  

Class: Converter

Processes graph nodes and edges to assign nodes into combos based on edge connectivity.

Properties

Constructor

constructor()

Initializes a new KeyGenerator and an empty dict.

Methods

• buildDict(edges: { source: string; target: string }[]): Record<string, string>

  Builds a dictionary mapping each node ID to a combo key based on edge connectivity.

  Algorithm:

  • Iterates over each edge.

  • If one node is already in dict, assigns the other node the same combo key.

  • If neither node is in dict, generates a new combo key via KeyGenerator.

  • Returns the updated dict.

  Parameters:

  • edges: Array of edge objects with source and target node IDs.

  Returns:

  • A dictionary mapping node IDs to combo keys (single characters).

  Usage example:

  const converter = new Converter();
  const edges = [
    { source: 'node1', target: 'node2' },
    { source: 'node3', target: 'node4' },
  ];
  const dict = converter.buildDict(edges);
  console.log(dict); // e.g. { node1: 'a', node2: 'a', node3: 'b', node4: 'b' }
  

• buildNodesAndCombos(nodes: any[], edges: any[]): { nodes: any[]; combos: any[] }

  Assigns each node a combo property based on the combos derived from edges, and constructs combo objects.

  Algorithm:

  • Calls buildDict to classify nodes by combos.

  • Maps nodes to include their assigned combo key.

  • Builds an array of unique combos from the dict.

  • Each combo is an object with id (combo key) and a label like "Combo a".

  Parameters:

  • nodes: Array of node objects, each with at least an id.

  • edges: Array of edge objects as above.

  Returns:

  • An object with:

    • nodes: nodes enriched with combo keys.

    • combos: array of combo objects representing clusters.

  Usage example:

  const nodes = [{ id: 'node1' }, { id: 'node2' }, { id: 'node3' }];
  const edges = [{ source: 'node1', target: 'node2' }];
  const converter = new Converter();
  const { nodes: newNodes, combos } = converter.buildNodesAndCombos(nodes, edges);
  

Function: isDataExist

Checks if valid graph data exists within an input object.

export const isDataExist = (data: any) => boolean

• Parameters:

  • data: An object expected to have a data property with a graph property inside.

• Returns: true if:

  • data.data exists and is not a boolean,

  • and data.data.graph is not empty (uses lodash's isEmpty).

• Otherwise, returns false.

Usage example:

if (isDataExist(response)) {
  // proceed with processing graph data
}

Function: buildNodesAndCombos

Creates combos based on a node's communities property and assigns nodes to these combos.

export const buildNodesAndCombos = (nodes: any[]) => { nodes: any[]; combos: any[] }

• Parameters:

  • nodes: Array of node objects, each possibly containing a communities array.

• Returns: An object containing:

  • nodes: nodes enriched with a combo property referencing the corresponding combo ID.

  • combos: array of combo objects with attributes:

    • isCombo: true

    • id: unique UUID (generated with uuid package)

    • data.label: the community label string

Implementation detail:

• Uses helper function findCombo to get the first community label.

• Avoids duplicate combos by checking if the label exists before adding.

• Assigns each node a combo property corresponding to the combo's UUID.

Usage example:

const nodes = [
  { id: '1', communities: ['group1', 'group2'] },
  { id: '2', communities: ['group1'] },
];
const { nodes: newNodes, combos } = buildNodesAndCombos(nodes);

Helper Function: findCombo

Extracts the first community label from an array.

const findCombo = (communities: string[]) => string | undefined

• Parameters:

  • communities: array of strings.

• Returns:

  • The first string in the array or undefined if input is not an array.

Important Implementation Details

• KeyGenerator only supports 26 unique keys (a to z). If more combos are needed, the current implementation will exceed array bounds without error handling.

• The Converter class builds combos based on edge connectivity, effectively grouping connected nodes into the same combo.

• The standalone buildNodesAndCombos function groups nodes based on community membership rather than edges.

• The code relies on lodash's isEmpty to check for empty graph data and uuid to generate unique IDs for combos.

• The separation of the Converter class and the standalone buildNodesAndCombos function suggests two different approaches for grouping nodes:

  • Converter for graph-based grouping.

  • buildNodesAndCombos for community-based grouping.

Interaction with Other Parts of the System

• This utility file likely serves a graph visualization or analysis module, preparing data by assigning groups (combos) to nodes.

• The isDataExist function is a guard utility to verify if the input data contains a valid graph before processing.

• The Converter class can be used when data is available as nodes and edges.

• The standalone buildNodesAndCombos function is useful when community information is embedded within node objects.

• The generated combos and enriched nodes are probably consumed by UI components or graph rendering engines elsewhere in the system.

Visual Diagram

flowchart TD
    A[KeyGenerator] -->|generateKey| B[Converter]
    B -->|buildDict(edges)| C[dict: nodeId -> comboKey]
    B -->|buildNodesAndCombos(nodes, edges)| D[Output: nodes with combos + combos array]
    E[buildNodesAndCombos(nodes)] --> F[Build combos by community]
    F --> G[Output: nodes with combo UUID + combos with UUID]
    H[isDataExist(data)] -->|validates| I[Graph data presence check]

    style A fill:#f9f,stroke:#333,stroke-width:1px
    style B fill:#ccf,stroke:#333,stroke-width:1px
    style E fill:#cfc,stroke:#333,stroke-width:1px
    style H fill:#ffc,stroke:#333,stroke-width:1px

Summary

The util.ts file encapsulates utilities that convert graph nodes and edges into grouped combos, facilitating cluster identification based on either graph connectivity or community membership. It provides both class-based and functional interfaces for flexible usage depending on input data format. The file's design supports modular graph data preparation for visualization or analysis components in larger applications.