fnNthWeekday

fnNthWeekday(Ano as number, Mes as number, DiaDaSemana as number, N as number) as nullable date

let
    fnNthWeekday = (Ano as number, Mes as number, DiaDaSemana as number, N as number) as nullable date =>
        let
            vPrimeiroDia = #date(Ano, Mes, 1),
            // Dias até o primeiro DiaDaSemana do mês (0 a 6); 0 = segunda ... 6 = domingo
            vDesloc = Number.Mod(DiaDaSemana - Date.DayOfWeek(vPrimeiroDia, Day.Monday) + 7, 7),
            vData = Date.AddDays(vPrimeiroDia, vDesloc + 7 * (N - 1))
        in
            // N inválido, dia fora de 0-6 ou ocorrência que cai no mês seguinte → null
            if N < 1 or not List.Contains({0 .. 6}, DiaDaSemana) or Date.Month(vData) <> Mes then null
            else vData,

    Documentacao = [
        Documentation.Name = "fnNthWeekday",
        Documentation.Description = "Enésima ocorrência de um dia da semana num mês.",
        Documentation.LongDescription = "DiaDaSemana vai de 0 (segunda) a 6 (domingo), a mesma numeração de Date.DayOfWeek(data, Day.Monday). Retorna null quando a ocorrência não existe no mês, quando N < 1 ou quando DiaDaSemana está fora de 0-6.",
        Documentation.Category = "Data e hora",
        Documentation.Author = "Paulo André Jesus",
        Documentation.Version = "1.1",
        Documentation.Examples = {
            [Description = "3ª segunda-feira de janeiro de 2025", Code = "fnNthWeekday(2025, 1, 0, 3)", Result = "#date(2025, 1, 20)"],
            [Description = "2ª sexta-feira de julho de 2024", Code = "fnNthWeekday(2024, 7, 4, 2)", Result = "#date(2024, 7, 12)"],
            [Description = "5ª segunda-feira de fevereiro de 2025 (não existe)", Code = "fnNthWeekday(2025, 2, 0, 5)", Result = "null"]
        }
    ]
in
    Value.ReplaceType(fnNthWeekday, Value.ReplaceMetadata(Value.Type(fnNthWeekday), Documentacao))