docs: add godoc and README files in English and Russian

README.md

@@ -0,0 +1,178 @@
+# extypes
+
+`extypes` is a small Go package with generic collection helpers built on top of native slices and maps.
+
+It provides:
+
+- `Slice[T]`: slice helpers such as `Push`, `Pop`, `Remove`, `Filter`, `Map`
+- `Tuple[T]`: a read-oriented ordered collection with JSON support
+- `Set[T]`: a uniqueness-enforcing collection backed by a slice
+- `HashMap[K, V]`: a generic map wrapper with helper methods
+- `Queue[T]`: a fixed-size, mutex-protected FIFO queue
+
+## Requirements
+
+- Go `1.25+`
+
+## Installation
+
+```bash
+go get git.nix13.pw/scuroneko/extypes
+```
+
+## Import
+
+```go
+import "git.nix13.pw/scuroneko/extypes"
+```
+
+## Design Notes
+
+- The package stays close to Go built-ins instead of introducing a large abstraction layer.
+- `Slice`, `Set`, and `HashMap` methods often return the receiver for chaining.
+- Some methods mutate the underlying storage in place: `Slice.Map`, `Slice.Swap`, `Set.Map`, `Set.Swap`, `HashMap.Add`, `HashMap.Remove`, `HashMap.Map`.
+- `Tuple` is read-oriented, but `NewTupleFrom` wraps the provided slice without copying it.
+- `Set` preserves first-seen order. Its `Equal` method is order-sensitive.
+- `Set.Map` does not restore uniqueness if the mapping function produces duplicates.
+- `HashMap` iteration order is unspecified, so `Keys`, `Values`, `Items`, `IndexKey`, and `IndexValue` should not be used where stable ordering is required.
+- Equality and search for `Slice`, `Tuple`, `Set`, and `HashMap.IndexValue` use `reflect.DeepEqual`, so element types do not need to be `comparable`.
+
+## Quick Examples
+
+### 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 Overview
+
+### `Slice[T]`
+
+Useful methods:
+
+- `Len`, `Cap`, `Get`, `First`, `Last`
+- `Index`, `Equal`
+- `Push`, `Pop`, `Remove`, `Swap`
+- `Filter`, `ForEach`, `Map`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSet`, `ToTuple`
+
+### `Tuple[T]`
+
+Useful methods:
+
+- `Len`, `Cap`, `Get`
+- `Equal`
+- `Filter`, `ForEach`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSet`, `ToSlice`
+- `MarshalJSON`, `UnmarshalJSON`
+
+### `Set[T]`
+
+Useful methods:
+
+- `Len`, `Cap`, `Get`, `First`, `Last`
+- `Index`, `Equal`
+- `Add`, `Pop`, `Remove`, `Swap`
+- `Filter`, `ForEach`, `Map`, `Join`
+- `ToArray`, `ToAnyArray`, `ToSlice`, `ToTuple`
+
+### `HashMap[K, V]`
+
+Useful methods:
+
+- `Len`, `Get`, `GetOrDefault`, `Contains`
+- `Add`, `Remove`
+- `Keys`, `Values`, `Items`
+- `IndexKey`, `IndexValue`
+- `Filter`, `ForEach`, `Map`
+
+### `Queue[T]`
+
+Useful methods:
+
+- `CreateQueue`
+- `Len`, `Size`, `IsEmpty`, `IsFull`
+- `Enqueue`, `Dequeue`, `Peak`
+- `Raw`
+
+Returned errors:
+
+- `QueueFullErr`
+- `QueueEmptyErr`
+
+## Running Tests
+
+```bash
+go test ./...
+```
+
+## Godoc
+
+The package includes doc comments for the public API, so local documentation can be viewed with standard Go tooling:
+
+```bash
+go doc
+go doc git.nix13.pw/scuroneko/extypes
+```