fix(launchd): improve `StartCalendarInterval`

Stricter launchd -> StartCalendarInterval type:

- Verify that the integers passed to `Minute`, `Hour`, etc. are within
  range.

- When provided, the value for StartCalendarInterval must be a non-empty
  list of calendar intervals and must not contain duplicates entries
  (throw an error otherwise).

- For increased flexibility and backwards-compatibility, allow an
  attrset to be passed as well (which will be type-checked and is
  functionally equivalent to passing a singleton list). Allowing an
  attrset or list is precisely in-line with what `launchd.plist(5)`
  accepts for StartCalendarInterval.

Migrate `nix.gc.interval` and `nix.optimise.interval` over to use this
new type, and update their defaults to run weekly instead of daily.

Create `modules/launchd/types.nix` file for easier/modular use of
launchd types needed in multiple files.

Documentation:

- Update and improve wording/documentation of launchd's
  `StartCalendarInterval`.

- Improve wording/documentation of `nix.gc.interval` and
  `nix.optimise.interval` ("time interval" can be misleading as it's
  actually a "calendar interval"; e.g. `{ Hour = 3; Minute = 15;}`
  runs daily, not every 3.25 hours).

1 files changed, 17 insertions, 48 deletions

diff --git a/modules/launchd/launchd.nix b/modules/launchd/launchd.nix
index 9fecde6..add0514 100644
--- a/modules/launchd/launchd.nix
+++ b/modules/launchd/launchd.nix
@@ -2,6 +2,10 @@
 
 with lib;
 
+let
+  launchdTypes = import ./types.nix { inherit config lib; };
+in
+
 {
   options = {
     Label = mkOption {
@@ -344,55 +348,21 @@ with lib;
       default = null;
       example = [{ Hour = 2; Minute = 30; }];
       description = ''
-        This optional key causes the job to be started every calendar interval as specified. Missing arguments
-        are considered to be wildcard. The semantics are much like `crontab(5)`.  Unlike cron which skips job
-        invocations when the computer is asleep, launchd will start the job the next time the computer wakes
+        This optional key causes the job to be started every calendar interval as specified. The semantics are
+        much like {manpage}`crontab(5)`: Missing attributes are considered to be wildcard. Unlike cron which skips
+        job invocations when the computer is asleep, launchd will start the job the next time the computer wakes
         up.  If multiple intervals transpire before the computer is woken, those events will be coalesced into
-        one event upon wake from sleep.
-      '';
-      type = types.nullOr (types.listOf (types.submodule {
-        options = {
-          Minute = mkOption {
-            type = types.nullOr types.int;
-            default = null;
-            description = ''
-              The minute on which this job will be run.
-            '';
-          };
-
-          Hour = mkOption {
-            type = types.nullOr types.int;
-            default = null;
-            description = ''
-              The hour on which this job will be run.
-            '';
-          };
-
-          Day = mkOption {
-            type = types.nullOr types.int;
-            default = null;
-            description = ''
-              The day on which this job will be run.
-            '';
-          };
+        one event upon waking from sleep.
 
-          Weekday = mkOption {
-            type = types.nullOr types.int;
-            default = null;
-            description = ''
-              The weekday on which this job will be run (0 and 7 are Sunday).
-            '';
-          };
+        ::: {.important}
+        The list must not be empty and must not contain duplicate entries (attrsets which compare equally).
+        :::
 
-          Month = mkOption {
-            type = types.nullOr types.int;
-            default = null;
-            description = ''
-              The month on which this job will be run.
-            '';
-          };
-        };
-      }));
+        ::: {.caution}
+        Since missing attrs become wildcards, an empty attrset effectively means "every minute".
+        :::
+      '';
+      type = types.nullOr launchdTypes.StartCalendarInterval;
     };
 
     StandardInPath = mkOption {
@@ -886,6 +856,5 @@ with lib;
     };
   };
 
-  config = {
-  };
+  config = {};
 }