clan-core/lib/default.nix

{
  lib,
}:
lib.fix (
  let
    f =
      clanLib:
      {
        __unfix__ = f;
        clan = throw "lib.clan is not yet initialized. Use lib.clan exported by the clan-core flake.";

        # TODO: Hide from public interface
        # TODO: Flatten our lib functions like this:
        checkConfig = import ./clan/checkConfig.nix { inherit lib; };
        evalService = import ./evalService.nix { inherit lib clanLib; };

        resolveModule = import ./resolve-module { inherit lib clanLib; };
        inventory = import ./inventory { inherit lib clanLib; };
        flake-inputs = import ./flake-inputs.nix { inherit lib clanLib; };

        types = import ./types { inherit lib clanLib; };

        introspection = import ./introspection { inherit lib; };
        jsonschema = import ./jsonschema { inherit lib clanLib; };
        docs = import ./docs.nix { inherit lib; };

        flakes = import ./flakes.nix { inherit lib clanLib; };

        fs = {
          inherit (builtins) pathExists readDir;
        };

        # ------------------------------------
        # Public ClanLib functions
        # TODO: Hoist all functions directly into clanLib

        # getPublicValue = import ./get-public-value.nix { inherit lib; };

        test = import ./test { inherit lib clanLib; };

        # Deprecated will be removed with the next release
        vars.getPublicValue = lib.warn "'vars.getPublicValue' was renamed. Use 'getPublicValue' instead." clanLib.getPublicValue;

        # Experimental
        exports = throw "clanLib.exports has been renamed. Use the utility in clanLib directly";
        /**
          Map the list and merge the list of sets into a new attribute set
           # Inputs
          `f`
           : 1\. Function argument
           `list`
           : 2\. Function argument
           # Type
           ```
          concatMapListToAttrs :: (a -> AttrSet) -> [a] -> AttrSet
          ```
           # Examples
          :::{.example}
          ## `clanLib.concatMapListToAttrs` usage example
           ```nix
          concatMapListToAttrs
            (name: {
              ${name} = name;
              z = name;
            })
            [ "a" "b" ]
          => { a = "a"; b = "b"; z = "b"; }
          ```
           :::
        */
        concatMapListToAttrs = f: list: lib.zipAttrsWith (_name: values: lib.last values) (map f list);

        /**
          Upper-case the first character, leave the rest alone

          # Inputs

          `str`
          : Input string

          # Type

          ```
          toUpperFirst :: string -> string
          ```

          # Examples
          :::{.example}
          ## `toUpperFirst` usage example

          ```nix
          toUpperFirst "foo"
          => "Foo"
          hasPrefix "fooBar"
          => "FooBar"
          ```

          :::
        */
        toUpperFirst =
          str:
          lib.throwIfNot (lib.isString str)
            "toUpperFirst only accepts string values, but got ${lib.typeOf str}"
            (
              let
                firstChar = lib.substring 0 1 str;
                rest = lib.substring 1 (-1) str;
              in
              lib.addContextFrom str (lib.toUpper firstChar + rest)
            );
        /**
          Replace a list's nth element with a new element

          # Inputs

          `list`
          : Input list

          `idx`
          : index to replace

          `newElem`
          : new element to replace with

          # Type

          ```
          replaceElemAt :: [a] -> int - b -> [a]
          ```

          # Examples
          :::{.example}
          ## `replaceElemAt` usage example

          ```nix
          lib.replaceElemAt` [1 2 3] 0 "a"
          => ["a" 2 3]
          ```

          :::
        */
        replaceElemAt =
          list: idx: newElem:
          lib.imap0 (i: oldElem: if i == idx then newElem else oldElem) list;

        /**
          Create a removed option that throws when used.

          This is useful for interface modules where NixOS assertions aren't available.

          # Inputs

          `name`
          : Option name for the error message

          `message`
          : Migration instructions or reason for removal

          # Type

          ```
          mkRemovedOption :: string -> string -> option
          ```

          # Examples
          :::{.example}
          ## `mkRemovedOption` usage example

          ```nix
          options.oldOption = clanLib.mkRemovedOption "oldOption" "Use 'newOption' instead.";
          ```

          :::
        */
        mkRemovedOption =
          name: message:
          lib.mkOption {
            visible = false;
            default = null;
            type = lib.types.raw;
            apply = _: throw "The option '${name}' was removed. ${message}";
          };
      }
      // (import ./vars/default.nix { inherit lib; })
      // (import ./exports/exports.nix { inherit lib clanLib; });
  in
  f
)