Make typed data resolver actually work with typed data interfaces

I've started looking into typed data resolver and how to improve it. This is going to be very long, but I have to write down some basics and my thoughts to be able to discuss this.

I don't think typed data is as bad as you make it. It definitely gives you the API's and definitions to access any value in it's data structure. The problem is that the structure is more complex than you try to make it. Typed Data consists of 3/4 different things:

- lists: ListInterface/ListDataDefinitionInterface
- complex data: ComplexDataInterface/ComplexDataDefinitionInterface
- "simple" data: DataInterface/ComplexDataInterface
- a special kind of data, references: DataReferenceDefinitionInterfac

In regards to type data, you can combine that in any way. you can have lists of lists, multiple nested complex data structures and eventually, you have the actual (sometimes but not always primitive) data.

It's not completely up to date, but there are actually fairly good docs on how content entities use typed data here: https://www.drupal.org/node/1795854

content entity structure, unlike typed data in general, is fixed. (at least down to the property) It always is:

Entity:Field:FieldItem:Property

Or, using the typed data names:
complex:list:complex:*

Property can be multiple things, a primitive, a reference, or complex data.

From looking at the current resolver code, the main problem is that you try to access entities with too simplified assumptions about it's structure and are to achieve that, use methods that actually have nothing to do with typed data.

Some examples, assuming we want to get the value of node:langcode:

$value = $this->getFirstApplicableTypeResolver($property)->getValueFromProperty($context->getContextValue()->$property_name);

getContextValue() doesn't return typed data. It returns whatever the value is and in this case, a node object. You also rely on magic __get(), which is a content entity specific feature. You want getContextData(). That just gives you typed data, but the method is getContextFromProperty(), so we can assume that we actually have complex data here. Which has a get($property_name) method.

  /**
   * {@inheritdoc}
   */
  public function appliesToProperty(ListDataDefinitionInterface $property) {
    return $property->getType() == 'entity_reference';
  }

ListDataDefinitionInterface has no getType() method. That is actually from FieldStorageDefinitionInterface, and it returns the *field type*. The typed data type is return with getDataType() and is... "list" (surprise! ;)). That's because FieldStorageDefinition/Field is simply a list of field items for typed data. So, the list definition itself is not relevant for figuring out what's actually inside, you need to check the list item definition. $property->getItemDefinition()->getDataType() gives you for the langcode field "field_item:langcode". It's *not* a langcode/language. It's a langcode field item.

So we need to look at the properties. $property->getItemDefinition()->getPropertyDefinitions() returns two, value and language. value is a simple string and contains the language code, language is the reference to the language object, a DataReferenceDefinition with the data type language_reference. It also has a getTargetDefinition() that finally contains the definition/type for the object we want, a language.

So, for your node:langcode, the typed data property path for the thing you actually want is node.langcode.0.language (the value of a reference is it's target, it does have its own definition and that of the target, though). And for node:type, to get the node type object, it's node.type.0.entity.

So the question is how do we actually get there in a generic way. It's pretty clear to me that "node:langcode" is a too simplified representation, but what's not clear to me is what ctools actually wants to achieve:

* What about multiple values. getCardinality() is again a field definition specific concept. An automatism that returns a list if there are multiple and just one if not is something imho turned out to be one of the worst decisions in entity.module in 7.x, which is why, in 8.x, we made the decision that fields are *always* a list. We could make the same assumption as content entities and default to delta 0. But we can only do that when accessing a property below, as otherwise it's not possible to access the list. For entities, $node->langcode->value is the same as $node->langcode[0]->value. But $node->langcode must return the full thing.

* How do we know which field property we actually want to access? As I said above, node.langcode has two, value and the reference (language). In this case, we want the reference. But what would we want for e.g. an integer field type. Or a TextWithSummary that has a text, format and a summary. Or a field that has two references to other entities? The resolvers are asked to extract "the data" from possibly indefinitely complex typed data structures, without being told anything about what is actually desired.

I think if we make that relationship notation or how we want to call it just slightly more explicit and closer to entities/typed data, then we can actually implement it in a generic way. What I think would work is "node:langcode:language". As written above, then we can imply delta 0 and access this information in a generic, typed data compliant way:

$context->getContextData()->get('langcode')->first()->get('language')->getValue().

Attaching a first patch for this. Not very well tested, but PathautoUnitTest::testPatternLoadByEntity() that uses exactly this passes now. One thing it can't do yet is deal with a list of references. Not sure yet how to handle this, maybe node:some_field:*:node? i don't think that is needed very often?