From 11c536fba243e935836c778e3ce38ec64f9b1b58 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Tue, 23 Oct 2018 10:29:59 -0400 Subject: [PATCH 01/10] Deprecate string api --- ...precate-component-manager-string-lookup.md | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 text/0000-deprecate-component-manager-string-lookup.md diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md new file mode 100644 index 0000000000..6631e6376d --- /dev/null +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -0,0 +1,90 @@ +- Start Date: 2018-10-23 +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# Summary + +This deprecates the string based lookup API for associating a custom component manager with a corresponding base class. + +```js +import EmberObject from '@ember/object'; +import { setComponentManager } from '@ember/component'; + +export default setComponentManager('basic', EmberObject.extend({ + //... +})) +``` + +Instead the you must pass a factory function that produces a instance of the custom manager: + +```js +import EmberObject from '@ember/object'; +import { createManager } from './basic-manager'; +import { setComponentManager } from '@ember/modifier'; + +export default setComponentManager(createManager, EmberObject.extend({ + // ... +})); +``` + +Where `createManager` is: + +```js +export function createManager(owner) { + return new BasicManager(owner); +} +``` + +# Motivation + +There are several motivators: + +- A string based API is not friendly when it comes to tree shaking. Would force us into creating a compiler to turn the string into a symbol that build tools like Rollup and Webpack could analyze. +- This API expands the namespacing problems associated with module unification. Specifically an addon author would have to associate the package name with the string, similar to how [RFC#367](https://github.com/mixonic/rfcs/blob/mu-packages/text/0000-module-unification-packages.md#explicit-packages-for-service-injections) proposes changes to services. +- `setModifierManager` as introduced by [RFC#373](https://github.com/emberjs/rfcs/blob/89349d30ade24303a06448bc121b8fd810cbe58d/text/0373-Element-Modifier-Managers.md#determining-which-modifier-manager-to-use) uses a factory style API. This RFC intends to align these to function signatures. +- We want to make sure this API is compatible with the binary AoT compilation work we did in the Glimmer-VM. + +# Transition Path + +We can transition away by producing a factory function in the internals of `setupComponentManager`. The implementation would look something like: + +```js +export function setComponentManager(stringOrFunction, obj: any) { + let factory; + if (typeof stringOrFunction === 'string') { + deprecate( + `Passing the name of the component manager to 'setupComponentManager' is deprecated. Please pass a function that produces an instance of the manager.`, + { + id: 'deprecate-string-based-component-manager', + unil: '4.0.0' + } + ); + factory = function(owner: Owner) { + return owner.lookup(`component-manager:${stringOrFunction}`); + }; + } else { + factory = stringOrFunction; + } + + // ... +} + +``` + +# How We Teach This + +From our understanding this API has very limited usage as it is a low-level API. We should update that docs accordingly. + +# Drawbacks + +Historically, Ember has given developers base classes that the developer would extend from and Ember would create on your behalf. This allows the framework know that the interface of the object is complete. With this approach we are relying more on the the addon author to be responsible for the construction of the object and that it conforms to the correct interface. + +Generally speaking this a good practice of OOP but due to the fact that JavaScript does not have first-class interfaces, Ember has taken the concretion approach. + +# Alternatives + +Instead of passing a factory function we could pass the class it's self. This option does have the issue of Ember needed to know how to construct the class and does not allow for the addon author to perform any dependency injections. + +# Unresolved questions + +TBD? From b00b66090fd9a0d91e6a30c7ef07b2ba98e894a0 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Tue, 23 Oct 2018 10:41:54 -0400 Subject: [PATCH 02/10] Update 0000-deprecate-component-manager-string-lookup.md --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index 6631e6376d..18ab774934 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -15,7 +15,7 @@ export default setComponentManager('basic', EmberObject.extend({ })) ``` -Instead the you must pass a factory function that produces a instance of the custom manager: +Instead you must pass a factory function that produces a instance of the custom manager: ```js import EmberObject from '@ember/object'; From b88c71a6d95ed6a1d30e0c597194a805ddaf1821 Mon Sep 17 00:00:00 2001 From: Chad Hietala Date: Tue, 23 Oct 2018 10:44:45 -0400 Subject: [PATCH 03/10] Update 0000-deprecate-component-manager-string-lookup.md --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index 18ab774934..c420084e27 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -77,7 +77,7 @@ From our understanding this API has very limited usage as it is a low-level API. # Drawbacks -Historically, Ember has given developers base classes that the developer would extend from and Ember would create on your behalf. This allows the framework know that the interface of the object is complete. With this approach we are relying more on the the addon author to be responsible for the construction of the object and that it conforms to the correct interface. +Historically, Ember has given developers base classes that the developer would extend from and Ember would create on your behalf. This allows the framework know that the interface of the object is complete. With this approach we are relying more on the addon author to construct the object and ensure it conforms to the correct interface. Generally speaking this a good practice of OOP but due to the fact that JavaScript does not have first-class interfaces, Ember has taken the concretion approach. From b165af4fe80e3c615876339e43dd7f42bf0e96c3 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 23 Oct 2018 11:03:01 -0400 Subject: [PATCH 04/10] Update text/0000-deprecate-component-manager-string-lookup.md Co-Authored-By: chadhietala --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index c420084e27..47c5520da7 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -4,7 +4,7 @@ # Summary -This deprecates the string based lookup API for associating a custom component manager with a corresponding base class. +This deprecates the string-based lookup API for associating a custom component manager with a corresponding base class. ```js import EmberObject from '@ember/object'; From 1add010f4d8d702545661f176f3e17d3c961d863 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 23 Oct 2018 11:03:07 -0400 Subject: [PATCH 05/10] Update text/0000-deprecate-component-manager-string-lookup.md Co-Authored-By: chadhietala --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index 47c5520da7..752fe826af 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -1,5 +1,5 @@ - Start Date: 2018-10-23 -- RFC PR: (leave this empty) +- RFC PR: https://github.com/emberjs/rfcs/pull/392 - Ember Issue: (leave this empty) # Summary From 96da64fcd2bea70f72899d2c61c4f67517bbfef8 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 23 Oct 2018 11:03:11 -0400 Subject: [PATCH 06/10] Update text/0000-deprecate-component-manager-string-lookup.md Co-Authored-By: chadhietala --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index 752fe826af..b3542905bf 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -15,7 +15,7 @@ export default setComponentManager('basic', EmberObject.extend({ })) ``` -Instead you must pass a factory function that produces a instance of the custom manager: +Instead, you must pass a factory function that produces an instance of the custom manager: ```js import EmberObject from '@ember/object'; From dbce41c19d1923a01ad4fa6ce85cb2907aeb13ce Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 23 Oct 2018 11:03:15 -0400 Subject: [PATCH 07/10] Update text/0000-deprecate-component-manager-string-lookup.md Co-Authored-By: chadhietala --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index b3542905bf..bdba05bad8 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -39,7 +39,7 @@ export function createManager(owner) { There are several motivators: -- A string based API is not friendly when it comes to tree shaking. Would force us into creating a compiler to turn the string into a symbol that build tools like Rollup and Webpack could analyze. +- A string-based API is not friendly when it comes to tree shaking. It would force us into creating a compiler to turn the string into a symbol that build tools like Rollup and Webpack could analyze. - This API expands the namespacing problems associated with module unification. Specifically an addon author would have to associate the package name with the string, similar to how [RFC#367](https://github.com/mixonic/rfcs/blob/mu-packages/text/0000-module-unification-packages.md#explicit-packages-for-service-injections) proposes changes to services. - `setModifierManager` as introduced by [RFC#373](https://github.com/emberjs/rfcs/blob/89349d30ade24303a06448bc121b8fd810cbe58d/text/0373-Element-Modifier-Managers.md#determining-which-modifier-manager-to-use) uses a factory style API. This RFC intends to align these to function signatures. - We want to make sure this API is compatible with the binary AoT compilation work we did in the Glimmer-VM. From 7c71322931cbf121890d3536257ab1a907ca6e6c Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 23 Oct 2018 11:03:19 -0400 Subject: [PATCH 08/10] Update text/0000-deprecate-component-manager-string-lookup.md Co-Authored-By: chadhietala --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index bdba05bad8..c1e0fa454d 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -40,7 +40,7 @@ export function createManager(owner) { There are several motivators: - A string-based API is not friendly when it comes to tree shaking. It would force us into creating a compiler to turn the string into a symbol that build tools like Rollup and Webpack could analyze. -- This API expands the namespacing problems associated with module unification. Specifically an addon author would have to associate the package name with the string, similar to how [RFC#367](https://github.com/mixonic/rfcs/blob/mu-packages/text/0000-module-unification-packages.md#explicit-packages-for-service-injections) proposes changes to services. +- This API expands the namespacing problems associated with module unification. Specifically, an addon author would have to associate the package name with the string, similar to how [RFC#367](https://github.com/mixonic/rfcs/blob/mu-packages/text/0000-module-unification-packages.md#explicit-packages-for-service-injections) proposes changes to services. - `setModifierManager` as introduced by [RFC#373](https://github.com/emberjs/rfcs/blob/89349d30ade24303a06448bc121b8fd810cbe58d/text/0373-Element-Modifier-Managers.md#determining-which-modifier-manager-to-use) uses a factory style API. This RFC intends to align these to function signatures. - We want to make sure this API is compatible with the binary AoT compilation work we did in the Glimmer-VM. From b1a8c0c25485960aa860df49996e9062c2bb8998 Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 23 Oct 2018 11:03:23 -0400 Subject: [PATCH 09/10] Update text/0000-deprecate-component-manager-string-lookup.md Co-Authored-By: chadhietala --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index c1e0fa454d..b84192f05f 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -77,7 +77,7 @@ From our understanding this API has very limited usage as it is a low-level API. # Drawbacks -Historically, Ember has given developers base classes that the developer would extend from and Ember would create on your behalf. This allows the framework know that the interface of the object is complete. With this approach we are relying more on the addon author to construct the object and ensure it conforms to the correct interface. +Historically, Ember has given developers base classes that the developer would extend from and Ember would create instances on your behalf. This allows the framework to know that the interface of the object is complete. With this approach we are relying more on the addon author to construct the object and ensure it conforms to the correct interface. Generally speaking this a good practice of OOP but due to the fact that JavaScript does not have first-class interfaces, Ember has taken the concretion approach. From c851af7747d67c9fcead1fde25d79aba2fcd066f Mon Sep 17 00:00:00 2001 From: Ricardo Mendes Date: Tue, 23 Oct 2018 11:03:28 -0400 Subject: [PATCH 10/10] Update text/0000-deprecate-component-manager-string-lookup.md Co-Authored-By: chadhietala --- text/0000-deprecate-component-manager-string-lookup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-component-manager-string-lookup.md b/text/0000-deprecate-component-manager-string-lookup.md index b84192f05f..89ffc172f3 100644 --- a/text/0000-deprecate-component-manager-string-lookup.md +++ b/text/0000-deprecate-component-manager-string-lookup.md @@ -83,7 +83,7 @@ Generally speaking this a good practice of OOP but due to the fact that JavaScri # Alternatives -Instead of passing a factory function we could pass the class it's self. This option does have the issue of Ember needed to know how to construct the class and does not allow for the addon author to perform any dependency injections. +Instead of passing a factory function we could pass the class itself. This option does have the issue of Ember needing to know how to construct the class and does not allow for the addon author to perform any dependency injections. # Unresolved questions