Обратная совместимость

Поддержка обратной совместимости в mo.js основана на принципе минимизации разрушительных изменений публичного API и сохранения предсказуемого поведения анимационных сущностей при обновлениях версии. Библиотека изначально проектировалась как инструмент декларативной анимации, где ключевым элементом является стабильность описаний tween- и timeline-структур, а не частота изменений интерфейса.

Стабильность публичного API

Основные сущности библиотеки — Shape, Burst, Timeline, Tween — сохраняют консистентную модель конфигурации через объектные литералы. Это позволяет старым конфигурациям продолжать работать даже при расширении функциональности.

Ключевые принципы:

  • сохранение структуры параметров (duration, delay, easing, repeat)
  • добавление новых опций без изменения поведения существующих
  • отказ от переименования базовых полей конфигурации
  • расширение функциональности через вложенные опции, а не замену корневых

Пример устойчивой модели:

const anim = new mojs.Tween({
  duration: 1200,
  delay: 200,
  easing: 'ease.out',
  onComplete() {
    console.log('done');
  }
});

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

Наследование и расширение конфигураций

Важный механизм обратной совместимости связан с тем, как библиотека обрабатывает наследование параметров. Объекты анимации не мутируют входные конфигурации, а создают внутренние копии с нормализованными значениями.

Это позволяет:

  • использовать старые конфигурации без адаптации
  • переиспользовать пресеты из ранних версий
  • комбинировать старые и новые параметры в одном объекте

Особое внимание уделяется объединению объектов:

const base = {
  duration: 1000,
  easing: 'linear'
};

const extended = {
  ...base,
  duration: 1500,
  stroke: 'red'
};

Даже если новые поля добавляются в более поздних версиях, механизм merge-логики не ломает поведение базовых параметров.

Версионирование и эволюция API

Подход к версионированию в библиотеке ориентирован на семантическую модель:

  • патч-обновления не изменяют API
  • минорные обновления добавляют новые возможности
  • мажорные версии допускают переработку внутренних механизмов, но стараются сохранить интерфейс совместимым через адаптеры

При изменениях поведения анимационного ядра используется стратегия:

  • сохранение старых параметров как алиасов
  • внутренний трансформер конфигураций
  • поддержка устаревших значений easing и presets

Устаревшие параметры и алиасинг

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

Примеры подхода:

  • angle может интерпретироваться как часть трансформации rotate
  • старые easing-строки преобразуются в новые функции интерполяции
  • deprecated-поля логически маппятся на актуальные внутренние свойства

Логика обработки конфигурации часто включает слой нормализации:

function normalize(config) {
  return {
    ...config,
    easing: mapEasing(config.easing || 'linear')
  };
}

Совместимость с браузерным окружением

Исторически библиотека опирается на requestAnimationFrame, CSS transforms и SVG-морфинг. Для старых окружений используется деградация поведения:

  • fallback на setTimeout при отсутствии requestAnimationFrame
  • упрощённая интерполяция без субпиксельной точности
  • отключение некоторых визуальных эффектов при отсутствии поддержки SVG-анимаций

Поддержка старых браузеров достигается не через дублирование логики, а через:

  • feature detection вместо version detection
  • graceful degradation вместо polyfill-heavy подхода
  • отказ от критической зависимости от современных API

Совместимость с модулями и системами сборки

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

  • UMD (универсальный формат для браузера и Node.js)
  • ES Modules (современные сборщики)
  • IIFE (ранние версии для прямого подключения)

Сохранение обратной совместимости достигается за счёт:

  • параллельной публикации нескольких сборок
  • неизменности публичного entry point API
  • отсутствия обязательных breaking imports

Пример использования в разных окружениях:

// ES Modules
import mojs from 'mo-js';

// UMD
const mojs = window.mojs;

Совместимость анимационных таймлайнов

Timeline является наиболее чувствительной частью системы, так как он управляет синхронизацией нескольких tween-объектов.

Старые таймлайны продолжают работать благодаря следующим принципам:

  • единый формат времени (миллисекунды)
  • неизменная логика delay chaining
  • обратная совместимость структуры child-анимаций

Даже при изменениях внутреннего планировщика времени сохраняется детерминированность:

const tl = new mojs.Timeline();

tl.add([
  new mojs.Tween({ duration: 300 }),
  new mojs.Tween({ delay: 100, duration: 500 })
]);

Обработка старых easing-функций

Система easing является одним из ключевых элементов совместимости. Ранние версии использовали строковые идентификаторы, позднее были добавлены функции и кастомные кривые.

Для поддержки старых проектов реализуется слой трансляции:

  • строковые значения переводятся в функции интерполяции
  • неизвестные easing заменяются на безопасный fallback (linear)
  • кастомные кривые нормализуются в единый формат cubic-bezier

Совместимость визуальных примитивов

Элементы вроде Shape и Burst имеют долгий жизненный цикл API. Их параметры сохраняются в стабильной форме:

  • radius
  • scale
  • opacity
  • strokeWidth

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

Миграционная стратегия между версиями

При изменениях внутренней архитектуры применяется постепенная миграция:

  • добавление новых API параллельно со старыми
  • маркировка устаревших параметров через soft-deprecation
  • сохранение обратного поведения на протяжении нескольких релизов
  • внутренние адаптеры между слоями анимации

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

Оглавление