gating two constraints: Go's lack of type parameters on methods, and the language's preference for explicit control flow. The solution architecture separates functional and chainable APIs to maximize type safety while preserving developer ergonomics.

Step 1: Functional API for Type-Safe Transformations

Go's type inference works best with standalone functions. When you need to change the element type during transformation (e.g., []int to []string), use the functional variant. The compiler infers the return type from the callback signature, eliminating manual type assertions.

package main

import (
	"fmt"
	"strings"

	"github.com/bube054/go-js-array-methods/v2/array"
)

func processMetrics(rawData []int) ([]string, error) {
	// Filter even numbers, then transform to formatted strings
	filtered, err := array.Filter(rawData, func(val, _ int, _ []int) bool {
		return val%2 == 0
	})
	if err != nil {
		return nil, err
	}

	transformed, err := array.Map(filtered, func(n, _ int, _ []int) string {
		return fmt.Sprintf("metric_%d", n)
	})
	if err != nil {
		return nil, err
	}

	return transformed, nil
}

Architecture Rationale: The callback signature (element, index, originalSlice) matches the MDN specification. Returning error from bounds-sensitive operations (At, Slice, Splice) replaces Go's default panic behavior, making the library safe for untrusted input processing.

Step 2: Chainable API for Same-Type Operations

When transformations preserve the element type, the chainable Array[T] wrapper reduces boilerplate. Note that Go does not permit type parameters on methods, so Array[T].Map() cannot change the underlying type. It remains locked to Array[any] if type conversion is attempted. For same-type operations, the chainable style is highly efficient.

package main

import (
	"strings"

	"github.com/bube054/go-js-array-methods/v2/array"
)

func normalizeLabels(raw []string) array.Array[string] {
	return array.Array[string](raw).
		Filter(func(s string, _ int, _ []string) bool {
			return len(strings.TrimSpace(s)) > 0
		}).
		MapStrict(func(s string, _ int, _ []string) string {
			return strings.ToUpper(s)
		}).
		Reverse()
}

Architecture Rationale: MapStrict and ReduceStrict variants enforce type consistency between input and output slices. This prevents accidental type widening and keeps the pipeline predictable. The chainable wrapper allocates a new slice on each operation, maintaining immutability without requiring manual slice copying.

Step 3: Handling Nested Data and Accumulation

Flattening mixed-type slices and performing type-preserving reductions require explicit type parameters due to Go's generic constraints. The library provides Flat[T] and ReduceStrict to handle these cases safely.

package main

import (
	"github.com/bube054/go-js-array-methods/v2/array"
)

func aggregateTransactions(raw []any) (int, error) {
	// Flatten nested transaction slices into a single int slice
	flat, err := array.Flat[int](raw)
	if err != nil {
		return 0, err
	}

	// Accumulate total with type preservation
	total := 0
	result, err := array.ReduceStrict(flat, func(acc, val, _ int, _ []int) int {
		return acc + val
	}, &total)
	
	return result, err
}

Architecture Rationale: Passing a pointer to the initial value (&total) allows ReduceStrict to preserve the exact type without resorting to any. This pattern eliminates runtime type switches and ensures the accumulator matches the slice element type at compile time.

Pitfall Guide

1. Expecting In-Place Mutation

Explanation: JavaScript's push, splice, and reverse modify the original array. This library returns a new slice for every operation to prevent aliasing bugs. Fix: Always assign the result to a variable or chain the next operation. Never assume the input slice is modified.

2. Using Chainable Map for Type Conversion

Explanation: Go's method type parameter restriction means Array[T].Map() cannot change the element type. Attempting to return a different type forces the wrapper into Array[any], losing compile-time safety. Fix: Use the functional array.Map() when transforming between types. Reserve chainable methods for same-type operations.

3. Ignoring Error Returns from Bounds Operations

Explanation: Methods like At, Slice, and Splice return (value, error) instead of panicking on out-of-range access. Dismissing the error leads to silent failures or zero-value defaults. Fix: Always check the error return. Implement fallback logic or validation before calling bounds-sensitive methods.

4. Overusing any for Mixed-Type Collections

Explanation: While Flat and some query methods accept []any, relying on it throughout the pipeline defeats Go's type system and shifts type checking to runtime. Fix: Use Flat[T] with explicit type parameters. Convert mixed data early in the pipeline, then operate on strongly-typed slices.

5. Reimplementing Sorting Logic

Explanation: The library intentionally omits Sort because Go's slices.Sort and sort package provide highly optimized, allocation-aware implementations. Fix: Use slices.Sort or slices.SortFunc for ordering. Apply functional transformations before or after sorting, not during.

6. Neglecting Strict Variants for Accumulation

Explanation: Standard Reduce may widen types to any if the callback signature isn't precise, causing downstream type assertion failures. Fix: Use ReduceStrict with a pointer to the initial value to guarantee type preservation across the entire pipeline.

7. Assuming JavaScript Mutation Semantics in Concurrency

Explanation: Because every operation returns a new slice, concurrent readers of the original data remain unaffected. However, developers sometimes assume the returned slice is safe to share across goroutines without copying. Fix: Treat returned slices as immutable. If mutation is required in a concurrent context, explicitly copy the slice before passing it to worker goroutines.

Production Bundle

Action Checklist

• Audit existing for loops: Identify repetitive filtering, mapping, or reduction logic that can be replaced with functional pipelines.
• Enforce immutability contracts: Document that all slice operations return new slices; update team coding standards accordingly.
• Replace panic-prone bounds checks: Swap manual index validation with At, Slice, or Splice error returns.
• Standardize type preservation: Mandate MapStrict and ReduceStrict for pipelines where element types must remain consistent.
• Profile allocation patterns: Use pprof to verify that immutable returns don't introduce GC pressure in hot paths; consider batching if necessary.
• Add integration tests: Validate pipeline outputs against known datasets, especially for negative indexing and out-of-bounds scenarios.
• Document fallback strategies: Define how bounds errors and type mismatches should be handled in production services.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Simple iteration with side effects	Native for loop	Lowest allocation overhead, direct control	Minimal
Type-changing transformation	Functional array.Map	Compiler-inferred output type, zero assertions	Low
Same-type chaining with readability priority	Array[T] wrapper	Fluent API, reduced boilerplate	Low
High-throughput data ingestion	slices package + manual loops	Avoids allocation per operation, maximizes CPU cache locality	Medium (development time)
Untrusted input processing	Functional pipeline with error returns	Prevents panics, enables graceful degradation	Low

Configuration Template

// pipeline/config.go
package pipeline

import (
	"github.com/bube054/go-js-array-methods/v2/array"
)

// PipelineConfig defines reusable transformation strategies
type PipelineConfig struct {
	MaxBatchSize int
	OnError      func(error) error
}

// ApplyFilter applies a predicate and handles bounds errors gracefully
func ApplyFilter[T any](data []T, predicate func(T, int, []T) bool, cfg PipelineConfig) ([]T, error) {
	if len(data) == 0 {
		return []T{}, nil
	}
	
	result, err := array.Filter(data, predicate)
	if err != nil {
		if cfg.OnError != nil {
			return nil, cfg.OnError(err)
		}
		return nil, err
	}
	
	return result, nil
}

// ApplyReduceStrict accumulates values with type preservation
func ApplyReduceStrict[T any](data []T, initial T, reducer func(T, T, int, []T) T) (T, error) {
	ptr := initial
	result, err := array.ReduceStrict(data, reducer, &ptr)
	return result, err
}

Quick Start Guide

1. Initialize the module: Run go get github.com/bube054/go-js-array-methods/v2 in your project root.
2. Import the package: Add "github.com/bube054/go-js-array-methods/v2/array" to your imports.
3. Replace a loop: Convert a basic for loop filtering even numbers into array.Filter(slice, func(n, _ int, _ []int) bool { return n%2 == 0 }).
4. Handle errors: Check the second return value from bounds-sensitive methods (At, Slice, Splice) and implement fallback logic.
5. Benchmark hot paths: Run go test -bench=. -benchmem to verify allocation patterns. Switch to slices or native loops only if profiling shows GC pressure exceeding your SLA thresholds.