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

package/src/di/errors.ts

@@ -0,0 +1,59 @@
+import type { Token } from './types';
+
+/**
+ * Ошибка, сообщающая, что в контейнере нет сервиса по заданному ключу.
+ */
+export class NothingBoundError extends Error {
+  readonly token: Token<unknown>;
+
+  /**
+   * Конструктор.
+   * @param token Токен.
+   * @param containerName Имя контейнера.
+   */
+  constructor(token: Token<unknown>, containerName?: string) {
+    super(`Nothing bound to ${String(token)} in ${display(containerName)}`);
+    this.name = 'NothingBoundError';
+    this.token = token;
+  }
+}
+
+/**
+ * Ошибка, сообщающая, что в контейнере уже зарегистрирован компонент под таким токеном.
+ */
+export class AlreadyBoundError extends Error {
+  /**
+   * Конструктор.
+   * @param token Токен.
+   * @param containerName Имя контейнера.
+   */
+  constructor(token: Token<unknown>, containerName?: string) {
+    super(`Cannot rebind token in ${display(containerName)}, already bound: ${String(token)}`);
+    this.name = 'AlreadyBoundError';
+  }
+}
+
+/**
+ * Ошибка, сообщающая, что обнаружена циклическая зависимость.
+ */
+export class CircularDependencyError extends Error {
+  /**
+   * Конструктор.
+   * @param trace Список токенов, в котором обнаружен цикл.
+   * @param containerName Имя контейнера.
+   */
+  constructor(trace: Token<unknown>[], containerName?: string) {
+    const names = trace.map(String).join(' >> ');
+    super(`Circular dependency found in ${display(containerName)}, trace: ${names}`);
+    this.name = 'CircularDependencyError';
+  }
+}
+
+/**
+ * Вернёт переданное имя контейнера или заглушку.
+ * @param containerName Имя.
+ * @return Имя или заглушка.
+ */
+function display(containerName?: string) {
+  return containerName ?? '[unknown container]';
+}

package/{di/index.d.ts → src/di/index.ts}

@@ -1,5 +1,5 @@
-export { Token, Resolve, Provider, Container, Application, Preset } from './types';
-export { NothingBoundError, CircularDependencyError } from './errors';
+export type { Token, Resolve, Provider, Container, Application, Preset } from './types';
+export { NothingBoundError, CircularDependencyError, AlreadyBoundError } from './errors';
 export { createToken } from './token';
 export { createContainer } from './container';
 export { createPreset } from './preset';

package/src/di/preset.ts

@@ -0,0 +1,32 @@
+/* eslint-disable require-jsdoc, jsdoc/require-jsdoc */
+import type { Application, Provider, Token, Preset } from './types';
+
+type PresetEntry<T = any> = [Token<T>, Provider<T>];
+
+class PresetImplementation implements Preset {
+  private registry: Map<Token<any>, Provider<any>>;
+
+  constructor(defaults?: Iterable<PresetEntry>) {
+    this.registry = new Map<Token<any>, Provider<any>>(defaults);
+  }
+
+  set<T>(token: Token<T>, provider: Provider<T>): this {
+    this.registry.set(token, provider);
+    return this;
+  }
+
+  apply(app: Application): void {
+    for (const [token, provider] of this.registry) {
+      app.bind(token).toProvider(provider);
+    }
+  }
+}
+
+/**
+ * Возвращает новый "preset" для DI-приложения - набор предустановленных компонентов которые можно переопределять.
+ * @param defaults Предустановленные зависимости.
+ * @return Preset.
+ */
+export function createPreset(defaults?: PresetEntry[]): Preset {
+  return new PresetImplementation(defaults);
+}

package/src/di/token.ts

@@ -0,0 +1,41 @@
+import { Token } from './types';
+
+/**
+ * Реализация токена.
+ */
+class TokenImplementation<T = never> implements Token<T> {
+  readonly _key: symbol;
+
+  /**
+   * Конструктор.
+   * @param name Имя для отладки.
+   */
+  constructor(name?: string) {
+    this._key = Symbol(name);
+  }
+
+  /**
+   * Получив реестр вернет из него нужный компонент.
+   * @param registry Реестр.
+   * @return Компонент.
+   */
+  _resolve(registry: Map<symbol, any>): T {
+    return registry.get(this._key);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  toString(): string {
+    return `Token(${this._key.description ?? 'unknown'})`;
+  }
+}
+
+/**
+ * Возвращает новый токен.
+ * @param name Имя токена для отладки в случае ошибок.
+ * @return Токен.
+ */
+export function createToken<T = never>(name?: string): Token<T> {
+  return new TokenImplementation(name);
+}

package/src/di/types.ts

@@ -0,0 +1,105 @@
+/**
+ * Токен - ключ который можно использовать для привязки реализации и получения компонента из контейнера.
+ * За токеном можно закрепить интерфейс. В дальнейшем это поможет нне ошибиться при привязке реализации.
+ */
+export interface Token<T> {
+  readonly _key: symbol;
+  readonly _resolve: (registry: Map<symbol, any>) => T;
+}
+
+/**
+ * Резолвер. Получив токен вернет реализацию интерфейса, который за ним закреплён.
+ */
+export interface Resolve {
+  <T>(token: Token<T>): T;
+}
+
+/**
+ * Провайдер - функция, которая, получив резолвер, должна вернуть реализацию интерфейса.
+ */
+export interface Provider<T> {
+  (resolve: Resolve): T;
+}
+
+/**
+ * DI-контейнер.
+ * Позволяет зарегистрировать за токеном компонент в виде функции-провайдера и в дальнейшем получить его по токену.
+ */
+export interface Container {
+  /**
+   * Регистрирует провайдер.
+   */
+  set: <T = never>(token: Token<T>, provider: Provider<T>) => void;
+
+  get: Resolve;
+}
+
+/**
+ * Интерфейс привязки компонента к токену.
+ */
+export interface Binding<T> {
+  /**
+   * Привязывает к токену конкретное "статическое" значение.
+   */
+  toValue: (value: T) => void;
+
+  /**
+   * Привязывает к токену функцию-провайдер.
+   */
+  toProvider: (provider: Provider<T>) => void;
+}
+
+/** @internal */
+export type ExtractType<T extends readonly Token<any>[]> = {
+  [index in keyof T]: T[index] extends T[number] ? ReturnType<T[index]['_resolve']> : never;
+};
+
+/**
+ * DI-Приложение. Расширенная версия DI-контейнера.
+ * Позволяет применять пресеты, задавать "родительские" приложения, вызывать callback-функции с инъекцией компонентов.
+ */
+export interface Application {
+  /**
+   * Добавляет пресет к приложению. Пресет будет применен в момент первой попытки получить компонент или вызвать функцию.
+   */
+  preset(preset: Preset): void;
+
+  /**
+   * Получив приложение, пометит его как "родительское".
+   * При попытке достать компонент, в случае если его нет в текущем приложении, будет произведена попытка найти его в "родительском".
+   */
+  attach(parent: Application): void;
+
+  /**
+   * Аналог метода set у Container. Получив токен вернет интерфейс привязки реализации.
+   * @param token Токен.
+   */
+  bind<T>(token: Token<T>): Binding<T>;
+
+  /**
+   * Получив токен, вернет его реализацию если она была зарегистрирована.
+   * @param token Токен.
+   */
+  get<T>(token: Token<T>): T;
+
+  /**
+   * Получив список токенов и callback-функцию, вызовет функцию с компонентами по соответствующим токенам.
+   */
+  invoke<Tokens extends readonly Token<any>[]>(
+    tokens: [...Tokens],
+    fn: (...args: ExtractType<Tokens>) => void,
+  ): void;
+}
+
+/**
+ * Пресет - набор провайдеров (с возможностью их добавлять/переопределять) который можно применить к DI-приложению.
+ */
+export interface Preset {
+  /** Добавляет провайдер в пресет. */
+  set: <T>(token: Token<T>, provider: Provider<T>) => this;
+
+  /** Применяет пресет к переданному приложению. */
+  apply: (app: Application) => void;
+
+  // @todo preventExtensions()
+}

package/src/http/__test__/errors.test.ts

@@ -0,0 +1,35 @@
+import { StatusError, ResponseError } from '../errors';
+
+describe('StatusError', () => {
+  it('should have some properties', () => {
+    const response = new Response('Good', { status: 200 });
+    const error = new StatusError(response);
+
+    expect(error.name).toBe('StatusError');
+    expect(error.message).toBe(`HTTP Request failed with status ${200}`);
+    expect(error.response).toBe(response);
+  });
+
+  it('static is() should works correctly', () => {
+    expect(StatusError.is(new StatusError(new Response('error', { status: 400 })))).toBe(true);
+    expect(StatusError.is(123)).toBe(false);
+  });
+});
+
+describe('ResponseError', () => {
+  it('should have some properties', () => {
+    const error = new ResponseError('Hello!', 400);
+
+    expect(error.name).toBe('ResponseError');
+    expect(error.message).toBe('Hello!');
+    expect(error.statusCode).toBe(400);
+  });
+
+  it('should handle status missing', () => {
+    const error = new ResponseError('Hello!');
+
+    expect(error.name).toBe('ResponseError');
+    expect(error.message).toBe('Hello!');
+    expect(error.statusCode).toBe(500);
+  });
+});

package/src/http/errors.ts

@@ -0,0 +1,42 @@
+/**
+ * Ошибка валидации статуса ответа.
+ * @todo Переименовать в HttpStatusValidationError?
+ */
+export class StatusError extends Error {
+  readonly response: Response;
+
+  /**
+   * @param response Ответ.
+   */
+  constructor(response: Response) {
+    super(`HTTP Request failed with status ${response.status}`);
+    this.name = 'StatusError';
+    this.response = response;
+  }
+
+  /**
+   * Определяет, является ли переданное значение ошибкой валидации статуса.
+   * @param value Значение.
+   * @return Результат.
+   */
+  static is(value: unknown): value is StatusError {
+    return (value as any)?.name === 'StatusError';
+  }
+}
+
+/**
+ * Ошибка в процессе формирования ответа.
+ */
+export class ResponseError extends Error {
+  statusCode: number;
+
+  /**
+   * @param message Сообщение.
+   * @param statusCode Код ответа.
+   */
+  constructor(message: string, statusCode = 500) {
+    super(message);
+    this.name = 'ResponseError';
+    this.statusCode = statusCode;
+  }
+}

package/src/http/index.ts

@@ -0,0 +1,14 @@
+export type {
+  Handler,
+  Enhancer,
+  Middleware,
+  LogData,
+  DoneLogData,
+  FailLogData,
+  LogHandler,
+  LogHandlerFactory,
+  CookieStore,
+} from './types';
+export { configureFetch, applyMiddleware, createCookieStore } from '@krutoo/fetch-tools';
+export { log, cookie, defaultHeaders, validateStatus } from '@krutoo/fetch-tools/middleware';
+export { StatusError, ResponseError } from './errors';

package/src/http/types.ts

@@ -0,0 +1,8 @@
+export type { Handler, Enhancer, Middleware, CookieStore } from '@krutoo/fetch-tools';
+export type {
+  LogData,
+  DoneLogData,
+  FailLogData,
+  LogHandler,
+  LogHandlerFactory,
+} from '@krutoo/fetch-tools/middleware';

package/src/log/__test__/errors.test.ts

@@ -0,0 +1,13 @@
+import { DetailedError, Breadcrumb } from '..';
+
+describe('DetailedError', () => {
+  it('name should be just "Error"', () => {
+    expect(new DetailedError('hello, world!').name).toBe('Error');
+  });
+});
+
+describe('Breadcrumb', () => {
+  it('name should be just "Error"', () => {
+    expect(new Breadcrumb({ message: 'some text' }).data).toEqual({ message: 'some text' });
+  });
+});

package/src/log/__test__/logger.test.ts

@@ -0,0 +1,24 @@
+import { createLogger } from '..';
+
+describe('createLogger', () => {
+  it('should return logger', () => {
+    const events: any[] = [];
+    const logger = createLogger();
+
+    logger.subscribe(event => events.push(event));
+
+    logger.log('a');
+    logger.info('b');
+    logger.error('c');
+    logger.warn('d');
+    logger.debug('e');
+
+    expect(events).toEqual([
+      { type: 'log', data: 'a' },
+      { type: 'info', data: 'b' },
+      { type: 'error', data: 'c' },
+      { type: 'warn', data: 'd' },
+      { type: 'debug', data: 'e' },
+    ]);
+  });
+});

package/src/log/errors.ts

@@ -0,0 +1,33 @@
+import { ErrorDetails, BreadcrumbDetails } from './types';
+
+/**
+ * Ошибка с данными.
+ */
+export class DetailedError extends Error {
+  data: ErrorDetails;
+
+  /**
+   * @param message Сообщение.
+   * @param data Данные.
+   */
+  constructor(message?: string, data: ErrorDetails = {}) {
+    super(message);
+    this.data = data;
+  }
+}
+
+/**
+ * Хлебная крошка.
+ */
+export class Breadcrumb {
+  type: string;
+  data: BreadcrumbDetails;
+
+  /**
+   * @param data Данные.
+   */
+  constructor(data: BreadcrumbDetails) {
+    this.type = 'breadcrumb';
+    this.data = data;
+  }
+}

package/src/log/handler/pino.ts

@@ -0,0 +1,27 @@
+import type { LogHandler } from '../types';
+import type pino from 'pino';
+
+/**
+ * Возвращает новый handler для logger'а для вывода событий в терминал.
+ * @param pinoInstance Конфиг.
+ * @return Handler.
+ */
+export function createPinoHandler(pinoInstance: pino.Logger): LogHandler {
+  return function pinoHandler(event) {
+    switch (event.type) {
+      case 'log':
+      case 'info':
+        pinoInstance.info(event.data);
+        break;
+      case 'warn':
+        pinoInstance.warn(event.data);
+        break;
+      case 'debug':
+        pinoInstance.debug(event.data);
+        break;
+      case 'error':
+        pinoInstance.error(event.data);
+        break;
+    }
+  };
+}

package/src/log/handler/sentry.ts

@@ -0,0 +1,57 @@
+import type { LogHandler } from '../types';
+import type { Hub } from '@sentry/types';
+import { Breadcrumb, DetailedError } from '../../log';
+
+/**
+ * Возвращает новый handler для logger'а для отправки событий в Sentry.
+ * @param hubInit Sentry Hub или функция которая его вернёт.
+ * @return Handler.
+ */
+export function createSentryHandler(hubInit: Hub | (() => Hub)): LogHandler {
+  const getHub = typeof hubInit === 'function' ? hubInit : () => hubInit;
+
+  return event => {
+    // ВАЖНО: каждый входящий http-запрос должен иметь свой собственный hub
+    // подробности: https://github.com/getsentry/sentry-javascript/discussions/5648
+    // поэтому если передана функция - вызываем каждый раз (внутри обработчика)
+    const hub = getHub();
+
+    // error
+    if (event.type === 'error') {
+      const error = event.data;
+
+      if (error instanceof DetailedError) {
+        const { level, context, extra } = error.data;
+
+        hub.withScope(scope => {
+          if (level) {
+            scope.setLevel(level);
+          }
+
+          if (context) {
+            const list = Array.isArray(context) ? context : [context];
+
+            for (const item of list) {
+              scope.setContext(item.key, item.data);
+            }
+          }
+
+          if (extra) {
+            scope.setExtra(extra.key, extra.data);
+          }
+
+          hub.captureException(error);
+        });
+      } else {
+        hub.captureException(error);
+      }
+    }
+
+    // breadcrumb
+    if (event.data instanceof Breadcrumb) {
+      const breadcrumb = event.data.data;
+
+      hub.addBreadcrumb(breadcrumb);
+    }
+  };
+}

package/src/log/index.ts

@@ -0,0 +1,12 @@
+export type {
+  Logger,
+  LogEvent,
+  LogLevel,
+  LogHandler,
+  ErrorDetails,
+  BreadcrumbDetails,
+  ContextData,
+} from './types';
+
+export { createLogger } from './logger';
+export { DetailedError, Breadcrumb } from './errors';

package/src/log/logger.ts

@@ -0,0 +1,30 @@
+import type { Logger, LogEvent, LogLevel, LogHandler } from './types';
+
+/**
+ * Возвращает новый logger - объект для журналирования событий подобно console.
+ * @return Logger.
+ */
+export function createLogger(): Logger {
+  const handlers: LogHandler[] = [];
+
+  // eslint-disable-next-line require-jsdoc, jsdoc/require-jsdoc
+  const createMethod = (type: LogLevel) => (data: any) => {
+    const event: LogEvent = { type, data };
+
+    for (const handler of handlers) {
+      handler(event);
+    }
+  };
+
+  return {
+    log: createMethod('log'),
+    info: createMethod('info'),
+    warn: createMethod('warn'),
+    error: createMethod('error'),
+    debug: createMethod('debug'),
+
+    subscribe: handler => {
+      handlers.push(handler);
+    },
+  };
+}

package/src/log/types.ts

@@ -0,0 +1,76 @@
+import type { SeverityLevel, Context, Extra, Breadcrumb } from '@sentry/types';
+
+/**
+ * Тип события.
+ */
+export type LogLevel = 'error' | 'log' | 'info' | 'warn' | 'debug';
+
+/**
+ * Интерфейс события.
+ */
+export interface LogEvent {
+  type: LogLevel;
+  data: unknown;
+}
+
+/**
+ * Интерфейс функции-обработчика события.
+ */
+export interface LogHandler {
+  (event: LogEvent): void;
+}
+
+/**
+ * Logger.
+ * Поддерживает наиболее распространенные события жизненного цикла программы.
+ */
+export interface Logger {
+  error(data: any): void;
+  log(data: any): void;
+  info(data: any): void;
+  warn(data: any): void;
+  debug(data: any): void;
+
+  // @todo вынести в интерфейс SubscribableLogger?
+  subscribe(handler: LogHandler): void;
+}
+
+/**
+ * Контекст ошибки.
+ */
+export interface ContextData {
+  key: string;
+  data: Context | null;
+}
+
+/**
+ * Детали ошибки.
+ */
+export interface ErrorDetails {
+  level?: SeverityLevel;
+
+  context?: ContextData | ContextData[];
+
+  extra?: {
+    key: string;
+    data: Extra | null;
+  };
+}
+
+/**
+ * Детали хлебной крошки.
+ */
+export type BreadcrumbDetails = Breadcrumb;
+
+/**
+ * Структура данных, которую необходимо выводить в терминал по соглашению внутри компании.
+ * @todo Убрать в preset'ы.
+ */
+export interface ConventionalFluentInfo {
+  version: string;
+  latency: number;
+  method: string;
+  remote_ip: string;
+  route: string;
+  status: number;
+}

package/src/preset/isomorphic/constants.ts

@@ -0,0 +1,7 @@
+/**
+ * События в процессе ответа на запрос.
+ */
+export const RESPONSE_EVENT_TYPE = {
+  renderStart: Symbol('render:start'),
+  renderFinish: Symbol('render:finish'),
+} as const;

package/src/preset/isomorphic/index.ts

@@ -0,0 +1,7 @@
+export type {
+  PresetTuner,
+  KnownHttpApiKey,
+  StrictMap,
+  PageAssets,
+  ConventionalJson,
+} from './types';