tree

Управление префиксным деревом (tree) с поддержкой слов и фраз. Включает систему счетчиков для корректной обработки дубликатов.

Описание

trie предоставляет API для работы с префиксным деревом, включая операции вставки, поиска, автодополнения и управления данными. Поддерживает как отдельные слова, так и целые фразы с учетом количества вхождений каждого элемента.

Функциональность

Операции со словами

• insertWord - добавление нового слова в дерево (увеличивает счетчик при дубликатах)
• searchWord - проверка существования слова в дереве
• deleteWord - удаление слова из дерева (уменьшает счетчик)
• autocompleteWords - получение списка слов по префиксу
• getWordCount - получение количества вхождений конкретного слова

Операции с фразами

• insertPhrase - добавление новой фразы в дерево (увеличивает счетчик при дубликатах)
• searchPhrase - проверка существования фразы в дереве
• autocompletePhrases - получение списка фраз по префиксу
• deletePhrase - удаление фразы из дерева (уменьшает счетчик)
• getPhraseCount - получение количества вхождений конкретной фразы

Дополнительные операции

• checkPrefix - проверка наличия слов, начинающихся с заданного префикса
• getStats - получение расширенной статистики по дереву (включая общее количество вхождений)
• clearTrie - удаление всех данных из дерева

Веб пример

Пример

Интерфейсы

InsertWord

interface InsertWord {
  word: string;
}

InsertPhrase

interface InsertPhrase {
  phrase: string;
}

SearchResponse

interface SearchResponse {
  exists: boolean;
  text: string;
  count?: number; // Количество вхождений (опционально)
}

AutocompleteResponse

interface AutocompleteResponse {
  prefix: string;
  suggestions: string[];
  count: number;
}

WordCountResponse

interface WordCountResponse {
  word: string;
  count: number;
  normalized: string;
}

PhraseCountResponse

interface PhraseCountResponse {
  phrase: string;
  count: number;
  normalized: string;
}

TreeStats

interface TreeStats {
  totalNodes: number;
  totalWords: number; // Уникальные слова
  totalPhrases: number; // Уникальные фразы
  totalWordOccurrences: number; // Общее количество вхождений слов
  totalPhraseOccurrences: number; // Общее количество вхождений фраз
}

Методы

insertWord(dto: InsertWord)

- Добавляет новое слово в префиксное дерево или увеличивает счетчик существующего.

**Параметры:**
- `dto` - объект с полем `word`

**Возвращает:**
- `{ message: string }` - сообщение об успешном добавлении

**Исключения:**
- Выбрасывает ошибку при неудачной вставке

**Примечание:**
- При добавлении дубликата увеличивается внутренний счетчик

insertPhrase(dto: InsertPhrase)

- Добавляет новую фразу в префиксное дерево или увеличивает счетчик существующей.

**Параметры:**
- `dto` - объект с полем `phrase`

**Возвращает:**
- `{ message: string }` - сообщение об успешном добавлении

**Исключения:**
- Выбрасывает ошибку при неудачной вставке

**Примечание:**
- При добавлении дубликата увеличивается внутренний счетчик
- Автоматически создаются префиксы для автодополнения

searchWord(word: string)

- Ищет слово в префиксном дереве.

**Параметры:**
- `word` - слово для поиска

**Возвращает:**
- `SearchResponse` - результат поиска с информацией о существовании

**Примечание:**
- Возвращает true только если слово существует и имеет count > 0

searchPhrase(phrase: string)

- Ищет фразу в префиксном дереве.

**Параметры:**
- `phrase` - фраза для поиска

**Возвращает:**
- `SearchResponse` - результат поиска с информацией о существовании

**Примечание:**
- Возвращает true только если фраза существует и имеет count > 0

getWordCount(word: string)

- Получает количество вхождений конкретного слова.

**Параметры:**
- `word` - слово для подсчета

**Возвращает:**
- `number` - количество вхождений слова (0 если не найдено)

**Пример использования:**
```typescript
const count = tree.getWordCount("рыбалка"); // 3

getPhraseCount(phrase: string)

- Получает количество вхождений конкретной фразы.

**Параметры:**
- `phrase` - фраза для подсчета

**Возвращает:**
- `number` - количество вхождений фразы (0 если не найдена)

**Пример использования:**
```typescript
const count = tree.getPhraseCount("зимняя рыбалка"); // 2

autocompleteWords(prefix: string, limit?: number)

- Получает список слов, начинающихся с заданного префикса.

**Параметры:**
- `prefix` - префикс для поиска
- `limit` - максимальное количество результатов (по умолчанию 10)

**Возвращает:**
- `AutocompleteResponse` - список предложений

**Исключения:**
- Выбрасывает ошибку, если префикс не указан

**Примечание:**
- Возвращает только слова с count > 0

autocompletePhrases(prefix: string, limit?: number)

- Получает список фраз, начинающихся с заданного префикса.

**Параметры:**
- `prefix` - префикс для поиска
- `limit` - максимальное количество результатов (по умолчанию 10)

**Возвращает:**
- `AutocompleteResponse` - список предложений

**Исключения:**
- Выбрасывает ошибка, если префикс не указан

**Примечание:**
- Возвращает только фразы с count > 0

checkPrefix(prefix: string)

- Проверяет наличие слов, начинающихся с заданного префикса.

**Параметры:**
- `prefix` - префикс для проверки

**Возвращает:**
- `{ hasWords: boolean }` - результат проверки

deleteWord(word: string)

- Удаляет слово из префиксного дерева (уменьшает счетчик).

**Параметры:**
- `word` - слово для удаления

**Возвращает:**
- `{ message: string }` - сообщение об успешном удалении

**Исключения:**
- Выбрасывает ошибку, если слово не найдено

**Примечание:**
- Уменьшает счетчик на 1
- Физически удаляет из дерева только при count = 0
- Безопасно обрабатывает дубликаты

deletePhrase(phrase: string)

- Удаляет фразу из префиксного дерева (уменьшает счетчик).

**Параметры:**
- `phrase` - фраза для удаления

**Возвращает:**
- `{ message: string }` - сообщение об успешном удалении

**Исключения:**
- Выбрасывает ошибку, если фраза не найдена

**Примечание:**
- Уменьшает счетчик на 1
- Физически удаляет из дерева только при count = 0
- Безопасно обрабатывает дубликаты
- Автоматически очищает связанные префиксы при полном удалении

getStats()

- Получает расширенную статистику по префиксному дереву.

**Возвращает:**
- `TreeStats` - объект со статистикой, включающий:
  - `totalNodes` - общее количество узлов
  - `totalWords` - количество уникальных слов
  - `totalPhrases` - количество уникальных фраз
  - `totalWordOccurrences` - общее количество вхождений слов
  - `totalPhraseOccurrences` - общее количество вхождений фраз

**Пример результата:**
```typescript
{
  totalNodes: 234,
  totalWords: 15,
  totalPhrases: 8,
  totalWordOccurrences: 45,
  totalPhraseOccurrences: 23
}

### clearTrie()
```html
- Очищает все данные из префиксного дерева.

**Возвращает:**
- `{ message: string }` - сообщение об успешной очистке

**Примечание:**
- Сбрасывает все счетчики и удаляет все узлы

Система счетчиков

Принцип работы

• Каждый узел дерева содержит счетчик count
• При добавлении элемента: count++
• При удалении элемента: count--
• Элемент считается существующим только при count > 0

Преимущества

• Корректная обработка дубликатов: 5 одинаковых фраз = 1 узел с count = 5
• Безопасное удаление: удаление одной фразы не влияет на остальные дубликаты
• Экономия памяти: дубликаты не создают лишние узлы
• Консистентность: поиск и автодополнение работают только с активными элементами

Пример использования со счетчиками

// Добавляем одинаковые фразы
tree.insertPhrase({ phrase: "зимняя рыбалка" }); // count = 1
tree.insertPhrase({ phrase: "зимняя рыбалка" }); // count = 2
tree.insertPhrase({ phrase: "зимняя рыбалка" }); // count = 3

// Проверяем количество
console.log(tree.getPhraseCount("зимняя рыбалка")); // 3

// Удаляем одну фразу
tree.deletePhrase("зимняя рыбалка"); // count = 2

// Фраза все еще существует
console.log(tree.searchPhrase("зимняя рыбалка")); // { exists: true, text: "зимняя рыбалка" }
console.log(tree.getPhraseCount("зимняя рыбалка")); // 2

Обработка ошибок

Tree включает обработку ошибок для всех операций. При возникновении ошибки выбрасывается исключение с описательным сообщением на русском языке.

Типы ошибок

• Пустые входные данные
• Отсутствие элементов при удалении
• Отсутствие префикса при автодополнении
• Внутренние ошибки дерева

Использование

import { tree } from 'tree-autocomplete';

// Добавление слова
tree.insertWord({ word: "привет" });
tree.insertWord({ word: "привет" }); // Увеличивает счетчик

// Проверка количества
console.log(tree.getWordCount("привет")); // 2

// Поиск слова
const result = tree.searchWord("привет");
console.log(result); // { exists: true, text: "привет" }

// Автодополнение
const suggestions = tree.autocompleteWords("прив", 5);

// Безопасное удаление
tree.deleteWord("привет"); // count = 1, слово остается
tree.deleteWord("привет"); // count = 0, слово удаляется

// Получение статистики
const stats = tree.getStats();
console.log(stats);
// {
//   totalNodes: 156,
//   totalWords: 23,
//   totalPhrases: 12,
//   totalWordOccurrences: 67,
//   totalPhraseOccurrences: 34
// }

Примечания

• Поддерживается работа как с отдельными словами, так и с целыми фразами
• Методы автодополнения имеют ограничение по умолчанию в 10 результатов
• Система счетчиков обеспечивает корректную работу с дубликатами
• Физическое удаление узлов происходит только при count = 0
• Все операции поиска учитывают только активные элементы (count > 0)
• Статистика включает как уникальные элементы, так и общее количество вхождений