fix: optimize record performance

Signed-off-by: Dr. Carsten Leue <carsten.leue@de.ibm.com>

v2/endomorphism/doc.go

@@ -40,7 +40,7 @@
 //	increment := N.Add(1)
 //
 //	// Compose them (RIGHT-TO-LEFT execution)
-//	composed := endomorphism.Compose(double, increment)
+//	composed := endomorphism.MonadCompose(double, increment)
 //	result := composed(5) // increment(5) then double: (5 + 1) * 2 = 12
 //
 //	// Chain them (LEFT-TO-RIGHT execution)
@@ -61,11 +61,11 @@
 //	monoid := endomorphism.Monoid[int]()
 //
 //	// Combine multiple endomorphisms (RIGHT-TO-LEFT execution)
-//	combined := M.ConcatAll(monoid)(
+//	combined := M.ConcatAll(monoid)([]endomorphism.Endomorphism[int]{
 //		N.Mul(2),  // applied third
 //		N.Add(1),  // applied second
 //		N.Mul(3),  // applied first
-//	)
+//	})
 //	result := combined(5) // (5 * 3) = 15, (15 + 1) = 16, (16 * 2) = 32
 //
 // # Monad Operations
@@ -87,7 +87,7 @@
 //	increment := N.Add(1)
 //
 //	// Compose: RIGHT-TO-LEFT (mathematical composition)
-//	composed := endomorphism.Compose(double, increment)
+//	composed := endomorphism.MonadCompose(double, increment)
 //	result1 := composed(5) // increment(5) * 2 = (5 + 1) * 2 = 12
 //
 //	// MonadChain: LEFT-TO-RIGHT (sequential application)

v2/endomorphism/endo.go

@@ -111,15 +111,19 @@ func MonadCompose[A any](f, g Endomorphism[A]) Endomorphism[A] {
 // This is the functor map operation for endomorphisms.
 //
 // IMPORTANT: Execution order is RIGHT-TO-LEFT:
-//   - g is applied first to the input
+//   - ma is applied first to the input
 //   - f is applied to the result
 //
+// Note: unlike most other packages where MonadMap takes (fa, f) with the container
+// first, here f (the morphism) comes first to match the right-to-left composition
+// convention: MonadMap(f, ma) = f ∘ ma.
+//
 // Parameters:
-//   - f: The function to map (outer function)
-//   - g: The endomorphism to map over (inner function)
+//   - f: The function to map (outer function, applied second)
+//   - ma: The endomorphism to map over (inner function, applied first)
 //
 // Returns:
-//   - A new endomorphism that applies g, then f
+//   - A new endomorphism that applies ma, then f
 //
 // Example:
 //
@@ -127,8 +131,8 @@ func MonadCompose[A any](f, g Endomorphism[A]) Endomorphism[A] {
 //	increment := N.Add(1)
 //	mapped := endomorphism.MonadMap(double, increment)
 //	// mapped(5) = double(increment(5)) = double(6) = 12
-func MonadMap[A any](f, g Endomorphism[A]) Endomorphism[A] {
-	return MonadCompose(f, g)
+func MonadMap[A any](f, ma Endomorphism[A]) Endomorphism[A] {
+	return MonadCompose(f, ma)
 }
 
 // Compose returns a function that composes an endomorphism with another, executing right to left.

v2/endomorphism/monoid.go

@@ -144,8 +144,8 @@ func Semigroup[A any]() S.Semigroup[Endomorphism[A]] {
 //	square := func(x int) int { return x * x }
 //
 //	// Combine multiple endomorphisms (RIGHT-TO-LEFT execution)
-//	combined := M.ConcatAll(monoid)(double, increment, square)
-//	result := combined(5) // square(increment(double(5))) = square(increment(10)) = square(11) = 121
+//	combined := M.ConcatAll(monoid)([]Endomorphism[int]{double, increment, square})
+//	result := combined(5) // double(increment(square(5))) = double(increment(25)) = double(26) = 52
 func Monoid[A any]() M.Monoid[Endomorphism[A]] {
 	return M.MakeMonoid(MonadCompose[A], Identity[A]())
 }

v2/endomorphism/types.go

@@ -41,20 +41,22 @@ type (
 	// It's a function from A to Endomorphism[A], used for composing endomorphic operations.
 	Kleisli[A any] = func(A) Endomorphism[A]
 
-	// Operator represents a transformation from one endomorphism to another.
+	// Operator represents a higher-order transformation on endomorphisms of the same type.
 	//
-	// An Operator takes an endomorphism on type A and produces an endomorphism on type B.
-	// This is useful for lifting operations or transforming endomorphisms in a generic way.
+	// An Operator takes an endomorphism on type A and produces another endomorphism on type A.
+	// Since Operator[A] = Endomorphism[Endomorphism[A]] = func(func(A)A) func(A)A,
+	// both the input and output endomorphisms operate on the same type A.
+	//
+	// This is the return type of curried operations such as Compose, Map, and Chain.
 	//
 	// Example:
 	//
-	//	// An operator that converts an int endomorphism to a string endomorphism
-	//	intToString := func(f endomorphism.Endomorphism[int]) endomorphism.Endomorphism[string] {
-	//		return func(s string) string {
-	//			n, _ := strconv.Atoi(s)
-	//			result := f(n)
-	//			return strconv.Itoa(result)
-	//		}
+	//	// An operator that applies any endomorphism twice
+	//	var applyTwice endomorphism.Operator[int] = func(f endomorphism.Endomorphism[int]) endomorphism.Endomorphism[int] {
+	//		return func(x int) int { return f(f(x)) }
 	//	}
+	//	double := N.Mul(2)
+	//	result := applyTwice(double) // double ∘ double
+	//	// result(5) = double(double(5)) = double(10) = 20
 	Operator[A any] = Endomorphism[Endomorphism[A]]
 )

v2/record/generic/record.go

@@ -38,21 +38,41 @@ func IsNonEmpty[M ~map[K]V, K comparable, V any](r M) bool {
 }
 
 func Keys[M ~map[K]V, GK ~[]K, K comparable, V any](r M) GK {
+	// fast path
+	if len(r) == 0 {
+		return nil
+	}
+	// full implementation
 	return collect[M, GK](r, F.First[K, V])
 }
 
 func Values[M ~map[K]V, GV ~[]V, K comparable, V any](r M) GV {
+	// fast path
+	if len(r) == 0 {
+		return nil
+	}
+	// full implementation
 	return collect[M, GV](r, F.Second[K, V])
 }
 
 func KeysOrd[M ~map[K]V, GK ~[]K, K comparable, V any](o ord.Ord[K]) func(r M) GK {
 	return func(r M) GK {
+		// fast path
+		if len(r) == 0 {
+			return nil
+		}
+		// full implementation
 		return collectOrd[M, GK](o, r, F.First[K, V])
 	}
 }
 
 func ValuesOrd[M ~map[K]V, GV ~[]V, K comparable, V any](o ord.Ord[K]) func(r M) GV {
 	return func(r M) GV {
+		// fast path
+		if len(r) == 0 {
+			return nil
+		}
+		// full implementation
 		return collectOrd[M, GV](o, r, F.Second[K, V])
 	}
 }
@@ -97,12 +117,18 @@ func collect[M ~map[K]V, GR ~[]R, K comparable, V, R any](r M, f func(K, V) R) G
 }
 
 func Collect[M ~map[K]V, GR ~[]R, K comparable, V, R any](f func(K, V) R) func(M) GR {
+	// full implementation
 	return F.Bind2nd(collect[M, GR, K, V, R], f)
 }
 
 func CollectOrd[M ~map[K]V, GR ~[]R, K comparable, V, R any](o ord.Ord[K]) func(f func(K, V) R) func(M) GR {
 	return func(f func(K, V) R) func(M) GR {
 		return func(r M) GR {
+			// fast path
+			if len(r) == 0 {
+				return nil
+			}
+			// full implementation
 			return collectOrd[M, GR](o, r, f)
 		}
 	}
@@ -416,12 +442,22 @@ func duplicate[M ~map[K]V, K comparable, V any](r M) M {
 }
 
 func upsertAt[M ~map[K]V, K comparable, V any](r M, k K, v V) M {
+	// fast path
+	if len(r) == 0 {
+		return Singleton[M](k, v)
+	}
+	// duplicate and update
 	dup := duplicate(r)
 	dup[k] = v
 	return dup
 }
 
 func deleteAt[M ~map[K]V, K comparable, V any](r M, k K) M {
+	// fast path
+	if len(r) == 0 {
+		return r
+	}
+	// duplicate and update
 	dup := duplicate(r)
 	delete(dup, k)
 	return dup

v2/record/record.go

@@ -55,10 +55,16 @@ func IsNonEmpty[K comparable, V any](r Record[K, V]) bool {
 // The order of keys is non-deterministic due to Go's map iteration behavior.
 // Use KeysOrd if you need keys in a specific order.
 //
+// Note: The return value can be nil in case of an empty map, since nil is a
+// valid representation of an empty slice in Go.
+//
 // Example:
 //
 //	record := Record[string, int]{"a": 1, "b": 2, "c": 3}
 //	keys := Keys(record) // ["a", "b", "c"] in any order
+//
+//	emptyRecord := Record[string, int]{}
+//	emptyKeys := Keys(emptyRecord) // nil or []string{}
 func Keys[K comparable, V any](r Record[K, V]) []K {
 	return G.Keys[Record[K, V], []K](r)
 }
@@ -68,10 +74,16 @@ func Keys[K comparable, V any](r Record[K, V]) []K {
 // The order of values is non-deterministic due to Go's map iteration behavior.
 // Use ValuesOrd if you need values ordered by their keys.
 //
+// Note: The return value can be nil in case of an empty map, since nil is a
+// valid representation of an empty slice in Go.
+//
 // Example:
 //
 //	record := Record[string, int]{"a": 1, "b": 2, "c": 3}
 //	values := Values(record) // [1, 2, 3] in any order
+//
+//	emptyRecord := Record[string, int]{}
+//	emptyValues := Values(emptyRecord) // nil or []int{}
 func Values[K comparable, V any](r Record[K, V]) []V {
 	return G.Values[Record[K, V], []V](r)
 }
@@ -98,6 +110,9 @@ func Collect[K comparable, V, R any](f func(K, V) R) func(Record[K, V]) []R {
 //
 // Unlike Collect, this function guarantees the order of results based on key ordering.
 //
+// Note: The return value can be nil in case of an empty map, since nil is a
+// valid representation of an empty slice in Go.
+//
 // Example:
 //
 //	record := Record[string, int]{"c": 3, "a": 1, "b": 2}
@@ -105,6 +120,9 @@ func Collect[K comparable, V, R any](f func(K, V) R) func(Record[K, V]) []R {
 //	    return fmt.Sprintf("%s=%d", k, v)
 //	})
 //	result := toStrings(record) // ["a=1", "b=2", "c=3"] (ordered by key)
+//
+//	emptyRecord := Record[string, int]{}
+//	emptyResult := toStrings(emptyRecord) // nil or []string{}
 func CollectOrd[V, R any, K comparable](o ord.Ord[K]) func(func(K, V) R) func(Record[K, V]) []R {
 	return G.CollectOrd[Record[K, V], []R](o)
 }
@@ -458,11 +476,18 @@ func UpsertAt[K comparable, V any](k K, v V) Operator[K, V, V] {
 // If the key doesn't exist, the record is returned unchanged.
 // The original record is not modified; a new record is returned.
 //
+// In case of an empty input map (including nil maps), the identical map is returned,
+// since deleting from an empty map is an idempotent operation.
+//
 // Example:
 //
 //	record := Record[string, int]{"a": 1, "b": 2, "c": 3}
 //	removeB := DeleteAt[string, int]("b")
 //	result := removeB(record) // {"a": 1, "c": 3}
+//
+//	// Deleting from empty map returns empty map
+//	emptyRecord := Record[string, int]{}
+//	result2 := removeB(emptyRecord) // {}
 func DeleteAt[K comparable, V any](k K) Operator[K, V, V] {
 	return G.DeleteAt[Record[K, V]](k)
 }

v2/record/record_nil_test.go

@@ -42,7 +42,7 @@ func TestNilMap_IsNonEmpty(t *testing.T) {
 func TestNilMap_Keys(t *testing.T) {
 	var nilMap Record[string, int]
 	keys := Keys(nilMap)
-	assert.NotNil(t, keys, "Keys should return non-nil slice")
+	// Keys can return nil for empty map, which is a valid representation of an empty slice
 	assert.Equal(t, 0, len(keys), "Keys should return empty slice for nil map")
 }
 
@@ -50,7 +50,7 @@ func TestNilMap_Keys(t *testing.T) {
 func TestNilMap_Values(t *testing.T) {
 	var nilMap Record[string, int]
 	values := Values(nilMap)
-	assert.NotNil(t, values, "Values should return non-nil slice")
+	// Values can return nil for empty map, which is a valid representation of an empty slice
 	assert.Equal(t, 0, len(values), "Values should return empty slice for nil map")
 }
 
@@ -288,8 +288,16 @@ func TestNilMap_DeleteAt(t *testing.T) {
 	var nilMap Record[string, int]
 	deleteFunc := DeleteAt[string, int]("key")
 	result := deleteFunc(nilMap)
-	assert.NotNil(t, result, "DeleteAt should return non-nil map")
-	assert.Equal(t, 0, len(result), "DeleteAt should return empty map for nil input")
+	// DeleteAt returns the identical map for nil input (idempotent operation)
+	assert.Nil(t, result, "DeleteAt should return nil for nil input (idempotent)")
+	assert.Equal(t, nilMap, result, "DeleteAt should return identical map for nil input")
+
+	// Verify that deleting from empty (non-nil) map returns identical map (idempotent)
+	emptyMap := Record[string, int]{}
+	result2 := deleteFunc(emptyMap)
+	assert.NotNil(t, result2, "DeleteAt should return non-nil map for empty input")
+	assert.Equal(t, 0, len(result2), "DeleteAt should return empty map for empty input")
+	assert.Equal(t, emptyMap, result2, "DeleteAt on empty map should be idempotent")
 }
 
 // TestNilMap_Filter verifies that Filter handles nil maps correctly