rescript-relay

When working with @connection directives, you often need the connection's __id to perform cache updates. If passing __id through the React tree is difficult, RescriptRelay generates a makeConnectionId function for every fragment containing a @connection.

This function is fully type-safe and mirrors the @connection and @argumentDefinitions (including default values) defined in your GraphQL.

Usage Pattern:

1. Pass the __id of the owner (the type that owns the connection) to makeConnectionId.
2. Provide the necessary arguments. If an argument is omitted, the function uses the defaultValue specified in the @argumentDefinitions within the GraphQL text.
3. Use the resulting ID for declarative updates or imperative store operations via RecordSourceSelectorProxy.get.

/* UserFriendsList.res */
module Fragment = %relay(`
  fragment UserFriendsList_user on User
    @argumentDefinitions(
      onlineStatuses: { type: "[OnlineStatus!]", defaultValue: [Idle] }
      count: { type: "Int", defaultValue: 2 }
      cursor: { type: "String", defaultValue: "" }
      minimumCommonFriends: { type: "Int!" }
    ) {
    __id
    friendsConnection(
      statuses: $onlineStatuses
      first: $count
      after: $cursor
      minimumCommonFriends: $minimumCommonFriends
    ) @connection(key: "UserFriendsList_user_friendsConnection") {
      edges {
        node {
          id
          ...UserFriendsListSingleUser_user
        }
      }
    }
  }
`)

@react.component
let make = (~user) => {
  let user = Fragment.use(user)

  // Uses default onlineStatuses: [Idle]
  let connectionId =
    user.__id->UserFriendsList_user_graphql.makeConnectionId(~minimumCommonFriends=10)

  // Uses explicit onlineStatuses
  let connectionId2 =
    user.__id->UserFriendsList_user_graphql.makeConnectionId(
      ~minimumCommonFriends=10,
      ~onlineStatuses=[#Online, #Idle]
    )

  // ...
}

To start loading data before a component renders (to avoid waterfalls), use the preloading pattern. This involves two steps:

1. useLoader: Call this to start the loading process. It returns a tuple: (option(queryRef), loadQuery, disposeQuery).
   • loadQuery is the function you call to trigger the fetch.
   • queryRef is the reference to the loading query.
2. usePreloaded: Pass the queryRef obtained from useLoader into this hook. It will either deliver the data immediately or suspend the component until the data arrives.

This pattern uses Relay's useQueryLoader and usePreloadedQuery hooks.

// 1. Initialize the loader
let (queryRef, loadQuery, disposeQuery) = Query.useLoader()

// 2. Trigger the load (e.g., in a useEffect or event handler)
loadQuery(~variables=())

// 3. In a child component or later in the render, consume the ref
let data = Query.usePreloaded(~queryRef=queryRef)

A GraphQL schema defines the structure of your data. Key concepts include:

• Nodes: The objects or records in your graph (e.g., Person, Story).
• Fields: The properties of a node. Fields can be:
  • Scalars: Primitive types like String, Int, ID, or Boolean.
  • Objects: Fields that point to other nodes (edges).
• Non-nullable fields (!): A type suffix (e.g., ID!) indicating that the field cannot be null. If a query requests a non-nullable field that is null at runtime, it results in an error.
• Interfaces: A way to define a set of fields that multiple types can implement (e.g., an Actor interface implemented by Person and Organization).
• Enums: A set of predefined constant values (e.g., Category { EDUCATION, NEWS, COOKING }).
• Top-level entry points:
  • Query: Used for fetching data (analogous to HTTP GET).
  • Mutation: Used for modifying data (analogous to HTTP POST).
  • Subscription: Used for real-time updates.

For maximum performance, especially when integrated with a router, you can bypass the React render cycle by calling the load function directly from the generated GraphQL artifact file.

When you define a query using %relay, the compiler generates a file named <queryName>_graphql.res. This file contains a load function that returns a queryRef. You can call this function anywhere (e.g., during route preparation) and then pass the resulting queryRef to a component using Query.usePreloaded.

/* Example using rescript-relay-router to preload data during route preparation */

module SomeComponent = %relay.deferredComponent(SomeComponent.make)

let renderer = Routes.SomeRoute.Route.makeRenderer(
  ~prepareCode=_ => [SomeComponentQuery.preload()],
  ~prepare=({environment, userId}) => {
    SomeComponentQuery_graphql.load(
      ~environment,
      ~variables={userId: userId},
      ~fetchPolicy=StoreOrNetwork,
    )
  },
  ~render=props => {
    <SomeComponent queryRef=props.prepared />
  },
)