docs: add godoc and README files in English and Russian

README_ru.md

@@ -0,0 +1,178 @@
+# extypes
+
+`extypes` - это небольшой Go-пакет с generic-коллекциями и вспомогательными методами поверх обычных `slice` и `map`.
+
+В пакет входят:
+
+- `Slice[T]`: методы для срезов, например `Push`, `Pop`, `Remove`, `Filter`, `Map`
+- `Tuple[T]`: упорядоченная read-oriented коллекция с поддержкой JSON
+- `Set[T]`: коллекция с уникальными значениями на базе среза
+- `HashMap[K, V]`: generic-обертка над `map`
+- `Queue[T]`: ограниченная по размеру FIFO-очередь с mutex-защитой
+
+## Требования
+
+- Go `1.25+`
+
+## Установка
+
+```bash
+go get git.nix13.pw/scuroneko/extypes
+```
+
+## Импорт
+
+```go
+import "git.nix13.pw/scuroneko/extypes"
+```
+
+## Особенности дизайна
+
+- Пакет остается близким к встроенным типам Go и не строит тяжелую абстракцию поверх них.
+- Методы `Slice`, `Set` и `HashMap` часто возвращают receiver, чтобы было удобно писать chain-вызовы.
+- Часть методов мутирует данные на месте: `Slice.Map`, `Slice.Swap`, `Set.Map`, `Set.Swap`, `HashMap.Add`, `HashMap.Remove`, `HashMap.Map`.
+- `Tuple` ориентирован на чтение, но `NewTupleFrom` не копирует входной срез, а оборачивает его.
+- `Set` сохраняет порядок первого появления элементов. Метод `Equal` чувствителен к порядку.
+- `Set.Map` не восстанавливает уникальность, если функция отображения порождает дубликаты.
+- Порядок обхода `HashMap` не определен, поэтому `Keys`, `Values`, `Items`, `IndexKey` и `IndexValue` не подходят там, где нужен стабильный порядок.
+- Для поиска и сравнения в `Slice`, `Tuple`, `Set` и `HashMap.IndexValue` используется `reflect.DeepEqual`, поэтому элементы не обязаны быть `comparable`.
+
+## Быстрые примеры
+
+### Slice
+
+```go
+nums := extypes.NewSliceFrom([]int{1, 2, 3})
+
+nums = nums.Push(4)
+nums = nums.Remove(2)
+nums = nums.Map(func(v int) int { return v * 10 })
+
+fmt.Println(nums.ToArray()) // [10 30 40]
+```
+
+### Tuple
+
+```go
+tuple := extypes.NewTupleFrom([]string{"api", "worker", "cron"})
+
+filtered := tuple.Filter(func(v string) bool {
+	return v != "worker"
+})
+
+fmt.Println(filtered.Join(", ")) // api, cron
+```
+
+### Set
+
+```go
+set := extypes.NewSetFrom([]string{"go", "go", "docs", "tests"})
+
+set = set.Add("bench")
+set = set.Remove("docs")
+
+fmt.Println(set.ToArray()) // [go tests bench]
+```
+
+### HashMap
+
+```go
+ports := extypes.NewMapFrom(map[string]int{
+	"http":  80,
+	"https": 443,
+})
+
+ports.Add("ssh", 22)
+
+secure := ports.Filter(func(name string, port int) bool {
+	return port >= 100 || name == "https"
+})
+
+fmt.Println(secure.Contains("https")) // true
+```
+
+### Queue
+
+```go
+q := extypes.CreateQueue[string](2)
+
+_ = q.Enqueue("first")
+_ = q.Enqueue("second")
+
+head, _ := q.Peak()
+fmt.Println(head) // first
+
+item, _ := q.Dequeue()
+fmt.Println(item) // first
+```
+
+## Краткий обзор API
+
+### `Slice[T]`
+
+Полезные методы:
+
+- `Len`, `Cap`, `Get`, `First`, `Last`
+- `Index`, `Equal`
+- `Push`, `Pop`, `Remove`, `Swap`
+- `Filter`, `ForEach`, `Map`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSet`, `ToTuple`
+
+### `Tuple[T]`
+
+Полезные методы:
+
+- `Len`, `Cap`, `Get`
+- `Equal`
+- `Filter`, `ForEach`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSet`, `ToSlice`
+- `MarshalJSON`, `UnmarshalJSON`
+
+### `Set[T]`
+
+Полезные методы:
+
+- `Len`, `Cap`, `Get`, `First`, `Last`
+- `Index`, `Equal`
+- `Add`, `Pop`, `Remove`, `Swap`
+- `Filter`, `ForEach`, `Map`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSlice`, `ToTuple`
+
+### `HashMap[K, V]`
+
+Полезные методы:
+
+- `Len`, `Get`, `GetOrDefault`, `Contains`
+- `Add`, `Remove`
+- `Keys`, `Values`, `Items`
+- `IndexKey`, `IndexValue`
+- `Filter`, `ForEach`, `Map`
+
+### `Queue[T]`
+
+Полезные методы:
+
+- `CreateQueue`
+- `Len`, `Size`, `IsEmpty`, `IsFull`
+- `Enqueue`, `Dequeue`, `Peak`
+- `Raw`
+
+Возвращаемые ошибки:
+
+- `QueueFullErr`
+- `QueueEmptyErr`
+
+## Запуск тестов
+
+```bash
+go test ./...
+```
+
+## Godoc
+
+Для публичного API добавлены doc-комментарии, поэтому локальную документацию можно смотреть стандартными инструментами Go:
+
+```bash
+go doc
+go doc git.nix13.pw/scuroneko/extypes
+```