From 93083150cfce30f49a6a75d768cf94152010ff68 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 31 Oct 2018 18:40:13 -0700 Subject: [PATCH 01/30] port from gist --- text/0000-ember-data-packages.md | 199 +++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 text/0000-ember-data-packages.md diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md new file mode 100644 index 0000000000..afb7b8770c --- /dev/null +++ b/text/0000-ember-data-packages.md @@ -0,0 +1,199 @@ +- Start Date: (fill me in with today's date, 2018-10-31) +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# Ember Data Packages + +## Summary + +This documents presents the proposed **public** import path changes for `ember-data`. + How *exactly* we re-align any internals is informed but not determined by this. + +## Motivation + + * Unify import location `import { Model } from 'ember-data'` or `import Model from 'ember-data/model'` ? + * Drop the concept of a single `DS` namespace + * Unlock the potential to enable end users to drop unneeded portions of ember-data + +## Detailed design + +### @ember-data/model + + * Model: `import { Model } from '@ember-data/model';` + * replaces: `import { Model } from 'ember-data';` + * replaces: `import Model from 'ember-data/model;` + * attr + * replaces: `import { attr } from 'ember-data'` + * replaces: `import attr from 'ember-data/attr';` + * `import { attr } from '@ember-data/model';` + * belongsTo + * replaces: `import { belongsTo } from 'ember-data'` + * replaces: `import belongsTo from 'ember-data/belongsTo';` + * `import { belongsTo } from '@ember-data/model';` + * hasMany + * replaces: `import { hasMany } from 'ember-data'` + * replaces: `import hasMany from 'ember-data/hasMany';` + * `import { hasMany } from '@ember-data/model';` + * Errors + * we will deprecate directly importing this class + * replaces: `import { Errors } from 'ember-data'` + * `import Errors from '@ember-data/model/errors';` + * PromiseManyArray + * we will deprecate directly importing this class + * replaces: `import { PromiseManyArray } from 'ember-data'` + * `import PromiseManyArray from '@ember-data/model/promise-many-array';` + * ManyArray + * we will deprecate directly importing this class + * replaces: `import { ManyArray } from 'ember-data'` + * `import ManyArray from '@ember-data/model/many-array';` + * `@private` InternalModel + * we will deprecate directly importing this class + * replaces: `import { ManyArray } from 'ember-data'` + * `import ManyArray from '@ember-data/model/-private/internal-model';` + * `@private` RootState + * we will deprecate directly importing this class + * replaces: `import { RootState } from 'ember-data'` + * `import RootState from '@ember-data/model/-private/root-state';` + +**Unresolved Questions** + + 1) `InternalModel` and `RootState` are tightly coupled to the store and to our provided `Model` + implementation. Overtime we need to uncouple this, but given their coupling to `Model` and our + desire to enable them to be eliminated from projects not using `Model`, I believe these exports + belong here. + + 2) Do the following belong in `@ember-data/model`, or in `@ember-data/relationship-layer`? + if not with relationships, does the package name "relationship-layer" become confusing? + + The argument for them being here is they are far more related to the current `Model` ui + presentation layer than they are to the state book-keeping which could be used with + alternative implementations. + + * `belongsTo` + * `hasMany` + * `PromiseManyArray` + * `ManyArray` + +### @ember-data/adapter + + * DS.Adapter + * DS.RESTAdapter + * DS.JSONAPIAdapter + * DS.BuildURLMixin + * DS.AdapterError + * DS.InvalidError + * DS.TimeoutError + * DS.AbortError + * DS.UnauthorizedError + * DS.ForbiddenError + * DS.NotFoundError + * DS.ConflictError + * DS.ServerError + * (public deprecate) DS.errorsHashToArray + * (public deprecate) DS.errorsArrayToHash + +### @ember-data/serializer + + * DS.Serializer + * DS.RESTSerializer + * DS.JSONSerializer + * DS.JSONAPISerializer + * DS.Transform + * DS.DateTransform + * DS.StringTransform + * DS.NumberTransform + * DS.BooleanTransform + * DS.EmbeddedRecordsMixin + +### @ember-data/store + + * DS.Store + * (deprecate-access) DS.PromiseArray + * (deprecate-access) DS.PromiseObject + * DS.Snapshot + * (deprecate-access) DS.RecordArray + * (deprecate-access) DS.AdapterPopulatedRecordArray + * (private deprecate-access) DS.RecordArrayManager + * (private deprecate-access) DS._initializeStoreService + * (private deprecate-access) DS._setupContainer + * (deprecate) normalizeModelName + +**Unresolved Questions** + + 1) _setupContainer registers various adapters and serializers for fallbacks. + Either we need to deprecate this behavior (preferred), or separate out initialization + by package, or both. It also eagerly injects store, which we should deprecate but + can't until there is a `defaultStore` RFC for ember itself. + + 2) _initializeStoreService eagerly instantiates the store to ensure that `defaultStore` is our store. + we should get rid of this but can't until there is a `defaultStore` RFC for ember itself. + + 3) normalizeModelName is defined... very oddly. Why? Also we should probably deprecate this + and continue to move to a world in which less normalization of modelName is required. + +### @ember-data/relationship-layer + + * (private deprecate) DS.Relationship + +**Notes** + +This package seems thin but it's likely to hold quite a bit. + Additional private things that would be moved here: + everything in `-private/system/relationships/state` + logic from `internal-model` that need to be extracted + +### @ember-data/debug + + * DS.DebugAdapter + +**Notes** + + Moving this here would allow dropping it. I already suspect we should RFC dropping it for production + builds. This exists to support the ember inspector. + +### Documented Public APIs without public import paths + +There are a few public classes that are not exposed at all via `export` today. Those classes will not be given + public export paths, but the package containing their documentation and implementation is shown here: + + * `@ember-data/store` + * `Reference` + * `RecordReference` + * `@ember-data/relationship-layer` + * `BelongsToReference` + * `HasManyReference` + * `@ember-data/model` + * `PromiseBelongsTo` + * `PromiseRecord` + +## How we teach this + +> What names and terminology work best for these concepts and why? How is this +idea best presented? As a continuation of existing Ember patterns, or as a +wholly new one? + +> 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? + +> How should this feature be introduced and taught to existing Ember +users? + +## 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? + +> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. + +## Unresolved questions + +> Optional, but suggested for first drafts. What parts of the design are still +TBD? From 37da1a1a29bfa08a6fed89cfec4a662b723f5d12 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 31 Oct 2018 18:57:28 -0700 Subject: [PATCH 02/30] update RFC with paths for adapters --- text/0000-ember-data-packages.md | 78 +++++++++++++++++++++++++------- 1 file changed, 61 insertions(+), 17 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index afb7b8770c..4379ff088b 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -74,23 +74,67 @@ This documents presents the proposed **public** import path changes for `ember-d * `PromiseManyArray` * `ManyArray` -### @ember-data/adapter - - * DS.Adapter - * DS.RESTAdapter - * DS.JSONAPIAdapter - * DS.BuildURLMixin - * DS.AdapterError - * DS.InvalidError - * DS.TimeoutError - * DS.AbortError - * DS.UnauthorizedError - * DS.ForbiddenError - * DS.NotFoundError - * DS.ConflictError - * DS.ServerError - * (public deprecate) DS.errorsHashToArray - * (public deprecate) DS.errorsArrayToHash +### @ember-data/adapters + + * Adapter + * replaces: `import { Adapter } from 'ember-data';` + * replaces: `import Adapter from 'ember-data/adapter';` + * `import Adapter from '@ember-data/adapters';` + * RESTAdapter + * replaces: `import { RESTAdapter } from 'ember-data';` + * replaces: `import RESTAdapter from 'ember-data/adapters/rest';` + * `import RESTAdapter from '@ember-data/adapters/rest';` + * JSONAPIAdapter + * replaces: `import { JSONAPIAdapter } from 'ember-data';` + * replaces: `import JSONAPIAdapter from 'ember-data/adapters/json-api';` + * `import JSONAPIAdapter from '@ember-data/adapters/json-api';` + * BuildURLMixin + * replaces: `import { BuildURLMixin } from 'ember-data';` + * `import BuildURLMixin from '@ember-data/adapters/mixins/build-url';` + * AdapterError + * replaces: `import { AdapterError } from 'ember-data';` + * replaces: `import { AdapterError { from 'ember-data/adapters/errors';` + * `import AdapterError from '@ember-data/adapters/errors';` + * InvalidError + * replaces: `import { InvalidError } from 'ember-data';` + * replaces: `import { InvalidError { from 'ember-data/adapters/errors';` + * `import { InvalidError } from '@ember-data/adapters/errors';` + * TimeoutError + * replaces: `import { TimeoutError } from 'ember-data';` + * replaces: `import { TimeoutError { from 'ember-data/adapters/errors';` + * `import { TimeoutError } from '@ember-data/adapters/errors';` + * AbortError + * replaces: `import { AbortError } from 'ember-data';` + * replaces: `import { AbortError { from 'ember-data/adapters/errors';` + * `import { AbortError } from '@ember-data/adapters/errors';` + * UnauthorizedError + * replaces: `import { UnauthorizedError } from 'ember-data';` + * replaces: `import { UnauthorizedError { from 'ember-data/adapters/errors';` + * `import { UnauthorizedError } from '@ember-data/adapters/errors';` + * ForbiddenError + * replaces: `import { ForbiddenError } from 'ember-data';` + * replaces: `import { ForbiddenError { from 'ember-data/adapters/errors';` + * `import { ForbiddenError } from '@ember-data/adapters/errors';` + * NotFoundError + * replaces: `import { NotFoundError } from 'ember-data';` + * replaces: `import { NotFoundError { from 'ember-data/adapters/errors';` + * `import { NotFoundError } from '@ember-data/adapters/errors';` + * ConflictError + * replaces: `import { ConflictError } from 'ember-data';` + * replaces: `import { ConflictError { from 'ember-data/adapters/errors';` + * `import { ConflictError } from '@ember-data/adapters/errors';` + * ServerError + * replaces: `import { ServerError } from 'ember-data';` + * replaces: `import { ServerError { from 'ember-data/adapters/errors';` + * `import { ServerError } from '@ember-data/adapters/errors';` + * errorsHashToArray + * this public method should also be a candidate for deprecation + * replaces: `import { errorsHashToArray } from 'ember-data';` + * `import { errorsHashToArray } from '@ember-data/adapters/errors';` + * errorsArrayToHash + * this public method should also be a candidate for deprecation + * replaces: `import { errorsArrayToHash } from 'ember-data';` + * `import { errorsArrayToHash } from '@ember-data/adapters/errors';` ### @ember-data/serializer From 8afd9c651cb4e36c1fecc1c4beaa0a3dccfc1b0a Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 31 Oct 2018 23:47:45 -0700 Subject: [PATCH 03/30] is a table nice? --- text/0000-ember-data-packages.md | 118 ++++++++++++++++++++----------- 1 file changed, 78 insertions(+), 40 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 4379ff088b..851f75bb28 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -17,45 +17,83 @@ This documents presents the proposed **public** import path changes for `ember-d ## Detailed design -### @ember-data/model - - * Model: `import { Model } from '@ember-data/model';` - * replaces: `import { Model } from 'ember-data';` - * replaces: `import Model from 'ember-data/model;` - * attr - * replaces: `import { attr } from 'ember-data'` - * replaces: `import attr from 'ember-data/attr';` - * `import { attr } from '@ember-data/model';` - * belongsTo - * replaces: `import { belongsTo } from 'ember-data'` - * replaces: `import belongsTo from 'ember-data/belongsTo';` - * `import { belongsTo } from '@ember-data/model';` - * hasMany - * replaces: `import { hasMany } from 'ember-data'` - * replaces: `import hasMany from 'ember-data/hasMany';` - * `import { hasMany } from '@ember-data/model';` - * Errors - * we will deprecate directly importing this class - * replaces: `import { Errors } from 'ember-data'` - * `import Errors from '@ember-data/model/errors';` - * PromiseManyArray - * we will deprecate directly importing this class - * replaces: `import { PromiseManyArray } from 'ember-data'` - * `import PromiseManyArray from '@ember-data/model/promise-many-array';` - * ManyArray - * we will deprecate directly importing this class - * replaces: `import { ManyArray } from 'ember-data'` - * `import ManyArray from '@ember-data/model/many-array';` - * `@private` InternalModel - * we will deprecate directly importing this class - * replaces: `import { ManyArray } from 'ember-data'` - * `import ManyArray from '@ember-data/model/-private/internal-model';` - * `@private` RootState - * we will deprecate directly importing this class - * replaces: `import { RootState } from 'ember-data'` - * `import RootState from '@ember-data/model/-private/root-state';` - -**Unresolved Questions** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BeforeAfter
`import DS from 'ember-data';`Direct ImportAfterNotes
`@ember-data/model`
`DS.Model``import Model from 'ember-data/model';``import { Model } from '@ember-data/model';`Not the default export to make working with attr/belongsTo/hasMany even easier
`DS.attr``import attr from 'ember-data/attr';`import { attr } from '@ember-data/model';`
`DS.belongsTo``import { belongsTo } from 'ember-data/relationships';``import { belongsTo } from '@ember-data/model';`
`DS.hasMany``import { hasMany } from 'ember-data/relationships';``import { hasMany } from '@ember-data/model';`
`DS.Errors`none`import Errors from '@ember-data/model/errors';`We should also deprecate directly importing this class
`DS.PromiseManyArray`none`import PromiseManyArray from '@ember-data/model/promise-many-array';`We should also deprecate directly importing this class
`DS.ManyArray`none`import ManyArray from '@ember-data/model/many-array';`We should also deprecate directly importing this class
(`@private`) `DS.InternalModel`nonenoneAccess to this private API will be removed
(`@private`) `DS.RootState`nonenoneAccess to this private API will be removed
+ +### Unresolved Questions + +### `@ember-data/model` 1) `InternalModel` and `RootState` are tightly coupled to the store and to our provided `Model` implementation. Overtime we need to uncouple this, but given their coupling to `Model` and our @@ -65,7 +103,7 @@ This documents presents the proposed **public** import path changes for `ember-d 2) Do the following belong in `@ember-data/model`, or in `@ember-data/relationship-layer`? if not with relationships, does the package name "relationship-layer" become confusing? - The argument for them being here is they are far more related to the current `Model` ui + The argument for them being here is they are far more related to the current `Model` ui presentation layer than they are to the state book-keeping which could be used with alternative implementations. From 992ff2fb3f685e67b3ecfa6e7d21271be81b1a30 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 31 Oct 2018 23:52:55 -0700 Subject: [PATCH 04/30] improve table --- text/0000-ember-data-packages.md | 34 +++++++++++++++++--------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 851f75bb28..296400dbbf 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -21,72 +21,74 @@ This documents presents the proposed **public** import path changes for `ember-d Before - After + After `import DS from 'ember-data';` Direct Import - After - Notes + New Location - `@ember-data/model` + `@ember-data/model` `DS.Model` `import Model from 'ember-data/model';` `import { Model } from '@ember-data/model';` - Not the default export to make working with attr/belongsTo/hasMany even easier + + + + `Model` is not the default export to make working with + `attr/belongsTo/hasMany` even easier + `DS.attr` `import attr from 'ember-data/attr'; `import { attr } from '@ember-data/model';` - `DS.belongsTo` `import { belongsTo } from 'ember-data/relationships';` `import { belongsTo } from '@ember-data/model';` - `DS.hasMany` `import { hasMany } from 'ember-data/relationships';` `import { hasMany } from '@ember-data/model';` - `DS.Errors` none - `import Errors from '@ember-data/model/errors';` - We should also deprecate directly importing this class + `import Errors from '@ember-data/model/errors';`
+
We should also deprecate directly importing this class + `DS.PromiseManyArray` none - `import PromiseManyArray from '@ember-data/model/promise-many-array';` - We should also deprecate directly importing this class + `import PromiseManyArray from '@ember-data/model/promise-many-array';`
+
We should also deprecate directly importing this class + `DS.ManyArray` none - `import ManyArray from '@ember-data/model/many-array';` - We should also deprecate directly importing this class + `import ManyArray from '@ember-data/model/many-array';`
+
We should also deprecate directly importing this class + (`@private`) `DS.InternalModel` none none - Access to this private API will be removed (`@private`) `DS.RootState` none none - Access to this private API will be removed From 52cf02120a6d151af53253b32487f0f5613b9459 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 1 Nov 2018 00:06:06 -0700 Subject: [PATCH 05/30] add adapter to table --- text/0000-ember-data-packages.md | 198 +++++++++++++++++-------------- 1 file changed, 106 insertions(+), 92 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 296400dbbf..f347b7585a 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -24,71 +24,147 @@ This documents presents the proposed **public** import path changes for `ember-d After - `import DS from 'ember-data';` + import DS from 'ember-data'; Direct Import New Location - `@ember-data/model` + @ember-data/model - `DS.Model` - `import Model from 'ember-data/model';` - `import { Model } from '@ember-data/model';` + DS.Model + import Model from 'ember-data/model'; + import { Model } from '@ember-data/model'; - - `Model` is not the default export to make working with - `attr/belongsTo/hasMany` even easier - + DS.attr + import attr from 'ember-data/attr'; + import { attr } from '@ember-data/model'; - `DS.attr` - `import attr from 'ember-data/attr'; - `import { attr } from '@ember-data/model';` + DS.belongsTo + import { belongsTo } from 'ember-data/relationships'; + import { belongsTo } from '@ember-data/model'; - `DS.belongsTo` - `import { belongsTo } from 'ember-data/relationships';` - `import { belongsTo } from '@ember-data/model';` + DS.hasMany + import { hasMany } from 'ember-data/relationships'; + import { hasMany } from '@ember-data/model'; - `DS.hasMany` - `import { hasMany } from 'ember-data/relationships';` - `import { hasMany } from '@ember-data/model';` + DS.Errors + none + import Errors from '@ember-data/model/errors';
+
+ deprecate directly importing this class + - `DS.Errors` + DS.PromiseManyArray none - `import Errors from '@ember-data/model/errors';`
-
We should also deprecate directly importing this class + import PromiseManyArray from '@ember-data/model/promise-many-array';
+
+ deprecate directly importing this class - `DS.PromiseManyArray` + DS.ManyArray none - `import PromiseManyArray from '@ember-data/model/promise-many-array';`
-
We should also deprecate directly importing this class + import ManyArray from '@ember-data/model/many-array';
+
+ deprecate directly importing this class - `DS.ManyArray` + (@private) DS.InternalModel + none none - `import ManyArray from '@ember-data/model/many-array';`
-
We should also deprecate directly importing this class - - (`@private`) `DS.InternalModel` + (@private) DS.RootState none none - (`@private`) `DS.RootState` + @ember-data/adapters + + + DS.Adapter + import Adapter from 'ember-data/adapter'; + import Adapter from '@ember-data/adapters'; + + + DS.RESTAdpter + import RESTAdapter from 'ember-data/adapters/rest'; + import RESTAdapter from '@ember-data/adapters/rest'; + + + DS.JSONAPIAdapter + import JSONAPIAdapter from 'ember-data/adapters/json-api'; + import from '@ember-data/adapters/json-api'; + + + DS.BuildURLMixin none + import BuildURLMixin from '@ember-data/adapters/mixins/build-url'; + + + DS.AdapterError + import { AdapterError } from 'ember-data/adapters/errors'; + import { AdapterError } from '@ember-data/adapters/errors'; + + + DS.InvalidError + import { InvalidError } from 'ember-data/adapters/errors'; + import { InvalidError } from '@ember-data/adapters/errors'; + + + DS.TimeoutError + import { TimeoutError } from 'ember-data/adapters/errors'; + import { TimeoutError } from '@ember-data/adapters/errors'; + + + DS.AbortError + import { AbortError } from 'ember-data/adapters/errors'; + import { AbortError } from '@ember-data/adapters/errors'; + + + DS.UnauthorizedError + import { UnauthorizedError } from 'ember-data/adapters/errors'; + import { UnauthorizedError } from '@ember-data/adapters/errors'; + + + DS.ForbiddenError + import { ForbiddenError } from 'ember-data/adapters/errors'; + import { ForbiddenError } from '@ember-data/adapters/errors'; + + + DS.NotFoundError + import { NotFoundError } from 'ember-data/adapters/errors'; + import { NotFoundError } from '@ember-data/adapters/errors'; + + + DS.ConflictError + import { ConflictError } from 'ember-data/adapters/errors'; + import { ConflictError } from '@ember-data/adapters/errors'; + + + DS.ServerError + import { ServerError } from 'ember-data/adapters/errors'; + import { ServerError } from '@ember-data/adapters/errors'; + + + DS.errorsHashToArray none + import { errorsHashToArray } from '@ember-data/adapters/errors';
+
this public method should also be a candidate for deprecation + + + + DS.errorsArrayToHash + none + import { errorsArrayToHashr } from '@ember-data/adapters/errors';
+
this public method should also be a candidate for deprecation + @@ -114,68 +190,6 @@ This documents presents the proposed **public** import path changes for `ember-d * `PromiseManyArray` * `ManyArray` -### @ember-data/adapters - - * Adapter - * replaces: `import { Adapter } from 'ember-data';` - * replaces: `import Adapter from 'ember-data/adapter';` - * `import Adapter from '@ember-data/adapters';` - * RESTAdapter - * replaces: `import { RESTAdapter } from 'ember-data';` - * replaces: `import RESTAdapter from 'ember-data/adapters/rest';` - * `import RESTAdapter from '@ember-data/adapters/rest';` - * JSONAPIAdapter - * replaces: `import { JSONAPIAdapter } from 'ember-data';` - * replaces: `import JSONAPIAdapter from 'ember-data/adapters/json-api';` - * `import JSONAPIAdapter from '@ember-data/adapters/json-api';` - * BuildURLMixin - * replaces: `import { BuildURLMixin } from 'ember-data';` - * `import BuildURLMixin from '@ember-data/adapters/mixins/build-url';` - * AdapterError - * replaces: `import { AdapterError } from 'ember-data';` - * replaces: `import { AdapterError { from 'ember-data/adapters/errors';` - * `import AdapterError from '@ember-data/adapters/errors';` - * InvalidError - * replaces: `import { InvalidError } from 'ember-data';` - * replaces: `import { InvalidError { from 'ember-data/adapters/errors';` - * `import { InvalidError } from '@ember-data/adapters/errors';` - * TimeoutError - * replaces: `import { TimeoutError } from 'ember-data';` - * replaces: `import { TimeoutError { from 'ember-data/adapters/errors';` - * `import { TimeoutError } from '@ember-data/adapters/errors';` - * AbortError - * replaces: `import { AbortError } from 'ember-data';` - * replaces: `import { AbortError { from 'ember-data/adapters/errors';` - * `import { AbortError } from '@ember-data/adapters/errors';` - * UnauthorizedError - * replaces: `import { UnauthorizedError } from 'ember-data';` - * replaces: `import { UnauthorizedError { from 'ember-data/adapters/errors';` - * `import { UnauthorizedError } from '@ember-data/adapters/errors';` - * ForbiddenError - * replaces: `import { ForbiddenError } from 'ember-data';` - * replaces: `import { ForbiddenError { from 'ember-data/adapters/errors';` - * `import { ForbiddenError } from '@ember-data/adapters/errors';` - * NotFoundError - * replaces: `import { NotFoundError } from 'ember-data';` - * replaces: `import { NotFoundError { from 'ember-data/adapters/errors';` - * `import { NotFoundError } from '@ember-data/adapters/errors';` - * ConflictError - * replaces: `import { ConflictError } from 'ember-data';` - * replaces: `import { ConflictError { from 'ember-data/adapters/errors';` - * `import { ConflictError } from '@ember-data/adapters/errors';` - * ServerError - * replaces: `import { ServerError } from 'ember-data';` - * replaces: `import { ServerError { from 'ember-data/adapters/errors';` - * `import { ServerError } from '@ember-data/adapters/errors';` - * errorsHashToArray - * this public method should also be a candidate for deprecation - * replaces: `import { errorsHashToArray } from 'ember-data';` - * `import { errorsHashToArray } from '@ember-data/adapters/errors';` - * errorsArrayToHash - * this public method should also be a candidate for deprecation - * replaces: `import { errorsArrayToHash } from 'ember-data';` - * `import { errorsArrayToHash } from '@ember-data/adapters/errors';` - ### @ember-data/serializer * DS.Serializer From 9a8343fe28a0396604666c440edbec85029fef27 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 1 Nov 2018 00:33:15 -0700 Subject: [PATCH 06/30] finish off the table --- text/0000-ember-data-packages.md | 189 +++++++++++++++++++++++-------- 1 file changed, 144 insertions(+), 45 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index f347b7585a..766fc5b967 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -31,7 +31,7 @@ This documents presents the proposed **public** import path changes for `ember-d - @ember-data/model +

@ember-data/model

DS.Model @@ -85,7 +85,7 @@ This documents presents the proposed **public** import path changes for `ember-d none - @ember-data/adapters +

@ember-data/adapters

DS.Adapter @@ -166,17 +166,141 @@ This documents presents the proposed **public** import path changes for `ember-d
this public method should also be a candidate for deprecation + +

@ember-data/serializers

+ + + DS.Serializer + import Serializer from 'ember-data/serializer'; + import Serializer from '@ember-data/serializers'; + + + DS.JSONSerializer + import JSONSerializer from 'ember-data/serializers/json'; + import JSONSerializer from '@ember-data/serializers/json'; + + + DS.RESTSerializer + import RESTSerializer from 'ember-data/serializers/rest'; + import RESTSerializer from '@ember-data/serializers/rest'; + + + DS.EmbeddedRecordsMixin + import EmbeddedRecordsMixin from 'ember-data/serializers/embedded-records-mixin'; + import EmbeddedRecordsMixin from 'ember-data/serializers/rest/mixins'; + + + DS.JSONAPISerializer + import JSONAPISerializer from 'ember-data/serializers/json-api'; + import JSONAPISerializer from 'ember-data/serializers/json-api'; + + + DS.Transform + import Transform from 'ember-data/transform'; + import Transform from 'ember-data/transforms'; + + + DS.DateTransform + import DateTransform from 'ember-data/transforms/date'; + import { DateTransform } from 'ember-data/transforms'; + + + DS.StringTransform + import StringTransform from 'ember-data/transforms/string'; + import { StringTransform } from 'ember-data/transforms'; + + + DS.NumberTransform + import NumberTransform from 'ember-data/transforms/number'; + import { NumberTransform } from 'ember-data/transforms'; + + + DS.BooleanTransform + import BooleanTransform from 'ember-data/transforms/boolean'; + import { BooleanTransform } from 'ember-data/transforms'; + + +

@ember-data/store

+ + + DS.Store + import Store from 'ember-data/store'; + import Store from '@ember-data/store'; + + + DS.Snapshot + none + none + + + DS.PromiseArray + none + none + + + DS.PromiseObject + none + none + + + DS.RecordArray + none + none + + + DS.AdapterPopulatedRecordArray + none + none + + + DS.RecordarrayManager + none + none + + + DS._initializeStoreService + import initializeStoreService from 'ember-data/intialize-store-service'; + none + + + DS._setupContainer + import setupContainer from 'ember-data/setup-container'; + none + + + DS.normalizeModelName + none + import { normalizeModelName } from 'ember-data/store';
+
this public method should be a candidate for deprecation + + + +

@ember-data/relationship-layer

+ + + DS.Relationship + none + none + + +

@ember-data/debug

+ + + DS.DebugAdapter + none + none + -### Unresolved Questions +### Notes -### `@ember-data/model` +#### `@ember-data/model` 1) `InternalModel` and `RootState` are tightly coupled to the store and to our provided `Model` implementation. Overtime we need to uncouple this, but given their coupling to `Model` and our desire to enable them to be eliminated from projects not using `Model`, I believe these exports - belong here. + belong in `@ember-data/model` for this reason. 2) Do the following belong in `@ember-data/model`, or in `@ember-data/relationship-layer`? if not with relationships, does the package name "relationship-layer" become confusing? @@ -189,34 +313,14 @@ This documents presents the proposed **public** import path changes for `ember-d * `hasMany` * `PromiseManyArray` * `ManyArray` + +#### `@ember-data/serializers` -### @ember-data/serializer - - * DS.Serializer - * DS.RESTSerializer - * DS.JSONSerializer - * DS.JSONAPISerializer - * DS.Transform - * DS.DateTransform - * DS.StringTransform - * DS.NumberTransform - * DS.BooleanTransform - * DS.EmbeddedRecordsMixin - -### @ember-data/store - - * DS.Store - * (deprecate-access) DS.PromiseArray - * (deprecate-access) DS.PromiseObject - * DS.Snapshot - * (deprecate-access) DS.RecordArray - * (deprecate-access) DS.AdapterPopulatedRecordArray - * (private deprecate-access) DS.RecordArrayManager - * (private deprecate-access) DS._initializeStoreService - * (private deprecate-access) DS._setupContainer - * (deprecate) normalizeModelName - -**Unresolved Questions** + 1) We should move automatic registration of transforms into a more traditional + `app/` directory re-export for the package so that when the package is dropped they + cleanly drop as well. + +#### `@ember-data/store` 1) _setupContainer registers various adapters and serializers for fallbacks. Either we need to deprecate this behavior (preferred), or separate out initialization @@ -229,25 +333,20 @@ This documents presents the proposed **public** import path changes for `ember-d 3) normalizeModelName is defined... very oddly. Why? Also we should probably deprecate this and continue to move to a world in which less normalization of modelName is required. -### @ember-data/relationship-layer - - * (private deprecate) DS.Relationship - -**Notes** +#### `@ember-data/relationship-layer` This package seems thin but it's likely to hold quite a bit. Additional private things that would be moved here: - everything in `-private/system/relationships/state` - logic from `internal-model` that need to be extracted - -### @ember-data/debug - * DS.DebugAdapter + * everything in `-private/system/relationships/state` + * `BelongsToReference` and `HasManyReference` + * relationship logic from `store` / `internal-model` that need to be isolated and extracted -**Notes** +#### `@ember-data/debug` - Moving this here would allow dropping it. I already suspect we should RFC dropping it for production - builds. This exists to support the ember inspector. + Moving `DebugAdapter` here would allow dropping it if not desired. I already suspect we should + RFC dropping it for production builds where it adds persistent unnecessary overhead for a tool + meant for devs. This exists to support the ember inspector. ### Documented Public APIs without public import paths From 0530d3312ea651441168f21d2791a12058332af7 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 8 Nov 2018 23:16:35 -0700 Subject: [PATCH 07/30] Adding proper @ember-data package name where missing --- text/0000-ember-data-packages.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 766fc5b967..7c3e8d37a6 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -187,37 +187,37 @@ This documents presents the proposed **public** import path changes for `ember-d DS.EmbeddedRecordsMixin import EmbeddedRecordsMixin from 'ember-data/serializers/embedded-records-mixin'; - import EmbeddedRecordsMixin from 'ember-data/serializers/rest/mixins'; + import EmbeddedRecordsMixin from '@ember-data/serializers/rest/mixins'; DS.JSONAPISerializer import JSONAPISerializer from 'ember-data/serializers/json-api'; - import JSONAPISerializer from 'ember-data/serializers/json-api'; + import JSONAPISerializer from '@ember-data/serializers/json-api'; DS.Transform import Transform from 'ember-data/transform'; - import Transform from 'ember-data/transforms'; + import Transform from '@ember-data/transforms'; DS.DateTransform import DateTransform from 'ember-data/transforms/date'; - import { DateTransform } from 'ember-data/transforms'; + import { DateTransform } from '@ember-data/transforms'; DS.StringTransform import StringTransform from 'ember-data/transforms/string'; - import { StringTransform } from 'ember-data/transforms'; + import { StringTransform } from '@ember-data/transforms'; DS.NumberTransform import NumberTransform from 'ember-data/transforms/number'; - import { NumberTransform } from 'ember-data/transforms'; + import { NumberTransform } from '@ember-data/transforms'; DS.BooleanTransform import BooleanTransform from 'ember-data/transforms/boolean'; - import { BooleanTransform } from 'ember-data/transforms'; + import { BooleanTransform } from '@ember-data/transforms';

@ember-data/store

@@ -298,7 +298,7 @@ This documents presents the proposed **public** import path changes for `ember-d #### `@ember-data/model` 1) `InternalModel` and `RootState` are tightly coupled to the store and to our provided `Model` - implementation. Overtime we need to uncouple this, but given their coupling to `Model` and our + implementation. Over time we need to uncouple this, but given their coupling to `Model` and our desire to enable them to be eliminated from projects not using `Model`, I believe these exports belong in `@ember-data/model` for this reason. From c54f40cc83c29c9190e7305e3322e111fb0b853d Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 15 Nov 2018 12:55:10 -0800 Subject: [PATCH 08/30] fillout RFC --- text/0000-ember-data-packages.md | 128 +++++++++++++++++++++++-------- 1 file changed, 98 insertions(+), 30 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 766fc5b967..c65ee95bac 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -6,14 +6,84 @@ ## Summary -This documents presents the proposed **public** import path changes for `ember-data`. - How *exactly* we re-align any internals is informed but not determined by this. +This documents presents the proposed **public** import path changes for `ember-data`, and moving `ember-data` + into the `@ember-data` namespace. ## Motivation - * Unify import location `import { Model } from 'ember-data'` or `import Model from 'ember-data/model'` ? - * Drop the concept of a single `DS` namespace - * Unlock the potential to enable end users to drop unneeded portions of ember-data +**Reduce Confusion & Bike Shedding** + +Users of `ember-data` have often noted their confusion by the existence of both direct and "god object" (`DS.`) style + imports for modules from `ember-data`. The documentation currently uses primarily the `DS.` use style, and users have + expressed interest and confusion over why the documentation has not been updated to reflect direct imports. + +**Improve The TypeScript Experience** + +Presence of multiple import locations confuses `Typescript`'s autocomplete, symbol resolution, and type hinting. + +**Simplify The Mental Model** + +Users of `ember-data` complain about the large API surface area; however, a large portion of this surface area is + non-essential user-land APIs that the provided adapter and serializer implementations expose. This move to packages + helps us simplify the mental model in three ways. + + First: it gives us a natural way of dividing the documentation and learning story such that key concepts + and APIs are more discoverable. + + Second: it allows us specifically to isolate the API surface area explosion of the provided adapter and serializer + implementations and make it clear that these are non-essential, replaceable APIs. E.G. it will help us to communicate + that these adapters and serializers are _an implementation_, **not** _the required implementation_. + + Third: it clarifies the roles of several concepts within `ember-data` that are often misused today. Specifically: + the `embedded-records-mixin` should *_only_* be used with the `RESTAdapter`, and `transforms` are *_only_* a + serialization/deserialization concern and not a way of defining custom `attrs` or `types`. Furthermore, `transforms` + are only applicable to the serializer implementations that `ember-data` provides, and not to `custom` (and sometimes + not to `subclassed`) serializers. + +**Improve the Contributor Experience** + +Contributors to `ember-data` are faced with a large, complex project with poor code and test organization. This makes it + unduly difficult to discover what tests exist, where to add tests, where associated code lives, and even what parts of + the code base relate to the feature or bug that they are looking to address. + + This move to packages will help us restructure the project and associated tests in a manner that is more discoverable. + +**Provide a Clear Subdivision of Packages** + +Today, `ember-data` is a large single package (`~35KB gzipped` in production). `ember-data` is often one of the largest + dependencies `emberjs` users have in their applications. However, not all users utilize all parts of `ember-data`, and + some users use very little. Providing these packages helps to clearly show the cost of various features, and better + allows us to enable end users to eliminate unneeded packages. + +Users that implement their own adapter os serializers today must still carry the significant weight of the adapter and + serializer implementations that `ember-data` ships regardless. This is a weight we should enable these users to eliminate. + +With the landing of `RecordData` and the merging of the `modelFactoryFor` RFC, it is likely that many applications + will soon require far less of `ember-data` than they do today. `ember-m3` is an example of a project that utilizes these + APIs in a way that requires significantly less of the `ember-data` experience. + +**Provide Infrastructure for Additional Changes** + +`ember-data` is entering a period of extended evolution, of which `RecordData` and `modelFactoryFor` are only the early + pieces. For example, current thinking includes the possibility of `ember-data` evolving to provide an `ember-m3`-like + experience for `json-api` as the default out-of-the-box experience, and a rethinking of how we manage the request/response + lifecycle when fulfilling a request for data. + + These experiences would live alongside the existing experience for a time prior to any deprecations of the current layer, + and it is possible that sometimes the current experience would never be deprecated. Subdividing `ember-data` into these + packages will enable us to provide a more seamless transition between these experiences without hoisting any package + size costs onto users that do not use either the current or the new experience. + +**Improve our CI Time** + +Currently `ember-data` lives in the `emberjs` organization on `github` despite owning the `ember-data` organization. + Other core projects (`ember-cli`, `glimmer`, `ember-learn`) have already established the value of a core team utilizing + their own organization. This includes improvements in managing membership permissions for their respective teams. + +Today, presence in the `emberjs` organization on `github` also places `ember-data` in the + `emberjs` organization on `Travis`, where we compete for a shared pool of test instances, often delaying our tests + by as much as an extra hour. A move to the `ember-data` organization would move our `CI` runs out of the `emberjs` + on `Travis` into our own organization, removing us from the shared pool. ## Detailed design @@ -93,7 +163,7 @@ This documents presents the proposed **public** import path changes for `ember-d import Adapter from '@ember-data/adapters'; - DS.RESTAdpter + DS.RESTAdapter import RESTAdapter from 'ember-data/adapters/rest'; import RESTAdapter from '@ember-data/adapters/rest'; @@ -187,7 +257,7 @@ This documents presents the proposed **public** import path changes for `ember-d DS.EmbeddedRecordsMixin import EmbeddedRecordsMixin from 'ember-data/serializers/embedded-records-mixin'; - import EmbeddedRecordsMixin from 'ember-data/serializers/rest/mixins'; + import EmbeddedRecordsMixin from '@ember-data/serializers/rest/mixins/embedded-records'; DS.JSONAPISerializer @@ -274,6 +344,14 @@ This documents presents the proposed **public** import path changes for `ember-d
this public method should be a candidate for deprecation + +

@ember-data/record-data

+ + + none + import { RecordData } from 'ember-data/-private'; + import RecordData from '@ember-data/record-data'; +

@ember-data/relationship-layer

@@ -330,7 +408,7 @@ This documents presents the proposed **public** import path changes for `ember-d 2) _initializeStoreService eagerly instantiates the store to ensure that `defaultStore` is our store. we should get rid of this but can't until there is a `defaultStore` RFC for ember itself. - 3) normalizeModelName is defined... very oddly. Why? Also we should probably deprecate this + 3) normalizeModelName is defined... very oddly. Why? We should probably deprecate this and continue to move to a world in which less normalization of modelName is required. #### `@ember-data/relationship-layer` @@ -344,7 +422,7 @@ This package seems thin but it's likely to hold quite a bit. #### `@ember-data/debug` - Moving `DebugAdapter` here would allow dropping it if not desired. I already suspect we should + Moving `DebugAdapter` here would allow dropping it if not desired. Additionally we should likely RFC dropping it for production builds where it adds persistent unnecessary overhead for a tool meant for devs. This exists to support the ember inspector. @@ -356,6 +434,7 @@ There are a few public classes that are not exposed at all via `export` today. T * `@ember-data/store` * `Reference` * `RecordReference` + * `StoreWrapper` * `@ember-data/relationship-layer` * `BelongsToReference` * `HasManyReference` @@ -365,32 +444,21 @@ There are a few public classes that are not exposed at all via `export` today. T ## How we teach this -> What names and terminology work best for these concepts and why? How is this -idea best presented? As a continuation of existing Ember patterns, or as a -wholly new one? +This RFC should be seen as a continuation of the `javascript-modules` RFC that defined explicit import paths for `emberjs`. -> 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? +Codemods and lint rules would be provided to convert existing imports to the new syntax. Existing import locations + would continue to exist for a time but would print build-time deprecations. -> How should this feature be introduced and taught to existing Ember -users? +Ember documentation and guides would be updated to reflect these new import paths as well as to utilize the new package + divisions to improve the teaching story. ## 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. +* A Tiny amount of churn ## Alternatives -> What other designs have been considered? What is the impact of not doing this? - -> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem. - -## Unresolved questions - -> Optional, but suggested for first drafts. What parts of the design are still -TBD? +* Divide into packages without exposing the new division publically +* Don't divide into packages until nebulous future RFCs have landed +* Use the `@ember` namespace. +* Use the `@ember-data` namespace without moving to the `@ember-data` org. From a48aebb681ba216207bb918e777e3848b7dbdc49 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 15 Nov 2018 13:05:36 -0800 Subject: [PATCH 09/30] grammer fix --- text/0000-ember-data-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index c65ee95bac..9f5bc62efc 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -14,7 +14,7 @@ This documents presents the proposed **public** import path changes for `ember-d **Reduce Confusion & Bike Shedding** Users of `ember-data` have often noted their confusion by the existence of both direct and "god object" (`DS.`) style - imports for modules from `ember-data`. The documentation currently uses primarily the `DS.` use style, and users have + imports for modules from `ember-data`. The documentation currently uses primarily the `DS.` style, and users have expressed interest and confusion over why the documentation has not been updated to reflect direct imports. **Improve The TypeScript Experience** From e8ab452cc686f21db1d1c963faa76970a2be2091 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Thu, 15 Nov 2018 13:20:25 -0800 Subject: [PATCH 10/30] sp --- text/0000-ember-data-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 9f5bc62efc..64e05de7a8 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -55,7 +55,7 @@ Today, `ember-data` is a large single package (`~35KB gzipped` in production). ` some users use very little. Providing these packages helps to clearly show the cost of various features, and better allows us to enable end users to eliminate unneeded packages. -Users that implement their own adapter os serializers today must still carry the significant weight of the adapter and +Users that implement their own adapter or serializers today must still carry the significant weight of the adapter and serializer implementations that `ember-data` ships regardless. This is a weight we should enable these users to eliminate. With the landing of `RecordData` and the merging of the `modelFactoryFor` RFC, it is likely that many applications From 39af85c58acb570a1de923fc87836d0923cfa01f Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Sat, 24 Nov 2018 11:47:31 -0800 Subject: [PATCH 11/30] import { Model } => import Model and fixes --- text/0000-ember-data-packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index be6e008972..e65a0fe3dc 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -106,7 +106,7 @@ Today, presence in the `emberjs` organization on `github` also places `ember-dat DS.Model import Model from 'ember-data/model'; - import { Model } from '@ember-data/model'; + import Model from '@ember-data/model'; DS.attr @@ -170,7 +170,7 @@ Today, presence in the `emberjs` organization on `github` also places `ember-dat DS.JSONAPIAdapter import JSONAPIAdapter from 'ember-data/adapters/json-api'; - import from '@ember-data/adapters/json-api'; + import JSONAPIAdapter from '@ember-data/adapters/json-api'; DS.BuildURLMixin From ffe324fc2276231b05622b4b7cdae5039ef97e85 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Sat, 24 Nov 2018 13:07:01 -0800 Subject: [PATCH 12/30] update alternatives --- text/0000-ember-data-packages.md | 68 +++++++++++++++++++++++++------- 1 file changed, 53 insertions(+), 15 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index e65a0fe3dc..b14023ecab 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -377,15 +377,14 @@ Today, presence in the `emberjs` organization on `github` also places `ember-dat 1) `InternalModel` and `RootState` are tightly coupled to the store and to our provided `Model` implementation. Over time we need to uncouple this, but given their coupling to `Model` and our - desire to enable them to be eliminated from projects not using `Model`, I believe these exports - belong in `@ember-data/model` for this reason. + desire to enable them to be eliminated from projects not using `Model`, these exports + belong in `@ember-data/model`. - 2) Do the following belong in `@ember-data/model`, or in `@ember-data/relationship-layer`? - if not with relationships, does the package name "relationship-layer" become confusing? - - The argument for them being here is they are far more related to the current `Model` ui - presentation layer than they are to the state book-keeping which could be used with - alternative implementations. + 2) The following belong in `@ember-data/model` and not in `@ember-data/relationship-layer` with + relationships. While this presents a mild risk of confusion due to the presence of the + `relationship-layer` package, the argument for their presence here is they are a ui-layer concern + being coupled to the current `Model` presentation layer and not related to overall state management + of relationships which could itself be used with alternative implementations. * `belongsTo` * `hasMany` @@ -400,15 +399,15 @@ Today, presence in the `emberjs` organization on `github` also places `ember-dat #### `@ember-data/store` - 1) _setupContainer registers various adapters and serializers for fallbacks. + 1) `_setupContainer` registers various adapters and serializers for fallbacks. Either we need to deprecate this behavior (preferred), or separate out initialization by package, or both. It also eagerly injects store, which we should deprecate but can't until there is a `defaultStore` RFC for ember itself. - 2) _initializeStoreService eagerly instantiates the store to ensure that `defaultStore` is our store. + 2) `_initializeStoreService` eagerly instantiates the store to ensure that `defaultStore` is our store. we should get rid of this but can't until there is a `defaultStore` RFC for ember itself. - 3) normalizeModelName is defined... very oddly. Why? We should probably deprecate this + 3) `normalizeModelName` is defined... very oddly. Why? We should probably deprecate this and continue to move to a world in which less normalization of modelName is required. #### `@ember-data/relationship-layer` @@ -458,7 +457,46 @@ Ember documentation and guides would be updated to reflect these new import path ## Alternatives -* Divide into packages without exposing the new division publically -* Don't divide into packages until nebulous future RFCs have landed -* Use the `@ember` namespace. -* Use the `@ember-data` namespace without moving to the `@ember-data` org. +1) Divide into packages without exposing the new division publicly + + * _argument for:_ Don't expose churn to end users without a clear win, we aren't 100% sure what belongs in a vague + "future ember-data", so wait until we are sure. + * _rebuttal:_ The churn is minimal and mostly automated (codemod). There are clear wins here for many users. We + should not hold up progress now on an uncertain future. Dividing into packages now gives us more options for how to + manage future evolution. Regardless of when we become certain of what belongs in "future ember-data", these packages + would need to exist alongside at least for a time. + +2) Don't divide into packages until nebulous future RFCs have landed + + * _argument for:_ This argument is an extension of _alternative 1_ in which we wait for specific concepts to mature and + materialize that we have discussed internally, including a significant rework of how we manage the `request/response` + lifecycle. These new feature RFCs would come with corresponding deprecation RFCs for parts of the system they either + fully replace or make vestigial. + * _rebuttal:_ The argument here is a variation of the argument in _alternative 1_ and the rebuttal merely extends + that rebuttal as well. These future deprecations would necessarily be long-tail, if we deprecate at all. There is + the option to have both old and new experiences live side-by-side. Additionally, if we deprecate and then land + `@ember-data/packages` there is both an equal amount of churn and fewer options for how to manage those deprecations. + +3) Use the `@ember` namespace. + + * _argument for:_ `ember-data` is an official package and we wish to position it centrally within the `ember` + ecosystem. This [argument has been presented](https://github.com/emberjs/rfcs/pull/238#issuecomment-318745236) + by other core teams in response to previous attempts to move forward with a packages RFC for `ember-data`. + * _rebuttal:_ `ember-cli` and `glimmer` are also official packages, but with their own namespaces. Additionally + re-using the `@ember` namespace would only further confusion that many folks already have regarding: + * where `ember` ends and `ember-data` begins. + * whether `ember-data` is required or optional + * whether other data layers are seen as "bad practices" (they are not) + * what packages are provided by `ember-data` vs `ember` + `ember-data`'s status as a team, in the guides and in release blog posts on `emberjs.com`, as well as presence in + the default blueprint provided by `ember-cli` make clear it's status as an official offering. Using the `@ember` + namespace is not required for this. + + This argument also necessarily foments an untrue presupposition: that `ember-data` is the right choice for every app. + While we strive to make this the case, it would be very difficult to claim this today, and may never be true, + as every app presents unique concerns and needs. + + Finally, using the `@ember` namespace would leave us in the unfortunate position of either always scoping all of our + packages to `@ember/data/` or of fighting with `emberjs` for package names. + +4) Use the `@ember-data` namespace without moving to the `@ember-data` org. From 7e57bf94d8f6e8a88a53a9aac5bf0dac2a764a9c Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Sun, 25 Nov 2018 17:02:50 -0800 Subject: [PATCH 13/30] finish off alternatives --- text/0000-ember-data-packages.md | 40 +++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index b14023ecab..31b8d02ab6 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -82,9 +82,11 @@ Currently `ember-data` lives in the `emberjs` organization on `github` despite o Today, presence in the `emberjs` organization on `github` also places `ember-data` in the `emberjs` organization on `Travis`, where we compete for a shared pool of test instances, often delaying our tests - by as much as an extra hour. A move to the `ember-data` organization would move our `CI` runs out of the `emberjs` + by as much as an extra hour. A move to the `ember-data` organization would move our `CI` runs out of `emberjs` on `Travis` into our own organization, removing us from the shared pool. +**The proposed package location is `@ember-data/ember-data`.** + ## Detailed design @@ -500,3 +502,39 @@ Ember documentation and guides would be updated to reflect these new import path packages to `@ember/data/` or of fighting with `emberjs` for package names. 4) Use the `@ember-data` namespace without moving to the `@ember-data` org. + +* _argument for:_ Folks have come to expect the repository to live at `emberjs/data`, and this provides extra signal that the package is an official one. + +* _rebuttal:_ + * `github` does a great job of redirecting packages to new locations. We should provide as consistent an experience as possible (package name, import paths, package location etc. all being `@ember-data`) + + * `data` already presents a namespacing issue for folks that fork `ember-data` to contribute back (`data` being a generic package name, akin to having a package called `cli` or `website`). + +5) This RFC but with Adapters and Serializers broken out into the packages `@ember-data/json` `@ember-data/rest` `@ember-data/json-api`. + +* _argument for:_ grouping the adapter / serializer "by API spec" feels more natural and would allow for users to drop only the versions of adapters / serializer they don't require. + +* _rebuttal:_ Even without considering future changes to `ember-data`'s API surface, there are several issues with this approach. + + 1) The implementations inherit each other: + * `JSONAPISerializer extends RESTSerializer extends JSONSerializer extends Serializer` + * `JSONAPIAdapter extends RESTAdapter extends Adapter` + 2) The adapter / serializer pairings aren't coupled + * It is fairly common to use the `JSONAPIAdapter` with the `RESTSerializer` or + with a custom serializer that extends the `RESTSerializer` and vice-verse. + * Even when using a consistent spec (`json-api` or `rest`) it is common to need + a fully custom serializer. The division of needs is at least equally between + adapter/serializer as it is between specs. + + 3) Transforms are an implementation detail for all the provided serializers + + * But they are not required and likely not even used by custom serializers. + + 4) Packages for automatically registered fallbacks would fit poorly. + * Serializers: `"-default"` `"-rest"` `"-json-api"` + * Adapters: `"-rest"` `"-json-api"` + 5) Today, we use multiple serializers for a single type based on entry-point + * `Model.serialize` (per-type) / `Model.toJSON` (`"-json"`) / `Adapter.serialize` (per-adapter) + + That said, this organization is also one of the only-nods + to future RFCs this RFC concedes. The existing provided implementations all follow roughly the same interface for their implementations, and that interface is something we strongly wish to change. For this reason, it seems advantageous to keep the existing implementations together such that the delineation between a new experience and this experience can be kept clear. \ No newline at end of file From 87aa7ec55fb4de38251352cb6a6ce2fbac4ef689 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Mon, 26 Nov 2018 12:21:51 -0800 Subject: [PATCH 14/30] Fix date --- text/0000-ember-data-packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 31b8d02ab6..416e8a232c 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -1,4 +1,4 @@ -- Start Date: (fill me in with today's date, 2018-10-31) +- Start Date: 2018-10-31 - RFC PR: (leave this empty) - Ember Issue: (leave this empty) @@ -537,4 +537,4 @@ Ember documentation and guides would be updated to reflect these new import path * `Model.serialize` (per-type) / `Model.toJSON` (`"-json"`) / `Adapter.serialize` (per-adapter) That said, this organization is also one of the only-nods - to future RFCs this RFC concedes. The existing provided implementations all follow roughly the same interface for their implementations, and that interface is something we strongly wish to change. For this reason, it seems advantageous to keep the existing implementations together such that the delineation between a new experience and this experience can be kept clear. \ No newline at end of file + to future RFCs this RFC concedes. The existing provided implementations all follow roughly the same interface for their implementations, and that interface is something we strongly wish to change. For this reason, it seems advantageous to keep the existing implementations together such that the delineation between a new experience and this experience can be kept clear. From 0590e062bf19f0acccc90bbfeb285b51b2c012cf Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 28 Nov 2018 19:42:10 -0800 Subject: [PATCH 15/30] remove repo move --- text/0000-ember-data-packages.md | 30 ++++++------------------------ 1 file changed, 6 insertions(+), 24 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 416e8a232c..151f4efe46 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -74,21 +74,10 @@ With the landing of `RecordData` and the merging of the `modelFactoryFor` RFC, i packages will enable us to provide a more seamless transition between these experiences without hoisting any package size costs onto users that do not use either the current or the new experience. -**Improve our CI Time** - -Currently `ember-data` lives in the `emberjs` organization on `github` despite owning the `ember-data` organization. - Other core projects (`ember-cli`, `glimmer`, `ember-learn`) have already established the value of a core team utilizing - their own organization. This includes improvements in managing membership permissions for their respective teams. - -Today, presence in the `emberjs` organization on `github` also places `ember-data` in the - `emberjs` organization on `Travis`, where we compete for a shared pool of test instances, often delaying our tests - by as much as an extra hour. A move to the `ember-data` organization would move our `CI` runs out of `emberjs` - on `Travis` into our own organization, removing us from the shared pool. - -**The proposed package location is `@ember-data/ember-data`.** - ## Detailed design +The following modules would continue to live in a monorepo that (until further RFC) would continue to live at `github.com/ember/data`. +
@@ -448,7 +437,9 @@ There are a few public classes that are not exposed at all via `export` today. T This RFC should be seen as a continuation of the `javascript-modules` RFC that defined explicit import paths for `emberjs`. Codemods and lint rules would be provided to convert existing imports to the new syntax. Existing import locations - would continue to exist for a time but would print build-time deprecations. + would continue to exist for a time but would at some point in the future be made to print build-time deprecations. + +End users would need to run the codemod at some point, but no other changes will be required. Ember documentation and guides would be updated to reflect these new import paths as well as to utilize the new package divisions to improve the teaching story. @@ -501,16 +492,7 @@ Ember documentation and guides would be updated to reflect these new import path Finally, using the `@ember` namespace would leave us in the unfortunate position of either always scoping all of our packages to `@ember/data/` or of fighting with `emberjs` for package names. -4) Use the `@ember-data` namespace without moving to the `@ember-data` org. - -* _argument for:_ Folks have come to expect the repository to live at `emberjs/data`, and this provides extra signal that the package is an official one. - -* _rebuttal:_ - * `github` does a great job of redirecting packages to new locations. We should provide as consistent an experience as possible (package name, import paths, package location etc. all being `@ember-data`) - - * `data` already presents a namespacing issue for folks that fork `ember-data` to contribute back (`data` being a generic package name, akin to having a package called `cli` or `website`). - -5) This RFC but with Adapters and Serializers broken out into the packages `@ember-data/json` `@ember-data/rest` `@ember-data/json-api`. +4) This RFC but with Adapters and Serializers broken out into the packages `@ember-data/json` `@ember-data/rest` `@ember-data/json-api`. * _argument for:_ grouping the adapter / serializer "by API spec" feels more natural and would allow for users to drop only the versions of adapters / serializer they don't require. From 900db99f111483406d17e3eb54c66f2d6958f391 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Fri, 30 Nov 2018 00:10:36 -0800 Subject: [PATCH 16/30] update paths --- text/0000-ember-data-packages.md | 96 +++++++++++++++++++++++--------- 1 file changed, 71 insertions(+), 25 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 151f4efe46..4ace7a5b17 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -117,33 +117,55 @@ The following modules would continue to live in a monorepo that (until further R - - - - + - + + + + + + + + + + + + + + + + + + + @@ -156,74 +178,77 @@ The following modules would continue to live in a monorepo that (until further R - + - + - + + + + - + - + - + - + - + - + - + - + - + - - @@ -238,22 +263,28 @@ The following modules would continue to live in a monorepo that (until further R - + - + + + + + + + + + - + - - - + @@ -432,6 +463,21 @@ There are a few public classes that are not exposed at all via `export` today. T * `PromiseBelongsTo` * `PromiseRecord` +## Migration + +Blueprints, guides, docs, and twiddle would be updated to use the new `@ember-data/` package imports. + +A codemod would be provided to convert from the existing import locations to the new ones, as well as lint rules for encouraging their use. + +The package `ember-data` would continue to exist, much like `ember-source`. Initially, this package would provide all of the subpackages + as dependencies as well as the respective re-exports for supporting the existing import paths. After a time, the existing paths would + be deprecated. + +Users who have resolved the deprecations may choose to convert to consuming only the packages they still require directly, + by dropping `ember-data` from their `package.json` and adding in the individual `@ember-data/` packages as necessary. + +Ultimately, the default `ember-data` story in `ember-cli` would change to install select packages from `@ember-data` directly. + ## How we teach this This RFC should be seen as a continuation of the `javascript-modules` RFC that defined explicit import paths for `emberjs`. From abfb015a3027d42dceedc1859480bd64005ea8f0 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Fri, 30 Nov 2018 12:04:36 -0800 Subject: [PATCH 17/30] cleanup adapter-errors package --- text/0000-ember-data-packages.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 4ace7a5b17..a3a733b329 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -191,64 +191,64 @@ The following modules would continue to live in a monorepo that (until further R - + - + - + - + - + - + - + - + - + - + - - From 1098bfecb406a2bc9d797855ba600f1ec2cd9be8 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 13:44:14 -0800 Subject: [PATCH 18/30] remove interfaces, in favor of a separate Typescript RFC --- text/0000-ember-data-packages.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index a3a733b329..61d69c16ba 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -149,24 +149,6 @@ The following modules would continue to live in a monorepo that (until further R
+ deprecate directly importing this class - - - - - - - - - - - - - - - - - - From 7c4834b74672333bb6aecbe17bea9808d5d91e70 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 13:48:49 -0800 Subject: [PATCH 19/30] update adapters structure following meeting with @tomdale --- text/0000-ember-data-packages.md | 33 +++++++++++++++----------------- 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 61d69c16ba..e5661cc4a1 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -155,82 +155,79 @@ The following modules would continue to live in a monorepo that (until further R - + - + - + - - - - + - + - + - + - + - + - + - + - + - + - - From a72f939a01dc21bf28dcc10d3e568938c797fa24 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 13:51:35 -0800 Subject: [PATCH 20/30] update serializers structure following meeting with @tomdale --- text/0000-ember-data-packages.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index e5661cc4a1..0f075edfa0 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -150,7 +150,7 @@ The following modules would continue to live in a monorepo that (until further R - + @@ -232,35 +232,32 @@ The following modules would continue to live in a monorepo that (until further R - + - + - + - + - - - - + - + From 27e61af1fa19a51e32713e7c047b2adac8fa7a63 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 13:52:40 -0800 Subject: [PATCH 21/30] remove transform exports and update default export following meeting with @tomdale --- text/0000-ember-data-packages.md | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 0f075edfa0..54c391e423 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -259,33 +259,10 @@ The following modules would continue to live in a monorepo that (until further R - - - - - - - - - - - - - - - - - - - - - - - - + From 2e539ad2c7e8fdd0a73161fbeaaf12a693522177 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 13:54:53 -0800 Subject: [PATCH 22/30] provide no future path for private imports --- text/0000-ember-data-packages.md | 35 -------------------------------- 1 file changed, 35 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 54c391e423..af1d05a695 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -114,41 +114,6 @@ The following modules would continue to live in a monorepo that (until further R - - - - - - - - - - - - - - - - - - - - - - - - - From 68c379103a3e4ac4d945e75159b9ad578e0588ce Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 14:08:24 -0800 Subject: [PATCH 23/30] remove things that will have no new import --- text/0000-ember-data-packages.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index af1d05a695..2f97431c6f 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -267,16 +267,6 @@ The following modules would continue to live in a monorepo that (until further R - - - - - - - - - - From 54527bc8aac01c0477918e9ef8168b314ec4d2aa Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 14:13:15 -0800 Subject: [PATCH 24/30] remove things that ought to be deprecated --- text/0000-ember-data-packages.md | 34 -------------------------------- 1 file changed, 34 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 2f97431c6f..e9e0faf815 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -182,20 +182,6 @@ The following modules would continue to live in a monorepo that (until further R - - - - - - - - - - @@ -267,13 +253,6 @@ The following modules would continue to live in a monorepo that (until further R - - - - - @@ -327,19 +306,6 @@ The following modules would continue to live in a monorepo that (until further R `app/` directory re-export for the package so that when the package is dropped they cleanly drop as well. -#### `@ember-data/store` - - 1) `_setupContainer` registers various adapters and serializers for fallbacks. - Either we need to deprecate this behavior (preferred), or separate out initialization - by package, or both. It also eagerly injects store, which we should deprecate but - can't until there is a `defaultStore` RFC for ember itself. - - 2) `_initializeStoreService` eagerly instantiates the store to ensure that `defaultStore` is our store. - we should get rid of this but can't until there is a `defaultStore` RFC for ember itself. - - 3) `normalizeModelName` is defined... very oddly. Why? We should probably deprecate this - and continue to move to a world in which less normalization of modelName is required. - #### `@ember-data/relationship-layer` This package seems thin but it's likely to hold quite a bit. From 486376f5c19e16befdd21659dc2d762ba1987045 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 14:17:10 -0800 Subject: [PATCH 25/30] Revert "remove things that ought to be deprecated" This reverts commit 54527bc8aac01c0477918e9ef8168b314ec4d2aa. --- text/0000-ember-data-packages.md | 34 ++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index e9e0faf815..2f97431c6f 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -182,6 +182,20 @@ The following modules would continue to live in a monorepo that (until further R + + + + + + + + + + @@ -253,6 +267,13 @@ The following modules would continue to live in a monorepo that (until further R + + + + + @@ -306,6 +327,19 @@ The following modules would continue to live in a monorepo that (until further R `app/` directory re-export for the package so that when the package is dropped they cleanly drop as well. +#### `@ember-data/store` + + 1) `_setupContainer` registers various adapters and serializers for fallbacks. + Either we need to deprecate this behavior (preferred), or separate out initialization + by package, or both. It also eagerly injects store, which we should deprecate but + can't until there is a `defaultStore` RFC for ember itself. + + 2) `_initializeStoreService` eagerly instantiates the store to ensure that `defaultStore` is our store. + we should get rid of this but can't until there is a `defaultStore` RFC for ember itself. + + 3) `normalizeModelName` is defined... very oddly. Why? We should probably deprecate this + and continue to move to a world in which less normalization of modelName is required. + #### `@ember-data/relationship-layer` This package seems thin but it's likely to hold quite a bit. From 2118d500ba4045a11b86a7fd608cfe3e206c7c1e Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 12 Dec 2018 14:17:35 -0800 Subject: [PATCH 26/30] keep removal of discussion of private things --- text/0000-ember-data-packages.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 2f97431c6f..6fd165f573 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -327,19 +327,6 @@ The following modules would continue to live in a monorepo that (until further R `app/` directory re-export for the package so that when the package is dropped they cleanly drop as well. -#### `@ember-data/store` - - 1) `_setupContainer` registers various adapters and serializers for fallbacks. - Either we need to deprecate this behavior (preferred), or separate out initialization - by package, or both. It also eagerly injects store, which we should deprecate but - can't until there is a `defaultStore` RFC for ember itself. - - 2) `_initializeStoreService` eagerly instantiates the store to ensure that `defaultStore` is our store. - we should get rid of this but can't until there is a `defaultStore` RFC for ember itself. - - 3) `normalizeModelName` is defined... very oddly. Why? We should probably deprecate this - and continue to move to a world in which less normalization of modelName is required. - #### `@ember-data/relationship-layer` This package seems thin but it's likely to hold quite a bit. From a9a2d4288650ba273718fe4c760dc9fd0a8a0ee6 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Tue, 18 Dec 2018 09:53:37 -0800 Subject: [PATCH 27/30] update drawbacks --- text/0000-ember-data-packages.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 6fd165f573..56b4aa8603 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -388,6 +388,8 @@ Ember documentation and guides would be updated to reflect these new import path ## Drawbacks * A Tiny amount of churn +* Sub-packages will require sprinkling significant numbers of excess package.json files throughout our repo. +* Our import paths may not align with the expected mental model for addon import paths going forward (no `/src/` in path) ## Alternatives From 02c7f0f0c0f8ea63795cecdc5d5d06c9304cf821 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 19 Dec 2018 13:52:04 -0800 Subject: [PATCH 28/30] add note on design considerations extending from the ember modules RFC --- text/0000-ember-data-packages.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index 56b4aa8603..ce42d28dc5 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -76,6 +76,13 @@ With the landing of `RecordData` and the merging of the `modelFactoryFor` RFC, i ## Detailed design +This RFC proposes import paths following the guidelines established in [Ember Modules RFC #176](https://github.com/emberjs/rfcs/pull/176), + with two addendums to account for scenarios that weren't faced by `ember`: +* `error` sub-classes are named exports +* `Mixins` are named exports + +This is done to allow for continued grouping by common usage and mental model, where otherwise users would be faced with multiple imports from length file paths. + The following modules would continue to live in a monorepo that (until further RFC) would continue to live at `github.com/ember/data`.
DS.Errors noneimport Errors from '@ember-data/model/errors';
+ 		import { Errors } from '@ember-data/model/-private';

+ deprecate directly importing this class
DS.PromiseManyArray noneimport PromiseManyArray from '@ember-data/model/promise-many-array';
+ 		import { PromiseManyArray } from '@ember-data/model/-private';

+ deprecate directly importing this class
DS.ManyArray noneimport ManyArray from '@ember-data/model/many-array';
+ 		import { ManyArray } from '@ember-data/model/-private';

+ deprecate directly importing this class
(@private) DS.InternalModel nonenoneimport { InternalModel } from '@ember-data/model/-private';
+
+ deprecate directly importing this class +
(@private) DS.RootState nonenoneimport { RootState } from '@ember-data/model/-private';
+
+ deprecate directly importing this class +

@ember-data/interfaces

n/an/aimport { Adapter } from '@ember-data/interfaces';
n/an/aimport { Serializer } from '@ember-data/interfaces';
n/an/aimport { RecordData } from '@ember-data/interfaces';

@ember-data/adapters

DS.RESTAdapter import RESTAdapter from 'ember-data/adapters/rest';import RESTAdapter from '@ember-data/adapters/rest';import { RESTAdapter } from '@ember-data/adapters';
DS.JSONAPIAdapter import JSONAPIAdapter from 'ember-data/adapters/json-api';import JSONAPIAdapter from '@ember-data/adapters/json-api';import { JSONAPIAdapter } from '@ember-data/adapters';
DS.BuildURLMixin noneimport BuildURLMixin from '@ember-data/adapters/mixins/build-url';import { BuildURLMixin } from '@ember-data/adapters';

@ember-data/adapter-errors
DS.AdapterError import { AdapterError } from 'ember-data/adapters/errors';import { AdapterError } from '@ember-data/adapters/errors';import { AdapterError } from '@ember-data/adapter-errors';
DS.InvalidError import { InvalidError } from 'ember-data/adapters/errors';import { InvalidError } from '@ember-data/adapters/errors';import { InvalidError } from '@ember-data/adapter-errors';
DS.TimeoutError import { TimeoutError } from 'ember-data/adapters/errors';import { TimeoutError } from '@ember-data/adapters/errors';import { TimeoutError } from '@ember-data/adapter-errors';
DS.AbortError import { AbortError } from 'ember-data/adapters/errors';import { AbortError } from '@ember-data/adapters/errors';import { AbortError } from '@ember-data/adapter-errors';
DS.UnauthorizedError import { UnauthorizedError } from 'ember-data/adapters/errors';import { UnauthorizedError } from '@ember-data/adapters/errors';import { UnauthorizedError } from '@ember-data/adapter-errors';
DS.ForbiddenError import { ForbiddenError } from 'ember-data/adapters/errors';import { ForbiddenError } from '@ember-data/adapters/errors';import { ForbiddenError } from '@ember-data/adapter-errors';
DS.NotFoundError import { NotFoundError } from 'ember-data/adapters/errors';import { NotFoundError } from '@ember-data/adapters/errors';import { NotFoundError } from '@ember-data/adapter-errors';
DS.ConflictError import { ConflictError } from 'ember-data/adapters/errors';import { ConflictError } from '@ember-data/adapters/errors';import { ConflictError } from '@ember-data/adapter-errors';
DS.ServerError import { ServerError } from 'ember-data/adapters/errors';import { ServerError } from '@ember-data/adapters/errors';import { ServerError } from '@ember-data/adapter-errors';
DS.errorsHashToArray noneimport { errorsHashToArray } from '@ember-data/adapters/errors';
+ 		import { errorsHashToArray } from '@ember-data/adapter-errors';

this public method should also be a candidate for deprecation
DS.errorsArrayToHash noneimport { errorsArrayToHashr } from '@ember-data/adapters/errors';
+ 		import { errorsArrayToHashr } from '@ember-data/adapter-errors';

this public method should also be a candidate for deprecation
DS.JSONSerializer import JSONSerializer from 'ember-data/serializers/json';import JSONSerializer from '@ember-data/serializers/json';import { JSONSerializer } from '@ember-data/serializers';
DS.RESTSerializer import RESTSerializer from 'ember-data/serializers/rest';import RESTSerializer from '@ember-data/serializers/rest';import { RESTSerializer } from '@ember-data/serializers';
DS.JSONAPISerializerimport JSONAPISerializer from 'ember-data/serializers/json-api';import { JSONAPISerializer } from '@ember-data/serializers';

@ember-data/embedded-records-mixin
DS.EmbeddedRecordsMixin import EmbeddedRecordsMixin from 'ember-data/serializers/embedded-records-mixin';import EmbeddedRecordsMixin from '@ember-data/serializers/rest/mixins/embedded-records';import EmbeddedRecordsMixin from '@ember-data/embedded-records-mixin';
DS.JSONAPISerializerimport JSONAPISerializer from 'ember-data/serializers/json-api';import JSONAPISerializer from '@ember-data/serializers/json-api';

@ember-data/transforms
DS.Transformimport { BuildURLMixin } from '@ember-data/adapters';

@ember-data/adapter-errors

@ember-data/adapter-error
DS.AdapterError import { AdapterError } from 'ember-data/adapters/errors';import { AdapterError } from '@ember-data/adapter-errors';import AdapterError from '@ember-data/adapter-error';
DS.InvalidError import { InvalidError } from 'ember-data/adapters/errors';import { InvalidError } from '@ember-data/adapter-errors';import { InvalidError } from '@ember-data/adapter-error';
DS.TimeoutError import { TimeoutError } from 'ember-data/adapters/errors';import { TimeoutError } from '@ember-data/adapter-errors';import { TimeoutError } from '@ember-data/adapter-error';
DS.AbortError import { AbortError } from 'ember-data/adapters/errors';import { AbortError } from '@ember-data/adapter-errors';import { AbortError } from '@ember-data/adapter-error';
DS.UnauthorizedError import { UnauthorizedError } from 'ember-data/adapters/errors';import { UnauthorizedError } from '@ember-data/adapter-errors';import { UnauthorizedError } from '@ember-data/adapter-error';
DS.ForbiddenError import { ForbiddenError } from 'ember-data/adapters/errors';import { ForbiddenError } from '@ember-data/adapter-errors';import { ForbiddenError } from '@ember-data/adapter-error';
DS.NotFoundError import { NotFoundError } from 'ember-data/adapters/errors';import { NotFoundError } from '@ember-data/adapter-errors';import { NotFoundError } from '@ember-data/adapter-error';
DS.ConflictError import { ConflictError } from 'ember-data/adapters/errors';import { ConflictError } from '@ember-data/adapter-errors';import { ConflictError } from '@ember-data/adapter-error';
DS.ServerError import { ServerError } from 'ember-data/adapters/errors';import { ServerError } from '@ember-data/adapter-errors';import { ServerError } from '@ember-data/adapter-error';
DS.errorsHashToArray noneimport { errorsHashToArray } from '@ember-data/adapter-errors';
+ 		import { errorsHashToArray } from '@ember-data/adapter-error';

this public method should also be a candidate for deprecation
DS.errorsArrayToHash noneimport { errorsArrayToHashr } from '@ember-data/adapter-errors';
+ 		import { errorsArrayToHashr } from '@ember-data/adapter-error';

this public method should also be a candidate for deprecation

@ember-data/interfaces

n/an/aimport { Adapter } from '@ember-data/interfaces';
n/an/aimport { Serializer } from '@ember-data/interfaces';
n/an/aimport { RecordData } from '@ember-data/interfaces';

@ember-data/adapters
DS.Adapter import Adapter from 'ember-data/adapter';import Adapter from '@ember-data/adapters';import Adapter from '@ember-data/adapter';
DS.RESTAdapter import RESTAdapter from 'ember-data/adapters/rest';import { RESTAdapter } from '@ember-data/adapters';import RESTAdapter from '@ember-data/adapter/rest';
DS.JSONAPIAdapter import JSONAPIAdapter from 'ember-data/adapters/json-api';import { JSONAPIAdapter } from '@ember-data/adapters';import JSONAPIAdapter from '@ember-data/adapter/json-api';
DS.BuildURLMixin noneimport { BuildURLMixin } from '@ember-data/adapters';

@ember-data/adapter-error

import { BuildURLMixin } from '@ember-data/adapter';
DS.AdapterError import { AdapterError } from 'ember-data/adapters/errors';import AdapterError from '@ember-data/adapter-error';import AdapterError from '@ember-data/adapter/error';
DS.InvalidError import { InvalidError } from 'ember-data/adapters/errors';import { InvalidError } from '@ember-data/adapter-error';import { InvalidError } from '@ember-data/adapter/error';
DS.TimeoutError import { TimeoutError } from 'ember-data/adapters/errors';import { TimeoutError } from '@ember-data/adapter-error';import { TimeoutError } from '@ember-data/adapter/error';
DS.AbortError import { AbortError } from 'ember-data/adapters/errors';import { AbortError } from '@ember-data/adapter-error';import { AbortError } from '@ember-data/adapter/error';
DS.UnauthorizedError import { UnauthorizedError } from 'ember-data/adapters/errors';import { UnauthorizedError } from '@ember-data/adapter-error';import { UnauthorizedError } from '@ember-data/adapter/error';
DS.ForbiddenError import { ForbiddenError } from 'ember-data/adapters/errors';import { ForbiddenError } from '@ember-data/adapter-error';import { ForbiddenError } from '@ember-data/adapter/error';
DS.NotFoundError import { NotFoundError } from 'ember-data/adapters/errors';import { NotFoundError } from '@ember-data/adapter-error';import { NotFoundError } from '@ember-data/adapter/error';
DS.ConflictError import { ConflictError } from 'ember-data/adapters/errors';import { ConflictError } from '@ember-data/adapter-error';import { ConflictError } from '@ember-data/adapter/error';
DS.ServerError import { ServerError } from 'ember-data/adapters/errors';import { ServerError } from '@ember-data/adapter-error';import { ServerError } from '@ember-data/adapter/error';
DS.errorsHashToArray noneimport { errorsHashToArray } from '@ember-data/adapter-error';
+ 		import { errorsHashToArray } from '@ember-data/adapter/error';

this public method should also be a candidate for deprecation
DS.errorsArrayToHash noneimport { errorsArrayToHashr } from '@ember-data/adapter-error';
+ 		import { errorsArrayToHash } from '@ember-data/adapter/error';

this public method should also be a candidate for deprecation

@ember-data/adapters

@ember-data/adapter
DS.Adapter

@ember-data/serializers

@ember-data/serializer
DS.Serializer import Serializer from 'ember-data/serializer';import Serializer from '@ember-data/serializers';import Serializer from '@ember-data/serializer';
DS.JSONSerializer import JSONSerializer from 'ember-data/serializers/json';import { JSONSerializer } from '@ember-data/serializers';import JSONSerializer from '@ember-data/serializer/json';
DS.RESTSerializer import RESTSerializer from 'ember-data/serializers/rest';import { RESTSerializer } from '@ember-data/serializers';import RESTSerializer from '@ember-data/serializer/rest';
DS.JSONAPISerializer import JSONAPISerializer from 'ember-data/serializers/json-api';import { JSONAPISerializer } from '@ember-data/serializers';

@ember-data/embedded-records-mixin

import JSONAPISerializer from '@ember-data/serializer/json-api';
DS.EmbeddedRecordsMixin import EmbeddedRecordsMixin from 'ember-data/serializers/embedded-records-mixin';import EmbeddedRecordsMixin from '@ember-data/embedded-records-mixin';import { EmbeddedRecordsMixin } from '@ember-data/serializer/rest';

@ember-data/transforms

import EmbeddedRecordsMixin from 'ember-data/serializers/embedded-records-mixin'; import { EmbeddedRecordsMixin } from '@ember-data/serializer/rest';

@ember-data/transforms

DS.Transform import Transform from 'ember-data/transform';import Transform from '@ember-data/transforms';
DS.DateTransformimport DateTransform from 'ember-data/transforms/date';import { DateTransform } from '@ember-data/transforms';
DS.StringTransformimport StringTransform from 'ember-data/transforms/string';import { StringTransform } from '@ember-data/transforms';
DS.NumberTransformimport NumberTransform from 'ember-data/transforms/number';import { NumberTransform } from '@ember-data/transforms';
DS.BooleanTransformimport BooleanTransform from 'ember-data/transforms/boolean';import { BooleanTransform } from '@ember-data/transforms';import Transform from '@ember-data/serializer/transform';

@ember-data/store

import { hasMany } from 'ember-data/relationships'; import { hasMany } from '@ember-data/model';
DS.Errorsnoneimport { Errors } from '@ember-data/model/-private';
-
+ deprecate directly importing this class -
DS.PromiseManyArraynoneimport { PromiseManyArray } from '@ember-data/model/-private';
-
+ deprecate directly importing this class -
DS.ManyArraynoneimport { ManyArray } from '@ember-data/model/-private';
-
+ deprecate directly importing this class -
(@private) DS.InternalModelnoneimport { InternalModel } from '@ember-data/model/-private';
-
+ deprecate directly importing this class -
(@private) DS.RootStatenoneimport { RootState } from '@ember-data/model/-private';
-
+ deprecate directly importing this class -

@ember-data/adapter
none none
DS._initializeStoreServiceimport initializeStoreService from 'ember-data/intialize-store-service';none
DS._setupContainerimport setupContainer from 'ember-data/setup-container';none
DS.normalizeModelName noneimport { ServerError } from 'ember-data/adapters/errors'; import { ServerError } from '@ember-data/adapter/error';
DS.errorsHashToArraynoneimport { errorsHashToArray } from '@ember-data/adapter/error';
-
this public method should also be a candidate for deprecation -
DS.errorsArrayToHashnoneimport { errorsArrayToHash } from '@ember-data/adapter/error';
-
this public method should also be a candidate for deprecation -

@ember-data/serializer
none none
DS.normalizeModelNamenoneimport { normalizeModelName } from 'ember-data/store';
-
this public method should be a candidate for deprecation -

@ember-data/record-data
import { ServerError } from 'ember-data/adapters/errors'; import { ServerError } from '@ember-data/adapter/error';
DS.errorsHashToArraynoneimport { errorsHashToArray } from '@ember-data/adapter/error';
+
this public method should also be a candidate for deprecation +
DS.errorsArrayToHashnoneimport { errorsArrayToHash } from '@ember-data/adapter/error';
+
this public method should also be a candidate for deprecation +

@ember-data/serializer
none none
DS.normalizeModelNamenoneimport { normalizeModelName } from 'ember-data/store';
+
this public method should be a candidate for deprecation +

@ember-data/record-data
From 9e6a58034775f63d4891820f1556c4389a3deb90 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 19 Dec 2018 13:55:44 -0800 Subject: [PATCH 29/30] cleanup notes --- text/0000-ember-data-packages.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index ce42d28dc5..d2106defcb 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -314,17 +314,18 @@ The following modules would continue to live in a monorepo that (until further R 1) `InternalModel` and `RootState` are tightly coupled to the store and to our provided `Model` implementation. Over time we need to uncouple this, but given their coupling to `Model` and our - desire to enable them to be eliminated from projects not using `Model`, these exports - belong in `@ember-data/model`. + desire to enable them to be eliminated from projects not using `Model`, these concepts belong in `@ember-data/model`, although they will not be given direct import paths. 2) The following belong in `@ember-data/model` and not in `@ember-data/relationship-layer` with relationships. While this presents a mild risk of confusion due to the presence of the - `relationship-layer` package, the argument for their presence here is they are a ui-layer concern - being coupled to the current `Model` presentation layer and not related to overall state management + `relationship-layer` package, the argument for their presence here is they are a ui-layer concern being coupled to the current `Model` presentation layer and not related to overall state management of relationships which could itself be used with alternative implementations. * `belongsTo` * `hasMany` + + 3) The following have the same considerations as #2 but they will not be given direct import paths. + * `PromiseManyArray` * `ManyArray` From d2b5cfb1a323bfd832cc9041e6f07e39525b57b2 Mon Sep 17 00:00:00 2001 From: Chris Thoburn Date: Wed, 19 Dec 2018 14:19:01 -0800 Subject: [PATCH 30/30] sp --- text/0000-ember-data-packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-ember-data-packages.md b/text/0000-ember-data-packages.md index d2106defcb..ac55fc0ca4 100644 --- a/text/0000-ember-data-packages.md +++ b/text/0000-ember-data-packages.md @@ -78,7 +78,7 @@ With the landing of `RecordData` and the merging of the `modelFactoryFor` RFC, i This RFC proposes import paths following the guidelines established in [Ember Modules RFC #176](https://github.com/emberjs/rfcs/pull/176), with two addendums to account for scenarios that weren't faced by `ember`: -* `error` sub-classes are named exports +* `Error` sub-classes are named exports * `Mixins` are named exports This is done to allow for continued grouping by common usage and mental model, where otherwise users would be faced with multiple imports from length file paths. @@ -325,7 +325,7 @@ The following modules would continue to live in a monorepo that (until further R * `hasMany` 3) The following have the same considerations as #2 but they will not be given direct import paths. - + * `PromiseManyArray` * `ManyArray`