Pipe(), а затем() и реальность в jQuery 1.8

Обновление: этот вопрос сейчас устарел, поскольку документация является точной и актуальной.

Я немного разбираюсь в jQuery Deferred/Promise API, и я очень смущен различием между pipe() и then() философски и в документации jQuery. Я обнаружил, что pipe() является просто псевдонимом для then() по jQuery 1.8.

Из источника jQuery:

// Keep pipe for back-compat
promise.pipe = promise.then;

Однако документация полностью отличается для pipe() и then(), поскольку они предположительно имеют совершенно разные виды использования.

Описание для then():

Описание: Добавить обработчики, которые будут вызываться, когда объект Отложенного разрешен или отклонен.

Описание для pipe():

Описание: Утилита для фильтрации и/или цепочки Отложенные.

Я понимаю, что исторически они имели несколько иное поведение, но во всей документации для протокола или для, он даже не говорит, что эти две функции выполняют то же самое сейчас.

Итак, вот мой вопрос из двух частей:

  • Почему документация между pipe() и then() отличается от jQuery 1.8?
  • Почему then() возвращает новый отложенный объект? Это поведение полностью недокументировано (docs просто говорят, что он возвращает Отложенный, а не новый). Я понимаю, что это имеет смысл при этом (а именно, реализовать все функции pipe()), но философски, почему это так? Это необязательно, учитывая описание then() (для прикрепления обработчиков).

Обновление

Я даже догадаюсь, что документы then() вводят в заблуждение и неточно:

Поскольку отложенный. then возвращает отложенный объект, к нему могут быть привязаны другие методы отложенного объекта, включая дополнительные методы .then().

Возможно, это просто расплывчато, но это означает, что он возвращает отложенный объект, который вы назвали then() on для цепочки, когда на самом деле он возвращает совершенно новый объект....

Обновить снова

Кажется, что документация просто ошибочна/устарела! Так что ответы, почему в документации не упоминается, что они одно и то же. Однако мой второй вопрос все еще стоит. Является ли причина then() возвратой новой отложенной просто так, чтобы она и pipe() могли быть эквивалентны?

ОТВЕТЫ

Ответ 1

Обновление документации для jQuery 1.8 еще не в сети.

В соответствии с этим недавним сообщением в блоге:

В процессе обновления документации API для всех изменяется на 1,8, но пока вы можете вернуться к списку изменений в объявление jQuery 1.8, чтобы узнать, что изменилось.

Обновление: Да, then() возвращает новый Deferred, потому что теперь эквивалентен pipe(). Я уверен, что обновление документации вскоре выяснит это.

Дальнейшее обновление для полноты: документация была недавно обновлена ​​и теперь говорит для pipe():

Уведомление об изнашивании: Как и в jQuery 1.8, метод deferred.pipe() устарел. Метод deferred.then(), который заменяет его, должен вместо этого используется.

И для then():

До jQuery 1.8 аргументы могут быть функцией или массивом функций.

[...]

Начиная с jQuery 1.8, метод deferred.then() возвращает новое обещание, которое может фильтровать статус и значения отложенных через, заменив теперь устаревший метод deferred.pipe(). Функции doneFilter и failFilter фильтруют исходные отложенные разрешенный/отклоненный статус и значения. Функция progressFilterфильтрует любые вызовы исходной отложенной notify или notifyWithметоды. Эти функции фильтра могут возвращать новое значение, которое необходимо передать наряду с обещаниями .done() или .fail() обратных вызовов, или они могут вернуть другой наблюдаемый объект (Отложенный, Обещание и т.д.), который будет передать свой разрешенный/отклоненный статус и ценности в соответствии с обещаниями Обратные вызовы. Если используется функция фильтра null или не указана, обещание будет разрешено или отклонено с теми же значениями, что и оригинал.