CreateJS 1.0: 推奨されなくなった機能をどのように扱うか ー 公式サイトの方針とその対応

CreateJS Blogに2018年8月15日付で「[Deprecating Functionality in CreateJS 1.0](http://blog.createjs.com/deprecating-functionality-in-createjs-1-0/)」という記事が公開されました。ライブラリで推奨されなくなった機能をどのように扱うかという公式サイトの方針と、それらの機能への対応の仕方が説明されています。本稿はこの記事にもとづき、内容に加筆・補正してご紹介します。

CreateJSのバージョン1.0は、基本的には各ライブラリのマイナーアップデートです。そして、CDNのCreateJS圧縮(min)/統合ライブラリを更新しました。この1.0のリリースから、推奨されないプロパティやメソッドを使ったとき、コンソールにかなり詳しい警告が出るようになったことにお気づきでしょうか。ここでは、推奨されない古いAPIにどうアプローチし、スムーズでわかりやすいプロセスのためにこのバージョンで何を行なったのかご説明します。


# なぜどのように変えるのか
APIが変わるのは当然です。また、ブラウザやJavaScriptの仕様は、これまでよりもさらに進化が速くなっています。ライブラリも変更や改善を加えていかなければなりません。

とはいえ、基本として目指すのは、新しいバージョンのリリースがこれまであるコンテンツをできるかぎり壊さないことです。そのために、非推奨の戦略を採ります。

1. 互換性を損なう変更か改善か。
2. できればもとの動作は1メジャーバージョンの間は保つ。
3. ユーザーにできるだけ早く周知する。

まず、廃止されるプロパティやメソッドも、期待どおりに動きますし、パフォーマンスに影響はありません。ただし、将来のバージョンで除かれたり、動作が変わるかもしれないということです。

これは優れたアプローチです。古い動作を1ないし2バージョンの間保ち、すべてが期待どおりに動くからです。さらに、ドキュメントには非推奨のメソッドも載っています。そして、新しい改善されたやり方も紹介されるでしょう。あるいは、なぜその機能が除かれるのか説明が加えられます。たとえば、[`Ticker.setFPS()`メソッド](https://createjs.com/docs/easeljs/classes/Ticker.html#method_setFPS)です。EaselJS 1.0では非推奨であるものの、ドキュメントには「deprecated」の表示つきで説明が掲げられています(図001)。

#### 図001■非推奨のTicker.setFPS()メソッド
![qiita_08_002_001.png](https://qiita-image-store.s3.amazonaws.com/0/128949/55dc4c4b-df13-739b-709f-f66b095dcbb6.png)



# バージョン1.0の新機能
これまでのバージョンでも、非推奨のプロパティは、バージョン1.0と同じようにしばらくの間は動かせていました。けれど、開発者に向けて、変更があったことや、更新しなければならないことは知らされなかったのです。リリースノートを読むしかありませんでした。バージョン1.0では、すべての推奨されないプロパティやメソッドは、使えばコンソールに警告が示されます(図002)。

#### 図002■非推奨のプロパティやメソッドを使ったときのコンソールの表示
![deprecated-warnings.png](http://blog.createjs.com/wp-content/uploads/2018/08/deprecated-warnings.png)


# 推奨されないプロパティやメソッドがなぜ増えたのか
これまでのCreateJSの開発をとおして、多くの動作やAPIが非推奨となりました。けれど、1.0にアップグレードすると、ここ数バージョンより[さらに多くのプロパティとメソッドが推奨されなくなっています](https://github.com/CreateJS/EaselJS/blob/master/VERSIONS.txt)。これらはつぎのメジャーリリースではおそらく除かれるでしょう。開発者に向けて、よりはっきりとした警告が示されなければなりません。とくに、Adobe Animate CCのHTML5ドキュメントは、CreateJSの新しいバージョンでは非推奨のコードが含まれています。Animate CCからパブリッシュされるテンプレートがまだ古いメソッドを使っているためです。

バージョン2.0ではECMAScript 2016に対応しようとしてします。そのためにも、古いコードは除いておくことが望ましいでしょう。


# 非推奨を扱うユーティリティ関数deprecate()
CreateJS 1.0にはユーティリティ関数[`deprecate()`](https://createjs.com/docs/easeljs/classes/Utility%20Methods.html#method_deprecate)が備わりました。[実装](https://createjs.com/docs/easeljs/files/createjs_utils_deprecate.js.html#l40)はつぎのとおり、簡単な関数です。プロパティやメソッドを簡単に非推奨とし、コンソールに名前と警告を示します。さらにオプションで、フォールバック関数を与えて、非推奨の機能を動かすこともできるのです。

```js
createjs.deprecate = function(fallbackMethod, name) {
	"use strict";
	return function() {
		var msg = "Deprecated property or method '"+name+"'. See docs for info.";
		console && (console.warn ? console.warn(msg) : console.log(msg));
		return fallbackMethod && fallbackMethod.apply(this, arguments);
	}
};
```

プロトタイプメソッドを非推奨にするのは、つぎのように簡単です。なお、CreateJS 1.0で廃止された`get`/`set`メソッドは、名前の頭にアンダースコアをつけて残されています。

Deprecating a prototype method is really straightforward:

```js
var p = createjs.DisplayObject.prototype;
p.getStage = createjs.deprecate(p._getStage, "DisplayObject.getStage");
```

プロパティの非推奨はもう少し手間はかかるものの、難しくはありません。前述のとおり、バージョン1.0では`get`/`set`メソッドは名前を変えてprotectedにされているだけですので、フォールバックすれば済みます。ライブラリに機能を加えなくてよいのです。

```js
Object.defineProperties(createjs.AbstractLoader, {
    POST: { get: deprecate(function() { return createjs.Methods.POST; }, "AbstractLoader.POST") }
};
```

ライブラリの機能が変わることには注意すべきです。潜在的な問題を洗い出したうえで、互換性を損なうのは十分な理由があるときのみとします。新しいライブラリにアップデートするとき、つぎのようなところを確かめるとよいでしょう。

1. メジャーリリースには[ブログ記事](http://blog.createjs.com/)を投稿しますのでお読みください。Twitterの[@createjs](https://twitter.com/createjs)にもtweetします。
2. [GitHubの各ライブラリ](https://github.com/createjs)にあるVERSIONS.TXTに変更内容が記載されています。影響の大きなものと小さなものに分け、互換性を損なう変更もリストされています。
3. コンソールを確かめてください。警告やエラーが、動かない原因を示しているかもしれません。


CreateJSについて問題やバグが見つかったときには、[StackOverflow](https://stackoverflow.com/questions/tagged/createjs)にご質問を投稿してください。チームのメンバーが活発に対応しています。