@dr.pogodin/react-utils 1.25.6 → 1.26.0

package/tsconfig.types.json

@@ -0,0 +1,53 @@
+// TS config for ESLint, editor plugins, and other tools that look-up and use
+// the default tsconfig.json file.
+{
+  // Note: Full relative paths, as some tools don't support Node module
+  // resolution mechanics.
+  "extends": "./node_modules/@tsconfig/recommended/tsconfig.json",
+
+  // Keep these in case any mocks / tests are declared within "src" code tree.
+  "exclude": [
+    "**/__mocks__/**",
+    "**/__tests__/**",
+  ],
+
+  "include": [
+    "src",
+    "types.d.ts",
+  ],
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "jsx": "react-jsx",
+
+    // BEWARE: Different settings are likely to transform dynamic import()
+    // statements in the code, thus breaking Webpack's code splitting.
+    // See: https://davidea.st/articles/webpack-typescript-code-split-wont-work
+    "module": "ESNext",
+    "moduleResolution": "Node",
+
+    "outDir": "build/types-code",
+
+    "paths": {
+      // BEWARE: Don't do this, as in other TS config files:
+      //
+      //  "*": ["./src/shared/*", "./src/*", "./*"]
+      //
+      // "ts-alias" does not act on "*" rule, as we need to get correctly
+      // resolved relative paths in the generated .d.ts files, so that they
+      // can work in host projects.
+
+      "components": ["./src/shared/components"],
+      "components/*": ["./src/shared/components/*"],
+      "server/*": ["./src/server/*"],
+      "utils": ["./src/shared/utils"],
+      "utils/*": ["./src/shared/utils/*"],
+    },
+    "rootDirs": [".", "build/types-scss"],
+    "strict": true,
+
+    // This ensures TypeScript does not remove unused imports, which may cause
+    // troubles when we rely on some side-effects from imported modules.
+    "verbatimModuleSyntax": true,
+  },
+}

package/typed-scss-modules.config.ts

@@ -0,0 +1,9 @@
+export default {
+  ignore: [
+    '**/docs/**/*.scss',
+  ],
+  includePaths: [
+    'src',
+  ],
+  outputFolder: 'build/types-scss',
+};

package/types.d.ts

@@ -0,0 +1,37 @@
+declare module '@babel/register/experimental-worker' {
+  const register: {
+    (args: {
+      envName: string;
+      extensions: string[];
+      root: string;
+    }): void;
+    revert: () => void;
+  };
+
+  export default register;
+}
+
+// TODO: This should be done inside my CSURF fork itself.
+declare module '@dr.pogodin/csurf' {
+  import F from 'csurf';
+
+  export default F;
+}
+
+declare module 'node-forge/lib/forge' {
+  import F from 'node-forge';
+
+  export default F;
+}
+
+declare module '*.png' {
+  export default string;
+}
+
+declare namespace React {
+  // This allows all JSX elements to have additional "styleName" attribute,
+  // handled by "@dr.pogodin/babel-plugin-react-css-modules".
+  interface Attributes {
+    styleName?: string;
+  }
+}

package/{webpack.config.js → webpack.config.ts}

@@ -1,17 +1,21 @@
 /* eslint-disable global-require */
 /* eslint-disable import/no-dynamic-require */
 
-module.exports = function buildConfig(env) {
-  const config = require(`./config/webpack/lib-${env}.js`)({
+module.exports = function buildConfig(env: string) {
+  let factory = require(`./config/webpack/lib-${env}.js`);
+  factory = 'default' in factory ? factory.default : factory;
+
+  const config = factory({
     context: __dirname,
     entry: './src',
     library: '@dr.pogodin/react-utils',
+    typescript: true,
   });
 
   /* The lib config is intended for use outside of this very package,
    * so we need some tweaks here to make it work for this package itself. */
   const babelLoader = config.module.rules.find(
-    (x) => x.loader === 'babel-loader',
+    (x: { loader: string }) => x.loader === 'babel-loader',
   );
   babelLoader.options.presets[0][0] = `${__dirname}/config/babel/webpack`;
 

package/config/babel/node-ssr.js

@@ -1,85 +0,0 @@
-/* eslint-disable import/no-extraneous-dependencies */
-
-const { pick, pull } = require('lodash');
-const getWebpackBabelConfig = require('./webpack');
-
-/**
- * Creates a new base config.
- * @param {object} babel Babel compiler.
- * @param {object} [options] It supports all options of
- *  {@link module:babel/webpack.getPreset babel/webpack's getPreset()},
- *  but it overrides `targets` option with `current node` value, and further
- *  accepts the following:
- * @param {string} [options.baseAssetsOutputPath] Path prefix for emitted
- *  image assets.
- * @return {object} Created config object.
- * @ignore
- */
-function newBase(babel, options = {}) {
-  const baseOps = pick(options, ['noStyling']);
-  const config = getWebpackBabelConfig(
-    babel,
-    { ...baseOps, targets: 'current node' },
-  );
-
-  const baseAssetsOutputPath = options.baseAssetsOutputPath || '';
-  config.plugins.push(
-    ['@dr.pogodin/transform-assets', {
-      extensions: ['gif', 'jpeg', 'jpg', 'png'],
-      name: `${baseAssetsOutputPath}/images/[md4:hash:20].[ext]`,
-    }],
-  );
-
-  const moduleResolverPluginOps = config.plugins.find(
-    (x) => x[0] === 'module-resolver',
-  )[1];
-  moduleResolverPluginOps.transformFunctions = [
-    'requireWeak',
-    'resolveWeak',
-    'webpack.requireWeak',
-    'webpack.resolveWeak',
-  ];
-
-  if (babel.env() === getWebpackBabelConfig.ENVIRONMENTS.DEV) {
-    pull(config.plugins, 'react-refresh/babel');
-  }
-
-  return config;
-}
-
-/**
- * Updates given `config` with styling ((S)CSS-related) setup.
- *
- * **Beware:** It mutates `config`.
- *
- * @param {object} config
- * @return {object} Returns mutated config for chaining.
- * @ignore
- */
-function addStyling(config) {
-  const cssModulesOps = config.plugins.find(
-    ([name]) => name === '@dr.pogodin/react-css-modules',
-  )[1];
-  cssModulesOps.replaceImport = true;
-  return config;
-}
-
-/**
- * Generates Babel config for NodeJS compilation and server-side  execution.
- * @param {object} babel Babel compiler instance.
- * @param {object} [ops] Preset options. It supports all options accepted by
- *  the underlying {@link module:babel/webpack preset for Webpack}, but it
- *  overrides `targets` option by `current node` value, and also accepts
- *  the following additional options:
- * @param {string} [ops.baseAssetsOutputPath] Path prefix for emitted image
- *  assets.
- * @return {object} Generated config.
- */
-function getConfig(babel, ops = {}) {
-  const env = babel.env();
-  const config = newBase(babel, ops);
-  if (!ops.noStyling) addStyling(config, env);
-  return config;
-}
-
-module.exports = getConfig;

package/config/babel/webpack.js

@@ -1,123 +0,0 @@
-const { pick } = require('lodash');
-
-const {
-  generateScopedNameFactory,
-} = require('@dr.pogodin/babel-plugin-react-css-modules/utils');
-
-const generateScopedNameDev = generateScopedNameFactory(
-  '[package]___[path][name]___[local]___[hash:base64:6]',
-);
-
-const generateScopedNameProd = generateScopedNameFactory(
-  '[hash:base64:6]',
-);
-
-/**
- * @static
- * @desc
- * ```js
- * import { ENVIRONMENTS } from '@dr.pogodin/react-utils/config/babel/webpack';
- * ```
- * Supported Babel environments.
- * @prop {string} DEV `development`
- * @prop {string} PROD `production`
- * @prop {string} TEST `test`
- */
-const ENVIRONMENTS = {
-  DEV: 'development',
-  PROD: 'production',
-  TEST: 'test',
-};
-
-/**
- * Creates a new base config.
- * @param {object} [options] Base config options.
- * @param {string|string[]|object} [options.targets=defaults]
- *  `@babel/preset-env` targets.
- * @return {object} Generated config.
- * @ignore
- */
-function newBaseConfig(options = {}) {
-  return {
-    presets: [
-      // Chrome 69 is the browser for Android API 28.
-      ['@babel/env', { targets: options.targets || 'defaults or chrome >= 69' }],
-
-      // TODO: Starting from Babel 8, "automatic" will be the default runtime,
-      // thus once upgraded to Babel 8, runtime should be removed from
-      // @babel/react options below.
-      ['@babel/react', { runtime: 'automatic' }],
-
-      '@dr.pogodin/babel-preset-svgr',
-    ],
-    plugins: [
-      ['module-resolver', {
-        extensions: ['.js', '.jsx'],
-        root: [
-          './src/shared',
-          './src',
-        ],
-      }],
-      '@babel/transform-runtime',
-    ],
-  };
-}
-
-/**
- * Updates given `config` with styling ((S)CSS-related) setup.
- *
- * **Beware:** It mutates `config`.
- *
- * @param {object} config
- * @param {string} env Target environment: `development` or `production`.
- * @return {object} Returns mutated config for chaining.
- * @ignore
- */
-function addStyling(config, env) {
-  const cssModulesOps = {
-    autoResolveMultipleImports: true,
-    filetypes: {
-      '.scss': { syntax: 'postcss-scss' },
-    },
-  };
-  config.plugins.push(['@dr.pogodin/react-css-modules', cssModulesOps]);
-  switch (env) {
-    case ENVIRONMENTS.DEV:
-    case ENVIRONMENTS.TEST:
-      cssModulesOps.generateScopedName = generateScopedNameDev;
-      break;
-    case ENVIRONMENTS.PROD:
-      cssModulesOps.generateScopedName = generateScopedNameProd;
-      break;
-    default:
-  }
-  return config;
-}
-
-/**
- * Generates Babel preset for Webpack.
- * @param {object} babel Babel compiler.
- * @param {object} [ops] Preset options.
- * @param {boolean} [ops.noRR] If truthy `react-refresh/babel` plugin is not
- *  included into config, no matter the environment.
- * @param {boolean} [ops.noStyling] If truthy all setup related to styling
- *  ((S)CSS processing) will be skipped.
- * @param {string|string[]|object} [ops.targets=defaults] Targets for
- *  `@babel/preset-env`.
- * @return {object} Generated config.
- */
-function getPreset(babel, ops = {}) {
-  const env = babel.env();
-
-  const baseOps = pick(ops, ['targets']);
-  const res = newBaseConfig(baseOps);
-
-  if (!ops.noStyling) addStyling(res, env);
-  if (env === ENVIRONMENTS.DEV && !ops.noRR) {
-    res.plugins.push('react-refresh/babel');
-  }
-  return res;
-}
-
-module.exports = getPreset;
-module.exports.ENVIRONMENTS = ENVIRONMENTS;

package/config/webpack/app-base.js

@@ -1,330 +0,0 @@
-/**
- * @category Configs
- * @module webpack/app-base
- * @desc
- * Base [Webpack](https://webpack.js.org/) configuration for apps.
- */
-
-const nodeFs = require('fs');
-const path = require('path');
-
-const {
-  clone,
-  defaults,
-  isFunction,
-  isObject,
-} = require('lodash');
-
-const autoprefixer = require('autoprefixer');
-const MiniCssExtractPlugin = require('mini-css-extract-plugin');
-const forge = require('node-forge');
-const SM = require('sitemap');
-const { DefinePlugin, ProgressPlugin } = require('webpack');
-const WorkboxPlugin = require('workbox-webpack-plugin');
-
-const {
-  getLocalIdent,
-} = require('@dr.pogodin/babel-plugin-react-css-modules/utils');
-
-/**
- * Creates a new Webpack config object, and performs some auxiliary operations
- * on the way.
- * @param {object} ops Configuration params. This allows to modify some
- * frequently changed options in a convenient way, without a need to manipulate
- * directly with the created config object.
- * @param {string} ops.babelEnv Babel environment to use for the Babel
- * compilation step.
- * @param {object} [ops.babelLoaderOptions] Overrides for default Babel options
- * of JSX and SVG files loader.
- * @param {string} ops.context Base URL for resolution of relative config paths.
- * @param {string} [ops.cssLocalIdent=hash:base64:6] The template for
- * CSS classnames generation by the Webpack's `css-loader`; it is passed into
- * the `localIdentName` param of the loader. It should match the corresponding
- * setting in the Babel config.
- * @param {boolean} [ops.dontEmitBuildInfo] If set the `.build-info` file won't
- * be created at the disk during the compilation.
- * @param {boolean} [ops.dontUseProgressPlugin] Set to not include progress
- *  plugin.
- * @param {string|string[]} ops.entry Entry points for "main" chunk. The config
- * will prepend them by some necessary polyfills, e.g.:
- * ([babel-polyfill](https://babeljs.io/docs/usage/polyfill/),
- * [nodelist-foreach-polyfill](https://www.npmjs.com/package/nodelist-foreach-polyfill)).
- * @param {boolean|object} ops.workbox If evaluates to a truthy value,
- * [Workbox's InjectManifest plugin](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#injectmanifest_plugin)
- * is added to the array of Webpack plugins, to generate service worker for
- * browser. If the value is an object, it is merged into the options passed
- * into the plugin, otherwise default options are used:
- * ```json
- * {
- *   "importWorkboxFrom": "local",
- *   "swSrc": "@dr.pogodin/react-utils/config/workbox/default.js",
- *   "swDest": "__service-worker.js"
- * }
- * ```
- * If service worker is generated by this option, it will be automatically
- * initiated at the client side by the standard
- * [client-side initialization script](docs/client.md)
- * provided by **@dr.pogodin/react-utils**. Note that `swDest`'s value cannot be
- * overriden by config options provided via `workbox` object.
- * @param {object} [ops.fs] Filesystem to use instead of the Node's FS.
- * @param {boolean|object} [ops.keepBuildInfo] If `true` and a `.build-info`
- *  file from a previous build exists in the context directory, it will be
- *  loaded and used, rather than re-generated by the config factory. It allows
- *  to re-create the Webpack config during a server launch without re-generation
- *  of the build info file created during a previous build (and thus bundled
- *  into the frontend bundle). If an object is provided, it will be used as
- *  the build info, instead of trying to load it from the filesystem. This
- *  feature is intended for testing context.
- * @param {string} ops.mode
- * [Webpack mode](https://webpack.js.org/concepts/mode/).
- * @param {string} [ops.outputPath=build] Optional. Output path for the build.
- * @param {string} ops.publicPath Base URL for the output of the build assets.
- * @param {string} [ops.sitemap] The path to JS or JSON config for sitemap.
- * It can be relative to the context, and can be a factory, which returns
- * the config. The config should be compatible with
- * [`sitemap`](https://www.npmjs.com/package/sitemap) library, and if
- * provided the Webpack config factory will use it to gererate `sitemap.xml`
- * file in the output folder, and then serve it from the app root.
- * @return The generated config will opt to:
- * - Bundle the font assets (EOF, OTF, SVG, TTF, WOFF, WOFF2 files from
- *   the `src/assets/fonts` folder of your source code will be bundled
- *   and output into the `[PUBLIC_PATH]/fonts` folder);
- * - Bundle image assets (GIF, JPEG, JPG, PNG files from any folder of
- *   your source code will be bundled and output into the
- *   `[PUBLIC_PATH]/images` folder);
- * - Bundle SCSS files from any folder of your source code, beside
- *   `node_modules` and its subfolders. The files will be compiled,
- *    bundled and extracted into the `[PUBLIC_PATH]/[CHUNK_NAME].css`
- *    bundles;
- * - Bundle CSS files from any folder of your code. The files will be
- *   bundled and extracted into the `[PUBLIC_PATH]/[CHUNK_NAME].css`
- *   bundles;
- * - Bundle JS, JSX, and SVG files; they will be compiled into the
- *   `[PUBLIC_PATH]/[CHUNK_NAME].js` bundles, using the Babel environment
- *   specified in the factory options, and
- *   [`config/babel/webpack`](./babel-config.js#webpack) config.
- *
- * - The following path aliases will be automatically set:
- * - **`assets`** for `[CONTEXT]/src/assets`;
- * - **`components`** for `[CONTEXT]/src/shared/components`;
- * - **`fonts`** for `[CONTEXT]/src/assets/fonts`;
- * - **`styles`** for `[CONTEXT]/src/styles`.
- *
- * Also `resolve.symlinks` Webpack option is set to *false* to avoid problems
- * with resolution of assets from packages linked with `npm link`.
- *
- * - The following global variables will be emulated inside the output
- *   JS bundle:
- *   - **`BUILD_RNDKEY`** — A random 32 bit key that can be used
- *     for encryption, it is set just as a global variable accessible in
- *     the code;
- *   - **`BUILD_TIMESTAMP`** — UTC timestamp of the beginning of
- *     the build;
- *   - **`FRONT_END`** — It will be set *true* inside the bundle,
- *     so that shared code can use it to determine that it is executed
- *     at the client side.
- *
- * - It also opts to polyfill the `__dirname` global variable,
- *   and to ignore imports of the `fs` Node package;
- *
- * - Also, it will store to the disk (re-writes if exists) the file
- *   `[CONTEXT]/.build-info` which will contain a stringified JSON
- *   object with the following fields:
- *   - **`rndkey`** — The value set for `BUILD_RNDKEY`;
- *   - **`timestamp`** — The value set for `BUILD_TIMESTAMP`.
- */
-module.exports = function configFactory(ops) {
-  const o = defaults(clone(ops), {
-    babelLoaderOptions: {},
-    cssLocalIdent: '[hash:base64:6]',
-    outputPath: 'build/web-public',
-    publicPath: '',
-  });
-
-  const fs = ops.fs || nodeFs;
-
-  /* TODO: This works in practice, but being async and not awaited it is a bad
-   * pattern. */
-  if (o.sitemap) {
-    const sitemapUrl = path.resolve(o.context, o.sitemap);
-    /* eslint-disable global-require, import/no-dynamic-require */
-    let source = require(sitemapUrl);
-    if (isFunction(source)) source = source();
-    /* eslint-enable global-require, import/no-dynamic-require */
-    const sm = new SM.SitemapStream();
-    source.forEach((item) => sm.write(item));
-    sm.end();
-    SM.streamToPromise(sm).then((sitemap) => {
-      const outUrl = path.resolve(o.context, o.outputPath);
-      if (!fs.existsSync(outUrl)) fs.mkdirSync(outUrl);
-      fs.writeFileSync(
-        path.resolve(o.context, o.outputPath, 'sitemap.xml'),
-        sitemap,
-      );
-    });
-  }
-
-  // TODO: Once all assets are named by hashes, we probably don't need build
-  // info anymore beside the key, which can be merged into stats object?
-  // On the other hand, it is still handy to have to pass around the build
-  // timestamp, and any other similar information to the actual app, so it
-  // can be used in some scenarious.
-  let buildInfo;
-  const buildInfoUrl = path.resolve(o.context, '.build-info');
-
-  if (o.keepBuildInfo) {
-    // If "true" - attempt to load from the filesystem.
-    if (o.keepBuildInfo === true) {
-      if (fs.existsSync(buildInfoUrl)) {
-        buildInfo = JSON.parse(fs.readFileSync(buildInfoUrl));
-      }
-
-    // Otherwise we assume .keepBuildInfo value itself is the build info object
-    // to use in the build.
-    } else buildInfo = o.keepBuildInfo;
-  }
-
-  // Even if "keepBuildInfo" option was provided, we still generate a new
-  // build info object in case nothing could be loaded.
-  if (!buildInfo) {
-    buildInfo = Object.freeze({
-      /* A random 32-bit key, that can be used for encryption. */
-      key: forge.random.getBytesSync(32),
-
-      /* Public path used during build. */
-      publicPath: o.publicPath,
-
-      /* `true` if client-side code should setup a service worker. */
-      useServiceWorker: Boolean(o.workbox),
-    });
-  }
-
-  // If not opted-out, we write the build info to the filesystem. We also attach
-  // it to the factory function itself, so it can be easily accessed right after
-  // the factory call in testing scenarios.
-  if (!o.dontEmitBuildInfo) {
-    // Note: this is needed if "fs" option is provided, to ensure the factory
-    // does not crash if the folder is not created in that filesystem.
-    fs.mkdirSync(o.context, { recursive: true });
-
-    fs.writeFileSync(buildInfoUrl, JSON.stringify(buildInfo));
-  }
-
-  /* Entry points normalization. */
-  const entry = [
-    'core-js/stable',
-    'regenerator-runtime/runtime',
-    'nodelist-foreach-polyfill',
-    ...Array.isArray(o.entry) ? o.entry : [o.entry],
-  ];
-
-  const plugins = [
-    new DefinePlugin({ BUILD_INFO: JSON.stringify(buildInfo) }),
-  ];
-
-  if (!ops.dontUseProgressPlugin) plugins.push(new ProgressPlugin());
-
-  /* Adds InjectManifest plugin from WorkBox, if opted to. */
-  if (o.workbox) {
-    if (!isObject(o.workbox)) o.workbox = {};
-    plugins.push(new WorkboxPlugin.InjectManifest({
-      swSrc: path.resolve(__dirname, '../workbox/default.js'),
-      ...o.workbox,
-      swDest: '__service-worker.js',
-    }));
-  }
-
-  return {
-    context: o.context,
-    entry,
-    node: {
-      __dirname: true,
-    },
-    mode: o.mode,
-    output: {
-      chunkFilename: '[contenthash].js',
-      filename: '[contenthash].js',
-      path: path.resolve(__dirname, o.context, o.outputPath),
-      publicPath: `${o.publicPath}/`,
-    },
-    plugins,
-    resolve: {
-      alias: {
-        /* Aliases to JS an JSX files are handled by Babel. */
-        assets: path.resolve(o.context, 'src/assets'),
-        components: path.resolve(o.context, 'src/shared/components'),
-        fonts: path.resolve(o.context, 'src/assets/fonts'),
-        styles: path.resolve(o.context, 'src/styles'),
-      },
-      extensions: ['.js', '.json', '.jsx', '.scss'],
-      symlinks: false,
-    },
-    module: {
-      rules: [{
-        /* Loads font resources from "src/assets/fonts" folder. */
-        test: /\.(eot|otf|svg|ttf|woff2?)$/,
-        include: [
-          /node_modules/,
-          /src[/\\]assets[/\\]fonts/,
-        ],
-        type: 'asset/resource',
-        generator: {
-          filename: 'fonts/[contenthash][ext][query]',
-        },
-      }, {
-        /* Loads JS and JSX moudles, and inlines SVG assets. */
-        test: /\.(jsx?|svg)$/,
-        exclude: [/node_modules/],
-        loader: 'babel-loader',
-        options: {
-          babelrc: false,
-          configFile: false,
-          envName: o.babelEnv,
-          presets: ['@dr.pogodin/react-utils/config/babel/webpack'],
-          ...o.babelLoaderOptions,
-        },
-      }, {
-        /* Loads image assets. */
-        test: /\.(gif|jpe?g|png)$/,
-        type: 'asset/resource',
-        generator: {
-          filename: 'images/[contenthash][ext][query]',
-        },
-      }, {
-        /* Loads SCSS stylesheets. */
-        test: /\.scss$/,
-        use: [
-          MiniCssExtractPlugin.loader, {
-            loader: 'css-loader',
-            options: {
-              modules: {
-                getLocalIdent,
-                localIdentName: o.cssLocalIdent,
-              },
-            },
-          }, {
-            loader: 'postcss-loader',
-            options: {
-              postcssOptions: {
-                plugins: [autoprefixer],
-              },
-            },
-          }, 'resolve-url-loader', {
-            loader: 'sass-loader',
-            options: {
-              sourceMap: true,
-            },
-          },
-        ],
-      }, {
-        /* Loads CSS stylesheets. It is assumed that CSS stylesheets come only
-        * from dependencies, as we use SCSS inside our own code. */
-        test: /\.css$/,
-        use: [
-          MiniCssExtractPlugin.loader,
-          'css-loader',
-        ],
-      }],
-    },
-  };
-};