{"action":"created","comment":{"url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/comments/36855032","id":36855032,"diff_hunk":"@@ -0,0 +1,309 @@\n+# Repositories\n+\n+<div class=\"well\">\n+This Guide is based on rom 0.9.0.beta and rom-repository 0.0.2.\n+</div>\n+\n+In ROM repositories encapsulates access to domain-specific entities. They use\n+relations to expose a convenient interface for composing relations together\n+and automatically mapping them to struct objects.\n+\n+## Defining a Repository Class\n+\n+A repository object gets access to selected relations that are available in the\n+ROM container object. When you create a repository class you can explicitly define\n+which relations should be established:\n+\n+``` ruby\n+class UserRepository < ROM::Repository::Base\n+  relations :users\n+\n+  # your methods go here\n+end\n+\n+rom = ROM.finalize.env\n+\n+user_repo = UserRepository.new(rom)\n+\n+user_repo.users\n+```\n+\n+Once you have access to your relations you can expose access to specific entities\n+with your custom interface:\n+\n+``` ruby\n+class UserRepository < ROM::Repository::Base\n+  relations :users\n+\n+  def [](id)\n+    users.where(id: id).one!\n+  end\n+end\n+\n+\n+rom = ROM.finalize.env\n+\n+user_repo = UserRepository.new(rom)\n+\n+user_repo[1]\n+# #<ROM::Struct[User] id=1 name=\"Jane\">\n+```\n+\n+As you can see the repository automatically maps relation tuples to instances of\n+`ROM::Struct`.\n+\n+## ROM Structs\n+\n+ROM structs are simple data-capsules. They give you access to their values via\n+attribute `[]` readers and are coercible to a hash. With powerful relation query\n+DSLs you can easily compose relations and return data in the expected state.\n+That's why automatically mapping to small structs is feasible and no custom\n+mapping is required.\n+\n+Struct constructor is strict with regards to the attribute hash it receives - if\n+there are attributes that were not expected you will get an exception.\n+\n+Here's an example of a struct:\n+\n+``` ruby\n+user = user_repo[1]\n+# #<ROM::Struct[User] id=1 name=\"Jane\">\n+\n+user.id # 1\n+user[:id] # 1\n+\n+user.to_hash # {:id=>1, :name=>\"Jane\"}\n+```\n+\n+ROM repositories generate struct classes for you so that you don't have to define\n+them.\n+\n+<div class=\"well well-small\">\n+There's a planned feature where you'll be able to provide namespace for your\n+structs where struct class constants will be defined as opposed to anonymous classes.\n+</div>\n+\n+## Working With Relations\n+\n+In ROM relations represent specific database queries that your application needs\n+to execute to get its data. It is recommended to define relations explicitly as\n+your own classes to achieve better encapsulation and simplify composition.\n+\n+A common pattern is to encapsulate specific relation methods and use those in your\n+repositories rather than accessing lower-level query DSLs.\n+\n+``` ruby\n+class Users < ROM::Relation[:sql]\n+  def listing\n+    select(:id, :name, :email, :created_at).order(:name, :id)\n+  end\n+\n+  def registered_after(timestamp)\n+    where { created_at > timestamp }\n+  end\n+end\n+\n+class UserRepository < ROM::Repository::Base\n+  relations :users\n+\n+  def new_users(timestamp)\n+    users.listing.registered_after(timestamp)\n+  end\n+end\n+\n+user_repo.new_users(Time.new(2015))\n+```\n+\n+This way you encapsulate specific queries and domain-specific relation views. Your","path":"source/doc-pages/guides/basics/repositories.md","position":117,"original_position":117,"commit_id":"f594852f3cd7647f551697c98b8902c9e5768ab5","original_commit_id":"f594852f3cd7647f551697c98b8902c9e5768ab5","user":{"login":"AMHOL","id":1582784,"avatar_url":"https://avatars.githubusercontent.com/u/1582784?v=3","gravatar_id":"","url":"https://api.github.com/users/AMHOL","html_url":"https://github.com/AMHOL","followers_url":"https://api.github.com/users/AMHOL/followers","following_url":"https://api.github.com/users/AMHOL/following{/other_user}","gists_url":"https://api.github.com/users/AMHOL/gists{/gist_id}","starred_url":"https://api.github.com/users/AMHOL/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/AMHOL/subscriptions","organizations_url":"https://api.github.com/users/AMHOL/orgs","repos_url":"https://api.github.com/users/AMHOL/repos","events_url":"https://api.github.com/users/AMHOL/events{/privacy}","received_events_url":"https://api.github.com/users/AMHOL/received_events","type":"User","site_admin":false},"body":"This way, you encapsulate specific queries and domain-specific relation views. Your\r\napplication interfaces with simple structs and has no idea how they are fetched and instantiated.","created_at":"2015-08-12T12:48:24Z","updated_at":"2015-08-12T12:48:24Z","html_url":"https://github.com/rom-rb/rom-rb.org/pull/84#discussion_r36855032","pull_request_url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84","_links":{"self":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/comments/36855032"},"html":{"href":"https://github.com/rom-rb/rom-rb.org/pull/84#discussion_r36855032"},"pull_request":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84"}}},"pull_request":{"url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84","id":42227907,"html_url":"https://github.com/rom-rb/rom-rb.org/pull/84","diff_url":"https://github.com/rom-rb/rom-rb.org/pull/84.diff","patch_url":"https://github.com/rom-rb/rom-rb.org/pull/84.patch","issue_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/84","number":84,"state":"open","locked":false,"title":"Add guides for rom-repository","user":{"login":"solnic","id":1066,"avatar_url":"https://avatars.githubusercontent.com/u/1066?v=3","gravatar_id":"","url":"https://api.github.com/users/solnic","html_url":"https://github.com/solnic","followers_url":"https://api.github.com/users/solnic/followers","following_url":"https://api.github.com/users/solnic/following{/other_user}","gists_url":"https://api.github.com/users/solnic/gists{/gist_id}","starred_url":"https://api.github.com/users/solnic/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/solnic/subscriptions","organizations_url":"https://api.github.com/users/solnic/orgs","repos_url":"https://api.github.com/users/solnic/repos","events_url":"https://api.github.com/users/solnic/events{/privacy}","received_events_url":"https://api.github.com/users/solnic/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-08-12T11:07:30Z","updated_at":"2015-08-12T12:48:24Z","closed_at":null,"merged_at":null,"merge_commit_sha":"9fae50746dd6cc0fb73d10804596816654479ba1","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84/commits","review_comments_url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84/comments","review_comment_url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/comments{/number}","comments_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/84/comments","statuses_url":"https://api.github.com/repos/rom-rb/rom-rb.org/statuses/f594852f3cd7647f551697c98b8902c9e5768ab5","head":{"label":"rom-rb:repository-guides","ref":"repository-guides","sha":"f594852f3cd7647f551697c98b8902c9e5768ab5","user":{"login":"rom-rb","id":4589832,"avatar_url":"https://avatars.githubusercontent.com/u/4589832?v=3","gravatar_id":"","url":"https://api.github.com/users/rom-rb","html_url":"https://github.com/rom-rb","followers_url":"https://api.github.com/users/rom-rb/followers","following_url":"https://api.github.com/users/rom-rb/following{/other_user}","gists_url":"https://api.github.com/users/rom-rb/gists{/gist_id}","starred_url":"https://api.github.com/users/rom-rb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rom-rb/subscriptions","organizations_url":"https://api.github.com/users/rom-rb/orgs","repos_url":"https://api.github.com/users/rom-rb/repos","events_url":"https://api.github.com/users/rom-rb/events{/privacy}","received_events_url":"https://api.github.com/users/rom-rb/received_events","type":"Organization","site_admin":false},"repo":{"id":10435644,"name":"rom-rb.org","full_name":"rom-rb/rom-rb.org","owner":{"login":"rom-rb","id":4589832,"avatar_url":"https://avatars.githubusercontent.com/u/4589832?v=3","gravatar_id":"","url":"https://api.github.com/users/rom-rb","html_url":"https://github.com/rom-rb","followers_url":"https://api.github.com/users/rom-rb/followers","following_url":"https://api.github.com/users/rom-rb/following{/other_user}","gists_url":"https://api.github.com/users/rom-rb/gists{/gist_id}","starred_url":"https://api.github.com/users/rom-rb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rom-rb/subscriptions","organizations_url":"https://api.github.com/users/rom-rb/orgs","repos_url":"https://api.github.com/users/rom-rb/repos","events_url":"https://api.github.com/users/rom-rb/events{/privacy}","received_events_url":"https://api.github.com/users/rom-rb/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rom-rb/rom-rb.org","description":"Official Ruby Object Mapper website","fork":false,"url":"https://api.github.com/repos/rom-rb/rom-rb.org","forks_url":"https://api.github.com/repos/rom-rb/rom-rb.org/forks","keys_url":"https://api.github.com/repos/rom-rb/rom-rb.org/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rom-rb/rom-rb.org/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rom-rb/rom-rb.org/teams","hooks_url":"https://api.github.com/repos/rom-rb/rom-rb.org/hooks","issue_events_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/events{/number}","events_url":"https://api.github.com/repos/rom-rb/rom-rb.org/events","assignees_url":"https://api.github.com/repos/rom-rb/rom-rb.org/assignees{/user}","branches_url":"https://api.github.com/repos/rom-rb/rom-rb.org/branches{/branch}","tags_url":"https://api.github.com/repos/rom-rb/rom-rb.org/tags","blobs_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/refs{/sha}","trees_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rom-rb/rom-rb.org/statuses/{sha}","languages_url":"https://api.github.com/repos/rom-rb/rom-rb.org/languages","stargazers_url":"https://api.github.com/repos/rom-rb/rom-rb.org/stargazers","contributors_url":"https://api.github.com/repos/rom-rb/rom-rb.org/contributors","subscribers_url":"https://api.github.com/repos/rom-rb/rom-rb.org/subscribers","subscription_url":"https://api.github.com/repos/rom-rb/rom-rb.org/subscription","commits_url":"https://api.github.com/repos/rom-rb/rom-rb.org/commits{/sha}","git_commits_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/commits{/sha}","comments_url":"https://api.github.com/repos/rom-rb/rom-rb.org/comments{/number}","issue_comment_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/comments{/number}","contents_url":"https://api.github.com/repos/rom-rb/rom-rb.org/contents/{+path}","compare_url":"https://api.github.com/repos/rom-rb/rom-rb.org/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rom-rb/rom-rb.org/merges","archive_url":"https://api.github.com/repos/rom-rb/rom-rb.org/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rom-rb/rom-rb.org/downloads","issues_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues{/number}","pulls_url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls{/number}","milestones_url":"https://api.github.com/repos/rom-rb/rom-rb.org/milestones{/number}","notifications_url":"https://api.github.com/repos/rom-rb/rom-rb.org/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rom-rb/rom-rb.org/labels{/name}","releases_url":"https://api.github.com/repos/rom-rb/rom-rb.org/releases{/id}","created_at":"2013-06-02T10:50:47Z","updated_at":"2015-06-12T20:43:51Z","pushed_at":"2015-08-12T12:27:47Z","git_url":"git://github.com/rom-rb/rom-rb.org.git","ssh_url":"git@github.com:rom-rb/rom-rb.org.git","clone_url":"https://github.com/rom-rb/rom-rb.org.git","svn_url":"https://github.com/rom-rb/rom-rb.org","homepage":"http://rom-rb.org/","size":2761,"stargazers_count":10,"watchers_count":10,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":40,"mirror_url":null,"open_issues_count":18,"forks":40,"open_issues":18,"watchers":10,"default_branch":"master"}},"base":{"label":"rom-rb:master","ref":"master","sha":"c209a16355ff19c5e7f41a931f616b0460160fc9","user":{"login":"rom-rb","id":4589832,"avatar_url":"https://avatars.githubusercontent.com/u/4589832?v=3","gravatar_id":"","url":"https://api.github.com/users/rom-rb","html_url":"https://github.com/rom-rb","followers_url":"https://api.github.com/users/rom-rb/followers","following_url":"https://api.github.com/users/rom-rb/following{/other_user}","gists_url":"https://api.github.com/users/rom-rb/gists{/gist_id}","starred_url":"https://api.github.com/users/rom-rb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rom-rb/subscriptions","organizations_url":"https://api.github.com/users/rom-rb/orgs","repos_url":"https://api.github.com/users/rom-rb/repos","events_url":"https://api.github.com/users/rom-rb/events{/privacy}","received_events_url":"https://api.github.com/users/rom-rb/received_events","type":"Organization","site_admin":false},"repo":{"id":10435644,"name":"rom-rb.org","full_name":"rom-rb/rom-rb.org","owner":{"login":"rom-rb","id":4589832,"avatar_url":"https://avatars.githubusercontent.com/u/4589832?v=3","gravatar_id":"","url":"https://api.github.com/users/rom-rb","html_url":"https://github.com/rom-rb","followers_url":"https://api.github.com/users/rom-rb/followers","following_url":"https://api.github.com/users/rom-rb/following{/other_user}","gists_url":"https://api.github.com/users/rom-rb/gists{/gist_id}","starred_url":"https://api.github.com/users/rom-rb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rom-rb/subscriptions","organizations_url":"https://api.github.com/users/rom-rb/orgs","repos_url":"https://api.github.com/users/rom-rb/repos","events_url":"https://api.github.com/users/rom-rb/events{/privacy}","received_events_url":"https://api.github.com/users/rom-rb/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rom-rb/rom-rb.org","description":"Official Ruby Object Mapper website","fork":false,"url":"https://api.github.com/repos/rom-rb/rom-rb.org","forks_url":"https://api.github.com/repos/rom-rb/rom-rb.org/forks","keys_url":"https://api.github.com/repos/rom-rb/rom-rb.org/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rom-rb/rom-rb.org/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rom-rb/rom-rb.org/teams","hooks_url":"https://api.github.com/repos/rom-rb/rom-rb.org/hooks","issue_events_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/events{/number}","events_url":"https://api.github.com/repos/rom-rb/rom-rb.org/events","assignees_url":"https://api.github.com/repos/rom-rb/rom-rb.org/assignees{/user}","branches_url":"https://api.github.com/repos/rom-rb/rom-rb.org/branches{/branch}","tags_url":"https://api.github.com/repos/rom-rb/rom-rb.org/tags","blobs_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/refs{/sha}","trees_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rom-rb/rom-rb.org/statuses/{sha}","languages_url":"https://api.github.com/repos/rom-rb/rom-rb.org/languages","stargazers_url":"https://api.github.com/repos/rom-rb/rom-rb.org/stargazers","contributors_url":"https://api.github.com/repos/rom-rb/rom-rb.org/contributors","subscribers_url":"https://api.github.com/repos/rom-rb/rom-rb.org/subscribers","subscription_url":"https://api.github.com/repos/rom-rb/rom-rb.org/subscription","commits_url":"https://api.github.com/repos/rom-rb/rom-rb.org/commits{/sha}","git_commits_url":"https://api.github.com/repos/rom-rb/rom-rb.org/git/commits{/sha}","comments_url":"https://api.github.com/repos/rom-rb/rom-rb.org/comments{/number}","issue_comment_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/comments{/number}","contents_url":"https://api.github.com/repos/rom-rb/rom-rb.org/contents/{+path}","compare_url":"https://api.github.com/repos/rom-rb/rom-rb.org/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rom-rb/rom-rb.org/merges","archive_url":"https://api.github.com/repos/rom-rb/rom-rb.org/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rom-rb/rom-rb.org/downloads","issues_url":"https://api.github.com/repos/rom-rb/rom-rb.org/issues{/number}","pulls_url":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls{/number}","milestones_url":"https://api.github.com/repos/rom-rb/rom-rb.org/milestones{/number}","notifications_url":"https://api.github.com/repos/rom-rb/rom-rb.org/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rom-rb/rom-rb.org/labels{/name}","releases_url":"https://api.github.com/repos/rom-rb/rom-rb.org/releases{/id}","created_at":"2013-06-02T10:50:47Z","updated_at":"2015-06-12T20:43:51Z","pushed_at":"2015-08-12T12:27:47Z","git_url":"git://github.com/rom-rb/rom-rb.org.git","ssh_url":"git@github.com:rom-rb/rom-rb.org.git","clone_url":"https://github.com/rom-rb/rom-rb.org.git","svn_url":"https://github.com/rom-rb/rom-rb.org","homepage":"http://rom-rb.org/","size":2761,"stargazers_count":10,"watchers_count":10,"language":"HTML","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":40,"mirror_url":null,"open_issues_count":18,"forks":40,"open_issues":18,"watchers":10,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84"},"html":{"href":"https://github.com/rom-rb/rom-rb.org/pull/84"},"issue":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/84"},"comments":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/issues/84/comments"},"review_comments":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84/comments"},"review_comment":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/pulls/84/commits"},"statuses":{"href":"https://api.github.com/repos/rom-rb/rom-rb.org/statuses/f594852f3cd7647f551697c98b8902c9e5768ab5"}}}}