# 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
```