Установка типов

Общая модель типизации Globalize

Библиотека Globalize предоставляет функциональность интернационализации на основе данных Unicode CLDR. При использовании в TypeScript-проектах ключевым аспектом становится наличие корректных типов, описывающих API форматирования чисел, дат, сообщений и единиц измерения.

Типизация может быть реализована тремя основными способами:

  • встроенные типы (если поддерживаются конкретной версией пакета);
  • внешние типы через DefinitelyTyped;
  • собственные декларации .d.ts при нестандартной интеграции.

Выбор подхода зависит от версии библиотеки, способа сборки и конфигурации TypeScript.

Установка пакета Globalize

Базовая установка выполняется через npm:

npm install globalize

Дополнительно почти всегда требуются CLDR-данные, без которых библиотека не выполняет форматирование:

npm install cldr-data

В современных сборках часто используется также загрузка CLDR через bundler или отдельные JSON-файлы.

Установка типов через DefinitelyTyped

Если используемая версия Globalize не содержит встроенных типов, применяется пакет типов из DefinitelyTyped:

npm install --save-dev @types/globalize

После установки TypeScript автоматически подхватывает декларации, если соблюдены стандартные правила разрешения модулей.

Структурно пакет типов описывает:

  • методы форматирования (number, date, currency);
  • локализационные API;
  • конфигурационные функции;
  • инициализацию CLDR.

Проверка доступности типов

TypeScript резолвит типы по следующим правилам:

  1. наличие node_modules/@types/globalize;
  2. наличие встроенных .d.ts внутри пакета globalize;
  3. пользовательские декларации в проекте.

Если типы не определяются автоматически, проверяется конфигурация tsconfig.json.

Конфигурация TypeScript

Ключевые параметры, влияющие на корректную установку типов:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true
  }
}

moduleResolution

node или bundler-режим определяет стратегию поиска .d.ts файлов. Для Globalize чаще используется классический node.

skipLibCheck

Опция снижает риск конфликтов типов между @types/globalize и другими библиотеками интернационализации.

Способы импорта и влияние на типы

Globalize поддерживает несколько вариантов импорта, и каждый влияет на типизацию.

CommonJS

const Globalize = require("globalize");

Типы подключаются через @types/globalize автоматически, если пакет установлен.

ES Modules

import Globalize from "globalize";

или

import * as Globalize from "globalize";

Корректный вариант зависит от конфигурации esModuleInterop. При включённой опции предпочтителен первый вариант.

Подключение CLDR и типы

Типизация Globalize не ограничивается самим API. Существенное значение имеет структура CLDR-данных.

import Globalize from "globalize";
import likelySubtags from "cldr-data/supplemental/likelySubtags.json";
import numbers from "cldr-data/main/en/numbers.json";

Типы не описывают содержимое CLDR-файлов полностью, так как они представляют собой большие JSON-структуры. Вместо этого описываются только методы загрузки и интерфейсы работы с ними.

Типизация основных сущностей API

Форматирование чисел

Типы описывают перегрузки метода:

Globalize.numberFormatter(options?: object): (value: number) => string;

Результат — функция форматирования, принимающая число и возвращающая строку.

Форматирование дат

Globalize.dateFormatter(options?: object): (value: Date) => string;

Типы учитывают:

  • входной тип Date;
  • опциональные параметры формата;
  • локаль, заданную через Globalize(locale).

Форматирование валют

Globalize.currencyFormatter(currency: string, options?: object): (value: number) => string;

Типизация фиксирует обязательный параметр валюты и возвращаемую функцию форматирования.

Расширение типов при отсутствии поддержки

В ряде случаев @types/globalize может быть неполным или несовместимым с конкретной версией библиотеки. Тогда используется модульное расширение.

Создаётся файл деклараций:

// globalize.d.ts
declare module "globalize" {
  const Globalize: any;
  export default Globalize;
}

Такой подход отключает строгую типизацию, но устраняет ошибки компиляции.

Интеграция собственных типов

При необходимости точной типизации API создаются расширенные интерфейсы:

interface NumberFormatterOptions {
  minimumFractionDigits?: number;
  maximumFractionDigits?: number;
}

type NumberFormatter = (value: number) => string;

И затем происходит привязка к API Globalize через декларации:

declare module "globalize" {
  interface GlobalizeStatic {
    numberFormatter(options?: NumberFormatterOptions): NumberFormatter;
  }
}

Конфликты типов и их причины

На практике встречаются следующие проблемы:

  • несовместимость версий globalize и @types/globalize;
  • дублирование деклараций;
  • пересечение с другими библиотеками i18n;
  • несовпадение module resolution (ESM vs CJS).

Приоритет разрешения типов

TypeScript использует следующий порядок:

  1. локальные .d.ts;
  2. node_modules/@types;
  3. встроенные типы пакета;
  4. fallback на any.

Это влияет на поведение при конфликтующих декларациях.

Проверка корректности типизации через компиляцию

Типизация считается корректной, если:

  • отсутствуют ошибки TS2307 (module not found);
  • отсутствуют ошибки TS7006 (implicit any) при строгом режиме;
  • корректно выводятся типы возвращаемых функций форматирования;
  • IDE показывает автодополнение методов Globalize.

Особенности типизации при tree-shaking

В сборках с Vite, Webpack или Rollup типы не влияют на runtime, но влияют на:

  • корректность импортов;
  • возможность удаления неиспользуемых функций;
  • точность определения API.

Globalize как модульная библиотека требует аккуратного импорта подмодулей, что отражается в .d.ts структурах.

Разделение типов по функциональным модулям

Типы часто логически разделяются на группы:

  • числа;
  • даты и время;
  • сообщения;
  • единицы измерения;
  • валюта.

Это соответствует архитектуре самой библиотеки и помогает поддерживать расширяемость деклараций.

Согласование версий CLDR и типов

Хотя типы не описывают данные CLDR, версия CLDR влияет на:

  • доступные локали;
  • структуру форматов;
  • поведение форматтеров.

Несоответствие версий может приводить к расхождению ожиданий типов и фактического результата выполнения.

Оглавление