reorganize api doc

docs/api/modules/util.md

@@ -0,0 +1,169 @@
+# util
+
+# util
+
+
+A collection of general-purpose utility functions for object manipulation, merging,
+deep copying, safe property access, etc.
+
+
+## guid()
+
+
+**Returns**: A random 32-character string (hex).
+
+Return a random 32-character hexadecimal UUID-like string (not guaranteed RFC4122-compliant).
+
+
+## insertion_sort(arr, cmp)
+
+
+**arr**: The array to be sorted in-place.
+
+**cmp**: Comparison function cmp(a,b)->Number.
+
+**Returns**: The same array, sorted in-place.
+
+In-place insertion sort of an array using cmp(a,b)->Number for ordering.
+
+
+## deepfreeze(obj)
+
+
+**obj**: The object to recursively freeze.
+
+**Returns**: None
+
+Recursively freeze an object and all of its nested objects so they cannot be modified.
+
+
+## dainty_assign(target, source)
+
+
+**target**: The target object whose keys may be updated.
+
+**source**: The source object containing new values.
+
+**Returns**: None
+
+Copy non-function properties from source into matching keys of target without overwriting
+keys that don't exist in target. Arrays are deep-copied, and objects are recursively assigned.
+
+
+## get(obj, path, defValue)
+
+
+**obj**: The object to traverse.
+
+**path**: A string like "a.b.c" or an array of path segments.
+
+**defValue**: The default value if the property is undefined.
+
+**Returns**: The nested property or defValue.
+
+Safely retrieve a nested property from obj at path (array or dot-string).
+Returns defValue if the property is undefined.
+
+
+## isEmpty(o)
+
+
+**o**: The object to check.
+
+**Returns**: Boolean indicating if the object is empty.
+
+Return true if the object has no own properties, otherwise false.
+
+
+## dig(obj, path, def)
+
+
+**obj**: The root object to modify.
+
+**path**: A dot-string specifying nested objects to create.
+
+**def**: The value to store in the final path component, default {}.
+
+**Returns**: The assigned final value.
+
+Ensure a nested path of objects exists inside obj; create objects if missing, and set
+the final path component to def.
+
+
+## access(obj, name)
+
+
+**obj**: The object to traverse.
+
+**name**: A dot-string path (e.g. "foo.bar.baz").
+
+**Returns**: The value at that path, or undefined if missing.
+
+Traverse obj by dot-separated path name, returning the final value or undefined
+if any step is missing.
+
+
+## mergekey(o1, o2, k)
+
+
+**o1**: The target object.
+
+**o2**: The source object.
+
+**k**: The key to merge.
+
+**Returns**: None
+
+Helper for merge, updating key k from o2 into o1. Arrays are deep-copied and objects are
+recursively merged.
+
+
+## merge(target, objs)
+
+
+**target**: The target object.
+
+**objs**: One or more objects to merge into target.
+
+**Returns**: The updated target object.
+
+Merge all passed objects into target, copying or merging each key as needed.
+Arrays are deep-copied, objects are recursively merged, etc.
+
+
+## copy(proto, objs)
+
+
+**proto**: The prototype object for the new object.
+
+**objs**: One or more objects whose properties will be mixed in.
+
+**Returns**: The newly created object.
+
+Create a new object with proto as its prototype, then mix in additional objects’ properties.
+
+
+## obj_lerp(a, b, t)
+
+
+**a**: The start object (its properties must have .lerp()).
+
+**b**: The end object (matching properties).
+
+**t**: Interpolation factor (0..1).
+
+**Returns**: A new object with interpolated properties.
+
+Linearly interpolate between two objects a and b by factor t, assuming each property
+supports .lerp().
+
+
+## normalizeSpacing(spacing)
+
+
+**spacing**: A number, an array of length 2 or 4, or an object with l/r/t/b.
+
+**Returns**: An object {l, r, t, b}.
+
+Normalize any spacing input into a {l, r, t, b} object.
+