Dates are represented as DateTime

[ChuckJonas]

For Salesforce Date (no time) fields, the API returns a string in the format YYYY-MM-DD.

Without much thought, I choose to parse this to a Javascript Date object. This causes timezone related issues, which often result in a Date saved to salesforce being off +- 1 day.

In a minor version, I'm thinking I can add some consistency by converting the Date to UTC (without timezone translation) before serialization.

However, the issue still persists that a "Calendar Date" SHOULD NOT be represented as a moment in time....

In a major version (because this will be a breaking change), I'm thinking we should adopt one of the following...

Type Format

A: string mirroring salesforce.

PROS:

• Mirrors salesforce. No mapping required

CONS:

• No validation
• Typically would need to be parsed to work with date parts. This is easy to mess up

B: [number, number, number] tuple.

PROS:

• convenience of setting the field [2019, 10, 27]
• Easy to work with date parts
• Requires mapping to and from salesforce

CONS:

• Ambiguous. Developer must know & remember it's year,month,day

C: {year: number; month: number; day: number;} Obj

PROS:

• Easy to work with dateparts
• Not ambiguous
• Requires mapping to and from salesforce

CONS:

• More verbose than B

Month Format

If we go with option B or C, then we also need to decide if we want to store month as 0-11 or 1-12...

0-11

Pros:

• consistent with javascript Date Object.

Cons:

• Value from salesforce would need to be parsed
• Need to be translated for Human Readable dates

1-12

Pros:

• This is how most people typically conceptualize months
• No need to parse for simple formatting

Cons:

• inconsistent with javascript Date Object.

[ChuckJonas]

Leaning toward option C & 0-11. With this approach you would be able to pass the object directly into momentjs

const today = moment({ year:2019, month: 10, day: 3 });

day.js (popular alternative), does not support this yet, but may at some point

[CarsonF]

FWIW I use Luxon and its fromISO supports ISO dates without time out of the box. I really enjoy Luxon's API too.