Использование в Node.js

Библиотека date-fns устанавливается как обычная npm-зависимость и используется напрямую в серверной среде Node.js без дополнительных настроек рантайма.

Установка:

npm install date-fns

или при использовании yarn:

yarn add date-fns

После установки доступ к функциям осуществляется через require (CommonJS) либо через import (ES Modules), в зависимости от конфигурации проекта.

Использование CommonJS (require)

Node.js исторически использует CommonJS-модули, поэтому наиболее совместимый способ подключения выглядит следующим образом:

const { format, addDays, subMonths } = require('date-fns');

const now = new Date();

console.log(format(now, 'yyyy-MM-dd'));
console.log(format(addDays(now, 7), 'yyyy-MM-dd'));
console.log(format(subMonths(now, 2), 'yyyy-MM-dd'));

Особенность date-fns заключается в том, что каждая функция импортируется отдельно, что позволяет избегать загрузки лишнего кода.

Использование ES Modules (import)

При использовании современных версий Node.js (14+ с включённым "type": "module" в package.json) доступен синтаксис ES Modules:

import { format, addDays } from 'date-fns';

const date = new Date();

const result = format(addDays(date, 3), 'dd.MM.yyyy');
console.log(result);

Пример package.json для включения ESM:

{
  "type": "module"
}

Особенности работы в серверной среде

Node.js не имеет ограничений браузера, связанных с часовыми поясами пользовательской системы, однако поведение Date остаётся привязанным к системному времени сервера.

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

  • все операции выполняются в локальной временной зоне сервера;
  • Date является изменяемым объектом JavaScript, но функции date-fns всегда возвращают новый экземпляр;
  • библиотека не мутирует исходные даты.

Пример:

import { addHours } from 'date-fns';

const original = new Date();
const modified = addHours(original, 5);

console.log(original === modified); // false

Форматирование дат в Node.js приложениях

date-fns часто используется в серверных API для подготовки данных перед отправкой клиенту.

import { format } from 'date-fns';

export function getUserResponse(user) {
  return {
    id: user.id,
    createdAt: format(user.createdAt, 'yyyy-MM-dd HH:mm:ss'),
  };
}

Поддерживается широкий набор токенов форматирования:

  • yyyy — год
  • MM — месяц
  • dd — день
  • HH — часы (24-часовой формат)
  • mm — минуты
  • ss — секунды

Парсинг и создание дат

В Node.js часто требуется преобразование строк из базы данных или внешних API в объекты Date.

import { parse, isValid } from 'date-fns';

const dateString = '2026-05-22 14:30:00';

const parsed = parse(dateString, 'yyyy-MM-dd HH:mm:ss', new Date());

if (isValid(parsed)) {
  console.log(parsed.toISOString());
}

Функция isValid используется для проверки корректности результата парсинга.

Работа с интервалами времени

Node.js часто используется для серверной логики, где важны вычисления временных интервалов: дедлайны, TTL, расписания задач.

import { differenceInDays, addMinutes } from 'date-fns';

const start = new Date('2026-01-01');
const end = new Date('2026-01-20');

console.log(differenceInDays(end, start)); // 19

const timeout = addMinutes(new Date(), 30);
console.log(timeout);

Использование в API и backend-сервисах

Типичный сценарий — обработка данных перед отправкой через REST API или GraphQL.

import { formatISO, subDays } from 'date-fns';

export function buildReport() {
  const endDate = new Date();
  const startDate = subDays(endDate, 7);

  return {
    start: formatISO(startDate),
    end: formatISO(endDate),
  };
}

Формат formatISO удобен для стандартизации данных между сервисами.

Интеграция с Express.js

В серверных приложениях на Express date-fns используется для логирования и обработки временных параметров запросов.

import express from 'express';
import { format } from 'date-fns';

const app = express();

app.get('/time', (req, res) => {
  res.json({
    serverTime: format(new Date(), 'HH:mm:ss'),
  });
});

app.listen(3000);

Использование в cron-задачах и планировщиках

Node.js часто применяется для фоновых задач. date-fns помогает вычислять расписания.

import { addDays, isBefore } from 'date-fns';

const nextRun = addDays(new Date(), 1);

if (isBefore(new Date(), nextRun)) {
  console.log('Задача ещё не должна выполняться');
}

Совместимость с TypeScript в Node.js

date-fns написана на TypeScript и предоставляет строгую типизацию без дополнительных деклараций.

import { format, addWeeks } from 'date-fns';

const date: Date = new Date();

const result: string = format(addWeeks(date, 2), 'yyyy-MM-dd');

Типы автоматически выводятся, что упрощает использование в серверных приложениях.

Особенности работы с ESM и CJS в одном проекте

В смешанных проектах Node.js возможны случаи, когда часть кода использует CommonJS, а часть ES Modules.

// CommonJS файл
const { format } = require('date-fns');

module.exports.getDate = function () {
  return format(new Date(), 'yyyy-MM-dd');
};
// ESM файл
import { format } from 'date-fns';

export function getDate() {
  return format(new Date(), 'yyyy-MM-dd');
}

Node.js корректно обрабатывает оба подхода при правильной конфигурации.

Производительность и модульность в Node.js

Архитектура date-fns ориентирована на tree-shaking и минимизацию размера сборки. В серверной среде это влияет на:

  • уменьшение времени загрузки модулей;
  • снижение потребления памяти;
  • отсутствие лишнего функционала в рантайме.

Пример точечного импорта:

import format from 'date-fns/format';
import addDays from 'date-fns/addDays';

Такой подход может быть полезен в высоконагруженных сервисах.

Работа с часовыми поясами через date-fns-tz

В Node.js часто требуется явная работа с временными зонами. Для этого используется дополнительный пакет:

npm install date-fns-tz

Пример:

import { format } from 'date-fns-tz';

const date = new Date();
const timeZone = 'Asia/Almaty';

const result = format(date, 'yyyy-MM-dd HH:mm:ssXXX', { timeZone });

console.log(result);

Этот подход позволяет корректно обрабатывать международные данные в backend-системах.

Оглавление