From 24ade71db532e27747b556d36ec7e95428f1bc91 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 22 Jan 2024 14:54:28 -0500 Subject: [PATCH 01/44] Wip --- text/deprecation-import-ember-from-ember.md | 91 +++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 text/deprecation-import-ember-from-ember.md diff --git a/text/deprecation-import-ember-from-ember.md b/text/deprecation-import-ember-from-ember.md new file mode 100644 index 0000000000..ab8fa0b0e6 --- /dev/null +++ b/text/deprecation-import-ember-from-ember.md @@ -0,0 +1,91 @@ +--- +stage: accepted +start-date: +release-date: +release-versions: +teams: # delete teams that aren't relevant + - cli + - data + - framework + - learning + - steering + - typescript +prs: + accepted: # update this to the PR that you propose your RFC in +project-link: +--- + + + +<-- Replace "RFC title" with the title of your RFC --> +# Deprecate `import Ember from 'ember'; + +## Summary + +> One paragraph explanation of the deprecation. + +## Motivation + +> Why are we doing this? What are the problems with the deprecated feature? +What is the replacement functionality? + +## Transition Path + +> This is the bulk of the RFC. Explain the use-cases that deprecated functionality +covers, and for each use-case, describe the transition path. +Describe it in enough detail for someone who uses the deprecated functionality +to understand, for someone to write the deprecation guide, and for someone +familiar with the implementation to implement. + +> It can be helpful to write the deprecation guide as part of this section. Published deprecation +> guides can be found at https://deprecations.emberjs.com/. + +> Please keep in mind any implications within the Ember ecosystem, such as: +> - Lint rules (ember-template-lint, eslint-plugin-ember) that should be added, modified or removed +> - Features that are replaced or made obsolete by this feature and should eventually be deprecated +> - Ember Inspector and debuggability +> - Server-side Rendering +> - Ember Engines +> - The Addon Ecosystem +> - IDE Support +> - Blueprints that should be added or modified + +## How We Teach This + +> Would the acceptance of this proposal mean the Ember guides must be +re-organized or altered? Does it change how Ember is taught to new users +at any level? +Does it mean we need to put effort into highlighting the replacement +functionality more? What should we do about documentation, in the guides +related to this feature? +How should this deprecation be introduced and explained to existing Ember +users? + +> Keep in mind the variety of learning materials: API docs, guides, blog posts, tutorials, etc. + +## Drawbacks + +> Why should we *not* do this? Please consider the impact on teaching Ember, +on the integration of this feature with other existing and planned features, +on the impact of the API churn on existing apps, etc. +There are tradeoffs to choosing any path, please attempt to identify them here. + +## Alternatives + +> What other designs have been considered? What is the impact of not doing this? + +## Unresolved questions + +> Optional, but suggested for first drafts. What parts of the design are still +TBD? From 1291551a72426afdb2f98b58ae5f32128ebf5538 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 22 Jan 2024 14:59:11 -0500 Subject: [PATCH 02/44] Rename file --- ...m-ember.md => 1003-deprecation-import-ember-from-ember.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename text/{deprecation-import-ember-from-ember.md => 1003-deprecation-import-ember-from-ember.md} (96%) diff --git a/text/deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md similarity index 96% rename from text/deprecation-import-ember-from-ember.md rename to text/1003-deprecation-import-ember-from-ember.md index ab8fa0b0e6..925a1b404b 100644 --- a/text/deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -1,6 +1,6 @@ --- stage: accepted -start-date: +start-date: 2024-01-22T00:00:00.000Z release-date: release-versions: teams: # delete teams that aren't relevant @@ -11,7 +11,7 @@ teams: # delete teams that aren't relevant - steering - typescript prs: - accepted: # update this to the PR that you propose your RFC in + accepted: https://github.com/emberjs/rfcs/pull/1003 project-link: --- From 28186a26400b0697be1f13bfc9011a7a7c4e1d8b Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:03:38 -0500 Subject: [PATCH 03/44] Ember.testing --- ...003-deprecation-import-ember-from-ember.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 925a1b404b..1e25aba43c 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -42,6 +42,57 @@ What is the replacement functionality? ## Transition Path + +### `Ember.testing` + +Instead, use + +```js +import { macroCondition, isTesting } from '@embroider/macros'; + +// ... + +if (macroCondition(isTesting()) { + // test only code here +} +``` + +ENV/EmberENV ... equivalent shape thing from config/environment + +Ember.lookup (what is this?) + +Ember.onError (needs replacement) + +Ember.BOOTED (what is this?) + +Ember.TEMPLATES (must die) + +Ember.onload (has replacement) ... what is runloadHooks? + +Ember.HTMLBars / Ember.Handlebars (must go) + +Ember.Test/Ember.setupForTesting (should be replaced by @ember/test-helpers??) + +Container + +Registry + +_setComponentManager (has replacement on @ember/component) + +_modifierManagerCapabilities (has replacement on @ember/modifier) + +_componentManagerCapabilities + +meta (tagged private but exported on 'ember') + +RSVP + +libraries (may need public replacement) + +ActionHandler (no public API) + +Comparable (used by import compare from @ember/utils) + > This is the bulk of the RFC. Explain the use-cases that deprecated functionality covers, and for each use-case, describe the transition path. Describe it in enough detail for someone who uses the deprecated functionality From 5ed046acf335d61a098ad815044a6a3d9e6b4ff5 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:09:12 -0500 Subject: [PATCH 04/44] Some info --- ...003-deprecation-import-ember-from-ember.md | 55 ++++++++----------- 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 1e25aba43c..ea645b852a 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -61,56 +61,47 @@ ENV/EmberENV ... equivalent shape thing from config/environment Ember.lookup (what is this?) -Ember.onError (needs replacement) +### `Ember.onError` -Ember.BOOTED (what is this?) +```js +window.addEventListener('error', /* ... event handler ... */); +``` + +### `Ember.BOOTED` -Ember.TEMPLATES (must die) +No replacement. Unused. -Ember.onload (has replacement) ... what is runloadHooks? +### `Ember.TEMPLATES` -Ember.HTMLBars / Ember.Handlebars (must go) +This is the template registry. It does not need to be public API. -Ember.Test/Ember.setupForTesting (should be replaced by @ember/test-helpers??) +No replacement. -Container +### Ember.onload (has replacement) ... what is runloadHooks? -Registry +### Ember.HTMLBars / Ember.Handlebars (must go) -_setComponentManager (has replacement on @ember/component) +### Ember.Test/Ember.setupForTesting (should be replaced by @ember/test-helpers??) -_modifierManagerCapabilities (has replacement on @ember/modifier) +### Container -_componentManagerCapabilities +### Registry -meta (tagged private but exported on 'ember') +### _setComponentManager (has replacement on @ember/component) -RSVP +### _modifierManagerCapabilities (has replacement on @ember/modifier) -libraries (may need public replacement) +### _componentManagerCapabilities -ActionHandler (no public API) +### meta (tagged private but exported on 'ember') -Comparable (used by import compare from @ember/utils) +### RSVP -> This is the bulk of the RFC. Explain the use-cases that deprecated functionality -covers, and for each use-case, describe the transition path. -Describe it in enough detail for someone who uses the deprecated functionality -to understand, for someone to write the deprecation guide, and for someone -familiar with the implementation to implement. +### libraries (may need public replacement) -> It can be helpful to write the deprecation guide as part of this section. Published deprecation -> guides can be found at https://deprecations.emberjs.com/. +### ActionHandler (no public API) -> Please keep in mind any implications within the Ember ecosystem, such as: -> - Lint rules (ember-template-lint, eslint-plugin-ember) that should be added, modified or removed -> - Features that are replaced or made obsolete by this feature and should eventually be deprecated -> - Ember Inspector and debuggability -> - Server-side Rendering -> - Ember Engines -> - The Addon Ecosystem -> - IDE Support -> - Blueprints that should be added or modified +### Comparable (used by import compare from @ember/utils) ## How We Teach This From b891675ade6fc3bc1c72a274ebf318d385198769 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:23:15 -0500 Subject: [PATCH 05/44] Add summary --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index ea645b852a..df859d681e 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -33,7 +33,7 @@ project-link: Leave as is ## Summary -> One paragraph explanation of the deprecation. +This RFC proprosing deprecating all APIs that have module-based replacements, as described in [RFC #176](https://rfcs.emberjs.com/id/0176-javascript-module-api) as well as other `Ember.*` apis that are no longer needed. ## Motivation From c74969a6c357a9b71b8942f530b2d8bf1de4e91b Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 22 Jan 2024 15:26:26 -0500 Subject: [PATCH 06/44] Add link to old codemod --- text/1003-deprecation-import-ember-from-ember.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index df859d681e..73cac2d050 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -116,6 +116,10 @@ users? > Keep in mind the variety of learning materials: API docs, guides, blog posts, tutorials, etc. +Available Codemods + +- https://github.com/ember-codemods/ember-modules-codemod (from the work of RFC 176) + ## Drawbacks > Why should we *not* do this? Please consider the impact on teaching Ember, From aaf87c88db3064e250de3c9608b73f49980c5201 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 22 Jan 2024 17:36:28 -0500 Subject: [PATCH 07/44] Update --- text/1003-deprecation-import-ember-from-ember.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 73cac2d050..216d2a1ee7 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -81,6 +81,10 @@ No replacement. ### Ember.HTMLBars / Ember.Handlebars (must go) +#### `Ember.Handlebars.Utils.escapeExpression` + +Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. + ### Ember.Test/Ember.setupForTesting (should be replaced by @ember/test-helpers??) ### Container From 36fbc52b6f68a8186a49205218fcc0a72ae0dc66 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Sat, 3 Feb 2024 12:12:01 -0500 Subject: [PATCH 08/44] updates --- ...1003-deprecation-import-ember-from-ember.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 216d2a1ee7..c6e5f3a99a 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -42,6 +42,19 @@ What is the replacement functionality? ## Transition Path +### `Ember.isNamespace` + +No replacement, not needed. + +### `Ember.toString` + +No replacement, not needed. +e +### `Ember.Container` + +Both value and type are not needed. + +### `Ember.Registry` ### `Ember.testing` @@ -133,7 +146,10 @@ There are tradeoffs to choosing any path, please attempt to identify them here. ## Alternatives -> What other designs have been considered? What is the impact of not doing this? +As a migration path for folks, we could add a package.json#exports entry to [`ember`](https://www.npmjs.com/package/ember) +that re-exports the still-available APIs. + +Some APIs we don't want or need to keep at all though. ## Unresolved questions From 8175bf434109d835bd1a5b7de39133125dcfc4e4 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 6 Feb 2024 22:15:45 -0800 Subject: [PATCH 09/44] align with the exports --- ...003-deprecation-import-ember-from-ember.md | 206 +++++++++++++++--- 1 file changed, 179 insertions(+), 27 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index c6e5f3a99a..5d868f61ed 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -70,55 +70,207 @@ if (macroCondition(isTesting()) { } ``` -ENV/EmberENV ... equivalent shape thing from config/environment - -Ember.lookup (what is this?) - -### `Ember.onError` +### `Ember._setComponentManager` +Use ```js -window.addEventListener('error', /* ... event handler ... */); +import { setComponentManager } from '@ember/component'; ``` -### `Ember.BOOTED` - -No replacement. Unused. +### `Ember._componentManagerCapabilities` -### `Ember.TEMPLATES` +Use +```js +import { capabilities } from '@ember/component'; +``` -This is the template registry. It does not need to be public API. +### `Ember._modifierManagerCapabilities` -No replacement. +Use +```js +import { capabilities } from '@ember/modifier'; +``` -### Ember.onload (has replacement) ... what is runloadHooks? +### `Ember.meta` + +No replacement, not public API + +### `Ember._createCache` + +### `Ember._cacheGetValue` +### `Ember._cacheIsConst` +### `Ember._descriptor` +### `Ember._getPath` +### `Ember._setClassicDecorator` +### `Ember._tracked` +### `Ember.beginPropertyChanges` +### `Ember.changeProperties` +### `Ember.endPropertyChanges` +### `Ember.hasListeners` +### `Ember.libraries` +### `Ember._ContainerProxyMixin` +### `Ember._ProxyMixin` +### `Ember._RegistryProxyMixin` +### `Ember.ActionHandler` +### `Ember.Comparable` +### `Ember.RSVP` +### `Ember._Cache` +### `Ember.GUID_KEY` +### `Ember.canInvoke` +### `Ember.generateGuid` +### `Ember.guidFor` +### `Ember.uuid` +### `Ember.wrap` +### `Ember.getOwner` +### `Ember.onLoad` +### `Ember.runLoadHooks` +### `Ember.setOwner` +### `Ember.Application` +### `Ember.ApplicationInstance` +### `Ember.Namespace` +### `Ember.A` +### `Ember.Array` +### `Ember.NativeArray` +### `Ember.isArray` +### `Ember.makeArray` +### `Ember.MutableArray` +### `Ember.ArrayProxy` +### `Ember.FEATURES` +### `Ember._Input` +### `Ember.Component` +### `Ember.Helper` +### `Ember.Controller` +### `Ember.ControllerMixin` +### `Ember._captureRenderTree` +### `Ember.assert` +### `Ember.warn` +### `Ember.debug` +### `Ember.deprecate` +### `Ember.deprecateFunc` +### `Ember.runInDebug` +### `Ember.inspect` +### `Ember.Debug` +### `Ember.ContainerDebugAdapter` +### `Ember.DataAdapter` +### `Ember._assertDestroyablesDestroyed` +### `Ember._associateDestroyableChild` +### `Ember._enableDestroyableTracking` +### `Ember._isDestroying` +### `Ember._isDestroyed` +### `Ember._registerDestructor` +### `Ember._unregisterDestructor` +### `Ember.destroy` +### `Ember.Engine` +### `Ember.EngineInstance` +### `Ember.Enumerable` +### `Ember.MutableEnumerable` +### `Ember.instrument` +### `Ember.subscribe` +### `Ember.Instrumentation` +### `Ember.Object` +### `Ember._action` +### `Ember.computed` +### `Ember.defineProperty` +### `Ember.get` +### `Ember.getProperties` +### `Ember.notifyPropertyChange` +### `Ember.observer` +### `Ember.set` +### `Ember.trySet` +### `Ember.setProperties` +### `Ember.cacheFor` +### `Ember._dependentKeyCompat` +### `Ember.ComputedProperty` +### `Ember.expandProperties` +### `Ember.CoreObject` +### `Ember.Evented` +### `Ember.on` +### `Ember.addListener` +### `Ember.removeListener` +### `Ember.sendEvent` +### `Ember.Mixin` +### `Ember.mixin` +### `Ember.Observable` +### `Ember.addObserver` +### `Ember.removeObserver` +### `Ember.PromiseProxyMixin` +### `Ember.ObjectProxy` +### `Ember.RouterDSL` +### `Ember.controllerFor` +### `Ember.generateController` +### `Ember.generateControllerFactory` +### `Ember.generateControllerFactory` +### `Ember.HashLocation` +### `Ember.HistoryLocation` +### `Ember.NonLocation` +### `Ember.Route` +### `Ember.Router` +### `Ember.run` +### `Ember.Service` +### `Ember.compare` +### `Ember.isBlank` +### `Ember.isEmpty` +### `Ember.isEqual` +### `Ember.isPresent` +### `Ember.typeOf` +### `Ember.VERSION` +### `Ember.ViewUtils` +### `Ember._getComponentTemplate` +### `Ember._helperManagerCapabilities` +### `Ember._setComponentTemplate` +### `Ember._setHelperManager` +### `Ember._setModifierManager` +### `Ember._templateOnlyComponent` +### `Ember._invokeHelper` +### `Ember._hash` +### `Ember._array` +### `Ember._concat` +### `Ember._get` +### `Ember._on` +### `Ember._fn` +### `Ember._Backburner` +### `Ember.inject` +### `Ember.__loader` +### `Ember.ENV` + +Use +``` +import MyEnv from '/config/environment'; +``` -### Ember.HTMLBars / Ember.Handlebars (must go) +### `Ember.lookup` -#### `Ember.Handlebars.Utils.escapeExpression` +### `Ember.onerror` -Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. +Use +```js +window.addEventListener('error', /* ... event handler ... */); +``` -### Ember.Test/Ember.setupForTesting (should be replaced by @ember/test-helpers??) +### `Ember.testing` +### `Ember.BOOTED` +No replacement. Unused. +### `Ember.TEMPLATES` -### Container +This is the template registry. It does not need to be public API. -### Registry +No replacement. -### _setComponentManager (has replacement on @ember/component) +### `Ember.HTMLBars` -### _modifierManagerCapabilities (has replacement on @ember/modifier) +No replacement. -### _componentManagerCapabilities +### `Ember.Handlebars` -### meta (tagged private but exported on 'ember') +No replacement. -### RSVP +#### `Ember.Handlebars.Utils.escapeExpression` -### libraries (may need public replacement) +Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. -### ActionHandler (no public API) -### Comparable (used by import compare from @ember/utils) +### `Ember.Test` +### `Ember.setupForTesting` ## How We Teach This From 845c66a2cbf46068cd1fab626bbead1adc10a770 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 6 Feb 2024 22:28:08 -0800 Subject: [PATCH 10/44] Update motivation --- text/1003-deprecation-import-ember-from-ember.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 5d868f61ed..732e72c4d8 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -37,8 +37,11 @@ This RFC proprosing deprecating all APIs that have module-based replacements, as ## Motivation -> Why are we doing this? What are the problems with the deprecated feature? -What is the replacement functionality? +The `import Ember from 'ember';` set of APIs is implementn as a barrel file, and properly optimizing barrel files [is a lot of work, requiring integration with build time tools](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js). + +By removing this set of exports, we have an opportunity to shrink some apps (as some APIs are not used), improving the load performance of ember apps -- and we removing all of these gives us a chance to have a better grasp of what we can get rid of permananently. + +Many of these APIs already have alternatives, and those will be called out explicitly in the _Transition Path_ below. ## Transition Path From 2acef1c93477ea378ec18b0a9f405968c3d6cdac Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Wed, 7 Feb 2024 00:45:01 -0800 Subject: [PATCH 11/44] So many APIs --- ...003-deprecation-import-ember-from-ember.md | 349 +++++++++++++++++- 1 file changed, 342 insertions(+), 7 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 732e72c4d8..c29bed1836 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -45,6 +45,8 @@ Many of these APIs already have alternatives, and those will be called out expli ## Transition Path +This list is semi-exhaustive, in that it covers _every_ export from 'ember', but may not exhaustivily provide alternatives. + ### `Ember.isNamespace` No replacement, not needed. @@ -55,10 +57,13 @@ No replacement, not needed. e ### `Ember.Container` -Both value and type are not needed. +No replacement. Both value and type are not needed. ### `Ember.Registry` +No replacement. Both value and type are not needed. +Every property/method on this value is private. + ### `Ember.testing` Instead, use @@ -75,94 +80,424 @@ if (macroCondition(isTesting()) { ### `Ember._setComponentManager` -Use +Instead, use ```js import { setComponentManager } from '@ember/component'; ``` ### `Ember._componentManagerCapabilities` -Use +Instead, use ```js import { capabilities } from '@ember/component'; ``` ### `Ember._modifierManagerCapabilities` -Use +Instead, use ```js import { capabilities } from '@ember/modifier'; ``` ### `Ember.meta` -No replacement, not public API +No replacement, not public API. +But meta may be used for the ember-inspector, but there are discussions starting around the time of this RFC to rework how ember-source and the inspector communicate with each other. ### `Ember._createCache` +Instead, use + +```js +import { createCache } from '@glimmer/tracking/primitives/cache'; +``` + +Implemented from [RFC#615](https://rfcs.emberjs.com/id/0615-autotracking-memoization) + ### `Ember._cacheGetValue` + +Instead, use +```js +import { getValue } from '@glimmer/tracking/primitives/cache'; +``` + +Implemented from [RFC#615](https://rfcs.emberjs.com/id/0615-autotracking-memoization) + ### `Ember._cacheIsConst` + +Instead, use +```js +import { isConst } from '@glimmer/tracking/primitives/cache'; +``` + +Implemented from [RFC#615](https://rfcs.emberjs.com/id/0615-autotracking-memoization) + ### `Ember._descriptor` + +No replacement. Internal utility for helping author decorators. + ### `Ember._getPath` + +No replacement. Used for deep getting a property on an object unless it's destroyed. + ### `Ember._setClassicDecorator` + +No replacement. Internal utility for helping author decorators. + ### `Ember._tracked` + +Instead, use + +```js +import { tracked } from '@glimmer/tracking'; +``` + ### `Ember.beginPropertyChanges` + +No replacement. + ### `Ember.changeProperties` + +No replacement. + ### `Ember.endPropertyChanges` + +No replacement. + ### `Ember.hasListeners` + +No replacement. + ### `Ember.libraries` -### `Ember._ContainerProxyMixin` + +No replacement. + +App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. + + +### `Ember._ContainerProxyMixin + +No replacement. Mixins have been recommended against since Octane's release. + ### `Ember._ProxyMixin` + +No replacement. Mixins have been recommended against since Octane's release. + ### `Ember._RegistryProxyMixin` + +No replacement. Mixins have been recommended against since Octane's release. + ### `Ember.ActionHandler` + +No replacement. + ### `Ember.Comparable` + +No replacement. Mixins have been recommended against since Octane's release. + ### `Ember.RSVP` + +Instead use +```js +import RSVP from 'rsvp'; +``` + ### `Ember._Cache` + +No replacement. A general `Map`-based Cache that tracks the misses and hits. + ### `Ember.GUID_KEY` + +No replacement. Private. + ### `Ember.canInvoke` + +Instead use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining): +```js +this.foo?.method?.(); +``` ### `Ember.generateGuid` + +No replacement. Private. + ### `Ember.guidFor` + +Instead use +```js +import { guidFor } from '@ember/object/internals'; +``` + ### `Ember.uuid` + +No replacement. + ### `Ember.wrap` + +No replacement. Private. + ### `Ember.getOwner` + +Instead, use +```js +import { getOwner } from '@ember/owner'; +``` + ### `Ember.onLoad` + +Instead, use +```js +import { onLoad } from '@ember/application'; +``` + ### `Ember.runLoadHooks` + +Instead, use +```js +import { runLoadHooks } from '@ember/application'; +``` + ### `Ember.setOwner` + +Instead, use +```js +import { setOwner } from '@ember/owner'; +``` + ### `Ember.Application` + +Instead, use +```js +import Application from '@ember/application'; +``` + ### `Ember.ApplicationInstance` + +Instead, use +```js +import ApplicationInstance from '@ember/application/instance'; +``` + ### `Ember.Namespace` + +Instead, use +```js +import Namespace from '@ember/application/namespace'; +``` + ### `Ember.A` + +Instead, use +```js +import { A } from '@ember/array'; +``` + ### `Ember.Array` + +Instead, use +```js +import EmberArray from '@ember/array'; +``` + ### `Ember.NativeArray` + +Instead, use +```js +import { NativeArray } from '@ember/array'; +``` + ### `Ember.isArray` + +Instead, use +```js +import { isArray } from '@ember/array'; +``` + ### `Ember.makeArray` + +Instead, use +```js +import { makeArray } from '@ember/array'; +``` + ### `Ember.MutableArray` + +Instead, use +```js +import MutableArray from '@ember/array/mutable'; +``` + ### `Ember.ArrayProxy` + +Instead, use +```js +import ArrayProxy from '@ember/array/proxy'; +``` + ### `Ember.FEATURES` + +No replacement. +But this is useful when working with feature flags. +This information could live on a specially named `globalThis` property, the enabled features could be emitted as a virtual module to import. + ### `Ember._Input` + +Instead, use +```js +import { Input } from '@ember/component'; +``` + ### `Ember.Component` + +Instead, use +```js +import Component from '@ember/component'; +``` + ### `Ember.Helper` + +Instead, use +```js +import Helper from '@ember/component/helper'; +``` + ### `Ember.Controller` + +Instead, use +```js +import Controller from '@ember/controller'; +``` + ### `Ember.ControllerMixin` + +No replacement. + ### `Ember._captureRenderTree` + +No replacement. But used by ember-inspector. + ### `Ember.assert` -### `Ember.warn` + +Instead, use +```js +import { assert } from '@ember/debug'; +``` + +### `Ember.warn + +Instead, use +```js +import { warn } from '@ember/debug'; +``` + ### `Ember.debug` + +Instead, use +```js +import { debug } from '@ember/debug'; +``` ### `Ember.deprecate` + +Instead, use +```js +import { deprecate } from '@ember/debug'; +``` + ### `Ember.deprecateFunc` + +No replacement. Private. + ### `Ember.runInDebug` + +Instead, use +```js +import { runInDebug } from '@ember/debug'; +``` + ### `Ember.inspect` + +No replacement. Private. + ### `Ember.Debug` + +No replacement. + +#### `Ember.Debug.registerDeprecationHandler` + +Instead, use +```js +import { registerDeprecationHandler } from '@ember/debug'; +``` + ### `Ember.ContainerDebugAdapter` + +Instead, use +```js +import ContainerDebugAdapter from '@ember/debug/container-debug-adapter'; +``` + ### `Ember.DataAdapter` + +Instead, use +```js +import DataAdapter from '@ember/debug/data-adapter'; +``` + ### `Ember._assertDestroyablesDestroyed` + +Instead, use +```js +import { assertDestroyablesDestroyed } from '@ember/destroyable'; +``` + ### `Ember._associateDestroyableChild` + +Instead, use +```js +import { associateDestroyableChild } from '@ember/destroyable'; +``` + ### `Ember._enableDestroyableTracking` + +Instead, use +```js +import { enableDestroyableTracking } from '@ember/destroyable'; +``` + ### `Ember._isDestroying` + +Instead, use +```js +import { isDestroying } from '@ember/destroyable'; +``` + ### `Ember._isDestroyed` + +Instead, use +```js +import { isDestroyed } from '@ember/destroyable'; +``` + ### `Ember._registerDestructor` + +Instead, use +```js +import { registerDestructor } from '@ember/destroyable'; +``` + ### `Ember._unregisterDestructor` + +Instead, use +```js +import { unregisterDestructor } from '@ember/destroyable'; +``` + ### `Ember.destroy` + +Instead, use +```js +import { destroy } from '@ember/destroyable'; +``` + ### `Ember.Engine` ### `Ember.EngineInstance` ### `Ember.Enumerable` From 28b45c7a5246908f3661b77530c09ae06e1326ae Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Wed, 7 Feb 2024 10:38:26 -0800 Subject: [PATCH 12/44] It's all there --- ...003-deprecation-import-ember-from-ember.md | 832 ++++++------------ 1 file changed, 255 insertions(+), 577 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index c29bed1836..fe409cd778 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -47,581 +47,266 @@ Many of these APIs already have alternatives, and those will be called out expli This list is semi-exhaustive, in that it covers _every_ export from 'ember', but may not exhaustivily provide alternatives. -### `Ember.isNamespace` +The deprecations kind of fall in to 3 categories +- has a modern equivelent ( +- private and needs no replacements +- not private, but there is no plan for providing a built-in alternative + + +### Behavior Alternatives + + + +### New Module Needed + +APIs for wiring up a test framework (e.g. QUnit, _etc_) +- `Ember.Test` +- `Ember.Test.Adapter` +- `Ember.Test.QUnitAdapter` +- `Ember.setupForTesting` + +These will need to be moved to a module such as `@ember/testing`. + +### No replacements. + +Applies to both the value and type exports (if applicable). + +- `Ember._getPath` +- `Ember.isNamespace` +- `Ember.toString` +- `Ember.Container` +- `Ember.Registry` +- `Ember.meta` + meta may be used for the ember-inspector, but there are discussions starting around the time of this RFC to rework how ember-source and the inspector communicate with each other. + + +Internal decorator utils +- `Ember._descriptor` +- `Ember._setClassicDecorator` + +Reactivity +- `Ember.beginPropertyChanges` +- `Ember.changeProperties` +- `Ember.endPropertyChanges` + +Observable +- `Ember.hasListeners` + +Mixins +- `Ember._ContainerProxyMixin` +- `Ember._ProxyMixin` +- `Ember._RegistryProxyMixin` +- `Ember.ActionHandler` +- `Ember.Comparable` + +Utility +- `Ember.libraries` - + App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. +- `Ember._Cache` +- `Ember.GUID_KEY` +- `Ember.canInvoke` + Instead use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining): + ```js + this.foo?.method?.(); + ``` +- `Ember.testing` + Instead, use + + ```js + import { macroCondition, isTesting } from '@embroider/macros'; + + // ... + + if (macroCondition(isTesting()) { + // test only code here + } + ``` + +- `Ember.onerror` + Instead use an event listener for the `error` event on window. + ```js + window.addEventListener('error', /* ... event handler ... */); + ``` +- `Ember.generateGuid` +- `Ember.uuid` +- `Ember.wrap` +- `Ember.FEATURES` + But this is useful when working with feature flags. + This information could live on a specially named `globalThis` property, the enabled features could be emitted as a virtual module to import. +- `Ember.ControllerMixin` +- `Ember._captureRenderTree` + used by ember-inspector. +- `Ember.deprecateFunc` +- `Ember.inspect` +- `Ember.Debug` +- `Ember.instrument` +- `Ember.subscribe` +- `Ember.Instrumentation.instrument` +- `Ember.Instrumentation.subscribe` +- `Ember.Instrumentation.unsubscribe` +- `Ember.Instrumentation.reset` +- `Ember.cacheFor` +- `Ember.ComputedProperty` +- `Ember.RouterDSL` +- `Ember.controllerFor` +- `Ember.generateController` +- `Ember.generateControllerFactory` +- `Ember.VERSION` + This has the ember version in it, but it could be converted to a virtual module to import from somewhere. +- `Ember.ViewUtils` +- `Ember.ViewUtils.getChildViews` +- `Ember.ViewUtils.getElementView` +- `Ember.ViewUtils.getRootViews` +- `Ember.ViewUtils.getViewBounds` +- `Ember.ViewUtils.getViewBoundingClientRect` +- `Ember.ViewUtils.getViewClientRects` +- `Ember.ViewUtils.getViewElement` +- `Ember.ViewUtils.isSimpleClick` +- `Ember.ViewUtils.isSerializationFirstNode` +- `Ember._Backburner` +- `Ember.inject` +- `Ember.__loader` +- `Ember.__loader.require` +- `Ember.__loader.define` +- `Ember.__loader.registry` +- `Ember.BOOTED` +- `Ember.TEMPLATES` + + +Replaced by [RFC #931][RFC-931] +- `Ember.HTMLBars` +- `Ember.HTMLBars.template` +- `Ember.HTMLBars.compile` +- `Ember.HTMLBars.precomple` +- `Ember.Handlebars` +- `Ember.Handlebars.template` +- `Ember.Handlebars.Utils.escapeExpression` + Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. +- `Ember.Handlebars.compile` +- `Ember.Handlebars.precomple` + + +[RFC-931]: https://github.com/emberjs/rfcs/pull/931 -No replacement, not needed. - -### `Ember.toString` - -No replacement, not needed. -e -### `Ember.Container` - -No replacement. Both value and type are not needed. - -### `Ember.Registry` - -No replacement. Both value and type are not needed. -Every property/method on this value is private. - -### `Ember.testing` - -Instead, use - -```js -import { macroCondition, isTesting } from '@embroider/macros'; - -// ... - -if (macroCondition(isTesting()) { - // test only code here -} -``` - -### `Ember._setComponentManager` - -Instead, use -```js -import { setComponentManager } from '@ember/component'; -``` - -### `Ember._componentManagerCapabilities` - -Instead, use -```js -import { capabilities } from '@ember/component'; -``` - -### `Ember._modifierManagerCapabilities` - -Instead, use -```js -import { capabilities } from '@ember/modifier'; -``` - -### `Ember.meta` - -No replacement, not public API. -But meta may be used for the ember-inspector, but there are discussions starting around the time of this RFC to rework how ember-source and the inspector communicate with each other. - -### `Ember._createCache` - -Instead, use - -```js -import { createCache } from '@glimmer/tracking/primitives/cache'; -``` - -Implemented from [RFC#615](https://rfcs.emberjs.com/id/0615-autotracking-memoization) - -### `Ember._cacheGetValue` - -Instead, use -```js -import { getValue } from '@glimmer/tracking/primitives/cache'; -``` - -Implemented from [RFC#615](https://rfcs.emberjs.com/id/0615-autotracking-memoization) - -### `Ember._cacheIsConst` - -Instead, use -```js -import { isConst } from '@glimmer/tracking/primitives/cache'; -``` - -Implemented from [RFC#615](https://rfcs.emberjs.com/id/0615-autotracking-memoization) - -### `Ember._descriptor` - -No replacement. Internal utility for helping author decorators. - -### `Ember._getPath` - -No replacement. Used for deep getting a property on an object unless it's destroyed. - -### `Ember._setClassicDecorator` - -No replacement. Internal utility for helping author decorators. - -### `Ember._tracked` - -Instead, use - -```js -import { tracked } from '@glimmer/tracking'; -``` - -### `Ember.beginPropertyChanges` - -No replacement. - -### `Ember.changeProperties` - -No replacement. - -### `Ember.endPropertyChanges` - -No replacement. - -### `Ember.hasListeners` - -No replacement. - -### `Ember.libraries` - -No replacement. - -App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. - - -### `Ember._ContainerProxyMixin - -No replacement. Mixins have been recommended against since Octane's release. - -### `Ember._ProxyMixin` - -No replacement. Mixins have been recommended against since Octane's release. - -### `Ember._RegistryProxyMixin` - -No replacement. Mixins have been recommended against since Octane's release. - -### `Ember.ActionHandler` - -No replacement. - -### `Ember.Comparable` - -No replacement. Mixins have been recommended against since Octane's release. - -### `Ember.RSVP` - -Instead use -```js -import RSVP from 'rsvp'; -``` - -### `Ember._Cache` - -No replacement. A general `Map`-based Cache that tracks the misses and hits. - -### `Ember.GUID_KEY` - -No replacement. Private. - -### `Ember.canInvoke` - -Instead use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining): -```js -this.foo?.method?.(); -``` -### `Ember.generateGuid` - -No replacement. Private. - -### `Ember.guidFor` - -Instead use -```js -import { guidFor } from '@ember/object/internals'; -``` - -### `Ember.uuid` - -No replacement. - -### `Ember.wrap` - -No replacement. Private. - -### `Ember.getOwner` - -Instead, use -```js -import { getOwner } from '@ember/owner'; -``` - -### `Ember.onLoad` - -Instead, use -```js -import { onLoad } from '@ember/application'; -``` - -### `Ember.runLoadHooks` - -Instead, use -```js -import { runLoadHooks } from '@ember/application'; -``` - -### `Ember.setOwner` - -Instead, use -```js -import { setOwner } from '@ember/owner'; -``` - -### `Ember.Application` - -Instead, use -```js -import Application from '@ember/application'; -``` - -### `Ember.ApplicationInstance` - -Instead, use -```js -import ApplicationInstance from '@ember/application/instance'; -``` - -### `Ember.Namespace` - -Instead, use -```js -import Namespace from '@ember/application/namespace'; -``` - -### `Ember.A` - -Instead, use -```js -import { A } from '@ember/array'; -``` - -### `Ember.Array` - -Instead, use -```js -import EmberArray from '@ember/array'; -``` - -### `Ember.NativeArray` - -Instead, use -```js -import { NativeArray } from '@ember/array'; -``` - -### `Ember.isArray` - -Instead, use -```js -import { isArray } from '@ember/array'; -``` - -### `Ember.makeArray` - -Instead, use -```js -import { makeArray } from '@ember/array'; -``` - -### `Ember.MutableArray` - -Instead, use -```js -import MutableArray from '@ember/array/mutable'; -``` - -### `Ember.ArrayProxy` - -Instead, use -```js -import ArrayProxy from '@ember/array/proxy'; -``` - -### `Ember.FEATURES` - -No replacement. -But this is useful when working with feature flags. -This information could live on a specially named `globalThis` property, the enabled features could be emitted as a virtual module to import. - -### `Ember._Input` - -Instead, use -```js -import { Input } from '@ember/component'; -``` - -### `Ember.Component` - -Instead, use -```js -import Component from '@ember/component'; -``` - -### `Ember.Helper` - -Instead, use -```js -import Helper from '@ember/component/helper'; -``` - -### `Ember.Controller` - -Instead, use -```js -import Controller from '@ember/controller'; -``` - -### `Ember.ControllerMixin` - -No replacement. - -### `Ember._captureRenderTree` - -No replacement. But used by ember-inspector. - -### `Ember.assert` - -Instead, use -```js -import { assert } from '@ember/debug'; -``` - -### `Ember.warn - -Instead, use -```js -import { warn } from '@ember/debug'; -``` - -### `Ember.debug` - -Instead, use -```js -import { debug } from '@ember/debug'; -``` -### `Ember.deprecate` - -Instead, use -```js -import { deprecate } from '@ember/debug'; -``` - -### `Ember.deprecateFunc` - -No replacement. Private. - -### `Ember.runInDebug` - -Instead, use -```js -import { runInDebug } from '@ember/debug'; -``` - -### `Ember.inspect` - -No replacement. Private. - -### `Ember.Debug` - -No replacement. - -#### `Ember.Debug.registerDeprecationHandler` - -Instead, use -```js -import { registerDeprecationHandler } from '@ember/debug'; -``` - -### `Ember.ContainerDebugAdapter` - -Instead, use -```js -import ContainerDebugAdapter from '@ember/debug/container-debug-adapter'; -``` - -### `Ember.DataAdapter` - -Instead, use -```js -import DataAdapter from '@ember/debug/data-adapter'; -``` - -### `Ember._assertDestroyablesDestroyed` - -Instead, use -```js -import { assertDestroyablesDestroyed } from '@ember/destroyable'; -``` - -### `Ember._associateDestroyableChild` - -Instead, use -```js -import { associateDestroyableChild } from '@ember/destroyable'; -``` - -### `Ember._enableDestroyableTracking` - -Instead, use -```js -import { enableDestroyableTracking } from '@ember/destroyable'; -``` - -### `Ember._isDestroying` - -Instead, use -```js -import { isDestroying } from '@ember/destroyable'; -``` - -### `Ember._isDestroyed` - -Instead, use -```js -import { isDestroyed } from '@ember/destroyable'; -``` - -### `Ember._registerDestructor` - -Instead, use -```js -import { registerDestructor } from '@ember/destroyable'; -``` - -### `Ember._unregisterDestructor` - -Instead, use -```js -import { unregisterDestructor } from '@ember/destroyable'; -``` - -### `Ember.destroy` - -Instead, use -```js -import { destroy } from '@ember/destroyable'; -``` - -### `Ember.Engine` -### `Ember.EngineInstance` -### `Ember.Enumerable` -### `Ember.MutableEnumerable` -### `Ember.instrument` -### `Ember.subscribe` -### `Ember.Instrumentation` -### `Ember.Object` -### `Ember._action` -### `Ember.computed` -### `Ember.defineProperty` -### `Ember.get` -### `Ember.getProperties` -### `Ember.notifyPropertyChange` -### `Ember.observer` -### `Ember.set` -### `Ember.trySet` -### `Ember.setProperties` -### `Ember.cacheFor` -### `Ember._dependentKeyCompat` -### `Ember.ComputedProperty` -### `Ember.expandProperties` -### `Ember.CoreObject` -### `Ember.Evented` -### `Ember.on` -### `Ember.addListener` -### `Ember.removeListener` -### `Ember.sendEvent` -### `Ember.Mixin` -### `Ember.mixin` -### `Ember.Observable` -### `Ember.addObserver` -### `Ember.removeObserver` -### `Ember.PromiseProxyMixin` -### `Ember.ObjectProxy` -### `Ember.RouterDSL` -### `Ember.controllerFor` -### `Ember.generateController` -### `Ember.generateControllerFactory` -### `Ember.generateControllerFactory` -### `Ember.HashLocation` -### `Ember.HistoryLocation` -### `Ember.NonLocation` -### `Ember.Route` -### `Ember.Router` -### `Ember.run` -### `Ember.Service` -### `Ember.compare` -### `Ember.isBlank` -### `Ember.isEmpty` -### `Ember.isEqual` -### `Ember.isPresent` -### `Ember.typeOf` -### `Ember.VERSION` -### `Ember.ViewUtils` -### `Ember._getComponentTemplate` -### `Ember._helperManagerCapabilities` -### `Ember._setComponentTemplate` -### `Ember._setHelperManager` -### `Ember._setModifierManager` -### `Ember._templateOnlyComponent` -### `Ember._invokeHelper` -### `Ember._hash` -### `Ember._array` -### `Ember._concat` -### `Ember._get` -### `Ember._on` -### `Ember._fn` -### `Ember._Backburner` -### `Ember.inject` -### `Ember.__loader` -### `Ember.ENV` - -Use -``` -import MyEnv from '/config/environment'; -``` ### `Ember.lookup` -### `Ember.onerror` - -Use -```js -window.addEventListener('error', /* ... event handler ... */); -``` - -### `Ember.testing` -### `Ember.BOOTED` -No replacement. Unused. -### `Ember.TEMPLATES` - -This is the template registry. It does not need to be public API. - -No replacement. - -### `Ember.HTMLBars` - -No replacement. - -### `Ember.Handlebars` - -No replacement. - -#### `Ember.Handlebars.Utils.escapeExpression` - -Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. - - -### `Ember.Test` -### `Ember.setupForTesting` +#### Imports Available + +Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascript-module-api) + +| `Ember.` API | Use this instead | +| ---------- | ---------------- | +| `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | +| `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | +| `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | +| `Ember._createCache` | `import { createCache } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +| `Ember._cacheGetValue` | `import { getValue } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +| `Ember._cacheIsConst` | `import { isConst } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +| `Ember._tracked` | `import { tracked } from '@glimmer/tracking';` | +| `Ember.RSVP` | `import RSVP from 'rsvp';` | +| `Ember.guidFor` | `import { guidFor } from '@ember/object/internals';` | +| `Ember.getOwner` | `import { getOwner } from '@ember/owner';` | +| `Ember.setOwner` | `import { setOwner } from '@ember/owner';` | +| `Ember.onLoad` | `import { onLoad } from '@ember/application';` | +| `Ember.runLoadHooks` | `import { runLoadHooks } from '@ember/application';` | +| `Ember.Application` | `import Application from '@ember/application';` | +| `Ember.ApplicationInstance` | `import ApplicationInstance from '@ember/application/instance';` | +| `Ember.Namespace` | `import Namespace from '@ember/application/namespace';` | +| `Ember.A` | `import { A } from '@ember/array';` | +| `Ember.Array` | `import Array from '@ember/array';` | +| `Ember.NativeArray` | `import { NativeArray } from '@ember/array';` | +| `Ember.isArray` | `import { isArray } from '@ember/array';` | +| `Ember.makeArray` | `import { makeArray } from '@ember/array';` | +| `Ember.MutableArray` | `import MutableArray from '@ember/array/mutable';` | +| `Ember.ArrayProxy` | `import ArrayProxy from '@ember/array/proxy';` | +| `Ember._Input` | `import { Input } from '@ember/component';` | +| `Ember.Component` | `import Component from '@ember/component';` | +| `Ember.Helper` | `import Helper from '@ember/component/helper';` | +| `Ember.Controller` | `import Controller from '@ember/controller';` | +| `Ember.assert` | `import { assert } from '@ember/debug';` | +| `Ember.warn` | `import { warn } from '@ember/debug';` | +| `Ember.debug` | `import { debug } from '@ember/debug';` | +| `Ember.deprecate` | `import { deprecate } from '@ember/debug';` | +| `Ember.runInDebug` | `import { runInDebug } from '@ember/debug';` | +| `Ember.Debug.registerDeprecationHandler` | `import { registerDeprecationHandler } from '@ember/debug';` | +| `Ember.ContainerDebugAdapter` | `import ContainerDebugAdapter from '@ember/debug/container-debug-adapter';` | +| `Ember.DataAdapter` | `import DataAdapter from '@ember/debug/data-adapter';` | +| `Ember._assertDestroyablesDestroyed` | `import { assertDestroyablesDestroyed } from '@ember/destroyable';` | +| `Ember._associateDestroyableChild` | `import { associateDestroyableChild } from '@ember/destroyable';` | +| `Ember._enableDestroyableTracking` | `import { enableDestroyableTracking } from '@ember/destroyable';` | +| `Ember._isDestroying` | `import { isDestroying } from '@ember/destroyable';` | +| `Ember._isDestroyed` | `import { isDestroyed } from '@ember/destroyable';` | +| `Ember._registerDestructor` | `import { registerDestructor } from '@ember/destroyable';` | +| `Ember._unregisterDestructor` | `import { unregisterDestructor } from '@ember/destroyable';` | +| `Ember.destroy` | `import { destroy } from '@ember/destroyable';` | +| `Ember.Engine` | `import Engine from '@ember/engine';` | +| `Ember.EngineInstance` | `import Engine from '@ember/engine/instance';` | +| `Ember.Enumerable` | `import Enumerable from '@ember/enumerable';` | +| `Ember.MutableEnumerable` | `import MutableEnumerable from '@ember/enumerable/mutable';` | +| `Ember.Object` | `import Object from '@ember/object';` | +| `Ember._action` | `import { action } from '@ember/object';` | +| `Ember.computed` | `import { computed } from '@ember/object';` | +| `Ember.defineProperty` | `import { defineProperty } from '@ember/object';` | +| `Ember.get` | `import { get } from '@ember/object';` | +| `Ember.getProperties` | `import { getProperties } from '@ember/object';` | +| `Ember.notifyPropertyChange` | `import { notifyPropertyChange } from '@ember/object';` | +| `Ember.observer` | `import { observer } from '@ember/object';` | +| `Ember.set` | `import { set } from '@ember/object';` | +| `Ember.trySet` | `import { trySet } from '@ember/object';` | +| `Ember.setProperties` | `import { setProperties } from '@ember/object';` | +| `Ember._dependentKeyCompat` | `import { dependentKeyCompat } from '@ember/object/compat';` | +| `Ember.expandProperties` | `import { expandProperties } from '@ember/object/computed';` | +| `Ember.CoreObject` | `import EmberObject from '@ember/object';` | +| `Ember.Evented` | `import Evented from '@ember/object/evented';` | +| `Ember.on` | `import { on } from '@ember/object/evented';` | +| `Ember.addListener` | `import { addListener } from '@ember/object/events';` | +| `Ember.removeListener` | `import { removeListener } from '@ember/object/events';` | +| `Ember.sendEvent` | `import { sendEvent } from '@ember/object/events';` | +| `Ember.Mixin` | `import Mixin from '@ember/object/mixin';` | +| `Ember.mixin` | `import { mixin } from '@ember/object/mixin';` | +| `Ember.Observable` | `import Observable from '@ember/object/observable';` | +| `Ember.addObserver` | `import { addObserver } from '@ember/object/observers';` | +| `Ember.removeObserver` | `import { removeObserver } from '@ember/object/observers';` | +| `Ember.PromiseProxyMixin` | `import EmberPromiseProxyMixin from '@ember/object/promise-proxy-mixin';` | +| `Ember.ObjectProxy` | `import ObjectProxy from '@ember/object/proxy';` | +| `Ember.HistoryLocation` | `import HistoryLocation from '@ember/routing/history-location';` | +| `Ember.HashLocation` | `import HashLocation from '@ember/routing/hash-location';` | +| `Ember.NoneLocation` | `import NoneLocation from '@ember/routing/none-location';` | +| `Ember.Route` | `import Route from '@ember/routing/route';` | +| `Ember.run` | `import { run } from '@ember/runloop';` | +| `Ember.Service` | `import Service from '@ember/service';` | +| `Ember.compare` | `import { compare } from '@ember/utils';` | +| `Ember.isBlank` | `import { isBlank } from '@ember/utils';` | +| `Ember.isEmpty` | `import { isEmpty } from '@ember/utils';` | +| `Ember.isEqual` | `import { isEqual } from '@ember/utils';` | +| `Ember.isPresent` | `import { isPresent } from '@ember/utils';` | +| `Ember.typeOf` | `import { typeOf } from '@ember/utils';` | +| `Ember._getComponentTemplate` | `import { getComponentTemplate } from '@ember/component';` | +| `Ember._setComponentTemplate` | `import { setComponentTemplate } from '@ember/component';` | +| `Ember._helperManagerCapabilities` | `import { capabilities } from '@ember/helper';` | +| `Ember._setHelperManager` | `import { setHelperManager } from '@ember/helper';` | +| `Ember._setModifierManager` | `import { setModifierManager } from '@ember/modifier';` | +| `Ember._templateOnlyComponent` | `import templateOnly from '@ember/component/template-only';` | +| `Ember._invokeHelper` | `import { invokeHelper } from '@ember/helper';` | +| `Ember._hash` | `import { hash } from '@ember/helper';` | +| `Ember._array` | `import { array } from '@ember/helper';` | +| `Ember._concat` | `import { concat } from '@ember/helper';` | +| `Ember._get` | `import { get } from '@ember/helper';` | +| `Ember._on` | `import { on } from '@ember/modifier';` | +| `Ember._fn` | `import { fn } from '@ember/helper';` | +| `Ember.ENV` | `import MyEnv from '/config/environment';` | + + +[RFC-615]: https://rfcs.emberjs.com/id/0615-autotracking-memoization ## How We Teach This -> Would the acceptance of this proposal mean the Ember guides must be -re-organized or altered? Does it change how Ember is taught to new users -at any level? -Does it mean we need to put effort into highlighting the replacement -functionality more? What should we do about documentation, in the guides -related to this feature? -How should this deprecation be introduced and explained to existing Ember -users? +The guides already use the modern imports where available. -> Keep in mind the variety of learning materials: API docs, guides, blog posts, tutorials, etc. +There is a place that needs updating, around advanced debugging, where folks configure Backburner to be in debug mode. + +When using embroider and `staticEmberSource: true`, the benefits of not having this file can be realized in apps (as long as the app and all consumed addons do not import from 'ember') Available Codemods @@ -629,19 +314,12 @@ Available Codemods ## Drawbacks -> Why should we *not* do this? Please consider the impact on teaching Ember, -on the integration of this feature with other existing and planned features, -on the impact of the API churn on existing apps, etc. -There are tradeoffs to choosing any path, please attempt to identify them here. +n/a, to be more module-friendly, we must get rid of the `'ember'` import. ## Alternatives -As a migration path for folks, we could add a package.json#exports entry to [`ember`](https://www.npmjs.com/package/ember) -that re-exports the still-available APIs. - -Some APIs we don't want or need to keep at all though. +n/a ## Unresolved questions -> Optional, but suggested for first drafts. What parts of the design are still -TBD? +n/a \ No newline at end of file From c6c9a4911b9c1e93a4ffd778fb9ca954470e2056 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Wed, 7 Feb 2024 10:57:54 -0800 Subject: [PATCH 13/44] More organization --- ...003-deprecation-import-ember-from-ember.md | 72 ++++++++++--------- 1 file changed, 40 insertions(+), 32 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index fe409cd778..090500ff86 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -47,16 +47,6 @@ Many of these APIs already have alternatives, and those will be called out expli This list is semi-exhaustive, in that it covers _every_ export from 'ember', but may not exhaustivily provide alternatives. -The deprecations kind of fall in to 3 categories -- has a modern equivelent ( -- private and needs no replacements -- not private, but there is no plan for providing a built-in alternative - - -### Behavior Alternatives - - - ### New Module Needed APIs for wiring up a test framework (e.g. QUnit, _etc_) @@ -67,6 +57,42 @@ APIs for wiring up a test framework (e.g. QUnit, _etc_) These will need to be moved to a module such as `@ember/testing`. +### A way to communicate with the ember-inspector + +The inspector will be hit especially hard by the removal of these APIs. + +- `Ember.meta` +- `Ember.VERSION` +- `Ember._captureRenderTree` +- `Ember.instrument` +- `Ember.subscribe` +- `Ember.Instrumentation.instrument` +- `Ember.Instrumentation.subscribe` +- `Ember.Instrumentation.unsubscribe` +- `Ember.Instrumentation.reset` +- `Ember.ViewUtils` +- `Ember.ViewUtils.getChildViews` +- `Ember.ViewUtils.getElementView` +- `Ember.ViewUtils.getRootViews` +- `Ember.ViewUtils.getViewBounds` +- `Ember.ViewUtils.getViewBoundingClientRect` +- `Ember.ViewUtils.getViewClientRects` +- `Ember.ViewUtils.getViewElement` +- `Ember.ViewUtils.isSimpleClick` +- `Ember.ViewUtils.isSerializationFirstNode` + + +Perhaps we can have folks add this to their apps: +```js +import { macroCondition, isDevelopingApp, importSync } from '@embroider/macros'; + +if (macroCondition(isDevelopingApp())) { + // maybe this is side-effecting and installs + // some functions on `globalThis` that the inspector could call + importSync('@ember/inspector-support'); +} +``` + ### No replacements. Applies to both the value and type exports (if applicable). @@ -76,9 +102,6 @@ Applies to both the value and type exports (if applicable). - `Ember.toString` - `Ember.Container` - `Ember.Registry` -- `Ember.meta` - meta may be used for the ember-inspector, but there are discussions starting around the time of this RFC to rework how ember-source and the inspector communicate with each other. - Internal decorator utils - `Ember._descriptor` @@ -134,17 +157,10 @@ Utility But this is useful when working with feature flags. This information could live on a specially named `globalThis` property, the enabled features could be emitted as a virtual module to import. - `Ember.ControllerMixin` -- `Ember._captureRenderTree` - used by ember-inspector. - `Ember.deprecateFunc` - `Ember.inspect` - `Ember.Debug` -- `Ember.instrument` -- `Ember.subscribe` -- `Ember.Instrumentation.instrument` -- `Ember.Instrumentation.subscribe` -- `Ember.Instrumentation.unsubscribe` -- `Ember.Instrumentation.reset` + Replaced by some of `@ember/debug` exports. - `Ember.cacheFor` - `Ember.ComputedProperty` - `Ember.RouterDSL` @@ -153,16 +169,6 @@ Utility - `Ember.generateControllerFactory` - `Ember.VERSION` This has the ember version in it, but it could be converted to a virtual module to import from somewhere. -- `Ember.ViewUtils` -- `Ember.ViewUtils.getChildViews` -- `Ember.ViewUtils.getElementView` -- `Ember.ViewUtils.getRootViews` -- `Ember.ViewUtils.getViewBounds` -- `Ember.ViewUtils.getViewBoundingClientRect` -- `Ember.ViewUtils.getViewClientRects` -- `Ember.ViewUtils.getViewElement` -- `Ember.ViewUtils.isSimpleClick` -- `Ember.ViewUtils.isSerializationFirstNode` - `Ember._Backburner` - `Ember.inject` - `Ember.__loader` @@ -172,7 +178,6 @@ Utility - `Ember.BOOTED` - `Ember.TEMPLATES` - Replaced by [RFC #931][RFC-931] - `Ember.HTMLBars` - `Ember.HTMLBars.template` @@ -305,6 +310,9 @@ Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascrip The guides already use the modern imports where available. There is a place that needs updating, around advanced debugging, where folks configure Backburner to be in debug mode. +- https://guides.emberjs.com/release/applications/run-loop/#toc_where-can-i-find-more-information +- https://guides.emberjs.com/release/configuring-ember/debugging/#toc_errors-within-emberrunlater-backburner + - Access to backburner here isn't relevant though because it's accessed from the `run` import from `@ember/runloop` When using embroider and `staticEmberSource: true`, the benefits of not having this file can be realized in apps (as long as the app and all consumed addons do not import from 'ember') From 656fa835a160b29022309babf97de8296dc5240a Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 8 Feb 2024 15:20:55 -0800 Subject: [PATCH 14/44] Add clarification for inspector stuff --- ...003-deprecation-import-ember-from-ember.md | 46 +++++++++++-------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 090500ff86..fdfdcbf33f 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -61,25 +61,29 @@ These will need to be moved to a module such as `@ember/testing`. The inspector will be hit especially hard by the removal of these APIs. -- `Ember.meta` -- `Ember.VERSION` -- `Ember._captureRenderTree` -- `Ember.instrument` -- `Ember.subscribe` -- `Ember.Instrumentation.instrument` -- `Ember.Instrumentation.subscribe` -- `Ember.Instrumentation.unsubscribe` -- `Ember.Instrumentation.reset` -- `Ember.ViewUtils` -- `Ember.ViewUtils.getChildViews` -- `Ember.ViewUtils.getElementView` -- `Ember.ViewUtils.getRootViews` -- `Ember.ViewUtils.getViewBounds` -- `Ember.ViewUtils.getViewBoundingClientRect` -- `Ember.ViewUtils.getViewClientRects` -- `Ember.ViewUtils.getViewElement` -- `Ember.ViewUtils.isSimpleClick` -- `Ember.ViewUtils.isSerializationFirstNode` +A good few already have available imports though. + +| API | import | +| --- | ------ | +| `Ember.meta` | `import { meta } from '@ember/-internals/meta';`[^internals] | +| `Ember.VERSION` | none | +| `Ember._captureRenderTree` | `import { captureRenderTree } from '@ember/debug';` | +| `Ember.instrument` | `import { instrument } from '@ember/instrumentation';`[^internals] | +| `Ember.subscribe` | `import { subscribe } from '@ember/instrumentation';`[^internals] | +| `Ember.Instrumentation.*` | `import { * } from '@ember/instrumentation';`[^internals] | +| `Ember.ViewUtils` | `import * as viewUtils from '@ember/-internals/views';`[^view-utils] [^internals] | +| `Ember.ViewUtils.getChildViews` | `import { getChildViews } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.getElementView` | `import { getElementView } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.getRootViews` | `import { getRootViews } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.getViewBounds` | `import { getViewBounds } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.getViewBoundingClientRect` | `import { getViewBoundingClientRect } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.getViewClientRects` | `import { getViewClientRects } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.getViewElement` | `import { getViewElement } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.isSimpleClick` | `import { isSimpleClick } from '@ember/-internals/views';`[^internals] | +| `Ember.ViewUtils.isSerializationFirstNode` | `import { isSerializationFirstNode } from '@ember/-internals/glimmer';`[^internals] | + +[^view-utils]: Not all of these exports are used for `ViewUtils`. +[^internals]: We may not want to expose "internals" as a package, but we may have to if it's the cleanest way to retain these APIs for _our own_ tooling. Are these covered under SemVer? Perhaps we can have folks add this to their apps: @@ -330,4 +334,6 @@ n/a ## Unresolved questions -n/a \ No newline at end of file +n/a + +Do our instrumentation and internals sub-packages have any SemVer guarantees? Or are we allowed to "do what we need to" and not care about _public-facing_ SemVer? From 65f5401299837562f3cda5492749f9b0d321566d Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 9 Feb 2024 14:28:35 -0500 Subject: [PATCH 15/44] FEATURES *does* have a public API --- text/1003-deprecation-import-ember-from-ember.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index fdfdcbf33f..eef903c734 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -127,6 +127,7 @@ Mixins - `Ember.Comparable` Utility +- `Ember.lookup` - `Ember.libraries` - App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. - `Ember._Cache` @@ -195,10 +196,11 @@ Replaced by [RFC #931][RFC-931] - `Ember.Handlebars.precomple` + + [RFC-931]: https://github.com/emberjs/rfcs/pull/931 -### `Ember.lookup` #### Imports Available @@ -206,6 +208,7 @@ Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascrip | `Ember.` API | Use this instead | | ---------- | ---------------- | +| `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | | `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | | `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | | `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | From 7b0faeefecbe0075cc462d13dadab793cc2b5f77 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 9 Feb 2024 15:37:28 -0500 Subject: [PATCH 16/44] Add visibility to each API --- ...003-deprecation-import-ember-from-ember.md | 358 +++++++++--------- 1 file changed, 180 insertions(+), 178 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index eef903c734..d508561293 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -47,6 +47,12 @@ Many of these APIs already have alternatives, and those will be called out expli This list is semi-exhaustive, in that it covers _every_ export from 'ember', but may not exhaustivily provide alternatives. +Throughout the rest of this RFC, the following key will be used: +- 🌐 to mean "this is public API" +- 🔒 to mean "this is private API" +- 🧷 to mean "this is protected API" +- 🫣 to mean "no declared access" + ### New Module Needed APIs for wiring up a test framework (e.g. QUnit, _etc_) @@ -63,27 +69,26 @@ The inspector will be hit especially hard by the removal of these APIs. A good few already have available imports though. -| API | import | -| --- | ------ | -| `Ember.meta` | `import { meta } from '@ember/-internals/meta';`[^internals] | -| `Ember.VERSION` | none | -| `Ember._captureRenderTree` | `import { captureRenderTree } from '@ember/debug';` | -| `Ember.instrument` | `import { instrument } from '@ember/instrumentation';`[^internals] | -| `Ember.subscribe` | `import { subscribe } from '@ember/instrumentation';`[^internals] | -| `Ember.Instrumentation.*` | `import { * } from '@ember/instrumentation';`[^internals] | -| `Ember.ViewUtils` | `import * as viewUtils from '@ember/-internals/views';`[^view-utils] [^internals] | -| `Ember.ViewUtils.getChildViews` | `import { getChildViews } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.getElementView` | `import { getElementView } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.getRootViews` | `import { getRootViews } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.getViewBounds` | `import { getViewBounds } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.getViewBoundingClientRect` | `import { getViewBoundingClientRect } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.getViewClientRects` | `import { getViewClientRects } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.getViewElement` | `import { getViewElement } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.isSimpleClick` | `import { isSimpleClick } from '@ember/-internals/views';`[^internals] | -| `Ember.ViewUtils.isSerializationFirstNode` | `import { isSerializationFirstNode } from '@ember/-internals/glimmer';`[^internals] | +| | API | import | +| - | --- | ------ | +|🔒| `Ember.meta` | `import { meta } from '@ember/-internals/meta';` | +|🌐| `Ember.VERSION` | none | +|🔒| `Ember._captureRenderTree` | `import { captureRenderTree } from '@ember/debug';` | +|🔒| `Ember.instrument` | `import { instrument } from '@ember/instrumentation';` | +|🔒| `Ember.subscribe` | `import { subscribe } from '@ember/instrumentation';` | +|🔒| `Ember.Instrumentation.*` | `import { * } from '@ember/instrumentation';` | +|🫣| `Ember.ViewUtils` | `import * as viewUtils from '@ember/-internals/views';`[^view-utils] | +|🔒| `Ember.ViewUtils.getChildViews` | `import { getChildViews } from '@ember/-internals/views';` | +|🫣| `Ember.ViewUtils.getElementView` | `import { getElementView } from '@ember/-internals/views';` | +|🔒| `Ember.ViewUtils.getRootViews` | `import { getRootViews } from '@ember/-internals/views';` | +|🔒| `Ember.ViewUtils.getViewBounds` | `import { getViewBounds } from '@ember/-internals/views';` | +|🔒| `Ember.ViewUtils.getViewBoundingClientRect` | `import { getViewBoundingClientRect } from '@ember/-internals/views';` | +|🔒| `Ember.ViewUtils.getViewClientRects` | `import { getViewClientRects } from '@ember/-internals/views';` | +|🔒| `Ember.ViewUtils.getViewElement` | `import { getViewElement } from '@ember/-internals/views';` | +|🫣| `Ember.ViewUtils.isSimpleClick` | `import { isSimpleClick } from '@ember/-internals/views';` | +|🫣| `Ember.ViewUtils.isSerializationFirstNode` | `import { isSerializationFirstNode } from '@ember/-internals/glimmer';` | [^view-utils]: Not all of these exports are used for `ViewUtils`. -[^internals]: We may not want to expose "internals" as a package, but we may have to if it's the cleanest way to retain these APIs for _our own_ tooling. Are these covered under SemVer? Perhaps we can have folks add this to their apps: @@ -101,43 +106,43 @@ if (macroCondition(isDevelopingApp())) { Applies to both the value and type exports (if applicable). -- `Ember._getPath` -- `Ember.isNamespace` -- `Ember.toString` -- `Ember.Container` -- `Ember.Registry` +- 🫣 `Ember._getPath` +- 🫣 `Ember.isNamespace` +- 🫣 `Ember.toString` +- 🔒 `Ember.Container` +- 🔒 `Ember.Registry` Internal decorator utils -- `Ember._descriptor` -- `Ember._setClassicDecorator` +- 🫣 `Ember._descriptor` +- 🔒 `Ember._setClassicDecorator` Reactivity -- `Ember.beginPropertyChanges` -- `Ember.changeProperties` -- `Ember.endPropertyChanges` +- 🔒 `Ember.beginPropertyChanges` +- 🔒 `Ember.changeProperties` +- 🔒 `Ember.endPropertyChanges` Observable -- `Ember.hasListeners` +- 🌐 `Ember.hasListeners` Mixins -- `Ember._ContainerProxyMixin` -- `Ember._ProxyMixin` -- `Ember._RegistryProxyMixin` -- `Ember.ActionHandler` -- `Ember.Comparable` +- 🔒 `Ember._ContainerProxyMixin` +- 🔒 `Ember._ProxyMixin` +- 🔒 `Ember._RegistryProxyMixin` +- 🔒 `Ember.ActionHandler` +- 🔒 `Ember.Comparable` Utility -- `Ember.lookup` -- `Ember.libraries` - +- 🫣 `Ember.lookup` +- 🌐 `Ember.libraries` - App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. -- `Ember._Cache` -- `Ember.GUID_KEY` -- `Ember.canInvoke` +- 🫣 `Ember._Cache` +- 🔒 `Ember.GUID_KEY` +- 🔒 `Ember.canInvoke` Instead use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining): ```js this.foo?.method?.(); ``` -- `Ember.testing` +- 🫣 `Ember.testing` Instead, use ```js @@ -150,50 +155,46 @@ Utility } ``` -- `Ember.onerror` +- 🌐 `Ember.onerror` Instead use an event listener for the `error` event on window. ```js window.addEventListener('error', /* ... event handler ... */); ``` -- `Ember.generateGuid` -- `Ember.uuid` -- `Ember.wrap` -- `Ember.FEATURES` - But this is useful when working with feature flags. - This information could live on a specially named `globalThis` property, the enabled features could be emitted as a virtual module to import. -- `Ember.ControllerMixin` -- `Ember.deprecateFunc` -- `Ember.inspect` -- `Ember.Debug` +- 🔒 `Ember.generateGuid` +- 🌐 `Ember.uuid` +- 🔒 `Ember.wrap` +- 🫣 `Ember.deprecateFunc` +- 🔒 `Ember.inspect` +- 🫣 `Ember.Debug` Replaced by some of `@ember/debug` exports. -- `Ember.cacheFor` -- `Ember.ComputedProperty` -- `Ember.RouterDSL` -- `Ember.controllerFor` -- `Ember.generateController` -- `Ember.generateControllerFactory` -- `Ember.VERSION` +- 🫣 `Ember.cacheFor` +- 🌐 `Ember.ComputedProperty` +- 🫣 `Ember.RouterDSL` +- 🔒 `Ember.controllerFor` +- 🔒 `Ember.generateController` +- 🔒 `Ember.generateControllerFactory` +- 🌐 `Ember.VERSION` This has the ember version in it, but it could be converted to a virtual module to import from somewhere. -- `Ember._Backburner` -- `Ember.inject` -- `Ember.__loader` -- `Ember.__loader.require` -- `Ember.__loader.define` -- `Ember.__loader.registry` -- `Ember.BOOTED` -- `Ember.TEMPLATES` +- 🔒 `Ember._Backburner` +- 🌐 `Ember.inject` +- 🫣 `Ember.__loader` +- 🫣 `Ember.__loader.require` +- 🫣 `Ember.__loader.define` +- 🫣 `Ember.__loader.registry` +- 🔒 `Ember.BOOTED` +- 🔒 `Ember.TEMPLATES` Replaced by [RFC #931][RFC-931] -- `Ember.HTMLBars` -- `Ember.HTMLBars.template` -- `Ember.HTMLBars.compile` -- `Ember.HTMLBars.precomple` -- `Ember.Handlebars` -- `Ember.Handlebars.template` -- `Ember.Handlebars.Utils.escapeExpression` +- 🫣 `Ember.HTMLBars` +- 🫣 `Ember.HTMLBars.template` +- 🫣 `Ember.HTMLBars.compile` +- 🫣 `Ember.HTMLBars.precomple` +- 🫣 `Ember.Handlebars` +- 🫣 `Ember.Handlebars.template` +- 🫣 `Ember.Handlebars.Utils.escapeExpression` Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. -- `Ember.Handlebars.compile` -- `Ember.Handlebars.precomple` +- 🫣 `Ember.Handlebars.compile` +- 🫣 `Ember.Handlebars.precomple` @@ -206,108 +207,109 @@ Replaced by [RFC #931][RFC-931] Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascript-module-api) -| `Ember.` API | Use this instead | -| ---------- | ---------------- | -| `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | -| `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | -| `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | -| `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | -| `Ember._createCache` | `import { createCache } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | -| `Ember._cacheGetValue` | `import { getValue } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | -| `Ember._cacheIsConst` | `import { isConst } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | -| `Ember._tracked` | `import { tracked } from '@glimmer/tracking';` | -| `Ember.RSVP` | `import RSVP from 'rsvp';` | -| `Ember.guidFor` | `import { guidFor } from '@ember/object/internals';` | -| `Ember.getOwner` | `import { getOwner } from '@ember/owner';` | -| `Ember.setOwner` | `import { setOwner } from '@ember/owner';` | -| `Ember.onLoad` | `import { onLoad } from '@ember/application';` | -| `Ember.runLoadHooks` | `import { runLoadHooks } from '@ember/application';` | -| `Ember.Application` | `import Application from '@ember/application';` | -| `Ember.ApplicationInstance` | `import ApplicationInstance from '@ember/application/instance';` | -| `Ember.Namespace` | `import Namespace from '@ember/application/namespace';` | -| `Ember.A` | `import { A } from '@ember/array';` | -| `Ember.Array` | `import Array from '@ember/array';` | -| `Ember.NativeArray` | `import { NativeArray } from '@ember/array';` | -| `Ember.isArray` | `import { isArray } from '@ember/array';` | -| `Ember.makeArray` | `import { makeArray } from '@ember/array';` | -| `Ember.MutableArray` | `import MutableArray from '@ember/array/mutable';` | -| `Ember.ArrayProxy` | `import ArrayProxy from '@ember/array/proxy';` | -| `Ember._Input` | `import { Input } from '@ember/component';` | -| `Ember.Component` | `import Component from '@ember/component';` | -| `Ember.Helper` | `import Helper from '@ember/component/helper';` | -| `Ember.Controller` | `import Controller from '@ember/controller';` | -| `Ember.assert` | `import { assert } from '@ember/debug';` | -| `Ember.warn` | `import { warn } from '@ember/debug';` | -| `Ember.debug` | `import { debug } from '@ember/debug';` | -| `Ember.deprecate` | `import { deprecate } from '@ember/debug';` | -| `Ember.runInDebug` | `import { runInDebug } from '@ember/debug';` | -| `Ember.Debug.registerDeprecationHandler` | `import { registerDeprecationHandler } from '@ember/debug';` | -| `Ember.ContainerDebugAdapter` | `import ContainerDebugAdapter from '@ember/debug/container-debug-adapter';` | -| `Ember.DataAdapter` | `import DataAdapter from '@ember/debug/data-adapter';` | -| `Ember._assertDestroyablesDestroyed` | `import { assertDestroyablesDestroyed } from '@ember/destroyable';` | -| `Ember._associateDestroyableChild` | `import { associateDestroyableChild } from '@ember/destroyable';` | -| `Ember._enableDestroyableTracking` | `import { enableDestroyableTracking } from '@ember/destroyable';` | -| `Ember._isDestroying` | `import { isDestroying } from '@ember/destroyable';` | -| `Ember._isDestroyed` | `import { isDestroyed } from '@ember/destroyable';` | -| `Ember._registerDestructor` | `import { registerDestructor } from '@ember/destroyable';` | -| `Ember._unregisterDestructor` | `import { unregisterDestructor } from '@ember/destroyable';` | -| `Ember.destroy` | `import { destroy } from '@ember/destroyable';` | -| `Ember.Engine` | `import Engine from '@ember/engine';` | -| `Ember.EngineInstance` | `import Engine from '@ember/engine/instance';` | -| `Ember.Enumerable` | `import Enumerable from '@ember/enumerable';` | -| `Ember.MutableEnumerable` | `import MutableEnumerable from '@ember/enumerable/mutable';` | -| `Ember.Object` | `import Object from '@ember/object';` | -| `Ember._action` | `import { action } from '@ember/object';` | -| `Ember.computed` | `import { computed } from '@ember/object';` | -| `Ember.defineProperty` | `import { defineProperty } from '@ember/object';` | -| `Ember.get` | `import { get } from '@ember/object';` | -| `Ember.getProperties` | `import { getProperties } from '@ember/object';` | -| `Ember.notifyPropertyChange` | `import { notifyPropertyChange } from '@ember/object';` | -| `Ember.observer` | `import { observer } from '@ember/object';` | -| `Ember.set` | `import { set } from '@ember/object';` | -| `Ember.trySet` | `import { trySet } from '@ember/object';` | -| `Ember.setProperties` | `import { setProperties } from '@ember/object';` | -| `Ember._dependentKeyCompat` | `import { dependentKeyCompat } from '@ember/object/compat';` | -| `Ember.expandProperties` | `import { expandProperties } from '@ember/object/computed';` | -| `Ember.CoreObject` | `import EmberObject from '@ember/object';` | -| `Ember.Evented` | `import Evented from '@ember/object/evented';` | -| `Ember.on` | `import { on } from '@ember/object/evented';` | -| `Ember.addListener` | `import { addListener } from '@ember/object/events';` | -| `Ember.removeListener` | `import { removeListener } from '@ember/object/events';` | -| `Ember.sendEvent` | `import { sendEvent } from '@ember/object/events';` | -| `Ember.Mixin` | `import Mixin from '@ember/object/mixin';` | -| `Ember.mixin` | `import { mixin } from '@ember/object/mixin';` | -| `Ember.Observable` | `import Observable from '@ember/object/observable';` | -| `Ember.addObserver` | `import { addObserver } from '@ember/object/observers';` | -| `Ember.removeObserver` | `import { removeObserver } from '@ember/object/observers';` | -| `Ember.PromiseProxyMixin` | `import EmberPromiseProxyMixin from '@ember/object/promise-proxy-mixin';` | -| `Ember.ObjectProxy` | `import ObjectProxy from '@ember/object/proxy';` | -| `Ember.HistoryLocation` | `import HistoryLocation from '@ember/routing/history-location';` | -| `Ember.HashLocation` | `import HashLocation from '@ember/routing/hash-location';` | -| `Ember.NoneLocation` | `import NoneLocation from '@ember/routing/none-location';` | -| `Ember.Route` | `import Route from '@ember/routing/route';` | -| `Ember.run` | `import { run } from '@ember/runloop';` | -| `Ember.Service` | `import Service from '@ember/service';` | -| `Ember.compare` | `import { compare } from '@ember/utils';` | -| `Ember.isBlank` | `import { isBlank } from '@ember/utils';` | -| `Ember.isEmpty` | `import { isEmpty } from '@ember/utils';` | -| `Ember.isEqual` | `import { isEqual } from '@ember/utils';` | -| `Ember.isPresent` | `import { isPresent } from '@ember/utils';` | -| `Ember.typeOf` | `import { typeOf } from '@ember/utils';` | -| `Ember._getComponentTemplate` | `import { getComponentTemplate } from '@ember/component';` | -| `Ember._setComponentTemplate` | `import { setComponentTemplate } from '@ember/component';` | -| `Ember._helperManagerCapabilities` | `import { capabilities } from '@ember/helper';` | -| `Ember._setHelperManager` | `import { setHelperManager } from '@ember/helper';` | -| `Ember._setModifierManager` | `import { setModifierManager } from '@ember/modifier';` | -| `Ember._templateOnlyComponent` | `import templateOnly from '@ember/component/template-only';` | -| `Ember._invokeHelper` | `import { invokeHelper } from '@ember/helper';` | -| `Ember._hash` | `import { hash } from '@ember/helper';` | -| `Ember._array` | `import { array } from '@ember/helper';` | -| `Ember._concat` | `import { concat } from '@ember/helper';` | -| `Ember._get` | `import { get } from '@ember/helper';` | -| `Ember._on` | `import { on } from '@ember/modifier';` | -| `Ember._fn` | `import { fn } from '@ember/helper';` | -| `Ember.ENV` | `import MyEnv from '/config/environment';` | +| | `Ember.` API | Use this instead | +| - | ---------- | ---------------- | +|🌐 | `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | +|🌐 | `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | +|🌐 | `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | +|🌐 | `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | +|🌐 | `Ember._createCache` | `import { createCache } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +|🌐 | `Ember._cacheGetValue` | `import { getValue } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +|🌐 | `Ember._cacheIsConst` | `import { isConst } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +|🌐 | `Ember._tracked` | `import { tracked } from '@glimmer/tracking';` | +|🌐 | `Ember.RSVP` | `import RSVP from 'rsvp';` | +|🌐 | `Ember.guidFor` | `import { guidFor } from '@ember/object/internals';` | +|🌐 | `Ember.getOwner` | `import { getOwner } from '@ember/owner';` | +|🌐 | `Ember.setOwner` | `import { setOwner } from '@ember/owner';` | +|🌐 | `Ember.onLoad` | `import { onLoad } from '@ember/application';` | +|🌐 | `Ember.runLoadHooks` | `import { runLoadHooks } from '@ember/application';` | +|🌐 | `Ember.Application` | `import Application from '@ember/application';` | +|🌐 | `Ember.ApplicationInstance` | `import ApplicationInstance from '@ember/application/instance';` | +|🌐 | `Ember.Namespace` | `import Namespace from '@ember/application/namespace';` | +|🌐 | `Ember.A` | `import { A } from '@ember/array';` | +|🌐 | `Ember.Array` | `import Array from '@ember/array';` | +|🌐 | `Ember.NativeArray` | `import { NativeArray } from '@ember/array';` | +|🌐 | `Ember.isArray` | `import { isArray } from '@ember/array';` | +|🔒 | `Ember.makeArray` | `import { makeArray } from '@ember/array';` | +|🌐 | `Ember.MutableArray` | `import MutableArray from '@ember/array/mutable';` | +|🌐 | `Ember.ArrayProxy` | `import ArrayProxy from '@ember/array/proxy';` | +|🌐 | `Ember._Input` | `import { Input } from '@ember/component';` | +|🌐 | `Ember.Component` | `import Component from '@ember/component';` | +|🌐 | `Ember.Helper` | `import Helper from '@ember/component/helper';` | +|🌐 | `Ember.Controller` | `import Controller from '@ember/controller';` | +|🔒 | `Ember.ControllerMixin` | `import { ControllerMixin } from '@ember/controller';` | +|🌐 | `Ember.assert` | `import { assert } from '@ember/debug';` | +|🌐 | `Ember.warn` | `import { warn } from '@ember/debug';` | +|🌐 | `Ember.debug` | `import { debug } from '@ember/debug';` | +|🌐 | `Ember.deprecate` | `import { deprecate } from '@ember/debug';` | +|🌐 | `Ember.runInDebug` | `import { runInDebug } from '@ember/debug';` | +|🌐 | `Ember.Debug.registerDeprecationHandler` | `import { registerDeprecationHandler } from '@ember/debug';` | +|🌐 | `Ember.ContainerDebugAdapter` | `import ContainerDebugAdapter from '@ember/debug/container-debug-adapter';` | +|🌐 | `Ember.DataAdapter` | `import DataAdapter from '@ember/debug/data-adapter';` | +|🌐 | `Ember._assertDestroyablesDestroyed` | `import { assertDestroyablesDestroyed } from '@ember/destroyable';` | +|🌐 | `Ember._associateDestroyableChild` | `import { associateDestroyableChild } from '@ember/destroyable';` | +|🌐 | `Ember._enableDestroyableTracking` | `import { enableDestroyableTracking } from '@ember/destroyable';` | +|🌐 | `Ember._isDestroying` | `import { isDestroying } from '@ember/destroyable';` | +|🌐 | `Ember._isDestroyed` | `import { isDestroyed } from '@ember/destroyable';` | +|🌐 | `Ember._registerDestructor` | `import { registerDestructor } from '@ember/destroyable';` | +|🌐 | `Ember._unregisterDestructor` | `import { unregisterDestructor } from '@ember/destroyable';` | +|🌐 | `Ember.destroy` | `import { destroy } from '@ember/destroyable';` | +|🌐 | `Ember.Engine` | `import Engine from '@ember/engine';` | +|🌐 | `Ember.EngineInstance` | `import Engine from '@ember/engine/instance';` | +|🔒 | `Ember.Enumerable` | `import Enumerable from '@ember/enumerable';` | +|🔒 | `Ember.MutableEnumerable` | `import MutableEnumerable from '@ember/enumerable/mutable';` | +|🌐 | `Ember.Object` | `import Object from '@ember/object';` | +|🌐 | `Ember._action` | `import { action } from '@ember/object';` | +|🌐 | `Ember.computed` | `import { computed } from '@ember/object';` | +|🌐 | `Ember.defineProperty` | `import { defineProperty } from '@ember/object';` | +|🌐 | `Ember.get` | `import { get } from '@ember/object';` | +|🌐 | `Ember.getProperties` | `import { getProperties } from '@ember/object';` | +|🌐 | `Ember.notifyPropertyChange` | `import { notifyPropertyChange } from '@ember/object';` | +|🌐 | `Ember.observer` | `import { observer } from '@ember/object';` | +|🌐 | `Ember.set` | `import { set } from '@ember/object';` | +|🌐 | `Ember.trySet` | `import { trySet } from '@ember/object';` | +|🌐 | `Ember.setProperties` | `import { setProperties } from '@ember/object';` | +|🌐 | `Ember._dependentKeyCompat` | `import { dependentKeyCompat } from '@ember/object/compat';` | +|🌐 | `Ember.expandProperties` | `import { expandProperties } from '@ember/object/computed';` | +|🌐 | `Ember.CoreObject` | `import EmberObject from '@ember/object';` | +|🌐 | `Ember.Evented` | `import Evented from '@ember/object/evented';` | +|🌐 | `Ember.on` | `import { on } from '@ember/object/evented';` | +|🌐 | `Ember.addListener` | `import { addListener } from '@ember/object/events';` | +|🌐 | `Ember.removeListener` | `import { removeListener } from '@ember/object/events';` | +|🌐 | `Ember.sendEvent` | `import { sendEvent } from '@ember/object/events';` | +|🌐 | `Ember.Mixin` | `import Mixin from '@ember/object/mixin';` | +|🔒 | `Ember.mixin` | `import { mixin } from '@ember/object/mixin';` | +|🌐 | `Ember.Observable` | `import Observable from '@ember/object/observable';` | +|🌐 |`Ember.addObserver` | `import { addObserver } from '@ember/object/observers';` | +|🌐 | `Ember.removeObserver` | `import { removeObserver } from '@ember/object/observers';` | +|🌐 | `Ember.PromiseProxyMixin` | `import EmberPromiseProxyMixin from '@ember/object/promise-proxy-mixin';` | +|🌐 | `Ember.ObjectProxy` | `import ObjectProxy from '@ember/object/proxy';` | +|🧷 | `Ember.HistoryLocation` | `import HistoryLocation from '@ember/routing/history-location';` | +|🧷 | `Ember.HashLocation` | `import HashLocation from '@ember/routing/hash-location';` | +|🧷 | `Ember.NoneLocation` | `import NoneLocation from '@ember/routing/none-location';` | +|🌐 | `Ember.Route` | `import Route from '@ember/routing/route';` | +|🌐 | `Ember.run` | `import { run } from '@ember/runloop';` | +|🌐 | `Ember.Service` | `import Service from '@ember/service';` | +|🌐 | `Ember.compare` | `import { compare } from '@ember/utils';` | +|🌐 | `Ember.isBlank` | `import { isBlank } from '@ember/utils';` | +|🌐 | `Ember.isEmpty` | `import { isEmpty } from '@ember/utils';` | +|🌐 | `Ember.isEqual` | `import { isEqual } from '@ember/utils';` | +|🌐 | `Ember.isPresent` | `import { isPresent } from '@ember/utils';` | +|🌐 | `Ember.typeOf` | `import { typeOf } from '@ember/utils';` | +|🌐 | `Ember._getComponentTemplate` | `import { getComponentTemplate } from '@ember/component';` | +|🌐 | `Ember._setComponentTemplate` | `import { setComponentTemplate } from '@ember/component';` | +|🌐 | `Ember._helperManagerCapabilities` | `import { capabilities } from '@ember/helper';` | +|🌐 | `Ember._setHelperManager` | `import { setHelperManager } from '@ember/helper';` | +|🌐 | `Ember._setModifierManager` | `import { setModifierManager } from '@ember/modifier';` | +|🌐 | `Ember._templateOnlyComponent` | `import templateOnly from '@ember/component/template-only';` | +|🌐 | `Ember._invokeHelper` | `import { invokeHelper } from '@ember/helper';` | +|🌐 | `Ember._hash` | `import { hash } from '@ember/helper';` | +|🌐 | `Ember._array` | `import { array } from '@ember/helper';` | +|🌐 | `Ember._concat` | `import { concat } from '@ember/helper';` | +|🌐 | `Ember._get` | `import { get } from '@ember/helper';` | +|🌐 | `Ember._on` | `import { on } from '@ember/modifier';` | +|🌐 | `Ember._fn` | `import { fn } from '@ember/helper';` | +|🌐 | `Ember.ENV` | `import MyEnv from '/config/environment';` | [RFC-615]: https://rfcs.emberjs.com/id/0615-autotracking-memoization From 6c08e67ba98b916104764d20d81da72499d3adf1 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 9 Feb 2024 15:43:18 -0500 Subject: [PATCH 17/44] Update test API vis --- text/1003-deprecation-import-ember-from-ember.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index d508561293..345cb8adb7 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -53,15 +53,15 @@ Throughout the rest of this RFC, the following key will be used: - 🧷 to mean "this is protected API" - 🫣 to mean "no declared access" -### New Module Needed +### Testing utilities APIs for wiring up a test framework (e.g. QUnit, _etc_) -- `Ember.Test` -- `Ember.Test.Adapter` -- `Ember.Test.QUnitAdapter` -- `Ember.setupForTesting` +- 🌐 `Ember.Test` +- 🌐 `Ember.Test.Adapter` - currently available at [`@ember/test`](https://api.emberjs.com/ember/5.6/modules/@ember%2Ftest) +- 🌐 `Ember.Test.QUnitAdapter` +- 🌐 `Ember.setupForTesting` -These will need to be moved to a module such as `@ember/testing`. +These will need to be moved to a module such as `@ember/test`. ### A way to communicate with the ember-inspector From dd0c096230fa07fbe8f1b062e918a4dfb148d2f4 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 16 Feb 2024 12:23:18 -0500 Subject: [PATCH 18/44] Update text/1003-deprecation-import-ember-from-ember.md Co-authored-by: Alexey Kulakov --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 345cb8adb7..0703992e93 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -150,7 +150,7 @@ Utility // ... - if (macroCondition(isTesting()) { + if (macroCondition(isTesting())) { // test only code here } ``` From c17be14f1bc767d0453fbb94a031b2a194e25484 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Sat, 24 Feb 2024 18:16:02 -0500 Subject: [PATCH 19/44] Update 1003-deprecation-import-ember-from-ember.md --- text/1003-deprecation-import-ember-from-ember.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 0703992e93..adf9894867 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -39,6 +39,8 @@ This RFC proprosing deprecating all APIs that have module-based replacements, as The `import Ember from 'ember';` set of APIs is implementn as a barrel file, and properly optimizing barrel files [is a lot of work, requiring integration with build time tools](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js). +**If anyone one dependency in an app's dependency tree does `import ... from 'ember'`, every feature of the framework is shipped to your users, without any ability for you to optimize.** + By removing this set of exports, we have an opportunity to shrink some apps (as some APIs are not used), improving the load performance of ember apps -- and we removing all of these gives us a chance to have a better grasp of what we can get rid of permananently. Many of these APIs already have alternatives, and those will be called out explicitly in the _Transition Path_ below. From 95df0091960b08508bd36ae80fa6d540646d29e9 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 17:20:51 -0500 Subject: [PATCH 20/44] Start adding ember-observer searches and declarations of usage / migration for each of the APIs with no replacements --- ...003-deprecation-import-ember-from-ember.md | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index adf9894867..b4f654efb9 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -74,7 +74,7 @@ A good few already have available imports though. | | API | import | | - | --- | ------ | |🔒| `Ember.meta` | `import { meta } from '@ember/-internals/meta';` | -|🌐| `Ember.VERSION` | none | +|🌐| `Ember.VERSION` | none, we should add one, `@ember/version` | |🔒| `Ember._captureRenderTree` | `import { captureRenderTree } from '@ember/debug';` | |🔒| `Ember.instrument` | `import { instrument } from '@ember/instrumentation';` | |🔒| `Ember.subscribe` | `import { subscribe } from '@ember/instrumentation';` | @@ -100,19 +100,25 @@ import { macroCondition, isDevelopingApp, importSync } from '@embroider/macros'; if (macroCondition(isDevelopingApp())) { // maybe this is side-effecting and installs // some functions on `globalThis` that the inspector could call + // since the inspector can't import modules from a built app. importSync('@ember/inspector-support'); } ``` ### No replacements. -Applies to both the value and type exports (if applicable). +Applies to both the value and type exports (if applicable). All of these will not be re-exported from other `@ember/*` packages, but the following tables will show addon usage[^why-addon-usage] in the ecosystem and potential paths forward for library authors. -- 🫣 `Ember._getPath` -- 🫣 `Ember.isNamespace` -- 🫣 `Ember.toString` -- 🔒 `Ember.Container` -- 🔒 `Ember.Registry` +[^why-addon-usage]: Addons are notorious for doing things they shouldn't, accessing private APIs, doing crazy things so users don't have to, working around ecosystem and broader ecosystem problems etc. It's also expected that addon authors will be able to handle migrations more quickly than app devs. + + +| | API | Usage | Migration | +| - | --- | ----- | --------- | +|🫣 | `Ember._getPath` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._getPath) | n/a | +|🫣 | `Ember.isNamespace` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.isNamespace) | n/a | +|🫣 | `Ember.toString` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.toString) | n/a | +|🔒 | `Ember.Container` | EmberObserver: [Many, but old or docs](https://emberobserver.com/code-search?codeQuery=Ember.Container) | n/a | +|🔒 | `Ember.Registry` | EmberObserver: [Many, but old or docs](https://emberobserver.com/code-search?codeQuery=Ember.Registry) | n/a | Internal decorator utils - 🫣 `Ember._descriptor` @@ -136,7 +142,7 @@ Mixins Utility - 🫣 `Ember.lookup` - 🌐 `Ember.libraries` - - App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. + App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list) or [unplugin-info](https://github.com/yjl9903/unplugin-info). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. - 🫣 `Ember._Cache` - 🔒 `Ember.GUID_KEY` - 🔒 `Ember.canInvoke` @@ -165,7 +171,6 @@ Utility - 🔒 `Ember.generateGuid` - 🌐 `Ember.uuid` - 🔒 `Ember.wrap` -- 🫣 `Ember.deprecateFunc` - 🔒 `Ember.inspect` - 🫣 `Ember.Debug` Replaced by some of `@ember/debug` exports. @@ -244,6 +249,7 @@ Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascrip |🌐 | `Ember.warn` | `import { warn } from '@ember/debug';` | |🌐 | `Ember.debug` | `import { debug } from '@ember/debug';` | |🌐 | `Ember.deprecate` | `import { deprecate } from '@ember/debug';` | +|🫣 | `Ember.deprecateFunc` | `import { deprecateFunc } from '@ember/debug';` | |🌐 | `Ember.runInDebug` | `import { runInDebug } from '@ember/debug';` | |🌐 | `Ember.Debug.registerDeprecationHandler` | `import { registerDeprecationHandler } from '@ember/debug';` | |🌐 | `Ember.ContainerDebugAdapter` | `import ContainerDebugAdapter from '@ember/debug/container-debug-adapter';` | From 89a527d182e3cfd4d6d90a3bf3e9eef0f804d572 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 17:26:02 -0500 Subject: [PATCH 21/44] More tables --- text/1003-deprecation-import-ember-from-ember.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index b4f654efb9..e19debc325 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -121,13 +121,17 @@ Applies to both the value and type exports (if applicable). All of these will no |🔒 | `Ember.Registry` | EmberObserver: [Many, but old or docs](https://emberobserver.com/code-search?codeQuery=Ember.Registry) | n/a | Internal decorator utils -- 🫣 `Ember._descriptor` -- 🔒 `Ember._setClassicDecorator` +| | API | Usage | Migration | +| - | --- | ----- | --------- | +|🫣 | `Ember._descriptor` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._descriptor) | n/a | +|🔒 | `Ember._setClassicDecorator` | EmberObserver: [ember-concurrency](https://emberobserver.com/code-search?codeQuery=Ember._setClassicDecorator) | n/a | Reactivity -- 🔒 `Ember.beginPropertyChanges` -- 🔒 `Ember.changeProperties` -- 🔒 `Ember.endPropertyChanges` +| | API | Usage | Migration | +| - | --- | ----- | --------- | +|🔒 | `Ember.beginPropertyChanges` | EmberObserver: [ember-m3 + old stuff](https://emberobserver.com/code-search?codeQuery=Ember.beginPropertyChanges) | n/a | +|🔒 | `Ember.endPropertyChanges` | EmberObserver: [ember-m3 + old stuff](https://emberobserver.com/code-search?codeQuery=Ember.endPropertyChanges) | n/a | +|🔒 | `Ember.changeProperties` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.changeProperties) | n/a | Observable - 🌐 `Ember.hasListeners` From 41585ab6223a3f734a642e945a25de06a215fa92 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 17:35:42 -0500 Subject: [PATCH 22/44] Another table --- text/1003-deprecation-import-ember-from-ember.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index e19debc325..7393016d7d 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -134,7 +134,9 @@ Reactivity |🔒 | `Ember.changeProperties` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.changeProperties) | n/a | Observable -- 🌐 `Ember.hasListeners` +| | API | Usage | Migration | +| - | --- | ----- | --------- | +|🌐 | `Ember.hasListeners` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.hasListeners) | n/a | Mixins - 🔒 `Ember._ContainerProxyMixin` From c3a582c052d252b83cb5bf84204f4a5a32aafd5b Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 21:07:26 -0500 Subject: [PATCH 23/44] =?UTF-8?q?Some=20of=20these=20feel=20like=20I'm=20d?= =?UTF-8?q?irectly=20calling=20out=20certain=20libraries=20=F0=9F=99=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../1003-deprecation-import-ember-from-ember.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 7393016d7d..e445275b00 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -129,8 +129,8 @@ Internal decorator utils Reactivity | | API | Usage | Migration | | - | --- | ----- | --------- | -|🔒 | `Ember.beginPropertyChanges` | EmberObserver: [ember-m3 + old stuff](https://emberobserver.com/code-search?codeQuery=Ember.beginPropertyChanges) | n/a | -|🔒 | `Ember.endPropertyChanges` | EmberObserver: [ember-m3 + old stuff](https://emberobserver.com/code-search?codeQuery=Ember.endPropertyChanges) | n/a | +|🔒 | `Ember.beginPropertyChanges` | EmberObserver: [ember-m3 + old addons](https://emberobserver.com/code-search?codeQuery=Ember.beginPropertyChanges) | n/a | +|🔒 | `Ember.endPropertyChanges` | EmberObserver: [ember-m3 + old addons](https://emberobserver.com/code-search?codeQuery=Ember.endPropertyChanges) | n/a | |🔒 | `Ember.changeProperties` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.changeProperties) | n/a | Observable @@ -139,11 +139,14 @@ Observable |🌐 | `Ember.hasListeners` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.hasListeners) | n/a | Mixins -- 🔒 `Ember._ContainerProxyMixin` -- 🔒 `Ember._ProxyMixin` -- 🔒 `Ember._RegistryProxyMixin` -- 🔒 `Ember.ActionHandler` -- 🔒 `Ember.Comparable` +| | API | Usage | Migration | +| - | --- | ----- | --------- | +|🔒 | `Ember._ContainerProxyMixin` | EmberObserver: [mostly old addons](https://emberobserver.com/code-search?codeQuery=Ember._ContainerProxyMixin&sort=updated&sortAscending=false). Includes `ember-decorators`, `ember-data-has-many-query`, `ember-graphql-adapter`, `ember-cli-fastboot` (in tests / test-support) | n/a | +|🔒 | `Ember._RegistryProxyMixin` | EmberObserver: [mostly old addons](https://emberobserver.com/code-search?codeQuery=Ember._RegistryProxyMixin&sort=updated&sortAscending=false). Includes `ember-decorators`, `ember-data-has-many-query`, `ember-graphql-adapter`, `ember-cli-fastboot` (in tests / test-support) | n/a | +|🔒 | `Ember._ProxyMixin` | EmberObserver: [`ember-bootstrap-components`, 8 years ago](https://emberobserver.com/code-search?codeQuery=Ember._ProxyMixin&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.ActionHandler` | EmberObserver: ['ember-error-tracker' + old addons](https://emberobserver.com/code-search?codeQuery=Ember.ActionHandler&sort=updated&sortAscending=false). Many usages include pre-modules Ember usage. | n/a | +|🔒 | `Ember.Comparable` | EmberObserver: [ember-data-model-fragments](https://emberobserver.com/code-search?codeQuery=Ember.Comparable&sort=updated&sortAscending=false) | n/a | + Utility - 🫣 `Ember.lookup` From 8c9e8cded00988b84d37d1460502609ab464d50c Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 21:40:29 -0500 Subject: [PATCH 24/44] more --- ...003-deprecation-import-ember-from-ember.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index e445275b00..4b9cf211ae 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -149,16 +149,15 @@ Mixins Utility -- 🫣 `Ember.lookup` -- 🌐 `Ember.libraries` - - App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list) or [unplugin-info](https://github.com/yjl9903/unplugin-info). This additionally means that V1 libraries that pushed themselves into `Ember.libraries` no longer need to worry about interacting with this or any similar API. -- 🫣 `Ember._Cache` -- 🔒 `Ember.GUID_KEY` -- 🔒 `Ember.canInvoke` - Instead use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining): - ```js - this.foo?.method?.(); - ``` +| | API | Usage | Migration | +| - | --- | ----- | --------- | +|🫣 | `Ember.lookup` | EmberObserver: [old addons, > 6 years](https://emberobserver.com/code-search?codeQuery=Ember.lookup&sort=updated&sortAscending=false) | Use `getOwner(...).lookup` from `@ember/owner` | +|🌐 | `Ember.libraries` | EmberObserver: [Many usages, mostly ember-data and related](https://emberobserver.com/code-search?codeQuery=Ember.libraries&sort=updated&sortAscending=false) | This isn't a behavior that Ember needs to provide, nor should it be library authors' responsibilty to register themselves with a library listing system. App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list) or [unplugin-info](https://github.com/yjl9903/unplugin-info). | +|🫣 | `Ember._Cache` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._Cache&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.GUID_KEY` | EmberObserver: [`ember-data-save-relationships`, 6 years ago](https://emberobserver.com/code-search?codeQuery=Ember.GUID_KEY&sort=updated&sortAscending=false) | n/a | +| 🔒 | `Ember.canInvoke` | EmberObserver: [@summit-electric-supply](https://emberobserver.com/code-search?codeQuery=Ember.canInvoke&sort=updated&sortAscending=false) | use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining), e.g.: `this.foo?.method?.()` | + + - 🫣 `Ember.testing` Instead, use From 95b5d48d27332a831ff937f8033fbc403d10af23 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 21:55:00 -0500 Subject: [PATCH 25/44] More --- ...003-deprecation-import-ember-from-ember.md | 66 ++++++++++--------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 4b9cf211ae..481b8a8e38 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -151,43 +151,25 @@ Mixins Utility | | API | Usage | Migration | | - | --- | ----- | --------- | -|🫣 | `Ember.lookup` | EmberObserver: [old addons, > 6 years](https://emberobserver.com/code-search?codeQuery=Ember.lookup&sort=updated&sortAscending=false) | Use `getOwner(...).lookup` from `@ember/owner` | +|🫣 | `Ember.lookup` | EmberObserver: [old addons, > 6 years](https://emberobserver.com/code-search?codeQuery=Ember.lookup&sort=updated&sortAscending=false) | Use `getOwner(...).lookup` from [`@ember/owner`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fowner/getOwner) | |🌐 | `Ember.libraries` | EmberObserver: [Many usages, mostly ember-data and related](https://emberobserver.com/code-search?codeQuery=Ember.libraries&sort=updated&sortAscending=false) | This isn't a behavior that Ember needs to provide, nor should it be library authors' responsibilty to register themselves with a library listing system. App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list) or [unplugin-info](https://github.com/yjl9903/unplugin-info). | |🫣 | `Ember._Cache` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._Cache&sort=updated&sortAscending=false) | n/a | |🔒 | `Ember.GUID_KEY` | EmberObserver: [`ember-data-save-relationships`, 6 years ago](https://emberobserver.com/code-search?codeQuery=Ember.GUID_KEY&sort=updated&sortAscending=false) | n/a | | 🔒 | `Ember.canInvoke` | EmberObserver: [@summit-electric-supply](https://emberobserver.com/code-search?codeQuery=Ember.canInvoke&sort=updated&sortAscending=false) | use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining), e.g.: `this.foo?.method?.()` | +|🔒 | `Ember.generateGuid` | EmberObserver: [`ember-flexberry + old addons](https://emberobserver.com/code-search?codeQuery=Ember.generateGuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | +|🌐 | `Ember.uuid` | EmberObserver: [3 recent addons](https://emberobserver.com/code-search?codeQuery=Ember.uuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | +|🔒 | `Ember.wrap` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.wrap&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.inspect` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.inspect&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.Debug` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.Debug&sort=updated&sortAscending=false) | use [`@ember/debug`](https://api.emberjs.com/ember/5.6/modules/@ember%2Fdebug) | +|🫣 | `Ember.cacheFor` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.cacheFor&sort=updated&sortAscending=false) | potentially [`@glimmer/tracking/primitives/cache`](https://api.emberjs.com/ember/5.6/modules/@glimmer%2Ftracking%2Fprimitives%2Fcache) | +|🌐 | `Ember.ComputedProperty` | EmberObserver: [aside from docs, old addons](https://emberobserver.com/code-search?codeQuery=Ember.ComputedProperty&sort=updated&sortAscending=false). Most recent usage is 3 years ago in `ember-cli-furnance-validation` | n/a | +|🫣 | `Ember.RouterDSL` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.RouterDSL&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.controllerFor` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.controllerFor&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.generateController` | EmberObserver: [bitbird-core-ember-routing, 5 years ago](https://emberobserver.com/code-search?codeQuery=Ember.generateController&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.generateControllerFactory` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.generateControllerFactory&sort=updated&sortAscending=false) | n/a | - -- 🫣 `Ember.testing` - Instead, use - - ```js - import { macroCondition, isTesting } from '@embroider/macros'; - - // ... - - if (macroCondition(isTesting())) { - // test only code here - } - ``` - -- 🌐 `Ember.onerror` - Instead use an event listener for the `error` event on window. - ```js - window.addEventListener('error', /* ... event handler ... */); - ``` -- 🔒 `Ember.generateGuid` -- 🌐 `Ember.uuid` -- 🔒 `Ember.wrap` -- 🔒 `Ember.inspect` -- 🫣 `Ember.Debug` - Replaced by some of `@ember/debug` exports. -- 🫣 `Ember.cacheFor` -- 🌐 `Ember.ComputedProperty` -- 🫣 `Ember.RouterDSL` -- 🔒 `Ember.controllerFor` -- 🔒 `Ember.generateController` -- 🔒 `Ember.generateControllerFactory` +| | API | Usage | Migration | +| - | --- | ----- | --------- | - 🌐 `Ember.VERSION` This has the ember version in it, but it could be converted to a virtual module to import from somewhere. - 🔒 `Ember._Backburner` @@ -200,6 +182,8 @@ Utility - 🔒 `Ember.TEMPLATES` Replaced by [RFC #931][RFC-931] +| | API | Usage | Migration | +| - | --- | ----- | --------- | - 🫣 `Ember.HTMLBars` - 🫣 `Ember.HTMLBars.template` - 🫣 `Ember.HTMLBars.compile` @@ -212,6 +196,24 @@ Replaced by [RFC #931][RFC-931] - 🫣 `Ember.Handlebars.precomple` +- 🫣 `Ember.testing` + Instead, use + + ```js + import { macroCondition, isTesting } from '@embroider/macros'; + + // ... + + if (macroCondition(isTesting())) { + // test only code here + } + ``` + +- 🌐 `Ember.onerror` + Instead use an event listener for the `error` event on window. + ```js + window.addEventListener('error', /* ... event handler ... */); + ``` [RFC-931]: https://github.com/emberjs/rfcs/pull/931 From 1175306f0cc1c695a267904b08fdd70a77b1a4c9 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 22:44:00 -0500 Subject: [PATCH 26/44] Almost done --- ...003-deprecation-import-ember-from-ember.md | 23 +++++++++++-------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 481b8a8e38..63f128e96f 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -170,16 +170,19 @@ Utility | | API | Usage | Migration | | - | --- | ----- | --------- | -- 🌐 `Ember.VERSION` - This has the ember version in it, but it could be converted to a virtual module to import from somewhere. -- 🔒 `Ember._Backburner` -- 🌐 `Ember.inject` -- 🫣 `Ember.__loader` -- 🫣 `Ember.__loader.require` -- 🫣 `Ember.__loader.define` -- 🫣 `Ember.__loader.registry` -- 🔒 `Ember.BOOTED` -- 🔒 `Ember.TEMPLATES` +|🌐 | `Ember.VERSION` | EmberObserver: [Not many usages](https://emberobserver.com/code-search?codeQuery=Ember.VERSION&sort=updated&sortAscending=false). | This has the ember version in it, but it could be converted to a virtual module to import from somewhere, such as `@ember/version` | +|🔒 | `Ember._Backburner` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._Backburner&sort=updated&sortAscending=false) | n/a | +|🌐 | `Ember.inject` | EmberObserver: [Many, all using classic classes](https://emberobserver.com/code-search?codeQuery=Ember.inject&sort=updated&sortAscending=false). A lot of results are also classic-class docs. | Use [`@service`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fservice/service) | + +Any projects using these are already not safe for embroider and won't work with Vite +| | API | Usage | Migration | +| - | --- | ----- | --------- | +|🫣 | `Ember.__loader` | EmberObserver: [159 addons. Some experimental. Most from `@ascua`](https://emberobserver.com/code-search?codeQuery=Ember.__loader&sort=updated&sortAscending=false) | n/a | +| 🫣 | `Ember.__loader.require` | EmberObserver: [same as `Ember.__loader`](https://emberobserver.com/code-search?codeQuery=Ember.__loader.require&sort=updated&sortAscending=false) | n/a | +| 🫣 | `Ember.__loader.define` | EmberObserver: [5 addons, ~2 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.define&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | +|🫣 | `Ember.__loader.registry` | EmberObserver: [13 addons, ~5 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.registry&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | +|🔒 | `Ember.BOOTED` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.BOOTED&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.TEMPLATES` | EmberObserver: [`ember-resolver`](https://emberobserver.com/code-search?codeQuery=Ember.TEMPLATES&sort=updated&sortAscending=false) | n/a | Replaced by [RFC #931][RFC-931] | | API | Usage | Migration | From 4aca297be395f3ae9990211aa905927cb893581e Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Tue, 27 Feb 2024 22:59:20 -0500 Subject: [PATCH 27/44] done --- ...003-deprecation-import-ember-from-ember.md | 128 +++++++++--------- 1 file changed, 66 insertions(+), 62 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 63f128e96f..347d30f6cc 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -58,10 +58,13 @@ Throughout the rest of this RFC, the following key will be used: ### Testing utilities APIs for wiring up a test framework (e.g. QUnit, _etc_) -- 🌐 `Ember.Test` -- 🌐 `Ember.Test.Adapter` - currently available at [`@ember/test`](https://api.emberjs.com/ember/5.6/modules/@ember%2Ftest) -- 🌐 `Ember.Test.QUnitAdapter` -- 🌐 `Ember.setupForTesting` + +| | API | Usage: EmberObserver | -- | +| - | --- | ----- | -- | +|🌐 | `Ember.Test` | [A good few](https://emberobserver.com/code-search?codeQuery=Ember.Test&sort=updated&sortAscending=false) | | +|🌐 | `Ember.Test.Adapter` | [`ember-cli-fastboot` and `@ember/test-helpers`](https://emberobserver.com/code-search?codeQuery=Ember.Test.Adapter&sort=updated&sortAscending=false) | currently available at [`@ember/test`](https://api.emberjs.com/ember/5.6/modules/@ember%2Ftest) | +|🌐 | `Ember.Test.QUnitAdapter` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.Test.QUnitAdapter&sort=updated&sortAscending=false) | | +|🌐 | `Ember.setupForTesting` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.setupForTesting&sort=updated&sortAscending=false) | | These will need to be moved to a module such as `@ember/test`. @@ -112,93 +115,94 @@ Applies to both the value and type exports (if applicable). All of these will no [^why-addon-usage]: Addons are notorious for doing things they shouldn't, accessing private APIs, doing crazy things so users don't have to, working around ecosystem and broader ecosystem problems etc. It's also expected that addon authors will be able to handle migrations more quickly than app devs. -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | -|🫣 | `Ember._getPath` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._getPath) | n/a | -|🫣 | `Ember.isNamespace` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.isNamespace) | n/a | -|🫣 | `Ember.toString` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.toString) | n/a | -|🔒 | `Ember.Container` | EmberObserver: [Many, but old or docs](https://emberobserver.com/code-search?codeQuery=Ember.Container) | n/a | -|🔒 | `Ember.Registry` | EmberObserver: [Many, but old or docs](https://emberobserver.com/code-search?codeQuery=Ember.Registry) | n/a | +|🫣 | `Ember._getPath` | [None](https://emberobserver.com/code-search?codeQuery=Ember._getPath) | n/a | +|🫣 | `Ember.isNamespace` | [None](https://emberobserver.com/code-search?codeQuery=Ember.isNamespace) | n/a | +|🫣 | `Ember.toString` | [None](https://emberobserver.com/code-search?codeQuery=Ember.toString) | n/a | +|🔒 | `Ember.Container` | [Many, but old or docs](https://emberobserver.com/code-search?codeQuery=Ember.Container) | n/a | +|🔒 | `Ember.Registry` | [Many, but old or docs](https://emberobserver.com/code-search?codeQuery=Ember.Registry) | n/a | Internal decorator utils -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | |🫣 | `Ember._descriptor` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._descriptor) | n/a | |🔒 | `Ember._setClassicDecorator` | EmberObserver: [ember-concurrency](https://emberobserver.com/code-search?codeQuery=Ember._setClassicDecorator) | n/a | Reactivity -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | -|🔒 | `Ember.beginPropertyChanges` | EmberObserver: [ember-m3 + old addons](https://emberobserver.com/code-search?codeQuery=Ember.beginPropertyChanges) | n/a | -|🔒 | `Ember.endPropertyChanges` | EmberObserver: [ember-m3 + old addons](https://emberobserver.com/code-search?codeQuery=Ember.endPropertyChanges) | n/a | -|🔒 | `Ember.changeProperties` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.changeProperties) | n/a | +|🔒 | `Ember.beginPropertyChanges` | [ember-m3 + old addons](https://emberobserver.com/code-search?codeQuery=Ember.beginPropertyChanges) | n/a | +|🔒 | `Ember.endPropertyChanges` | [ember-m3 + old addons](https://emberobserver.com/code-search?codeQuery=Ember.endPropertyChanges) | n/a | +|🔒 | `Ember.changeProperties` | [None](https://emberobserver.com/code-search?codeQuery=Ember.changeProperties) | n/a | Observable -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | -|🌐 | `Ember.hasListeners` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.hasListeners) | n/a | +|🌐 | `Ember.hasListeners` | [None](https://emberobserver.com/code-search?codeQuery=Ember.hasListeners) | n/a | Mixins -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | -|🔒 | `Ember._ContainerProxyMixin` | EmberObserver: [mostly old addons](https://emberobserver.com/code-search?codeQuery=Ember._ContainerProxyMixin&sort=updated&sortAscending=false). Includes `ember-decorators`, `ember-data-has-many-query`, `ember-graphql-adapter`, `ember-cli-fastboot` (in tests / test-support) | n/a | -|🔒 | `Ember._RegistryProxyMixin` | EmberObserver: [mostly old addons](https://emberobserver.com/code-search?codeQuery=Ember._RegistryProxyMixin&sort=updated&sortAscending=false). Includes `ember-decorators`, `ember-data-has-many-query`, `ember-graphql-adapter`, `ember-cli-fastboot` (in tests / test-support) | n/a | -|🔒 | `Ember._ProxyMixin` | EmberObserver: [`ember-bootstrap-components`, 8 years ago](https://emberobserver.com/code-search?codeQuery=Ember._ProxyMixin&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.ActionHandler` | EmberObserver: ['ember-error-tracker' + old addons](https://emberobserver.com/code-search?codeQuery=Ember.ActionHandler&sort=updated&sortAscending=false). Many usages include pre-modules Ember usage. | n/a | -|🔒 | `Ember.Comparable` | EmberObserver: [ember-data-model-fragments](https://emberobserver.com/code-search?codeQuery=Ember.Comparable&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember._ContainerProxyMixin` | [mostly old addons](https://emberobserver.com/code-search?codeQuery=Ember._ContainerProxyMixin&sort=updated&sortAscending=false). Includes `ember-decorators`, `ember-data-has-many-query`, `ember-graphql-adapter`, `ember-cli-fastboot` (in tests / test-support) | n/a | +|🔒 | `Ember._RegistryProxyMixin` | [mostly old addons](https://emberobserver.com/code-search?codeQuery=Ember._RegistryProxyMixin&sort=updated&sortAscending=false). Includes `ember-decorators`, `ember-data-has-many-query`, `ember-graphql-adapter`, `ember-cli-fastboot` (in tests / test-support) | n/a | +|🔒 | `Ember._ProxyMixin` | [`ember-bootstrap-components`, 8 years ago](https://emberobserver.com/code-search?codeQuery=Ember._ProxyMixin&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.ActionHandler` | ['ember-error-tracker' + old addons](https://emberobserver.com/code-search?codeQuery=Ember.ActionHandler&sort=updated&sortAscending=false). Many usages include pre-modules Ember usage. | n/a | +|🔒 | `Ember.Comparable` | [ember-data-model-fragments](https://emberobserver.com/code-search?codeQuery=Ember.Comparable&sort=updated&sortAscending=false) | n/a | Utility -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | -|🫣 | `Ember.lookup` | EmberObserver: [old addons, > 6 years](https://emberobserver.com/code-search?codeQuery=Ember.lookup&sort=updated&sortAscending=false) | Use `getOwner(...).lookup` from [`@ember/owner`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fowner/getOwner) | -|🌐 | `Ember.libraries` | EmberObserver: [Many usages, mostly ember-data and related](https://emberobserver.com/code-search?codeQuery=Ember.libraries&sort=updated&sortAscending=false) | This isn't a behavior that Ember needs to provide, nor should it be library authors' responsibilty to register themselves with a library listing system. App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list) or [unplugin-info](https://github.com/yjl9903/unplugin-info). | -|🫣 | `Ember._Cache` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._Cache&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.GUID_KEY` | EmberObserver: [`ember-data-save-relationships`, 6 years ago](https://emberobserver.com/code-search?codeQuery=Ember.GUID_KEY&sort=updated&sortAscending=false) | n/a | -| 🔒 | `Ember.canInvoke` | EmberObserver: [@summit-electric-supply](https://emberobserver.com/code-search?codeQuery=Ember.canInvoke&sort=updated&sortAscending=false) | use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining), e.g.: `this.foo?.method?.()` | -|🔒 | `Ember.generateGuid` | EmberObserver: [`ember-flexberry + old addons](https://emberobserver.com/code-search?codeQuery=Ember.generateGuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | -|🌐 | `Ember.uuid` | EmberObserver: [3 recent addons](https://emberobserver.com/code-search?codeQuery=Ember.uuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | -|🔒 | `Ember.wrap` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.wrap&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.inspect` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.inspect&sort=updated&sortAscending=false) | n/a | -|🫣 | `Ember.Debug` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.Debug&sort=updated&sortAscending=false) | use [`@ember/debug`](https://api.emberjs.com/ember/5.6/modules/@ember%2Fdebug) | -|🫣 | `Ember.cacheFor` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.cacheFor&sort=updated&sortAscending=false) | potentially [`@glimmer/tracking/primitives/cache`](https://api.emberjs.com/ember/5.6/modules/@glimmer%2Ftracking%2Fprimitives%2Fcache) | -|🌐 | `Ember.ComputedProperty` | EmberObserver: [aside from docs, old addons](https://emberobserver.com/code-search?codeQuery=Ember.ComputedProperty&sort=updated&sortAscending=false). Most recent usage is 3 years ago in `ember-cli-furnance-validation` | n/a | -|🫣 | `Ember.RouterDSL` | EmberObserver: [old addons](https://emberobserver.com/code-search?codeQuery=Ember.RouterDSL&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.controllerFor` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.controllerFor&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.generateController` | EmberObserver: [bitbird-core-ember-routing, 5 years ago](https://emberobserver.com/code-search?codeQuery=Ember.generateController&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.generateControllerFactory` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.generateControllerFactory&sort=updated&sortAscending=false) | n/a | - -| | API | Usage | Migration | +|🫣 | `Ember.lookup` | [old addons, > 6 years](https://emberobserver.com/code-search?codeQuery=Ember.lookup&sort=updated&sortAscending=false) | Use `getOwner(...).lookup` from [`@ember/owner`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fowner/getOwner) | +|🌐 | `Ember.libraries` | [Many usages, mostly ember-data and related](https://emberobserver.com/code-search?codeQuery=Ember.libraries&sort=updated&sortAscending=false) | This isn't a behavior that Ember needs to provide, nor should it be library authors' responsibilty to register themselves with a library listing system. App authors could choose to use any webpack or other build plugin that collections this information, such as [webpack-node-modules-list](https://github.com/ubilabs/webpack-node-modules-list) or [unplugin-info](https://github.com/yjl9903/unplugin-info). | +|🫣 | `Ember._Cache` | [None](https://emberobserver.com/code-search?codeQuery=Ember._Cache&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.GUID_KEY` | [`ember-data-save-relationships`, 6 years ago](https://emberobserver.com/code-search?codeQuery=Ember.GUID_KEY&sort=updated&sortAscending=false) | n/a | +| 🔒 | `Ember.canInvoke` | [@summit-electric-supply](https://emberobserver.com/code-search?codeQuery=Ember.canInvoke&sort=updated&sortAscending=false) | use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining), e.g.: `this.foo?.method?.()` | +|🔒 | `Ember.generateGuid` | [`ember-flexberry + old addons](https://emberobserver.com/code-search?codeQuery=Ember.generateGuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | +|🌐 | `Ember.uuid` | [3 recent addons](https://emberobserver.com/code-search?codeQuery=Ember.uuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | +|🔒 | `Ember.wrap` | [None](https://emberobserver.com/code-search?codeQuery=Ember.wrap&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.inspect` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.inspect&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.Debug` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.Debug&sort=updated&sortAscending=false) | use [`@ember/debug`](https://api.emberjs.com/ember/5.6/modules/@ember%2Fdebug) | +|🫣 | `Ember.cacheFor` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.cacheFor&sort=updated&sortAscending=false) | potentially [`@glimmer/tracking/primitives/cache`](https://api.emberjs.com/ember/5.6/modules/@glimmer%2Ftracking%2Fprimitives%2Fcache) | +|🌐 | `Ember.ComputedProperty` | [aside from docs, old addons](https://emberobserver.com/code-search?codeQuery=Ember.ComputedProperty&sort=updated&sortAscending=false). Most recent usage is 3 years ago in `ember-cli-furnance-validation` | n/a | +|🫣 | `Ember.RouterDSL` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.RouterDSL&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.controllerFor` | [None](https://emberobserver.com/code-search?codeQuery=Ember.controllerFor&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.generateController` | [bitbird-core-ember-routing, 5 years ago](https://emberobserver.com/code-search?codeQuery=Ember.generateController&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.generateControllerFactory` | [None](https://emberobserver.com/code-search?codeQuery=Ember.generateControllerFactory&sort=updated&sortAscending=false) | n/a | + +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | |🌐 | `Ember.VERSION` | EmberObserver: [Not many usages](https://emberobserver.com/code-search?codeQuery=Ember.VERSION&sort=updated&sortAscending=false). | This has the ember version in it, but it could be converted to a virtual module to import from somewhere, such as `@ember/version` | |🔒 | `Ember._Backburner` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember._Backburner&sort=updated&sortAscending=false) | n/a | |🌐 | `Ember.inject` | EmberObserver: [Many, all using classic classes](https://emberobserver.com/code-search?codeQuery=Ember.inject&sort=updated&sortAscending=false). A lot of results are also classic-class docs. | Use [`@service`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fservice/service) | Any projects using these are already not safe for embroider and won't work with Vite -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | -|🫣 | `Ember.__loader` | EmberObserver: [159 addons. Some experimental. Most from `@ascua`](https://emberobserver.com/code-search?codeQuery=Ember.__loader&sort=updated&sortAscending=false) | n/a | -| 🫣 | `Ember.__loader.require` | EmberObserver: [same as `Ember.__loader`](https://emberobserver.com/code-search?codeQuery=Ember.__loader.require&sort=updated&sortAscending=false) | n/a | -| 🫣 | `Ember.__loader.define` | EmberObserver: [5 addons, ~2 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.define&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | -|🫣 | `Ember.__loader.registry` | EmberObserver: [13 addons, ~5 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.registry&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | -|🔒 | `Ember.BOOTED` | EmberObserver: [None](https://emberobserver.com/code-search?codeQuery=Ember.BOOTED&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.TEMPLATES` | EmberObserver: [`ember-resolver`](https://emberobserver.com/code-search?codeQuery=Ember.TEMPLATES&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.__loader` | [159 addons. Some experimental. Most from `@ascua`](https://emberobserver.com/code-search?codeQuery=Ember.__loader&sort=updated&sortAscending=false) | n/a | +| 🫣 | `Ember.__loader.require` | [same as `Ember.__loader`](https://emberobserver.com/code-search?codeQuery=Ember.__loader.require&sort=updated&sortAscending=false) | n/a | +| 🫣 | `Ember.__loader.define` | [5 addons, ~2 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.define&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | +|🫣 | `Ember.__loader.registry` | [13 addons, ~5 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.registry&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | +|🔒 | `Ember.BOOTED` | [None](https://emberobserver.com/code-search?codeQuery=Ember.BOOTED&sort=updated&sortAscending=false) | n/a | +|🔒 | `Ember.TEMPLATES` | [`ember-resolver`](https://emberobserver.com/code-search?codeQuery=Ember.TEMPLATES&sort=updated&sortAscending=false) | n/a | Replaced by [RFC #931][RFC-931] -| | API | Usage | Migration | +| | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | -- 🫣 `Ember.HTMLBars` -- 🫣 `Ember.HTMLBars.template` -- 🫣 `Ember.HTMLBars.compile` -- 🫣 `Ember.HTMLBars.precomple` -- 🫣 `Ember.Handlebars` -- 🫣 `Ember.Handlebars.template` -- 🫣 `Ember.Handlebars.Utils.escapeExpression` - Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. -- 🫣 `Ember.Handlebars.compile` -- 🫣 `Ember.Handlebars.precomple` - - +|🫣 | `Ember.HTMLBars` | [Lots of usage (encompasses the below APIs)](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.HTMLBars.DOMHelper` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars.DOMHelper&sort=updated&sortAscending=false) uses `protocolForURL`, `parseHTML` | n/a | +|🫣 | `Ember.HTMLBars.template` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars.template&sort=updated&sortAscending=false) (and `ember-ast-hot-load`) | n/a | +|🫣 | `Ember.HTMLBars.compile` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars.compile&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.HTMLBars.precomple` | [`ember-ast-hot-load`](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars.precompile&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.Handlebars` | [174 addons, mostly @ascua](https://emberobserver.com/code-search?codeQuery=Ember.Handlebars&sort=updated&sortAscending=false) and also a lot of mentions in docs. | n/a | +|🫣 | `Ember.Handlebars.template` | [None](https://emberobserver.com/code-search?codeQuery=Ember.Handlebars.template&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.Handlebars.Utils.escapeExpression` | [100 addons, mostly @ascua](https://emberobserver.com/code-search?codeQuery=Ember.Handlebars.Utils.escapeExpression&sort=updated&sortAscending=false) | Removed in [ember.js PR#20360](https://github.com/emberjs/ember.js/pull/20360) as it is not public API. | +|🫣 | `Ember.Handlebars.compile` | [`ember-cli-fastboot` and `ember-collection`](https://emberobserver.com/code-search?codeQuery=Ember.Handlebars.compile&sort=updated&sortAscending=false) | n/a | +|🫣 | `Ember.Handlebars.precomple` | [None](https://emberobserver.com/code-search?codeQuery=Ember.Handlebars.precompile&sort=updated&sortAscending=false) | n/a | + + +Other APIs - 🫣 `Ember.testing` Instead, use From 396cba0dfcfb93f86c38738ecc1ea7a685a29710 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 1 Mar 2024 10:50:27 -0500 Subject: [PATCH 28/44] Start addign usages for the public API that does have alternative imports --- text/1003-deprecation-import-ember-from-ember.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 347d30f6cc..0337597f0d 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -231,9 +231,9 @@ Other APIs Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascript-module-api) -| | `Ember.` API | Use this instead | -| - | ---------- | ---------------- | -|🌐 | `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | +| | `Ember.` API | Use this instead | Usage: EmberObserver | +| - | ------------ | ---------------- | -------------------- | +|🌐 | `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | [@ember-data & @busy-web](https://emberobserver.com/code-search?codeQuery=Ember.FEATURES&sort=updated&sortAscending=false) | |🌐 | `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | |🌐 | `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | |🌐 | `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | From c95c83db0348c0f9092a54a0ac1d5e5da1793dd8 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 1 Mar 2024 11:01:32 -0500 Subject: [PATCH 29/44] oof --- ...003-deprecation-import-ember-from-ember.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 0337597f0d..a600e2f71c 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -234,20 +234,20 @@ Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascrip | | `Ember.` API | Use this instead | Usage: EmberObserver | | - | ------------ | ---------------- | -------------------- | |🌐 | `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | [@ember-data & @busy-web](https://emberobserver.com/code-search?codeQuery=Ember.FEATURES&sort=updated&sortAscending=false) | -|🌐 | `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | -|🌐 | `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | -|🌐 | `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | -|🌐 | `Ember._createCache` | `import { createCache } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | -|🌐 | `Ember._cacheGetValue` | `import { getValue } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | -|🌐 | `Ember._cacheIsConst` | `import { isConst } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | -|🌐 | `Ember._tracked` | `import { tracked } from '@glimmer/tracking';` | -|🌐 | `Ember.RSVP` | `import RSVP from 'rsvp';` | -|🌐 | `Ember.guidFor` | `import { guidFor } from '@ember/object/internals';` | -|🌐 | `Ember.getOwner` | `import { getOwner } from '@ember/owner';` | -|🌐 | `Ember.setOwner` | `import { setOwner } from '@ember/owner';` | -|🌐 | `Ember.onLoad` | `import { onLoad } from '@ember/application';` | -|🌐 | `Ember.runLoadHooks` | `import { runLoadHooks } from '@ember/application';` | -|🌐 | `Ember.Application` | `import Application from '@ember/application';` | +|🌐 | `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | [None](https://emberobserver.com/code-search?codeQuery=Ember._setComponentManager&sort=updated&sortAscending=false) | +|🌐 | `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | [None](https://emberobserver.com/code-search?codeQuery=Ember._componentManagerCapabilities&sort=updated&sortAscending=false) +|🌐 | `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | [ember-modifier-manager-polyfill](https://emberobserver.com/code-search?codeQuery=Ember._modifierManagerCapabilities&sort=updated&sortAscending=false) +|🌐 | `Ember._createCache` | `import { createCache } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | [None](https://emberobserver.com/code-search?codeQuery=Ember._createCache&sort=updated&sortAscending=false) +|🌐 | `Ember._cacheGetValue` | `import { getValue } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | [None](https://emberobserver.com/code-search?codeQuery=Ember._cacheGetValue&sort=updated&sortAscending=false) +|🌐 | `Ember._cacheIsConst` | `import { isConst } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | [None](https://emberobserver.com/code-search?codeQuery=Ember._cacheIsConst&sort=updated&sortAscending=false) +|🌐 | `Ember._tracked` | `import { tracked } from '@glimmer/tracking';` | [ember-custom-elements and ember-custom-elements-patch](https://emberobserver.com/code-search?codeQuery=Ember._tracked&sort=updated&sortAscending=false) +|🌐 | `Ember.RSVP` | `import RSVP from 'rsvp';` | [290 addons, less than 50 updated in the last 5 years](https://emberobserver.com/code-search?codeQuery=Ember.RSVP&sort=updated&sortAscending=false) +|🌐 | `Ember.guidFor` | `import { guidFor } from '@ember/object/internals';` | [ember-cli-fastboot, ember-flexberry-gjs](https://emberobserver.com/code-search?codeQuery=Ember.guidFor&sort=updated&sortAscending=false) everything else is older than 5 years. | +|🌐 | `Ember.getOwner` | `import { getOwner } from '@ember/owner';` | [ember-cli-fastboot, flexberry(-gjs)](https://emberobserver.com/code-search?codeQuery=Ember.getOwner&sort=updated&sortAscending=false). @summit-electric-supply, @eflexsystems, ember-tether, etc. +|🌐 | `Ember.setOwner` | `import { setOwner } from '@ember/owner';` | [ember-cli-fastboot](https://emberobserver.com/code-search?codeQuery=Ember.setOwner&sort=updated&sortAscending=false), everything else is more than 5 years old. +|🌐 | `Ember.onLoad` | `import { onLoad } from '@ember/application';` | [None](https://emberobserver.com/code-search?codeQuery=Ember.onLoad&sort=updated&sortAscending=false). Everything is more than 5 years old. +|🌐 | `Ember.runLoadHooks` | `import { runLoadHooks } from '@ember/application';` | [ember-new-modules-shim (7 years ago)](https://emberobserver.com/code-search?codeQuery=Ember.runLoadHooks&sort=updated&sortAscending=false) +|🌐 | `Ember.Application` | `import Application from '@ember/application';` | [1756 addons](https://emberobserver.com/code-search?codeQuery=Ember.Application&sort=updated&sortAscending=false), some results are docs, many are test suites, some are types. `ember-cli-fastboot` uses the value to `reopen`. |🌐 | `Ember.ApplicationInstance` | `import ApplicationInstance from '@ember/application/instance';` | |🌐 | `Ember.Namespace` | `import Namespace from '@ember/application/namespace';` | |🌐 | `Ember.A` | `import { A } from '@ember/array';` | From 6db09caca0fa17b1266688ed10f59bb40d41ca50 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 1 Mar 2024 15:22:50 -0500 Subject: [PATCH 30/44] Minor updates --- ...1003-deprecation-import-ember-from-ember.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index a600e2f71c..16cc473ff5 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -159,8 +159,9 @@ Utility |🫣 | `Ember._Cache` | [None](https://emberobserver.com/code-search?codeQuery=Ember._Cache&sort=updated&sortAscending=false) | n/a | |🔒 | `Ember.GUID_KEY` | [`ember-data-save-relationships`, 6 years ago](https://emberobserver.com/code-search?codeQuery=Ember.GUID_KEY&sort=updated&sortAscending=false) | n/a | | 🔒 | `Ember.canInvoke` | [@summit-electric-supply](https://emberobserver.com/code-search?codeQuery=Ember.canInvoke&sort=updated&sortAscending=false) | use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining), e.g.: `this.foo?.method?.()` | -|🔒 | `Ember.generateGuid` | [`ember-flexberry + old addons](https://emberobserver.com/code-search?codeQuery=Ember.generateGuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | -|🌐 | `Ember.uuid` | [3 recent addons](https://emberobserver.com/code-search?codeQuery=Ember.uuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) | +|🔒 | `Ember.generateGuid` | [`ember-flexberry + old addons](https://emberobserver.com/code-search?codeQuery=Ember.generateGuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) or the browser-native [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | + +|🌐 | `Ember.uuid` | [3 recent addons](https://emberobserver.com/code-search?codeQuery=Ember.uuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) or the browser-native [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | |🔒 | `Ember.wrap` | [None](https://emberobserver.com/code-search?codeQuery=Ember.wrap&sort=updated&sortAscending=false) | n/a | |🔒 | `Ember.inspect` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.inspect&sort=updated&sortAscending=false) | n/a | |🫣 | `Ember.Debug` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.Debug&sort=updated&sortAscending=false) | use [`@ember/debug`](https://api.emberjs.com/ember/5.6/modules/@ember%2Fdebug) | @@ -185,11 +186,13 @@ Any projects using these are already not safe for embroider and won't work with | 🫣 | `Ember.__loader.define` | [5 addons, ~2 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.define&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | |🫣 | `Ember.__loader.registry` | [13 addons, ~5 recent](https://emberobserver.com/code-search?codeQuery=Ember.__loader.registry&sort=updated&sortAscending=false). One is `ember-cli-fastboot` (tests, test-support). | n/a | |🔒 | `Ember.BOOTED` | [None](https://emberobserver.com/code-search?codeQuery=Ember.BOOTED&sort=updated&sortAscending=false) | n/a | -|🔒 | `Ember.TEMPLATES` | [`ember-resolver`](https://emberobserver.com/code-search?codeQuery=Ember.TEMPLATES&sort=updated&sortAscending=false) | n/a | -Replaced by [RFC #931][RFC-931] + +Replaced by [RFC #931][RFC-931]. +For scenarios where folks would like to compile templates at runtime, see [RFC #931][RFC-931] or the code of [ember-repl](https://www.npmjs.com/package/ember-repl). | | API | Usage: EmberObserver | Migration | | - | --- | ----- | --------- | +|🔒 | `Ember.TEMPLATES` | [`ember-resolver`](https://emberobserver.com/code-search?codeQuery=Ember.TEMPLATES&sort=updated&sortAscending=false) | n/a | |🫣 | `Ember.HTMLBars` | [Lots of usage (encompasses the below APIs)](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars&sort=updated&sortAscending=false) | n/a | |🫣 | `Ember.HTMLBars.DOMHelper` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars.DOMHelper&sort=updated&sortAscending=false) uses `protocolForURL`, `parseHTML` | n/a | |🫣 | `Ember.HTMLBars.template` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.HTMLBars.template&sort=updated&sortAscending=false) (and `ember-ast-hot-load`) | n/a | @@ -339,6 +342,8 @@ Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascrip [RFC-615]: https://rfcs.emberjs.com/id/0615-autotracking-memoization +## What to do about things that don't have replacements + ## How We Teach This The guides already use the modern imports where available. @@ -354,6 +359,11 @@ Available Codemods - https://github.com/ember-codemods/ember-modules-codemod (from the work of RFC 176) +## Depracation Guide + +- Separate ids for each API so that folks don't have to scroll too far to get to their migration path (if a migration path exists). +- Mostly using the above tables, but without the `Usage: EmberObserver` column. + ## Drawbacks n/a, to be more module-friendly, we must get rid of the `'ember'` import. From 654fc1f65c02ead2b8f1fa246f588399259003b8 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 4 Mar 2024 08:48:52 -0500 Subject: [PATCH 31/44] Add implementation plan, which summarizes all the tables --- ...003-deprecation-import-ember-from-ember.md | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 16cc473ff5..4946fe3114 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -342,7 +342,23 @@ Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascrip [RFC-615]: https://rfcs.emberjs.com/id/0615-autotracking-memoization -## What to do about things that don't have replacements +## Implementation Plan + +These can happen in any order + +- Add deprecations to each `Ember.*` access +- Add the [Testing utilities](#testing-utilities) to `@ember/test` +- Add an `@ember/version` package to `ember-source` +- Update ember-inspector to use imports for the internals and instrumentation APIs +- Add `@ember/inspector-support` to `ember-source` to manage things like `LIBRARIES`. + ```js + import { libraries } from '@ember/inspector-support'; + + libraries.add('ember-data', '5.3.1'); + // and/or + libraries.addAll(depInfoFromPlugin); + ``` +- Add deprecation guide entries for each API ## How We Teach This @@ -359,7 +375,7 @@ Available Codemods - https://github.com/ember-codemods/ember-modules-codemod (from the work of RFC 176) -## Depracation Guide +## Deprecation Guide - Separate ids for each API so that folks don't have to scroll too far to get to their migration path (if a migration path exists). - Mostly using the above tables, but without the `Usage: EmberObserver` column. From 82f2c34ca594f0e8b83c7c4ba1a0a87b8ef0c6f2 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 4 Mar 2024 08:50:17 -0500 Subject: [PATCH 32/44] Add implementation plan, which summarizes all the tables --- text/1003-deprecation-import-ember-from-ember.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 4946fe3114..4da37ccaeb 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -349,6 +349,8 @@ These can happen in any order - Add deprecations to each `Ember.*` access - Add the [Testing utilities](#testing-utilities) to `@ember/test` - Add an `@ember/version` package to `ember-source` +- Add re-exports of private APIs, `ComputedProperty`, and `_setClassicDecorator` + These will still be deprecated on `Ember.`, and will be deprecated themselves as we progress through deprecating Ember Classic. - Update ember-inspector to use imports for the internals and instrumentation APIs - Add `@ember/inspector-support` to `ember-source` to manage things like `LIBRARIES`. ```js From 769bf6f9a15c70f7dac630204d65b415db1214fa Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 8 Mar 2024 14:16:14 -0500 Subject: [PATCH 33/44] Remove redundant ember observer links --- ...003-deprecation-import-ember-from-ember.md | 42 ++++++++++--------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 4da37ccaeb..f4b33d161f 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -234,26 +234,28 @@ Other APIs Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascript-module-api) -| | `Ember.` API | Use this instead | Usage: EmberObserver | -| - | ------------ | ---------------- | -------------------- | -|🌐 | `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | [@ember-data & @busy-web](https://emberobserver.com/code-search?codeQuery=Ember.FEATURES&sort=updated&sortAscending=false) | -|🌐 | `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | [None](https://emberobserver.com/code-search?codeQuery=Ember._setComponentManager&sort=updated&sortAscending=false) | -|🌐 | `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | [None](https://emberobserver.com/code-search?codeQuery=Ember._componentManagerCapabilities&sort=updated&sortAscending=false) -|🌐 | `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | [ember-modifier-manager-polyfill](https://emberobserver.com/code-search?codeQuery=Ember._modifierManagerCapabilities&sort=updated&sortAscending=false) -|🌐 | `Ember._createCache` | `import { createCache } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | [None](https://emberobserver.com/code-search?codeQuery=Ember._createCache&sort=updated&sortAscending=false) -|🌐 | `Ember._cacheGetValue` | `import { getValue } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | [None](https://emberobserver.com/code-search?codeQuery=Ember._cacheGetValue&sort=updated&sortAscending=false) -|🌐 | `Ember._cacheIsConst` | `import { isConst } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | [None](https://emberobserver.com/code-search?codeQuery=Ember._cacheIsConst&sort=updated&sortAscending=false) -|🌐 | `Ember._tracked` | `import { tracked } from '@glimmer/tracking';` | [ember-custom-elements and ember-custom-elements-patch](https://emberobserver.com/code-search?codeQuery=Ember._tracked&sort=updated&sortAscending=false) -|🌐 | `Ember.RSVP` | `import RSVP from 'rsvp';` | [290 addons, less than 50 updated in the last 5 years](https://emberobserver.com/code-search?codeQuery=Ember.RSVP&sort=updated&sortAscending=false) -|🌐 | `Ember.guidFor` | `import { guidFor } from '@ember/object/internals';` | [ember-cli-fastboot, ember-flexberry-gjs](https://emberobserver.com/code-search?codeQuery=Ember.guidFor&sort=updated&sortAscending=false) everything else is older than 5 years. | -|🌐 | `Ember.getOwner` | `import { getOwner } from '@ember/owner';` | [ember-cli-fastboot, flexberry(-gjs)](https://emberobserver.com/code-search?codeQuery=Ember.getOwner&sort=updated&sortAscending=false). @summit-electric-supply, @eflexsystems, ember-tether, etc. -|🌐 | `Ember.setOwner` | `import { setOwner } from '@ember/owner';` | [ember-cli-fastboot](https://emberobserver.com/code-search?codeQuery=Ember.setOwner&sort=updated&sortAscending=false), everything else is more than 5 years old. -|🌐 | `Ember.onLoad` | `import { onLoad } from '@ember/application';` | [None](https://emberobserver.com/code-search?codeQuery=Ember.onLoad&sort=updated&sortAscending=false). Everything is more than 5 years old. -|🌐 | `Ember.runLoadHooks` | `import { runLoadHooks } from '@ember/application';` | [ember-new-modules-shim (7 years ago)](https://emberobserver.com/code-search?codeQuery=Ember.runLoadHooks&sort=updated&sortAscending=false) -|🌐 | `Ember.Application` | `import Application from '@ember/application';` | [1756 addons](https://emberobserver.com/code-search?codeQuery=Ember.Application&sort=updated&sortAscending=false), some results are docs, many are test suites, some are types. `ember-cli-fastboot` uses the value to `reopen`. -|🌐 | `Ember.ApplicationInstance` | `import ApplicationInstance from '@ember/application/instance';` | -|🌐 | `Ember.Namespace` | `import Namespace from '@ember/application/namespace';` | -|🌐 | `Ember.A` | `import { A } from '@ember/array';` | +Unless otherwise state, there will not be usage-based decision on these, as they all exist under available imports today. + +| | `Ember.` API | Use this instead | +| - | ------------ | ---------------- | +|🌐 | `Ember.FEATURES` | `import { isEnabled, FEATURES } from '@ember/canary-features';` | +|🌐 | `Ember._setComponentManager` | `import { setComponentManager } from '@ember/component';` | +|🌐 | `Ember._componentManagerCapabilities` | `import { capabilities } from '@ember/component';` | +|🌐 | `Ember._modifierManagerCapabilities` | `import { capabilities } from '@ember/modifier';` | +|🌐 | `Ember._createCache` | `import { createCache } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +|🌐 | `Ember._cacheGetValue` | `import { getValue } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +|🌐 | `Ember._cacheIsConst` | `import { isConst } from '@glimmer/tracking/primitives/cache';` [RFC #615][RFC-615] | +|🌐 | `Ember._tracked` | `import { tracked } from '@glimmer/tracking';` | +|🌐 | `Ember.RSVP` | `import RSVP from 'rsvp';` | +|🌐 | `Ember.guidFor` | `import { guidFor } from '@ember/object/internals';` | +|🌐 | `Ember.getOwner` | `import { getOwner } from '@ember/owner';` | +|🌐 | `Ember.setOwner` | `import { setOwner } from '@ember/owner';` | +|🌐 | `Ember.onLoad` | `import { onLoad } from '@ember/application';` | +|🌐 | `Ember.runLoadHooks` | `import { runLoadHooks } from '@ember/application';` | +|🌐 | `Ember.Application` | `import Application from '@ember/application';` | +|🌐 | `Ember.ApplicationInstance` | `import ApplicationInstance from '@ember/application/instance';` | +|🌐 | `Ember.Namespace` | `import Namespace from '@ember/application/namespace';` | +|🌐 | `Ember.A` | `import { A } from '@ember/array';` | |🌐 | `Ember.Array` | `import Array from '@ember/array';` | |🌐 | `Ember.NativeArray` | `import { NativeArray } from '@ember/array';` | |🌐 | `Ember.isArray` | `import { isArray } from '@ember/array';` | From b30f25d17a87aca9d3c70decfff4d0d097171e8f Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 8 Mar 2024 14:31:55 -0500 Subject: [PATCH 34/44] fix typo --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index f4b33d161f..e28d173302 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -234,7 +234,7 @@ Other APIs Most of this is covered in [RFC #176](https://rfcs.emberjs.com/id/0176-javascript-module-api) -Unless otherwise state, there will not be usage-based decision on these, as they all exist under available imports today. +Unless otherwise stated, there will not be usage-based decision on these, as they all exist under available imports today. | | `Ember.` API | Use this instead | | - | ------------ | ---------------- | From da9406fb19dca2f2cdcbb6fda8c33c4fcc8864ff Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 8 Mar 2024 14:38:12 -0500 Subject: [PATCH 35/44] Specify 'if needed' for tests --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index e28d173302..7f7c56a1cf 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -66,7 +66,7 @@ APIs for wiring up a test framework (e.g. QUnit, _etc_) |🌐 | `Ember.Test.QUnitAdapter` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.Test.QUnitAdapter&sort=updated&sortAscending=false) | | |🌐 | `Ember.setupForTesting` | [`ember-cli-fastboot`](https://emberobserver.com/code-search?codeQuery=Ember.setupForTesting&sort=updated&sortAscending=false) | | -These will need to be moved to a module such as `@ember/test`. +If needed, these will need to be moved to a module such as `@ember/test`. ### A way to communicate with the ember-inspector From 6582892dfa1b8de7f7bd1d94f1d98bbf4dfa36bc Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 8 Mar 2024 14:46:00 -0500 Subject: [PATCH 36/44] Add another if needed --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 7f7c56a1cf..173964a449 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -349,7 +349,7 @@ Unless otherwise stated, there will not be usage-based decision on these, as the These can happen in any order - Add deprecations to each `Ember.*` access -- Add the [Testing utilities](#testing-utilities) to `@ember/test` +- Add the [Testing utilities](#testing-utilities) to `@ember/test`, if needed. - Add an `@ember/version` package to `ember-source` - Add re-exports of private APIs, `ComputedProperty`, and `_setClassicDecorator` These will still be deprecated on `Ember.`, and will be deprecated themselves as we progress through deprecating Ember Classic. From 48739a2b893008ca593943918ba9c2bdb1e88c38 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 8 Mar 2024 14:47:18 -0500 Subject: [PATCH 37/44] Add note about env --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 173964a449..d52629dba4 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -339,7 +339,7 @@ Unless otherwise stated, there will not be usage-based decision on these, as the |🌐 | `Ember._get` | `import { get } from '@ember/helper';` | |🌐 | `Ember._on` | `import { on } from '@ember/modifier';` | |🌐 | `Ember._fn` | `import { fn } from '@ember/helper';` | -|🌐 | `Ember.ENV` | `import MyEnv from '/config/environment';` | +|🌐 | `Ember.ENV` | `import MyEnv from '/config/environment';` (for apps) or `owner.resolveRegistration('config:environment')` for addons| [RFC-615]: https://rfcs.emberjs.com/id/0615-autotracking-memoization From 8967d1cfeaa97c394c8d67a285e938c5ff5880d4 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 8 Mar 2024 14:48:49 -0500 Subject: [PATCH 38/44] Fix table --- text/1003-deprecation-import-ember-from-ember.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index d52629dba4..c098d3bf0c 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -160,7 +160,6 @@ Utility |🔒 | `Ember.GUID_KEY` | [`ember-data-save-relationships`, 6 years ago](https://emberobserver.com/code-search?codeQuery=Ember.GUID_KEY&sort=updated&sortAscending=false) | n/a | | 🔒 | `Ember.canInvoke` | [@summit-electric-supply](https://emberobserver.com/code-search?codeQuery=Ember.canInvoke&sort=updated&sortAscending=false) | use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining), e.g.: `this.foo?.method?.()` | |🔒 | `Ember.generateGuid` | [`ember-flexberry + old addons](https://emberobserver.com/code-search?codeQuery=Ember.generateGuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) or the browser-native [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | - |🌐 | `Ember.uuid` | [3 recent addons](https://emberobserver.com/code-search?codeQuery=Ember.uuid&sort=updated&sortAscending=false) | Use [`guidFor`](https://api.emberjs.com/ember/5.6/functions/@ember%2Fobject%2Finternals/guidFor) or [`uuid`](https://www.npmjs.com/package/uuid) or the browser-native [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | |🔒 | `Ember.wrap` | [None](https://emberobserver.com/code-search?codeQuery=Ember.wrap&sort=updated&sortAscending=false) | n/a | |🔒 | `Ember.inspect` | [old addons](https://emberobserver.com/code-search?codeQuery=Ember.inspect&sort=updated&sortAscending=false) | n/a | From 5b368188da25eb1711780c3d8568bdbc9bdb7e0e Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 8 Mar 2024 14:54:18 -0500 Subject: [PATCH 39/44] Answer the unresolved question --- text/1003-deprecation-import-ember-from-ember.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index c098d3bf0c..f590454099 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -395,4 +395,5 @@ n/a n/a -Do our instrumentation and internals sub-packages have any SemVer guarantees? Or are we allowed to "do what we need to" and not care about _public-facing_ SemVer? +Q: Do our instrumentation and internals sub-packages have any SemVer guarantees? Or are we allowed to "do what we need to" and not care about _public-facing_ SemVer? +A: If something is privately but heavily used, we will try to deprecate before removing the API and make sure the deprecation makes it in to an LTS before that removal. From 42ac1e286248bcb77a17920ce85d225dbfd482e0 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 15 Mar 2024 14:28:46 -0400 Subject: [PATCH 40/44] mention get/set onerror --- text/1003-deprecation-import-ember-from-ember.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index f590454099..282962b32e 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -224,6 +224,12 @@ Other APIs window.addEventListener('error', /* ... event handler ... */); ``` + If you really need the original behavior: + ```js + import { getOnerror, setOnerror } from '@ember/-internals/error-handling'; + ``` + But this should not be needed. + [RFC-931]: https://github.com/emberjs/rfcs/pull/931 From d55470b68e64f7277ef80ca657330a348f6809c8 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 15 Mar 2024 14:29:54 -0400 Subject: [PATCH 41/44] Mention unhandledrejection --- text/1003-deprecation-import-ember-from-ember.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 282962b32e..83de59534b 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -224,6 +224,12 @@ Other APIs window.addEventListener('error', /* ... event handler ... */); ``` + For promise rejections, you'll want to use the `unhandledrejection` event. + ```js + window.addEventListener('unhandledrejection', /* ... event handler ... */); + ``` + + If you really need the original behavior: ```js import { getOnerror, setOnerror } from '@ember/-internals/error-handling'; From 6352cda71a8f41425f76f733300454761c692ed8 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 15 Mar 2024 14:48:42 -0400 Subject: [PATCH 42/44] @ember/-internals now public --- text/1003-deprecation-import-ember-from-ember.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index 83de59534b..b3708c3a21 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -28,7 +28,6 @@ prs: project-link: Leave as is --> -<-- Replace "RFC title" with the title of your RFC --> # Deprecate `import Ember from 'ember'; ## Summary @@ -219,7 +218,7 @@ Other APIs ``` - 🌐 `Ember.onerror` - Instead use an event listener for the `error` event on window. + Instead you may be able to use an event listener for the `error` event on window. ```js window.addEventListener('error', /* ... event handler ... */); ``` @@ -377,6 +376,12 @@ These can happen in any order ## How We Teach This +While `@ember/-internals` were created to be internal, introducing new names for them would create churn and would make it harder for addon authors to support a wide range of versions. The internals paths all work today on supported releases, so dropping the deprecated usage doesn't reduce your support matrix, whereas using a newly-introduced import path would. + +_All `@ember/-internals(/*)?` APIs (as mentioned above) are now public API, and to remove any of those APIs, they will need to go through the deprecation process._ + +------------ + The guides already use the modern imports where available. There is a place that needs updating, around advanced debugging, where folks configure Backburner to be in debug mode. @@ -401,7 +406,7 @@ n/a, to be more module-friendly, we must get rid of the `'ember'` import. ## Alternatives -n/a +Don't use `@ember/-internals` and create new public APIs for all of the things currently under `@ember/-internals`. This would create a lot of churn in the ecosystem, when we want to get rid of some of these APIs anyway. ## Unresolved questions From 17e3778c528427592141e2546a0e0cab2e9b2cd1 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 15 Mar 2024 16:24:59 -0400 Subject: [PATCH 43/44] VERSION has an import --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index b3708c3a21..fdeab856aa 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -76,7 +76,7 @@ A good few already have available imports though. | | API | import | | - | --- | ------ | |🔒| `Ember.meta` | `import { meta } from '@ember/-internals/meta';` | -|🌐| `Ember.VERSION` | none, we should add one, `@ember/version` | +|🌐| `Ember.VERSION` | `import { VERSION } from '@ember/version';` | |🔒| `Ember._captureRenderTree` | `import { captureRenderTree } from '@ember/debug';` | |🔒| `Ember.instrument` | `import { instrument } from '@ember/instrumentation';` | |🔒| `Ember.subscribe` | `import { subscribe } from '@ember/instrumentation';` | From b8b7975af6c50dae213b7f79d8ed10bf4e786aad Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 22 Mar 2024 14:10:29 -0400 Subject: [PATCH 44/44] Update text/1003-deprecation-import-ember-from-ember.md Co-authored-by: Katie Gengler --- text/1003-deprecation-import-ember-from-ember.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1003-deprecation-import-ember-from-ember.md b/text/1003-deprecation-import-ember-from-ember.md index fdeab856aa..560eee2f70 100644 --- a/text/1003-deprecation-import-ember-from-ember.md +++ b/text/1003-deprecation-import-ember-from-ember.md @@ -378,7 +378,7 @@ These can happen in any order While `@ember/-internals` were created to be internal, introducing new names for them would create churn and would make it harder for addon authors to support a wide range of versions. The internals paths all work today on supported releases, so dropping the deprecated usage doesn't reduce your support matrix, whereas using a newly-introduced import path would. -_All `@ember/-internals(/*)?` APIs (as mentioned above) are now public API, and to remove any of those APIs, they will need to go through the deprecation process._ +_All `@ember/-internals(/*)?` APIs mentioned above are now public API, and to remove any of those APIs, they will need to go through the deprecation process._ ------------