feat(watch): implement --debounce flag with duration (#16187)

- fixes #16178
- `watch --debounce-ms` deprecated

Co-authored-by: Luca Scherzer <luca.scherzer@de.clara.net>

crates/nu-command/src/filesystem/watch.rs

@@ -6,7 +6,11 @@ use notify_debouncer_full::{
     },
 };
 use nu_engine::{ClosureEval, command_prelude::*};
-use nu_protocol::{engine::Closure, report_shell_error, shell_error::io::IoError};
+use nu_protocol::{
+    DeprecationEntry, DeprecationType, ReportMode, engine::Closure, report_shell_error,
+    shell_error::io::IoError,
+};
+
 use std::{
     path::PathBuf,
     sync::mpsc::{RecvTimeoutError, channel},
@@ -33,6 +37,16 @@ impl Command for Watch {
         vec!["watcher", "reload", "filesystem"]
     }
 
+    fn deprecation_info(&self) -> Vec<DeprecationEntry> {
+        vec![DeprecationEntry {
+            ty: DeprecationType::Flag("--debounce-ms".into()),
+            report_mode: ReportMode::FirstUse,
+            since: Some("0.107.0".into()),
+            expected_removal: Some("0.109.0".into()),
+            help: Some("`--debounce-ms` will be removed in favour of  `--debounce`".into()),
+        }]
+    }
+
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("watch")
         .input_output_types(vec![(Type::Nothing, Type::table())])
@@ -43,7 +57,13 @@ impl Command for Watch {
             .named(
                 "debounce-ms",
                 SyntaxShape::Int,
-                "Debounce changes for this many milliseconds (default: 100). Adjust if you find that single writes are reported as multiple events",
+                "Debounce changes for this many milliseconds (default: 100). Adjust if you find that single writes are reported as multiple events (deprecated)",
+                None,
+            )
+            .named(
+                "debounce",
+                SyntaxShape::Duration,
+                "Debounce changes for this duration (default: 100ms). Adjust if you find that single writes are reported as multiple events",
                 Some('d'),
             )
             .named(
@@ -95,11 +115,25 @@ impl Command for Watch {
 
         let quiet = call.has_flag(engine_state, stack, "quiet")?;
 
-        let debounce_duration_flag: Option<Spanned<i64>> =
+        let debounce_duration_flag_ms: Option<Spanned<i64>> =
             call.get_flag(engine_state, stack, "debounce-ms")?;
-        let debounce_duration = match debounce_duration_flag {
-            Some(val) => match u64::try_from(val.item) {
-                Ok(val) => Duration::from_millis(val),
+
+        let debounce_duration_flag: Option<Spanned<Value>> =
+            call.get_flag(engine_state, stack, "debounce")?;
+
+        let debounce_duration: Duration = match (debounce_duration_flag, debounce_duration_flag_ms)
+        {
+            (None, None) => DEFAULT_WATCH_DEBOUNCE_DURATION,
+            (Some(l), Some(r)) => {
+                return Err(ShellError::IncompatibleParameters {
+                    left_message: "Here".to_string(),
+                    left_span: l.span,
+                    right_message: "and here".to_string(),
+                    right_span: r.span,
+                });
+            }
+            (None, Some(val)) => match u64::try_from(val.item) {
+                Ok(v) => Duration::from_millis(v),
                 Err(_) => {
                     return Err(ShellError::TypeMismatch {
                         err_message: "Debounce duration is invalid".to_string(),
@@ -107,7 +141,18 @@ impl Command for Watch {
                     });
                 }
             },
-            None => DEFAULT_WATCH_DEBOUNCE_DURATION,
+            (Some(v), None) => {
+                let Value::Duration { val, .. } = v.item else {
+                    return Err(ShellError::TypeMismatch {
+                        err_message: "Debounce duration must be a duration".to_string(),
+                        span: v.item.span(),
+                    });
+                };
+                Duration::from_nanos(u64::try_from(val).map_err(|_| ShellError::TypeMismatch {
+                    err_message: "Debounce duration is invalid".to_string(),
+                    span: v.item.span(),
+                })?)
+            }
         };
 
         let glob_flag: Option<Spanned<String>> = call.get_flag(engine_state, stack, "glob")?;
@@ -294,6 +339,11 @@ impl Command for Watch {
                 example: r#"watch /foo/bar { |op, path| $"($op) - ($path)(char nl)" | save --append changes_in_bar.log }"#,
                 result: None,
             },
+            Example {
+                description: "Print file changes with a debounce time of 5 minutes",
+                example: r#"watch /foo/bar --debounce 5min { |op, path| $"Registered ($op) on ($path)" | print }"#,
+                result: None,
+            },
             Example {
                 description: "Note: if you are looking to run a command every N units of time, this can be accomplished with a loop and sleep",
                 example: r#"loop { command; sleep duration }"#,

crates/nu-protocol/src/value/mod.rs

@@ -89,6 +89,7 @@ pub enum Value {
         internal_span: Span,
     },
     Duration {
+        /// The duration in nanoseconds.
         val: i64,
         /// note: spans are being refactored out of Value
         /// please use .span() instead of matching this span value