relay-runtime 20.1.1 → 21.0.1

package/store/RelayStoreTypes.d.ts

@@ -0,0 +1,1327 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { MutationParameters } from '../mutations/commitMutation';
+import {
+  GraphQLResponse,
+  Network,
+  PayloadData,
+  PayloadError,
+  ReactFlightServerTree,
+  UploadableMap,
+} from '../network/RelayNetworkTypes';
+import { RelayObservable } from '../network/RelayObservable';
+import { GraphQLTaggedNode } from '../query/GraphQLTag';
+import { RequestIdentifier } from '../util/getRequestIdentifier';
+import {
+  NormalizationLinkedField,
+  NormalizationScalarField,
+  NormalizationSelectableNode,
+  NormalizationSplitOperation,
+} from '../util/NormalizationNode';
+import {ReaderFragment, ReaderLinkedField} from '../util/ReaderNode';
+import {ConcreteRequest, RequestParameters} from '../util/RelayConcreteNode';
+import {
+  CacheConfig,
+  DataID,
+  Disposable,
+  OperationType,
+  RenderPolicy,
+  Variables,
+  VariablesOf,
+} from '../util/RelayRuntimeTypes';
+import { InvalidationState } from './RelayModernStore';
+import { RelayOperationTracker } from './RelayOperationTracker';
+import { RecordState } from './RelayRecordState';
+
+export type FragmentType = unknown;
+export type OperationTracker = RelayOperationTracker;
+
+/*
+ * An individual cached graph object.
+ */
+export interface Record<T extends object = Record<string, unknown>> {
+    [key: string]: T;
+}
+
+/**
+ * A collection of records keyed by id.
+ */
+export interface RecordMap {
+    // theoretically, this should be `[dataID: DataID]`, but `DataID` is a string.
+    [dataID: string]: Record | null | undefined;
+}
+
+export interface FragmentMap {
+    [key: string]: ReaderFragment;
+}
+
+/**
+ * The results of a selector given a store/RecordSource.
+ */
+export interface SelectorData {
+    [key: string]: unknown;
+}
+
+export interface SingularReaderSelector {
+    readonly kind: 'SingularReaderSelector';
+    readonly dataID: DataID;
+    readonly isWithinUnmatchedTypeRefinement: boolean;
+    readonly node: ReaderFragment;
+    readonly owner: RequestDescriptor;
+    readonly variables: Variables;
+}
+
+export type ReaderSelector = SingularReaderSelector | PluralReaderSelector;
+
+export interface PluralReaderSelector {
+    readonly kind: 'PluralReaderSelector';
+    readonly selectors: readonly SingularReaderSelector[];
+}
+
+export interface RequestDescriptor {
+    readonly identifier: RequestIdentifier;
+    readonly node: ConcreteRequest;
+    readonly variables: Variables;
+    readonly cacheConfig: CacheConfig | null;
+}
+
+/**
+ * A selector defines the starting point for a traversal into the graph for the
+ * purposes of targeting a subgraph.
+ */
+export interface NormalizationSelector {
+    readonly dataID: DataID;
+    readonly node: NormalizationSelectableNode;
+    readonly variables: Variables;
+}
+
+/**
+ * A representation of a selector and its results at a particular point in time.
+ */
+export interface TypedSnapshot<TData> {
+    readonly data: TData;
+    readonly isMissingData: boolean;
+    readonly seenRecords: RecordMap;
+    readonly selector: SingularReaderSelector;
+}
+export type Snapshot = TypedSnapshot<SelectorData>;
+
+/**
+ * An operation selector describes a specific instance of a GraphQL operation
+ * with variables applied.
+ *
+ * - `root`: a selector intended for processing server results or retaining
+ *   response data in the store.
+ * - `fragment`: a selector intended for use in reading or subscribing to
+ *   the results of the the operation.
+ */
+export interface OperationDescriptor {
+    readonly fragment: SingularReaderSelector;
+    readonly request: RequestDescriptor;
+    readonly root: NormalizationSelector;
+}
+
+/**
+ * Arbitrary data e.g. received by a container as props.
+ */
+export interface Props {
+    [key: string]: unknown;
+}
+
+/**
+ * The type of the `relay` property set on React context by the React/Relay
+ * integration layer (e.g. QueryRenderer, FragmentContainer, etc).
+ */
+export interface RelayContext {
+    environment: Environment;
+}
+
+/**
+ * The results of reading the results of a FragmentMap given some input
+ * `Props`.
+ */
+export interface FragmentSpecResults {
+    [key: string]: unknown;
+}
+
+/**
+ * A utility for resolving and subscribing to the results of a fragment spec
+ * (key -> fragment mapping) given some "props" that determine the root ID
+ * and variables to use when reading each fragment. When props are changed via
+ * `setProps()`, the resolver will update its results and subscriptions
+ * accordingly. Internally, the resolver:
+ * - Converts the fragment map & props map into a map of `Selector`s.
+ * - Removes any resolvers for any props that became null.
+ * - Creates resolvers for any props that became non-null.
+ * - Updates resolvers with the latest props.
+ */
+export interface FragmentSpecResolver {
+    /**
+     * Stop watching for changes to the results of the fragments.
+     */
+    dispose(): void;
+
+    /**
+     * Get the current results.
+     */
+    resolve(): FragmentSpecResults;
+
+    /**
+     * Update the resolver with new inputs. Call `resolve()` to get the updated
+     * results.
+     */
+    setProps(props: Props): void;
+
+    /**
+     * Override the variables used to read the results of the fragments. Call
+     * `resolve()` to get the updated results.
+     */
+    setVariables(variables: Variables, node: ConcreteRequest): void;
+
+    /**
+     * Subscribe to resolver updates.
+     * Overrides existing callback (if one has been specified).
+     */
+    setCallback(callback: () => void): void;
+}
+
+/**
+ * A read-only interface for accessing cached graph data.
+ */
+export interface RecordSource {
+    get<T extends object = Record<string, unknown>>(dataID: DataID): Record<T> | null | undefined;
+    getRecordIDs(): DataID[];
+    getStatus(dataID: DataID): RecordState;
+    has(dataID: DataID): boolean;
+    size(): number;
+    toJSON(): { [key: string]: Record };
+}
+
+/**
+ * A read/write interface for accessing and updating graph data.
+ */
+export interface MutableRecordSource extends RecordSource {
+    clear(): void;
+    delete(dataID: DataID): void;
+    remove(dataID: DataID): void;
+    set(dataID: DataID, record: Record): void;
+}
+
+export interface CheckOptions {
+    target: MutableRecordSource;
+    handlers: readonly MissingFieldHandler[];
+}
+
+export type OperationAvailability =
+    | {
+        status: 'available';
+        fetchTime: number | null | undefined;
+    }
+    | { status: 'stale' }
+    | { status: 'missing' };
+
+export { InvalidationState } from './RelayModernStore';
+
+/**
+ * An interface for keeping multiple views of data consistent across an
+ * application.
+ */
+export interface Store {
+    /**
+     * Get a read-only view of the store's internal RecordSource.
+     */
+    getSource(): RecordSource;
+
+    /**
+     * Determine if the operation can be resolved with data in the store (i.e. no
+     * fields are missing).
+     */
+    check(operation: OperationDescriptor, options?: CheckOptions): OperationAvailability;
+
+    /**
+     * Read the results of a selector from in-memory records in the store.
+     * Optionally takes an owner, corresponding to the operation that
+     * owns this selector (fragment).
+     */
+    lookup(selector: SingularReaderSelector): Snapshot;
+
+    /**
+     * Notify subscribers (see `subscribe`) of any data that was published
+     * (`publish()`) since the last time `notify` was called.
+     * Optionally provide an OperationDescriptor indicating the source operation
+     * that was being processed to produce this run.
+     *
+     * This method should return an array of the affected fragment owners
+     */
+    notify(sourceOperation?: OperationDescriptor, invalidateStore?: boolean): readonly RequestDescriptor[];
+
+    /**
+     * Publish new information (e.g. from the network) to the store, updating its
+     * internal record source. Subscribers are not immediately notified - this
+     * occurs when `notify()` is called.
+     */
+    publish(source: RecordSource, idsMarkedForInvalidation?: DataIDSet): void;
+
+    /**
+     * Ensure that all the records necessary to fulfill the given selector are
+     * retained in-memory. The records will not be eligible for garbage collection
+     * until the returned reference is disposed.
+     */
+    retain(operation: OperationDescriptor): Disposable;
+
+    /**
+     * Subscribe to changes to the results of a selector. The callback is called
+     * when `notify()` is called *and* records have been published that affect the
+     * selector results relative to the last `notify()`.
+     */
+    subscribe(snapshot: Snapshot, callback: (snapshot: Snapshot) => void): Disposable;
+
+    /**
+     * The method should disable garbage collection until
+     * the returned reference is disposed.
+     */
+    holdGC(): Disposable;
+
+    /**
+     * Record a backup/snapshot of the current state of the store, including
+     * records and derived data such as fragment and connection subscriptions.
+     * This state can be restored with restore().
+     */
+    snapshot(): void;
+
+    /**
+     * Reset the state of the store to the point that snapshot() was last called.
+     */
+    restore(): void;
+
+    /**
+     * Will return an opaque snapshot of the current invalidation state of
+     * the data ids that were provided.
+     */
+    lookupInvalidationState(dataIDs: readonly DataID[]): InvalidationState;
+
+    /**
+     * Given the previous invalidation state for those
+     * ids, this function will return:
+     *   - false, if the invalidation state for those ids is the same, meaning
+     *     **it has not changed**
+     *   - true, if the invalidation state for the given ids has changed
+     */
+    checkInvalidationState(previousInvalidationState: InvalidationState): boolean;
+
+    /**
+     * Will subscribe the provided callback to the invalidation state of the
+     * given data ids. Whenever the invalidation state for any of the provided
+     * ids changes, the callback will be called, and provide the latest
+     * invalidation state.
+     * Disposing of the returned disposable will remove the subscription.
+     */
+    subscribeToInvalidationState(invalidationState: InvalidationState, callback: () => void): Disposable;
+}
+
+/**
+ * A type that accepts a callback and schedules it to run at some future time.
+ * By convention, implementations should not execute the callback immediately.
+ */
+export type Scheduler = (callback: () => void) => void;
+
+/**
+ * An interface for imperatively getting/setting properties of a `Record`. This interface
+ * is designed to allow the appearance of direct Record manipulation while
+ * allowing different implementations that may e.g. create a changeset of
+ * the modifications.
+ */
+export type Unarray<T> = T extends Array<infer U> | ReadonlyArray<infer U> ? U : T;
+export type Primitive = string | number | boolean | null | undefined;
+
+export interface RecordProxy<T = Record<string, unknown>> {
+    copyFieldsFrom(source: RecordProxy): void;
+    getDataID(): DataID;
+    // If a parent type is provided, provide the child type
+    getLinkedRecord<K extends keyof T>(name: K, args?: Variables | null): RecordProxy<NonNullable<T[K]>>;
+    // If a hint is provided, the return value is guaranteed to be the hint type
+    getLinkedRecord<H = never>(
+        name: string,
+        args?: Variables | null,
+    ): [H] extends [never] ? RecordProxy | null : RecordProxy<H>;
+    getLinkedRecords<K extends keyof T>(
+        name: K,
+        args?: Variables | null,
+    ): Array<RecordProxy<Unarray<NonNullable<T[K]>>>>;
+    getLinkedRecords<H = never>(
+        name: string,
+        args?: Variables | null,
+    ): [H] extends [never] ? RecordProxy[] | null
+        : NonNullable<H> extends Array<infer U> ? Array<RecordProxy<U>> | (H extends null ? null : never)
+        : never;
+    getOrCreateLinkedRecord<K extends keyof T>(
+        name: K,
+        typeName: string,
+        args?: Variables | null,
+    ): RecordProxy<NonNullable<T[K]>>;
+    getOrCreateLinkedRecord(name: string, typeName: string, args?: Variables | null): RecordProxy<T>;
+    getType(): string;
+    getValue<K extends keyof T>(name: K, args?: Variables | null): T[K];
+    getValue(name: string, args?: Variables | null): Primitive | Primitive[];
+    setLinkedRecord<K extends keyof T>(
+        record: RecordProxy<T[K]> | null,
+        name: K,
+        args?: Variables | null,
+    ): RecordProxy<T>;
+    setLinkedRecord(record: RecordProxy | null, name: string, args?: Variables | null): RecordProxy;
+    setLinkedRecords<K extends keyof T>(
+        records: Array<RecordProxy<Unarray<T[K]>> | null> | null | undefined,
+        name: K,
+        args?: Variables | null,
+    ): RecordProxy<T>;
+    setLinkedRecords(
+        records: Array<RecordProxy | null> | null | undefined,
+        name: string,
+        args?: Variables | null,
+    ): RecordProxy<T>;
+    setValue<K extends keyof T>(value: T[K], name: K, args?: Variables | null): RecordProxy<T>;
+    setValue(value: Primitive | Primitive[], name: string, args?: Variables | null): RecordProxy;
+    invalidateRecord(): void;
+}
+
+export interface ReadOnlyRecordProxy {
+    getDataID(): DataID;
+    getLinkedRecord(name: string, args?: Variables): RecordProxy | null | undefined;
+    getLinkedRecords(name: string, args?: Variables): Array<RecordProxy | null | undefined> | null | undefined;
+    getType(): string;
+    getValue(name: string, args?: Variables | null): unknown;
+}
+
+/**
+ * An interface for imperatively getting/setting properties of a `RecordSource`. This interface
+ * is designed to allow the appearance of direct RecordSource manipulation while
+ * allowing different implementations that may e.g. create a changeset of
+ * the modifications.
+ */
+
+export interface RecordSourceProxy {
+    create(dataID: DataID, typeName: string): RecordProxy;
+    delete(dataID: DataID): void;
+    get<T = Record<string, unknown>>(dataID: DataID): RecordProxy<T> | null | undefined;
+    getRoot(): RecordProxy;
+}
+
+export interface ReadOnlyRecordSourceProxy {
+    get(dataID: DataID): ReadOnlyRecordProxy | null | undefined;
+    getRoot(): ReadOnlyRecordProxy;
+}
+
+/**
+ * Extends the RecordSourceProxy interface with methods for accessing the root
+ * fields of a Selector.
+ */
+
+export interface RecordSourceSelectorProxy<T = Record<string, unknown>> extends RecordSourceProxy {
+    getRootField<K extends keyof T>(fieldName: K): RecordProxy<NonNullable<T[K]>>;
+    getRootField(fieldName: string): RecordProxy | null;
+    getPluralRootField(fieldName: string): Array<RecordProxy<T> | null> | null;
+    invalidateStore(): void;
+    readUpdatableQuery<TQuery extends OperationType>(
+        gqlQuery: GraphQLTaggedNode,
+        variables: VariablesOf<TQuery>,
+    ): UpdatableQueryData<TQuery>;
+    readUpdatableFragment<TKey extends HasUpdatableSpread>(
+        fragmentInput: GraphQLTaggedNode,
+        fragmentRef: TKey,
+    ): UpdatableFragmentData<TKey>;
+}
+
+export type LogEvent =
+    | Readonly<{
+        name: 'suspense.fragment';
+        data: unknown;
+        fragment: ReaderFragment;
+        isRelayHooks: boolean;
+        isMissingData: boolean;
+        isPromiseCached: boolean;
+        pendingOperations: readonly RequestDescriptor[];
+    }>
+    | Readonly<{
+        name: 'suspense.query';
+        fetchPolicy: string;
+        isPromiseCached: boolean;
+        operation: OperationDescriptor;
+        queryAvailability?: OperationAvailability | undefined;
+        renderPolicy: RenderPolicy;
+    }>
+    | Readonly<{
+        name: 'queryresource.fetch';
+        /**
+         * ID of this query resource request and will be the same if there is an associated queryresource.retain event.
+         */
+        resourceID: number;
+        operation: OperationDescriptor;
+        // value from ProfilerContext
+        profilerContext: unknown;
+        // FetchPolicy from Relay Hooks
+        fetchPolicy: string;
+        // RenderPolicy from Relay Hooks
+        renderPolicy: RenderPolicy;
+        queryAvailability: OperationAvailability;
+        shouldFetch: boolean;
+    }>
+    | Readonly<{
+        name: 'queryresource.retain';
+        resourceID: number;
+        // value from ProfilerContext
+        profilerContext: unknown;
+    }>
+    | Readonly<{
+        // Indicates FragmentResource is going to return a result that is missing data.
+        name: 'fragmentresource.missing_data';
+        data: unknown;
+        fragment: ReaderFragment;
+        isRelayHooks: boolean;
+        // Are we reading this result from the fragment resource cache?
+        cached: boolean;
+    }>
+    | Readonly<{
+        /**
+         * Indicates getPendingOperationForFragment identified a pending operation.
+         * Useful for measuring how frequently RelayOperationTracker identifies a related operation on which to suspend.
+         */
+        name: 'pendingoperation.found';
+        fragment: ReaderFragment;
+        fragmentOwner: RequestDescriptor;
+        pendingOperations: ReadonlyArray<RequestDescriptor>;
+    }>
+    | Readonly<{
+        name: 'network.info';
+        networkRequestId: number;
+        info: unknown;
+    }>
+    | Readonly<{
+        name: 'network.start';
+        networkRequestId: number;
+        params: RequestParameters;
+        variables: Variables;
+        cacheConfig: CacheConfig;
+    }>
+    | Readonly<{
+        name: 'network.next';
+        networkRequestId: number;
+        response: GraphQLResponse;
+    }>
+    | Readonly<{
+        name: 'network.error';
+        networkRequestId: number;
+        error: Error;
+    }>
+    | Readonly<{
+        name: 'network.complete';
+        networkRequestId: number;
+    }>
+    | Readonly<{
+        name: 'network.unsubscribe';
+        networkRequestId: number;
+    }>
+    | Readonly<{
+        name: 'execute.start';
+        executeId: number;
+        params: RequestParameters;
+        variables: Variables;
+        cacheConfig: CacheConfig;
+    }>
+    | Readonly<{
+        name: 'execute.next.start';
+        executeId: number;
+        response: GraphQLResponse;
+        operation: OperationDescriptor;
+    }>
+    | Readonly<{
+        name: 'execute.next.end';
+        executeId: number;
+        response: GraphQLResponse;
+        operation: OperationDescriptor;
+    }>
+    | Readonly<{
+        name: 'execute.async.module';
+        executeId: number;
+        operationName: string;
+        duration: number;
+    }>
+    | Readonly<{
+        name: 'execute.error';
+        executeId: number;
+        error: Error;
+    }>
+    | Readonly<{
+        name: 'execute.complete';
+        executeId: number;
+    }>
+    | Readonly<{
+        name: 'execute.normalize.start';
+        operation: OperationDescriptor;
+    }>
+    | Readonly<{
+        name: 'execute.normalize.end';
+        operation: OperationDescriptor;
+    }>
+    | Readonly<{
+        name: 'store.datachecker.start';
+        selector: NormalizationSelector;
+    }>
+    | Readonly<{
+        name: 'store.datachecker.end';
+        selector: NormalizationSelector;
+    }>
+    | Readonly<{
+        name: 'store.publish';
+        source: RecordSource;
+        optimistic: boolean;
+    }>
+    | Readonly<{
+        name: 'store.snapshot';
+    }>
+    | Readonly<{
+        name: 'store.lookup.start';
+        selector: SingularReaderSelector;
+    }>
+    | Readonly<{
+        name: 'store.lookup.end';
+        selector: SingularReaderSelector;
+    }>
+    | Readonly<{
+        name: 'store.restore';
+    }>
+    | Readonly<{
+        name: 'store.gc.start';
+    }>
+    | Readonly<{
+        name: 'store.gc.interrupted';
+    }>
+    | Readonly<{
+        name: 'store.gc.end';
+        references: DataIDSet;
+    }>
+    | Readonly<{
+        name: 'store.notify.start';
+        sourceOperation?: OperationDescriptor | undefined;
+    }>
+    | Readonly<{
+        name: 'store.notify.complete';
+        sourceOperation?: OperationDescriptor | undefined;
+        updatedRecordIDs: DataIDSet;
+        invalidatedRecordIDs: DataIDSet;
+        subscriptionsSize: number;
+        updatedOwners: Array<RequestDescriptor>;
+    }>
+    | Readonly<{
+        name: 'store.notify.subscription';
+        sourceOperation?: OperationDescriptor | undefined;
+        snapshot: Snapshot;
+        nextSnapshot: Snapshot;
+    }>
+    | Readonly<{
+        name: 'entrypoint.root.consume';
+        profilerContext: unknown;
+        rootModuleID: string;
+    }>
+    | Readonly<{
+        name: 'liveresolver.batch.start';
+    }>
+    | Readonly<{
+        name: 'liveresolver.batch.end';
+    }>
+    | Readonly<{
+        name: 'useFragment.subscription.missedUpdates';
+        hasDataChanges: boolean;
+    }>;
+
+export type LogFunction = (logEvent: LogEvent) => void;
+
+/**
+ * The public API of Relay core. Represents an encapsulated environment with its
+ * own in-memory cache.
+ */
+export interface Environment {
+    /**
+     * Extra information attached to the environment instance
+     */
+    options: unknown;
+
+    /**
+     * Determine if the operation can be resolved with data in the store (i.e. no
+     * fields are missing).
+     *
+     * Note that this operation effectively "executes" the selector against the
+     * cache and therefore takes time proportional to the size/complexity of the
+     * selector.
+     */
+    check(operation: OperationDescriptor, options?: CheckOptions): OperationAvailability;
+
+    /**
+     * Subscribe to changes to the results of a selector. The callback is called
+     * when data has been committed to the store that would cause the results of
+     * the snapshot's selector to change.
+     */
+    subscribe(snapshot: Snapshot, callback: (snapshot: Snapshot) => void): Disposable;
+
+    /**
+     * Ensure that all the records necessary to fulfill the given operation are
+     * retained in-memory. The records will not be eligible for garbage collection
+     * until the returned reference is disposed.
+     */
+    retain(operation: OperationDescriptor): Disposable;
+
+    /**
+     * Apply an optimistic update to the environment. The mutation can be reverted
+     * by calling `dispose()` on the returned value.
+     */
+    applyUpdate(optimisticUpdate: OptimisticUpdateFunction): Disposable;
+
+    /**
+     * Apply an optimistic mutation response and/or updater. The mutation can be
+     * reverted by calling `dispose()` on the returned value.
+     */
+    applyMutation(optimisticConfig: OptimisticResponseConfig): Disposable;
+
+    /**
+     * Commit an updater to the environment. This mutation cannot be reverted and
+     * should therefore not be used for optimistic updates. This is mainly
+     * intended for updating fields from client schema extensions.
+     */
+    commitUpdate(updater: StoreUpdater): void;
+
+    /**
+     * Commit a payload to the environment using the given operation selector.
+     */
+    commitPayload(operationDescriptor: OperationDescriptor, payload: PayloadData): void;
+
+    /**
+     * Get the environment's internal Network.
+     */
+    getNetwork(): Network;
+
+    /**
+     * Get the environment's internal Store.
+     */
+    getStore(): Store;
+
+    /**
+     * Returns the environment specific OperationTracker.
+     */
+    getOperationTracker(): RelayOperationTracker;
+
+    /**
+     * Read the results of a selector from in-memory records in the store.
+     * Optionally takes an owner, corresponding to the operation that
+     * owns this selector (fragment).
+     */
+    lookup(selector: SingularReaderSelector): Snapshot;
+
+    /**
+     * Send a query to the server with Observer semantics: one or more
+     * responses may be returned (via `next`) over time followed by either
+     * the request completing (`completed`) or an error (`error`).
+     *
+     * Networks/servers that support subscriptions may choose to hold the
+     * subscription open indefinitely such that `complete` is not called.
+     *
+     * Note: Observables are lazy, so calling this method will do nothing until
+     * the result is subscribed to: environment.execute({...}).subscribe({...}).
+     */
+    execute(config: {
+        operation: OperationDescriptor;
+        updater?: SelectorStoreUpdater | null | undefined;
+    }): RelayObservable<GraphQLResponse>;
+
+    /**
+     * Returns an Observable of GraphQLResponse resulting from executing the
+     * provided Mutation operation, the result of which is then normalized and
+     * committed to the publish queue along with an optional optimistic response
+     * or updater.
+     *
+     * Note: Observables are lazy, so calling this method will do nothing until
+     * the result is subscribed to:
+     * environment.executeMutation({...}).subscribe({...}).
+     */
+    executeMutation({
+        operation,
+        optimisticUpdater,
+        optimisticResponse,
+        updater,
+        uploadables,
+    }: {
+        operation: OperationDescriptor;
+        optimisticUpdater?: SelectorStoreUpdater | null | undefined;
+        optimisticResponse?: { [key: string]: any } | null | undefined;
+        updater?: SelectorStoreUpdater | null | undefined;
+        uploadables?: UploadableMap | null | undefined;
+    }): RelayObservable<GraphQLResponse>;
+
+    /**
+     * Returns an Observable of GraphQLResponse resulting from executing the
+     * provided Query or Subscription operation responses, the result of which is
+     * then normalized and committed to the publish queue.
+     *
+     * Note: Observables are lazy, so calling this method will do nothing until
+     * the result is subscribed to:
+     * environment.executeWithSource({...}).subscribe({...}).
+     */
+    executeWithSource({
+        operation,
+        source,
+    }: {
+        operation: OperationDescriptor;
+        source: RelayObservable<GraphQLResponse>;
+    }): RelayObservable<GraphQLResponse>;
+
+    /**
+     * Returns true if a request is currently "active", meaning it's currently
+     * actively receiving payloads or downloading modules, and has not received
+     * a final payload yet. Note that a request might still be pending (or "in flight")
+     * without actively receiving payload, for example a live query or an
+     * active GraphQL subscription
+     */
+    isRequestActive(requestIdentifier: string): boolean;
+
+    /**
+     * Returns true if the environment is for use during server side rendering.
+     * functions like getQueryResource key off of this in order to determine
+     * whether we need to set up certain caches and timeout's.
+     */
+    isServer(): boolean;
+
+    /**
+     * Called by Relay when it encounters a missing field that has been annotated
+     * with `@required(action: LOG)` or `@required(action: THROW)`.
+     */
+    relayFieldLogger: RelayFieldLogger;
+}
+
+/**
+ * The results of reading data for a fragment. This is similar to a `Selector`,
+ * but references the (fragment) node by name rather than by value.
+ */
+export interface FragmentPointer {
+    __id: DataID;
+    __fragments: { [fragmentName: string]: Variables };
+    __fragmentOwner: RequestDescriptor;
+}
+
+// tslint:disable:no-redundant-jsdoc-2
+/**
+ * The partial shape of an object with a '...Fragment @module(name: "...")'
+ * selection
+ */
+export interface ModuleImportPointer {
+    readonly __fragmentPropName: string | null | undefined;
+    readonly __module_component: unknown;
+    readonly $fragmentSpreads: unknown;
+}
+// tslint:enable:no-redundant-jsdoc-2
+
+/**
+ * A callback for resolving a Selector from a source.
+ */
+export type AsyncLoadCallback = (loadingState: LoadingState) => void;
+export interface LoadingState {
+    status: 'aborted' | 'complete' | 'error' | 'missing';
+    error?: Error | undefined;
+}
+
+export type DataIDSet = Set<DataID>;
+
+/**
+ * A function that updates a store (via a proxy) given the results of a "handle"
+ * field payload.
+ */
+export class Handler {
+    update: (store: RecordSourceProxy, fieldPayload: HandleFieldPayload) => void;
+}
+
+/**
+ * A payload that is used to initialize or update a "handle" field with
+ * information from the server.
+ */
+export interface HandleFieldPayload {
+    // The arguments that were fetched.
+    readonly args: Variables;
+    // The __id of the record containing the source/handle field.
+    readonly dataID: DataID;
+    // The (storage) key at which the original server data was written.
+    readonly fieldKey: string;
+    // The name of the handle.
+    readonly handle: string;
+    // The (storage) key at which the handle's data should be written by the
+    // handler.
+    readonly handleKey: string;
+}
+
+/**
+ * A payload that represents data necessary to process the results of an object
+ * with a `@module` fragment spread:
+ * - data: The GraphQL response value for the @match field.
+ * - dataID: The ID of the store object linked to by the @match field.
+ * - operationReference: A reference to a generated module containing the
+ *   SplitOperation with which to normalize the field's `data`.
+ * - variables: Query variables.
+ * - typeName: the type that matched.
+ *
+ * The dataID, variables, and fragmentName can be used to create a Selector
+ * which can in turn be used to normalize and publish the data. The dataID and
+ * typeName can also be used to construct a root record for normalization.
+ */
+export interface ModuleImportPayload {
+    readonly data: PayloadData;
+    readonly dataID: DataID;
+    readonly operationReference: any;
+    readonly path: readonly string[];
+    readonly typeName: string;
+    readonly variables: Variables;
+}
+
+/**
+ * Data emitted after processing a Defer or Stream node during normalization
+ * that describes how to process the corresponding response chunk when it
+ * arrives.
+ */
+export interface DeferPlaceholder {
+    readonly kind: 'defer';
+    readonly data: PayloadData;
+    readonly label: string;
+    readonly path: readonly string[];
+    readonly selector: NormalizationSelector;
+    readonly typeName: string;
+}
+export interface StreamPlaceholder {
+    readonly kind: 'stream';
+    readonly label: string;
+    readonly path: readonly string[];
+    readonly parentID: DataID;
+    readonly node: NormalizationSelectableNode;
+    readonly variables: Variables;
+}
+export type IncrementalDataPlaceholder = DeferPlaceholder | StreamPlaceholder;
+
+/**
+ * A user-supplied object to load a generated operation (SplitOperation) AST
+ * by a module reference. The exact format of a module reference is left to
+ * the application, but it must be a plain JavaScript value (string, number,
+ * or object/array of same).
+ */
+export interface OperationLoader {
+    /**
+     * Synchronously load an operation, returning either the node or null if it
+     * cannot be resolved synchronously.
+     */
+    get(reference: unknown): NormalizationSplitOperation | null | undefined;
+
+    /**
+     * Asynchronously load an operation.
+     */
+    load(reference: unknown): Promise<NormalizationSplitOperation | null | undefined>;
+}
+
+/**
+ * A function that receives a proxy over the store and may trigger side-effects
+ * (indirectly) by calling `set*` methods on the store or its record proxies.
+ */
+export type StoreUpdater = (store: RecordSourceProxy) => void;
+
+/**
+ * Similar to StoreUpdater, but accepts a proxy tied to a specific selector in
+ * order to easily access the root fields of a query/mutation as well as a
+ * second argument of the response object of the mutation.
+ */
+export type SelectorStoreUpdater<T = object> = (
+    store: RecordSourceSelectorProxy<T>,
+    data: T | null | undefined,
+) => void;
+
+/**
+ * A set of configs that can be used to apply an optimistic update into the
+ * store.
+ */
+export type OptimisticUpdate = OptimisticUpdateFunction | OptimisticUpdateRelayPayload;
+
+export interface OptimisticUpdateFunction {
+    readonly storeUpdater: StoreUpdater;
+}
+
+export interface OptimisticUpdateRelayPayload {
+    readonly operation: OperationDescriptor;
+    readonly payload: RelayResponsePayload;
+    readonly updater: SelectorStoreUpdater | null | undefined;
+}
+
+export interface OptimisticResponseConfig<TMutation extends MutationParameters = any> {
+    readonly operation: OperationDescriptor;
+    readonly response: PayloadData | null | undefined;
+    readonly updater: SelectorStoreUpdater<TMutation> | null | undefined;
+}
+
+/**
+ * A set of handlers that can be used to provide substitute data for missing
+ * fields when reading a selector from a source.
+ */
+export type MissingFieldHandler =
+    | {
+        kind: 'scalar';
+        handle: (
+            field: NormalizationScalarField,
+            parentRecord: ReadOnlyRecordProxy | null | undefined,
+            args: Variables,
+            store: ReadOnlyRecordSourceProxy,
+        ) => unknown;
+    }
+    | {
+        kind: 'linked';
+        handle: (
+            field: NormalizationLinkedField | ReaderLinkedField,
+            parentRecord: ReadOnlyRecordProxy | null | undefined,
+            args: Variables,
+            store: ReadOnlyRecordSourceProxy,
+        ) => DataID | null | undefined;
+    }
+    | {
+        kind: 'pluralLinked';
+        handle: (
+            field: NormalizationLinkedField | ReaderLinkedField,
+            parentRecord: ReadOnlyRecordProxy | null | undefined,
+            args: Variables,
+            store: ReadOnlyRecordSourceProxy,
+        ) => Array<DataID | null | undefined> | null | undefined;
+    };
+
+type TRelayFieldErrorForDisplay = Readonly<{
+    path?: ReadonlyArray<string | number>;
+    severity?: 'CRITICAL' | 'ERROR' | 'WARNING';
+}>;
+
+export type TRelayFieldError =
+    & TRelayFieldErrorForDisplay
+    & Readonly<{
+        message: string;
+    }>;
+
+/**
+ * Data which Relay expected to be in the store (because it was requested by
+ * the parent query/mutation/subscription) was missing. This can happen due
+ * to graph relationship changes observed by other queries/mutations, or
+ * imperative updates that don't provide all needed data.
+ *
+ * https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change
+ *
+ * In this case Relay will render with the referenced field as `undefined`.
+ *
+ * __NOTE__: This may break with the type contract of Relay's generated types.
+ *
+ * To turn this into a hard error for a given fragment/query, you can use
+ * `@throwOnFieldError`.
+ *
+ * https://relay.dev/docs/next/guides/throw-on-field-error-directive/
+ */
+type MissingExpectedDataLogEvent = Readonly<{
+    kind: 'missing_expected_data.log';
+    owner: string;
+    fieldPath: string;
+}>;
+
+/**
+ * Data which Relay expected to be in the store (because it was requested by
+ * the parent query/mutation/subscription) was missing. This can happen due
+ * to graph relationship changes observed by other queries/mutations, or
+ * imperative updates that don't provide all needed data.
+ *
+ * https://relay.dev/docs/next/debugging/why-null/#graph-relationship-change
+ *
+ * This event is as `.throw` because the missing data was encountered in a
+ * query/fragment/mutation with `@throwOnFieldError` `@throwOnFieldError`.
+ *
+ * https://relay.dev/docs/next/guides/throw-on-field-error-directive/
+ *
+ * Relay will throw immediately after logging this event. If you wish to
+ * customize the error being thrown, you may throw your own error.
+ *
+ * *NOTE*: Only throw on this event if `handled` is false. Errors that have been
+ * handled by a `@catch` directive or by making a resolver null will have
+ * `handled: true` and should not trigger a throw.
+ */
+type MissingExpectedDataThrowEvent = Readonly<{
+    kind: 'missing_expected_data.throw';
+    owner: string;
+    fieldPath: string;
+    handled: boolean;
+}>;
+
+/**
+ * A field was marked as @required(action: LOG) but was null or missing in the
+ * store.
+ */
+type MissingRequiredFieldLogEvent = Readonly<{
+    kind: 'missing_required_field.log';
+    owner: string;
+    fieldPath: string;
+}>;
+
+/**
+ * A field was marked as @required(action: THROW) but was null or missing in the
+ * store.
+ *
+ * Relay will throw immediately after logging this event. If you wish to
+ * customize the error being thrown, you may throw your own error.
+ *
+ * *NOTE*: Only throw on this event if `handled` is false. Errors that have been
+ * handled by a `@catch` directive or by making a resolver null will have
+ * `handled: true` and should not trigger a throw.
+ */
+type MissingRequiredFieldThrowEvent = Readonly<{
+    kind: 'missing_required_field.throw';
+    owner: string;
+    fieldPath: string;
+    handled: boolean;
+}>;
+
+/**
+ * A Relay Resolver that is currently being read threw a JavaScript error when
+ * it was last evaluated. By default, the value has been coerced to null and
+ * passed to the product code.
+ *
+ * If `@throwOnFieldError` was used on the parent query/fragment/mutation, you
+ * will also receive a TODO
+ *
+ * *NOTE*: Only throw on this event if `handled` is false. Errors that have been
+ * handled by a `@catch` directive or by making a resolver null will have
+ * `handled: true` and should not trigger a throw.
+ */
+type RelayResolverErrorEvent = Readonly<{
+    kind: 'relay_resolver.error';
+    owner: string;
+    fieldPath: string;
+    error: Error;
+    shouldThrow: boolean;
+    handled: boolean;
+}>;
+
+/**
+ * A field being read by Relay was marked as being in an error state by the
+ * GraphQL response.
+ *
+ * https://spec.graphql.org/October2021/#sec-Errors.Field-errors
+ *
+ * If the field's parent query/fragment/mutation was annotated with
+ * `@throwOnFieldError` and no `@catch` directive was used to catch the error,
+ * Relay will throw an error immediately after logging this event.
+ *
+ * https://relay.dev/docs/next/guides/catch-directive/
+ * https://relay.dev/docs/next/guides/throw-on-field-error-directive/
+ *
+ * *NOTE*: Only throw on this event if `handled` is false. Errors that have been
+ * handled by a `@catch` directive or by making a resolver null will have
+ * `handled: true` and should not trigger a throw.
+ */
+type RelayFieldPayloadErrorEvent = Readonly<{
+    kind: 'relay_field_payload.error';
+    owner: string;
+    fieldPath: string;
+    error: TRelayFieldError;
+    shouldThrow: boolean;
+    handled: boolean;
+}>;
+
+/**
+ * Union of all RelayFieldLoggerEvent types
+ */
+export type RelayFieldLoggerEvent =
+    | MissingExpectedDataLogEvent
+    | MissingExpectedDataThrowEvent
+    | MissingRequiredFieldLogEvent
+    | MissingRequiredFieldThrowEvent
+    | RelayResolverErrorEvent
+    | RelayFieldPayloadErrorEvent;
+
+/**
+ * A handler for events related to field errors.
+ */
+export type RelayFieldLogger = (event: RelayFieldLoggerEvent) => void;
+
+/**
+ * The results of normalizing a query.
+ */
+export interface RelayResponsePayload {
+    readonly errors: PayloadError[] | null | undefined;
+    readonly fieldPayloads: HandleFieldPayload[] | null | undefined;
+    readonly incrementalPlaceholders: IncrementalDataPlaceholder[] | null | undefined;
+    readonly moduleImportPayloads: ModuleImportPayload[] | null | undefined;
+    readonly source: MutableRecordSource;
+    readonly isFinal: boolean;
+}
+
+/**
+ * Configuration on the executeMutation(...).
+ */
+export interface ExecuteMutationConfig<TMutation extends MutationParameters> {
+    operation: OperationDescriptor;
+    optimisticUpdater?: SelectorStoreUpdater<TMutation['response']> | null;
+    optimisticResponse?: { [key: string]: any } | null;
+    updater?: SelectorStoreUpdater<TMutation['response']> | null;
+    uploadables?: UploadableMap | null;
+}
+
+/**
+ * Public interface for Publish Queue
+ */
+export interface PublishQueue {
+    /**
+     * Schedule applying an optimistic updates on the next `run()`.
+     */
+    applyUpdate(updater: OptimisticUpdate): void;
+
+    /**
+     * Schedule reverting an optimistic updates on the next `run()`.
+     */
+    revertUpdate(updater: OptimisticUpdate): void;
+
+    /**
+     * Schedule a revert of all optimistic updates on the next `run()`.
+     */
+    revertAll(): void;
+
+    /**
+     * Schedule applying a payload to the store on the next `run()`.
+     */
+    commitPayload(
+        operation: OperationDescriptor,
+        payload: RelayResponsePayload,
+        updater?: SelectorStoreUpdater | null,
+    ): void;
+
+    /**
+     * Schedule an updater to mutate the store on the next `run()` typically to
+     * update client schema fields.
+     */
+    commitUpdate(updater: StoreUpdater): void;
+
+    /**
+     * Schedule a publish to the store from the provided source on the next
+     * `run()`. As an example, to update the store with substituted fields that
+     * are missing in the store.
+     */
+    commitSource(source: RecordSource): void;
+
+    /**
+     * Execute all queued up operations from the other public methods.
+     */
+    run(): readonly RequestDescriptor[];
+}
+
+/**
+ * ReactFlightDOMRelayClient processes a ReactFlightServerTree into a
+ * ReactFlightClientResponse object. readRoot() can suspend.
+ */
+export interface ReactFlightClientResponse {
+    readRoot: () => any;
+}
+
+export interface ReactFlightReachableQuery {
+    readonly module: any;
+    readonly variables: Variables;
+}
+
+export type ReactFlightPayloadDeserializer = (tree: ReactFlightServerTree) => ReactFlightClientResponse;
+
+interface FieldLocation {
+    path: string;
+    owner: string;
+}
+
+export type MissingRequiredFields =
+    | Readonly<{ action: 'THROW'; field: FieldLocation }>
+    | Readonly<{ action: 'LOG'; fields: FieldLocation[] }>;
+
+export interface RelayResolverError {
+    field: FieldLocation;
+    error: Error;
+}
+
+export type RelayResolverErrors = RelayResolverError[];
+
+/**
+ * The return type of calls to store.readUpdatableFragment.
+ */
+export interface UpdatableFragmentData<TKey extends HasUpdatableSpread<TData>, TData = unknown> {
+    readonly updatableData: Required<TKey>[' $data'];
+}
+
+/**
+ * The return type of calls to store.readUpdatableQuery.
+ */
+export interface UpdatableQueryData<TQuery extends OperationType> {
+    readonly updatableData: TQuery['response'];
+}
+
+/**
+ * A linked field where an updatable fragment is spread has the type
+ * HasUpdatableSpread.
+ * This type is expected by store.readUpdatableFragment.
+ */
+export type HasUpdatableSpread<TData = unknown> = Readonly<{
+    ' $data'?: TData | undefined;
+    $updatableFragmentSpreads: FragmentType;
+}>;
+
+/**
+ * The return type of a Live Resolver. Models an external value which can
+ * be read lazily and which might change over time. The subscribe method
+ * returns a callback which should be called when the value _may_ have changed.
+ *
+ * While over-notification (subscription notifications when the read value has
+ * not actually changed) is suported, for performance reasons, it is recommended
+ * that the provider of the LiveState value confirms that the value has indeed
+ * change before notifying Relay of the change.
+ */
+export interface LiveState<T> {
+    /**
+     * Returns the current value of the live state.
+     */
+    read(): T;
+
+    /**
+     * Subscribes to changes in the live state. The state provider should
+     * call the callback when the value of the live state changes.
+     * If the returned unsubscribe function is invoked, the state provider
+     * should stop calling the callback for state updates.
+     */
+    subscribe(callback: () => void): () => void;
+}
+
+export function suspenseSentinel(): never;
+
+/**
+ * A placeholder type for the context that will be provided to resolvers.
+ * The actual type used will be determined by the `resolverContextType` type specified in your Relay project config.
+ *
+ * When set on the Relay Store, this context will be passed as the third argument to all resolvers (live and non-live).
+ *
+ * @see {@link https://relay.dev/docs/next/guides/relay-resolvers/context/#type-checking} for documentation on configuring resolverContextType
+ */
+export type ResolverContext = unknown;
+
+export type KeyType<TData = unknown> = Readonly<{
+    ' $data'?: TData | undefined;
+    ' $fragmentSpreads': FragmentType;
+}>;
+
+export type KeyTypeData<TKey extends KeyType<TData>, TData = unknown> = Required<TKey>[' $data'];
+
+export type ArrayKeyType<TData = unknown> = ReadonlyArray<KeyType<readonly TData[]> | null | undefined>;
+export type ArrayKeyTypeData<TKey extends ArrayKeyType<TData>, TData = unknown> = KeyTypeData<
+    NonNullable<TKey[number]>
+>;
+
+export type FragmentState<T> =
+    | { state: 'ok'; value: T }
+    | { state: 'error'; error: Error }
+    | { state: 'loading' };