feat!: fix Drop semantics and add RemoveAt function

BREAKING CHANGE: Drop function now correctly drops first N elements
instead of removing element at specific index.

Changes:
- Renamed old Drop behavior to RemoveAt function
- Implemented correct Drop semantics (drop first N elements)
- Added comprehensive tests for both functions

Drop (NEW behavior):
- Drop([]int{1,2,3,4,5}, 2) → [3,4,5] (drops first 2 elements)
- Returns empty slice if n >= len(values)
- Returns original slice if n <= 0

RemoveAt (OLD Drop behavior):
- RemoveAt([]int{1,2,3,4,5}, 2) → [1,2,4,5] (removes index 2)
- Returns original slice if index out of bounds
- Pre-allocates with capacity len(values)-1

Tests added:
- Drop: 5 tests (basic, none, all, empty, single)
- RemoveAt: 6 tests (basic, first, last, bounds, empty, single)

Documentation updated:
- README.md: Added RemoveAt to function list
- CLAUDE.md: Marked Drop semantics as fixed
- ACTION_PLAN.md: Updated completion status

Migration guide:
- Old: Drop(slice, index) → New: RemoveAt(slice, index)
- New Drop usage: Drop(slice, n) drops first n elements

Coverage: 98.8% (maintained)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,183 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`underscore` is a Go library providing functional programming helpers inspired by underscore.js, built on Go 1.18+ generics. The library is organized as a flat structure with individual files for each function, plus a `maps` subpackage for map-specific utilities.
+
+## Development Commands
+
+### Testing
+
+```sh
+# Run all tests (local)
+go test ./...
+
+# Run all tests with coverage (local)
+go test ./... -coverpkg=./... -coverprofile cov.out -covermode=count
+go tool cover -func cov.out
+rm cov.out
+
+# Run tests in Docker (preferred for CI/validation)
+make test
+
+# Run a single test
+go test -run TestFunctionName
+
+# Run tests for a specific file
+go test -run TestMap
+```
+
+### Building
+
+```sh
+# Build Docker image
+make build
+
+# Install dependencies
+go mod download
+```
+
+### Linting & Security
+
+```sh
+# Scan Docker image for vulnerabilities
+make scan
+
+# Scan config files
+make scan-config
+```
+
+### Documentation
+
+```sh
+# Serve docs locally at http://localhost:1313
+make docs
+
+# Build static docs
+make build-docs
+```
+
+## Architecture
+
+### Code Organization
+
+The library uses a **flat structure** where each function is implemented in its own file:
+
+- `<function>.go` - implementation
+- `<function>_test.go` - tests
+
+Example: `filter.go` + `filter_test.go`, `map.go` + `map_test.go`
+
+### Core Patterns
+
+**Generic Functions**: Most functions use Go generics with constraints from `cmp.Ordered` or custom type parameters. Functions operate on slices and return new slices (immutable style).
+
+**Pipe Chain**: The `Pipe[T]` struct enables method chaining for ordered types. Methods that return slices continue the chain, while methods that return values (like `All`, `Any`, `Reduce`) break the chain and return the final value.
+
+```go
+// pipe.go defines Pipe[T cmp.Ordered]
+// Chain-continuing: Filter, Map
+// Chain-breaking: All, Any, Reduce, Min, Max, Partition, Find, Each
+```
+
+**Concurrency Helpers**: `ParallelMap` and `ParallelFilter` use worker pools with:
+
+- Context-based cancellation
+- Order preservation (results match input order)
+- First-error-wins semantics
+- Default workers = GOMAXPROCS if workers <= 0
+
+Implementation detail: Uses `sync.Once` to capture first error and cancel context immediately.
+
+**Subpackages**:
+
+- `maps/` - Map-specific utilities (`Keys`, `Values`, `Map`)
+  - Uses type alias `M[K, V] = map[K]V` for cleaner signatures
+  - `Map` function allows transforming map entries
+
+### Testing Conventions
+
+- Use `testify/assert` for assertions
+- Test file names match source files with `_test.go` suffix
+- Table-driven tests are common (see `map_test.go`, `filter_test.go`)
+- Internal tests (using `package underscore` rather than `package underscore_test`) are used sparingly for testing unexported functions
+
+## Key Constraints
+
+- **Minimum Go version**: 1.24.2 (see go.mod)
+- **Generic constraints**: Most collection functions require `cmp.Ordered` types; some use `comparable` or no constraints
+- **Order preservation**: `ParallelMap` and `ParallelFilter` guarantee output order matches input order
+- **No mutation**: Functions return new slices; `UniqueInPlace` is the exception (in-place deduplication)
+
+## Known Limitations
+
+### Recently Fixed (2025-11-14)
+
+1. ✅ **Filter allocation** - Now pre-allocates with `make([]T, 0, len(values))` (90% fewer allocations)
+2. ✅ **OrderBy algorithm** - Replaced bubble sort with `slices.SortFunc` (629x faster for large datasets)
+3. ✅ **Partition allocation** - Now pre-allocates both result slices
+4. ✅ **Max/Min empty slices** - Now panics with clear message: "underscore.Max: empty slice"
+5. ✅ **Drop semantics** - Fixed to drop first N elements (breaking change). Old behavior available as `RemoveAt`
+
+### API Design Issues
+
+1. **Pipe constraint** (`pipe.go:7`) - `Pipe[T cmp.Ordered]` prevents usage with custom types
+2. **Last panics** (`last.go:5-8`) - No empty slice handling
+
+### Missing Features
+
+Popular FP utilities not yet implemented: `TakeWhile`, `DropWhile`, `Scan`, `First/FirstN`, `Init`, `Intersperse`, `Sliding`, `FoldRight`, `Tap`, `Transpose`, `Unzip`, `ParallelReduce`, `Replicate`
+
+## Performance Characteristics
+
+### Good Performance Patterns
+- `Filter` pre-allocates: `make([]T, 0, len(values))` ✅ (Fixed 2025-11-14)
+- `Map` pre-allocates: `make([]P, 0, len(values))`
+- `Partition` pre-allocates: `make([]T, 0, len(values))` for both slices ✅ (Fixed 2025-11-14)
+- `Chunk` pre-calculates capacity: `(l+n-1)/n`
+- `ParallelFilter` pre-counts before allocation
+- `OrderBy` uses `slices.SortFunc`: O(n log n) performance ✅ (Fixed 2025-11-14)
+
+### Remaining Performance Issues
+- `Flatmap`: Accumulation overhead from repeated appends
+- `GroupBy`: Map initialized with capacity 0 (useless hint)
+
+### When to Use ParallelMap vs Map
+
+Use `ParallelMap` when:
+- Processing 100+ elements with expensive operations (>1ms per element)
+- Operations are CPU-bound (not I/O-bound with shared resources)
+- Order preservation is required
+- Context cancellation is needed
+
+Use regular `Map` when:
+- Small slices (<100 elements)
+- Fast operations (<100µs per element)
+- Avoiding goroutine overhead matters
+- Simple transformations without error handling
+
+**Worker count guidelines:**
+- Default (workers=0): Uses `runtime.GOMAXPROCS(0)` - good starting point
+- CPU-bound: Use GOMAXPROCS or GOMAXPROCS*2
+- I/O-bound: Can use higher values (10-100) if not sharing resources
+
+## Contributing Notes
+
+When adding new functions:
+
+1. Create both `<function>.go` and `<function>_test.go`
+2. Add examples in comments using Go doc format
+3. Pre-allocate slices with `make([]T, 0, len(input))` when output size is similar to input
+4. Document panic conditions (empty slices, nil inputs, invalid indices)
+5. Add edge case tests (empty, single element, nil)
+6. If the function applies to Pipe chains, add a method to `pipe.go`
+7. Update README.md function list if adding new collection functions
+8. Follow SemVer for version numbers
+9. Ensure all tests pass: `make test`
+
+When fixing bugs:
+- Add regression tests before fixing
+- Run benchmarks if performance-related: `go test -bench=. -benchmem`
+- Check for similar issues in other functions

README.md

@@ -113,6 +113,7 @@ make test
 - `Partition`
 - `Range`
 - `Reduce`
+- `RemoveAt`
 - `Sum` / `SumMap`
 - `Unique`
 - `UniqueBy`

drop.go

@@ -1,12 +1,16 @@
 package underscore
 
-// Drop returns the rest of the elements in a slice.
-// Pass an index to return the values of the slice from that index onward.
-func Drop[T any](values []T, index int) (rest []T) {
-	for i, value := range values {
-		if i != index {
-			rest = append(rest, value)
-		}
+// Drop returns a new slice with the first n elements removed.
+// If n is greater than or equal to the slice length, returns an empty slice.
+// If n is less than or equal to 0, returns the original slice.
+func Drop[T any](values []T, n int) []T {
+	if n <= 0 {
+		return values
 	}
-	return rest
+	if n >= len(values) {
+		return []T{}
+	}
+	res := make([]T, len(values)-n)
+	copy(res, values[n:])
+	return res
 }

drop_test.go

@@ -9,8 +9,34 @@ import (
 )
 
 func TestDrop(t *testing.T) {
-	nums := []int{1, 9, 2, 8, 3, 7, 4, 6, 5}
-	want := []int{1, 9, 2, 3, 7, 4, 6, 5}
+	nums := []int{1, 2, 3, 4, 5}
+	want := []int{3, 4, 5}
 
-	assert.Equal(t, want, u.Drop(nums, 3))
+	assert.Equal(t, want, u.Drop(nums, 2))
+}
+
+func TestDropNone(t *testing.T) {
+	nums := []int{1, 2, 3, 4, 5}
+
+	assert.Equal(t, nums, u.Drop(nums, 0))
+	assert.Equal(t, nums, u.Drop(nums, -1))
+}
+
+func TestDropAll(t *testing.T) {
+	nums := []int{1, 2, 3, 4, 5}
+
+	assert.Empty(t, u.Drop(nums, 5))
+	assert.Empty(t, u.Drop(nums, 10))
+}
+
+func TestDropEmpty(t *testing.T) {
+	result := u.Drop([]int{}, 5)
+	assert.Empty(t, result)
+}
+
+func TestDropSingleElement(t *testing.T) {
+	nums := []int{42}
+
+	assert.Equal(t, nums, u.Drop(nums, 0))
+	assert.Empty(t, u.Drop(nums, 1))
 }

go.mod

@@ -2,10 +2,7 @@ module github.com/rjNemo/underscore
 
 go 1.24.2
 
-require (
-	github.com/stretchr/testify v1.8.4
-	golang.org/x/exp v0.0.0-20250711185948-6ae5c78190dc
-)
+require github.com/stretchr/testify v1.8.4
 
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect

go.sum

@@ -4,8 +4,6 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-golang.org/x/exp v0.0.0-20250711185948-6ae5c78190dc h1:TS73t7x3KarrNd5qAipmspBDS1rkMcgVG/fS1aRb4Rc=
-golang.org/x/exp v0.0.0-20250711185948-6ae5c78190dc/go.mod h1:A+z0yzpGtvnG90cToK5n2tu8UJVP2XUATh+r+sfOOOc=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

remove_at.go

@@ -0,0 +1,16 @@
+package underscore
+
+// RemoveAt returns a new slice with the element at the given index removed.
+// Returns original slice if index is out of bounds.
+func RemoveAt[T any](values []T, index int) []T {
+	if index < 0 || index >= len(values) {
+		return values
+	}
+	res := make([]T, 0, len(values)-1)
+	for i, value := range values {
+		if i != index {
+			res = append(res, value)
+		}
+	}
+	return res
+}

remove_at_test.go

@@ -0,0 +1,50 @@
+package underscore_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	u "github.com/rjNemo/underscore"
+)
+
+func TestRemoveAt(t *testing.T) {
+	nums := []int{1, 9, 2, 8, 3, 7, 4, 6, 5}
+	want := []int{1, 9, 2, 3, 7, 4, 6, 5}
+
+	assert.Equal(t, want, u.RemoveAt(nums, 3))
+}
+
+func TestRemoveAtFirst(t *testing.T) {
+	nums := []int{1, 2, 3, 4, 5}
+	want := []int{2, 3, 4, 5}
+
+	assert.Equal(t, want, u.RemoveAt(nums, 0))
+}
+
+func TestRemoveAtLast(t *testing.T) {
+	nums := []int{1, 2, 3, 4, 5}
+	want := []int{1, 2, 3, 4}
+
+	assert.Equal(t, want, u.RemoveAt(nums, 4))
+}
+
+func TestRemoveAtOutOfBounds(t *testing.T) {
+	nums := []int{1, 2, 3}
+
+	// Negative index
+	assert.Equal(t, nums, u.RemoveAt(nums, -1))
+
+	// Index too large
+	assert.Equal(t, nums, u.RemoveAt(nums, 10))
+}
+
+func TestRemoveAtEmpty(t *testing.T) {
+	result := u.RemoveAt([]int{}, 0)
+	assert.Empty(t, result)
+}
+
+func TestRemoveAtSingleElement(t *testing.T) {
+	result := u.RemoveAt([]int{42}, 0)
+	assert.Empty(t, result)
+}