Browse
From 777a724d7a297f1255eea73e663b5bc2ee40a01f Mon Sep 17 00:00:00 2001
From: Kirill Shaplyko
Date: Wed, 28 Feb 2024 22:39:01 +0100
Subject: [PATCH 06/20] Updates after 5.3.1 release verification. Also should
address most of review comments
---
guides/drafts/incremental-adoption-guide.md | 55 ++++++++++++++++-----
1 file changed, 43 insertions(+), 12 deletions(-)
diff --git a/guides/drafts/incremental-adoption-guide.md b/guides/drafts/incremental-adoption-guide.md
index dd496c9dc76..425b66b0d5a 100644
--- a/guides/drafts/incremental-adoption-guide.md
+++ b/guides/drafts/incremental-adoption-guide.md
@@ -12,33 +12,37 @@ This version of EmberData is the first version that supports the new APIs. It is
## Step 2: Add `Store` service to your application
-You will need to create your own store service. Before, a store service was automatically injected by EmberData.
+You will need to create your own store service. Before, a store service was automatically injected by EmberData.
Here is how you do it:
-```ts
+```js
// eslint-disable-next-line ember/use-ember-data-rfc-395-imports
import Store from 'ember-data/store';
import { service } from '@ember/service';
-import RequestManager from '@ember-data/request';
export default class MyStore extends Store {
- @service declare requestManager: RequestManager;
+ @service requestManager;
}
```
Notice we still want to import the `Store` class from `ember-data/store` package. You might have a lint rule that says don't do it. You can disable it for this import. The reason we want to import it from `ember-data/store` is because we want to use EmberData models, serializers, adapters, etc. while alongside we want to start utilizing new APIs.
+>> Note: You can also use `@ember-data/store` package, but you will need to configure a lot more to make things work to use old APIs. We recommend using `ember-data/store` package to avoid confusion.
+>> Note: Because we are extending `ember-data/store`, it is still v1 addon, so things might not work for you if you are using typescript. We recommend to have `store.js` file for now.
+
## Step 3: Add `RequestManager` service to your application
-Now let's create our very own `RequestManager` service. It is a service that is responsible for sending requests to the server. It is a composable class, which means you can add your own request handlers to it. In the example below we are adding `LegacyNetworkHandler`, `TestHandler` and `Fetch` handlers.
+Now let's create our very own `RequestManager` service. It is a service that is responsible for sending requests to the server. It is a composable class, which means you can add your own request handlers to it.
+
+First you need to install [`@ember-data/request`](https://github.com/emberjs/data/tree/main/packages/request) and [`@ember-data/legacy-compat`](https://github.com/emberjs/data/tree/main/packages/legacy-compat) packages. First contains the `RequestManager` service and a few request handlers, second has `LegacyNetworkHandler` that gonna handle all old-style `this.store.*` calls.
+
+Here is how your own `RequestManager` service may look like:
-```ts
+```js
import RequestManager from '@ember-data/request';
import Fetch from '@ember-data/request/fetch';
import { LegacyNetworkHandler } from '@ember-data/legacy-compat';
-import { CacheHandler } from 'ember-data/store';
-import { setBuildURLConfig } from '@ember-data/request-utils';
const TestHandler = {
async request({ request }, next) {
@@ -56,7 +60,6 @@ export default class Requests extends RequestManager {
constructor(args) {
super(args);
this.use([LegacyNetworkHandler, TestHandler, Fetch]);
- this.useCache(CacheHandler);
}
}
```
@@ -69,13 +72,17 @@ Let's go over the code above:
3. Lastly `Fetch`. It is a handler that sends requests to the server using the `fetch` API. It expects responses to be JSON and when in use it should be the last handler you put in the chain. After finishing each request it will convert the response into json and pass it back to the handlers chain in reverse order as the request context's response. So `TestHandler` will receive `response` property first, and so on if we would have any.
-You can read more about request manager in the [request manager guide](./request-manager-guide.md).
+>> NOTE: Your `RequestManager` service should be exactly `app/services/request-manager.[js|ts]` file. It is a convention that Ember uses to find the service.
+
+You can read more about request manager in the [request manager guide](../requests/index.md).
## Step 4: Install `@ember-data/json-api`, `@ember-data/request-utils` packages
-If you were using JSON:API adapter/serializer for your backend communication, you can use `@ember-data/json-api` package. It is a package that contains predefined builders for JSON:API requests. You can read more about it in the [`@ember-data/json-api` guide](TODO: add link).
+If you were using JSON:API adapter/serializer for your backend communication, you can use `@ember-data/json-api` package. It is a package that contains predefined builders for JSON:API requests. You can read more about it in the [`@ember-data/json-api`](https://github.com/emberjs/data/tree/main/packages/json-api).
+
+If you have different backend format - EmberData provides you with builders for `REST`([`@ember-data/rest`](https://github.com/emberjs/data/tree/main/packages/rest)) and `ActiveRecord`([`@ember-data/active-record`](https://github.com/emberjs/data/tree/main/packages/active-record)).
-If you have different backend format - EmberData provides you with builders for `REST`(@ember-data/rest) and `ActiveRecord`(@ember-data/active-record).
+`@ember-data/request-utils` package contains a lot of useful utilities for building requests. You can read more about it in its [Readme](https://github.com/emberjs/data/tree/main/packages/request-utils#readme). It has request builders for all type of requests.
## Step 5: Off you go! Start using new APIs
@@ -113,3 +120,27 @@ export default class AuthHandler {
}
```
+You can read more about auth topic [here](../requests/auth.md).
+
+Another good thing to do is to configure default host and namespace for your requests. There is an utility for that out of the box of `@ember-data/request-utils` called [`setBuildURLConfig`](https://github.com/emberjs/data/blob/main/packages/request-utils/src/index.ts#L67). You can do it anywhere in your app theoretically, but we recommend doing it in the `app/app.js` file. Here is how you can do it:
+
+```diff app/app.js
+import Application from '@ember/application';
+import Resolver from 'ember-resolver';
+import loadInitializers from 'ember-load-initializers';
+import config from 'base-ember-typescript-app/config/environment';
++import { setBuildURLConfig } from '@ember-data/request-utils';
+
+export default class App extends Application {
+ modulePrefix = config.modulePrefix;
+ podModulePrefix = config.podModulePrefix;
+ Resolver = Resolver;
+}
+
+loadInitializers(App, config.modulePrefix);
+
++setBuildURLConfig({
++ host: 'https://api.example.com',
++ namespace: 'v1',
++});
+```
From 489178f3fcaee9216574c7313ffc16776ec29daa Mon Sep 17 00:00:00 2001
From: Kirill Shaplyko
Date: Wed, 28 Feb 2024 22:47:12 +0100
Subject: [PATCH 07/20] MD fixes for notes
---
guides/drafts/incremental-adoption-guide.md | 9 +++++----
1 file changed, 5 insertions(+), 4 deletions(-)
diff --git a/guides/drafts/incremental-adoption-guide.md b/guides/drafts/incremental-adoption-guide.md
index 425b66b0d5a..d965f384f45 100644
--- a/guides/drafts/incremental-adoption-guide.md
+++ b/guides/drafts/incremental-adoption-guide.md
@@ -28,13 +28,14 @@ export default class MyStore extends Store {
Notice we still want to import the `Store` class from `ember-data/store` package. You might have a lint rule that says don't do it. You can disable it for this import. The reason we want to import it from `ember-data/store` is because we want to use EmberData models, serializers, adapters, etc. while alongside we want to start utilizing new APIs.
->> Note: You can also use `@ember-data/store` package, but you will need to configure a lot more to make things work to use old APIs. We recommend using `ember-data/store` package to avoid confusion.
->> Note: Because we are extending `ember-data/store`, it is still v1 addon, so things might not work for you if you are using typescript. We recommend to have `store.js` file for now.
+> Note: You can also use `@ember-data/store` package, but you will need to configure a lot more to make things work to use old APIs. We recommend using `ember-data/store` package to avoid confusion.
+
+> Note: Because we are extending `ember-data/store`, it is still v1 addon, so things might not work for you if you are using typescript. We recommend to have `store.js` file for now.
## Step 3: Add `RequestManager` service to your application
Now let's create our very own `RequestManager` service. It is a service that is responsible for sending requests to the server. It is a composable class, which means you can add your own request handlers to it.
-
+
First you need to install [`@ember-data/request`](https://github.com/emberjs/data/tree/main/packages/request) and [`@ember-data/legacy-compat`](https://github.com/emberjs/data/tree/main/packages/legacy-compat) packages. First contains the `RequestManager` service and a few request handlers, second has `LegacyNetworkHandler` that gonna handle all old-style `this.store.*` calls.
Here is how your own `RequestManager` service may look like:
@@ -72,7 +73,7 @@ Let's go over the code above:
3. Lastly `Fetch`. It is a handler that sends requests to the server using the `fetch` API. It expects responses to be JSON and when in use it should be the last handler you put in the chain. After finishing each request it will convert the response into json and pass it back to the handlers chain in reverse order as the request context's response. So `TestHandler` will receive `response` property first, and so on if we would have any.
->> NOTE: Your `RequestManager` service should be exactly `app/services/request-manager.[js|ts]` file. It is a convention that Ember uses to find the service.
+> NOTE: Your `RequestManager` service should be exactly `app/services/request-manager.[js|ts]` file. It is a convention that Ember uses to find the service.
You can read more about request manager in the [request manager guide](../requests/index.md).
From d0d9e951fa1591614cacc0b50b3e66f362b0d36c Mon Sep 17 00:00:00 2001
From: Kirill Shaplyko
Date: Sat, 2 Mar 2024 10:46:16 +0100
Subject: [PATCH 08/20] Typing request manager
---
.../app/services/request-manager.ts | 18 +++++++-----------
1 file changed, 7 insertions(+), 11 deletions(-)
diff --git a/tests/incremental-json-api/app/services/request-manager.ts b/tests/incremental-json-api/app/services/request-manager.ts
index 94afeaf220e..2f7bd3bd5c1 100644
--- a/tests/incremental-json-api/app/services/request-manager.ts
+++ b/tests/incremental-json-api/app/services/request-manager.ts
@@ -1,14 +1,15 @@
import { LegacyNetworkHandler } from '@ember-data/legacy-compat';
+import type { Handler, NextFn, RequestContext } from '@ember-data/request';
import RequestManager from '@ember-data/request';
import Fetch from '@ember-data/request/fetch';
-// import { CacheHandler } from '@ember-data/store';
-const TestHandler = {
- async request({ request }, next) {
- console.log('TestHandler.request', request);
- const newContext = await next(Object.assign({}, request));
+/* eslint-disable no-console */
+const TestHandler: Handler = {
+ async request(context: RequestContext, next: NextFn) {
+ console.log('TestHandler.request', context.request);
+ const newContext = await next(Object.assign({}, context.request));
console.log('TestHandler.response after fetch', newContext.response);
- return newContext;
+ return newContext as T;
},
};
@@ -16,10 +17,5 @@ export default class Requests extends RequestManager {
constructor(args) {
super(args);
this.use([LegacyNetworkHandler, TestHandler, Fetch]);
-
- // TODO: This fails due to implementation in Store. It always adds cache.
- // Maybe we should change implementation, or just warn about not adding it
-
- // this.useCache(CacheHandler);
}
}
From e7aecb717a6a53a07a4fcae93cc97add3a50120f Mon Sep 17 00:00:00 2001
From: Kirill Shaplyko
Date: Sat, 2 Mar 2024 10:46:25 +0100
Subject: [PATCH 09/20] Create cookbook folder in guides
---
.../incremental-adoption-guide.md | 21 +++++++++----------
guides/cookbook/index.md | 3 +++
guides/index.md | 1 +
3 files changed, 14 insertions(+), 11 deletions(-)
rename guides/{drafts => cookbook}/incremental-adoption-guide.md (95%)
create mode 100644 guides/cookbook/index.md
diff --git a/guides/drafts/incremental-adoption-guide.md b/guides/cookbook/incremental-adoption-guide.md
similarity index 95%
rename from guides/drafts/incremental-adoption-guide.md
rename to guides/cookbook/incremental-adoption-guide.md
index d965f384f45..0c1b140c4e7 100644
--- a/guides/drafts/incremental-adoption-guide.md
+++ b/guides/cookbook/incremental-adoption-guide.md
@@ -40,20 +40,19 @@ First you need to install [`@ember-data/request`](https://github.com/emberjs/dat
Here is how your own `RequestManager` service may look like:
-```js
+```ts
+import { LegacyNetworkHandler } from '@ember-data/legacy-compat';
+import type { Handler, NextFn, RequestContext } from '@ember-data/request';
import RequestManager from '@ember-data/request';
import Fetch from '@ember-data/request/fetch';
-import { LegacyNetworkHandler } from '@ember-data/legacy-compat';
-
-const TestHandler = {
- async request({ request }, next) {
- console.log('TestHandler.request', request);
-
- const newContext = await next(request);
+/* eslint-disable no-console */
+const TestHandler: Handler = {
+ async request(context: RequestContext, next: NextFn) {
+ console.log('TestHandler.request', context.request);
+ const newContext = await next(Object.assign({}, context.request));
console.log('TestHandler.response after fetch', newContext.response);
-
- return next(newContext);
+ return newContext as T;
},
};
@@ -103,7 +102,7 @@ Now you can start refactoring old code to use new APIs. You can start with the `
You most likely would need to add Auth Handler to your request manager to add `accessToken` to your requests.
Let's say you have your `accessToken` in the `session` service. Here is how you can add it to the request manager:
-```js auth-handler.js
+```js
import { inject as service } from '@ember/service';
export default class AuthHandler {
diff --git a/guides/cookbook/index.md b/guides/cookbook/index.md
new file mode 100644
index 00000000000..53df945e865
--- /dev/null
+++ b/guides/cookbook/index.md
@@ -0,0 +1,3 @@
+# Cookbook
+
+- [Incremental Adoption Guide](./incremental-adoption-guide.md)
diff --git a/guides/index.md b/guides/index.md
index 08f5c6c731c..0a7f07f0a53 100644
--- a/guides/index.md
+++ b/guides/index.md
@@ -3,3 +3,4 @@
- [Relationships](./relationships/index.md)
- [Requests](./requests/index.md)
- [Terminology](./terminology.md)
+- [Cookbook](./cookbook/index.md)
From 0d2ef7a361fcf2dd716122703bc1c9ce16782a02 Mon Sep 17 00:00:00 2001
From: Kirill Shaplyko
Date: Sun, 10 Mar 2024 14:08:13 +0100
Subject: [PATCH 10/20] Move around setBuildUrlConfig
---
guides/cookbook/incremental-adoption-guide.md | 10 +++++-----
tests/incremental-json-api/app/app.ts | 7 +++++++
tests/incremental-json-api/app/routes/application.ts | 6 ------
3 files changed, 12 insertions(+), 11 deletions(-)
diff --git a/guides/cookbook/incremental-adoption-guide.md b/guides/cookbook/incremental-adoption-guide.md
index 0c1b140c4e7..eb6f73c5909 100644
--- a/guides/cookbook/incremental-adoption-guide.md
+++ b/guides/cookbook/incremental-adoption-guide.md
@@ -130,6 +130,11 @@ import Resolver from 'ember-resolver';
import loadInitializers from 'ember-load-initializers';
import config from 'base-ember-typescript-app/config/environment';
+import { setBuildURLConfig } from '@ember-data/request-utils';
++
++setBuildURLConfig({
++ host: 'https://api.example.com',
++ namespace: 'v1',
++});
export default class App extends Application {
modulePrefix = config.modulePrefix;
@@ -138,9 +143,4 @@ export default class App extends Application {
}
loadInitializers(App, config.modulePrefix);
-
-+setBuildURLConfig({
-+ host: 'https://api.example.com',
-+ namespace: 'v1',
-+});
```
diff --git a/tests/incremental-json-api/app/app.ts b/tests/incremental-json-api/app/app.ts
index 8f235d166e6..270d3147ca9 100644
--- a/tests/incremental-json-api/app/app.ts
+++ b/tests/incremental-json-api/app/app.ts
@@ -2,9 +2,16 @@ import Application from '@ember/application';
import loadInitializers from 'ember-load-initializers';
+import { setBuildURLConfig } from '@ember-data/request-utils';
+
import config from './config/environment';
import Resolver from './resolver';
+setBuildURLConfig({
+ host: '/',
+ namespace: 'api',
+});
+
class App extends Application {
modulePrefix = config.modulePrefix;
podModulePrefix = config.podModulePrefix;
diff --git a/tests/incremental-json-api/app/routes/application.ts b/tests/incremental-json-api/app/routes/application.ts
index 6d7aef1f86f..9a120ca6823 100644
--- a/tests/incremental-json-api/app/routes/application.ts
+++ b/tests/incremental-json-api/app/routes/application.ts
@@ -2,7 +2,6 @@ import Route from '@ember/routing/route';
import { service } from '@ember/service';
import { query } from '@ember-data/json-api/request';
-import { setBuildURLConfig } from '@ember-data/request-utils';
import type Store from '@ember-data/store';
import type { Document } from '@ember-data/store/-private/document';
@@ -10,11 +9,6 @@ import type Author from '../models/author';
import type Book from '../models/book';
import type Genre from '../models/genre';
-setBuildURLConfig({
- host: '/',
- namespace: 'api',
-});
-
export default class ApplicationRoute extends Route {
@service declare store: Store;
From e8c486f2636464f8ac0cf632c4b7deafdaee4d9f Mon Sep 17 00:00:00 2001
From: Kirill Shaplyko
Date: Mon, 11 Mar 2024 15:34:37 +0100
Subject: [PATCH 11/20] Update layout for test app, make it look like rest of
columns
---
.../app/templates/application.hbs | 22 +++++++++++--------
1 file changed, 13 insertions(+), 9 deletions(-)
diff --git a/tests/incremental-json-api/app/templates/application.hbs b/tests/incremental-json-api/app/templates/application.hbs
index 353016a51c8..df905f4190f 100644
--- a/tests/incremental-json-api/app/templates/application.hbs
+++ b/tests/incremental-json-api/app/templates/application.hbs
@@ -2,14 +2,7 @@
-
- Old Books{{@model.oldBooks.length}} |
-
- {{#each @model.oldBooks as |book|}}
- {{book.title}}
- {{/each}}
- |
-
+
Browse
@@ -23,4 +16,15 @@
|
-{{outlet}}
\ No newline at end of file
+{{outlet}}
+
+ Old Books({{@model.oldBooks.length}})
+
+ {{#each @model.oldBooks as |book|}}
+ -
+ {{book.title}} ({{book.genre}}) - {{book.publicationDate}}
+
by {{book.author}} ISBN: {{book.isbn}}
+
+ {{/each}}
+
+
\ No newline at end of file
From 43bcb68d4a9a020ba0dc0897eff6befe59f41df3 Mon Sep 17 00:00:00 2001
From: Kirill Shaplyko
Date: Mon, 11 Mar 2024 21:25:06 +0100
Subject: [PATCH 12/20] Add more legacy examples, update layout
---
.../app/components/legacy-infinite-books.hbs | 15 ++++++
.../app/components/legacy-infinite-books.ts | 48 +++++++++++++++++++
tests/incremental-json-api/app/models/book.ts | 3 ++
.../app/routes/application.ts | 14 ++++--
.../app/templates/application.hbs | 37 +++++++++-----
5 files changed, 102 insertions(+), 15 deletions(-)
create mode 100644 tests/incremental-json-api/app/components/legacy-infinite-books.hbs
create mode 100644 tests/incremental-json-api/app/components/legacy-infinite-books.ts
diff --git a/tests/incremental-json-api/app/components/legacy-infinite-books.hbs b/tests/incremental-json-api/app/components/legacy-infinite-books.hbs
new file mode 100644
index 00000000000..f88275006ad
--- /dev/null
+++ b/tests/incremental-json-api/app/components/legacy-infinite-books.hbs
@@ -0,0 +1,15 @@
+
+
+ {{book.title}} ({{book.genre}}) - {{book.publicationDate}}
+
by {{book.author}} ISBN: {{book.isbn}}
+
+
\ No newline at end of file
diff --git a/tests/incremental-json-api/app/components/legacy-infinite-books.ts b/tests/incremental-json-api/app/components/legacy-infinite-books.ts
new file mode 100644
index 00000000000..151b40a1aea
--- /dev/null
+++ b/tests/incremental-json-api/app/components/legacy-infinite-books.ts
@@ -0,0 +1,48 @@
+import { service } from '@ember/service';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import type Store from '@ember-data/store';
+import type { Collection } from '@ember-data/store/-private/record-arrays/identifier-array';
+
+import type Book from '../models/book';
+
+export interface InfiniteBookSignature {
+ Element: HTMLUListElement;
+ Args: {
+ allBooks: Collection;
+ };
+}
+
+class Pages {
+ @tracked pages: Collection[] = [];
+ @tracked data: T[] = [];
+
+ constructor(page: Collection) {
+ this.pages = [page];
+ this.data = page.slice();
+ }
+
+ addPage(page: Collection) {
+ this.pages.push(page);
+ this.data = this.data.concat(page);
+ }
+}
+
+export default class InfiniteBookComponent extends Component {
+ @service declare store: Store;
+ pageCollection = new Pages(this.args.allBooks);
+
+ get books(): Book[] {
+ return this.pageCollection.data;
+ }
+
+ next = async () => {
+ const meta = this.pageCollection.pages.at(-1)?.query as { page: number; pageSize: number };
+ if (!meta) {
+ return;
+ }
+ const result = await this.store.query('book', { page: meta.page + 1, pageSize: meta.pageSize });
+ this.pageCollection.addPage(result);
+ };
+}
diff --git a/tests/incremental-json-api/app/models/book.ts b/tests/incremental-json-api/app/models/book.ts
index b1044c5d710..0cf69b427ea 100644
--- a/tests/incremental-json-api/app/models/book.ts
+++ b/tests/incremental-json-api/app/models/book.ts
@@ -1,4 +1,5 @@
import Model, { attr } from '@ember-data/model';
+import { ResourceType } from '@warp-drive/core-types/symbols';
export default class Book extends Model {
@attr declare title: string;
@@ -6,4 +7,6 @@ export default class Book extends Model {
@attr declare publicationDate: string;
@attr declare author: string;
@attr declare genre: string;
+
+ [ResourceType] = 'book' as const;
}
diff --git a/tests/incremental-json-api/app/routes/application.ts b/tests/incremental-json-api/app/routes/application.ts
index 9a120ca6823..480a77d19ae 100644
--- a/tests/incremental-json-api/app/routes/application.ts
+++ b/tests/incremental-json-api/app/routes/application.ts
@@ -15,16 +15,24 @@ export default class ApplicationRoute extends Route {
override async model() {
const genres = this.store.request>({ url: '/api/books/genres' });
const authors = this.store.request>({ url: '/api/books/authors' });
- const books = this.store.request>(query('book'));
+
+ // Example of legacy usage to be refactored, unpaginated
const oldBooks = this.store.findAll('book');
- const data = await Promise.all([genres, authors, books, oldBooks]);
+ // Example of legacy usage, paginated
+ const oldBooksPaginated = this.store.query('book', { page: 1, pageSize: 20 });
+
+ // Example of new usage (refactored, paginated)
+ const books = this.store.request>(query('book'));
+
+ const data = await Promise.all([genres, authors, books, oldBooks, oldBooksPaginated]);
return {
genres: data[0].content.data!,
authors: data[1].content.data!,
allBooks: data[2].content,
- oldBooks: Array.from(data[3]),
+ oldBooks: data[3],
+ oldBooksPaginated: data[4],
};
}
}
diff --git a/tests/incremental-json-api/app/templates/application.hbs b/tests/incremental-json-api/app/templates/application.hbs
index df905f4190f..1d4539f2c5f 100644
--- a/tests/incremental-json-api/app/templates/application.hbs
+++ b/tests/incremental-json-api/app/templates/application.hbs
@@ -16,15 +16,28 @@
|