Docs: Add guide for incremental adoption

[Baltazore]

Description

Working on guides for incremental adoption of new APIs of EmberData

Rendered

Notes for the release

guide for incremental adoption

[runspired]

Overall looking good, left some small cleanups

[fry69]

• ember-data/store (without the @) does not export CacheHandler, only @ember-data/store does, so the import { CacheHandler } line in the RequestManager service should be changed
• import { setBuildURLConfig } seems to be unused and get marked as such by the linter

[fry69]

I also do not know how much hand-holding is needed here, but maybe it should be mentioned that the RequestManager service must be in the file app/services/request-manager.js or the @service declaration in the Store service won't find it without explicitly referring to it (e.g. @service('requests') for app/service/requests.js).

[Baltazore]

hey @fry69 thanks for review and testing, good inputs - I will update accordingly
Also please keep in mind there code here not works just yet, some fixes were made, but not yet released, especially around service injection area.

[fry69]

The goal is to get this working, right? IMHO nothing is more frustrating that simple sample code which does not work. I just want to point out some pitfalls, here are some others:

• @ember-data/json-api in the version 4.12.x does not seem to have a query() in the /request -> Could not find module @ember-data/json-api/request imported from (require)
• @ember-data/request-utils does not exist for 4.12.x
• host: config.api.host inside the JSON:API query() (using EmberData 5.3) does not set the host for said query, it still talks to localhost (my old style adapter based queries work fine with the same config)
• host: config.api.host seems to get respected if I put it into a call to setBuildURLConfig() inside the constructor() of /app/app.js
• console.log() from TestHandler never show up even if my request now flows through this new service (and fails because of a missing API key, so it is clearly not using the old, working flow/store)?
• even if I completely clear the this.use() array in the RequestManager, my request still comes through (and fails because of missing said API key), which leads me to believe the store service is not using the new RequestManager at all, but a different one, the @service does not seem to be enough in this case?
• it seems to work with 5.3.0 and current alpha.22 preview release IF the code from RequestManager gets moved into the store service, otherwise I get RequestManager.useCache(<handler>) May only be invoked once errors

This the store.js that works for me:

// eslint-disable-next-line ember/use-ember-data-rfc-395-imports
import Store from 'ember-data/store';
import { CacheHandler } from '@ember-data/store';
import RequestManager from '@ember-data/request';
import Fetch from '@ember-data/request/fetch';
import { LegacyNetworkHandler } from '@ember-data/legacy-compat';

const APIKeyHandler = {
  request({ request }, next) {
    console.log('APIKeyHandler() called');
    const headers = new Headers(request.headers);
    headers.append(
      // see AuthHandler example
    );

    return next(Object.assign({}, request, { headers }));
  }
}

export default class MyStore extends Store {
  requestManager: RequestManager;

  constructor(args) {
    super(args);
    this.requestManager = new RequestManager;
    this.requestManager.use([LegacyNetworkHandler, APIKeyHandler, Fetch]);
    this.requestManager.useCache(CacheHandler);
  }
}

[fry69]

Latest version looks great, thank you @Baltazore

[Baltazore]

@runspired where do we put it? I need to update the location of file, and then fix nav links. But overall I think this is ready

[sly7-7]

Above this is recommended to call this function in app/app.js, for consistency, maybe it would be better to use the recommandation ?

[Baltazore]

same as above, up to change still

[runspired]

app.js makes the most sense

[Baltazore]

@sly7-7 thanks for review, would need to finalize some questions

[Baltazore]

same as above, up to change still

[Baltazore]

@runspired apparently I don't know how to use github (only gitlab on work 😄 )
I left some questions last week, but to submit those questions I should have click a button that only visible in diff view 🤦

[sly7-7]

@Baltazore Did you just do a rebase ?

[Baltazore]

@Baltazore Did you just do a rebase ?

yes, have I lost something ?

[sly7-7]

I don't think so, actually I was speaking with @runspired and he asked me if I could make the rebase, because he wanted to merge :)

[sly7-7]

@runspired, @Baltazore has been quickier 😄 so I guess you can merge