Append unique ID to every ApiDOM element

[char0n]

minim that we use as an underlying ApiDOM structure library has a concept of assigning unique ID to any element and we can directly utilize it. The only question is what our ID will actually be.

I see options:

1.) Using global number counter

Every node will pull it's ID(number) from the counter during syntactic analysis. Counter keeps it's internal state. There are multiple problems associated with this approach like when working with already existing ApiDOMs and adding new node, we have to know what was the last ID.

2.) Using UUID

The only problem with this solution is the UUID size. We can pick some short variant of one of the UUID versions which has low computational requirements.

Ref https://shortunique.id/

3.) Having ID as ephemeral value

ApiDOM will not be aware of ID. We will use the same mechanism as we use for assigning CST nodes to ApiDOM Ast nodes.

Element decoration with unique ID

Decorating only semantic elements

We will decorate only semantic elements - specification objects like InfoElement, PathItemElement etc... We will not decorate every Element withing the tree - all properties that points to primitive data. IMHO we only need IDs for semantic nodes that we further work with using higher level algorithms like dereferencing or LS. Memory and storage footprint will be increased only marginally.

Decorating all elements

We will decorate all elements within the ApiDOM. This will increase memory and storage footprint of ApiDOM significantly and currently I cannot see a usecase when we will need it.

How to decorate elements ?

I propose we don't decorate inside element constructors but rather in refractor layer explicitly. Doing decoration inside element constructors pollute the elements with data that ApiDOM consumers may or may not need. We'll use refractor layer to decorate only semantic elements explicitly. We can introduce an option to turn this behavior off (in future). This allows to create additional plugins to annotate all elements with IDs if necessary in future.

---

I propose we go with Decorating only semantic elements in refractor layer using short variant implementation of UUID.

Update

It has been agreed that UUID decoration is going to be provided via refractor plugins.

[frantuma]

@char0n I'd go for 2...

[char0n]

We'll use https://shortunique.id/ with 6 characters long UUID which gives us

Collision probability: 0.000525877839496618%
Uniqueness: 99.9994741221605%

[frantuma]

Decorating in refractor layer sounds good to me.

About the all vs "significant" elements, I would actually prefer "all elements", this is both to have consistent "values" for all elements, and because I can foresee use cases for it, e.g. for keys of elements (like info key) etc.

I understand though this can be problematic in terms of performance and size (possibly limited, as each element is already quite verbose..), it would be ideal to provide both options as alternatives (so 1) no id, 2) significant, 3) all)