trackformutations.go

package invariant

import "strings"

// MutationResult is the value returned by Tracker.DetectMutations. It mirrors
// the JS return shapes `{wasMutated: true, path: [...]}` and `{wasMutated:
// false}`.
//
// When WasMutated is false, Path is nil (the original object omits the `path`
// key entirely in that case).
type MutationResult struct {
	WasMutated bool
	Path       []string
}

// trackedProperty is the snapshot node built by trackProperties. It mirrors the
// JS `{ value, children }` shape.
//
// children is nil when the value was immutable at snapshot time (the JS object
// simply lacks a `children` key in that case).
type trackedProperty struct {
	value    Value
	children map[string]*trackedProperty
	// childKeys preserves the enumeration order of children so detection can
	// reproduce JS key ordering.
	childKeys []string
}

// Tracker snapshots a state tree and can later report whether it was mutated in
// place. It is the Go equivalent of the object returned by the JS
// `trackForMutations` function, exposing a single DetectMutations method.
type Tracker struct {
	isImmutable IsImmutableFunc
	ignore      []string
	tracked     *trackedProperty
	obj         Value
}

// TrackForMutations snapshots obj and returns a Tracker. This is a direct port
// of the JS `trackForMutations(isImmutable, ignore, obj)` factory.
//
// A nil isImmutable defaults to IsImmutableDefault, matching the JS default
// binding performed by the middleware.
func TrackForMutations(isImmutable IsImmutableFunc, ignore []string, obj Value) *Tracker {
	if isImmutable == nil {
		isImmutable = IsImmutableDefault
	}
	return &Tracker{
		isImmutable: isImmutable,
		ignore:      ignore,
		tracked:     trackProperties(isImmutable, ignore, obj, nil),
		obj:         obj,
	}
}

// DetectMutations reports whether the tracked object has been mutated in place
// since it was snapshotted. Port of the returned `detectMutations()` closure.
func (t *Tracker) DetectMutations() MutationResult {
	return detectMutations(t.isImmutable, t.ignore, t.tracked, t.obj, false, nil)
}

// trackProperties recursively snapshots obj. Port of the JS `trackProperties`.
//
// path is the accumulated key path (nil at the root, matching the JS default
// `path = []`).
func trackProperties(isImmutable IsImmutableFunc, ignore []string, obj Value, path []string) *trackedProperty {
	tracked := &trackedProperty{value: obj}

	if !isImmutable(obj) {
		tracked.children = map[string]*trackedProperty{}

		for _, key := range ownKeys(obj) {
			childPath := appendPath(path, key)
			if len(ignore) > 0 && contains(ignore, strings.Join(childPath, ".")) {
				continue
			}

			tracked.children[key] = trackProperties(
				isImmutable,
				ignore,
				propertyValue(obj, key),
				childPath,
			)
			tracked.childKeys = append(tracked.childKeys, key)
		}
	}
	return tracked
}

// detectMutations recursively compares the current obj against its snapshot.
// Port of the JS `detectMutations`.
//
// sameParentRef reports whether the parent reference was unchanged; path is the
// accumulated key path.
func detectMutations(
	isImmutable IsImmutableFunc,
	ignore []string,
	tracked *trackedProperty,
	obj Value,
	sameParentRef bool,
	path []string,
) MutationResult {
	var prevObj Value = Undefined
	if tracked != nil {
		prevObj = tracked.value
	}

	sameRef := refEqual(prevObj, obj)

	if sameParentRef && !sameRef && !isNaNValue(obj) {
		return MutationResult{WasMutated: true, Path: path}
	}

	if isImmutable(prevObj) || isImmutable(obj) {
		return MutationResult{WasMutated: false}
	}

	// Gather all keys from prev (tracked) and after objs, mirroring the JS
	// union that seeds `keysToDetect` from tracked children first, then from
	// the current object.
	keys := unionKeys(tracked, obj)

	for i := 0; i < len(keys); i++ {
		key := keys[i]
		childPath := appendPath(path, key)
		if len(ignore) > 0 && contains(ignore, strings.Join(childPath, ".")) {
			continue
		}

		var childTracked *trackedProperty
		if tracked != nil && tracked.children != nil {
			childTracked = tracked.children[key]
		}

		result := detectMutations(
			isImmutable,
			ignore,
			childTracked,
			propertyValue(obj, key),
			sameRef,
			childPath,
		)

		if result.WasMutated {
			return result
		}
	}
	return MutationResult{WasMutated: false}
}

// unionKeys reproduces the JS `keysToDetect` object: keys from the tracked
// children (in their tracked order) followed by any additional own keys present
// on the current object, preserving first-seen order and de-duplicating.
func unionKeys(tracked *trackedProperty, obj Value) []string {
	seen := map[string]bool{}
	var keys []string

	if tracked != nil {
		for _, k := range tracked.childKeys {
			if !seen[k] {
				seen[k] = true
				keys = append(keys, k)
			}
		}
	}
	for _, k := range ownKeys(obj) {
		if !seen[k] {
			seen[k] = true
			keys = append(keys, k)
		}
	}
	return keys
}

// ownKeys returns the own enumerable keys of a container value, mirroring
// Object.keys / for..in. Non-containers have no enumerable keys.
func ownKeys(v Value) []string {
	switch c := v.(type) {
	case *Obj:
		return c.Keys()
	case *Arr:
		return c.Keys()
	default:
		return nil
	}
}

// propertyValue reads obj[key], returning Undefined for a missing key or a
// non-container, mirroring JS property access which yields `undefined`.
func propertyValue(v Value, key string) Value {
	switch c := v.(type) {
	case *Obj:
		if child, ok := c.Get(key); ok {
			return child
		}
		return Undefined
	case *Arr:
		idx, ok := parseIndex(key)
		if ok && idx >= 0 && idx < c.Len() {
			return c.At(idx)
		}
		return Undefined
	default:
		return Undefined
	}
}

// refEqual reproduces JS `===` for the values that flow through detection.
// Containers compare by reference (pointer identity); primitives compare by
// value. NaN !== NaN, matching IEEE-754 / JS semantics.
func refEqual(a, b Value) bool {
	switch av := a.(type) {
	case *Obj:
		bv, ok := b.(*Obj)
		return ok && av == bv
	case *Arr:
		bv, ok := b.(*Arr)
		return ok && av == bv
	case Str:
		bv, ok := b.(Str)
		return ok && av == bv
	case Num:
		bv, ok := b.(Num)
		// NaN is never equal to itself, matching JS `===`.
		return ok && !isNaNValue(av) && !isNaNValue(bv) && av == bv
	case Bool:
		bv, ok := b.(Bool)
		return ok && av == bv
	case nullType:
		_, ok := b.(nullType)
		return ok
	case undefinedType:
		_, ok := b.(undefinedType)
		return ok
	case nil:
		return b == nil
	default:
		return false
	}
}

// appendPath returns a new slice with key appended, never aliasing the caller's
// backing array. Mirrors the JS `path.concat(key)` which always allocates.
func appendPath(path []string, key string) []string {
	next := make([]string, len(path)+1)
	copy(next, path)
	next[len(path)] = key
	return next
}

// contains reports whether needle is present in haystack.
func contains(haystack []string, needle string) bool {
	for _, s := range haystack {
		if s == needle {
			return true
		}
	}
	return false
}

// parseIndex parses a non-negative decimal array index. Mirrors JS array index
// coercion for the string keys produced by Arr.Keys.
func parseIndex(s string) (int, bool) {
	if s == "" {
		return 0, false
	}
	n := 0
	for i := 0; i < len(s); i++ {
		c := s[i]
		if c < '0' || c > '9' {
			return 0, false
		}
		n = n*10 + int(c-'0')
	}
	return n, true
}