Adds @queryAsync decorator

[sorvell]

Fixes #903 by adding an @asyncQuery decorator.

[kevinpschaaf]

Is this good/required?

It sort of confuses the question "why should a user use asyncQuery?"

1. Because you need a reference to a child element but it won't be there until after this element flushes?
2. Because you've changed state on the child element and for some reason don't want to interact with it until after it's flushed?

The latter should be rare; flushing a child should normally be unobservable except for measurement (and we know that's fraught due to nested/chained updates). It's sort of lumping two use cases together, and given the second one is problematic, just want to discuss whether the child await is defensible vs. just pushing the entire measurement case to user responsibility.

[justinfagnani]

This also causes another microtask wait for every use, regardless of whether the element is a LitElement. And it doesn't work for other asynchronously rendering components like Stencil.

[sorvell]

Yup, removing this part.

[justinfagnani]

I think this is potentially very useful if made a bit more flexible:

export function asyncQuery(selector: string, waitFor?: (el) => Promise<unknown>) {
  if (waitFor) { await waitFor(el); }
...

Then one could do:

@asyncQuery('#foo', (e) => e.updateComplete) foo;

Or the equivalent for Stencil...

[sorvell]

Added a comment about supporting this in the future.

[justinfagnani]

Why is this preferable over:

class {
  @query('#foo') foo;

  x() {
    await this.updateComplete;
    this.foo;
  }
}

ie, when would we tell someone to use one pattern over the other?

[sorvell]

Inside the element, this is arguably just slightly sugared. For a property that needs to be accessed external to the element, using @asyncQuery is much cleaner since the user doesn't have to know about updateComplete.

[justinfagnani]

Do we have use cases where an element wants to expose part of its internals like this?

[sorvell]

This is useful when a property that is a query can change with element state. It's preferable when the property is public so that the user does not have to know about the updateComplete promise.

[justinfagnani]

This also causes another microtask wait for every use, regardless of whether the element is a LitElement. And it doesn't work for other asynchronously rendering components like Stencil.

[justinfagnani]

I think the example should show the usage of this.first somewhere too.

[sorvell]

Done.

[justinfagnani]

LGTM

Only other thought is the name. I've gotten used to sync/async modifiers coming at the end of names. How's @queryAsync() sound?

[justinfagnani]

I think this is potentially very useful if made a bit more flexible:

export function asyncQuery(selector: string, waitFor?: (el) => Promise<unknown>) {
  if (waitFor) { await waitFor(el); }
...

Then one could do:

@asyncQuery('#foo', (e) => e.updateComplete) foo;

Or the equivalent for Stencil...