relay-runtime 21.0.0 → 21.0.1

package/multi-actor-environment/MultiActorEnvironment.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 { HandlerProvider } from '../handlers/RelayDefaultHandlerProvider';
+import { MutationParameters } from '../mutations/commitMutation';
+import {GraphQLResponse, Network, PayloadData} from '../network/RelayNetworkTypes';
+import { RelayObservable as Observable } from '../network/RelayObservable';
+import { TaskScheduler } from '../store/OperationExecutor';
+import { GetDataID } from '../store/RelayResponseNormalizer';
+import {
+  ExecuteMutationConfig,
+  LogFunction,
+  MissingFieldHandler,
+  OperationAvailability,
+  OperationDescriptor,
+  OperationLoader,
+  OptimisticResponseConfig,
+  OptimisticUpdateFunction,
+  RelayFieldLogger,
+  SelectorStoreUpdater,
+  SingularReaderSelector,
+  Snapshot,
+  Store,
+  StoreUpdater,
+} from '../store/RelayStoreTypes';
+import {Disposable, RenderPolicy} from '../util/RelayRuntimeTypes';
+import { ActorIdentifier } from './ActorIdentifier';
+import {
+  ActorEnvironment,
+  MultiActorEnvironment as IMultiActorEnvironment,
+  MultiActorStoreUpdater,
+} from './MultiActorEnvironmentTypes';
+
+export type MultiActorEnvironmentConfig = Readonly<{
+    createConfigNameForActor?: ((actorIdentifier: ActorIdentifier) => string) | null;
+    createNetworkForActor: (actorIdentifier: ActorIdentifier) => Network;
+    createStoreForActor?: ((actorIdentifier: ActorIdentifier) => Store) | null;
+    defaultRenderPolicy?: RenderPolicy | null;
+    getDataID?: GetDataID;
+    handlerProvider?: HandlerProvider;
+    isServer?: boolean | null;
+    logFn?: LogFunction | null;
+    missingFieldHandlers?: readonly MissingFieldHandler[] | null;
+    operationLoader?: OperationLoader | null;
+    relayFieldLogger?: RelayFieldLogger | null;
+    scheduler?: TaskScheduler | null;
+    shouldProcessClientComponents?: boolean | null;
+    treatMissingFieldsAsNull?: boolean;
+}>;
+
+export class MultiActorEnvironment implements IMultiActorEnvironment {
+    constructor(config: MultiActorEnvironmentConfig);
+
+    forActor(actorIdentifier: string): ActorEnvironment;
+
+    check(actorEnvironment: ActorEnvironment, operation: OperationDescriptor): OperationAvailability;
+
+    subscribe(
+        actorEnvironment: ActorEnvironment,
+        snapshot: Snapshot,
+        callback: (snapshot: Snapshot) => void,
+    ): Disposable;
+
+    retain(actorEnvironment: ActorEnvironment, operation: OperationDescriptor): Disposable;
+
+    applyUpdate(actorEnvironment: ActorEnvironment, optimisticUpdate: OptimisticUpdateFunction): Disposable;
+
+    revertUpdate(actorEnvironment: ActorEnvironment, update: OptimisticUpdateFunction): void;
+
+    replaceUpdate(
+        actorEnvironment: ActorEnvironment,
+        update: OptimisticUpdateFunction,
+        replacement: OptimisticUpdateFunction,
+    ): void;
+
+    applyMutation(
+        actorEnvironment: ActorEnvironment,
+        optimisticConfig: OptimisticResponseConfig<MutationParameters>,
+    ): Disposable;
+
+    commitUpdate(actorEnvironment: ActorEnvironment, updater: StoreUpdater): void;
+
+    commitMultiActorUpdate(updater: MultiActorStoreUpdater): void;
+
+    commitPayload(
+        actorEnvironment: ActorEnvironment,
+        operationDescriptor: OperationDescriptor,
+        payload: PayloadData,
+    ): void;
+
+    lookup(actorEnvironment: ActorEnvironment, selector: SingularReaderSelector): Snapshot;
+
+    execute(
+        actorEnvironment: ActorEnvironment,
+        config: { operation: OperationDescriptor },
+    ): Observable<GraphQLResponse>;
+
+    executeSubscription(
+        actorEnvironment: ActorEnvironment,
+        config: {
+            operation: OperationDescriptor;
+            updater?: SelectorStoreUpdater<MutationParameters['response']> | null | undefined;
+        },
+    ): Observable<GraphQLResponse>;
+
+    executeMutation(
+        actorEnvironment: ActorEnvironment,
+        config: ExecuteMutationConfig<MutationParameters>,
+    ): Observable<GraphQLResponse>;
+
+    executeWithSource(
+        actorEnvironment: ActorEnvironment,
+        arg: { operation: OperationDescriptor; source: Observable<GraphQLResponse> },
+    ): Observable<GraphQLResponse>;
+
+    isRequestActive(actorEnvironment: ActorEnvironment, requestIdentifier: string): boolean;
+
+    isServer(): boolean;
+}

package/multi-actor-environment/MultiActorEnvironment.js.flow

@@ -75,24 +75,28 @@ export type MultiActorEnvironmentConfig = Readonly<{
 }>;
 
 class MultiActorEnvironment implements IMultiActorEnvironment {
-  +_actorEnvironments: Map<ActorIdentifier, IActorEnvironment>;
-  +_createConfigNameForActor: ?(actorIdentifier: ActorIdentifier) => string;
-  +_createNetworkForActor: (actorIdentifier: ActorIdentifier) => INetwork;
-  +_createStoreForActor: ?(actorIdentifier: ActorIdentifier) => Store;
-  +_defaultRenderPolicy: RenderPolicy;
-  +_getDataID: GetDataID;
-  +_handlerProvider: HandlerProvider;
-  +_isServer: boolean;
-  +_logFn: LogFunction;
-  +_missingFieldHandlers: ReadonlyArray<MissingFieldHandler>;
-  +_normalizeResponse: NormalizeResponseFunction;
-  +_operationExecutions: Map<string, ActiveState>;
-  +_operationLoader: ?OperationLoader;
-  +_relayFieldLogger: RelayFieldLogger;
-  +_scheduler: ?TaskScheduler;
-  +_shouldProcessClientComponents: ?boolean;
-  +_treatMissingFieldsAsNull: boolean;
-  +_deferDeduplicatedFields: boolean;
+  readonly _actorEnvironments: Map<ActorIdentifier, IActorEnvironment>;
+  readonly _createConfigNameForActor: ?(
+    actorIdentifier: ActorIdentifier,
+  ) => string;
+  readonly _createNetworkForActor: (
+    actorIdentifier: ActorIdentifier,
+  ) => INetwork;
+  readonly _createStoreForActor: ?(actorIdentifier: ActorIdentifier) => Store;
+  readonly _defaultRenderPolicy: RenderPolicy;
+  readonly _getDataID: GetDataID;
+  readonly _handlerProvider: HandlerProvider;
+  readonly _isServer: boolean;
+  readonly _logFn: LogFunction;
+  readonly _missingFieldHandlers: ReadonlyArray<MissingFieldHandler>;
+  readonly _normalizeResponse: NormalizeResponseFunction;
+  readonly _operationExecutions: Map<string, ActiveState>;
+  readonly _operationLoader: ?OperationLoader;
+  readonly _relayFieldLogger: RelayFieldLogger;
+  readonly _scheduler: ?TaskScheduler;
+  readonly _shouldProcessClientComponents: ?boolean;
+  readonly _treatMissingFieldsAsNull: boolean;
+  readonly _deferDeduplicatedFields: boolean;
 
   constructor(config: MultiActorEnvironmentConfig) {
     this._actorEnvironments = new Map();

package/multi-actor-environment/MultiActorEnvironmentTypes.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 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, PayloadData} from '../network/RelayNetworkTypes';
+import { RelayObservable } from '../network/RelayObservable';
+import {
+  Environment as IEnvironment,
+  ExecuteMutationConfig,
+  OperationAvailability,
+  OperationDescriptor,
+  OptimisticResponseConfig,
+  OptimisticUpdateFunction,
+  RecordSourceProxy,
+  SelectorStoreUpdater,
+  SingularReaderSelector,
+  Snapshot,
+  StoreUpdater,
+} from '../store/RelayStoreTypes';
+import { Disposable } from '../util/RelayRuntimeTypes';
+import { ActorIdentifier } from './ActorIdentifier';
+
+export type MultiActorStoreUpdater = (
+    actorIdentifier: ActorIdentifier,
+    environment: ActorEnvironment,
+    store: RecordSourceProxy,
+) => void;
+
+export interface ActorEnvironment extends IEnvironment {
+    /**
+     * Reference to the main MultActorEnvironment that handles
+     * the network execution/and responsible for network integration
+     */
+    readonly multActorEnvironment: MultiActorEnvironment;
+
+    /**
+     * Identifier of the actor for the current active environment
+     */
+    readonly actorIdentifier: ActorIdentifier;
+
+    /**
+     * Optional. A human-readable identifier of the environment.
+     * This value should be visible in the dev tools.
+     */
+    readonly configName: string | null;
+}
+
+/**
+ * Interface for the main (or parent) multi-actor environment that contains
+ * the map of individual actor-specific sub-environments. These sub-environments
+ * implement the Relay IEnvironment interface.
+ */
+export interface MultiActorEnvironment {
+    /**
+     * A factory of actor-specific environments.
+     */
+    forActor(actorIdentifier: ActorIdentifier): ActorEnvironment;
+
+    /**
+     * 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(actorEnvironment: ActorEnvironment, operation: OperationDescriptor): 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(
+        actorEnvironment: ActorEnvironment,
+        snapshot: Snapshot,
+        callback: (snapshot: Snapshot) => void,
+    ): Disposable;
+
+    /**
+     * 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(actorEnvironment: ActorEnvironment, operation: OperationDescriptor): Disposable;
+
+    /**
+     * Apply an optimistic update to the environment. The mutation can be reverted
+     * by calling `dispose()` on the returned value.
+     */
+    applyUpdate(actorEnvironment: ActorEnvironment, optimisticUpdate: OptimisticUpdateFunction): Disposable;
+
+    /**
+     * Revert updates for the `update` function.
+     */
+    revertUpdate(actorEnvironment: ActorEnvironment, update: OptimisticUpdateFunction): void;
+
+    /**
+     * Revert updates for the `update` function, and apply the `replacement` update.
+     */
+    replaceUpdate(
+        actorEnvironment: ActorEnvironment,
+        update: OptimisticUpdateFunction,
+        replacement: OptimisticUpdateFunction,
+    ): void;
+
+    /**
+     * Apply an optimistic mutation response and/or updater. The mutation can be
+     * reverted by calling `dispose()` on the returned value.
+     */
+    applyMutation(
+        actorEnvironment: ActorEnvironment,
+        optimisticConfig: OptimisticResponseConfig<MutationParameters>,
+    ): 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(actorEnvironment: ActorEnvironment, updater: StoreUpdater): void;
+
+    /**
+     * Commit store updates for each actor-specific environment known to MultActorEnvironment
+     */
+    commitMultiActorUpdate(updater: MultiActorStoreUpdater): void;
+
+    /**
+     * Commit a payload to the environment using the given operation selector.
+     */
+    commitPayload(
+        actorEnvironment: ActorEnvironment,
+        operationDescriptor: OperationDescriptor,
+        payload: PayloadData,
+    ): void;
+
+    /**
+     * Read the results of a selector from in-memory records in the store.
+     */
+    lookup(actorEnvironment: ActorEnvironment, 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`).
+     *
+     * Note: Observables are lazy, so calling this method will do nothing until
+     * the result is subscribed to: environment.execute({...}).subscribe({...}).
+     */
+    execute(
+        actorEnvironment: ActorEnvironment,
+        config: {
+            operation: OperationDescriptor;
+        },
+    ): RelayObservable<GraphQLResponse>;
+
+    /**
+     * Send a subscription 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.executeSubscription({...}).subscribe({...}).
+     */
+    executeSubscription(
+        actorEnvironment: ActorEnvironment,
+        config: {
+            operation: OperationDescriptor;
+            updater?: SelectorStoreUpdater<MutationParameters['response']> | null;
+        },
+    ): 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(
+        actorEnvironment: ActorEnvironment,
+        config: ExecuteMutationConfig<MutationParameters>,
+    ): 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(
+        actorEnvironment: ActorEnvironment,
+        arg: {
+            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(actorEnvironment: ActorEnvironment, requestIdentifier: string): boolean;
+
+    /**
+     * Returns `true` if execute in the server environment
+     */
+    isServer(): boolean;
+}

package/multi-actor-environment/MultiActorEnvironmentTypes.js.flow

@@ -46,12 +46,12 @@ export interface IActorEnvironment extends IEnvironment {
    * Reference to the main MultiActorEnvironment that handles
    * the network execution/and responsible for network integration
    */
-  +multiActorEnvironment: IMultiActorEnvironment;
+  readonly multiActorEnvironment: IMultiActorEnvironment;
 
   /**
    * Identifier of the actor for the current active environment
    */
-  +actorIdentifier: ActorIdentifier;
+  readonly actorIdentifier: ActorIdentifier;
 
   /**
    * TODO: this needs to move the the MultiActorEnvironment with different API.
@@ -62,7 +62,7 @@ export interface IActorEnvironment extends IEnvironment {
    * Optional. A human-readable identifier of the environment.
    * This value should be visible in the dev tools.
    */
-  +configName: ?string;
+  readonly configName: ?string;
 }
 
 /**

package/multi-actor-environment/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+export { ActorIdentifier, getActorIdentifier } from './ActorIdentifier';
+
+export { MultiActorEnvironment } from './MultiActorEnvironment';
+export {
+    ActorEnvironment as IActorEnvironment,
+    MultiActorEnvironment as IMultiActorEnvironment,
+} from './MultiActorEnvironmentTypes';

package/multi-actor-environment.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export * from './multi-actor-environment';

package/mutations/RelayDeclarativeMutationConfig.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { SelectorStoreUpdater } from '../store/RelayStoreTypes';
+import { ConcreteRequest } from '../util/RelayConcreteNode';
+import { Variables } from '../util/RelayRuntimeTypes';
+
+export type MutationTypes = 'RANGE_ADD' | 'RANGE_DELETE' | 'NODE_DELETE';
+
+export type RangeOperations = 'append' | 'prepend';
+export type RangeBehaviorsFunction = (connectionArgs: { [name: string]: unknown }) => RangeOperations;
+export interface RangeBehaviorsObject {
+    [key: string]: RangeOperations;
+}
+export type RangeBehaviors = RangeBehaviorsFunction | RangeBehaviorsObject;
+
+export interface RangeAddConfig {
+    type: 'RANGE_ADD';
+    parentName?: string | undefined;
+    parentID?: string | undefined;
+    connectionInfo?:
+        | ReadonlyArray<{
+            key: string;
+            filters?: Variables | undefined;
+            rangeBehavior: string;
+        }>
+        | undefined;
+    connectionName?: string | undefined;
+    edgeName: string;
+    rangeBehaviors?: RangeBehaviors | undefined;
+}
+
+export interface RangeDeleteConfig {
+    type: 'RANGE_DELETE';
+    parentName?: string | undefined;
+    parentID?: string | undefined;
+    connectionKeys?:
+        | ReadonlyArray<{
+            key: string;
+            filters?: Variables | undefined;
+        }>
+        | undefined;
+    connectionName?: string | undefined;
+    deletedIDFieldName: string | readonly string[];
+    pathToConnection: readonly string[];
+}
+
+export interface NodeDeleteConfig {
+    type: 'NODE_DELETE';
+    parentName?: string | undefined;
+    parentID?: string | undefined;
+    connectionName?: string | undefined;
+    deletedIDFieldName: string;
+}
+
+export type DeclarativeMutationConfig = RangeAddConfig | RangeDeleteConfig | NodeDeleteConfig;
+
+export function convert(
+    configs: DeclarativeMutationConfig[],
+    request: ConcreteRequest,
+    optimisticUpdater?: SelectorStoreUpdater,
+    updater?: SelectorStoreUpdater,
+): {
+    optimisticUpdater: SelectorStoreUpdater;
+    updater: SelectorStoreUpdater;
+};

package/mutations/applyOptimisticMutation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 { GraphQLTaggedNode } from '../query/GraphQLTag';
+import {Environment, SelectorStoreUpdater} from '../store/RelayStoreTypes';
+import {Disposable, Variables} from '../util/RelayRuntimeTypes';
+import { DeclarativeMutationConfig } from './RelayDeclarativeMutationConfig';
+
+export interface OptimisticMutationConfig {
+    configs?: readonly DeclarativeMutationConfig[] | null | undefined;
+    mutation: GraphQLTaggedNode;
+    variables: Variables;
+    optimisticUpdater?: SelectorStoreUpdater | null | undefined;
+    optimisticResponse?: object | undefined;
+}
+
+/**
+ * Higher-level helper function to execute a mutation against a specific
+ * environment.
+ */
+export function applyOptimisticMutation(environment: Environment, config: OptimisticMutationConfig): Disposable;

package/mutations/commitLocalUpdate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 {Environment, SelectorStoreUpdater} from '../store/RelayStoreTypes';
+
+export function commitLocalUpdate(environment: Environment, updater: SelectorStoreUpdater): void;

package/mutations/commitMutation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 {PayloadError, UploadableMap} from '../network/RelayNetworkTypes';
+import { GraphQLTaggedNode } from '../query/GraphQLTag';
+import {Environment, SelectorStoreUpdater} from '../store/RelayStoreTypes';
+import {CacheConfig, Disposable} from '../util/RelayRuntimeTypes';
+import { DeclarativeMutationConfig } from './RelayDeclarativeMutationConfig';
+
+export interface MutationParameters {
+    readonly response: Record<string, unknown>;
+    readonly variables: Record<string, unknown>;
+    readonly rawResponse?: Record<string, unknown> | undefined;
+}
+
+export interface MutationConfig<TOperation extends MutationParameters> {
+    configs?: DeclarativeMutationConfig[] | undefined;
+    cacheConfig?: CacheConfig | undefined;
+    mutation: GraphQLTaggedNode;
+    onError?: ((error: Error) => void) | null | undefined;
+    onCompleted?:
+        | ((response: TOperation['response'], errors: readonly PayloadError[] | null | undefined) => void)
+        | null
+        | undefined;
+    onUnsubscribe?: (() => void | null | undefined) | undefined;
+    /**
+     * An object whose type matches the raw response type of the mutation. Make sure you decorate
+     * your mutation with `@raw_response_type` if you are using this field.
+     */
+    optimisticResponse?: (TOperation['rawResponse'] extends Record<string, unknown> ? TOperation['rawResponse'] : never) | undefined;
+    optimisticUpdater?: SelectorStoreUpdater<TOperation['response']> | null | undefined;
+    updater?: SelectorStoreUpdater<TOperation['response']> | null | undefined;
+    uploadables?: UploadableMap | null | undefined;
+    variables: TOperation['variables'];
+}
+
+/**
+ * Higher-level helper function to execute a mutation against a specific
+ * environment.
+ */
+export function commitMutation<TOperation extends MutationParameters = MutationParameters>(
+    environment: Environment,
+    config: MutationConfig<TOperation>,
+): Disposable;

package/mutations/commitMutation.js.flow

@@ -49,7 +49,7 @@ export type MutationConfig<TMutation extends MutationParameters> = Readonly<{
   onNext?: ?() => void,
   onUnsubscribe?: ?() => void,
   optimisticResponse?: {
-    +rawResponse?: {...},
+    readonly rawResponse?: {...},
     ...TMutation,
     ...
   }['rawResponse'],

package/network/RelayNetwork.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 {FetchFunction, Network, SubscribeFunction} from './RelayNetworkTypes';
+
+export const RelayNetwork: {
+    create(fetchFn: FetchFunction, subscribeFn?: SubscribeFunction): Network;
+};