= ({ order: orderStatusOrError }) =>
192 | orderStatusOrError.__typename === 'OrderStatus' ? (
193 |
194 | {orderStatusOrError.deliveryDispatched
195 | ? 'Your order has been dispatched.'
196 | : 'Your order has not been dispatched yet.'}
197 |
198 | ) : (
199 |
200 | {orderStatusOrError.code === 'unpublished'
201 | ? 'Please contact gallery services.'
202 | : `An unexpected error occurred: ${orderStatusOrError.message}`}
203 |
204 | );
205 |
206 | export const OrderStatusContainer = createFragmentContainer(
207 | OrderStatus,
208 | graphql`
209 | fragment OrderStatus_order on Order {
210 | orderStatusOrError {
211 | __typename
212 | ... on OrderStatus {
213 | deliveryDispatched
214 | }
215 | ... on OrderError {
216 | message
217 | code
218 | }
219 | }
220 | }
221 | `,
222 | );
223 | ```
224 |
225 | There are some complications and unanswered questions though:
226 |
227 | - GraphQL interface cannot implement other interface ([RFC](https://github.com/facebook/graphql/pull/373))
228 | - scalars cannot be part of the union ([RFC](https://github.com/facebook/graphql/issues/215))
229 | - mutations can fail with multiple errors - how to handle it with this pattern? (possible solution: https://github.com/artsy/artsy.github.io/issues/495#issuecomment-466517039)
230 | - Relay `@connection` cannot be used with the union directly ([more details](https://github.com/artsy/artsy.github.io/issues/495#issuecomment-465667460)), solution: https://github.com/facebook/relay/issues/1983#issuecomment-467153713
231 |
232 | Interesting little helper:
233 |
234 | ```js
235 | const dataByTypename = (data) => (data && data.__typename ? { [data.__typename]: data } : {});
236 | ```
237 |
238 | Usage:
239 |
240 | ```js
241 | const { OrderError, OrderStatus } = dataByTypename(orderStatusOrError);
242 | if (OrderError) {
243 | // render error component
244 | }
245 | // render OrderStatus component
246 | ```
247 |
248 | Source: https://github.com/artsy/artsy.github.io/issues/495#issuecomment-509697859
249 |
250 | ## Recursive queries
251 |
252 | > Take Reddit as an example since it's close to this hypothetical nested comments example. They don't actually query to an unknown depth when fetching nested comments. Instead, they eventually bottom out with a "show more comments" link which can trigger a new query fetch. The technique I illustrated in a prior comment allows for this maximum depth control.
253 |
254 | [source](https://github.com/facebook/graphql/issues/91#issuecomment-254895093)
255 |
256 | ```graphql
257 | {
258 | messages {
259 | ...CommentsRecursive
260 | }
261 | }
262 |
263 | fragment CommentsRecursive on Message {
264 | comments {
265 | ...CommentFields
266 | comments {
267 | ...CommentFields
268 | comments {
269 | ...CommentFields
270 | comments {
271 | ...CommentFields
272 | comments {
273 | ...CommentFields
274 | comments {
275 | ...CommentFields
276 | comments {
277 | ...CommentFields
278 | comments {
279 | ...CommentFields
280 | }
281 | }
282 | }
283 | }
284 | }
285 | }
286 | }
287 | }
288 | }
289 |
290 | fragment CommentFields on Comment {
291 | id
292 | content
293 | }
294 | ```
295 |
296 | > GraphQL doesn't support recursive fragments by design, as this could allow unbounded data-fetching. Relay goes a bit further and offers support for recursion, but it still has to be terminated - you can use @argumentDefinitions to define a boolean value that is used to conditionally include the same fragment, passing @arguments to change the condition. But the recursion still has to terminate statically - e.g. you can have a fixed number of levels of recursion.
297 |
298 | [source](https://github.com/facebook/relay/issues/1998#issuecomment-548147456)
299 |
300 | ```js
301 | graphql`
302 | fragment QuickActivities_recursive on Lead
303 | @argumentDefinitions(recurse: { type: "Boolean", defaultValue: false }) {
304 | id
305 | ... @include(if: $recurse) {
306 | ...QuickActivities_recursive
307 | }
308 | }
309 | `;
310 |
311 | export default createFragmentContainer(XYZ, {
312 | lead: graphql`
313 | fragment QuickActivities_lead on Lead {
314 | id
315 | ...QuickActivities_recursive @arguments(recurse: true)
316 | }
317 | `,
318 | });
319 | ```
320 |
321 | ## A/B testing in GraphQL
322 |
323 | GraphQL has `@include` and `@skip` directives defined by default. There directives can be used for A/B testing like this for example:
324 |
325 | ```graphql
326 | fragment MyLocation on Location {
327 | name
328 | type
329 | countryFlagURL
330 | }
331 |
332 | query ($first: Int! = 10, $abTestEnabled: Boolean! = true) {
333 | allLocations(first: $first) {
334 | edges {
335 | node {
336 | ...MyLocation
337 | id_A: code @include(if: $abTestEnabled)
338 | id_B: id(opaque: false) @skip(if: $abTestEnabled)
339 | }
340 | }
341 | }
342 | }
343 | ```
344 |
345 | Interestingly, you can use inline fragments to include/skip the whole block of fields like this:
346 |
347 | ```graphql
348 | query ($first: Int! = 10, $abTestEnabled: Boolean! = true) {
349 | allLocations(first: $first) {
350 | edges {
351 | node {
352 | id
353 | ... @include(if: $abTestEnabled) {
354 | name
355 | slug
356 | type
357 | }
358 | }
359 | }
360 | }
361 | }
362 | ```
363 |
364 | Such inline fragments (without type condition or even without the directive) are allowed per specification (see: https://graphql.github.io/graphql-spec/draft/#sec-Inline-Fragments). Bonus tip: Relay handles this kind of fragment and generates Flow type correctly, for example:
365 |
366 | ```js
367 | /*
368 | query PollingQuery(
369 | $abTestEnabled: Boolean!
370 | ) {
371 | currency(code: "usd") {
372 | rate
373 | code @include(if: $abTestEnabled)
374 | format @include(if: $abTestEnabled)
375 | id
376 | }
377 | }
378 | */
379 | export type PollingQueryResponse = {|
380 | +currency: ?{|
381 | +rate: ?number,
382 | +code?: ?string, // note it's optional
383 | +format?: ?string, // note it's optional
384 | |},
385 | |};
386 | ```
387 |
388 | Therefore server can return you dynamic response even though Relay generates the meta files statically.
389 |
--------------------------------------------------------------------------------
/docs/relay.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: relay
3 | title: Relay all-in
4 | sidebar_label: Relay all-in
5 | ---
6 |
7 | :::note
8 | This file describes experimental and more advanced Relay features. It can be very unstable due to its nature so be careful. _Here be dragons!_ 🐉
9 | :::
10 |
11 | TODO:
12 |
13 | - https://github.com/c0m1t/relay-enum-generator
14 | - Mock Data Generation: https://github.com/facebook/relay/commit/09d317943f6936ffb0002154c389b6d7a507c58d
15 | - `renderPolicy`: https://github.com/facebook/relay/commit/b1cf05de8770122b30d491c4265df01e161e67c9 (partial/full)
16 | - New GC release buffer: https://github.com/mrtnzlml/relay/pull/126/commits/6ed264413ba8cdd586d695e5ed234951ee9eca13
17 | - [complex arguments with nested variables are now supported](https://github.com/facebook/relay/commit/5da3be070283c6dcd42774ba33c1590db65fe3c7)
18 | - HTTP persister example: https://github.com/facebook/relay/commit/aaa9588e081d3591ad8d043e924cacfadc06ec80
19 | - special `__id` field
20 | - special `__token` field (https://github.com/facebook/relay/commit/018af6da244e1242833e1bd89e8762c1409bee6d)
21 | - https://github.com/relay-tools/relay-connection-handler-plus (use-case: https://github.com/facebook/relay/issues/3065)
22 | - entrypoints: [prepareEntryPoint](https://github.com/facebook/relay/blob/master/packages/relay-experimental/prepareEntryPoint.js#L26), [EntryPointContainer](https://github.com/facebook/relay/blob/master/packages/relay-experimental/EntryPointContainer.react.js) + tests
23 | - https://github.com/jstejada/relay-session
24 | - https://github.com/maraisr/relay-sentry
25 | - https://github.com/relay-tools/typescript-relayjs-examples/issues/1
26 |
27 | > There are different tradeoffs across completeness, consistency, and performance, and there isn't one approach that is appropriate for every app. Relay focuses on cases where consistency matters: if you don't need consistency then a simpler/lighter solution can be more appropriate. ([source](https://github.com/facebook/relay/issues/2237#issuecomment-525420993))
28 |
29 | ## Useful Links (learning resources)
30 |
31 | - https://github.com/adeira/relay-example
32 | - https://github.com/sibelius/relay-modern-network-deep-dive
33 | - https://medium.com/entria/wrangling-the-client-store-with-the-relay-modern-updater-function-5c32149a71ac
34 | - https://twitter.com/sseraphini/status/1078595758801203202
35 | - https://relay-modern-course.now.sh/packages/
36 | - https://github.com/zth/relay-utils
37 | - https://github.com/zth/reason-relay
38 |
39 | ## Relay Developer Tools
40 |
41 | You can find Relay Devtools here: https://chrome.google.com/webstore/detail/relay-developer-tools/ncedobpgnmkhcmnnkcimnobpfepidadl/related
42 |
43 | Don't confuse them with the old devtools. This version is the new one:
44 |
45 | 
46 |
47 | There is also a community fork worth trying: https://github.com/oslabs-beta/protostar-relay
48 |
49 | Alternatively, you can also access the store directly (similarly to how the devtools are doing) from your dev console. To do so, you simply need to register a `__RELAY_DEVTOOLS_HOOK__` **before** creating your Relay Environment:
50 |
51 | ```js
52 | if (
53 | process.env.NODE_ENV === 'development' &&
54 | window.__RELAY_DEVTOOLS_HOOK__ === undefined &&
55 | window.__RELAY__ === undefined
56 | ) {
57 | window.__RELAY_DEVTOOLS_HOOK__ = {
58 | registerEnvironment: (environment: Environment) => {
59 | window.__RELAY__ = {
60 | store: (dataID: string | null = null) => {
61 | const source = environment.getStore().getSource();
62 | if (dataID === null) {
63 | return source.toJSON();
64 | }
65 | return source.get(dataID);
66 | },
67 | };
68 | },
69 | };
70 | }
71 | ```
72 |
73 | The usage is simple: call `__RELAY__.store()` from your console _or_ call it with some record ID which is in the store `__RELAY__.store('client:root')`. Both of these calls should print the Relay Store content or the single record content respectively.
74 |
75 | ## What is `__isNode`?
76 |
77 | The `__isNode` field here is fetched so that Relay can determine whether the object that is returned (whose type we don't know statically) implements the `Node` interface or not. The mutation will be transformed as follows:
78 |
79 | ```graphql
80 | mutation SidebarLayoutMarkAsSeenMutation($leadID: ID!) @raw_response_type {
81 | updateLead(input: { id: $leadID, wasSeen: true }) {
82 | wasSeen
83 | ... on Node {
84 | __isNode: __typename # if this field is present, we know the return type implements `Node`
85 | id
86 | }
87 | }
88 | }
89 | ```
90 |
91 | So your optimistic response should include `__isNode: 'Lead'` if the type implements Node, or exclude that key if the type does not implement Node.
92 |
93 | Source: https://github.com/facebook/relay/issues/3129#issuecomment-659439154 (Thanks [@josephsavona](https://github.com/josephsavona)!)
94 |
95 | ## Enabling feature flags
96 |
97 | There are several feature flags hidden in Relay Runtime (obviously a geeky thing) and you can enable them like this:
98 |
99 | ```js
100 | require('relay-runtime').RelayFeatureFlags.ENABLE_PRECISE_TYPE_REFINEMENT = true;
101 | ```
102 |
103 | The latest Relay (master) has [these feature flags](https://github.com/facebook/relay/blob/90c81bbd404bee718707f32b7b959a24d0d5b72a/packages/relay-runtime/util/RelayFeatureFlags.js) to this date:
104 |
105 | ```js
106 | const RelayFeatureFlags = {
107 | ENABLE_VARIABLE_CONNECTION_KEY: false,
108 | ENABLE_PARTIAL_RENDERING_DEFAULT: false,
109 | ENABLE_RELAY_CONTAINERS_SUSPENSE: false,
110 | ENABLE_PRECISE_TYPE_REFINEMENT: false,
111 | ENABLE_REACT_FLIGHT_COMPONENT_FIELD: false,
112 | ENABLE_REQUIRED_DIRECTIVES: false,
113 | ENABLE_GETFRAGMENTIDENTIFIER_OPTIMIZATION: false,
114 | };
115 | ```
116 |
117 | Source: https://github.com/facebook/relay/issues/3126#issuecomment-658438527
118 |
119 | ## GraphQL types without ID field
120 |
121 | Ever wondered how are GraphQL types being stored inside Relay Store when the types doesn't have globally unique `ID!` according to GraphQL specification? Here is an example of 2 identical stores _with_ and _without_ the ID: https://gist.github.com/mrtnzlml/e77315a6879ce8de26fe2a164872be09
122 |
123 | Basically, Relay will try to use the `ID` field when available (preferable). However, when it's not available, it will construct some unique key which represents the record correctly. Here is an example of the record _with_ ID:
124 |
125 | ```json
126 | {
127 | "QWxsSG90ZWxBdmFpbGFiaWxpdHlIb3RlbDo0NTA5Njk1": {
128 | "__id": "QWxsSG90ZWxBdmFpbGFiaWxpdHlIb3RlbDo0NTA5Njk1",
129 | "__typename": "AllHotelAvailabilityHotel",
130 | "id": "QWxsSG90ZWxBdmFpbGFiaWxpdHlIb3RlbDo0NTA5Njk1",
131 | "name": "Sweet Inn Apartments - Rocafort"
132 | }
133 | }
134 | ```
135 |
136 | And here is it _without_ the `ID`:
137 |
138 | ```json
139 | {
140 | "client:root:allAvailableBookingComHotels(search:{\"checkin\":\"2020-02-13\",\"checkout\":\"2020-02-15\",\"cityId\":\"SG90ZWxDaXR5Oi0zNzI0OTA=\",\"roomsConfiguration\":[{\"adultsCount\":2}]}):edges:0:node": {
141 | "__id": "client:root:allAvailableBookingComHotels(search:{\"checkin\":\"2020-02-13\",\"checkout\":\"2020-02-15\",\"cityId\":\"SG90ZWxDaXR5Oi0zNzI0OTA=\",\"roomsConfiguration\":[{\"adultsCount\":2}]}):edges:0:node",
142 | "__typename": "AllHotelAvailabilityHotel",
143 | "name": "Sweet Inn Apartments - Rocafort"
144 | }
145 | }
146 | ```
147 |
148 | As you can see, the ID is composed of the query itself + the path. Moreover, there are also GraphQL arguments which ensures you will always get the correct record (forementioned Relay consistency).
149 |
150 | ## Future of `QueryRenderer`/`useQuery` pattern
151 |
152 | > In general we're planning to move away from the QueryRenderer/useQuery pattern, which we're referring to as "fetch-on-render". This design makes behavior unpredictable (rendering can happen arbitrarily due to changes in parent components, suspense can cause re-renders and doesn't guarantee cleanup). The alternative is "fetch-then-render" - perform your data-fetching based on some event (user interaction, navigation, timer, app initialization) and then consume that result during render. Then "how do i refetch?" has the same answer as "how do i fetch?". Expect to see more API changes in this direction.
153 |
154 | Source: https://github.com/facebook/relay/issues/2864#issuecomment-535108266
155 |
156 | ## Deferred results
157 |
158 | - https://github.com/graphql/graphql-js/pull/2318
159 | - https://github.com/graphql/graphql-js/pull/2319
160 | - https://gist.github.com/robrichard/f563fd272f65bdbe8742764f1a149b2b
161 |
162 | `@defer` directive is not really ready in GraphQL world (no matter what framework) but there is a different solution which you can use today. All you need is a refetch container and `@include` directive. Let's say you want to fetch "note" lazily for some reason. Simply wrap the component into `createRefetchContainer` instead of `createFragmentContainer` and fetch some parts of the fragment conditionally like so:
163 |
164 | ```js
165 | export const NoteContainer = createRefetchContainer(
166 | NoteContainerWithoutData,
167 | {
168 | lead: graphql`
169 | fragment NoteContainer_lead on Lead
170 | @argumentDefinitions(isMounted: { type: "Boolean!", defaultValue: false }) {
171 | id
172 | ... @include(if: $isMounted) {
173 | ...NoteEditor_lead
174 | note
175 | }
176 | }
177 | `,
178 | },
179 | graphql`
180 | query NoteContainerDeferredQuery($isMounted: Boolean!, $id: ID!) {
181 | lead: node(id: $id) {
182 | ...NoteContainer_lead @arguments(isMounted: $isMounted)
183 | }
184 | }
185 | `,
186 | );
187 | ```
188 |
189 | Now, the only thing you have to do is to send the refetch query on mount and you are done:
190 |
191 | ```js
192 | useEffect(() => {
193 | // you can find `relay` in your props
194 | relay.refetch(
195 | {
196 | isMounted: true,
197 | id: lead.id,
198 | },
199 | undefined,
200 | undefined,
201 | {
202 | fetchPolicy: 'store-or-network', // handy but not necessary
203 | },
204 | );
205 | }, [lead.id, relay]);
206 | ```
207 |
208 | Kudos: https://relay-modern-course.now.sh/packages/11-simulating-defer/#2
209 |
210 | ## RelayResponseNormalizer: `handleStrippedNulls`
211 |
212 | Update: https://github.com/facebook/relay/commit/7a798d16abd08a930a3b249c26697cf92c269639 (`treatMissingFieldsAsNull`)
213 |
214 | Please read this: https://github.com/facebook/relay/issues/3052
215 |
216 | Relay is able to recover completely missing fields in the response. You can use this knowledge to optimize JSON response from the server. Let's say this is our incoming payload from the server:
217 |
218 | ```json
219 | {
220 | "data": {
221 | "allLocations": {
222 | "edges": [
223 | { "node": { "id": "san-francisco_ca_us", "name": "San Francisco" } },
224 | { "node": { "id": "boston_ma_us", "name": "Boston" } },
225 | { "node": { "id": "washington_dc_us", "name": "Washington, D.C." } }
226 | ]
227 | }
228 | }
229 | }
230 | ```
231 |
232 | Traditionally, server would return something like this in case of failure (or just missing data):
233 |
234 | ```json
235 | {
236 | "data": {
237 | "allLocations": {
238 | "edges": [
239 | { "node": { "id": "san-francisco_ca_us", "name": "San Francisco" } },
240 | { "node": { "id": "boston_ma_us", "name": null } },
241 | { "node": { "id": "washington_dc_us", "name": null } }
242 | ]
243 | }
244 | },
245 | "errors": ...
246 | }
247 | ```
248 |
249 | But it's not necessary to send the nullable fields at all. Afterall, server knows what fields were requested. `RelayResponseNormalizer` by default recovers from this state so you can send response like this from the server (see the missing names):
250 |
251 | ```json
252 | {
253 | "data": {
254 | "allLocations": {
255 | "edges": [
256 | { "node": { "id": "san-francisco_ca_us", "name": "San Francisco" } },
257 | { "node": { "id": "boston_ma_us" } },
258 | { "node": { "id": "washington_dc_us" } }
259 | ]
260 | }
261 | },
262 | "errors": ...
263 | }
264 | ```
265 |
266 | Relay will show you this warning in this console (dev mode only):
267 |
268 | > Warning: RelayResponseNormalizer(): Payload did not contain a value for field `name: name`. Check that you are parsing with the same query that was used to fetch the payload.
269 |
270 | See: https://github.com/facebook/relay/blob/76fef685f70a5aa09cd180ce0f2ef6b6d3f4f7e8/packages/relay-runtime/store/RelayResponseNormalizer.js#L75
271 |
272 | ## Refetch container
273 |
274 | https://facebook.github.io/relay/docs/en/refetch-container.html
275 |
276 | When `refetch` is called and the `refetchQuery` is executed, Relay doesn't actually use the result of the query to re-render the component. All it does is normalize the payload into the store and fire any relevant subscriptions. This means that if the fetched data is unrelated to the data that the mounted container is subscribed to (e.g. using a totally different node id that doesn't have any data overlaps), then the component won't re-render.
277 |
278 | Refetch containers are only really meant to be used when you are changing variables in the component fragment. If you don't want or need to include variables in the fragment, you could go one level up and set new variables directly in the QueryRenderer (using props or state).
279 |
280 | https://github.com/facebook/relay/issues/2244#issuecomment-355054944
281 |
282 | ## Common Relay mistakes (from user perspective)
283 |
284 | - users are not using fragments correctly (data-masking misunderstanding, [types generation misunderstanding](https://github.com/relay-tools/relay-compiler-language-typescript/issues/64#issuecomment-458654418))
285 | - incorrect environment imports (not using the right Environment instance)
286 |
287 | TKTK
288 |
289 | ```ts
290 | export type CustomFieldsList_customFields = ReadonlyArray<
291 | | {
292 | readonly '__typename': 'CustomFieldAutocomplete';
293 | readonly ' $fragmentRefs': FragmentRefs<'CustomFieldAutocomplete_data'>;
294 | readonly ' $refType': 'CustomFieldsList_customFields';
295 | }
296 | | {
297 | readonly '__typename': 'CustomFieldDate';
298 | readonly 'date': string;
299 | readonly 'name': string | null;
300 | readonly ' $fragmentRefs': FragmentRefs<'CustomFieldDate_data'>;
301 | readonly ' $refType': 'CustomFieldsList_customFields';
302 | }
303 | >;
304 |
305 | // type Extract = T extends U ? T : never;
306 | type CustomFieldDateType = Extract<
307 | CustomFieldsList_customFields[0], // because of @relay(plural: true)
308 | { readonly __typename: 'CustomFieldDate' }
309 | >;
310 | ```
311 |
312 | ^^ this should however be unnecessary since the correct solution is to decompose
313 |
314 | There is another plot twist into the type generation (Joe Savona on why sometimes the types are a bit weird, especially around interfaces):
315 |
316 | > The Flow types are reflecting the data that Relay will actually provide at runtime. We don't encode which types implement which interfaces (even if we encoded it at build time, it could still change on the server in the meantime), so we always read into fragment spreads on abstract types. If the object implements the interface and we've fetched those fields they'll be there, but otherwise they could be missing entirely. Generating a disjoint union wouldn't reflect the actual values RelayReader would produce.
317 |
318 | > That being said, it would be nice to have more precise output types, and it's something we're investigating.
319 |
320 | ## Common Relay errors explained
321 |
322 | ### Relay does not allow `__typename` field on Query, Mutation or Subscription
323 |
324 | > Rather than special-case the representation of the root of the graph, Relay generates a "client" record to represent the Query and mutation/subscription objects. Like all other record instances those records have a **typename, but we special-case this typename to be 'ROOT'. Querying for the **typename field would overwrite this value with the actual typename (e.g. Query or whatever you call it in your schema), which messes with a few invariants. It's on our wishlist to make the root record a bit less special, but in practice we couldn't think of a reason to query \_\_typename on the root so we just disallow it for now.
325 |
326 | - https://github.com/facebook/relay/commit/793729e7af9c7ee0de971e3d2ed26e5896774640#commitcomment-37652508
327 |
328 | A nice workaround was mentioned here: https://github.com/facebook/relay/issues/2471#issuecomment-624238501
329 |
330 | ```graphql
331 | ... on Query { __typename }
332 | ```
333 |
334 | (instead of just `__typename`)
335 |
336 | ## Current Relay struggles
337 |
338 | These are things which are somehow difficult to achieve with current Relay abilities. It's almost like a wishlist:
339 |
340 | - Function `readInlineData` doesn't support variables (throws error _"Variables are not yet supported inside @inline fragments."_)
341 | - How to figure out request is in-flight when using fetch policy `store-and-network` (to show some spinner)?
342 | - How to access fields with some complicated args (without actually knowing all the possible args combinations in advance). See: https://github.com/facebook/relay/issues/3077
343 |
344 | ## On handling of GraphQL errors in Relay
345 |
346 | > My general advice for applications is, for now:
347 | >
348 | > 1: Establish and enforce a convention in your schema for the values returned in the errors property, and when an error is considered critical enough to return null for data (When nothing can be meaningfully be rendered anyway). For example, for critical errors you might choose to still return data but have errors contain an object with `{critical: true, message: '...'}`, or you might choose to make data be null. The important part is consistency.
349 | >
350 | > 2: Take advantage of this in your network layer. Check the data/errors property for the presence of critical error based on whatever approach you follow from the previous step, and if a critical error is present return `{data: null, errors}` to Relay. Otherwise pass through the data as-is.
351 |
352 | (https://github.com/facebook/relay/issues/1816#issuecomment-304492071)
353 |
354 | > The GraphQL errors field is intended for truly exceptional errors such as an invalid query or variable value: things that are not reasonably expected to occur in an application. Invalid user input or a backend service being unavailable are reasonable errors that are expected to occur (hopefully infrequently for the service down case!).
355 |
356 | (continue reading here: https://github.com/facebook/relay/issues/2640#issuecomment-461137805)
357 |
--------------------------------------------------------------------------------
/docs/flow.md:
--------------------------------------------------------------------------------
1 | ---
2 | id: flow
3 | title: Flow all-in
4 | sidebar_label: Flow all-in
5 | ---
6 |
7 | - **https://flow.org/en/docs/faq/**
8 | - https://github.com/facebook/flow/wiki
9 | - https://github.com/wgao19/flow-notes
10 | - https://github.com/facebook/flow/blob/master/Changelog.md
11 | - https://github.com/niieani/typescript-vs-flowtype
12 | - https://github.com/vkurchatkin/typescript-vs-flow
13 | - https://github.com/lttb/flown
14 | - https://github.com/dustinspecker/awesome-flow
15 | - https://gajus.github.io/flow-runtime/
16 | - https://medium.com/flow-type/what-the-flow-team-has-been-up-to-54239c62004f#a548
17 | - https://github.com/facebook/flow/issues/7365 (Facebook's own Flow adoption?)
18 | - https://github.com/lessmess-dev/gen-flow-files
19 | - Paper: [Fast and Precise Type Checking for JavaScript](https://arxiv.org/pdf/1708.08021.pdf)
20 | - type checking for `this` annotations in functions: https://github.com/facebook/flow/commit/fb6a836ef7d8d3ae842ac9df67e4c83698cbffb4
21 | - option `indexed_access=true` (https://github.com/facebook/flow/search?q=%22indexed_access%22&type=commits)
22 |
23 | :::tip
24 | Flow infers the widest type that makes your code work. If you don't want inference to widen your type, the solution is always to annotate.
25 | :::
26 |
27 | ## Oncalls in Facebook (Flow related)
28 |
29 | > so the way it works is that the Flow team has a rotating oncall. it's relatively calm as oncalls go (we aren't getting woken up in the middle of the night), but whoever is oncall is responsible for doing support (we have an internal group where people can ask questions), and also responsible for taking the lead if something goes wrong with Flow or the various related integrations we have. near the beginning of the year we also made it so that the oncall is responsible for addressing libdef and documentation PRs, since there is usually no clear owner for those, and pretty much anyone should be able to review them
30 |
31 | (source Discord)
32 |
33 | ## Exit codes
34 |
35 | Flow exited with some numeric exit code and you are not sure what does it mean? You can find these exit codes here: https://github.com/facebook/flow/blob/eaffc8cdf09fb268c6f9ab9914685cbbd562e534/src/common/exit_status/flowExitStatus.ml
36 |
37 | ## Sound vs. complete
38 |
39 | > A sound type system (or analysis) is one that rejects all erroneous programs, and a complete system accepts all correct programs.
40 |
41 | > A sound type system is one that is not lenient, in that it rejects all invalid programs plus some number of valid programs. A complete type system accepts all valid programs, and some invalid ones to boot. Which to pick?
42 |
43 | > A sound type system is one that ensures your program does not get into invalid states. For example, if an expression’s static type is string, at runtime, you are guaranteed only to get a string when you evaluate it.
44 |
45 | - https://eschew.wordpress.com/2009/08/31/sound-and-complete/
46 | - https://stackoverflow.com/a/21437375/3135248
47 | - https://blog.logrocket.com/is-typescript-worth-it
48 | - https://dart.dev/guides/language/sound-dart#what-is-soundness
49 |
50 | Please note: not everything can be expressed/modeled in your type system so you have to take into account also dynamic errors (division by zero or integer overflow) when writing your program.
51 |
52 | > Programmers dislike having the computer reject a program that would have run fine, simply because the computer couldn’t make sure it would run fine without actually running it. In short, restrictive type systems drive programmers to more flexible environments.
53 |
54 | ## Type-safe filter function
55 |
56 | ```js
57 | declare function filter, T: Array | $ReadOnlyArray>(
58 | fn: P,
59 | xs: T,
60 | ): Array<$Refine>;
61 |
62 | const input: $ReadOnlyArray = [1, 'a', 2, 3, 'b'];
63 |
64 | function isNumber(x: mixed): boolean %checks {
65 | return typeof x === 'number';
66 | }
67 |
68 | // const result: $ReadOnlyArray = input.filter(isNumber);
69 | // ^ Cannot assign `input.filter(...)` to `result` because string [1] is incompatible with number [2] in array element.
70 | const result: $ReadOnlyArray = input.filter(isNumber);
71 |
72 | const result_fixed: $ReadOnlyArray = filter(isNumber, input);
73 | ```
74 |
75 | [flow.org/try](https://flow.org/try/#0CYUwxgNghgTiAEAzArgOzAFwJYHtVKwgxBgB4BpAGngDVqAFALngBJ65hSBGAPmoBVmAQRgwoAT1I0e8AD6sASiCjAA8qgjiRYydJ4AKAFDwkqZvUrH4ADwDOzfpYCUw0RNIsliLKhBSG1Lw8ANyGhmB4thjwPgAOyBjMnspqGlpukqjIALYARiRy8FEwPgDmMgC88ADaXNQA5FD11ABM1ADMDbn1ALqhhijo2HgxtgByOfkw+tbM2VjWIMAu8Lk4OBDK+ACkYAAW4ADWtvAA3lZwGMgw+BjisSA4iDbwFW-w9Vl5JPWhAL5hCKoKLwOC2ZBEJJKFTqTTadxfKaVGKoeIYAB03iIJH0WHGkxITlCQJBYIhGAA+t5FsAoSlYekdKRESRkVjiNM8RNvjBqHEEkSgA)
76 |
77 | - https://github.com/facebook/flow/issues/1414
78 |
79 | ## Force type casting
80 |
81 | You may find yourself in a situation where you want to force cast some type despite it's originally defined differently. Example:
82 |
83 | ```js
84 | type StringOrNumber = string | number;
85 | const foo: StringOrNumber = 'hello';
86 |
87 | const bar1: string = foo; // cannot assign `foo` to `bar` because number is incompatible with string
88 | const bar2: string = (foo: string); // cannot cast `foo` to string because number is incompatible with string
89 | ```
90 |
91 | Both errors are correct and valid. The solution is to cast the type via `any` like this:
92 |
93 | ```js
94 | const bar: string = (foo: any);
95 | ```
96 |
97 | > So you cast `foo` to an `any` because `any` accepts any type of value as an input. Then because the `any` type also allows you to read all possible types from it, you can assign the `any` value to `bar` because an `any` is also a string.
98 |
99 | This obviously means that you are going against the type system and you might be doing something wrong. Did you want to use conditional refinement instead?
100 |
101 | ```js
102 | type StringOrNumber = string | number;
103 | const foo: StringOrNumber = 'hello';
104 |
105 | if (typeof foo === 'string') {
106 | const bar: string = foo; // no errors!
107 | }
108 | ```
109 |
110 | > It's important to note that both suppression comments and cast-through any are **unsafe**. They override Flow completely, and will happily perform completely nonsensical "casts". To avoid this, use refinements that Flow understands whenever you can, and avoid use of the other, unsafe "casting" techniques.
111 |
112 | Source: https://stackoverflow.com/questions/41328728/how-can-flow-be-forced-to-cast-a-value-to-another-type/45068255
113 |
114 | ## `$Compose`, `$ComposeReverse`
115 |
116 | Compose pattern is very common among JS community. Here are some examples: [Redux](http://redux.js.org/docs/api/compose.html), [Recompose](https://github.com/acdlite/recompose/blob/master/docs/API.md#compose), [Lodash](https://lodash.com/docs/4.17.15#flow) and [Ramda](https://ramdajs.com/docs/#compose)
117 |
118 | You can enable this common `compose` pattern like so:
119 |
120 | ```js
121 | declare var compose: $Compose;
122 | declare var composeReverse: $ComposeReverse;
123 | ```
124 |
125 | More info: https://github.com/facebook/flow/commit/ab9bf44c725efd2ed6d7e1e957c5566b6eb6f688
126 |
127 | ## `$CharSet`
128 |
129 | Handy utility for things like regexp flags or for any other case where the flags (chars) cannot repeat.
130 |
131 | ```js
132 | type RegExpFlags = $CharSet<'gimsuy'>;
133 |
134 | const a: RegExpFlags = 'miug'; // OK
135 | const b: RegExpFlags = 'iii'; // not OK! ("i" is duplicated)
136 | const c: RegExpFlags = 'abc'; // not OK! ("a", "b", "c" are not valid members)
137 | ```
138 |
139 | - https://github.com/facebook/flow/issues/4654
140 | - https://github.com/microsoft/TypeScript/issues/6579
141 |
142 | ## Contributing to native libdevs
143 |
144 | First, you have to build Flow locally (check official README for updated instructions: https://github.com/facebook/flow):
145 |
146 | ```bash
147 | brew install opam # http://opam.ocaml.org/
148 | opam init
149 | opam switch create . --deps-only -y # install OCaml and Flow's dependencies
150 | eval $(opam env) # probably not necessary, read `opam init` step
151 | make
152 | ```
153 |
154 | Now, you can start making changes to libdevs:
155 |
156 | ```bash
157 | make
158 | bash ./runtests.sh -t node_tests bin/flow
159 | bash ./runtests.sh -t node_tests -r bin/flow # to write snapshots
160 | ```
161 |
162 | Please note, building like this should be faster for local development:
163 |
164 | ```bash
165 | make build-flow-debug
166 | ```
167 |
168 | Now, you can use this new binary from source in your application to test new features. Just use newly built `bin/flow` instead of Flow binary from NPM like so:
169 |
170 | ```bash
171 | bin/flow status
172 | ```
173 |
174 | What to do when something goes wrong during the build?
175 |
176 | ```bash
177 | make clean
178 | make build-flow-debug
179 | ```
180 |
181 | ## Performance of Large unions (simple enums)
182 |
183 | > I've been working on this recently so I can give you an overview. Essentially the reasons large unions are slow is that the amount of work Flow needs to do can grow exponentially with the size of the union. To determine if a union is a valid subtype of another type, we need to consider whether every single element of the union is a valid subtype, while to determine if it's a supertype we need to check if at least one of its cases is a supertype. If the union isn't actually a supertype we end up needing to check every case. Where this gets really bad is when we compare two union types, and this can easily result in an exponential case where we need to perform a lot of work for every single combination of union cases.
184 |
185 | > Luckily we have a lot of optimizations in place for dealing with unions, especially those that can be simplified to enums (unions of strings or number literals). 450 variants is really not that large in the scheme of things; we deal with unions with upwards of 100,000 elements routinely. The only caution I would suggest is to make sure that you don't add non-literal types to your enum unions, because that will cause our optimizations to fail and leave you with the worst case peformance.
186 |
187 | Thanks @sainati on Discord.
188 |
189 | ## Enums
190 |
191 | - https://medium.com/flow-type/introducing-flow-enums-16d4239b3180
192 | - https://medium.com/flow-type/typescript-enums-vs-flow-enums-83da2ca4a9b4
193 |
194 | You have to explicitly enable support for enums in `.flowconfig` to be able to use them:
195 |
196 | ```ini
197 | [options]
198 | enums=true
199 | ```
200 |
201 | Additionally, there are some requirements for minimal versions of Babel, Eslint, Prettier + related configuration. You can check how were the enums enabled in [`adeira/univers`](https://github.com/adeira/universe/pull/3124/files) or consult the official docs: https://flow.org/en/docs/enums/
202 |
203 | Now, you can use this new feature:
204 |
205 | ```js
206 | enum E1 {
207 | A,
208 | B,
209 | }
210 |
211 | enum E2 of number {
212 | A = 1,
213 | B = 2,
214 | }
215 | ```
216 |
217 | Basic methods support:
218 |
219 | ```js
220 | enum E {
221 | A,
222 | B,
223 | }
224 |
225 | const a: ?E = E.cast('A');
226 | const b: Iterable = E.members();
227 | const c: boolean = E.isValid('A');
228 | ```
229 |
230 | Rather negative discussion about enums in Flow: https://github.com/facebook/flow/issues/7837
231 |
232 | ## Declaration with `mixins`
233 |
234 | Mixins (not [React mixins](https://reactjs.org/blog/2016/07/13/mixins-considered-harmful.html)) are a little know feature in Flow which is no longer being publicly advertised (even though [it used to be in docs](https://github.com/facebook/flow/commit/5c4297bcfa0f577e6f989ad188a7b8d1633b2df4)).
235 |
236 | You can declare a class which mixes in 1 or more other classes with the `mixins` keyword. Mixing class `B` into class `A` copies `B`'s fields and methods into `A`. Note, however, that any fields or methods that `B` inherits are not copied over. Mixins are for code reuse, not for multiple inheritance.
237 |
238 | Example:
239 |
240 | ```js
241 | // You can mixin more than one class
242 | declare class MyClass extends Child mixins MixinA, MixinB {}
243 | declare class MixinA {
244 | a: number;
245 | b: number;
246 | }
247 | // Mixing in MixinB will NOT mix in MixinBase
248 | declare class MixinB extends MixinBase {}
249 | declare class MixinBase {
250 | c: number;
251 | }
252 | declare class Child extends Base {
253 | a: string;
254 | c: string;
255 | }
256 | declare class Base {
257 | b: string;
258 | }
259 |
260 | var c = new MyClass();
261 | (c.a: number); // Both Child and MixinA provide `a`, so MixinA wins
262 | (c.b: number); // The same principle holds for `b`, which Child inherits
263 | (c.c: string); // mixins does not copy inherited properties, so `c` comes from Child
264 | ```
265 |
266 | You can combine `mixins` with `implements` as well:
267 |
268 | ```js
269 | declare interface Test {
270 | test(): void;
271 | }
272 |
273 | declare class MyClass extends Child mixins MixinA, MixinB implements Test {
274 | test(): void;
275 | }
276 | ```
277 |
278 | ## Callable objects
279 |
280 | This type allows you to use the function as a function and as an object at the same time.
281 |
282 | ```js
283 | type MemoizedFactorial = {
284 | +cache: {
285 | [number]: number,
286 | },
287 | (number): number,
288 | };
289 |
290 | const factorial: MemoizedFactorial = (n) => {
291 | if (!factorial.cache) {
292 | factorial.cache = {};
293 | }
294 | if (factorial.cache[n] !== undefined) {
295 | return factorial.cache[n];
296 | }
297 | factorial.cache[n] = n === 0 ? 1 : n * factorial(n - 1);
298 | return factorial.cache[n];
299 | };
300 | ```
301 |
302 | See: https://flow.org/en/docs/types/functions/#toc-callable-objects
303 |
304 | Alternatively, you can use so called _internal slot property_:
305 |
306 | ```js
307 | type MemoizedFactorial = {
308 | +cache: {
309 | [number]: number,
310 | },
311 | [[call]](number): number,
312 | };
313 | ```
314 |
315 | - https://github.com/facebook/flow/pull/7790/files
316 | - https://github.com/niieani/typescript-vs-flowtype/pull/55/files
317 | - https://github.com/facebook/flow/commit/954a72704a6338778c940239573045b28c716488
318 | - https://github.com/facebook/flow/commit/732eae55e102cdb7dfa7b6a85f0147d48c3afed7
319 |
320 | Support of internal slot properties in tools like Babel or Eslint is not great though.
321 |
322 | ## Interesting Flow commands
323 |
324 | ```bash
325 | yarn flow graph cycle src/incubator/graphql/src/public/FAQ/types/outputs/FAQArticle.js
326 |
327 | # Outputs dependency graphs of flow repositories. Subcommands:
328 | # cycle: Produces a graph of the dependency cycle containing the input file
329 | # dep-graph: Produces the dependency graph of a repository
330 | ```
331 |
332 | ```bash
333 | yarn flow dump-types src/packages/relay/src/QueryRenderer.js
334 | ```
335 |
336 | ```bash
337 | yarn flow check --debug
338 | ```
339 |
340 | ```bash
341 | yarn flow check --profile
342 | ```
343 |
344 | ```bash
345 | yarn flow autofix
346 | ```
347 |
348 | [source](https://stackoverflow.com/a/40569640/3135248)
349 |
350 | ## Private object properties
351 |
352 | ```js
353 | class Thing {
354 | prop1: string;
355 | #prop2: string = 'I am private!';
356 | }
357 |
358 | new Thing().prop1;
359 | new Thing().prop2; // <- ERROR
360 | ```
361 |
362 | ```
363 | 7: (new Thing()).prop2;
364 | ^ Cannot get `new Thing().prop2` because property `prop2` is missing in `Thing` [1].
365 | References:
366 | 7: (new Thing()).prop2;
367 | ^ [1]
368 | ```
369 |
370 | - https://github.com/tc39/proposal-class-fields#private-fields
371 |
372 | ## Predicate functions with `%checks`
373 |
374 | `%checks` is an experimental predicate type. Check this code (no Flow errors):
375 |
376 | ```js
377 | function isGreaterThan5(x: string | number): boolean {
378 | if (typeof x === 'string') {
379 | return parseInt(x) > 5;
380 | }
381 | return x > 5;
382 | }
383 | ```
384 |
385 | But you can slightly refactor it and you'll get unexpected errors:
386 |
387 | ```js
388 | function isString(y): boolean {
389 | return typeof y === 'string';
390 | }
391 |
392 | function isGreaterThan5(x: string | number): boolean {
393 | if (isString(x)) {
394 | return parseInt(x) > 5;
395 | }
396 | return x > 5;
397 | }
398 | ```
399 |
400 | ```
401 | 9: return x > 5;
402 | ^ Cannot compare string [1] to number [2].
403 | References:
404 | 5: function isGreaterThan5(x: string | number) {
405 | ^ [1]
406 | 9: return x > 5;
407 | ^ [2]
408 | ```
409 |
410 | This is because the refinement information of `y` as `string` instead of `string | number` is lost when returning from the `isString` function. You have to fix it like this:
411 |
412 | ```js
413 | function isString(y): boolean %checks {
414 | return typeof y === 'string';
415 | }
416 | ```
417 |
418 | You can also declare the predicate like this:
419 |
420 | ```js
421 | declare function isSchema(schema: mixed): boolean %checks(schema instanceof GraphQLSchema);
422 | ```
423 |
424 | - https://flow.org/en/docs/types/functions/#toc-predicate-functions
425 | - https://github.com/facebook/flow/issues/3048
426 | - https://github.com/facebook/flow/issues/34
427 |
428 | ## Object indexer properties
429 |
430 | ```js
431 | const o: { [string]: number, ... } = {};
432 | o['foo'] = 0;
433 | o['bar'] = 1;
434 | o[42] = 2; // Error!
435 | const foo: number = o['foo'];
436 | ```
437 |
438 | > When an object type has an indexer property, property accesses are assumed to have the annotated type, even if the object does not have a value in that slot at runtime. It is the programmer’s responsibility to ensure the access is safe, as with arrays.
439 |
440 | This is similar to the issue with [possibly undefined array elements](#possibly-undefined-array-elements):
441 |
442 | ```js
443 | const obj: { [number]: string, ... } = {};
444 | obj[42].length; // No type error, but will throw at runtime!
445 | ```
446 |
447 | Indexer properties can be also mixed with normal properties:
448 |
449 | ```js
450 | const obj: {
451 | size: number,
452 | [id: number]: string,
453 | ...
454 | } = {
455 | size: 0,
456 | };
457 |
458 | function add(id: number, name: string) {
459 | obj[id] = name;
460 | obj.size++;
461 | }
462 | ```
463 |
464 | ---
465 |
466 | _This information is not valid from version 0.126.0+ since indexer properties are now implemented even for exact objects, see: https://github.com/facebook/flow/commit/97e3a103227a381de0fd0be197bf25f6d6b6081a._
467 |
468 | Please note: indexer property doesn't make any sense on exact objects:
469 |
470 | ```js
471 | type S = {| [key: string]: string |};
472 | const s: S = { key: 'value' }; // cannot assign object literal to `s` because property `key` is missing in `S`
473 | ```
474 |
475 | This is not a bug - it simply doesn't make any sense with exact objects. It could be eventually repurposed though, see: https://github.com/facebook/flow/issues/7862 (related issue: https://github.com/facebook/flow/issues/3162)
476 |
477 | However, it still somehow works when you are not trying to re-assign the whole value, see:
478 |
479 | ```js
480 | type S = {| [key: string]: string |};
481 |
482 | const s: S = { key: 'value' }; // Error: Cannot assign object literal to `s` because property `key` is missing in `S` but exists in object literal.
483 |
484 | function test(x: S): string {
485 | x.y = 'string'; // OK (would fail with a wrong type assignment)
486 | return x.test; // OK
487 | }
488 | ```
489 |
490 | ## Difference between `&` and `...`
491 |
492 | It's easy to misunderstand the difference between intersection types (`A & B`) and spreading types (`{ ...A, b:boolean }`) in Flow.
493 |
494 | ```js
495 | type A = { a: number };
496 | type B = { b: boolean };
497 | type C = { c: string };
498 |
499 | // Intersection types are the opposite of union types!
500 | const a: A & B & C = {
501 | a: 1,
502 | b: true,
503 | c: 'ok',
504 | };
505 |
506 | const b: $Exact | $Exact | $Exact = {
507 | a: 1,
508 | // b: true,
509 | // c: 'ok'
510 | };
511 |
512 | const c: {
513 | ...{ a: number, b: string },
514 | a: string,
515 | } = {
516 | a: '1', // only string, no number
517 | b: '2',
518 | };
519 |
520 | const d: {|
521 | ...{| a: number, b: string |},
522 | a: string,
523 | |} = {
524 | a: '1', // works the same with exact types
525 | b: '2',
526 | };
527 |
528 | // Impossible type:
529 | // const e: {| a: number |} & {| a: string |} = {
530 | // a: ???,
531 | // }
532 | ```
533 |
534 | No errors!
535 |
536 | - https://www.knyz.org/blog/post/flow-union-intersection-spead/
537 |
538 | ## `@flow` pragma consequences
539 |
540 | It is incorrect to assume that adding `@flow` pragma to your files just enables typesystem without any side-effects. There can be some unexpected changes in fact:
541 |
542 | 1. `/*:: ... */` and `/*: ... */` comments have special meaning (https://flow.org/en/docs/types/comments/)
543 | 2. `a(c)` becomes a type argument, rather than `((a < b) > c)`
544 |
545 | https://github.com/facebook/flow/issues/7928#issuecomment-511428223
546 |
547 | ## Conditions in Flow using `$Call`
548 |
549 | - https://gist.github.com/miyaokamarina/934887ac2aff863b9c73283acfb71cf0
550 | - https://flow.org/en/docs/types/utilities/#toc-call
551 | - https://github.com/niieani/typescript-vs-flowtype/issues/37
552 |
553 | > (jbrown215)
554 | > \$Call is a shitty syntax for conditional types, but it exists. You can use overloading to simulate the cases, so:
555 |
556 | ```js
557 | type Fun = ((number) => string) & ((string) => number);
558 | type SwapNumberAndString = $Call;
559 | ```
560 |
561 | Is approximately in TS:
562 |
563 | ```ts
564 | type SwapNumberAndString = T extends number ? string : number;
565 | ```
566 |
--------------------------------------------------------------------------------