recoil/cjs/caches/Recoil_TreeCacheImplementationType.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
 * @format
 */
'use strict';

import type { NodeKey } from '../core/Recoil_Keys';
export type NodeCacheRoute = Array<[NodeKey, mixed]>;
export type TreeCacheNode<T> = TreeCacheLeaf<T> | TreeCacheBranch<T>;
export type TreeCacheLeaf<T> = {
  type: 'leaf',
  value: T,
  branchKey?: ?mixed,
  parent: ?TreeCacheBranch<T>,
};
export type TreeCacheBranch<T> = {
  type: 'branch',
  nodeKey: NodeKey,
  branches: Map<mixed, TreeCacheNode<T>>,
  branchKey?: ?mixed,
  parent: ?TreeCacheBranch<T>,
};
export type NodeValueGet = (nodeKey: NodeKey) => mixed;
type NodeVisitHandler<T> = (node: TreeCacheNode<T>) => void;
export type GetHandlers<T> = {
  onNodeVisit: NodeVisitHandler<T>
};
export type SetHandlers<T> = {
  onNodeVisit: NodeVisitHandler<T>
};
/**
 * This is an opinionated tree cache that conforms to the requirements needed
 * by Recoil selectors.
 *
 * Unlike a conventional cache, the tree cache does not store key-value pairs,
 * but "routes" that point to values. In the context of selectors these routes
 * represent dependencies that a selector has to other atoms and selectors.
 *
 * In order to retrieve a value from the cache, a function is passed to the
 * cache's `get()` method, and the tree cache will use that function to traverse
 * itself, passing the provided function a "key" (the first part of the route tuple),
 * reconstructing the route to some value (or undefined).
 *
 * The handlers are necessary for the selector to be able to capture the
 * incremental nodes in the tree that are traversed while looking for a cache
 * hit as these incremental nodes represent dependencies to the selector, which
 * are used internally by the selector.
 */

export interface TreeCacheImplementation<T> {
  +get: (NodeValueGet, handlers?: GetHandlers<T>) => ?T,
  +set: (NodeCacheRoute, T, handlers?: SetHandlers<T>) => void,
  +delete: (TreeCacheNode<T>) => boolean,
  +clear: () => void,
  +root: () => ?TreeCacheNode<T>,
  +size: () => number,
}