Data: [QUEST] 🌲Project Trim 🌲

Created on 18 Jun 2019 · 7Comments · Source: emberjs/data

🌲 Project Trim🌲

As the Ember Community approaches delivery of long awaited features enabling tree-shaking, ember-data needs to take some steps to enable this feature to shed the weight of features that consuming applications do not use.

The first step is to ensure that the packages ember-data provides are properly encapsulated. In many cases, this will both enable support for tree-shaking once available to the broader community and enable manually opting for a subset of packages.

Later steps will ensure that ember-data relies on explicit imports (whether automatically generated at build-time or declared by consuming applications) where currently we rely on resolver lookups.

🌲 Use `ember-data` without `@ember-data/serializer`

The serializer package provides reference serializer implementations and a base serializer class that are not required for applications that choose to write a custom serializer implementing the minimal serializer interface. This includes the EmbeddedRecordsMixin and the base Transform class.

Transforms, while specified via attr available from @ember-data/model are a concept specific to these reference serializers and not used anywhere else within ember-data. Custom serializers thus may or may not choose to use them via the same mechanism (owner.lookup('transform:<name>')). Lastly the Transform base class merely shows the interface required for transforms but is not required to be used as a base class.

Action Items

[x] 🔒 ~#6113~ #6451 add a public Typescript interface for the minimal required serializer interface
[x] 🔒 #6086 eliminate registration of default transforms (use app re-exports instead)
[x] 🔒 #6086 eliminate injection of -default and -json-api serializer (use app re-exports instead)
[x] 🔒https://github.com/emberjs/rfcs/pull/522 deprecate -default serializer fallback in Store.serializerFor
[x] 🔒https://github.com/emberjs/rfcs/pull/522 deprecate Adapter.serializer and Adapter.defaultSerializer fallbacks (which currently default to -json-api.
[x] 🔒https://github.com/emberjs/rfcs/pull/522 deprecate Model.toJSON and support the scenario for quick debug-mode inspection via debugData() method which in DEBUG would print a similar object to the current toJSON method.
[x] implement serializer deprecations from https://github.com/emberjs/rfcs/pull/522
[x] 🔒 #6368 remove -rest serializer fallback usage in tests
[x] 🔒 #6369 #6370 remove -json-api serializer fallback usage in tests
[x] remove -default serializer fallback usage in tests
[x] add serializer encapsulation test
[x] (Side Quest) Add tests for the MinimumSerializerInterface (#6460 )

🌲 Use `ember-data` without `@ember-data/adapter`

The adapter package provides reference adapter implementations and a base adapter class that are not required for applications that choose to write a custom adapter implementing the minimal adapter interface.

Action Items

[x] add a public Typescript interface for the minimal required adapter interface
[x] eliminate injection of -rest and -json-api adapter (use re-export pattern for -json-api adapter)
[x] 🔒https://github.com/emberjs/rfcs/pull/522 deprecate Store.defaultAdapter (-json-api) and the -json-api adapter fallback behavior
[x] 🔒 #6353 eliminate -rest adapter which is only available for tests at this point unless consumers manually call adapterFor('-rest').
cleanup minimum required adapter interface
- [x] findMany is optional
- [x] findBelongsTo is optional
- [x] findHasMany is optional
- [x] shouldReloadRecord is optional
- [x] shouldBackgroundReloadRecord is optional
- [x] shouldReloadAll is optional
- [x] shouldBackgroundReloadAll is optional
[x] implement adapter deprecations from https://github.com/emberjs/rfcs/pull/522
[x] test for isInvalidError flag or specific message instead of instanceof InvalidError in store
[x] ensure internal usage of errorsArrayToHash uses the private store version
[x] (Side Quest) Add tests for the MinimumAdapterInterface

🌲 Use `ember-data` without `@ember-data/model`

While at the time of writing this quest @ember-data/model is the only model class available for use with ember-data based on public APIs, the introduction of custom Model Classes will mean that users who install @ember-data/model alternatives via addon or by writing their own should be able to consume ember-data without using a package which provides a model implementation they do not use.

Enabling use without @ember-data/model requires much more groundwork than that needed for the adapter and serializer package.

Model Action Items

[x] move the implementation of Model from the store package into the Model package.
[x] move the implementation of @hasMany and @belongsTo into the Model package.
[x] move -private/system/relationships/ext.js in @ember-data/store into the Model package
[x] move the implementation of ManyArray and PromiseManyArray into the Model package. See RFC notes
[x] move the implementation of PromiseBelongsTo into the Model package.
[x] inject the Model specific _modelForMixin implementation into the store from the Model package (this provides the multi-inheritance polymorphism feature which some aspects of ember-data currently support).
[x] deprecate BelongsToReference.push receiving a Model instance
[x] polish off the implementation of the Identifiers RFC.
- [ ] refactor conversion of Record to RecordIdentifier to occur within @belongsTo and @hasMany

InternalModel Action Items

[x] Deprecate/shim intimate Reference.internalModel property
[ ] Refactor Store.getReference to not lookup the associated InternalModel to generate the reference.
[x] Move the state-machine into the Model package.
[ ] Refactor store APIs to use identifiers instead of InternalModel
[x] Implement RecordData Errors RFC
[x] Implement Request State RFC.
[ ] Move InternalModel into the Model package.

InternalModel Cleanup Action Items

Once the items in InternalModel Action Items are complete, we can move the instantiation and lookup logic in the Store into the Model package.

[ ] create InternalModel only for @ember-data/model when using the instantiateRecord hook.
[ ] Eliminate any remaining Store._internalModelForId usage in favor of Identifier based logic.

🌲 Use `ember-data` without `@ember-data/relationship-layer`

The relationship-layer package is currently deeply entangled with @ember-data/model's Model implementation. Even though we can encapsulate the imports to/from these packages, users would not be able to use @ember-data/model without also using @ember-data/relationship-layer. Additionally, in its current form the relationship-layer is not abstracted away from the specifics of the implementation of Model making is largely unusable with other Model implementations. Changes to address this are needed but are outside the scope of this quest, and until such time as they occur users wishing to drop this package would need to drop both this and the Model package together.

[x] move everything within -private/system/relationships/state in @ember-data/store into a new relationship-layer package. See RFC notes
[ ] Move belongsToReference and HasManyReference into relationship-layer from store.
[x] refactor usage of internalModel to pull information from the RecordIdentifier or the Store for type id hasRecord and getRecord()
[ ] introduce a private -request-manager service for the store to use to refactor our current network request flows onto
[ ] isolate relationship fetching logic (currently spread across dozens of private store methods) into a private middleware to be used by the private -request-manager service
[ ] isolate coalescing logic into a private middleware to be used by the private -request-manager service (related to relationships due to how some relationship codepaths flow through it, but should not be part of the relationship-layer package)

🌲 Use `ember-data` without `@ember-data/debug`

Provides the DataAdapter for the ember-inspector

[x] refactor to use service injection, kill initializer injection
[x] refactor to manage own registration
[x] detect should not require Model
[x] stop automatically shipping to production (ship by config only)
[x] Add documentation for shipping the inspector in production if desired
[x] Add Encapsulation Test

🌲 Use `ember-data` without `@ember-data/record-data`

Provides the default RecordData implementation

[x] move RecordData into this package
[ ] (stretch goal) Land RecordDataV2
[ ] (stretch goal) Public Docs for RecordData
[x] hook into store package to implement createRecordDataFor
[x] Add Encapsulation Test
- [ ] (stretch goal) Move RecordData interface tests into the encapsulation test app

Misc

[x] 🔒 #6357 kill createStore and setupStore
- #6353 allow incremental removal of these helpers
- #6356 make removal easier to review
- #6361 remove some usage of setupStore
- #6347 remove all createStore usage
- #6221 remove some usage
- #6386 remove createStore
[x] 🔒 #6353 deprecate injection of -default serializer if moduleFor style tests are still supported
- [x] 🔒 #6353 lazily register and the -default serializer when this condition is detected

🌲 Tree Shaking Strategy

embroider is pursuing a strategy in which consuming applications opt in to enabling tree-shaking of specific kinds of features once they have determined for their own application that this is allowable.

To this end, users of ember-data would also opt in to tree shaking, possibly on a per-primitive basis.

Models - build time generated imports, nothing would be shaken except when possible for users opting into the "megamorphic model" case once that becomes available.

[ ] generation of static import file to keep embroider happy

Adapters/Serializers - in the near-term, deprecating various fallbacks will allow us to shake out the implementations provided by default once tree-shaking is enabled more generally. Here, as with models, we would generate at build time a list of the user's adapters as a list of static imports. Any default implementations not imported by user adapters would then be dropped.

In the long-term, adapters would be deprecated in favor of user-supplied network middlewares. Such middlewares, including those provided by addons, would be imported and registered with the request-manager service directly. Since these are static imports being registered to a service, in the long term no custom infrastructure would be needed to support tree-shaking.

Also in the long-term, serializers would be deprecated in favor of either their corresponding "adapter" replacement handling these concerns or in favor of middlewares specific to normalization and serialization concerns. Similarly, in the long term no custom infra for ensuring static imports for tree-shaking needs would be required.

[ ] generation of static import file to keep embroider happy
[ ] generation of static import file to keep embroider happy

Transforms - There are three ways for a user to utilize a transform today: attr(<transformName>), owner.lookup('transform:<transformName>') and direct import of a transform followed by Transform.create(). Of these, the third already plays nicely with tree-shaking. For attr and lookup usage we will need to enforce "static string usage" for lookup and and attr(), at which point we can use this to generate an import file of only those transforms that are actually in-use.

Also note, if none of the default serializers is in use and there is no project usage of lookup('transform:<transformName>') then it is likely we can drop all transforms even when referenced by attr.

[ ] deprecate non-static strings for lookup and attr
[ ] generation of static import file of lookup and attr transform usages

DefaultRecordData/DefaultModel - we would export our default setup within the app/ directory. An end user or addon configuring their own Model or RecordData would result in overriding this.