Promote usage of TraversableTypedDataInterface

This sounds like a good idea to me though I'm not that sure about changing the DataDefinition interfaces. We need also some clarification about what is a Property, what is an Item, what is an Element..

Also some methods that look the same are not actually the same, and I think this is a major DX issue that will be fixed by this patch:

interface ComplexDataInterface extends TraversableTypedDataInterface {
  /**
   * Gets a property object.
   *
   * @param $property_name
   *   The name of the property to get; e.g., 'title' or 'name'.
   *
   * @return \Drupal\Core\TypedData\TypedDataInterface
   *   The property object.
   *
   * @throws \InvalidArgumentException
   *   If an invalid property name is given.
   * @throws \Drupal\Core\TypedData\Exception\MissingDataException
   *   If the complex data structure is unset and no property can be created.
   */
  public function get($property_name);
}

interface ListInterface extends TraversableTypedDataInterface, \ArrayAccess, \Countable {
  /**
   * Returns the item at the specified position in this list.
   *
   * @param int $index
   *   Index of the item to return.
   *
   * @return \Drupal\Core\TypedData\TypedDataInterface|null
   *   The item at the specified position in this list, or NULL if no item
   *   exists at that position.
   *
   * @throws \Drupal\Core\TypedData\Exception\MissingDataException
   *   If the complex data structure is unset and no item can be created.
   */
  public function get($index);
}

Or also, this one that looks like trivial is very confusing.

interface ComplexDataInterface extends TraversableTypedDataInterface {
  /**
   * Determines whether the data structure is empty.
   *
   * @return boolean
   *   TRUE if the data structure is empty, FALSE otherwise.
   */
  public function isEmpty();
}

interface ListInterface extends TraversableTypedDataInterface, \ArrayAccess, \Countable {
  /**
   * Determines whether the list contains any non-empty items.
   *
   * @return boolean
   *   TRUE if the list is empty, FALSE otherwise.
   */
  public function isEmpty();
}

Some handy links to follow this issue:
- ComplexDataInterface,
https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21TypedData...
- ListInterface,
https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21TypedData...
- DataDefinitionInterface hierarchy, https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21TypedData...

@tstoeckler,

Oh, no, what I mean is they must be fixed because having same method in similar interfaces with different semantics is really horrible, horrible DX. So we better consolidate all of them in TraversableTypedDataInterface.

So I'm 100% for this patch. I just mean it needs to be done carefully, looking at the different semantics and implementations and actually consolidating the behavior, not only the names of the methods.

One simple example: TraversableTypedDataInterface:get()
- The interface needs to specify exactly what happens (exception?) when we try to get a key that doesn't exist (for which there are two options, that it is not in the data and that it is not defined). Atm this is different for ComplexDataInterface and ListInterface.

TypedData is atm a major mess, and also lacking documentation everywhere about the purpose of each class and it should be fixed.

It is good to know that we have such an issue already!
Disclaimer: I have no idea about typed data.

Move get() and isEmpty() up from ListInterface and ComplexDataInterface. These are not API changes.

Well, according to https://secure.php.net/manual/it/class.traversable.php this is for stuff, that can be foreached. Do those things have an empty() function? Also an Iterator doesn't have the concept of random access/checking whether its empty. One question someone could ask is: What is the semantic information of traversable in typed data. For me at least, just by its naming, adding get() / empty() doesn't make sense necessarily.

I don't think this is something we should do. Reasons:

• I strongly dislike establishing TraversableTypedDataInterface more as it has no semantic meaning, but highlights a PHP implementation detail of being traversable. (I missed the issue where it was introduced...). I think we should go for #2350597: Extract a common DataContainerInterface for lists and complex data and deprecate TraversableTypedDataInterface instead.
• I'm wary about introducing the concept of an "element". So then everything is typed data, a list item, and a traversable element. Yet another abstraction you have to grasp and understand.

That said, the need for a comon parent interface for data containers is there. That should have a semantic meaning though and try to avoid introducing new terms that we have to learn/teach.

Oh, no, what I mean is they must be fixed because having same method in similar interfaces with different semantics is really horrible, horrible DX. So we better consolidate all of them in TraversableTypedDataInterface.

Lists and maps are different, I don't see why that makes a horrible DX when a list has items and a map has properties.

#1928868: Typed config incorrectly implements Typed Data interfaces shows that we miss proper support for an ordered, keyed collection of elements, having unknown keys. Maybe it would be best to just add dedicated supported for such a data structure? E.g., would the following make sense to you?

- DataContainer (parent data structure, no metadata nor API for fetching contained elements. Can have utility methods like isEmpty() or toArray())
|--- Complex Data (map with named properties)
|---- List (ordered list of items)
|---- Collection (ordered list of key,value pairs)

Complex data does not qualify as Collection, because the values are of a different type. (Depends on how you define "Collection" exactly). Given that, config schema sequences would be collections, which can be handled as lists also. (Thus the sub-type relationship).

Giving the whole topic of data structures maps, collections etc. some more thoughts (once again), I figured the following:

- Collections are mostly considered as a very generic data structure, containing things like sets or trees. So it's probably not a good choice for "ordered list of key,value pairs", that's an ordered map.
- Map vs Complex Data and ordering: Our complex data does define whether it's considered ordered or not, what means you have to be able to work with either. Imo, it would be totally fine to have an implementation that is ordered.
But one thing we miss is the definition whether it may contain additional properties or not. E.g., json schema has that "additionalProperties" indicator for objects.
- A config schema sequence would be fine as ordered implementation of complex data, that allows additional properties (and has no metadata about pre-existing properties).

#2350597: Extract a common DataContainerInterface for lists and complex data is about to deprecated TraversableTypedDataInterface, so marking this as won't fix.