babel/packages/babel-core/src/config/caching.js

// @flow

type CacheConfigurator = CacheConfiguratorFn & CacheConfiguratorObj;

type CacheConfiguratorFn = {
  (boolean): void,
  <T>(handler: () => T): T,
};
type CacheConfiguratorObj = {
  forever: () => void,
  never: () => void,
  using: <T>(handler: () => T) => T,
  invalidate: <T>(handler: () => T) => T,
};

type CacheEntry<ResultT> = Array<[ ResultT, () => boolean ]>;

/**
 * Given a function with a single argument, cache its results based on its argument and how it
 * configures its caching behavior. Cached values are stored strongly.
 */
export function makeStrongCache<ArgT, ResultT>(
  handler: (ArgT, CacheConfigurator) => ResultT,
  autoPermacache?: boolean,
): (ArgT) => ResultT {
  return makeCachedFunction(new Map(), handler, autoPermacache);
}

/**
 * Given a function with a single argument, cache its results based on its argument and how it
 * configures its caching behavior. Cached values are stored weakly and the function argument must be
 * an object type.
 */
export function makeWeakCache<ArgT: Object, ResultT>(
  handler: (ArgT, CacheConfigurator) => ResultT,
  autoPermacache?: boolean,
): (ArgT) => ResultT {
  return makeCachedFunction(new WeakMap(), handler, autoPermacache);
}

type CacheMap<ArgT, ResultT> = Map<ArgT, CacheEntry<ResultT>>|WeakMap<ArgT, CacheEntry<ResultT>>;

function makeCachedFunction<ArgT, ResultT, Cache: CacheMap<ArgT, ResultT>>(
  callCache: Cache,
  handler: (ArgT, CacheConfigurator) => ResultT,
  autoPermacache: boolean = true,
): (ArgT) => ResultT {
  return function cachedFunction(arg) {
    let cachedValue: CacheEntry<ResultT>|void = callCache.get(arg);

    if (cachedValue) {
      for (const [ value, valid ] of cachedValue) {
        if (valid()) return value;
      }
    }

    const { cache, result, deactivate } = makeCacheConfig();

    const value = handler(arg, cache);

    if (autoPermacache && !result.configured) cache.forever();

    deactivate();

    if (!result.configured) {
      // eslint-disable-next-line max-len
      throw new Error([
        "Caching was left unconfigured. Babel's plugins, presets, and .babelrc.js files can be configured",
        "for various types of caching, using the first param of their handler functions:",
        "",
        "module.exports = function(api) {",
        "  // The API exposes the following:",
        "",
        "  // Cache the returned value forever and don't call this function again.",
        "  api.cache(true);",
        "",
        "  // Don't cache at all. Not recommended because it will be very slow.",
        "  api.cache(false);",
        "",
        "  // Cached based on the value of some function. If this function returns a value different from",
        "  // a previously-encountered value, the plugins will re-evaluate.",
        "  var env = api.cache(() => process.env.NODE_ENV);",
        "",
        "  // If testing for a specific env, we recommend specifics to avoid instantiating a plugin for",
        "  // any possible NODE_ENV value that might come up during plugin execution.",
        "  var isProd = api.cache(() => process.env.NODE_ENV === \"production\");",
        "",
        "  // .cache(fn) will perform a linear search though instances to find the matching plugin based",
        "  // based on previous instantiated plugins. If you want to recreate the plugin and discard the",
        "  // previous instance whenever something changes, you may use:",
        "  var isProd = api.cache.invalidate(() => process.env.NODE_ENV === \"production\");",
        "",
        "  // Note, we also expose the following more-verbose versions of the above examples:",
        "  api.cache.forever(); // api.cache(true)",
        "  api.cache.never();   // api.cache(false)",
        "  api.cache.using(fn); // api.cache(fn)",
        "",
        "  // Return the value that will be cached.",
        "  return { };",
        "};",
      ].join("\n"));
    }

    if (!result.never) {
      if (result.forever) {
        cachedValue = [
          [value, () => true],
        ];
      } else if (result.invalidate) {
        cachedValue = [
          [value, result.valid],
        ];
      } else {
        cachedValue = cachedValue || [];
        cachedValue.push([ value, result.valid ]);
      }
      callCache.set(arg, cachedValue);
    }

    return value;
  };
}

function makeCacheConfig(): { cache: CacheConfigurator, result: *, deactivate: () => void } {
  const pairs = [];

  const result = {
    configured: false,
    never: false,
    forever: false,
    invalidate: false,
    valid: () => pairs.every(([key, fn]) => key === fn()),
  };

  let active = true;
  const deactivate = () => {
    active = false;
  };

  const cache: CacheConfigurator = Object.assign((function cacheFn(val) {
    if (typeof val === "boolean") {
      if (val) cache.forever();
      else cache.never();
      return;
    }

    return cache.using(val);
  }: any), ({
    forever() {
      if (!active) throw new Error("Cannot change caching after evaluation has completed.");
      if (result.never) throw new Error("Caching has already been configured with .never()");
      result.forever = true;
      result.configured = true;
    },
    never() {
      if (!active) throw new Error("Cannot change caching after evaluation has completed.");
      if (result.forever) throw new Error("Caching has already been configured with .forever()");
      result.never = true;
      result.configured = true;
    },
    using<T>(handler: () => T): T {
      if (!active) throw new Error("Cannot change caching after evaluation has completed.");
      if (result.never || result.forever) {
        throw new Error("Caching has already been configured with .never or .forever()");
      }
      result.configured = true;

      const key = handler();
      pairs.push([ key, handler ]);
      return key;
    },
    invalidate<T>(handler: () => T): T {
      if (!active) throw new Error("Cannot change caching after evaluation has completed.");
      if (result.never || result.forever) {
        throw new Error("Caching has already been configured with .never or .forever()");
      }
      result.invalidate = true;
      result.configured = true;

      const key = handler();
      pairs.push([ key, handler ]);
      return key;
    },
  }: CacheConfiguratorObj));

  return { cache, result, deactivate };
}