@dr.pogodin/react-utils 1.25.5 → 1.26.0

package/src/shared/components/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Just an aggregation of all exported components into a single module.
+ */
+
+export { default as Button } from 'components/Button';
+export { default as Checkbox } from 'components/Checkbox';
+export { default as Dropdown } from 'components/Dropdown';
+export { default as Input } from 'components/Input';
+export { default as Link } from 'components/Link';
+export { default as PageLayout } from 'components/PageLayout';
+export { default as MetaTags } from 'components/MetaTags';
+export { default as Modal, BaseModal } from 'components/Modal';
+export { default as NavLink } from 'components/NavLink';
+export { default as ScalableRect } from 'components/ScalableRect';
+export { default as Throbber } from 'components/Throbber';
+export { default as WithTooltip } from 'components/WithTooltip';
+export { default as YouTubeVideo } from 'components/YouTubeVideo';

package/src/shared/utils/config.ts

@@ -0,0 +1,21 @@
+/* global document */
+
+import { IS_CLIENT_SIDE } from './isomorphy/environment-check';
+import { requireWeak } from './webpack';
+
+const config = (
+  IS_CLIENT_SIDE
+    // eslint-disable-next-line global-require
+    ? require('client/getInj').default().CONFIG
+    : requireWeak('config')
+) || {};
+
+// The safeguard for "document" is necessary because in non-Node environments,
+// like React Native, IS_CLIENT_SIDE is "true", however "document" and a bunch
+// of other browser-world features are not available.
+if (IS_CLIENT_SIDE && typeof document !== 'undefined') {
+  const cookie = require('cookie'); // eslint-disable-line global-require
+  config.CSRF = cookie.parse(document.cookie).csrfToken;
+}
+
+export default config;

package/src/shared/utils/globalState.ts

@@ -0,0 +1,29 @@
+import type { Request } from 'express';
+
+import RGS, { type API, type SsrContext } from '@dr.pogodin/react-global-state';
+
+export type ChunkGroupsT = {
+  [chunkName: string]: string[];
+};
+
+// The type of data object injected by server into generated markup.
+export type InjT = {
+  CHUNK_GROUPS?: ChunkGroupsT;
+  CONFIG?: { [key: string]: any },
+  ISTATE?: unknown;
+};
+
+export interface SsrContextT<StateT> extends SsrContext<StateT> {
+  chunkGroups: ChunkGroupsT;
+  chunks: string[];
+  req: Request,
+  status: number;
+}
+
+const {
+  getSsrContext,
+} = (RGS as unknown) as API<unknown, SsrContextT<unknown>>;
+
+export {
+  getSsrContext,
+};

package/src/shared/utils/index.ts

@@ -0,0 +1,105 @@
+import themedImpl, {
+  type Theme,
+  COMPOSE,
+  PRIORITY,
+  ThemeProvider,
+} from '@dr.pogodin/react-themes';
+
+import config from './config';
+import * as isomorphy from './isomorphy';
+import time from './time';
+import * as webpack from './webpack';
+
+import type * as JuT from './jest';
+
+export { Barrier, Emitter, Semaphore } from '@dr.pogodin/js-utils';
+
+export { getSsrContext } from './globalState';
+export { default as splitComponent } from './splitComponent';
+
+type ThemedT = typeof themedImpl & {
+  COMPOSE: typeof COMPOSE;
+  PRIORITY: typeof PRIORITY;
+};
+
+const themed: ThemedT = themedImpl as ThemedT;
+
+themed.COMPOSE = COMPOSE;
+themed.PRIORITY = PRIORITY;
+
+// Note: it should be done this way, as in some environments
+// "process" might not exist, and process.env.NODE_CONFIG_ENV
+// not injected by Webpack.
+let NODE_CONFIG_ENV;
+try {
+  NODE_CONFIG_ENV = process.env.NODE_CONFIG_ENV;
+} catch { /* noop */ }
+
+const env = NODE_CONFIG_ENV || process.env.NODE_ENV;
+
+const JU: typeof JuT | null = env !== 'production'
+  ? webpack.requireWeak('./jest', __dirname) as typeof JuT | null
+  : null;
+
+/**
+ * @category Utilities
+ * @global
+ * @func withRetries
+ * @desc
+ * ```js
+ * import { withRetries } from '@dr.pogodin/react-utils';
+ * ```
+ * Attempts to perform given asynchronous `action` up to `maxRetries` times,
+ * with the given `interval` between attempts. If any attempt is successful,
+ * the result is returned immediately, with no further attempts done;
+ * otherwise, if all attempts fail, the result Promise rejects after the last
+ * attempt.
+ * @param {function} action
+ * @param {number} [maxRetries=5] Optional. Maximum number of retries. Defaults
+ *  to 5 attempts.
+ * @param {number} [interval=1000] Optional. Interval between retries [ms].
+ *  Defaults to 1 second.
+ * @return {Promise} Resolves to the result of successful operation, or
+ *  rejects with the error from the latst failed attempt.
+ * @example
+ * import { withRetries } from '@dr.pogodin/react-utils';
+ *
+ * let firstCall = true;
+ *
+ * function sampleAction() {
+ *   if (!firstCall) return 'success';
+ *   firstCall = false;
+ *   throw Error('The first call to this method fails');
+ * }
+ *
+ * withRetries(sampleAction).then(console.log);
+ * // It will print 'success' after one second, once the second attempt
+ * // is performed.
+ */
+export async function withRetries(
+  action: () => Promise<unknown>,
+  maxRetries = 5,
+  interval = 1000,
+) {
+  /* eslint-disable no-await-in-loop */
+  for (let n = 1; ; ++n) {
+    try {
+      return await action();
+    } catch (error) {
+      if (n < maxRetries) await time.timer(interval);
+      else throw error;
+    }
+  }
+  /* eslint-enable no-await-in-loop */
+}
+
+export {
+  type Theme,
+  config,
+  isomorphy,
+  JU,
+  themed,
+  ThemeProvider,
+  time,
+  webpack,
+};

package/src/shared/utils/isomorphy/buildInfo.ts

@@ -0,0 +1,54 @@
+// Encapsulates access to "Build Info" data.
+
+/* global BUILD_INFO */
+
+// BEWARE: This should match the type of build info object generated by
+// Webpack build (see "/config/webpack/app-base.js"), and currently this
+// match is not checked automatically.
+export type BuildInfoT = {
+  key: string;
+  publicPath: string;
+  timestamp: string;
+  useServiceWorker: boolean;
+};
+
+declare global {
+  // Depending on the build mode & environment, BUILD_INFO is either a global
+  // variable defined at the app launch, or it is replaced by the actual value
+  // by the Webpack build.
+  const BUILD_INFO: BuildInfoT | undefined;
+}
+
+let buildInfo: BuildInfoT | undefined;
+
+// On the client side "BUILD_INFO" should be injected by Webpack. Note, however,
+// that in test environment we may need situations were environment is mocked as
+// client-side, although no proper Webpack compilation is executed, thus no info
+// injected; because of this we don't do a hard environment check here.
+if (typeof BUILD_INFO !== 'undefined') buildInfo = BUILD_INFO;
+
+/**
+ * In scenarious where "BUILD_INFO" is not injected by Webpack (server-side,
+ * tests, etc.) we expect the host codebase to explicitly set it before it is
+ * ever requested. As a precaution, this function throws if build info has been
+ * set already, unless `force` flag is explicitly set.
+ * @param info
+ * @param force
+ */
+export function setBuildInfo(info?: BuildInfoT, force = false) {
+  if (buildInfo !== undefined && !force) {
+    throw Error('"Build Info" is already initialized');
+  }
+  buildInfo = info;
+}
+
+/**
+ * Returns "Build Info" object; throws if it has not been initialized yet.
+ * @returns
+ */
+export function getBuildInfo(): BuildInfoT {
+  if (buildInfo === undefined) {
+    throw Error('"Build Info" has not been initialized yet');
+  }
+  return buildInfo;
+}

package/src/shared/utils/isomorphy/environment-check.ts

@@ -0,0 +1,18 @@
+// Checks for client- vs. server-side environment detection.
+
+declare global {
+  // eslint-disable-next-line no-var, vars-on-top
+  var REACT_UTILS_FORCE_CLIENT_SIDE: boolean | undefined;
+}
+
+/**
+ * `true` within client-side environment (browser), `false` at server-side.
+ */
+export const IS_CLIENT_SIDE: boolean = typeof process !== 'object'
+  || !process.versions || !process.versions.node
+  || !!global.REACT_UTILS_FORCE_CLIENT_SIDE;
+
+/**
+ * `true` within the server-side environment (node), `false` at client-side.
+ */
+export const IS_SERVER_SIDE: boolean = !IS_CLIENT_SIDE;

package/src/shared/utils/isomorphy/index.ts

@@ -0,0 +1,38 @@
+import { getBuildInfo } from './buildInfo';
+import { IS_CLIENT_SIDE, IS_SERVER_SIDE } from './environment-check';
+
+/**
+ * @ignore
+ * @return {string} Code mode: "development" or "production".
+ */
+function getMode() {
+  return process.env.NODE_ENV;
+}
+
+/**
+ * Returns `true` if development version of the code is running;
+ * `false` otherwise.
+ * @return {boolean}
+ */
+export function isDevBuild() {
+  return getMode() === 'development';
+}
+
+/**
+ * Returns `true` if production build of the code is running;
+ * `false` otherwise.
+ * @return {boolean}
+ */
+export function isProdBuild() {
+  return getMode() === 'production';
+}
+
+/**
+ * Returns build timestamp of the front-end JS bundle.
+ * @return {string} ISO date/time string.
+ */
+export function buildTimestamp() {
+  return getBuildInfo().timestamp;
+}
+
+export { IS_CLIENT_SIDE, IS_SERVER_SIDE, getBuildInfo };

package/src/shared/utils/jest/E2eSsrEnv.ts

@@ -0,0 +1,250 @@
+/**
+ * Jest environment for end-to-end SSR and client-side testing. It relies on
+ * the standard react-utils mechanics to execute SSR of given scene, and also
+ * Webpack build of the code for client-side execution, it further exposes
+ * Jsdom environment for the client-side testing of the outcomes.
+ */
+/* eslint-disable global-require, import/no-dynamic-require */
+
+// BEWARE: The module is not imported into the JU module / the main assembly of
+// the library, because doing so easily breaks stuff:
+//  1)  This module depends on Node-specific modules, which would make JU
+//      incompatible with JsDom if included into JU.
+//  2)  If this module is weakly imported from somewhere else in the lib,
+//      it seems to randomly break tests using it for a different reason,
+//      probably some sort of a require-loop, or some issues with weak
+//      require in that scenario.
+
+import path from 'path';
+
+import type { Request, Response } from 'express';
+import { defaults, noop, set } from 'lodash';
+
+// As this environment is a part of the Jest testing utils,
+// we assume development dependencies are available when it is used.
+/* eslint-disable import/no-extraneous-dependencies */
+import register from '@babel/register/experimental-worker';
+
+import JsdomEnv from 'jest-environment-jsdom';
+import { type IFs, createFsFromVolume, Volume } from 'memfs';
+import webpack from 'webpack';
+/* eslint-enable import/no-extraneous-dependencies */
+
+import ssrFactory from 'server/renderer';
+
+import type {
+  EnvironmentContext,
+  JestEnvironmentConfig,
+} from '@jest/environment';
+
+export default class E2eSsrEnv extends JsdomEnv {
+  pragmas: Record<string, string | string[]>;
+
+  ssrRequest: object;
+
+  rootDir: string;
+
+  testFolder: string;
+
+  withSsr: boolean;
+
+  webpackStats?: webpack.StatsCompilation;
+
+  /**
+   * Loads Webpack config, and exposes it to the environment via global
+   * webpackConfig object.
+   */
+  loadWebpackConfig() {
+    const optionsString = this.pragmas['webpack-config-options'] as string;
+
+    const options = (optionsString
+      ? JSON.parse(optionsString) : {}) as webpack.Configuration;
+
+    defaults(options, {
+      context: this.testFolder,
+      fs: this.global.webpackOutputFs,
+    });
+
+    const factoryPath = this.pragmas['webpack-config-factory'] as string;
+    let factory = require(path.resolve(this.rootDir, factoryPath));
+    factory = 'default' in factory ? factory.default : factory;
+
+    this.global.webpackConfig = factory(options);
+
+    const fs = this.global.webpackOutputFs as IFs;
+    let buildInfo = `${options.context}/.build-info`;
+    if (fs.existsSync(buildInfo)) {
+      buildInfo = fs.readFileSync(buildInfo, 'utf8') as string;
+      this.global.buildInfo = JSON.parse(buildInfo);
+    }
+  }
+
+  /**
+   * Executes Webpack build.
+   * @return {Promise}
+   */
+  async runWebpack() {
+    this.loadWebpackConfig();
+
+    const compiler = webpack(this.global.webpackConfig as webpack.Configuration);
+    compiler.outputFileSystem = this.global.webpackOutputFs;
+    return new Promise<void>((done, fail) => {
+      compiler.run((err, stats) => {
+        if (err) fail(err);
+        if (stats?.hasErrors()) {
+          // eslint-disable-next-line no-console
+          console.error(stats.toJson().errors);
+          fail(Error('Webpack compilation failed'));
+        }
+
+        this.global.webpackStats = stats?.toJson();
+
+        // Keeps reference to the raw Webpack stats object, which should be
+        // explicitly passed to the server-side renderer alongside the request,
+        // so that it can to pick up asset paths for different named chunks.
+        this.webpackStats = stats;
+
+        done();
+      });
+    });
+  }
+
+  async runSsr() {
+    const optionsString = this.pragmas['ssr-options'] as string;
+    const options = optionsString ? JSON.parse(optionsString) : {};
+
+    // TODO: This is temporary to shortcut the logging added to SSR.
+    if (options.logger === undefined) {
+      options.logger = {
+        debug: noop,
+        info: noop,
+        log: noop,
+        warn: noop,
+      };
+    }
+
+    if (!options.buildInfo) options.buildInfo = this.global.buildInfo;
+
+    let cleanup: (() => void) | undefined;
+
+    if (options.entry) {
+      const p = path.resolve(this.testFolder, options.entry);
+      const module = require(p);
+      cleanup = module.cleanup;
+      options.Application = module[options.entryExportName || 'default'];
+    }
+
+    const renderer = ssrFactory(this.global.webpackConfig!, options);
+    let status = 200; // OK
+    const markup = await new Promise<string>((done, fail) => {
+      renderer(
+        this.ssrRequest as Request,
+
+        // TODO: This will do for now, with the current implementation of
+        // the renderer, but it will require a rework once the renderer is
+        // updated to do streaming.
+        ({
+          cookie: noop,
+          send: done,
+          set: noop,
+          status: (value: number) => {
+            status = value;
+          },
+
+          // This is how up-to-date Webpack stats are passed to the server in
+          // development mode, and we use this here always, instead of having
+          // to pass some information via filesystem.
+          locals: {
+            webpack: {
+              devMiddleware: {
+                stats: this.webpackStats,
+              },
+            },
+          },
+        } as unknown) as Response,
+
+        (error) => {
+          if (error) fail(error);
+          else done('');
+        },
+      );
+    });
+
+    this.global.ssrMarkup = markup;
+    this.global.ssrOptions = options;
+    this.global.ssrStatus = status;
+
+    if (cleanup) cleanup();
+  }
+
+  constructor(
+    config: JestEnvironmentConfig,
+    context: EnvironmentContext,
+  ) {
+    const pragmas = context.docblockPragmas;
+
+    const requestString = pragmas['ssr-request'] as string;
+    const request = requestString ? JSON.parse(requestString) : {};
+
+    if (!request.url) request.url = '/';
+    request.csrfToken = noop;
+
+    // This ensures the initial JsDom URL matches the value we use for SSR.
+    set(
+      config.projectConfig,
+      'testEnvironmentOptions.url',
+      `http://localhost${request.url}`,
+    );
+
+    super(config, context);
+
+    this.global.dom = this.dom;
+    this.global.webpackOutputFs = createFsFromVolume(new Volume());
+
+    // Extracts necessary settings from config and context.
+    const { projectConfig } = config;
+    this.rootDir = projectConfig.rootDir;
+    this.testFolder = path.dirname(context.testPath);
+    this.withSsr = !pragmas['no-ssr'];
+    this.ssrRequest = request;
+    this.pragmas = pragmas;
+
+    // The usual "babel-jest" transformation setup does not apply to
+    // the environment code and imports from it, this workaround enables it.
+    const optionsString = this.pragmas['ssr-options'] as string;
+    const options = optionsString ? JSON.parse(optionsString) : {};
+    let root;
+    switch (options.root) {
+      case 'TEST': root = this.testFolder; break;
+      default: root = process.cwd();
+    }
+    register({
+      envName: options.babelEnv,
+      extensions: ['.js', '.jsx', '.ts', '.tsx', '.svg'],
+      root,
+    });
+  }
+
+  async setup() {
+    await super.setup();
+    await this.runWebpack();
+    if (this.withSsr) await this.runSsr();
+    this.global.REACT_UTILS_FORCE_CLIENT_SIDE = true;
+  }
+
+  async teardown() {
+    delete this.global.REACT_UTILS_FORCE_CLIENT_SIDE;
+
+    // Resets module cache and @babel/register. Effectively this ensures that
+    // the next time an instance of this environment is set up, all modules are
+    // transformed by Babel from scratch, thus taking into account the latest
+    // Babel config (which may change between different environment instances,
+    // which does not seem to be taken into account by Babel / Node caches
+    // automatically).
+    Object.keys(require.cache).forEach((key) => {
+      delete require.cache[key];
+    });
+    register.revert();
+    super.teardown();
+  }
+}

package/src/shared/utils/jest/global.ts

@@ -0,0 +1,19 @@
+import { type IFs } from 'memfs';
+
+/* eslint-disable import/no-extraneous-dependencies */
+import webpack from 'webpack';
+/* eslint-enable import/no-extraneous-dependencies */
+
+declare global {
+  interface Window {
+    ssrMarkup: string | undefined;
+    ssrStatus: number | undefined;
+    webpackConfig: webpack.Configuration | undefined;
+    webpackOutputFs: IFs;
+    webpackStats?: webpack.StatsCompilation;
+  }
+}
+
+export default function getGlobal(): Window {
+  return global as any;
+}