Road to 1.0.0 JavaScript Promise Book

• 文章レビュー
  • https://github.com/azu/promises-book/blob/master/CONTRIBUTE.md
  • #41 あたりを参照
  • 1文字からでいいのでpull-request受け付けています。
• #18
• All test passed
• リソースの欠損してないかの確認
• ライセンスチェック
• ライブラリチェック
• Write editor's Note
• PDF #2
• タイトルからWIPをとる
• はてブのタイトルをなおす
• git tag 1.0.0
• 紹介記事
  • efcl.info
    • どこまで紹介するか、Asciidocを使った書籍作成については別記事でいいかも
    • => JavaScript Promiseの本を書きました | Web scratch
  • JSer.info
    • あなたが読むべきJavaScript Promises | JSer.info を更新
  • 他募集中

URL : http://azu.github.io/promises-book/#ch2-promise.then

先ほどの章でPromiseの基本となるインスタンスメソッドであるthenとcatchの使い方を説明しました。

二章でも追加してあるし、
先ほどの賞という表現は変。
バッサリいらないかも

リポジトリのコードのライセンスはMITだけど、文章はクリエイティブ・コモンズで指定するのがよくある感じな気がする。

転載とか別にいいけど勝手に販売は嫌だなーぐらいかな。(CC-BY-NCになるのかな)

クリエイティブ・コモンズ 表示 - 非営利 4.0 国際 ライセンス

特にこだわりないから、一般的なやつなら何でもいい気がする。

URL : http://azu.github.io/promises-book/#ch2-promise-resolve

基本的には、.catchを使いresolveとrejectそれぞれを別々に処理した方がよいと考えらますが

成功時失敗時とした方がいい

setTimeoutのコールバック内ではの例外

typo

Native PromiseはFirefox29、Chrome35あたりから使えるけど、
現実的にはライブラリを使ったほうがサポート範囲広いし、便利な機能も多いので簡単に紹介する。

• polyfill(どれがいいんだろか…)
• petkaantonov/bluebird
  • bluebird/API.md at master · petkaantonov/bluebird
• kriskowal/q
  • API Reference · kriskowal/q Wiki

どちらも優れたAPIリファレンス持ってるので、これも紹介しておきたい。

URL : http://azu.github.io/promises-book/#ch2-promise.then

これは、Task A または Task B の処理にて、以下のどちらかが起きた場合に

例外が発生した時

Rejectedなpromiseオブジェクトがreturnされた時

onRejected が呼ばれるという事を示しています。

次のような場合にonRejected が呼ばれるという事を示しています。

間があると繋がりが良くない

#12 と関係するけど、この書籍に出てくるサンプルを実行する環境の定義、紹介やjsfiddle的なの実行出来るやつが必要そう。

#17 と合わせてもいい気がする。

埋め込んでるサンプルコードで、基本的にincludeで書いてるやつはそのままコピペで実行できるようなコード(Promiseがあれば)だと思うので、asciidocの埋め込みマクロでコードに印を付けて、
JavaScriptでjsFiddle APIを叩いて実行用のページを開くとかできると良さそう。

[source,js]
----
include::embed/embed-code.js[]
----

それぞれのコードのjsFiddleを真面目に用意するのは更新コストが高い。

w3ctag/promises-guide とかでも、delay( ms )が出てくる。

けど、ユースケースはちゃんと出てきてない気がするので、
delayを使ったタイムアウトの実装を例にしたものがあると良い気がする。

#8 の内容 無理やりPromise.allと組み合わせるよりも、個別にした方が分かりやすい気がする。

安易にthrowしないで、rejectを積極的に使おうという話。

ネイティブの実装でもthrowは結局どうやってとめているかというとtry catchしてるだけなので、rejectを使ったほうがtryにかからないで明示的にpromiseオブジェクトをrejectedにできる。

• v8/src/promise.js at master · v8/v8

new Promiseは簡単だけど、thenの中でもthrowを使わないでrejectするには、
thenで返すpromiseオブジェクトをnew Promiseで作ればいける

• use reject not thorw

URL : http://azu.github.io/promises-book/#ch2-promise-resolve

.lengthを持っているが配列ではないものをArray likeというのと同じで、 thenableの場合は.thenというメソッドを持ってるオブジェクトのことを言います。

thenableの場合は.thenというメソッドを持ってるがPromiseのインスタンスではないもの。

URL : http://azu.github.io/promises-book/#promises-overview

左が ES6Promisesで定められている名前で、 右が Promises/A+で登場する状態の名前

用語集を参照させるべき

• 横にスクロールできてしまう
• Github リボンが邪魔

PromiseとDeferredの違いについて

Deferredは

Twisted -> MochiKit/Dojo -> Promises/A -> jQuery.Deferred

時系列適当…

• Twisted 入門 — Twisted Intro
• Promise & Deferred objects in JavaScript Pt.1: Theory and Semantics.

Deferred ∋ Promise という関係は明確だけど、細かい仕様はPromise/A+とかみたいなのがないきがするから、イマイチDeferredと言われた時に何をしめすものなのか分からない。(たいていはjQeuryになるんだろうけど)

• deferred/src/Deferred.js at master · angular/deferred
• plain-promise/deferred.js at master · medikoo/plain-promise
• ljharb/promise-deferred

正直そこまで詳しくないし、あまり興味持ってないから寄稿して欲しい感じ…

promise-all.adoc の最後に逐次実行したい場合のTIPを追加

方針としては2つありそう

• 実用的なサンプルを中心にする
• アンチパターンや応用例等を中心とする

3章までそこまで実用的な話入れてないし、あんまり具体的なの大変そうなので、
#1 で書いた目的にそってアンチパターンとかを紹介する感じがいいかなと思ってる

promiseおけるエラーハンドリングが強すぎる影響で、逆にエラーを握りつぶしてしまいがち。

そういう趣旨で登場し、多くのライブラリに実装されている
doneとは何かについて

テスト周りで色々試してて使ってないnode moduleが混ざってるので整理する

• echoecho
• gulp-*

http://azu.github.io/promises-book/#then-or-catch
で最後にちょっとだけ触れているけど、
thenやcatchやPromise.allなど全部新しいpromiseオブジェクトを作って返しているというのはどこかで知らないとハマるような気がするので、
もうちょっと詳細に書く。

主戦軸とはちょっと違うので"コラム"的な位置で入れしまうのがいい気がする。
(そもそもコラムてのが何か用語的に変だ)

• コードで証明
• promiseを拡張する際に意識する必要がある

URL : http://azu.github.io/promises-book/#ch2-promise.then

スタートはPromise.resolve(1);で、この処理は以下のような流れてpromise chainが処理されていきます。

書籍の用語の表記のぶれや説明の仕方にぶれがあるので、出来るだけ統一した書き方をする。

• Promise

❌ Promises

Promiseという機能について言う時は大文字の単数を使う。

例外としてES6 Promisesの仕様へのリンクを貼る時はsをつけてもよい。

小文字は基本的にpromiseオブジェクトのみにする。

related #7

• thenで登録するコールバック関数

thenで渡すコールバック関数の事

thenで登録するコールバック関数 という書き方を大体してるが、他の書き方の方が分かりやすいかどうか？

thenに登録するハンドラ？

thenで登録されたコールバック関数

という表記にする。

• FulFilled または Rejected

いわゆるSettledの状態になった時という意味。
短縮しないで、毎回両方の状態について書いてる。

解決された時という書き方だと誤解を生みそうだし、Settledという言葉は馴染みがないので毎回書いてるが、より良い表現はないかどうか？

resolve または reject された時 という表現も使ってる。

どちらが主語になってるかの違いだけどどう統一しよう。

迷いそうな表記はCONTRIBUTIONファイルか何処かにまとめておく。

URL : http://azu.github.io/promises-book/#ch2-promise-resolve

thenableなオブジェクトが持つ元々のthenを上手く利用できるようにしつつpromiseオブジェクトに変換するという仕組みです。

そのまま利用し

ぐらいの方がシンプル

一番最初のPromiseとは何かについて

• 1.1. What Is Promises
  #1 で書いた 書籍の目的 も組んで、Promiseとは何か、何に使えるのかについてを簡単に紹介する。

IE 10 IE 9未満では promise.catchと書くだけでシンタックスエラーになるというかなりキツイものがあるので、どこかでそれについて触れる必要がある。

• jakearchibald/es6-promise
• petkaantonov/bluebird

.caught 等の回避エイリアスを用意してるライブラリもある。

この書籍としては、それは(今の)仕様に反しているので気にはしないけど、
現実的にはIE9はまだサポートから外してないケースが多いので、触れる必要があると考える。

• どのタイミングで触れるべきか

セクションとして入れるほど書けることは無いけど、どこタイミングで書くのかが難しい…

asyncThing1().then(function() {
  return asyncThing2();
}).then(function() {
  return asyncThing3();
}).catch(function(err) {
  return asyncRecovery1();
})

promise の処理を書くとメソッドチェーンをしてる事がわかる。

普通のメソッドチェーンとの違い(非同期のケースあんまりないからいいや)

ユーザーが触るAPIからはthenが見えなくて、内部的にpromiseを使うpromise chainの関数を定義するケースについて。

(promise chainという言葉は admc/wd#186 あたりからとっています)

• ステートレスAPIのメソッドチェーン
• promise chainならではのエラーハンドリング

サンプルで使用するAPIのURLが少し混ぜこぜになってるので統一する。

• promises-book/json at master · azu/promises-book

は一部サンプルで使ってる。

github pagesはCORS対応してないから微妙に不便。

他のサンプルは httpbin(1): HTTP Client Testing Service を叩くようにするのが短くでCORSも対応してて良い気がする。

#1 #12 と関連するが、

書籍の目的について最初に述べておくべきだと思う。

• Promisesとはどういうものかを学び、パターンやテストを扱えるようになる事。
• Promisesの向き不向きを知り、濫用しすぎない自制心を養う事。
• 基本的な事からよくあるはまり所等を学び、より発展した形を自分で考えられるようになること

Ch4 #5
Promiseのサブクラスの作り方 と UseCase or Libraryについて

• https://github.com/cscott/prfun
• paulmillr/es6-shim#170
• domenic/promises-unwrapping#87

Promise.resolve は第二章の先頭へ
(Promise.rejectも一緒に)

そして、ThenableとPromise.resolve はCh4へ移動する。

ThenableとPromise.resolveはいきなり難易度が上がりすぎてる感じがするのと、前後の章とあんまり関わりないので、後回しでもよさそう。

Ch2のPromise.resolveでも軽くThenableに触れてCh4へのリンクとする。

URL : http://azu.github.io/promises-book/#how-to-write-promise

幾つかインスタンスを持っており

=> インスタンスメソッド

セクションの区切りが分かりにくい

before

After

線を入れると少し分かりやすくなるかも

電子書籍は更新継続性を持てるのが正しい姿なので、
読んでる書籍のバージョンがいくつなのかを表示できるようにする。

一番下に Last updated が出るけど、バージョン表示も合ったほうがコミット関連付けし易いと思う。

asciidoctor(1) | Asciidoctor

asciidoctor -a version=$ver

みたいな感じで値が渡せるので、package.jsonのバージョンと連動すればアップデートも気軽に出来ると思う。

http://azu.github.io/promises-book/#_then_reject

で

ここで少しthenの挙動について思い出してみましょう。

といってるけど、そもそも解説してない気がする。

http://www.html5rocks.com/en/tutorials/es6/promises/#toc-error-handling これのフローの紹介と一緒にthenで返す値について触れるのが妥当な流れかなー

#40 のメタissue

第二章に promise.then について深堀りするセクションを追加する

2.4. Promise.resolve では機能的に、Promise.resolve()は何でも受け取れるという話は書いたけど、それの使い道がハッキリ書いてなかったと思う。

promiseオブジェクトかもしれないものを引数に受け取る関数を例にそれを書く

reply http://mizchi.hatenablog.com/entry/2014/05/03/230529

をもう少し具体的にしたものを入れる感じ。

• 具体的なサンプル

どこ読んでるのか迷子になりやすい気がするので、
目次に対してマーカーを付けたい。

http://bonsaiden.github.io/JavaScript-Garden/ja/ みたいなやつ

promises-bookはググらビリティが低いし、
promises なのか promiseで表記ゆれが発生しやすそう。

書籍内でもpromisesとpromiseが表記ゆれあるので(意識としてチャプタータイトルはs付ける感じでやってたけど)、Promiseに統一しちゃったほうが良い気がしてる。

タイトルとしては

• Promiseという単語が入ってる

というのが最低条件。

被りそうな書籍的なものは多分、JavaScript with Promises - O'Reilly Mediaぐらいしか今後でなさそうなので、紛らわしくなければ良いと思う。

読者の想定レベル via #12 (comment)

既にJavaScript(not jQuery)を使ったことがある程度あって、
Good Parts or JavaScriptパターン or サイ本 or パーフェクトJavaScript辺りのどれかは読んだことある感じかなー。

ES5の機能も積極的に使ったことはなくても、存在は知ってるぐらいのレベルとなってる気がします。
普通の書籍に比べると若干高めな気がしますが、Promise以外については他のもので理解してくださいねというスタンスで書いてた気がします。(別に売り物じゃないので多少ハードル上げても問題ない)

Promises API Reference

1-2行ぐらいで簡単なAPIまとめが必要。

逆参照はどうしよう。。いらない気もする。

Promise.resolveの分かりやすいユースケースが浮かばなかったので、
何かあったら書き直す。

getURL のonloadをもっと簡略化するべきかどうか?

200だけみるの正確じゃないし、どうせなら、onloadとonerrorだけという分かりやすい区切りにした方がいい気がする。

https://github.com/azu/promises-book/blob/master/Ch1_WhatsPromises/src/xhr-promise.js
https://github.com/azu/promises-book/blob/master/Ch4_AdvancedPromises/src/xhr-deferred.js
https://github.com/azu/promises-book/blob/master/Ch4_AdvancedPromises/lib/cancelableXHR.js

またnew Error(req.statusText)というのも意味が分かりにくいので、
new Error("HTTP Error " + req.status + ": " + req.statusText);という感じにした方がいいかも?
(多分文中でも言及してる)

Promise.allとPromise.raceを組み合わせて使うケース。

Distributed Electronic Rights in JavaScript
とか見て思いついた。

普通に書くと非同期処理をグループ分けてしてやるのは結構大変なので、
その辺をPromiseでまとめるとやりやすいしミスが減るというのを示せるとよいと思う。

• 現実的にありそうな具体例

asciidoctor コマンドはWARNINGがあってもビルドが取ってしまうので、
WARNINGがあった場合はexit statue 1にしてTravis CIが落ちるようにしたい。

どのようなフォーマットで公開するかについて。

• HTMLはデフォルト - Promises book
• PDF はできればあったほうがよさそう
• epub 面倒じゃなければあったほうがいい

当初の目的だと、PDFとかは任意の値段で購入できるようにして実験していたいというのがあった。
(お金 何か面倒だから自由にダウンロードできるようにしちゃいそうだけど)

URL : http://azu.github.io/promises-book/#ch2-promise.then

Promiseのメソッドチェーンだと長いので、今後はpromise chainと呼びますが、 このpromise chainがPromiseが非同期処理の流れを書きやすい理由の一つといえるかもしれません。

今後はpromise chainと呼びますが、

呼びます。 で一度区切ろう

promiseオブジェクトの配列を受け取って、それを一つづつ実行していくPromise.allの亜種的な実装について。

多分これを実装しようと思うと、 #9 について触れる必要があるはずなので、
#9 と一緒にまとめてしまう。

Promise.all とも内部的にPromise.resolveを通してるはず。

Task Aで例外が発生した時の図

ビルド時にワーニングでないのかな?(でたらテスト落ちるはずだけど

URL : http://azu.github.io/promises-book/#ch2-promise-reject

多くの場合は、多種多様なPromiseの実装ライブラリがある中でそれらの違いを意識せず使えるように、 共通の挙動であるthenだけを利用して、他の機能は自分自分のPromiseにあるものを利用できるように変換するという意味合いが強いと思います。

このthenableを変換する機能は、以前はPromise.castという名前であった事からも想像できるかもしれません。

様々なライブラリ間でpromiseを相互に変換して利用できる仕組み

という感じでもっと短く書こう

http://azu.github.io/promises-book/#_promise_6

みたいに日本語が入るとIDが連番になってしまうので、全てのセクションにIDを振るようにする

サンプルでも以下の2種類に分けられて書いてる。

• ソースコード(主に関数定義等が中心)
• ソースコードを実行する例を示すインラインコード

ソースコードの動作自体は、テストによってある程度保証されてるけど、
インラインコードはコピペで貼り付けてる部分があるので、これの動作を検証したい。

インラインコードも全部外部ファイルにして動かせるようにすればいいんだけど、中々大変な感じがする(インラインコードがソースコードに依存するケースが殆どなので)

[source,js]
----
インラインコード
----

という記法は間違いなく固定なので、このインラインコードをパースして、パース出来なければさすがにオカシイので、文法的なミスを検出するテストとか入れたい。
多分文法ミスによるエラーのサンプルは今のところなかったはず。
console.errror というようなtypoをした場合の例とかはありえそうだけど、これもJavaScriptの文法として間違ってないので、明らかな書きミスだけでも保証しておきたい。

必要なもの

• Asciidocのパース
• 取得したインラインコードをパースする(esprimaとか)

URL : http://azu.github.io/promises-book/#ch2-promise.then

非同期のタイミングとなります。

タイミングは余計な感じがする