moment / luxon

⏱ A library for working with dates and times in JS
https://moment.github.io/luxon
MIT License
15.28k stars 732 forks source link

Document that both singular and plural form is accepted for object/string #932

Open adamreisnz opened 3 years ago

adamreisnz commented 3 years ago

Is your feature request related to a problem? Please describe. It is unclear that functions like Duration.fromObject() and dateTime.startOf/endOf accept both singular and plural form of period parameters (e.g. month and months are both valid).

I had to figure this out by trial and error because the API documentation for these functions isn't clear on that:

const {DateTime, Duration} = require('luxon');

const s1 = DateTime.local().startOf('month');
const s2 = DateTime.local().startOf('months');

console.log(s1.toObject()); //{year: 2021, month: 5, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0}
console.log(s2.toObject()); //{year: 2021, month: 5, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0}

const d1 = Duration.fromObject({month: 2});
const d2 = Duration.fromObject({months: 2});

console.log(d1.toObject()); //{months: 2}
console.log(d2.toObject()); //{months: 2}

This is neat of course, as it saves us the hassle of having to convert a period from singular to plural or vice versa depending on what function we want to put it in, but it would be nice if it could be better documented so newcomers to Luxon can be aware of this.

Describe the solution you'd like Update the documentation for methods like Duration.fromObject(), dateTime.startOf(), dateTime.endOf() to clarify that both singular and plural form can be used for the object keys or as strings.

icambron commented 3 years ago

Luxon goes pretty far out of its way to make this work, simply because in practice, it's super frustrating if it doesn't work (early designs of Luxon only accepted singular for DateTimes and plural for Durations and it even frustrated me). In general, I'm against Robustness Principle flakiness like this, so I tried documenting it, but it just ended up cluttered and confusing. If you can do it in a way that doesn't add voluminous docstrings all saying basically the same thing, I'd accepted.