| + | + +[Making Requests →](./2-requests.md) + + | +
+ 💚 Fully Typed! +
+ +```ts +const { content } = await store.requestWhoops!
+{{error.message}}
+ + + + <:content as |result|> + Hello {{result.data.name}}! + + + <:loading as |state|> ++ diff --git a/guides/manual/1-overview.md b/guides/1-manual/11-about.md similarity index 75% rename from guides/manual/1-overview.md rename to guides/1-manual/11-about.md index c43afbe3a31..e8b3da7eab3 100644 --- a/guides/manual/1-overview.md +++ b/guides/1-manual/11-about.md @@ -1,25 +1,63 @@ -| | | -| -- | -- | -| [← Table of Contents](./0-index.md#table-of-contents) | [Making Requests →](./2-requests.md) | +
| + | + +[❖ Table of Contents](./0-index.md) -## Introduction + | -WarpDrive is a suite of features built around orchestrated data-fetching. ++ +[Overview →](./2-overview.md) + + | +
@@ -37,35 +75,19 @@ decades.
-## Why WarpDrive? - -WarpDrive is the data framework for building ambitious applications. +--- -What do we mean by ambitious? WarpDrive is ideal for applications looking to -be best-in-class: whether that's a small todo app, e-commerce, a -social app, or an enterprise b2b software solution. - -That's because WarpDrive is designed to seamlessly handle the hardest parts -of state management when building an app, helping you focus on creating the -features and user experiences that drive value. - -Our value goes beyond our feature set. WarpDrive embraces the platform, making it -quick to pickup the basics. Our patterns are portable and scalable, meaning that as -your app, team and data needs evolve we'll be right there with you. - -Because we are universal and also not tied to any API Format or backend architecture, -there's no lock-in. The data patterns you learn and the code you write is portable -between frontend frameworks and backend APIs and can help smooth the evolution of both. - -We're also not specific to a given frontend architecture. When serving on the same -domain, you can dedupe and cache requests across multiple apps and tabs at once! -This means we are as good for embedded content and MPAs as we are for SPAs. +
-Our core philosophy is to deliver value that lasts decades and evolves with your app, -helping you ship, iterate and deliver to your customers. +
| + |
- +[Overview →](./2-overview.md) -| | | -| -- | -- | -| [← Table of Contents](./0-index.md#table-of-contents) | [Making Requests →](./2-requests.md) | + |
+
| + +[← Introduction](./1-introduction.md) + + | ++ +[Key Data Structures →](./4-data.md) + + | +
+ 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ +```ts +const result = await store.request({ + url: '/api/users?search=Chris' +}) +``` + +```glimmer-ts +const UsersSearch = { + url: '/api/users?search=Chris' +}); + +export default +
-
+ {{#each result.data as |user|}}
+
- {{user.name}} + {{/each}} +
+ +*Run This Example* → [Request | Fetch Example](https://warpdrive.nullvoxpopuli.com/manual/requests/fetch) + +
+ +Data fetching is managed by a `RequestManager`, which executes handlers you provide. + +In order to make requests, first we create a `RequestManager` for our +application, and we tell it to fulfill requests using a `Fetch` handler. + +```ts +import RequestManager from '@ember-data/request'; +import { Fetch } from '@ember-data/request/fetch'; + +const manager = new RequestManager().use([Fetch]); +``` + +Now we can issue a request for a list of our users: + +```ts +const { content } = await manager.request({ url: '/users' }); + +for (const user of content.data) { + greet(`${user.firstName} ${user.lastName}`); +} +``` + +If we wanted to type the above request, we could supply a type for the +content returned by the request: + +```ts +type User = { + id: string; + firstName: string; + lastName: string; + age: number; +}; + +type UsersQuery = { + data: User[]; +} +``` + +And use it like this: + +```ts +const { content } = await manager.request
+ +### The Chain of Responsibility + +When we created the request manager for our application above, you may have noticed that when we told it to fulfill requests using the `Fetch` handler we did so by passing in an array: + +```ts +new RequestManager().use([Fetch]); +``` + +The request manager follows the [chain-of-responsibility pattern](https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern): each handler in our array may choose to fulfill the request, modify it, or pass it along unchanged to the next handler in the array, in array order. + + +```mermaid +--- +config: + theme: neutral +--- +flowchart LR + C(Handler 1) + C <==> D(Handler 2) + D <==> E(Handler 3) + C <--> F@{ shape: lin-cyl, label: "Source A" } + D <--> G@{ shape: lin-cyl, label: "Source B" } + E <--> H@{ shape: lin-cyl, label: "Source C" } +``` + + +A handler receives the request `context` as well as a `next` function with which to pass along +a request if it so chooses. + +```ts +type NextFn
diff --git a/guides/manual/3-data.md b/guides/1-manual/4-data.md similarity index 100% rename from guides/manual/3-data.md rename to guides/1-manual/4-data.md diff --git a/guides/manual/4-caching.md b/guides/1-manual/5-caching.md similarity index 100% rename from guides/manual/4-caching.md rename to guides/1-manual/5-caching.md diff --git a/guides/manual/5-presentation.md b/guides/1-manual/6-presentation.md similarity index 100% rename from guides/manual/5-presentation.md rename to guides/1-manual/6-presentation.md diff --git a/guides/manual/7-builders.md b/guides/1-manual/7-builders.md similarity index 100% rename from guides/manual/7-builders.md rename to guides/1-manual/7-builders.md diff --git a/guides/manual/6-schemas.md b/guides/1-manual/8-schemas.md similarity index 100% rename from guides/manual/6-schemas.md rename to guides/1-manual/8-schemas.md diff --git a/guides/1-manual/concepts/builders.md b/guides/1-manual/concepts/builders.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/handlers.md b/guides/1-manual/concepts/handlers.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/mutations.md b/guides/1-manual/concepts/mutations.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/normalization.md b/guides/1-manual/concepts/normalization.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/operations.md b/guides/1-manual/concepts/operations.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/reactive-control-flow.md b/guides/1-manual/concepts/reactive-control-flow.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/requests.md b/guides/1-manual/concepts/requests.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/schemas.md b/guides/1-manual/concepts/schemas.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/serialization.md b/guides/1-manual/concepts/serialization.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/concepts/transformation.md b/guides/1-manual/concepts/transformation.md new file mode 100644 index 00000000000..e69de29bb2d diff --git a/guides/1-manual/images/handlers-all-labeled.gif b/guides/1-manual/images/handlers-all-labeled.gif new file mode 100644 index 00000000000..fa9dd9d284d Binary files /dev/null and b/guides/1-manual/images/handlers-all-labeled.gif differ diff --git a/guides/1-manual/images/handlers-cloud-resolution.gif b/guides/1-manual/images/handlers-cloud-resolution.gif new file mode 100644 index 00000000000..74cd4b31689 Binary files /dev/null and b/guides/1-manual/images/handlers-cloud-resolution.gif differ diff --git a/guides/1-manual/images/handlers-early-resolution.gif b/guides/1-manual/images/handlers-early-resolution.gif new file mode 100644 index 00000000000..ce4dae20022 Binary files /dev/null and b/guides/1-manual/images/handlers-early-resolution.gif differ diff --git a/guides/1-manual/images/handlers-local-resolution.gif b/guides/1-manual/images/handlers-local-resolution.gif new file mode 100644 index 00000000000..4aad06b2973 Binary files /dev/null and b/guides/1-manual/images/handlers-local-resolution.gif differ diff --git a/guides/typescript/0-installation.md b/guides/2-typescript/0-installation.md similarity index 100% rename from guides/typescript/0-installation.md rename to guides/2-typescript/0-installation.md diff --git a/guides/typescript/1-configuration.md b/guides/2-typescript/1-configuration.md similarity index 100% rename from guides/typescript/1-configuration.md rename to guides/2-typescript/1-configuration.md diff --git a/guides/typescript/2-why-brands.md b/guides/2-typescript/2-why-brands.md similarity index 100% rename from guides/typescript/2-why-brands.md rename to guides/2-typescript/2-why-brands.md diff --git a/guides/typescript/3-typing-models.md b/guides/2-typescript/3-typing-models.md similarity index 100% rename from guides/typescript/3-typing-models.md rename to guides/2-typescript/3-typing-models.md diff --git a/guides/typescript/4-typing-requests.md b/guides/2-typescript/4-typing-requests.md similarity index 94% rename from guides/typescript/4-typing-requests.md rename to guides/2-typescript/4-typing-requests.md index e96cb184f16..8c71dafb96e 100644 --- a/guides/typescript/4-typing-requests.md +++ b/guides/2-typescript/4-typing-requests.md @@ -26,8 +26,7 @@ The signature for `request` will infer the generic for the content type from a s ```ts import type { RequestSignature } from '@warp-drive/core-types/symbols'; -import type { CollectionRecordArray } from '@ember-data/store/types'; -import type User from '../models/user'; +import type { User } from '../types/data/user'; type MyRequest { // ... diff --git a/guides/typescript/5-typing-includes.md b/guides/2-typescript/5-typing-includes.md similarity index 100% rename from guides/typescript/5-typing-includes.md rename to guides/2-typescript/5-typing-includes.md diff --git a/guides/typescript/index.md b/guides/2-typescript/index.md similarity index 100% rename from guides/typescript/index.md rename to guides/2-typescript/index.md diff --git a/guides/requests/examples/0-basic-usage.md b/guides/3-requests/examples/0-basic-usage.md similarity index 100% rename from guides/requests/examples/0-basic-usage.md rename to guides/3-requests/examples/0-basic-usage.md diff --git a/guides/requests/examples/1-auth.md b/guides/3-requests/examples/1-auth.md similarity index 89% rename from guides/requests/examples/1-auth.md rename to guides/3-requests/examples/1-auth.md index d19d7bece53..d7a0602e998 100644 --- a/guides/requests/examples/1-auth.md +++ b/guides/3-requests/examples/1-auth.md @@ -49,20 +49,15 @@ const AuthHandler: Handler = { } ``` -This handler would need to be added to request manager service configuration: +This handler would need to be added to the request manager configuration: ```ts import RequestManager from '@ember-data/request'; import Fetch from '@ember-data/request/fetch'; import AuthHandler from './auth-handler.js'; -export default class extends RequestManager { - constructor(args?: Record
- -### Fetch Example - -> [!TIP] -> When we want to show integration with a framework, this tutorial -> uses [EmberJS](https://emberjs.com), a powerful modern web framework with an established multi-decade legacy. - -
- -*Run This Example* → [Request | Fetch Example](https://warpdrive.nullvoxpopuli.com/manual/requests/fetch) - -
- -Data fetching is managed by a `RequestManager`, which executes handlers you provide. - -In order to make requests, first we create a `RequestManager` for our -application, and we tell it to fulfill requests using a `Fetch` handler. - -```ts -import RequestManager from '@ember-data/request'; -import { Fetch } from '@ember-data/request/fetch'; - -const manager = new RequestManager().use([Fetch]); -``` - -Now we can issue a request for a list of our users: - -```ts -const { content } = await manager.request({ url: '/users' }); - -for (const user of content.data) { - greet(`${user.firstName} ${user.lastName}`); -} -``` - -If we wanted to type the above request, we could supply a type for the -content returned by the request: - -```ts -type User = { - id: string; - firstName: string; - lastName: string; - age: number; -}; - -type UsersQuery = { - data: User[]; -} -``` - -And use it like this: - -```ts -const { content } = await manager.request
- -### The Chain of Responsibility - -When we created the request manager for our application above, you may have noticed that when we told it to fulfill requests using the `Fetch` handler we did so by passing in an array: - -```ts -new RequestManager().use([Fetch]); -``` - -The request manager follows the [chain-of-responsibility pattern](https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern): each handler in our array may choose to fulfill the request, modify it, or pass it along unchanged to the next handler in the array, in array order. - - -```mermaid ---- -config: - theme: neutral ---- -flowchart LR - C(Handler 1) - C <==> D(Handler 2) - D <==> E(Handler 3) - C <--> F@{ shape: lin-cyl, label: "Source A" } - D <--> G@{ shape: lin-cyl, label: "Source B" } - E <--> H@{ shape: lin-cyl, label: "Source C" } -``` - - -A handler receives the request `context` as well as a `next` function with which to pass along -a request if it so chooses. - -```ts -type NextFn
- -| | | -| -- | -- | -| [← Introduction](./1-overview.md) | [Key Data Structures →](./3-data.md) | diff --git a/packages/core-types/src/request.type-test.ts b/packages/core-types/src/request.type-test.ts new file mode 100644 index 00000000000..fce5601efb0 --- /dev/null +++ b/packages/core-types/src/request.type-test.ts @@ -0,0 +1,23 @@ +import type { RequestInfo } from './request'; +import type { RequestSignature } from './symbols'; + +type User = { + id: string; + name: string; +}; + +function myBuilder