relay-runtime 20.1.0 → 21.0.0

package/llm-docs/tutorial/interfaces-polymorphism.mdx

@@ -0,0 +1,161 @@
+# GraphQL Types, Interfaces, and Polymorphism
+
+In this section, we’ll see how to treat different types of nodes differently. You might notice that some of the newsfeed stories in the example app are posted by people, while others are posted by organizations. In this example, we'll enhance our hovercard by writing a fragment that selects people-specific information about people  and organization-specific information about organizations.
+
+* * *
+
+We’ve alluded to the fact that GraphQL nodes aren’t just random bags of fields — they have types. Your GraphQL schema defines what fields each type has. For instance, it might define the `Story` type like this:
+
+```
+type Story {
+  id: ID!
+  title: String
+  summary: String
+  createdAt: Date
+  poster: Actor
+  image: Image
+}
+```
+
+Here, some of the fields are scalars (like `String` and `ID`). Others are types defined elsewhere in the schema, like `Image` — these fields are edges to nodes of those specific types. The `!` on `ID!` means that field is non-nullable. In GraphQL, fields are normally nullable and non-nullability is the exception.
+
+Fragments are always “on” a particular type. In our example above, `StoryFragment` is defined `on Story`. This means that you can only spread it into places in a query where a `Story` node is expected. And it means that the fragment can select just those fields that exist on the `Story` type.
+
+Of particular interest is the `Actor` type used for the `poster` field. This type is an *interface*. That means that the `poster` of a story can be a Person, a Page, an Organization, or any other type of entity that meets the specifications for being an “Actor”.
+
+The GraphQL schema in our example app defines an Actor as follows:
+
+```
+interface Actor {
+  name: String
+  profilePicture: Image
+  joined: DateTime
+}
+```
+
+Not coincidentally this is exactly the information that we’re displaying here. There are two types in the schema that *implement* Actor, meaning that they include all the fields defined in Actor. They are declared as such:
+
+```
+type Person implements Actor {
+  id: ID!
+  name: String
+  profilePicture: Image
+  joined: DateTime
+  email: String
+  location: Location
+}
+
+type Organization implements Actor {
+  id: ID!
+  name: String
+  profilePicture: Image
+  joined: DateTime
+  organizationKind: OrganizationKind
+}
+```
+
+Both of these types have `name` , `profilePicture`, and `joined`, so they can both declare that they implement Actor and thus can be used wherever an Actor is called for in the schema and in fragments. They also have other fields that are distinct to each particular type.
+
+Let’s see how to work with interfaces more by extending the `PosterDetailsHovercardContentsBody` component to display the location of a `Person` or the organization kind of an `Organization`. These are fields that are only present on those specific types, not on the `Actor` interface.
+
+Right now, if you’ve followed along so far, it should have a fragment defined like this (in `PosterDetailsHovercardContents.tsx`):
+
+```
+fragment PosterDetailsHovercardContentsBodyFragment on Actor {
+  name
+  joined
+  profilePicture {
+    ...ImageFragment
+  }
+}
+```
+
+If you try to add a field like `organizationKind` to this fragment, you’ll get an error from the Relay compiler:
+
+```
+✖︎ The type `Actor` has no field organizationKind
+```
+
+This is because when we define a fragment as being on an interface, we can only use fields from that interface. To use fields from a specific type that implements the interface, we use a *type refinement* to tell GraphQL we’re selecting fields from that type:
+
+```
+fragment PosterDetailsHovercardContentsBodyFragment on Actor {
+  name
+  joined
+  profilePicture {
+    ...ImageFragment
+  }
+  // change
+  ... on Organization {
+    organizationKind
+  }
+  // end-change
+}
+```
+
+Go ahead and add this now. You can also add a type refinement for `Person`:
+
+```
+fragment PosterDetailsHovercardContentsBodyFragment on Actor {
+  name
+  joined
+  profilePicture {
+    ...ImageFragment
+  }
+  ... on Organization {
+    organizationKind
+  }
+  // change
+  ... on Person {
+    location {
+      name
+    }
+  }
+  // end-change
+}
+```
+
+When you select a field that’s only present on some of the types that implement an interface, and the node you’re dealing with is of a different type, then you simply get `null` for the value of that field when you read it out. With that in mind, we can modify the `PosterDetailsHovercardContentsBody` component to show the location of people and organization kind of organizations:
+
+```
+import OrganizationKind from './OrganizationKind';
+
+function PosterDetailsHovercardContentsBody({ poster }: Props): React.ReactElement {
+  const data = useFragment(PosterDetailsHovercardContentsBodyFragment, poster);
+  return (
+    <>
+      <Image image={data.profilePicture} width={128} height={128} className="posterHovercard__image" />
+      <div className="posterHovercard__name">{data.name}</div>
+      <ul className="posterHovercard__details">
+         <li>Joined <Timestamp time={poster.joined} /></li>
+         // change
+         {data.location != null && (
+           <li>{data.location.name}</li>
+         )}
+        {data.organizationKind != null && (
+          <li><OrganizationKind kind={data.organizationKind} /></li>
+         )}
+         // end-change
+      </ul>
+    </>
+  );
+}
+```
+
+You should now see the location of people, and the organization kind for organizations:
+
+![An organization hovercard](/img/docs/tutorial/interfaces-organization-screenshot.png) ![A person hovercard](/img/docs/tutorial/interfaces-person-screenshot.png)
+
+By the way, we can now understand why we had `... on Actor` in the example earlier. The `node` field can return a node of any type because any ID could be given at runtime. So the type that it gives us is `Node`, a very generic interface that can be implemented by anything that has an `id` field. We needed a type refinement to use fields from the `Actor` interface.
+
+:::note
+In the GraphQL spec and other sources, type refinements are called *inline fragments*. We call them “type refinements” instead because this terminology is more descriptive and less confusing.
+:::
+
+:::tip
+If you need to do something totally different depending on what type it is, you can select a field called `__typename`, which returns a string with the name of the concrete type that you got (e.g., `"Person"` or `"Organization"`). This is a built-in feature of GraphQL.
+:::
+
+## Summary
+
+The `... on Type {}` syntax allows us to select fields that are only present in a specific type that implements an interface.

package/llm-docs/tutorial/intro.mdx

@@ -0,0 +1,58 @@
+# Tutorial Intro
+
+This tutorial will get you started with the most important and frequently-used features of Relay. To do that, we’ll build a simple app that displays a newsfeed. We will cover:
+
+* How to fetch data using [Queries](./queries-1.mdx).
+* How to make components self-contained by breaking [Queries](./queries-1.mdx) into [Fragments](./fragments-1.mdx).
+
+This tutorial assumes a fair familiarity with React. If you’re still new to React, we suggest going through the [React tutorial](https://reactjs.org/tutorial/) and working with React until you’re comfortable with creating components, passing props, and using the basic hooks such as `useState`. The tutorial is based on the Web, but Relay also works great with React Native.
+
+This tutorial is built with TypeScript, so [very basic knowledge of TypeScript](https://www.typescriptlang.org/docs/) is helpful as well — you don’t need to know anything beyond declaring and importing types and annotating functions. Relay can also be used with the Flow type system or without a type system.
+
+:::info
+**IMPORTANT**: The tutorial is meant to be gone through in order, as the exercises build on each other. You’ll be making incremental changes to an example app, so later section won’t make sense if you haven’t done the earlier sections.
+:::
+
+## Setup
+
+To get started, run the following commands:
+
+```
+git clone https://github.com/relayjs/relay-examples.git
+cd relay-examples/newsfeed
+npm install
+npm run dev
+```
+
+This downloads a template project to get started from and starts the server. (If they don’t work, you may need to [install git](https://github.com/git-guides/install-git) or [install npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).)
+
+When you run `npm run dev`, several processes are started:
+
+* A Webpack-based HTTP server that serves up the front-end code.
+* A basic GraphQL server that that front-end will query to retrieve information.
+* The Relay compiler, which processes the GraphQL in your app and generates additional files that Relay uses at runtime, as well as TypeScript types representing the inputs and results of your queries. It will automatically regenerate when you save changes in your files.
+
+In the terminal output, these three processes’ log output are marked with tags: `[webpack]` in yellow, `[server]` in green, and `[relay]` in blue. Keep a look out for errors marked with `[relay]` as these are helpful if your GraphQL has any mistakes.
+
+If you encounter errors in the `[relay]` process indicating: ```[relay] thread 'main' panicked at 'Cannot run relay in watch mode if `watchman` is not available (or explicitly disabled).'```, this means watchman is not installed or available on your system. To resolve this, you may need to [install watchman separately](https://facebook.github.io/watchman/docs/install). After installing watchman, try running `npm run dev` again.
+
+Now that these processes are running, you should be able to open [http://localhost:3000](http://localhost:3000/) in your browser.
+
+![Screenshot](/img/docs/tutorial/intro-screenshot-placeholder.png)
+
+We start from a webpage that shows a single Newsfeed story rendered with React, but the data for that story is just placeholder data hard-coded into the React components. In the rest of this tutorial, we’ll make the app functional by having it fetch data from the server, paginate over multiple stories, and update the data by commenting and liking.
+
+## Folder Structure
+
+The files that make up the example app are laid out in this way:
+
+* `src/components` — the front-end app components that we’ll be modifying and working with. Some of the important components are:
+    * `App.tsx` — the top-level component
+    * `Newsfeed.tsx` — a component that will run a query to fetch newsfeed stories and display a scrolling list of stories
+    * `Story.tsx` — a component that shows a single newsfeed story.
+* `server` — a very basic GraphQL server that serves up example data
+    * `server/schema.graphql` — the GraphQL schema: it specifies what information can be queried from the server via GraphQL.
+
+Finally, you may want to install the [Relay VSCode extension](https://marketplace.visualstudio.com/items?itemName=meta.relay) for autocomplete, errors, and other help when using VSCode.
+
+Head over to the next section to start learning about GraphQL and Relay.