microsoft / microsoft/Power-Fx

Requested API breaking changes for a v2 API

Open
#2,811 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Breaking API
Dominant language
C#
Stars
3.4k
Forks
358
Avg merge
10h 34m
Merged PRs (30d)
3

Description

Current nugets are v1. Here are API breaking changes to consider for a v2 nuget. No change to language semantics here - just API breaking to take advantage of lessons learned in v1.

[1] Remove all [Obsolete] APIs*

[2] No usage of hidden awaits / .Result.
This is especially important for sandbox/governor scenarios - the host must know when any network calls are being made.

[3] Improved TableValue.Rows management
This is a case where it's too easy to call .Result under the hood. Improve to:

  • ensure host has full visibility into traversals. It's too easy to traverse a million rows.
  • allow optimizations like Sequence(100000) can be lazy and doesn't have to eagerly create the table.
  • better align with delegation. -

[4] Remove any FormulaValue equality, especially for RecordValues.
The Fx language does not allow equality operators on records. The API should not have operators that don't correspond to language semantics.

FormulaType equality is still valid, especially when comparing primitives.

More broadly - how can we ensue #2788 would have been a compile-time error, and that Distinct/Summarize/Join all have the same semantics.

[5] Remove FormulaValue.ToObject
This works well for primitives, but there are too many cases this fails for other types. Having RecordValue return a dynamically created object was too clever. Most usage of this API beyond primitives is just wrong. Callers will call ToObject to get an object and test it - there needs to be a way to conduct that test upfront.

TryGetPrimitive is good:
https://github.com/microsoft/Power-Fx/blob/f0af967deb8a79e719dd29a835d97563f185b5d2/src/libraries/Microsoft.PowerFx.Core/Public/Values/FormulaValue.cs#L82

We can add other safe TryGet accessors as needed.

[6] Any changes on PowerFxConfig?
PowerFxConfig is in core and used across engines. So it can't have any interpreter config.
What does config have that Engine doesn't? Need a clear articulation on the split.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the API areas listed in the issue, especially FormulaValue.cs and PowerFxConfig, then inspect issue #2788 and the referenced TryGetPrimitive API. Done requires an agreed v2 API design covering obsolete members, async visibility, table traversal, equality, value accessors, and the Config/Engine split.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
api, backend-api-design
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.