package-lock.jsonの各プロパティについて調べてみました。

[JavaScript Advent Calendar 2017](https://qiita.com/advent-calendar/2017/javascript) 13日目の記事です。

今年はnpmが5にメジャーアップデートされました。
npm5になり新しく加わった機能の一つにpackage-lock.jsonがあります。
他の機能については[こちら(npm v5 がリリースされた)](http://yosuke-furukawa.hatenablog.com/entry/2017/05/30/090602)

今回はpackage-lock.jsonの各プロパティについて詳しく載っている日本語記事が無かったので調べてみました。
内容に不備があったり気づいたことがあればどんどんコメントください。

# きっかけ
package-lock.jsonについては依存パッケージの固定化する機能であったり、元々はnpm-shrinkwrapというものがあってそれを改良したものであったり等は聞いたり読んだりしたことある方は多いかと思います。
私も「依存パッケージの固定ができるなんて便利だな、公式もコミットするのを推奨しているしgit管理するか」ぐらいの軽いノリでpackage-lock.jsonをコミットしていたのですが、macos環境とLinux環境でoptionalDepndenciesが入ったり入らなかったり、requiresというプロパティが増えたり、package.jsonに変更がなくてもpackage-lock.jsonが意図せず変更されるることがありました。
そういった時に中身を見てみるのですが、何が何だかわからず読めなかったので調べてみました。

# 各プロパティについて
[公式](https://docs.npmjs.com/files/package-lock.json)の完全翻訳ではありません。
省略していたり追記している部分がありますが、[公式](https://docs.npmjs.com/files/package-lock.json)をベースに説明していきます。

## name
パッケージの名称です。
package.jsonに記載されいてるnameが自動で設定されます。

## version
パッケージのバージョンです。
package.jsonに記載されているversionが自動で設定されます。
ちょっと話は逸れますが、依存パッケージのバージョンを上げる際は[semver](https://semver.org/lang/ja/)に従ってアップデートしてください。

## lockfileVersion
package-lock.json自体のバージョンです。ロックするフォーマットの形式が将来変わった場合にどのバージョンのロック形式かわかるようにするためです。
1から始まる整数が設定されます。

## packageIntegrity
package.jsonの[Subresource Integrity(SRI)](https://developer.mozilla.org/ja/docs/Web/Security/Subresource_Integrity)です。SRIの値は[ssri](https://www.npmjs.com/package/ssri)のようなモジュールによって生成可能です。

## preserveSymlinks
`NODE_PRESERVE_SYMLINKS`という環境変数を使ってパッケージをインストールする場合、インストーラーはこの値が環境変数と一致する必要があるみたいです。

## dependencies
依存関係のマッピング。ここに記載されたパッケージの定義に従い`node_modules`にパッケージをインストールします。
各依存関係のマッピングには以下のプロパティが定義されています。

### version
依存パッケージのバージョンです。
npmレジストリに登録されている場合は1.2.3のようなバージョン番号になります。githubから取得する場合は`git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`のようになり、リモートアーカイブから取得する場合は`https://example.com/example-1.3.0.tgz`のようになります。

### integrity
依存パッケージの[Subresource Integrity(SRI)](https://developer.mozilla.org/ja/docs/Web/Security/Subresource_Integrity)です。githubから取得する場合はコミットのハッシュ、リモートアーカイブから取得した場合はファイルをSHA-512で暗号化したハッシュ値です。

### resolved
npmレジストリ上の特定のファイルが使用可能な場合はここに記載されたURL先のファイルを使用します。存在しない場合は`version`を使用して依存解決します。

### bundled
該当しない場合はこのプロパティは記述されません。
true: このパッケージは独立してインストールされるわけではなく親モジュールの圧縮パッケージが解凍されるときに親モジュールから直接取り出されます。

### dev
devDependenciesに指定されているパッケージの依存パッケージの場合のみこのプロパティは記述されます。
true: devDependenciesとして指定されているパッケージからの参照の場合のみ
false: devDependenciesからのパッケージだけに限らず、devDependencies以外からも参照されている場合

### optional
optionalDependenciesに指定されているパッケージの依存パッケージの場合のみこのプロパティは記述されます。
true: optionalDependenciesとして指定されているパッケージからの参照の場合のみ
false: optionalDependenciesからのパッケージに限らず、optionalDependencies以外からも参照されている場合

### requires
[公式](https://docs.npmjs.com/files/package-lock.json)にはありませんが、[GitHub](https://github.com/npm/npm/blob/latest/doc/spec/package-lock.md)には説明が記載されています。
npm 5.1.0から追加されました。([リリースノート](https://github.com/npm/npm/releases/tag/v5.1.0)）
このモジュールが必要とするすべてのパッケージが、どこからインストールされたかに関係なく、`名前: バージョン番号`の形式で一覧で記載されます。
各パッケージが参照する特定のバージョンへの参照が記載されています。package-lock.json以外の他のロックファイルやフォーマットへの変換や最適化、パッケージツリーの正確性の検証などさまざまな用途に使用されます。
npmjs.comでパッケージを検索した際に表示されているDependenciesの内容と一致します。

# 参考
- [package-lock.json | npm Documentation](https://docs.npmjs.com/files/package-lock.json)
- [package-locks | npm Documentation](https://docs.npmjs.com/files/package-locks)
- [セマンティックバージョニング 2.0.0](https://semver.org/lang/ja/)
- [Subresource Integrity](https://developer.mozilla.org/ja/docs/Web/Security/Subresource_Integrity)
- [Understanding lock files in NPM 5](https://jpospisil.com/2017/06/02/understanding-lock-files-in-npm-5.html)
- [npm v5 がリリースされた](http://yosuke-furukawa.hatenablog.com/entry/2017/05/30/090602)

以上になります。
package-lockの運用や内容の理解に困っている方の一助になれば幸いです。
今回の調査によって私も勉強になりました。
また、package-lock.jsonの運用が固まってきて良い感じになってきたら記事にしたいと思います。
最後までお読み頂きありがとうございました。