API Reference
Please note that this reference is under construction. With that said, most things in the API should be available here.
#
Types, values and functionsallFieldsMasked#
If you see this, it means that all fields have been masked in this selection, which is why it contains no data. Relay uses data masking to hide data you haven't explicitly asked for, even if it exists on the object.
#
Why am I seeing this?In most cases when you see this but expected to see actual data, you've spread one or more fragments into a mutation and forgot to add @raw_response_type
to your mutation, like:
@raw_response_type
(documented here) will make sure that you get access to all the data when making optimistic updates.
featureFlags#
Relay feature flags. Mutate this record as soon as your application boots to enable/disable features.
#
ExamplecacheConfig#
The cache config provided to the network layer. Relay won't do anything in particular with these, it's up to you to use them if you want inside of your NetworkLayer
.
fetchPolicy#
fetchPolicy controls how you want Relay to resolve your data.
fetchQueryFetchPolicy#
The fetch policies allowed for fetching a query outside of React's render (as in Query.fetch
).
mutationError#
An error from a mutation.
arguments#
Abstract type for arguments, used when selecting fields on RecordProxy and friends when interacting with the store imperatively.
uploadables#
Abstract type for uploadables.
uploadables#
Constructing anUse makeUploadables : makeUploadables(aJsDictContainingYourFilesHere)
to construct an uploadables , and then pass it to your mutation via the uploadables prop. Then, in your network layer, use unwrapUploadables to get the dict with your files again. You can then iterate through that and add the files to your request for upload.
Please note that you'll need to handle sending the uploadables to your server yourself in the network layer. Here's an example in regular JS that you can adapt to ReScript as you need/want.
any#
Abstract helper type to signify something that could not be generated in a type-safe way.
dataId#
The type of the id Relay uses to identify records in its store.
dataId 's#
GettingYou can get the dataId of anything by selecting __id
in your query/fragment/mutation/subscription, like this:
If you have globally unique IDs in your graph, __id
will always be the same as the regular id
. However, as id
is commonly modelled as a string
, selecting __id
will conveniently give you a dataId directly that you can use to interact with the store.
string
and dataId#
Converting between You'll often want to convert between string
and dataId . You can do this by using makeDataId (RescriptRelay.makeDataId(yourStringHere
) and dataIdToString (RescriptRelay.dataIdToString(yourDataIdHere)
).
recordSourceRecords#
An abstract type representing all records in the store serialized to JSON in a way that you can use to re-hydrate the store.
See RecordSource.toJSON for how to produce it.
dataIdToString#
Read more about: dataId
Turns a dataId into a string
.
makeArguments#
Read more about: arguments
Construct an arguments object for use with certain Relay store APIs.
#
UsageUse it like this: makeArguments({ "someArgument": someValue, "anotherArgument": anotherValue })
. Notice the "" surrounding the property names - these are important and tells ReScript that we want this to be a JS object.
generateClientID#
Read more about: dataId
This generates a dataId
for use on the client side. However, this is farily low level, and what you're probably really looking for is generateUniqueClientID that'll let you generate a new, unique dataId
that you can use for client side only records (like when doing optimistic updates).
generateUniqueClientID#
Read more about: dataId
This generates a unique dataId that's safe to use on the client side. Useful when doing optimistic updates and you need to create IDs that the optimistic update can use.
isClientID#
Read more about: dataId
Checks whether the provided dataId is guaranteed to be a client side only id.
relayFeatureFlags#
Read more about: featureFlags
Relay feature flags. Mutate this record as soon as your application boots to enable/disable features.
#
ExamplestoreRootId#
Read more about: dataId
An abstract type representing all records in the store serialized to JSON in a way that you can use to re-hydrate the store.
See RecordSource.toJSON for how to produce it.
storeRootType#
The type
for the Relay store's root RecordProxy .
makeDataId#
Read more about: dataId
Turns a string
into a dataId .
#
ExamplemakeUploadables#
Read more about: uploadables
Construct an uploadables object that you can use for uploads via Relay.
#
UsageUse it like this: makeUploadables(myJsDictWithMyFiles)
.
unwrapUploadables#
Read more about: uploadables
Unwraps an uploadables
into a Js.Dict.t
, letting you set the file format you expect. You can then loop through that dict to add all the files you want to upload to your request in the network layer.
#
RecordProxyRead the following section on working with the Relay store: https://relay.dev/docs/en/relay-store
RecordProxy.t#
Read the following section on working with the Relay store: https://relay.dev/docs/en/relay-store
RecordProxy.getLinkedRecords#
Read more about: RecordProxy.t, arguments
Gets an array of linked records, for when a field is a list (meaning a link to multiple records).
RecordProxy.copyFieldsFrom#
Read more about: RecordProxy.t
Read the following section on working with the Relay store: https://relay.dev/docs/en/relay-store
RecordProxy.getDataId#
Read more about: RecordProxy.t, dataId
Gets the dataId for a particular record.
RecordProxy.getLinkedRecord#
Read more about: RecordProxy.t, arguments
Gets a single linked record. A linked record is another object in the store, and not a scalar field like an int or float.
RecordProxy.getOrCreateLinkedRecord#
Read more about: RecordProxy.t, arguments
Gets an array of linked records, for when a field is a list (meaning a link to multiple records).
RecordProxy.getType#
Read more about: RecordProxy.t
Returns the __typename
of this particular record.
RecordProxy.getValueString#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be a string.
RecordProxy.getValueStringArray#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be an array of strings.
RecordProxy.getValueInt#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be an int.
RecordProxy.getValueIntArray#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be an array of ints.
RecordProxy.getValueFloat#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be a float.
RecordProxy.getValueFloatArray#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be an array of floats.
RecordProxy.getValueBool#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be a boolean.
RecordProxy.getValueBoolArray#
Read more about: RecordProxy.t, arguments
Returns a field value, expecting it to be an array of booleans.
RecordProxy.setLinkedRecord#
Read more about: RecordProxy.t, arguments
Sets a RecordProxy.t as the linked record for a particular field.
RecordProxy.setLinkedRecords#
Read more about: RecordProxy.t, arguments
Sets an array of RecordProxy.t as the linked records for a particular field.
RecordProxy.setValueString#
Read more about: RecordProxy.t, arguments
Sets a string as field value.
RecordProxy.setValueStringArray#
Read more about: RecordProxy.t, arguments
Sets an array of strings as field value.
RecordProxy.setValueInt#
Read more about: RecordProxy.t, arguments
Sets an int as field value.
RecordProxy.setValueIntArray#
Read more about: RecordProxy.t, arguments
Sets an array of ints as field value.
RecordProxy.setValueFloat#
Read more about: RecordProxy.t, arguments
Sets a float as field value.
RecordProxy.setValueFloatArray#
Read more about: RecordProxy.t, arguments
Sets an array of floats as field value.
RecordProxy.setValueBool#
Read more about: RecordProxy.t, arguments
Sets a boolean as field value.
RecordProxy.setValueBoolArray#
Read more about: RecordProxy.t, arguments
Sets an array of booleans as field value.
RecordProxy.setValueToUndefined#
Read more about: RecordProxy.t, arguments
Sets the field value to undefined
(meaning Relay will treat it as missing data).
RecordProxy.setValueToNull#
Read more about: RecordProxy.t, arguments
Sets the field value to null
.
RecordProxy.setLinkedRecordToUndefined#
Read more about: RecordProxy.t, arguments
Sets this linked record to undefined
(meaning Relay will treat it as missing data).
RecordProxy.setLinkedRecordToNull#
Read more about: RecordProxy.t, arguments
Sets this linked record to null
.
RecordProxy.setLinkedRecordsToUndefined#
Read more about: RecordProxy.t, arguments
Sets the field holding these linked records to undefined
(meaning Relay will treat it as missing data).
RecordProxy.setLinkedRecordsToNull#
Read more about: RecordProxy.t, arguments
Sets the field holding these linked records to null
.
RecordProxy.invalidateRecord#
Read more about: RecordProxy.t
Invalidates this record.
Invalidating a record means that the next time Relay evaluates this record, it'll be treated as missing.
Beware that this doesn't mean that queries using this record will refetch immediately. Rather, it'll happen the next time the query renders. Have a look at useSubscribeToInvalidationState
, that'll allow you to subscribe to whenever records are invalidated, if you're looking for a way to refetch immediately as something invalidates.
#
RecordSourceSelectorProxyRecordSourceSelectorProxy and RecordSourceProxy are the two modules representing the store, with various capabilities.
RecordSourceSelectorProxy.t#
Type type representing a RecordSourceSelectorProxy .
RecordSourceSelectorProxy.getPluralRootField#
Read more about: RecordSourceSelectorProxy.t
Plural version of RecordSourceSelectorProxy.getRootField .
RecordSourceSelectorProxy.create#
Read more about: RecordSourceSelectorProxy.t, dataId, RecordProxy, RecordProxy.t
Type type representing a RecordSourceSelectorProxy .
RecordSourceSelectorProxy.delete#
Read more about: RecordSourceSelectorProxy.t, dataId
Deletes the RecordProxy with the provided dataId .
RecordSourceSelectorProxy.get#
Read more about: RecordSourceSelectorProxy.t, dataId
Returns the RecordProxy with the provided dataId , if it exists.
RecordSourceSelectorProxy.getRoot#
Read more about: RecordSourceSelectorProxy.t, RecordProxy, RecordProxy.t
Returns the root RecordProxy , meaning the RecordProxy holding your top level fields.
RecordSourceSelectorProxy.getRootField#
Read more about: RecordSourceSelectorProxy.t
Returns the RecordProxy for the fieldName
at root. You should prefer using RecordSourceSelectorProxy.getRoot()
and traverse from there if you need access to root fields rather than use this.
RecordSourceSelectorProxy.invalidateStore#
Read more about: RecordSourceSelectorProxy.t
Plural version of RecordSourceSelectorProxy.getRootField .
#
ConnectionHandlerRead the Relay docs section on ConnectionHandler
ConnectionHandler.getConnection#
Read more about: arguments, RecordProxy, RecordProxy.t
For a RecordProxy , returns the RecordProxy that is at the connection config provided.
ConnectionHandler.createEdge#
Read more about: RecordProxy, RecordProxy.t, RecordSourceSelectorProxy, RecordSourceSelectorProxy.t, RecordSource
Creates an edge for a particular connection.
ConnectionHandler.insertEdgeBefore#
Read more about: RecordProxy, RecordProxy.t
Inserts an edge into a connection before the provided cursor. If no cursor is provided, it inserts the edge at the start of the connection list.
ConnectionHandler.insertEdgeAfter#
Read more about: RecordProxy, RecordProxy.t
Inserts an edge into a connection after the provided cursor. If no cursor is provided, it inserts the edge at the end of the connection list.
ConnectionHandler.deleteNode#
Read more about: dataId, RecordProxy, RecordProxy.t
Deletes any edge from the connection where the node of the edge has the provided dataId . Please not that this will not remove the actual node from the store. Use RecordSourceSelectorProxy.delete for that.
#
ObservableA Relay observable, used throughout Relay for delivering data, in particular when dealing with multiple payloads like with subscriptions or multipart responses like @stream
or @defer
.
Observable.subscription#
A subscription for an observable, allowing you to unsubscribe if wanted.
Observable.makeObserver#
Read more about: Observable.subscription
The type representing the observable.
Observable.make#
Create a new observable, getting fed an Observable.sink
for interacting with the observable, and optionally returning a Observable.subscription if you have things you want to unsubscribe from as the observable closes.
Observable.subscribe#
Read more about: Observable.subscription
Subscribe to the Observable.t
using an observer.
Observable.toPromise#
Turns an Observable into a promise. Beware that reading the response in the resulting promise is currently not safe due to some internals of how ReScript Relay works. This will be resolved in the future.
#
NetworkRepresents the network layer.
Network.operation#
The operation fed to the NetworkLayer
when Relay wants to make a request. Please note that if you're using persisted queries, id
will exist but text
won't, and vice versa when not using persisted queries.
Network.subscribeFn#
Read more about: Observable
The shape of the function Relay expects for creating a subscription.
Network.fetchFunctionPromise#
The shape of the function responsible for fetching data if you want to return a promise rather than an Observable .
Network.fetchFunctionObservable#
Read more about: Observable
The shape of the function responsible for fetching data if you want to return an Observable .
Network.t#
The type representing an instantiated NetworkLayer
.
Network.makePromiseBased#
Read more about: Network.subscribeFn, Network.fetchFunctionPromise, Network.t
The type representing an instantiated NetworkLayer
.
Network.makeObservableBased#
Read more about: Network.subscribeFn, Network.fetchFunctionObservable, Network.t
Create a new NetworkLayer
using a fetch function that returns an Observable .
#
RecordSourceRecordSource is the source of records used by the store. Can be initiated with or without prior records; eg. hydrating the store with prior data.
RecordSource.t#
The type representing an instantiated RecordSource .
RecordSource.make#
Read more about: recordSourceRecords, RecordSource.t
The type representing an instantiated RecordSource .
RecordSource.toJSON#
Read more about: RecordSource.t, recordSourceRecords
Serializes the RecordSource into recordSourceRecords that you can use to rehydrate another store. Typically used for SSR.
#
StoreThe actual store module, with configuration for the store.
Store.t#
The type representing an instantiated Store .
Store.make#
Read more about: RecordSource, RecordSource.t, Store.t
Creates a new Store .
Store.getSource#
Read more about: Store.t, RecordSource, RecordSource.t
The type representing an instantiated Store .
Store.publish#
Read more about: Store.t
Publishes new records to this store. This is useful in particular with frameworks like Next.js where routes could preload data needed and then serialize that (using RecordSource.toJSON ) and send it over the wire, but you already have a store instantiated client side. This will then allow you to publish those records into your existing store.
#
Pseudo-example#
EnvironmentModule representing the environment, which you'll need to use and pass to various functions. Takes a few configuration options like store and network layer.
Environment.t#
The type representing an instantiated Environment .
Environment.make#
Read more about: Network, Network.t, Store, Store.t, Environment.t
Create a new Environment .
Environment.getStore#
Read more about: Environment.t, Store, Store.t
The type representing an instantiated Environment .
Environment.commitPayload#
Read more about: Environment.t
Given an operationDescriptor
, commits the corresponding payload.
#
DisposableA disposable is something you can use to dispose of something when you don't use/need it anymore.
Disposable.t#
The type representing a Disposable .
Disposable.dispose#
Read more about: Disposable.t
The type representing a Disposable .
#
ContextContext provider for the Relay environment.
Context.contextShape#
Read more about: Environment, Environment.t
The expected shape of the context.
Context.t#
Type representing the context.
Context.context#
Type representing the context.
#
ProviderThe context provider you wrap your app in and pass your Environment for Relay to work.