recoil/cjs/hooks/Recoil_Hooks.js.flow

Recoil - A state management library for React

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 *
 * @emails oncall+recoil
 * @flow strict-local
 * @format
 */
'use strict';

import type { Loadable } from '../adt/Recoil_Loadable';
import type { DefaultValue } from '../core/Recoil_Node';
import type { PersistenceType } from '../core/Recoil_Node';
import type { RecoilState, RecoilValue } from '../core/Recoil_RecoilValue';
import type { ComponentSubscription } from '../core/Recoil_RecoilValueInterface';
import type { NodeKey, Store, TreeState } from '../core/Recoil_State';

const {
  useCallback,
  useEffect,
  useMemo,
  useRef,
  useState
} = require('React');

const {
  batchUpdates
} = require('../core/Recoil_Batching');

const {
  DEFAULT_VALUE,
  getNode,
  nodes
} = require('../core/Recoil_Node');

const {
  useRecoilMutableSource,
  useStoreRef
} = require('../core/Recoil_RecoilRoot.react');

const {
  isRecoilValue
} = require('../core/Recoil_RecoilValue');

const {
  AbstractRecoilValue,
  getRecoilValueAsLoadable,
  setRecoilValue,
  setRecoilValueLoadable,
  setUnvalidatedRecoilValue,
  subscribeToRecoilValue
} = require('../core/Recoil_RecoilValueInterface');

const {
  Snapshot,
  cloneSnapshot
} = require('../core/Recoil_Snapshot');

const {
  setByAddingToSet
} = require('../util/Recoil_CopyOnWrite');

const differenceSets = require('../util/Recoil_differenceSets');

const expectationViolation = require('../util/Recoil_expectationViolation');

const filterMap = require('../util/Recoil_filterMap');

const filterSet = require('../util/Recoil_filterSet');

const invariant = require('../util/Recoil_invariant');

const mapMap = require('../util/Recoil_mapMap');

const mergeMaps = require('../util/Recoil_mergeMaps');

const {
  mutableSourceExists,
  useMutableSource
} = require('../util/Recoil_mutableSource');

const nullthrows = require('../util/Recoil_nullthrows');

const recoverableViolation = require('../util/Recoil_recoverableViolation');

const Tracing = require('../util/Recoil_Tracing');

const useComponentName = require('../util/Recoil_useComponentName');

declare function handleLoadable<T>(loadable: Loadable<T>, atom: any, storeRef: any): T;
declare function validateRecoilValue(recoilValue: any, hookName: any): any;
export type SetterOrUpdater<T> = (((T) => T) | T) => void;
export type Resetter = () => void;
export type RecoilInterface = {
  getRecoilValue: <T>(RecoilValue<T>) => T,
  getRecoilValueLoadable: <T>(RecoilValue<T>) => Loadable<T>,
  getRecoilState: <T>(RecoilState<T>) => [T, SetterOrUpdater<T>],
  getRecoilStateLoadable<T>(RecoilState<T>): [Loadable<T>, SetterOrUpdater<T>],
  getSetRecoilState: <T>(RecoilState<T>) => SetterOrUpdater<T>,
  getResetRecoilState: <T>(RecoilState<T>) => Resetter,
};
declare function useRecoilInterface_DEPRECATED(): RecoilInterface;
const recoilComponentGetRecoilValueCount_FOR_TESTING = {
  current: 0
};
declare function useRecoilValueLoadable_MUTABLESOURCE<T>(recoilValue: RecoilValue<T>): Loadable<T>;
declare function useRecoilValueLoadable_LEGACY<T>(recoilValue: RecoilValue<T>): Loadable<T>;
/**
  Like useRecoilValue(), but either returns the value if available or
  just undefined if not available for any reason, such as pending or error.
*/

declare function useRecoilValueLoadable<T>(recoilValue: RecoilValue<T>): Loadable<T>;
/**
  Returns the value represented by the RecoilValue.
  If the value is pending, it will throw a Promise to suspend the component,
  if the value is an error it will throw it for the nearest React error boundary.
  This will also subscribe the component for any updates in the value.
  */

declare function useRecoilValue<T>(recoilValue: RecoilValue<T>): T;
/**
  Returns a function that allows the value of a RecoilState to be updated, but does
  not subscribe the component to changes to that RecoilState.
*/

declare function useSetRecoilState<T>(recoilState: RecoilState<T>): SetterOrUpdater<T>;
/**
  Returns a function that will reset the value of a RecoilState to its default
*/

declare function useResetRecoilState<T>(recoilState: RecoilState<T>): Resetter;
/**
  Equivalent to useState(). Allows the value of the RecoilState to be read and written.
  Subsequent updates to the RecoilState will cause the component to re-render. If the
  RecoilState is pending, this will suspend the component and initiate the
  retrieval of the value. If evaluating the RecoilState resulted in an error, this will
  throw the error so that the nearest React error boundary can catch it.
*/

declare function useRecoilState<T>(recoilState: RecoilState<T>): [T, SetterOrUpdater<T>];
/**
  Like useRecoilState(), but does not cause Suspense or React error handling. Returns
  an object that indicates whether the RecoilState is available, pending, or
  unavailable due to an error.
*/

declare function useRecoilStateLoadable<T>(recoilState: RecoilState<T>): [Loadable<T>, SetterOrUpdater<T>];
declare function useTransactionSubscription(callback: (Store) => void): any;
declare function externallyVisibleAtomValuesInState(state: TreeState): Map<NodeKey, mixed>;
type ExternallyVisibleAtomInfo = {
  persistence_UNSTABLE: {
    type: PersistenceType,
    backButton: boolean,
    ...
  },
  ...
};
/**
  Calls the given callback after any atoms have been modified and the consequent
  component re-renders have been committed. This is intended for persisting
  the values of the atoms to storage. The stored values can then be restored
  using the useSetUnvalidatedAtomValues hook.

  The callback receives the following info:

  atomValues: The current value of every atom that is both persistable (persistence
              type not set to 'none') and whose value is available (not in an
              error or loading state).

  previousAtomValues: The value of every persistable and available atom before
               the transaction began.

  atomInfo: A map containing the persistence settings for each atom. Every key
            that exists in atomValues will also exist in atomInfo.

  modifiedAtoms: The set of atoms that were written to during the transaction.

  transactionMetadata: Arbitrary information that was added via the
          useSetUnvalidatedAtomValues hook. Useful for ignoring the useSetUnvalidatedAtomValues
          transaction, to avoid loops.
*/

declare function useTransactionObservation_DEPRECATED(callback: ({
  atomValues: Map<NodeKey, mixed>,
  previousAtomValues: Map<NodeKey, mixed>,
  atomInfo: Map<NodeKey, ExternallyVisibleAtomInfo>,
  modifiedAtoms: Set<NodeKey>,
  transactionMetadata: {
    [NodeKey]: mixed,
    ...
  },
}) => void): any;
declare function useRecoilTransactionObserver(callback: ({
  snapshot: Snapshot,
  previousSnapshot: Snapshot,
}) => void): any; // Return a snapshot of the current state and subscribe to all state changes

declare function useRecoilSnapshot(): Snapshot;
declare function useGotoRecoilSnapshot(): (Snapshot) => void;
declare function useSetUnvalidatedAtomValues(): (values: Map<NodeKey, mixed>, transactionMetadata?: {...}) => void;
type CallbackInterface = $ReadOnly<{
  set: <T>(RecoilState<T>, ((T) => T) | T) => void,
  reset: <T>(RecoilState<T>) => void,
  snapshot: Snapshot,
  gotoSnapshot: (Snapshot) => void,
}>;
declare class Sentinel {}
const SENTINEL = new Sentinel();
declare function useRecoilCallback<Args: $ReadOnlyArray<mixed>, Return>(fn: (CallbackInterface) => (...Args) => Return, deps?: $ReadOnlyArray<mixed>): (...Args) => Return;
module.exports = {
  recoilComponentGetRecoilValueCount_FOR_TESTING,
  useGotoRecoilSnapshot,
  useRecoilCallback,
  useRecoilInterface: useRecoilInterface_DEPRECATED,
  useRecoilSnapshot,
  useRecoilState,
  useRecoilStateLoadable,
  useRecoilTransactionObserver,
  useRecoilValue,
  useRecoilValueLoadable,
  useResetRecoilState,
  useSetRecoilState,
  useSetUnvalidatedAtomValues,
  useTransactionObservation_DEPRECATED,
  useTransactionSubscription_DEPRECATED: useTransactionSubscription
};