cs-element/docs/21-element-navigation.md

Advanced reactive data management library with state machines, blueprints, persistence, compression, networking, and multithreading support

# Element Navigation - Навигация и обход элементов

Система навигации CSElement предоставляет мощные инструменты для обхода и поиска элементов в сложных иерархических структурах.

## 🎯 Основные возможности

- **Depth-First и Breadth-First обход** - различные стратегии обхода
- **Поиск по предикатам** - гибкая система поиска элементов
- **Безопасный от циклов обход** - защита от бесконечных циклов
- **Асинхронный обход** - поддержка асинхронных операций

## 🚀 Быстрый старт

```typescript
import { CSElement } from 'cs-element';

const root = CSElement.create('root');
const child1 = root.createChild('child1');
const child2 = root.createChild('child2');
child1.createChild('grandchild1');
child1.createChild('grandchild2');

// Depth-First обход
await root.traverseDepthFirst(async (element, depth) => {
  console.log(`${' '.repeat(depth)}${element.name}`);
  return { continue: true };
});

// Breadth-First обход
await root.traverseBreadthFirst(async (element, level) => {
  console.log(`Level ${level}: ${element.name}`);
  return { continue: true };
});

// Поиск элементов
const found = await root.findElement((element) => {
  return element.getData('type') === 'important';
});

// Поиск всех элементов по условию
const allFound = await root.findAllElements((element) => {
  return element.getData('active') === true;
});
```

## 📚 Подробное руководство

### Стратегии обхода

```typescript
// Настройка обхода
const traversalOptions = {
  maxDepth: 10,
  avoidCycles: true,
  collectPaths: true,
  includeRoot: true,
  filter: (element) => element.getData('visible') !== false
};

// DFS с опциями
const dfsResult = await root.traverseDepthFirst(
  async (element, depth, path) => {
    console.log(`Visiting: ${element.name} at depth ${depth}`);
    
    // Можно прервать обход
    if (element.getData('stop')) {
      return { continue: false, data: 'stopped' };
    }
    
    return { continue: true, data: element.getData() };
  },
  traversalOptions
);

// BFS с опциями
const bfsResult = await root.traverseBreadthFirst(
  async (element, level, queue) => {
    console.log(`Level ${level}: ${element.name}`);
    return { continue: true };
  },
  traversalOptions
);
```

### Поиск элементов

```typescript
// Поиск первого элемента
const user = await root.findElement((element) => {
  return element.name === 'user' && 
         element.getData('id') === 123;
});

// Поиск с асинхронным предикатом
const verified = await root.findElement(async (element) => {
  if (element.getData('type') !== 'user') return false;
  
  // Асинхронная проверка
  const isVerified = await checkUserVerification(element.getData('id'));
  return isVerified;
});

// Поиск множественных элементов
const activeUsers = await root.findAllElements((element) => {
  return element.getData('type') === 'user' && 
         element.getData('status') === 'active';
});
```

### Навигационные утилиты

```typescript
// Получение пути к элементу
const path = element.getPath(); // ['root', 'child1', 'grandchild1']
const pathString = element.getPathString('/'); // 'root/child1/grandchild1'

// Вычисление глубины
const depth = element.getDepth(); // 2

// Получение предков
const ancestors = element.getAncestors();
const parent = element.getParent();
const root = element.getRoot();

// Получение потомков
const children = element.getChildren();
const descendants = element.getDescendants();
const siblings = element.getSiblings();

// Навигация по соседям
const nextSibling = element.getNextSibling();
const prevSibling = element.getPreviousSibling();
const firstChild = element.getFirstChild();
const lastChild = element.getLastChild();
```

Element Navigation предоставляет полный набор инструментов для эффективного обхода и поиска в сложных структурах данных.