[docs] Switch from AttributeSerializer to AttributeConverter breaks TS type checking

[KeithHenry]

Description

In @polymer/lit-element 0.6.4 you could create your own attribute serialisers, like so:

import { AttributeSerializer } from '../{lib dir}/@polymer/lit-element/lib/updating-element';

export const DateType: AttributeSerializer<Date> = {
    fromAttribute: attr => parseDateString(attr),
    toAttribute: prop => formatDateString(prop)
}

In lit-element 2.0.0-rc.2 this breaks because we now have converter - the problem appears to be that is that AttributeConverter is not exported, so AttributeSerializer can't be replaced: https://github.com/Polymer/lit-element/blob/9fda823791048e33de3dafcd83b25adef1a5eb35/src/lib/updating-element.ts#L59-L60

This change is documented in #264

Steps to Reproduce

1. Take a @polymer/lit-element 0.6.4 TS project that uses AttributeSerializer
2. Upgrade to lit-element 2.0.0-rc.2
3. Replace references
4. Change @property({ type: MySerialiser }) to @property({ converter: MySerialiser })
5. Replace AttributeSerializer with AttributeConverter
6. Error:

TS2305 (TS) Module "...lit-element/lib/updating-element" has no exported member 'AttributeConverter'.

Expected Results

Either no error or patch notes explaining how to resolve the breaking change.

[dfreedm]

Hmm, it looks like the replacement for AttributeSerializer<Type> is ComplexAttributeConverter<Type, TypeHint>. I think this is just a docs issue.

[dfreedm]

A bit more context:

• AttributeSerializer was renamed to ComplexAttributeConverter with an optional, additional argument to fromAttribute and toAttribute for type hinting.
• AttributeType was renamed to AttributeConverter, and AttributeType was never exported. https://github.com/Polymer/lit-element/blob/v0.6.4/src/lib/updating-element.ts#L15-L33

AttributeConverter doesn't really need to be exported because it is just a union of ComplexAttributeConverter and (value: string, type?: TypeHint) => Type.

In your example, you should use

import { ComplexAttributeConverter } from '../{lib dir}/@polymer/lit-element/lib/updating-element';

export const DateType: ComplexAttributeConverter<Date, Date> = {
    fromAttribute: attr => parseDateString(attr),
    toAttribute: prop => formatDateString(prop)
}

[KeithHenry]

@azakus Cheers! That fixes it, I think we just need to document it.

[dfreedm]

Related to #453

[ghost]

There is a section in the guides on conversion between attributes and properties which covers using converter: /* your custom converter */ in property declarations.

ComplexAttributeConverter is in the API docs but not the guides. I don't think we ever referred to AttributeSerializer in the guides directly. Do we need to document ComplexAttributeConverter in the guides?

[arthurevans]

@azakus I'm not convinced that AttributeConverter doesn't need to be exported. Since that's the typing for converter, the API docs hit a dead end here--there's no way to follow the breadcrumbs from "converter" to "ComplexAttributeConverter":

https://lit-element.polymer-project.org/api/interfaces/lib_updating_element.propertydeclaration.html#converter

The other issues here are:

1. The change should have been flagged in the 2.0 release notes/change log. (Seems a little late to add a note at this point, but maybe I'm wrong.)
2. Maybe we need to update the discussion about converting attributes? This part is unclear to me.