lib/debug: add traceFnSeqN

Immensely helpful when you want to see the changes a function makes to
its value as it passes through.

Example:

```
$ nix-instantiate --strict --eval -E '(with import ./lib; traceFnSeqN 2 "id" (x: x) { a.b.c = 3; })'
trace: {
  fn = "id";
  from = {
    a = {
      b = {…};
    };
  };
  to = {
    a = {
      b = {…};
    };
  };
}
{ a = { b = { c = 3; }; }; }
```

2 files changed, 23 insertions, 1 deletions

diff --git a/lib/debug.nix b/lib/debug.nix
index ea6aed60ab4..e3ca3352397 100644
--- a/lib/debug.nix
+++ b/lib/debug.nix
@@ -148,6 +148,28 @@ rec {
   /* A combination of `traceVal` and `traceSeqN`. */
   traceValSeqN = traceValSeqNFn id;
 
+  /* Trace the input and output of a function `f` named `name`,
+  both down to `depth`.
+
+  This is useful for adding around a function call,
+  to see the before/after of values as they are transformed.
+
+     Example:
+       traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
+       trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; }
+       => { a.b.c = 3; }
+  */
+  traceFnSeqN = depth: name: f: v:
+    let res = f v;
+    in lib.traceSeqN
+        (depth + 1)
+        {
+          fn = name;
+          from = v;
+          to = res;
+        }
+        res;
+
 
   # -- TESTING --
 
diff --git a/lib/default.nix b/lib/default.nix
index f985266ed93..803f1f76564 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -130,7 +130,7 @@ let
       assertMsg assertOneOf;
     inherit (self.debug) addErrorContextToAttrs traceIf traceVal traceValFn
       traceXMLVal traceXMLValMarked traceSeq traceSeqN traceValSeq
-      traceValSeqFn traceValSeqN traceValSeqNFn traceShowVal
+      traceValSeqFn traceValSeqN traceValSeqNFn traceFnSeqN traceShowVal
       traceShowValMarked showVal traceCall traceCall2 traceCall3
       traceValIfNot runTests testAllTrue traceCallXml attrNamesToStr;
     inherit (self.misc) maybeEnv defaultMergeArg defaultMerge foldArgs