Настройка TypeScript

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

Day.js распространяется с встроенной поддержкой TypeScript, поэтому отдельные типы из @types не требуются. Базовая установка выполняется стандартным способом через пакетный менеджер:

npm install dayjs

или

yarn add dayjs

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

npm install dayjs-plugin-utc
npm install dayjs-plugin-relativeTime

Встроенная поддержка типизации

Библиотека включает собственные TypeScript-описания, которые поставляются вместе с основным пакетом. Это обеспечивает:

  • строгую типизацию объектов Dayjs
  • корректную работу автодополнения в редакторах
  • проверку цепочек методов на уровне компиляции

Основной тип времени представлен интерфейсом Dayjs, который используется во всех операциях:

import dayjs, { Dayjs } from "dayjs";

const date: Dayjs = dayjs();

Каждый вызов dayjs() возвращает объект этого типа, обеспечивая согласованность API.

Конфигурация TypeScript-проекта

Корректная работа Day.js в TypeScript зависит от настроек компилятора. Основные параметры tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2019",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Ключевые моменты:

  • esModuleInterop обеспечивает корректный импорт CommonJS-модулей
  • strict активирует строгую типизацию, важную для цепочек Day.js
  • skipLibCheck снижает вероятность конфликтов с типами зависимостей

Импорт Day.js в TypeScript

Поддерживаются два основных стиля импорта:

import dayjs from "dayjs";

и альтернативный вариант для проектов с настройками CommonJS:

const dayjs = require("dayjs");

В типизированной среде предпочтение отдаётся ES-модулям, так как они обеспечивают более точную работу автодополнения и tree-shaking.

Тип Dayjs и базовые операции

Основной тип Dayjs описывает неизменяемый объект даты. Любая операция возвращает новый экземпляр, сохраняя тип:

import dayjs, { Dayjs } from "dayjs";

const start: Dayjs = dayjs("2026-01-01");
const end: Dayjs = start.add(7, "day");

Типизация методов гарантирует:

  • контроль допустимых единиц времени (day, month, year и т.д.)
  • корректность аргументов функций
  • предсказуемость возвращаемых значений

Пример работы с форматированием:

const formatted: string = dayjs().format("YYYY-MM-DD");

Метод format всегда возвращает строку, что фиксируется типами.

Плагины и расширение типов

Day.js использует систему плагинов, которая влияет на API объекта Dayjs. После подключения плагина типы должны быть расширены вручную или через встроенные декларации.

Пример подключения плагина:

import dayjs from "dayjs";
import utc from "dayjs/plugin/utc";

dayjs.extend(utc);

После подключения добавляются новые методы:

const d = dayjs().utc();

Module augmentation для расширения интерфейса

При использовании TypeScript расширение интерфейса Dayjs выполняется через module augmentation.

import "dayjs";

declare module "dayjs" {
  interface Dayjs {
    customMethod(): string;
  }
}

Реализация метода:

import dayjs from "dayjs";

(dayjs.prototype as any).customMethod = function () {
  return "value";
};

После расширения метод становится доступен в типизированной среде:

const result = dayjs().customMethod();

Типизация пользовательских форматов и расширений

При работе с кастомными форматами часто используется строгая типизация строковых литералов:

type DateFormat = "YYYY-MM-DD" | "DD.MM.YYYY";

function formatDate(date: Dayjs, format: DateFormat): string {
  return date.format(format);
}

Это ограничивает набор допустимых форматов и снижает вероятность ошибок.

Типы плагинов и их интеграция

Некоторые плагины добавляют дополнительные параметры к функциям dayjs. В TypeScript это учитывается через расширение типов функций и интерфейсов.

Пример с относительным временем:

import dayjs from "dayjs";
import relativeTime from "dayjs/plugin/relativeTime";

dayjs.extend(relativeTime);

const value: string = dayjs().from(dayjs("2020-01-01"));

Тип возвращаемого значения фиксирован как string, что отражает поведение API.

Обработка null и invalid значений

Day.js возвращает специальный объект для некорректных дат. В TypeScript это учитывается через дополнительные проверки:

const date = dayjs("invalid");

const isValid: boolean = date.isValid();

Метод isValid используется как основной механизм проверки корректности даты перед дальнейшими операциями.

Совместимость с строгим режимом TypeScript

В режиме strict поведение Day.js остаётся предсказуемым благодаря явной типизации:

  • отсутствуют неявные any
  • методы строго проверяют входные параметры
  • цепочки вызовов сохраняют тип Dayjs

Пример безопасной цепочки:

const result: string = dayjs()
  .add(2, "day")
  .set("month", 5)
  .format("YYYY-MM-DD");

Каждый этап сохраняет корректную типизацию до финального преобразования в строку.

Оглавление