Missing public API imports
Turbo87 opened this issue · comments
According to #11 the following list of documented public globals APIs in Ember have no corresponding new module import paths yet:
ContainerProxyMixin
Ember.FEATURES.isEnabled
Ember.MutableEnumerable
Ember.Namespace
Ember.NativeArray
Ember.Test
Ember.Test.QUnitAdapter
Ember.testing
Ember.VERSION
RouterService
Ember.Handlebars.Utils.escapeExpression
Ember.HTMLBars.template
Ember.Handlebars.compile
user hook:
Ember.onerror
Additionally the ember-cli-shims were exporting the following globals APIs which don't have corresponding new module import paths yet either:
Ember.destroy
Ember.SortableMixin
Ember.K is deprecated, don't think it should be included?
good point, I didn't check the deprecated flag on those 😞
Ember.Binding and Ember.bind are also deprecated I believe.
Ember.onerror is a user provideable hook (not something that Ember itself provides).
Ember.registerDeprecationHandler
Ember.registerWarnHandler
These are both wrong, they should be Ember.Debug.register*. The docs may need updating (since I know that is where you generated this list from).
I didn't think that we exposed the RouterService on the global at all actually. We make it available in the default app registry, but I don't think we actually set a Ember.RouterService (we'll have to confirm).
I've updated the list
I didn't think that we exposed the RouterService on the global at all actually. We make it available in the default app registry, but I don't think we actually set a Ember.RouterService (we'll have to confirm).
that's probably why it's not prefixed with Ember.
Is the intention of the RFC to expose all the public APIs as modules, regardless of their deprecation state, or those should not be included?
I think it would need to be a case by case basis on the deprecated items. For example, I don't think K makes much sense (and you have already written a codemod for it).
@rwjblue #12 (comment) up for review:
Added Ember.defineProperty to the list.
Proposals that try to follow the guidelines in the RFC.
| Before | After |
|---|---|
Ember.ApplicationInstance |
import ApplicationInstance from "@ember/application-instance" |
Ember.ApplicationInstance.BootOptions |
Is this public API? |
Ember.ComputedProperty |
import ComputedProperty from "@ember/object/computed" |
Ember.CoreObject |
import CoreObject from "@ember/object/core" |
Ember.Debug |
Not exported, it's just a namespace |
Ember.Debug.registerDeprecationHandler |
import { registerDeprecationHandler } from "@ember/debug" |
Ember.Debug.registerWarnHandler |
import { registerWarnHandler } from "@ember/debug" |
Ember.defineProperty |
No clue |
Ember.Engine |
import Engine from "@ember/engine" |
Ember.EngineInstance |
import Engine from "@ember/engine-instance" |
Ember.Error |
import Error from "@ember/error" |
Ember.FEATURES.isEnabled |
import { isEnabled } from "@ember/features"; |
Ember.getEngineParent |
import { getEngineParent } from "@ember/engine" |
Ember.getWithDefault |
import { getWithDefault } from "@ember/object" |
Ember.MutableEnumerable |
import MutableEnumerable from "@ember/mutable-enumerable |
Ember.Namespace |
import Namespace from "@ember/object/namespace" |
Ember.NativeArray |
Is there any reason for this to be public? Isn't this only used to extend the prototype of Array? |
Ember.ObjectProxy |
@import ObjectProxy from "@ember/object-proxy" |
Ember.Observable |
@import Observable from "@ember/object/observable" |
Ember.PromiseProxyMixin |
@import PromiseProxyMixin from "@ember/promise-proxy-mixin"; (meh) |
Ember.Test |
Not exported, just a namespace |
Ember.Test.Adapter |
@import TestAdapter from "@ember/test/adapter" |
Ember.Test.QUnitAdapter |
@import TestAdapter from "@ember/test/qunit-adapter" (Is this part of Ember? Shouldn't it be on an addon) |
Ember.testing |
Unsure |
Ember.VERSION |
import VERSION from "@ember/version" (this kind of breaks the rules of default exports being classes) |
RouterService |
Unsure |
Close seconds:
| Before | After |
|---|---|
Ember.ApplicationInstance |
import ApplicationInstance from "@ember/application/instance" |
Ember.EngineInstance |
import EngineInstance from "@ember/engine/instance" |
We discussed this issue at todays Ember core team meeting, and have generally agreed to your list above with the following (relatively small) modifications:
// some that you were unsure of
import { isTesting, setTesting } from '@ember/test'; // Ember.testing
import { defineProperty } from '@ember/object'; // Ember.defineProperty
// we preferred alternates for these:
import ApplicationInstance from "@ember/application/instance";
import EngineInstance from "@ember/engine/instance";
import PromiseProxyMixin from "@ember/object/promise-proxy-mixin";
import ObjectProxy from "@ember/object/proxy"
// we want to hold off on these for now (will review again next week):
Ember.VERSION
Ember.Test.QUnitAdapter // as of QUnit 2.0 this is completely provided by ember-qunitWould love a PR adding the missing things, then we can update the listing in the description...
instead of import MutableEnumerable from "@ember/mutable-enumerable" I would like to suggest import MutableEnumerable from "@ember/enumerable/mutable"
Updated table with suggested changes:
| Before | After |
|---|---|
Ember.ApplicationInstance |
import ApplicationInstance from "@ember/application/instance" |
Ember.ApplicationInstance.BootOptions |
Is this public API? |
Ember.ComputedProperty |
import ComputedProperty from "@ember/object/computed" |
Ember.CoreObject |
import CoreObject from "@ember/object/core" |
Ember.Debug |
Not exported, it's just a namespace |
Ember.Debug.registerDeprecationHandler |
import { registerDeprecationHandler } from "@ember/debug" |
Ember.Debug.registerWarnHandler |
import { registerWarnHandler } from "@ember/debug" |
Ember.defineProperty |
import { defineProperty } from "@ember/object" |
Ember.Engine |
import Engine from "@ember/engine" |
Ember.EngineInstance |
import Engine from "@ember/engine/instance" |
Ember.Error |
import Error from "@ember/error" |
Ember.FEATURES.isEnabled |
import { isEnabled } from "@ember/features"; |
Ember.getEngineParent |
import { getEngineParent } from "@ember/engine" |
Ember.getWithDefault |
import { getWithDefault } from "@ember/object" |
Ember.MutableEnumerable |
import MutableEnumerable from "@ember/mutable-enumerable |
Ember.Namespace |
import Namespace from "@ember/object/namespace" |
Ember.NativeArray |
Is there any reason for this to be public? Isn't this only used to extend the prototype of Array? |
Ember.ObjectProxy |
@import ObjectProxy from "@ember/object/proxy" |
Ember.Observable |
@import Observable from "@ember/object/observable" |
Ember.PromiseProxyMixin |
@import PromiseProxyMixin from "@ember/object/promise-proxy-mixin"; (meh) |
Ember.Test |
Not exported, just a namespace |
Ember.Test.Adapter |
@import TestAdapter from "@ember/test/adapter" |
Ember.Test.QUnitAdapter |
(Is this part of Ember? Shouldn't it be on an addon?) |
Ember.testing |
import { isTesting, setTesting } from "@ember/test" |
Ember.VERSION |
import VERSION from "@ember/version" (this kind of breaks the rules of default exports being classes) |
RouterService |
Unsure |
Now that some of these have been landed, we should update the list in the description...
@Turbo87 Can you edit the table and remove what was implemented? Heading off right now.
I found another missing API: Ember.Test.registerAsyncHelper
Missing API imports and they suggested import paths
| Before | After |
|---|---|
| Ember.Test.registerAsyncHelper | @import { registerAsyncHelper } from '@ember/test |
| Ember.Test.registerHelper | @import { registerHelper } from '@ember/test |
| Ember.Test.registerWaiter | @import { registerWaiter } from '@ember/test |
| Ember.Test.unregisterHelper | @import { unregisterHelper } from '@ember/test (what is the use case for this?) |
| Ember.Test.unregisterWaiter | @import { unregisterWaiter } from '@ember/test (what is the use case for this?) |
If there is agreement I could PR that tonight or tomorrow.
Ya, those look good @cibernox
What is the path forward with import { isTesting, setTesting } from '@ember/test';?
This doesn't seem like something that can be defined using just the json manifest.
I just noticed another one:
Ember.Handlebars.Utils.escapeExpression
one more interesting thing:
Ember.String.singularize
Ember.String.pluralize
These methods are apparently monkey-patched onto Ember.String by ember-inflector which is imported by ember-data
@Turbo87 I'm not sure ember should export that if it's not always there and depends on the inclusion of a library.
If it is dependent on ember-inspector, it sounds to me that it should be import { pluralize, singularize } from 'ember-inspector'.
Yes, confirm. We should add a deprecation in ember-inflector for that global...
For libraries that Ember re-exports, can we stop re-exporting them for modules? For example, replace:
Ember.Handlebars.Utils.escapeExpression("<div></div>");with
import Handlebars from "handlebars";
Handlebars.Utils.escapeExpression("<div></div>");It sucks that Handlebars doesn't have a real module API other than exporting an instance as the default export from index.js AFAICT.
Update: I missed that we already discussed this in #18. :)
I was editing the guides, and I don't see an export for Ember.libraries.register(libraryName, libraryVersion);.
These are also some exports here that are marked private in API docs:
RSVP.offEmber.AutoLocationEmber.HashLocationEmber.HistoryLocationEmber.NoneLocation
There are also:
Ember.computed.filterPropertyEmber.computed.mapProperty
which are missing from API docs.
Should we include Ember.Logger? I know @aklkv is having an issue with the codemod ember-codemods/ember-modules-codemod#28
Although I'm not entirely sure what the deprecation status of this is 🤔 @tomdale mentioned that the Ember.Logger is not required anymore because it was essentially a polyfill emberjs/rfcs#176 (comment)
I'm not sure how widespread this issue would be but I think we should have an upgrade path for anyone using Ember.Logger 👍
Ember.onerror is a user provideable hook (not something that Ember itself provides).
Doesn't there still need to be an equivalent way to provide a callback for that hook in a world without the Ember global?
@dfreeman - Good point. There definitely needs to be a way to set the default Ember.onerror in modules land....
Ember.NAME_KEY might not be public but is necessary to provide readable names to the Ember Inspector. Should we add that too?
We should fix the inspector. I don't grok why it would use NAME_KEY instead of toString...
@rwjblue I'm kind of in charge of fixing it already, so I could do this too, but I'll need some time from Teddy to guide me through the desert.
What's the current status on this issue?
Update the description with a few more of the template layer related ones.
Hmm, I landed on this issue after searching around for Ember.Logger. Given the comment & link above, am I correct in presuming the right course of action is to replace all instances with console.log for good? Just to make sure before I "jump ship", as it were.
The issue I have with removing or deprecating something like Ember.Logger is that there are some addons that rely on this being the main way to log to the console. The one that I have been using is: https://github.com/davewasmer/ember-cli-rollbar which piggy-backs on the Logger instance and ships any errors to the Rollbar service.
I'm happy with moving forward into the future where this is deprecated but I think we ought to reach out to the addon community if this is going to be the case 👍
Echoing what @locks mentioned earlier, I had a few instances of Ember.libraries.register in my app (to show a few 3rd party library versions in the inspector) that don't yet convert over -- they're the last holdouts of the Ember global for me (I just ousted Ember.Logger for simplicity).
A curiosity: there's a big fat "private" label in the one place in the Ember docs it's mentioned (here) -- I take it to mean the class is private but the singleton on the Ember global is not, but it isn't crystal clear just by looking.
I'm not clear about Ember.onerror as it is still in the table as deprecated.
@rwjblue: There definitely needs to be a way to set the default Ember.onerror in modules land
It's the last Ember global in my app.
Hello guys,
Can you please explain the benefits from using this new import syntax from "vendor" package size point of view? As I understand we import only those functions that needed for current app. Do I need to change ember-cli-build.js file somehow?
Thank you.
Hi @catz, I've answered you at https://discuss.emberjs.com/t/q-a-rfc-176-javascript-modules-api/13664/2?u=locks so as to keep this thread focused on discussing missing imports.
One import I didn't see was Ember.uuid which is currently marked as public
https://github.com/emberjs/ember.js/blob/v2.15.0/packages/ember-utils/lib/guid.js#L20-L22
We use this in 1 place in our app
We are using 2.16, where import { isTesting, setTesting } from '@ember/test' does not work. We still need to use Ember.testing. Any thoughts on this?
What is the path forward with import { isTesting, setTesting } from '@ember/test';?
This doesn't seem like something that can be defined using just the json manifest.
Looks like Ember.Copyable is missing as well.
@GCheung55 that is private API
@locks you’re right. My mistake.
no problem, thanks for keeping an eye out!
Was there ever a definitive answer for if we are going to include Logger, or if it's getting depreciated/removed?
@webark It seems that's going to be removed, Ember.Logger is no more than a polyfill as it was said at emberjs/rfcs#176
@Gorzas it’s a little more then just a polyfil. (not much more, but a little) That comment does mention that they will “revisit logging” in the future. At first read i read that as more of a suggestion then an answer, but upon reading it more it seems that it’s more of a conclusion. Thanks.
Nothing is happening to Ember.Logger until an RFC is filed and accepted.
Ember.testing replacement pl0x? 🙏
@elwayman02 I've been using the suggestion given by @rwjblue here: emberjs/ember-qunit#297 (comment).
Old:
if (Ember.testing) { ... }
New:
import config from '<projectname>/config/environment';
...
if (config.environment === 'test') { ... }
Updating the description for the following:
Ember.ApplicationInstance -> import ApplicationInstance from '@ember/application/instance';
Ember.ApplicationInstance.BootOptions -> Not a "real" class to instantiate
Ember.ComputedProperty -> import ComputedProperty from '@ember/object/computed';
Ember.CoreObject -> import CoreObject from '@ember/object/core';
Ember.Debug.registerDeprecationHandler -> import { registerDeprecationHandler } from '@ember/debug';
Ember.Debug.registerWarnHandler -> import { registerWarnHandler } from '@ember/debug';
Ember.defineProperty -> import { defineProperty } from '@ember/object';
Ember.Engine -> import Engine from '@ember/engine';
Ember.EngineInstance -> import EngineInstance from '@ember/engine/instance';
Ember.Error -> import EmberError from '@ember/error';
Ember.getEngineParent -> import { getEngineParent } from '@ember/engine';
Ember.getWithDefault -> import { getWithDefault } from '@ember/object';
Ember.ObjectProxy -> import ObjectProxy from '@ember/object/proxy';
Ember.Observable -> import Observable from '@ember/object/observable';
Ember.PromiseProxyMixin -> import PromiseProxyMixin from '@ember/object/promise-proxy-mixin';
Ember.Test.Adapter -> import TestAdapter from '@ember/test/adapter';
import TestAdapter from '@ember/test/adapter';
I also removed the following as they were removed in 3.0.0:
Ember.bind
Ember.binding
Ember.K
What about Ember.onerror?
After discussion with @tomdale we came up with a bunch of answers (though not completely):
Ember.HTMLBars.template -> import { wrapTemplate } from '@ember/template-compilation';
Ember.HTMLBars.compile -> import { compileTemplate } from '@ember/template-compilation';
Ember.HTMLBars.precompile -> import { precompileTemplate } from '@ember/template-compilation';
Ember.VERSION -> import { VERSION } from '@ember/version';
Ember.onerror -> import { getErrorHandler, setErrorHandler } from '@ember/runloop';
Ember.FEATURES / Ember.FEATURES.isEnabled -> import { FEATURES, isEnabled } from '@ember/canary-features'
Ember.Namespace -> import Namespace from '@ember/application/namespace';
@krisselden The rationale was that we wanted to make it clear that it was an internal helper used as part of codegenned templates, and not something app developers should use. It's not technically used "by" the template compiler, but it is required to evaluate the output the template compiler produces.
If you'd like to put it in a different package than @ember/template-compilation that's fine with me, but I was operating under the assumption that packages could contain both compile-time and run-time code and treeshaking would sort it out appropriately.
Are Ember-Data modules will be added or is this for Ember only?
@wanxie this is for ember.js only, Ember Data is a separate library and needs a separate RFC :)