¿Hay algún patrón para manejar parámetros de funciones en conflicto?

Tenemos una función API que desglosa un monto total en montos mensuales en función de las fechas de inicio y finalización.

// JavaScript

function convertToMonths(timePeriod) {
  // ... returns the given time period converted to months
}

function getPaymentBreakdown(total, startDate, endDate) {
  const numMonths = convertToMonths(endDate - startDate);

  return {
    numMonths,
    monthlyPayment: total / numMonths,
  };
}

Recientemente, un consumidor de esta API quería especificar el rango de fechas de otras maneras: 1) proporcionando el número de meses en lugar de la fecha de finalización, o 2) proporcionando el pago mensual y calculando la fecha de finalización. En respuesta a esto, el equipo de API cambió la función a la siguiente:

// JavaScript

function addMonths(date, numMonths) {
  // ... returns a new date numMonths after date
}

function getPaymentBreakdown(
  total,
  startDate,
  endDate /* optional */,
  numMonths /* optional */,
  monthlyPayment /* optional */,
) {
  let innerNumMonths;

  if (monthlyPayment) {
    innerNumMonths = total / monthlyPayment;
  } else if (numMonths) {
    innerNumMonths = numMonths;
  } else {
    innerNumMonths = convertToMonths(endDate - startDate);
  }

  return {
    numMonths: innerNumMonths,
    monthlyPayment: total / innerNumMonths,
    endDate: addMonths(startDate, innerNumMonths),
  };
}

Siento que este cambio complica la API. Ahora la persona que llama tiene que preocuparse por la heurística ocultos en la implementación de la función en la determinación de los parámetros que tienen preferencia en la que se utiliza para calcular el intervalo de fechas (es decir, por orden de prioridad monthlyPayment, numMonths, endDate). Si una persona que llama no presta atención a la firma de la función, puede enviar varios de los parámetros opcionales y confundirse sobre por qué endDatese ignora. Sí especificamos este comportamiento en la documentación de la función.

Además, creo que sienta un mal precedente y agrega responsabilidades a la API con las que no debería preocuparse (es decir, violar SRP). Suponga que consumidores adicionales desean que la función admita más casos de uso, como el cálculo a totalpartir de los parámetros numMonthsy monthlyPayment. Esta función se volverá cada vez más complicada con el tiempo.

Mi preferencia es mantener la función como estaba y, en cambio, exigirle a la persona que llama que se calcule endDate. Sin embargo, puedo estar equivocado y me preguntaba si los cambios que hicieron fueron una forma aceptable de diseñar una función API.

Alternativamente, ¿hay un patrón común para manejar escenarios como este? Podríamos proporcionar funciones adicionales de orden superior en nuestra API que envuelvan la función original, pero esto aumenta la API. Tal vez podríamos agregar un parámetro de indicador adicional que especifique qué enfoque usar dentro de la función.

Al ver la implementación, me parece que lo que realmente necesita aquí son 3 funciones diferentes en lugar de una:

El original:

function getPaymentBreakdown(total, startDate, endDate) 

El que proporciona el número de meses en lugar de la fecha de finalización:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

y el que proporciona el pago mensual y calcula la fecha de finalización:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Ahora, ya no hay parámetros opcionales, y debería quedar bastante claro qué función se llama cómo y para qué propósito. Como se menciona en los comentarios, en un lenguaje estrictamente tipado, uno también podría utilizar la sobrecarga de funciones, distinguiendo las 3 funciones diferentes no necesariamente por su nombre, sino por su firma, en caso de que esto no ofusque su propósito.

Tenga en cuenta que las diferentes funciones no significan que tenga que duplicar ninguna lógica: internamente, si estas funciones comparten un algoritmo común, se debe refactorizar a una función "privada".

¿Existe un patrón común para manejar escenarios como este?

No creo que haya un "patrón" (en el sentido de los patrones de diseño de GoF) que describa un buen diseño de API. El uso de nombres autodescriptivos, funciones con menos parámetros, funciones con parámetros ortogonales (= independientes), son solo principios básicos para crear código legible, mantenible y evolutivo. No toda buena idea en programación es necesariamente un "patrón de diseño".

Además, creo que sienta un mal precedente y agrega responsabilidades a la API con las que no debería preocuparse (es decir, violar SRP). Suponga que consumidores adicionales desean que la función admita más casos de uso, como el cálculo a totalpartir de los parámetros numMonthsy monthlyPayment. Esta función se volverá cada vez más complicada con el tiempo.

Estás exactamente en lo correcto.

Mi preferencia es mantener la función como estaba y, en cambio, pedirle a la persona que llama que calcule endDate por sí misma. Sin embargo, puedo estar equivocado y me preguntaba si los cambios que hicieron fueron una forma aceptable de diseñar una función API.

Esto tampoco es ideal, porque el código de la persona que llama estará contaminado con una placa de caldera no relacionada.

Alternativamente, ¿hay un patrón común para manejar escenarios como este?

Introducir un nuevo tipo, como DateInterval. Agregue los constructores que tengan sentido (fecha de inicio + fecha de finalización, fecha de inicio + número de meses, lo que sea). Adopte esto como los tipos de moneda común para expresar intervalos de fechas / horas en todo su sistema.

A veces, las expresiones fluidas ayudan en esto:

let payment1 = forTotalAmount(1234)
                  .breakIntoPayments()
                  .byPeriod(months(2));

let payment2 = forTotalAmount(1234)
                  .breakIntoPayments()
                  .byDateRange(saleStart, saleEnd);

let monthsDue = forTotalAmount(1234)
                  .calculatePeriod()
                  .withPaymentsOf(12.34)
                  .monthly();

Con tiempo suficiente para diseñar, puede llegar a una API sólida que actúe de manera similar a un lenguaje específico de dominio.

La otra gran ventaja es que los IDE con autocompletado hacen que sea casi irreverente leer la documentación de la API, como es intuitivo debido a sus capacidades de autodescubrimiento.

Existen recursos como https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ o https://github.com/nikaspran/fluent.js sobre este tema.

Ejemplo (tomado del primer enlace de recursos):

let insert = (value) => ({into: (array) => ({after: (afterValue) => {
  array.splice(array.indexOf(afterValue) + 1, 0, value);
  return array;
}})});

insert(2).into([1, 3]).after(1); //[1, 2, 3]

Bueno, en otros idiomas, usarías parámetros con nombre . Esto se puede emular en Javscript:

function getPaymentBreakdown(total, startDate, durationSpec) { ... }

getPaymentBreakdown(100, today, {endDate: whatever});
getPaymentBreakdown(100, today, {noOfMonths: 4});
getPaymentBreakdown(100, today, {monthlyPayment: 20});

Como alternativa, también puede romper la responsabilidad de especificar el número de meses y dejarlo fuera de su función:

getPaymentBreakdown(420, numberOfMonths(3))
getPaymentBreakdown(420, dateRage(a, b))
getPaymentBreakdown(420, paymentAmount(350))

Y getpaymentBreakdown recibiría un objeto que proporcionaría el número base de meses

Esas funciones de orden superior devolverían, por ejemplo, una función.

function numberOfMonths(months) {
  return {months: (total) => months};
}

function dateRange(startDate, endDate) {
  return {months: (total) => convertToMonths(endDate - startDate)}
}

function monthlyPayment(amount) {
  return {months: (total) => total / amount}
}


function getPaymentBreakdown(total, {months}) {
  const numMonths= months(total);
  return {
    numMonths, 
    monthlyPayment: total / numMonths,
    endDate: addMonths(startDate, numMonths)
  };
}

Y si estuviera trabajando con un sistema con uniones discriminadas / tipos de datos algebraicos, podría pasarlo como, por ejemplo, a TimePeriodSpecification.

type TimePeriodSpecification =
    | DateRange of startDate : DateTime * endDate : DateTime
    | MonthCount of startDate : DateTime * monthCount : int
    | MonthlyPayment of startDate : DateTime * monthlyAmount : float

y luego ninguno de los problemas ocurriría cuando no pudieras implementar uno y así sucesivamente.