@sima-land/isomorph 11.0.0-alpha.4 → 11.0.0-alpha.40

package/src/utils/redux-saga/take-chain.ts

@@ -0,0 +1,67 @@
+import { Action } from '@reduxjs/toolkit';
+import { delay, fork, put, race, take } from 'redux-saga/effects';
+
+/**
+ * Накапливает экшены и генерирует эффект по таймауту.
+ * @param timeout Время задержки в мс.
+ * @param types Массив с типами ожидаемых экшенов.
+ * @param task Генератор.
+ * @param deps Аргументы для генератора.
+ * @return Эффект.
+ */
+export function takeChain<
+  Deps extends any[],
+  Task extends (...someArgs: [...Deps, Action[]]) => any,
+>(timeout: number, types: string[], task: Task, ...deps: Deps) {
+  return fork(generateTakeChain as any, timeout, types, task, deps);
+}
+
+/**
+ * Генерирует эффект по таймауту.
+ * @internal
+ * @param timeout Время задержки в мс.
+ * @param types Массив с типами ожидаемых экшенов.
+ * @param task Генератор.
+ * @param deps Аргументы для генератора.
+ */
+export function* generateTakeChain<
+  Deps extends any[],
+  Task extends (...someArgs: [...Deps, Action[]]) => any,
+>(timeout: number, types: string[], task: Task, deps: Deps): Generator<any, void, any> {
+  while (true) {
+    const breakAction: Action = { type: `BREAK_${Date.now()}` };
+    const firstAction: Action = yield take(types);
+    const collectedActions = [firstAction];
+
+    yield fork(putDelayed, timeout, breakAction);
+
+    while (true) {
+      const { action, canceled } = yield race({
+        action: take(types),
+        canceled: take(breakAction.type),
+      });
+
+      action && collectedActions.push(action);
+
+      if (
+        canceled ||
+        types.every(type => collectedActions.some(someAction => someAction.type === type))
+      ) {
+        // @todo убрать "as any"
+        yield fork(task as any, ...deps, collectedActions);
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Вызывает экшен с заданной задержкой.
+ * @internal
+ * @param timeout Время задержки в мс.
+ * @param action Тип экшена.
+ */
+export function* putDelayed(timeout: number, action: Action) {
+  yield delay(timeout);
+  yield put(action);
+}

package/src/utils/redux-saga/types.ts

@@ -0,0 +1,43 @@
+import type { Middleware } from '@reduxjs/toolkit';
+import type { Saga, SagaMiddlewareOptions } from 'redux-saga';
+
+/** Опции остановки redux-saga. */
+export interface SagaInterruptConfig {
+  strategy?: 'dispatch-end' | 'cancel-task';
+}
+
+/** Информация, которая приходит вторым аргументом в обработчик ошибки SagaMiddleware. */
+export type SagaErrorInfo = Parameters<Required<SagaMiddlewareOptions>['onError']>[1];
+
+/** Информация об остановке redux-saga. */
+export interface SagaInterruptInfo {
+  timeout: number;
+}
+
+/** Опции запуска redux-saga с остановкой по таймауту. */
+export interface SagaTimeoutRunData<S extends Saga> {
+  saga: S;
+  args: Parameters<S>;
+  timeout: number;
+}
+
+/** Кастомная версия SagaMiddleware. */
+export interface SagaExtendedMiddleware extends Middleware {
+  /**
+   * Установить временное ограничение работы саги.
+   * Если сага не успела выполнится до истечения этого ограничения она будет принудительно завершена.
+   */
+  timeout(milliseconds: number, config?: SagaInterruptConfig): this;
+
+  /**
+   * Запускает сагу.
+   */
+  run: <S extends Saga>(saga: S, ...args: Parameters<S>) => Promise<void>;
+}
+
+/** Обработчик событий SagaExtendedMiddleware. */
+export interface SagaMiddlewareHandler {
+  onSagaError(error: Error, errorInfo: SagaErrorInfo): Promise<void> | void;
+  onConfigError(error: Error): Promise<void> | void;
+  onTimeoutInterrupt(info: SagaInterruptInfo): Promise<void> | void;
+}

package/src/utils/ssr/index.tsx

@@ -0,0 +1,78 @@
+import jsesc from 'jsesc';
+
+/**
+ * Данные для SSR, сформированные на сервере.
+ */
+export interface BridgeServerSide {
+  rootElementId: string;
+  serverDataKey: string;
+}
+
+/**
+ * Данные для SSR, доступные на стороне клиента (в браузере).
+ */
+export interface BridgeClientSide<T> {
+  rootElement: HTMLElement;
+  serverSideData: T;
+}
+
+/**
+ * Набор методов для связывания серверного и клиентского приложений.
+ */
+export const SsrBridge = {
+  /**
+   * Вызывается на сервере.
+   * @param serviceKey Идентификатор корневого элемента.
+   * @return Идентификатор корневого элемента и ключ для глобальной переменной.
+   */
+  prepare(serviceKey: string): BridgeServerSide {
+    return {
+      rootElementId: `${serviceKey}__root`,
+      serverDataKey: `${serviceKey}__serverData`,
+    };
+  },
+
+  /**
+   * Вызывается на клиенте.
+   * @param serviceKey Идентификатор корневого элемента.
+   * @return Корневой элемент и начальное состояние.
+   */
+  resolve<T = any>(serviceKey: string): BridgeClientSide<T> {
+    const rootElement = document.getElementById(`${serviceKey}__root`);
+    const serverSideData = (window as any)[`${serviceKey}__serverData`];
+
+    if (!rootElement) {
+      throw Error('SSR: Не был найден корневой элемент');
+    }
+
+    return { rootElement, serverSideData };
+  },
+} as const;
+
+/**
+ * Скрипт, формирующий глобально доступные на странице данные.
+ * @todo Перенести в utils/react.
+ * @param props Свойства.
+ * @return Элемент.
+ */
+export function GlobalDataScript({
+  property,
+  value,
+}: {
+  property: string;
+  value: Record<any, any>;
+}) {
+  const json = jsesc(JSON.stringify(value), {
+    json: true,
+    isScriptContext: true,
+  });
+
+  return (
+    <script
+      dangerouslySetInnerHTML={{
+        // @todo возможно стоит также экранировать символы в "property"
+        __html: `window["${property}"] = JSON.parse(${json});`,
+      }}
+    />
+  );
+}

package/src/utils/web/analytics/__test__/data-layer.test.ts

@@ -0,0 +1,50 @@
+import { dataLayerPush } from '../data-layer';
+
+describe('dataLayerPush', () => {
+  beforeAll(() => {
+    (window as any).dataLayer = {
+      checkContext: () => 123,
+
+      push: jest.fn(function (this: any, data) {
+        // имитируем реальную работу window.dataLayer.push: в процессе удаляет data.n
+        delete data.n;
+
+        // имитируем реальную работу window.dataLayer.push: в процессе вызывает другие методы с this
+        this.checkContext();
+      }),
+    };
+  });
+
+  afterAll(() => {
+    delete (window as any).dataLayer;
+  });
+
+  it('should handle window.dataLayer.push mutates object argument', () => {
+    const testData = {
+      n: 'test-event',
+      prop1: 1,
+      prop2: 2,
+    };
+
+    expect((window as any).dataLayer.push).toBeCalledTimes(0);
+
+    dataLayerPush(testData);
+
+    expect((window as any).dataLayer.push).toBeCalledTimes(1);
+    expect((window as any).dataLayer.push.mock.calls[0][0]).toEqual({
+      prop1: 1,
+      prop2: 2,
+    });
+    expect(testData).toEqual({
+      n: 'test-event',
+      prop1: 1,
+      prop2: 2,
+    });
+  });
+
+  it('should handle window.dataLayer.push absence', () => {
+    delete (window as any).dataLayer;
+
+    expect(() => dataLayerPush({ n: 'test-123' })).not.toThrow();
+  });
+});

package/src/utils/web/analytics/__test__/oko.test.ts

@@ -0,0 +1,50 @@
+import { okoPush } from '../oko';
+
+describe('okoPush', () => {
+  beforeAll(() => {
+    (window as any).oko = {
+      checkContext: () => 123,
+
+      push: jest.fn(function (this: any, data) {
+        // имитируем реальную работу window.oko.push: в процессе удаляет data.n
+        delete data.n;
+
+        // имитируем реальную работу window.oko.push: в процессе вызывает другие методы с this
+        this.checkContext();
+      }),
+    };
+  });
+
+  afterAll(() => {
+    delete (window as any).oko;
+  });
+
+  it('should handle window.oko.push mutates object argument', () => {
+    const testData = {
+      n: 'test-event',
+      prop1: 1,
+      prop2: 2,
+    };
+
+    expect((window as any).oko.push).toBeCalledTimes(0);
+
+    okoPush(testData);
+
+    expect((window as any).oko.push).toBeCalledTimes(1);
+    expect((window as any).oko.push.mock.calls[0][0]).toEqual({
+      prop1: 1,
+      prop2: 2,
+    });
+    expect(testData).toEqual({
+      n: 'test-event',
+      prop1: 1,
+      prop2: 2,
+    });
+  });
+
+  it('should handle window.oko.push absence', () => {
+    delete (window as any).oko;
+
+    expect(() => okoPush({ n: 'test-123' })).not.toThrow();
+  });
+});

package/src/utils/web/analytics/data-layer.ts

@@ -0,0 +1,12 @@
+/**
+ * Отправка аналитики в dataLayer.
+ * @param eventData Данные события для отправки.
+ */
+export function dataLayerPush(eventData: Record<string, any>): void {
+  const target: any = window;
+
+  if (typeof target.dataLayer?.push === 'function') {
+    // копируем объект так как window.dataLayer.push может менять аргумент в процессе работы
+    target.dataLayer.push({ ...eventData });
+  }
+}

package/src/utils/web/analytics/index.ts

@@ -0,0 +1,2 @@
+export { dataLayerPush } from './data-layer';
+export { type OkoEvent, okoPush } from './oko';

package/src/utils/web/analytics/oko.ts

@@ -0,0 +1,14 @@
+export type OkoEvent = Record<string, any>;
+
+/**
+ * Получив объект события, запустит его отправку в ОКО (если на странице есть ОКО).
+ * @param eventData Данные события для отправки.
+ */
+export function okoPush(eventData: OkoEvent): void {
+  const target: any = window;
+
+  if (typeof target.oko?.push === 'function') {
+    // копируем объект так как window.oko.push меняет свой аргумент в процессе выполнения
+    target.oko.push({ ...eventData });
+  }
+}

package/src/utils/web/storage/index.ts

@@ -0,0 +1,84 @@
+/* eslint-disable require-jsdoc, jsdoc/require-jsdoc */
+
+/**
+ * Интерфейс объекта-обертки для безопасной работы с WebStorage.
+ */
+export interface StorageUtils
+  extends Pick<Storage, 'clear' | 'getItem' | 'key' | 'removeItem' | 'setItem' | 'length'> {
+  isAvailable: () => boolean;
+}
+
+/**
+ * Возвращает объект для безопасной работы с браузерным хранилищем (LocalStorage, SessionStorage).
+ * @param getStorage Функция, которая должна вернуть целевое хранилище.
+ * @return Объект-обертка для безопасной работы с браузерным хранилищем.
+ * @todo Пересмотреть и перенести из browser?
+ */
+export function createStorageUtils(getStorage: () => Storage): StorageUtils {
+  function isAvailable(): boolean {
+    try {
+      const testKey = `storage_test_key::${Date.now()}`;
+
+      getStorage().setItem(testKey, testKey);
+      getStorage().removeItem(testKey);
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function clear(): void {
+    if (isAvailable()) {
+      getStorage().clear();
+    }
+  }
+
+  function getItem(name: string): string | null {
+    if (isAvailable()) {
+      return getStorage().getItem(name);
+    }
+
+    return null;
+  }
+
+  function key(index: number): string | null {
+    if (isAvailable()) {
+      return getStorage().key(index);
+    }
+    return null;
+  }
+
+  function removeItem(name: string): void {
+    if (isAvailable()) {
+      getStorage().removeItem(name);
+    }
+  }
+
+  function setItem(name: string, value: string): void {
+    if (isAvailable()) {
+      getStorage().setItem(name, value);
+    }
+  }
+
+  function length(): number {
+    if (isAvailable()) {
+      return getStorage().length;
+    }
+
+    return 0;
+  }
+
+  return {
+    isAvailable,
+
+    clear,
+    getItem,
+    key,
+    removeItem,
+    setItem,
+    get length() {
+      return length();
+    },
+  };
+}

package/src/utils/webpack/env/index.ts

@@ -0,0 +1,91 @@
+import { defineEnv, asEnvVariables } from './utils';
+import type { Compiler, WebpackPluginInstance } from 'webpack';
+import type { EnvPluginOptions } from './types';
+
+/**
+ * Плагин для зашивания переменных среды в сборки.
+ * В браузерную сборку зашьёт только переменные с префиксом "PUBLIC_".
+ * ВАЖНО: все зашиваемые переменные будут доступны через глобальный объект __ISOMORPH_ENV__.
+ */
+export class EnvPlugin implements WebpackPluginInstance {
+  options: Required<EnvPluginOptions>;
+
+  /**
+   * @param options Опции.
+   */
+  constructor(options: EnvPluginOptions = {}) {
+    this.options = {
+      target: options.target ?? 'auto',
+      dotenvUsage: options.dotenvUsage ?? true,
+      additional: options.additional ?? [],
+      define: options.define ?? {},
+    };
+  }
+
+  /**
+   * @param compiler Компилятор.
+   */
+  apply(compiler: Compiler) {
+    const { webpack } = compiler;
+
+    const env = defineEnv({
+      dotenvUsage: this.options.dotenvUsage,
+      onError: error => {
+        compiler.hooks.compilation.tap('EnvPlugin', compilation => {
+          compilation.warnings.push(new webpack.WebpackError(`[EnvPlugin] ${String(error)}`));
+        });
+      },
+    });
+
+    let values: Record<string, string | undefined> | null = null;
+    let target: string | undefined;
+
+    // define target
+    if (this.options.target === 'auto') {
+      target = typeof compiler.options.target === 'string' ? compiler.options.target : undefined;
+    } else {
+      target = this.options.target;
+    }
+
+    // define values based on target
+    switch (target) {
+      case 'web': {
+        const targetKeys = [...this.options.additional, 'NODE_ENV'];
+
+        values = { ...this.options.define };
+
+        for (const name of Object.keys(env)) {
+          if (targetKeys.includes(name) || name.startsWith('PUBLIC_')) {
+            values[name] = env[name];
+          }
+        }
+        break;
+      }
+      case 'node': {
+        const targetKeys = [...this.options.additional, 'NODE_ENV'];
+
+        values = { ...this.options.define };
+
+        for (const name of Object.keys(env)) {
+          if (targetKeys.includes(name) || name.startsWith('PUBLIC_')) {
+            values[name] = env[name];
+          }
+        }
+        break;
+      }
+      default: {
+        compiler.hooks.compilation.tap('EnvPlugin', compilation => {
+          compilation.warnings.push(
+            new webpack.WebpackError('[EnvPlugin] Target is unknown, variables will NOT be added'),
+          );
+        });
+        break;
+      }
+    }
+
+    if (values) {
+      new webpack.DefinePlugin({ __ISOMORPH_ENV__: JSON.stringify(values) }).apply(compiler);
+      new webpack.DefinePlugin(asEnvVariables(values)).apply(compiler);
+    }
+  }
+}

package/src/utils/webpack/env/types.ts

@@ -0,0 +1,14 @@
+/** Опции EnvPlugin. */
+export interface EnvPluginOptions {
+  /** Целевая среда. */
+  target?: 'auto' | 'web' | 'node';
+
+  /** Нужно ли использоваь .env файлы. */
+  dotenvUsage?: boolean;
+
+  /** Переменные, зашиваемые из среды запуска. */
+  additional?: string[];
+
+  /** Переменные определяемые на месте. */
+  define?: Record<string, string>;
+}

package/src/utils/webpack/env/utils.ts

@@ -0,0 +1,53 @@
+import { EnvPluginOptions } from './types';
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+
+/**
+ * Формирует объект с переменными среды с учетом .env файлов.
+ * @param options Опции.
+ * @return Объект с переменными среды.
+ */
+export function defineEnv(
+  options: Pick<EnvPluginOptions, 'dotenvUsage'> & { onError?: (error: unknown) => void },
+): Record<string, string | undefined> {
+  const result = { ...process.env };
+
+  if (options.dotenvUsage && process.env.NODE_ENV) {
+    try {
+      const dotenvPath = path.join(process.cwd(), `.env.${process.env.NODE_ENV}`);
+
+      if (fs.existsSync(dotenvPath)) {
+        const parsed = dotenv.parse(fs.readFileSync(dotenvPath, 'utf-8'));
+
+        // @todo дёрнуть бы эту логику из пакета dotenv, https://github.com/motdotla/dotenv/issues/690
+        for (const key of Object.keys(parsed)) {
+          if (!Object.prototype.hasOwnProperty.call(result, key)) {
+            result[key] = parsed[key];
+          }
+        }
+      }
+    } catch (error) {
+      options.onError?.(error);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Получив таблицу "название переменной среды >> значение переменной среды" вернёт определение для DefinePlugin.
+ * @param input Таблица переменных.
+ * @return Определение для DefinePlugin.
+ */
+export function asEnvVariables(input: Record<string, string | undefined>): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(input)) {
+    if (key && typeof value === 'string') {
+      result[`process.env.${key}`] = JSON.stringify(value);
+    }
+  }
+
+  return result;
+}

package/src/utils/webpack/index.ts

@@ -0,0 +1,7 @@
+import { EnvPlugin } from './env';
+import { EnvPluginOptions } from './env/types';
+import { ModuleFederationPlugin } from './module-federation';
+import { ModuleFederationPluginOptions } from './module-federation/types';
+
+export type { EnvPluginOptions, ModuleFederationPluginOptions };
+export { EnvPlugin, ModuleFederationPlugin };