Updated how we describe injecting Ember Data store

[ijlee2]

Description

Through a Discord conversation, I realized that we didn't explain well when a developer needs to inject the Ember Data store service:

Developer: Hello all. Just a quick Q: I’m using this.store in my model() without injecting it as a service and it’s all working as expected. Am I missing something or am I just lucky? (I’ve just seen that the docs inject as a service)

I also noticed that the Zoey says has a Markdown typo (we unfortunately have to manually provide a <code> tag).

How to Review

I recommend reviewing commits one by one. Each commit makes the same type of change across different versions, starting with Ember 3.15 (Octane).

References

• https://guides.emberjs.com/release/routing/specifying-a-routes-model/#toc_ember-data-example
• https://guides.emberjs.com/release/models/#toc_the-store-and-a-single-source-of-truth (see the Zoey says... towards the end)
• https://github.com/emberjs/data/blob/v3.21.1/packages/-ember-data/addon/setup-container.js#L44-L48

[ijlee2]

Because the reader hasn't seen the code yet, I thought it'd be better to move this paragraph (an afterthought about Model vs. model()) after we present the code.

[jenweber]

I very vaguely recall that we did the store injection on purpose in the code samples, and I don’t remember why. Could you reach out to the dev-ember-data channel to get feedback on this? Thanks! The wording changes seem great regardless.

[acorncom]

From what I remember, the Ember Data team would like to move away from having the store injected automatically in all the places. Long term, switching to specified injection (vs automated injection) likely leads to less error prone tree-shaking as app authors have “opted in” more clearly to using the store service

[ijlee2]

Jen and David, thanks for providing feedback and additional context.

I think it makes sense that, in Octane and going forward, we will want developers to begin practicing being more explicit with dependency injection. At the same time, I wonder if, until initializeStoreInjections can be removed from Ember Data (code), it'd be better for Ember Guides to document what's current common practice.

As an intermediate step, I think we can also consider the option of reviewing all pages in the Ember Guides (in v3.15 and above), to ensure that the injection of store occurs whenever there's a reference to this.store and Ember Data. What I wouldn't want is for some pages to show injection of store service and others not, which may confuse developers.

Yep, I will reach out to the #dev-ember-data channel and ask for more feedback. Thanks again!

[acorncom]

At the same time, I wonder if, until initializeStoreInjections can be removed from Ember Data (code), it'd be better for Ember Guides to document what's current common practice.

@ijlee2 I think given the end desire expressed by the Ember Data team at the very end of the issue here (emberjs/data#6166) it’s probably wiser to be steering community members toward the new best practices that we want them to be using in the future.

But yes, fully agreed that it should be standardized

[ijlee2]

@acorncom Sounds good! When I get a chance, I'll check which pages don't currently show store injection. It's possible that all pages do and I can just revert the change that I made in this PR.

[ijlee2]

I ran git grep -n store inside the source/release directory. Afterwards, I visited the relevant pages to see if we need to add @service store.

There are several places where we encourage implicit store injection. In a few other places, including the Super Rentals Tutorial, we do practice explicit store injection. Probably let's change implicit to explicit in a separate PR?

• Routing - Defining Your Routes

  • app/routes/some-route.js

• Routing - Specifying a Route's Model

  • app/routes/songs.js
  • app/routes/album/index.js
  • app/routes/album.js

• Routing - Loading / Error Substates

  • app/routes/slow-model.js
  • app/routes/user-slow-model.js
  • app/routes/articles-overview.js

• Routing - Query Parameters

  • app/routes/articles.js

• Ember Data - Introduction

  • "Routes and their corresponding controllers can ask the store for models ..."
  • "Both routes and their corresponding controllers have access to this shared store ..."
  • Zoey says... "Ember Data injects the store service in every route and controller, so you can access it as this.store!"

• Ember Data - Creating, Updating and Deleting

  • The subsection Creating Records mentions that the store object is available in controllers and routes.

• Ember Data - Pushing Records into the Store

  • app/routes/confirm-payment.js

• Ember Data - Handling Metadata

  • app/routes/users.js

[ijlee2]

Closed by mistake.

[jenweber]

This looks good to me! I am not totally clear on whether you wanted to do more work on this before merging, so I'm not merging yet. Feel free to push the green button if you are ready!

[ijlee2]

Thanks! I'll merge this PR and make a separate issue that asks for injecting the store service explicitly.