Design Architecture of @dojo/shim

[kitsonk]

Discussion

We need to codify what we include in @dojo/shim and its overall design. We should include this in our README and other appropriate documentation.

My suggestion is that we have the following guidelines for this package:

• The package includes only functional fills that are part of the ECMAScript standard or a formal proposal for the standard.
  • All Stage 4 proposals which have a functional component that can be shimmed SHOULD be included.
  • Stage 3 proposals MAY be included on a case by case basis where it is believed that they:
    • Are likely to land without further significant breaking changes.
    • Are important features which we need to adopt.
• The package includes syntactical features which cannot be effectively transpiled with TypeScript (for example @dojo/shim/iterators/forOf for for ... of).
• If a feature cannot be fully shimmed, but some of the functionality is generally useful, it would be a good candidate for @dojo/core.
• Any functionality attempts detect native support and offload.
• Modules do not augment/shim built ins or pollute the global namespace.
  • The exception is for certain features which are needed in the global namespace to support transpilation by TypeScript (e.g. Promise and Symbol)
• Modules which are providing added functionality to an existing global classes prototype, should be included in a module that exports the functionality as a function from a module named in lower case (e.g. @dojo/shim/array.includes())

[dylans]

I would add to this that there is at least one shim that is not anywhere near stage 3 (Observables) that is pretty key to our efforts.

Also, streams itself is a shim for a WHATWG proposal.. while that is now in a separate package, I guess the bigger point is that we may find ourselves shimming things that are not part of the ES process but W3C or others, which don't have the same stage 0-4 process.

For example, there's the pointer events polyfill (which to be fair we're just importing wholesale), there's Globalize which currently does not but will likely eventually wrap EC402 (which it turns out does have the same staging process), and then there's the IntersectionObserver API which we're strongly considering using for dgrid.

So I'm not sure what the right answer is, other than we probably do not want to restrict ourselves to Stage 3 or 4.

Also, do we need to support all stage 4 proposals? What if they all have a working implementation, or what if it's a feature we probably won't use? Also, I'm not sure if it's even possible to shim shared memory and atomics, but assuming it was, would we really bother to shim it without knowing if we need to use it.

Longer term, we probably need a plan for deprecation of shims in future major releases. I assume we'll base it on browser versions and usage statistics, but at what point do we get rid of forOf, and does this have any impact when people upgrade and need to start using for...of?

[kitsonk]

PR #101 will provide a better overall architecture that should support downstream projects targeting ES6 and fairly efficient build optimization using dojo build.

[kitsonk]

PR #101 is a breaking change in quite a few ways (Promise being global, tighter typings on collections). We need to stage PRs across the rest of the packages to deal with this.

• Changes to align with shim refactors core#346
• Updates for @dojo/shim widget-core#610
• Update for @dojo/shim widgets#246
• Upgrading to use new @dojo/shim routing#97
• dojo/cli - no changes
• Upgrading to new dojo/shim cli-build-webpack#181
• dojo/cli-test-intern - doesn't use shim/core
• dojo/cli-create-app - doesn't use shim/core
• Updating to latest dojo/shim i18n#95
• Updating for use with latest shim changes dgrid#43
• Updating examples to work with new shim changes examples#230

[rorticus]

@kitsonk I believe these are all taken care of!

[kitsonk]

WOOT! 🎉 👐 (Jazz hands)