Skip to content

Suggestion: remove disambiguation: 'balance' for non-Duration types #609

@justingrant

Description

@justingrant

disambiguation: 'balance' is a challenging concept to understand and explain. I understand why it's useful and necessary for Duration, but why is it useful for non-Duration types?

I'm asking because almost every other Temporal feature has many obvious use cases, but I've been unable to think of a single use case where disambiguation: 'balance' results in clearer code vs. just using plus or minus instead.

For example, here's the (only) cookbook example that uses disambiguation: 'balance':

function plusAndRoundToMonthStart(date, delayDays) {
  const delayedDate = date.plus({ days: delayDays });
  const month = delayedDate.month + 1;
  return delayedDate.with({ month, day: 1 }, { disambiguation: 'balance' });
}

Rewriting it to use addition & subtraction makes the code easier to understand, esp. for developers new to Temporal.

// using arithmetic
function plusAndRoundToMonthStart(date, delayDays) {
  return date.plus({ days: delayDays })
    .plus({month: 1})  // constrains to end of month if needed, e.g. Jan 31 -> Feb 28 
    .with({day: 1});
}

What are other non-Duration use cases where disambiguation: 'balance' is superior to plus/minus?

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions