recoil/cjs/recoil_values/Recoil_atomFamily.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'; // @fb-only: import type {ScopeRules} from 'Recoil_ScopedAtom';

import type { CachePolicyWithoutEviction } from '../caches/Recoil_CachePolicy';
import type { RecoilState, RecoilValue } from '../core/Recoil_RecoilValue';
import type { RetainedBy } from '../core/Recoil_RetainedBy';
import type { AtomEffect, AtomOptions } from './Recoil_atom';

const cacheFromPolicy = require('../caches/Recoil_cacheFromPolicy');

const {
  setConfigDeletionHandler
} = require('../core/Recoil_Node');

const stableStringify = require('../util/Recoil_stableStringify');

const atom = require('./Recoil_atom');

type Primitive = void | null | boolean | number | string;
interface HasToJSON {
  toJSON: () => string
}
export type Parameter = Primitive | HasToJSON | $ReadOnlyArray<Parameter> | $ReadOnly<{
  [string]: Parameter
}>; // flowlint unclear-type:off

export type ParameterizedScopeRules<P> = $ReadOnlyArray<RecoilValue<$ReadOnlyArray<any>> | $ReadOnlyArray<RecoilValue<any> | ((P) => RecoilValue<any>)>>; // flowlint unclear-type:error

export type AtomFamilyOptions<T, P: Parameter> = $ReadOnly<{ ...AtomOptions<T>,
  default: RecoilValue<T> | Promise<T> | T | ((P) => T | RecoilValue<T> | Promise<T>),
  effects_UNSTABLE?: $ReadOnlyArray<AtomEffect<T>> | ((P) => $ReadOnlyArray<AtomEffect<T>>),
  retainedBy_UNSTABLE?: RetainedBy | ((P) => RetainedBy),
  cachePolicyForParams_UNSTABLE?: CachePolicyWithoutEviction,
}>; // Process scopeRules to handle any entries which are functions taking parameters
// prettier-ignore
// @fb-only: function mapScopeRules<P>(
// @fb-only: scopeRules?: ParameterizedScopeRules<P>,
// @fb-only: param: P,
// @fb-only: ): ScopeRules | void {
// @fb-only: return scopeRules?.map(rule =>
// @fb-only: Array.isArray(rule)
// @fb-only: ? rule.map(entry => (typeof entry === 'function' ? entry(param) : entry))
// @fb-only: : rule,
// @fb-only: );
// @fb-only: }

/*
A function which returns an atom based on the input parameter.

Each unique parameter returns a unique atom. E.g.,

  const f = atomFamily(...);
  f({a: 1}) => an atom
  f({a: 2}) => a different atom

This allows components to persist local, private state using atoms.  Each
instance of the component may have a different key, which it uses as the
parameter for a family of atoms; in this way, each component will have
its own atom not shared by other instances.  These state keys may be composed
into children's state keys as well.
*/

declare function atomFamily<T, P: Parameter>(options: AtomFamilyOptions<T, P>): (P) => RecoilState<T>;
module.exports = atomFamily;