{"action":"created","comment":{"url":"https://api.github.com/repos/survivejs/maintenance-book/pulls/comments/143822343","pull_request_review_id":68390864,"id":143822343,"diff_hunk":"@@ -1,31 +1,61 @@\n # Typing\n \n-A function interface is a contract. Depending on the system, it gives you guarantees. In JavaScript there are no guarantees by default and you can pass anything to a function. This may lead to a runtime error, though, given it's an interpreted language. In a stricter system passing invalid values would be forbidden on a type level.\n+A function interface is a contract and depending on the system, it gives you guarantees. JavaScript doesn't give any guarantees by default and you can pass anything to a function. Doing this may lead to a runtime error and crash your application. In a stricter system it would be more difficult, or even impossible, to do this.\n \n ## The Value of Typing\n \n-A loose typing system, such as the one included in JavaScript, doesn't get in your way. This is also the problem. Once you better understand what you want, it makes sense to provide type information. Modeling types and data structures is an important part of programming, as they help to model domain understanding.\n+A loose typing system, such as the one included in JavaScript, doesn't get in your way. But what if you know the types and want to communicate them? You could include rough checks by programming them but this cannot match proper type systems and tooling cannot use the information in any meaningful manner.\n \n-Loose typing comes with the following problems:\n+Certain languages allow **type hints** as a compromise. If you know a type, add it to the code. The language uses this information when available. One side benefit of stating types this way is that then the interpreter can use these guarantees to speed up execution. The type information can be used for **property based testing** and documentation.\n \n-* It allows runtime errors to exist. If you pass a value of wrong type, it can lead to unexpected results and crash the entire system.\n-* Even if you knew the expected type, communicating it would be difficult. You can perform a type check on language level but the problem with this is that it's difficult to use the type information in tooling then.\n-* Types can be annotated within comments but then you would lose code level checks without compiling the comments to actual checks.\n+## Flow\n \n-Certain languages allow **type hints** as a compromise. If you know a type, add it to the code. The language uses this information when available. One side benefit of stating types this way is that then the interpreter can use these guarantees to speed up execution. The type information can be used for **property based testing** and documentation.\n+![Flow](images/flow.png)\n+\n+[Flow type checker by Facebook](https://flow.org/) is an example of a solution that builds on top of JavaScript while providing stronger typing semantics for it.  To give you an example, consider the following `add` function that has been annotated using Flow:\n+\n+<!-- textlint-disable -->\n+\n+```javascript\n+function add(x: number, y: number): number {\n+  return x + y;\n+}\n+```\n+\n+<!-- textlint-enable -->\n+\n+The definition states that `add` should receive two numbers and return one as a result. This is the way it's typically done in statically typed languages. Now we can benefit from the same idea in JavaScript.","path":"manuscript/code-quality/03-typing.md","position":34,"original_position":34,"commit_id":"d483ed670c99a57e7fdf98acf7fd177da5e138e2","original_commit_id":"d483ed670c99a57e7fdf98acf7fd177da5e138e2","user":{"login":"sapegin","id":70067,"avatar_url":"https://avatars2.githubusercontent.com/u/70067?v=4","gravatar_id":"","url":"https://api.github.com/users/sapegin","html_url":"https://github.com/sapegin","followers_url":"https://api.github.com/users/sapegin/followers","following_url":"https://api.github.com/users/sapegin/following{/other_user}","gists_url":"https://api.github.com/users/sapegin/gists{/gist_id}","starred_url":"https://api.github.com/users/sapegin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sapegin/subscriptions","organizations_url":"https://api.github.com/users/sapegin/orgs","repos_url":"https://api.github.com/users/sapegin/repos","events_url":"https://api.github.com/users/sapegin/events{/privacy}","received_events_url":"https://api.github.com/users/sapegin/received_events","type":"User","site_admin":false},"body":"typically → usually ;-)\r\n\r\n“Now we can benefit from the same idea in JavaScript.” → “”","created_at":"2017-10-10T19:00:05Z","updated_at":"2017-10-10T19:09:23Z","html_url":"https://github.com/survivejs/maintenance-book/pull/30#discussion_r143822343","pull_request_url":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30","author_association":"COLLABORATOR","_links":{"self":{"href":"https://api.github.com/repos/survivejs/maintenance-book/pulls/comments/143822343"},"html":{"href":"https://github.com/survivejs/maintenance-book/pull/30#discussion_r143822343"},"pull_request":{"href":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30"}}},"pull_request":{"url":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30","id":145662409,"html_url":"https://github.com/survivejs/maintenance-book/pull/30","diff_url":"https://github.com/survivejs/maintenance-book/pull/30.diff","patch_url":"https://github.com/survivejs/maintenance-book/pull/30.patch","issue_url":"https://api.github.com/repos/survivejs/maintenance-book/issues/30","number":30,"state":"open","locked":false,"title":"chore: Add more info on typing systems","user":{"login":"bebraw","id":166921,"avatar_url":"https://avatars0.githubusercontent.com/u/166921?v=4","gravatar_id":"","url":"https://api.github.com/users/bebraw","html_url":"https://github.com/bebraw","followers_url":"https://api.github.com/users/bebraw/followers","following_url":"https://api.github.com/users/bebraw/following{/other_user}","gists_url":"https://api.github.com/users/bebraw/gists{/gist_id}","starred_url":"https://api.github.com/users/bebraw/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bebraw/subscriptions","organizations_url":"https://api.github.com/users/bebraw/orgs","repos_url":"https://api.github.com/users/bebraw/repos","events_url":"https://api.github.com/users/bebraw/events{/privacy}","received_events_url":"https://api.github.com/users/bebraw/received_events","type":"User","site_admin":false},"body":"","created_at":"2017-10-10T11:10:17Z","updated_at":"2017-10-10T19:09:23Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a1c66a6fddc40a6b735ec9cd331a02e3c7c08dc3","assignee":null,"assignees":[],"requested_reviewers":[],"milestone":null,"commits_url":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30/commits","review_comments_url":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30/comments","review_comment_url":"https://api.github.com/repos/survivejs/maintenance-book/pulls/comments{/number}","comments_url":"https://api.github.com/repos/survivejs/maintenance-book/issues/30/comments","statuses_url":"https://api.github.com/repos/survivejs/maintenance-book/statuses/d483ed670c99a57e7fdf98acf7fd177da5e138e2","head":{"label":"survivejs:edit-typing","ref":"edit-typing","sha":"d483ed670c99a57e7fdf98acf7fd177da5e138e2","user":{"login":"survivejs","id":11871113,"avatar_url":"https://avatars1.githubusercontent.com/u/11871113?v=4","gravatar_id":"","url":"https://api.github.com/users/survivejs","html_url":"https://github.com/survivejs","followers_url":"https://api.github.com/users/survivejs/followers","following_url":"https://api.github.com/users/survivejs/following{/other_user}","gists_url":"https://api.github.com/users/survivejs/gists{/gist_id}","starred_url":"https://api.github.com/users/survivejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/survivejs/subscriptions","organizations_url":"https://api.github.com/users/survivejs/orgs","repos_url":"https://api.github.com/users/survivejs/repos","events_url":"https://api.github.com/users/survivejs/events{/privacy}","received_events_url":"https://api.github.com/users/survivejs/received_events","type":"Organization","site_admin":false},"repo":{"id":84477465,"name":"maintenance-book","full_name":"survivejs/maintenance-book","owner":{"login":"survivejs","id":11871113,"avatar_url":"https://avatars1.githubusercontent.com/u/11871113?v=4","gravatar_id":"","url":"https://api.github.com/users/survivejs","html_url":"https://github.com/survivejs","followers_url":"https://api.github.com/users/survivejs/followers","following_url":"https://api.github.com/users/survivejs/following{/other_user}","gists_url":"https://api.github.com/users/survivejs/gists{/gist_id}","starred_url":"https://api.github.com/users/survivejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/survivejs/subscriptions","organizations_url":"https://api.github.com/users/survivejs/orgs","repos_url":"https://api.github.com/users/survivejs/repos","events_url":"https://api.github.com/users/survivejs/events{/privacy}","received_events_url":"https://api.github.com/users/survivejs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/survivejs/maintenance-book","description":"Maintenance book","fork":false,"url":"https://api.github.com/repos/survivejs/maintenance-book","forks_url":"https://api.github.com/repos/survivejs/maintenance-book/forks","keys_url":"https://api.github.com/repos/survivejs/maintenance-book/keys{/key_id}","collaborators_url":"https://api.github.com/repos/survivejs/maintenance-book/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/survivejs/maintenance-book/teams","hooks_url":"https://api.github.com/repos/survivejs/maintenance-book/hooks","issue_events_url":"https://api.github.com/repos/survivejs/maintenance-book/issues/events{/number}","events_url":"https://api.github.com/repos/survivejs/maintenance-book/events","assignees_url":"https://api.github.com/repos/survivejs/maintenance-book/assignees{/user}","branches_url":"https://api.github.com/repos/survivejs/maintenance-book/branches{/branch}","tags_url":"https://api.github.com/repos/survivejs/maintenance-book/tags","blobs_url":"https://api.github.com/repos/survivejs/maintenance-book/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/survivejs/maintenance-book/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/survivejs/maintenance-book/git/refs{/sha}","trees_url":"https://api.github.com/repos/survivejs/maintenance-book/git/trees{/sha}","statuses_url":"https://api.github.com/repos/survivejs/maintenance-book/statuses/{sha}","languages_url":"https://api.github.com/repos/survivejs/maintenance-book/languages","stargazers_url":"https://api.github.com/repos/survivejs/maintenance-book/stargazers","contributors_url":"https://api.github.com/repos/survivejs/maintenance-book/contributors","subscribers_url":"https://api.github.com/repos/survivejs/maintenance-book/subscribers","subscription_url":"https://api.github.com/repos/survivejs/maintenance-book/subscription","commits_url":"https://api.github.com/repos/survivejs/maintenance-book/commits{/sha}","git_commits_url":"https://api.github.com/repos/survivejs/maintenance-book/git/commits{/sha}","comments_url":"https://api.github.com/repos/survivejs/maintenance-book/comments{/number}","issue_comment_url":"https://api.github.com/repos/survivejs/maintenance-book/issues/comments{/number}","contents_url":"https://api.github.com/repos/survivejs/maintenance-book/contents/{+path}","compare_url":"https://api.github.com/repos/survivejs/maintenance-book/compare/{base}...{head}","merges_url":"https://api.github.com/repos/survivejs/maintenance-book/merges","archive_url":"https://api.github.com/repos/survivejs/maintenance-book/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/survivejs/maintenance-book/downloads","issues_url":"https://api.github.com/repos/survivejs/maintenance-book/issues{/number}","pulls_url":"https://api.github.com/repos/survivejs/maintenance-book/pulls{/number}","milestones_url":"https://api.github.com/repos/survivejs/maintenance-book/milestones{/number}","notifications_url":"https://api.github.com/repos/survivejs/maintenance-book/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/survivejs/maintenance-book/labels{/name}","releases_url":"https://api.github.com/repos/survivejs/maintenance-book/releases{/id}","deployments_url":"https://api.github.com/repos/survivejs/maintenance-book/deployments","created_at":"2017-03-09T18:53:40Z","updated_at":"2017-10-10T11:17:46Z","pushed_at":"2017-10-10T13:59:00Z","git_url":"git://github.com/survivejs/maintenance-book.git","ssh_url":"git@github.com:survivejs/maintenance-book.git","clone_url":"https://github.com/survivejs/maintenance-book.git","svn_url":"https://github.com/survivejs/maintenance-book","homepage":null,"size":625,"stargazers_count":35,"watchers_count":35,"language":null,"has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3,"mirror_url":null,"open_issues_count":14,"forks":3,"open_issues":14,"watchers":35,"default_branch":"master"}},"base":{"label":"survivejs:master","ref":"master","sha":"59fbd130ee8cf0ca873b829d115cde90f25f6aad","user":{"login":"survivejs","id":11871113,"avatar_url":"https://avatars1.githubusercontent.com/u/11871113?v=4","gravatar_id":"","url":"https://api.github.com/users/survivejs","html_url":"https://github.com/survivejs","followers_url":"https://api.github.com/users/survivejs/followers","following_url":"https://api.github.com/users/survivejs/following{/other_user}","gists_url":"https://api.github.com/users/survivejs/gists{/gist_id}","starred_url":"https://api.github.com/users/survivejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/survivejs/subscriptions","organizations_url":"https://api.github.com/users/survivejs/orgs","repos_url":"https://api.github.com/users/survivejs/repos","events_url":"https://api.github.com/users/survivejs/events{/privacy}","received_events_url":"https://api.github.com/users/survivejs/received_events","type":"Organization","site_admin":false},"repo":{"id":84477465,"name":"maintenance-book","full_name":"survivejs/maintenance-book","owner":{"login":"survivejs","id":11871113,"avatar_url":"https://avatars1.githubusercontent.com/u/11871113?v=4","gravatar_id":"","url":"https://api.github.com/users/survivejs","html_url":"https://github.com/survivejs","followers_url":"https://api.github.com/users/survivejs/followers","following_url":"https://api.github.com/users/survivejs/following{/other_user}","gists_url":"https://api.github.com/users/survivejs/gists{/gist_id}","starred_url":"https://api.github.com/users/survivejs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/survivejs/subscriptions","organizations_url":"https://api.github.com/users/survivejs/orgs","repos_url":"https://api.github.com/users/survivejs/repos","events_url":"https://api.github.com/users/survivejs/events{/privacy}","received_events_url":"https://api.github.com/users/survivejs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/survivejs/maintenance-book","description":"Maintenance book","fork":false,"url":"https://api.github.com/repos/survivejs/maintenance-book","forks_url":"https://api.github.com/repos/survivejs/maintenance-book/forks","keys_url":"https://api.github.com/repos/survivejs/maintenance-book/keys{/key_id}","collaborators_url":"https://api.github.com/repos/survivejs/maintenance-book/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/survivejs/maintenance-book/teams","hooks_url":"https://api.github.com/repos/survivejs/maintenance-book/hooks","issue_events_url":"https://api.github.com/repos/survivejs/maintenance-book/issues/events{/number}","events_url":"https://api.github.com/repos/survivejs/maintenance-book/events","assignees_url":"https://api.github.com/repos/survivejs/maintenance-book/assignees{/user}","branches_url":"https://api.github.com/repos/survivejs/maintenance-book/branches{/branch}","tags_url":"https://api.github.com/repos/survivejs/maintenance-book/tags","blobs_url":"https://api.github.com/repos/survivejs/maintenance-book/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/survivejs/maintenance-book/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/survivejs/maintenance-book/git/refs{/sha}","trees_url":"https://api.github.com/repos/survivejs/maintenance-book/git/trees{/sha}","statuses_url":"https://api.github.com/repos/survivejs/maintenance-book/statuses/{sha}","languages_url":"https://api.github.com/repos/survivejs/maintenance-book/languages","stargazers_url":"https://api.github.com/repos/survivejs/maintenance-book/stargazers","contributors_url":"https://api.github.com/repos/survivejs/maintenance-book/contributors","subscribers_url":"https://api.github.com/repos/survivejs/maintenance-book/subscribers","subscription_url":"https://api.github.com/repos/survivejs/maintenance-book/subscription","commits_url":"https://api.github.com/repos/survivejs/maintenance-book/commits{/sha}","git_commits_url":"https://api.github.com/repos/survivejs/maintenance-book/git/commits{/sha}","comments_url":"https://api.github.com/repos/survivejs/maintenance-book/comments{/number}","issue_comment_url":"https://api.github.com/repos/survivejs/maintenance-book/issues/comments{/number}","contents_url":"https://api.github.com/repos/survivejs/maintenance-book/contents/{+path}","compare_url":"https://api.github.com/repos/survivejs/maintenance-book/compare/{base}...{head}","merges_url":"https://api.github.com/repos/survivejs/maintenance-book/merges","archive_url":"https://api.github.com/repos/survivejs/maintenance-book/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/survivejs/maintenance-book/downloads","issues_url":"https://api.github.com/repos/survivejs/maintenance-book/issues{/number}","pulls_url":"https://api.github.com/repos/survivejs/maintenance-book/pulls{/number}","milestones_url":"https://api.github.com/repos/survivejs/maintenance-book/milestones{/number}","notifications_url":"https://api.github.com/repos/survivejs/maintenance-book/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/survivejs/maintenance-book/labels{/name}","releases_url":"https://api.github.com/repos/survivejs/maintenance-book/releases{/id}","deployments_url":"https://api.github.com/repos/survivejs/maintenance-book/deployments","created_at":"2017-03-09T18:53:40Z","updated_at":"2017-10-10T11:17:46Z","pushed_at":"2017-10-10T13:59:00Z","git_url":"git://github.com/survivejs/maintenance-book.git","ssh_url":"git@github.com:survivejs/maintenance-book.git","clone_url":"https://github.com/survivejs/maintenance-book.git","svn_url":"https://github.com/survivejs/maintenance-book","homepage":null,"size":625,"stargazers_count":35,"watchers_count":35,"language":null,"has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":3,"mirror_url":null,"open_issues_count":14,"forks":3,"open_issues":14,"watchers":35,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30"},"html":{"href":"https://github.com/survivejs/maintenance-book/pull/30"},"issue":{"href":"https://api.github.com/repos/survivejs/maintenance-book/issues/30"},"comments":{"href":"https://api.github.com/repos/survivejs/maintenance-book/issues/30/comments"},"review_comments":{"href":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30/comments"},"review_comment":{"href":"https://api.github.com/repos/survivejs/maintenance-book/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/survivejs/maintenance-book/pulls/30/commits"},"statuses":{"href":"https://api.github.com/repos/survivejs/maintenance-book/statuses/d483ed670c99a57e7fdf98acf7fd177da5e138e2"}},"author_association":"OWNER"}}
{"actor":{"display_login":"sapegin"}}