Please rename ASAP

[domenic]

Please do not publish polyfills that squat on proposed names, for features that are not already implemented interoperably in multiple browsers or in the standard. That prevents future evolution and causes massive renaming conflicts, as we've already seen with custom elements and shadow DOM where we had to rename all the v0 APIs due to existing polyfills. If this does not get fixed ASAP I will have to withdraw the proposal since these names are poisoned forever.

I'd suggest prefixing everything with a $ or _ instead, or just providing a library that doesn't attach itself to document.

[jdalton]

Hey @domenic!

Thanks for working on this API proposal. How is this polyfill different than folks polyfilling any other API? If the property exists, so implemented in the browser, it will use the built-in implementation, else it will polyfill. Seems like something es-shims, fetch-polyfill, and other polyfills do. Am I missing something?

(related to whatwg/html#127 (comment))

[domenic]

The difference is this API is not yet implemented and shipped in multiple browsers. It doesn't even have a stable spec yet.

[jdalton]

Ah nice! If the code paths defer to built-ins is there a harm?
(I mean polyfills and shims get updated all the time)

Would a disclaimer that it's super early/unstable help?

[domenic]

If the code paths defer to built-ins is there a harm? I mean polyfills and shims get updated all the time.

Yes, there is huge harm; that is the worst possible setup. Consider if I built a website that depending on document.loaded being the load event using this polyfill. Then we update the spec so that instead document.loaded is the DOMContentLoaded event. Then Chrome starts implementing. Boom! The website is now broken in Chrome, because it depends on the polyfill's semantics of the load event, but Chrome is trying to follow the spec and use DOMContentLoaded. Chrome can no longer ship this API with this name, and we have to remove the API from the standard and from Chrome.

A disclaimer would not help at all. If this is unstable, then don't polyfill it. Just release a library with interesting inspired-by-a-proposed-spec semantics.

[jdalton]

Yes, there is huge harm; that is the worst possible setup.

Giving it a different name kinda defeats the purpose of a shim. Can you explain the best possible setup? Is it just waiting for spec text to be put up?

[domenic]

The best possible setup is this:

• Use a name that will never be implemented in browsers, or a module. See if people like the semantics, without squatting on the name. That gives the standards process good feedback!
• Once we are sure the spec is stable (which does not mean merged; it means, implemented in 2+ browsers, unflagged, stable channel): then create a polyfill.

[domenic]

Giving it a different name kinda defeats the purpose of a shim.

The purpose of a shim should not be to allow people to use features before they are actually stabilized features. It should be to help polyfill features in browsers that do not support it yet, given an ecosystem of other browsers which do.

Regardless, I'd like to hear from the author, @jonathantneal. Can you commit to some kind of renaming here? On what timeline? Otherwise I need to withdraw the proposal.

[domenic]

This isn't a threat; this is just a hard-earned lesson on the web that governs the standards process. It already happened with web components v0, and I don't intend to waste any more time on a proposal that's going to suffer the same fate.

[WebReflection]

I don't think early polyfills are any different from stage-0 transpilers , I actually implemented in dom4 repository early append, pretend and others, that even if removed from specs at some point, recently landed in Chrome and Opera. I wonder if early adoption should be taken as community happiness and will to use the proposal ASAP, and yet another wrapper library non conform with any standard, these days, wouldn't be as welcome, fading developers offer trying to bring best ideas and proposal to the community without waiting every vendor and signaling loudly interest.

[jonathantneal]

I assigned myself to this issue fairly quickly, and I already have 2 solutions. Let me keep this quick (as the conversation is already moving quickly):

1. Turn this into a ponyfill object containing the interactive, contentLoaded, and loaded promises already hard-wired to the document.
2. Turn this into a similar descriptor ponyfill, not specifically hard-wired to any node (Maybe it generates the promise on the getter which is then assigned to the value).

[domenic]

@jonathantneal although I don't quite understand the ponyfill notation, both of those sound great. Thank you so much for being willing to work with this.

[jonathantneal]

The descriptor ponyfill would look something like this. Would you let me know if this explains it better and/or reaches your goal?

let interactiveDescriptor = {
    configurable: true,
    enumerable: false,
    writable: true,
    get: function () {
        let promise = promisifyInteractive(this);

        Object.defineProperty(this, 'interactive', {
            configurable: true,
            enumerable: false,
            writable: true,
            value: promise
        });

        return promise;
    }
};

Polyfill Usage

Object.defineProperty(document, 'interactive', interactiveDescriptor);

[WebReflection]

It already happened with web components v0

Since both me and Polymer team worked on polyfills for V0, you might have realized that both me and Polymer team migrated almost effortless to V1 and I don't remember anyone complaining, beside the builtins extend, something every-single-developer interested in Custom Elements wanted and used as much as they could.

Despite the story behind WebComponents, since I've brought already various other recent standards to the DOM4 repository, would you mind telling me when exactly would be appropriate to implement these new features I've also already tried to patch in the past?

I don't want this to be redrawn but I'd like to know it's been agreed across vendors.

Is there a specific channel of agreed proposal, something similar to ES stage, when it comes to WHATWG?

Thank You

[WebReflection]

@jonathantneal I don't think lazy property assignment is a solution because "loaded" in document will still return true from a feature detection perspective _{(you actually re-demonstrated in operator, which doesn't trigger getters, is still the best way to feature detect, unfortunately it fails its intent in here, but it's still less obtrusive)}.

[domenic]

@jonathantneal that's interesting; I guess it seems reasonable, assuming you just provide the descriptor and don't install it for people. Although I'd be wary about people accidentally installing it on document, so option 1 seems a bit nicer to me.

@WebReflection

I don't remember anyone complaining

The issue is that we had to rename all the methods in custom elements and shadow DOM due to the polyfills squatting on them before the semantics were finalized. The semantics are only now being finalized with v1, and we had to invent all new names to do so since polyfills were squatting on the old names with not-yet-finalized semantics.

would you mind telling me when exactly would be appropriate to implement these new features

It is appropriate to implement them as soon as possible; it's great to get developer feedback. But it's only appropriate to squat on final names when it is shipping in two browsers (stable, unflagged).

The only advantage of using the final names is if you're certain they will match the final semantics. But until things are shipping in two browsers, you can't be certain of that, so it's just misleading to consumers and harmful to standards development.

Is there a specific channel of agreed proposal, something similar to ES stage, when it comes to WHATWG?

We consider things stable when they are shipping in two browsers (stable, unflagged). Before then they can and often do change.

[WebReflection]

I don't think early polyfills adopters are too concerned about changes and in this very specific case I don't see anything that could change so drastically beside a name.

I mean, promises are promises, here listeners have no space (necro-listeners like the one I've created aren't a thing yet and I don't think you want to define them for this proposal).

I'll wait Canary + some other browser to agree on this, but I don't think this is how an Open Source channel should move forward: people adopting APIs are people needing to consume them. If this happens is usually because they are happy.

Best Regards

[WebReflection]

Last from me on this topic: there are best evangelists in this world creating hype, excited as much as developers.

Early polyfills will be a tough battle if every time something hyped gets burned due early adoption.

There should be some synchronization or agreement here.

[domenic]

There should be some synchronization or agreement here.

Totally agreed. That's what we're accomplishing in this thread!

[WebReflection]

As specs customer, reading "landing in the spec, +1 from Firefox & Chrome." gives me confidence that those two browsers mentioned in here already agreed, hence green light for polyfills.

I understand the pain of a specs author, yet as API consumer I'm not too fund of the situation as described in here.

I hope this thread will help. (done done, unless questioned)

[mislav]

When @domenic says that it's dangerous to start polyfilling standards that haven't been finalized yet, I believe him. If it only takes a small change that avoids exporing this interface directly to document, I support that.

At GitHub.com, we've used this promise for a while:

export const ready = (function() {
  if (document.readyState === 'interactive' || document.readyState === 'complete') {
    return Promise.resolve()
  } else {
    return new Promise(resolve => {
      document.addEventListener('DOMContentLoaded', resolve)
    })
  }
})()

So instead of simply accessing document.whatever, we first have to import this module in order to access the promise. But we'd rather continue doing this, or use a 3rd party library that provides this interface if we didn't write it ourselves, than having something on document that is not standard, even if the latter API is more convenient.

[WebReflection]

(implicitly questioned ...)
sorry @mislav but your example inevitably uses a transpiler (ES6 modules) which usually adopt early standards too, not really the best example of your:

than having something that is not standard

Like I've said I've done this before without using any non yet standard feature, widely compatible, and completely transparent for whatever library/code/developer:

document.addEventListener('DOMContentLoaded', function (e) {
  console.log('that is it');
});

The point in here is indeed to define standard because something in WHATWG and agreed by two vendors sounds as usable as your ES6 module in your example.

Last, since you shared your code, here is how I'd write your module:

export new Promise(resolve =>
  /^interactive|complete$/.test(document.readyState) ?
    resolve() :
    document.addEventListener('DOMContentLoaded', resolve)
)

[mislav]

The point in here is indeed to define standard

That's a valid point. I think in this case I would define "a standard" something that the person or people who were involved in defining it gave their 👍 to vendors and other implementors. And for this project it's pretty simple to find out what the person who made the proposal thinks right now.

[AlicanC]

As specs customer, reading "landing in the spec, +1 from Firefox & Chrome." gives me confidence that those two browsers mentioned in here already agreed, hence green light for polyfills.

Green light for a spec, not polyfills. What you get confidence from is basically a Firefox and a Chrome developer saying "Yeah, sure." under a PR. Why does that give you confidence? There is no guarantee at this time that the spec won't change. Intent to implement does not guarantee that.

I don't think early polyfills are any different from stage-0 transpilers

They are. A project with await* kept running when the syntax got sacked from the spec, but a project with this polyfill will break if this API lands with a different spec. You can't risk having incompatible or broken implementations. That's the whole point of specs.

---

Some polyfills make polyfilling opt-in. I think this should be standard for all polyfills:

// Without polyfilling
import documentPromises from 'document-promises';

documentPromises.interactive.then(/* ... */);

import { interactive } from 'document-promises';

interactive.then(/* ... */);

// With polyfilling
import documentPromises from 'document-promises';
documentPromises.polyfill();

document.interactive.then(/* ... */);

// Alternative
import 'document-promises/polyfill';

document.interactive.then(/* ... */);

At this time, polyfilling should throw or at least warn.

[philipwalton]

I think its important to not forget the primary purpose of polyfills: to normalize runtime behavior between browsers that ship a feature and browsers that don't (usually to avoid runtime errors).

In the case of a spec that hasn't shipped in any browser, there's nothing to normalize. Until there is, I think it makes the most sense to stick to a local module with the same behavior.

[WebReflection]

polyfills as module are the exact same as polyfills as global.

You import something you believe it's going to be eventually natively implemented.

If you import something just because it solves your problem, and you know such something because you believe standards are going to solve such problem so that's the direction you want to follow (standards), you'd be disappointed knowing such library never became a standard.

So you have two options here:

1. you believe in standards and to help them you early adopt them because you are happy and you want to tell the developer behind the polyfill (and even more specs proposals) you appreciate her/his job
2. you use a ready-to-go 3rd parts library/framework ... which IMO are winning against slowly implemented standards (react, ember, you name it these days) .

Pick your poison, I guess, is the rule here: I've always chosen standards and I've written tons of polyfills since ever. It paid back so far (16+ years), every library around faded out in the meanwhile.

Hence my concerns. I'm not sure anymore if I should even listen to this channel, if it's so fragile.

[StephanBijzitter]

Interesting.

However, is this not simply a problem of trying to please too many people? If Twitter decides to polyfill a proposal, and when the proposal is finally included in a browser and Twitter breaks: so be it.

I do agree with the above comment: polyfills should normalize behaviour, but there's only a few major companies creating browsers, while there's hunderds of thousands website developers. Companies like Google, Mozilla, Microsoft and the like should just not care about compatibility with polyfills in this case.

At least that's my two cents.

[domenic]

If Twitter decides to polyfill a proposal, and when the proposal is finally included in a browser and Twitter breaks: so be it.

That's unfortunately not realistic. No browser can afford to break Twitter. That would cause people to stop using that browser, in favor of a competitor. Instead, the browser will just not ship the feature.

[WebReflection]

I'm not sure why Twitter was mentioned but big companies, as well as small one, have developers capable of deciding if a polyfill is good enough or not.

If it's reasonable, and it would be eventually easy to follow its changes (like it happened for every big FW/library out there ultimetely), it's a way safer bet on the long term than any other 3rd parts library.

Please do not convince me otherwise, it'd be way too much disappointing. Thank you.

[jonathantneal]

The ponyfill re-implementation may be reviewed at #6.

@domenic, would this documentation satisfy your concerns? Your advise is why this change is being made.

@mislav, would this implementation satisfy your expectations? Your advisement on previous polyfills has been my gold standard.

Those individuals positive review will be my 👍 to push 2.0.0, and all others are very welcome to chime in. Thanks!

[domenic]

@jonathantneal thanks so much for the work here. I'd suggest omitting

Developers may also polyfill the proposal at their own risk.

Maybe even replacing it with "developers are strongly advised not to assign these promises to the document object, as the standard could still change substantially and such code could be future-incompatible."

[triblondon]

I have put polyfills on the agenda for a Technical Architecture Group call this week. There's a tipping point at which creating polyfills moves from frustrating standardisation efforts to speeding up their adoption. Speeding up adoption is critical to keeping the web moving forward, so polyfills are to be encouraged, but it seems there is no common agreement on what signifies that tipping point.

Second, I'm wondering if a spec should have a polyfill, if one is technically feasible, as a condition of moving to something like CR status. This would dampen the enthusiasm from third parties to create polyfills prematurely, while boosting the quality and availability of polyfills when they offer most value (assuming you think CR status is the tipping point - I'm not saying it is)

I'm interested in this as a TAG member and also as maintainer of polyfill.io.

[jonathantneal]

Interest and evangelism prompt specifications and fills, but not necessarily in that order. Interest comes from the perceived gain of the feature, which is sometimes encouraged by evangelism, which sometimes takes the form of a fill.

For example, two years ago, Element.prototype.closest was a nottifill. It advocated for a specification, generated a lot of interest, and soon it became a prollyfill and then a polyfill. Another success story is cssnext, which, while safely guarded behind precompilation, prollyfills many of Tab Atkins Jr’s proposals, that is if his proposals qualify them for prollyfill status. Or read Lea Verou’s journal / instructions on how to motivate implementations.

Now, I’m presently of the mind that prollyfills and nottifills should be packaged as ponyfills, that way any polyfilling is explicit to the project and the developers assume the onus.

By the way, what I mean when I say:

• Polyfill: functionality current systems implement natively.
• Prollyfill: functionality future systems expect to implement natively, as defined by widely accepted specifications.
• Nottifill: functionality future systems may implement natively, as desired by developers.
• Ponyfill: a strategy where functionality is implemented as an independent module.

[jonathantneal]

The ponyfill changes have been merged and published. Closing!

[sindresorhus]

Ponyfill: a strategy where functionality is implemented as an independent module.

For reference: https://ponyfill.com

[yoavweiss]

Another data point supporting @domenic's stance here is scottjehl/picturefill#478 and the fact that this issue in the wild caused the currentSrc part of srcset to be delayed until the feature was fully supported in both Edge and Safari, despite the fact that it got fixed in under 24 hours.

Once your polyfill gets out there, it's impossibly difficult to get people to upgrade it, even in the face of future-breaking issues. We reached out to large sites that hosted an older version of picturefill and asked them to upgrade or support will be taken out from Edge. That didn't help. A few months later, Safari encountered the same issues with those same sites.

Maybe evergreen polyfills (like what polyfill.io is trying to create) can help on that front, since they can upgrade all their users.

[jakearchibald]

@domenic can you talk a little more about the failure cases here?

I thought the web component issues were down to Chrome shipping too early. In that case names had to change. If names didn't change, a single site would have no control over over which behaviour users would get, because it'd be the browser deciding.

Is the big problem with this polyfill that it defers to the browser's implementation if it exists, and that remains to be defined? What if the polyfill always overwrote document.interactive, would that be somewhat better?

I guess the rule is don't mess with objects you don't own, unless:

• You're polyfilling a feature with wide adoption
• The polyfill is accurate to the native implementation

[yoavweiss]

@jakearchibald - Even if those two conditions apply, polyfill bugs can significantly delay browser adoption, as seen in the picturefill case. Unless you have a distribution channel, polyfilling on the native namespace is a dangerous gamble.

[jkarttunen]

So essentially we need vendor prefixes?

[marcoscaceres]

So essentially we need vendor prefixes?

"user-land" prefixes, but yes - pretty much. Specially for when things are unstable.

[jakearchibald]

I wouldn't call https://github.com/jonathantneal/document-promises#usage a prefix, it's just a library.

[marcoscaceres]

Sure, was more commenting on people wanting to directly prollyfill stuff and the risk of reducing clashes with browser-implemented objects. I still get worried when I see "document.loaded". Anyway, don't want us to go around in circles as the main points have been made (and good things happened as a result 👍 ).

[stuartpb]

What about shipping the polyfill (which can/could/should be compartmentalized and hidden behind a shimming function, es-shim-api style) wrapped in an if (Date.now() > expirationDate) { console.error('This polyfill is expired; please go to github.com/whatever and update to the newest version') } else { condition, akin to how native features are being experimented with now in Chrome as time-limited Origin Trials?

Of course, there's nothing stopping the end author from simply removing this expiration check, but there's nothing stopping them from converting a ponyfill to a prollyfill, either - it's all about just building controlled obsolescence into the path of least resistance (and adequately admonishing them, in a strongly-worded inline comment, against the potential consequences of dismantling such constraints to the web as a whole).

[mikesherov]

Seems as if TC39 and JS landed in a pretty good place with defined stages for the evolution of features in JS.

Perhaps the web itself needs a "stage" process where polyfills are discouraged until stage 3, and that ponyfills are encouraged before then. It can even be as simple as prepending pony fills with $ or _ as already suggested.

This allows standards to evolve and signal to users the point in time where polyfills make sense without fear that the name will be squatted while simultaneously allowing for end user experimentation and feedback.

[marcoscaceres]

We should probably be having this discussion in https://github.com/extensibleweb/

[WebReflection]

On Web ponyfills and library make no sense.

Take Element.prototype.append for example, there's no way you can use a module when you might have innerHTML injecting nodes, expecting genericEl.append to work as expected.

What are you suggesting here, to use append(el, ...args) instead? And who pays for refactoring every single invoke once the standard can be simply used?

I think most of you are missing the reason polyfills moved the Web forward in the first place.

We'd be still stuck using IE8 compatible JavaScript, methods, and functionalities, if it wasn't for polyfills taking care of it and it's unpractical to wait 'till two browsers already released a new feature that, once again, if early adopted means these are appreciated.

Early polyfills might have that warning/notice, and they probably should; saying that libraries can substitute them is a bit of a non-sense.

At this point, if library has to be, developers already demonstrated they are better off with 3rd parts that are not aligned with the Web Platform.

use the Web Platform

IIRC this was the slogan at last Polymer summit, everything I read in here is more like "don't trust anything unless already late to the party to use it" which for a company that claims to live in perpetual beta (it's a beta or it's deprecated, isn't it?) seems to be a very controversial advice.

[jakearchibald]

@WebReflection

Take Element.prototype.append for example, there's no way you can use a module when you might have innerHTML injecting nodes, expecting genericEl.append to work as expected.

https://github.com/tc39/proposal-bind-operator would help here.

import {append} from 'dom-ponyfill';

document.querySelector(whatever)::append(something);

[WebReflection]

yeah, that's a proposal not approved/final yet, so to have it in, you need to include a transpiler that targets stage 0 or stage 1 which is as risky, if not more, than having a polyfill.

Basically the exact same issue:

• if the bind operator changes, you have problems
• if the polyfilled API changes, you have same problems.
• once the API is officially in, you eventually need to both get rid of the module and refactor your code (with polyfills on browser-land you remove the external link after a while and you are done)

Nobody wins using transpilers on top, while polyfill for the last 16 years worked like a charms.

That being said, I can't wait for that syntax to land in JS. It is indeed an alternative, unobtrusive, way to polyfill too, but it wouldn't practically solve any problem discussed in here.

edit: or better, it would solve one problem, name clashing, but not the early adoption one. Name clashing is something proposals not final yet should, IMO, don't care much.

[domenic]

Is the big problem with this polyfill that it defers to the browser's implementation if it exists, and that remains to be defined? What if the polyfill always overwrote document.interactive, would that be somewhat better?

Yes, that is somewhat better, but as noted, it still has failure cases. It's also pretty silly---at that point you're just monkeypatching objects you don't own. Better to use the library approach.

What about shipping the polyfill (which can/could/should be compartmentalized and hidden behind a shimming function, es-shim-api style) wrapped in an

This is an interesting idea, but of course it does prevent browsers from shipping and standards from progressing until the expiration date set by the library author. I don't think we want to add more friction to the process of getting features shipped on the web.

Perhaps the web itself needs a "stage" process where polyfills are discouraged until stage 3, and that ponyfills are encouraged before then. It can even be as simple as prepending pony fills with $ or _ as already suggested.

We already do; that's what I tried to communicate above. When things are shipped in 2 browsers (stage 4, not stage 3), they're considered stable.

[kohver]

Browsers could just warn some time when property is reserved and somebody tries to define it.

[developit]

FWIW, I keep seeing people compare browser feature support to transpilers - transpilers are different because you control their version. I cannot control the versions of the myriad of browsers stuff runs on, but I can control which version of Babel or a given plugin I transpile my code with. That is a fairly significant difference.

@kohver The warning would be shown after the browser's implementation had already been shipped, which means it would be too late. The property isn't currently reserved because it doesn't currently exist (if I'm following along correctly).

Base argument here is for/against abstraction VS normalization. There are more and better arguments in favor of abstraction when the underlying (polyfill/browser/varies) implementation is not yet finalized. The risk with abstraction is ending up with a group of people who don't understand the platform itself, but rather only know a set of abstractions on top of it, however we've already seen how that plays out (jQuery) and it could be worse.

[WebReflection]

I keep seeing people compare browser feature support to transpilers

it's about using early standards and base some code on it for what you do daily.

Like I've said, same as people willing to update code around stage-0 (otherwise they are stuck forever if it changes) are those willing to early adopt new Web standards.

We've seen this already with WebComponents, a problem for specs author, precisely what the community wanted and used in the last 2 years.

3rd parts libraries are moving fast and winning these days, and people putting effort into polyfills shouldn't be turned down by their happiness for one proposal or another.

Anyway, I've waited long time and been asked to bring Custom Elements V1 which is not 100% final yet and two major browsers already shipped it.

I didn't bother before because V0 was indeed a failure in the long term, but I'm maintaining both versions now and there are abstractions based on my polyfill.

That polyfill is impossible to use otherwise (prolly, pony, whateverfill) and since I've written and maintaining many others, I want this to be as clear as possible and act accordingly.