luxon icon indicating copy to clipboard operation
luxon copied to clipboard

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

Open adamreisnz opened this issue 3 years ago • 1 comments

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.

adamreisnz avatar May 07 '21 22:05 adamreisnz

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.

icambron avatar May 23 '21 18:05 icambron