repository-support 0.1.1 → 0.1.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (33) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +0 -1
  3. data/Rakefile +12 -0
  4. data/bin/kramdown +29 -0
  5. data/bin/setup +2 -1
  6. data/bin/yard +29 -0
  7. data/bin/yardoc +29 -0
  8. data/bin/yri +29 -0
  9. data/doc/Repository.html +128 -0
  10. data/doc/Repository/Support.html +140 -0
  11. data/doc/Repository/Support/ErrorFactory.html +205 -0
  12. data/doc/Repository/Support/ResultBuilder.html +274 -0
  13. data/doc/Repository/Support/StoreResult.html +464 -0
  14. data/doc/Repository/Support/StoreResult/Failure.html +227 -0
  15. data/doc/Repository/Support/StoreResult/Success.html +227 -0
  16. data/doc/Repository/Support/TestAttributeContainer.html +282 -0
  17. data/doc/_index.html +188 -0
  18. data/doc/class_list.html +51 -0
  19. data/doc/css/common.css +1 -0
  20. data/doc/css/full_list.css +58 -0
  21. data/doc/css/style.css +499 -0
  22. data/doc/file.README.html +323 -0
  23. data/doc/file_list.html +56 -0
  24. data/doc/frames.html +17 -0
  25. data/doc/index.html +323 -0
  26. data/doc/js/app.js +248 -0
  27. data/doc/js/full_list.js +216 -0
  28. data/doc/js/jquery.js +4 -0
  29. data/doc/method_list.html +131 -0
  30. data/doc/top-level-namespace.html +110 -0
  31. data/lib/repository/support/version.rb +1 -1
  32. data/repository-support.gemspec +4 -2
  33. metadata +58 -4
data/doc/file.README.html ADDED
@@ -0,0 +1,323 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.9.12
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ pathId = "README";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="file_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: README</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'><h1>Repository::Support</h1>
61
+
62
+ <p><a href="http://badge.fury.io/rb/repository-support"><img src="https://badge.fury.io/rb/repository-support.svg" alt="Gem Version" /></a>
63
+ <a href="https://codeclimate.com/github/jdickey/repository-support"><img src="https://codeclimate.com/github/jdickey/repository-support/badges/gpa.svg" alt="Code Climate" /></a>
64
+ <a href="https://codeship.com/projects/63652"> <img src="https://codeship.com/projects/224d6180-997e-0132-c9c3-165733f17d49/status?branch=master" alt="Codeship Status for jdickey/repository-support" /></a>
65
+ <a href="https://hakiri.io/github/jdickey/repository-support/master"><img src="https://hakiri.io/github/jdickey/repository-support/master.svg" alt="security" /></a>
66
+ <a href="https://gemnasium.com/jdickey/repository-support"><img src="https://gemnasium.com/jdickey/repository-support.svg" alt="Dependency Status" /></a></p>
67
+
68
+ <h2>Contents</h2>
69
+
70
+ <ul>
71
+ <li><a href="#overview">Overview</a></li>
72
+ <li><a href="#important-legacy-notice">IMPORTANT LEGACY NOTICE</a></li>
73
+ <li><a href="#installation">Installation</a></li>
74
+ <li><a href="#usage">Usage</a>
75
+ <ul>
76
+ <li><a href="#storeresult"><code>StoreResult</code></a>
77
+ <ul>
78
+ <li><a href="#storeresultsuccess"><code>StoreResult::Success</code></a></li>
79
+ <li><a href="#storeresultfailure"><code>StoreResult::Failure</code></a></li>
80
+ </ul>
81
+ </li>
82
+ <li><a href="#errorfactory"><code>ErrorFactory</code></a></li>
83
+ <li><a href="#testattributecontainer"><code>TestAttributeContainer</code></a></li>
84
+ <li><a href="#a-note-on-parameters">A Note on Parameters</a></li>
85
+ </ul>
86
+ </li>
87
+ <li><a href="#contributing">Contributing</a></li>
88
+ <li><a href="#version-history">Version History</a></li>
89
+ <li><a href="#legal">Legal</a></li>
90
+ </ul>
91
+
92
+ <h2 id="overview">Overview</h2>
93
+
94
+ <p>This Gem provides several support classes and modules for
95
+ <a href="https://github.com/jdickey/repository-base"><code>Repository::Base</code></a> and its
96
+ user-created subclasses, which implement the Repository layer of a typical Data
97
+ Mapper pattern architecture.</p>
98
+
99
+ <p>These classes and modules are:</p>
100
+
101
+ <ul>
102
+ <li><code>ErrorFactory</code> provides a single class method, <code>.create</code> which, when supplied with an <code>ActiveModel::Errors</code>-quacking object as a parameter, produces an Array of Hashes containing JSON-compatible error information;</li>
103
+ <li><code>ResultBuilder</code> is a Command-pattern class whose <code>#initialize</code> method takes one parameter and whose <code>#build</code> method evaluates that value. If it is truthy, then <code>#build</code> returns a <code>StoreResult::Success</code> (see below) with that value as its “paylaaod”. If the value is falsy, then <code>#build</code> returns a <code>StoreResult#Failure</code>, yielding the value to a block that returns the payload for the <code>StoreResult</code>.</li>
104
+ <li><code>StoreResult</code> is a simple value object with three accessors for values passed in to the <code>#initialize</code> method: namely <code>#entity</code> (some value object); <code>#success</code> (a Boolean, aliased as <code>#success?</code>); and <code>#errors</code> an Array of error records as created by <code>ErrorFactory.create</code>. It has two subclasses: <code>StoreResult::Success</code> fills in a <code>StoreResult</code> using its single parameter (the entity) and defaults for the other fields; and <code>StoreResult::Failure</code>, which does likewise initialised with an array of error hashes.</li>
105
+ <li><code>TestAttributeContainer</code> is a module that, when used to extend a class, adds an <code>attributes</code> Hash property (reader and writer) to the extending class. While <code>attributes</code> is initially empty, it may be added to either by defining a single key, or by mass-assigning a Hash to <code>attributes</code>. Once an individual “attribute” is defined for a class instance, it can be read from or written to using a direct method on that instance. See the discussion in “Usage” below for more details.</li>
106
+ </ul>
107
+
108
+ <h2 id="important-legacy-notice">IMPORTANT LEGACY NOTICE</h2>
109
+
110
+ <p><strong><em>NOTICE!</em></strong> This Gem was created to support a solo, ad-hoc, early learning experience in what is now known as Clean Architecture. It was part of our first attempt to build an alternative to the ActiveRecord/ActiveModel scheme native to Ruby on Rails.</p>
111
+
112
+ <p>As such, it has been superseded and far outshone by other, team efforts, notably <a href="http://rom-rb.org/">ROM</a> as used with <a href="http://hanamirb.org/">Hanami</a> and <a href="http://trailblazer.to/">Trailblazer</a>. You are <em>strongly advised</em> to examine these and other tools rather than to use this for <em>any</em> new development. The Gem is being republished as an 0.1.0 release purely for internal archaeologigical purposes.</p>
113
+
114
+ <h2 id="installation">Installation</h2>
115
+
116
+ <p>Add this line to your application’s Gemfile:</p>
117
+
118
+ <p><code>ruby
119
+ gem 'repository-support'
120
+ </code></p>
121
+
122
+ <p>And then execute:</p>
123
+
124
+ <pre class="code ruby"><code class="ruby">$ bundle
125
+ </code></pre>
126
+
127
+ <p>Or install it yourself as:</p>
128
+
129
+ <pre class="code ruby"><code class="ruby">$ gem install repository-support
130
+ </code></pre>
131
+
132
+ <h2 id="usage">Usage</h2>
133
+
134
+ <h3 id="storeresult"><code>StoreResult</code></h3>
135
+
136
+ <p><code>StoreReult</code> is used as the return value from all <code>Repository::Base</code> instance
137
+ methods (actions) <em>except</em> <code>#all</code>.</p>
138
+
139
+ <p>If the action implemented by the method was successful, it returns a
140
+ <code>StoreResult</code> where</p>
141
+
142
+ <ul>
143
+ <li>the <code>entity</code> attribute is an entity matching the state of the record persisted or accessed by the action;</li>
144
+ <li>the <code>success</code> attribute (or <code>#success?</code> method) is <code>true</code>; and</li>
145
+ <li>the <code>errors</code> attribute is an empty Array.</li>
146
+ </ul>
147
+
148
+ <p>If the action was unsuccessful, the repository method returns a <code>StoreResult</code>
149
+ where</p>
150
+
151
+ <ul>
152
+ <li>the <code>entity</code> attribute is <code>nil</code>;</li>
153
+ <li>the <code>success</code> attribute (or <code>#success?</code> method) is <code>false</code>; and</li>
154
+ <li>the <code>errors</code> attribute contains one error Hash for each error preventing the action from succeeding.</li>
155
+ </ul>
156
+
157
+ <h4 id="storeresultsuccess"><code>StoreResult::Success</code></h4>
158
+
159
+ <p>This subclass of <code>StoreResult</code> is a convenience for initialising a successful
160
+ <code>StoreResult</code>. Its <code>#initialize</code> method takes a single parameter, the entity to
161
+ be used in the result, with the other fields set as described above for a
162
+ successful result.</p>
163
+
164
+ <h4 id="storeresultfailure"><code>StoreResult::Failure</code></h4>
165
+
166
+ <p>This subclass of <code>StoreResult</code> is a convenience for initialising an unsuccessful
167
+ <code>StoreResult</code>. Its <code>#initialize</code> method takes a single parameter, the Array of
168
+ error hashes to be used in the result, with the other fields set as described
169
+ above for an unsuccessful result.</p>
170
+
171
+ <h3 id="errorfactory"><code>ErrorFactory</code></h3>
172
+
173
+ <p>This class has a single class method, <code>.create</code>. Given a parameter value that
174
+ quacks as an<a href="http://api.rubyonrails.org/classes/ActiveModel/Errors.html"><code>ActiveModel::Errors</code></a>
175
+ instance, it returns an Array where each item is a Hash derived from each error
176
+ reported by the parameter object, or an empty Array if there are no errors. Each
177
+ Hash in the Array has two fields:</p>
178
+
179
+ <ol>
180
+ <li><code>field</code>, which contains the attribute passed to <a href="http://api.rubyonrails.org/classes/ActiveModel/Errors.html#method-i-add"><code>ActiveModel::Errors#add</code></a> <em>as a string</em>; and</li>
181
+ <li><code>message</code>, which contains the message as passed into the same <code>#add</code> call.</li>
182
+ </ol>
183
+
184
+ <p>So, given an <code>ActiveModel::Errors</code> object that resulted from the following code:</p>
185
+
186
+ <p><code>ruby
187
+ errors = ActiveModel::Errors.new self
188
+ # ...
189
+ errors.add :frobulator, 'does not frob'
190
+ errors.add :frobulator, `is busted'
191
+ errors.add :foo, 'is :foo'
192
+ # ...
193
+ error_data = ErrorFactory.create errors
194
+ @logger.log error_data
195
+ </code></p>
196
+
197
+ <p>the value of <code>error_data</code> written to the log would be (formatted for clarity)</p>
198
+
199
+ <p><code>
200
+ [
201
+ {field: 'frobulator', message: 'does not frob'},
202
+ {field: 'frobulator', message: 'is busted'},
203
+ {field: 'foo', 'is :foo'}
204
+ ]
205
+ </code></p>
206
+
207
+ <p>Note that no guarantees are made for ordering, just as seems to be the case for
208
+ <code>ActiveModel::Errors</code>.</p>
209
+
210
+ <h3 id="testattributecontainer"><code>TestAttributeContainer</code></h3>
211
+
212
+ <p>This module implements support for attributes in a way that can be thought of as “halfway between a <a href="http://ruby-doc.org//core-2.1.5/Struct.html"><code>Struct</code></a> and an <a href="http://ruby-doc.org/stdlib-2.1.5/libdoc/ostruct/rdoc/OpenStruct.html"><code>OpenStruct</code></a> or <a href="https://github.com/tomchapin/fancy-open-struct/"><code>FancyOpenStruct</code></a>.”</p>
213
+
214
+ <p>By extending a class with the module and invoking the <code>init_empty_attribute_container</code> class method within that class, a Hash is added as the <code>attributes</code> attribute of each instance of that class. It can be assigned to directly; once having done so, individual “attributes” may be accessed <em>or modified</em> through a method call using the name of the attribute.</p>
215
+
216
+ <p>For example:</p>
217
+
218
+ <p>```ruby
219
+ class Foo
220
+ extend Repository::Support::TestAttributeContainer</p>
221
+
222
+ <p>init_empty_attribute_container
223
+ end</p>
224
+
225
+ <h1 id="interactively">interactively</h1>
226
+ <p>foo = Foo.new
227
+ # =&gt; #<Foo:0x007fd2b4b9da28>
228
+ foo.attributes
229
+ # =&gt; {}
230
+ foo.attributes = { foo: true, bar: 42 }
231
+ # =&gt; :bar=&gt;42
232
+ foo.foo
233
+ # =&gt; true
234
+ foo.foo = :whatever_you_want
235
+ # =&gt; :whatever_you_want
236
+ foo.attributes
237
+ # =&gt; :bar=&gt;42
238
+ foo.quux
239
+ # =&gt; NoMethodError: undefined method `quux' # ...
240
+ foo.attributes[:quux] = 'hello'
241
+ # =&gt; "hello"
242
+ foo.quux
243
+ # =&gt; "hello"
244
+ ```</Foo:0x007fd2b4b9da28></p>
245
+
246
+ <p>To create a new attribute after the container has been set up, assign to a new key in the <code>attributes</code> property Hash. As demonstrated above, the “attribute” can then be accessed or modified by using its name as a reader or writer method name. Without explicitly assigning to <code>attributes</code>, however, undefined methods raise errors as usual.</p>
247
+
248
+ <h3 id="a-note-on-parameters">A Note on Parameters</h3>
249
+
250
+ <p>All <em>public</em> methods having multiple arguments (including <code>#initialize</code>) in each
251
+ of the classes defined above use the keyword-argument specification introduced
252
+ in Ruby 2.0. By removing order dependency of arguments, inadvertent-reordering
253
+ errors are no longer a
254
+ <a href="http://en.wikipedia.org/wiki/Hunt_the_Wumpus">hunt-the-typo</a>
255
+ exercise. This rule <em>does not</em> apply to single-parameter methods, nor to
256
+ <code>private</code> methods.</p>
257
+
258
+ <h2 id="contributing">Contributing</h2>
259
+
260
+ <ol>
261
+ <li>Fork it ( https://github.com/jdickey/repository-support/fork )</li>
262
+ <li>Create your feature branch (<code>git checkout -b my-new-feature</code>)</li>
263
+ <li>Ensure that your changes are completely covered by <em>passing</em> specs, and comply with the <a href="https://github.com/bbatsov/ruby-style-guide">Ruby Style Guide</a> as enforced by <a href="https://github.com/bbatsov/rubocop">RuboCop</a>. To verify this, run <code>bundle exec rake</code>, noting and repairing any lapses in coverage or style violations;</li>
264
+ <li>Commit your changes (<code>git commit -a</code>). Please <em>do not</em> use a single-line commit message (<code>git commit -am "some message"</code>). A good commit message notes what was changed and why in sufficient detail that a relative newcomer to the code can understand your reasoning and your code;</li>
265
+ <li>Push to the branch (<code>git push origin my-new-feature</code>)</li>
266
+ <li>Create a new Pull Request. Describe at some length the rationale for your new feature; your implementation strategy at a higher level than each individual commit message; anything future maintainers should be aware of; and so on. <em>If this is a modification to existing code, reference the open issue being addressed</em>.</li>
267
+ <li>Don’t be discouraged if the PR generates a discussion that leads to further refinement of your PR through additional commits. These should <em>generally</em> be discussed in comments on the PR itself; discussion in the Gitter room (see below) may also be useful;</li>
268
+ <li>If you’ve comments, questions, or just want to talk through your ideas, don’t hesitate to hang out in the <code>Repository::Base</code> <a href="https://gitter.im/jdickey/repository-base">room on Gitter</a>. Ask away!</li>
269
+ </ol>
270
+
271
+ <h2 id="version-history">Version History</h2>
272
+
273
+ <table>
274
+ <thead>
275
+ <tr>
276
+ <th>Version</th>
277
+ <th>Date</th>
278
+ <th>Notes</th>
279
+ </tr>
280
+ </thead>
281
+ <tbody>
282
+ <tr>
283
+ <td>v0.1.0</td>
284
+ <td>2 February 2018</td>
285
+ <td>Changed MRI supported version from 2.2.2 to 2.5.0; <strong>published legacy notice</strong></td>
286
+ </tr>
287
+ <tr>
288
+ <td>v0.0.4</td>
289
+ <td>9 March 2015</td>
290
+ <td>Added experimental, one-off JRuby 9000 support</td>
291
+ </tr>
292
+ <tr>
293
+ <td>v0.0.3</td>
294
+ <td>21 February 2015</td>
295
+ <td>Completed initial feature development</td>
296
+ </tr>
297
+ <tr>
298
+ <td>v0.0.2</td>
299
+ <td>18 February 2015</td>
300
+ <td>Internal; incremental feature development</td>
301
+ </tr>
302
+ <tr>
303
+ <td>v0.0.1</td>
304
+ <td>18 February 2015</td>
305
+ <td>Internal; incremental feature development</td>
306
+ </tr>
307
+ </tbody>
308
+ </table>
309
+
310
+ <h2 id="legal">Legal</h2>
311
+
312
+ <p>This document and the accompanying code are Copyright © 2015-2018 by Jeff Dickey/Seven Sigma Agility, and are released under the terms of the <a href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
313
+ </div></div>
314
+
315
+ <div id="footer">
316
+ Generated on Sun Feb 4 17:26:37 2018 by
317
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
318
+ 0.9.12 (ruby-2.5.0).
319
+ </div>
320
+
321
+ </div>
322
+ </body>
323
+ </html>
data/doc/file_list.html ADDED
@@ -0,0 +1,56 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
5
+ <meta charset="utf-8" />
6
+
7
+ <link rel="stylesheet" href="css/full_list.css" type="text/css" media="screen" charset="utf-8" />
8
+
9
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
10
+
11
+
12
+
13
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
14
+
15
+ <script type="text/javascript" charset="utf-8" src="js/full_list.js"></script>
16
+
17
+
18
+ <title>File List</title>
19
+ <base id="base_target" target="_parent" />
20
+ </head>
21
+ <body>
22
+ <div id="content">
23
+ <div class="fixed_header">
24
+ <h1 id="full_list_header">File List</h1>
25
+ <div id="full_list_nav">
26
+
27
+ <span><a target="_self" href="class_list.html">
28
+ Classes
29
+ </a></span>
30
+
31
+ <span><a target="_self" href="method_list.html">
32
+ Methods
33
+ </a></span>
34
+
35
+ <span><a target="_self" href="file_list.html">
36
+ Files
37
+ </a></span>
38
+
39
+ </div>
40
+
41
+ <div id="search">Search: <input type="text" /></div>
42
+ </div>
43
+
44
+ <ul id="full_list" class="file">
45
+
46
+
47
+ <li id="object_README" class="odd">
48
+ <div class="item"><span class="object_link"><a href="index.html" title="README">README</a></span></div>
49
+ </li>
50
+
51
+
52
+
53
+ </ul>
54
+ </div>
55
+ </body>
56
+ </html>
data/doc/frames.html ADDED
@@ -0,0 +1,17 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Documentation by YARD 0.9.12</title>
6
+ </head>
7
+ <script type="text/javascript" charset="utf-8">
8
+ var match = unescape(window.location.hash).match(/^#!(.+)/);
9
+ var name = match ? match[1] : 'index.html';
10
+ name = name.replace(/^(\w+):\/\//, '').replace(/^\/\//, '');
11
+ window.top.location = name;
12
+ </script>
13
+ <noscript>
14
+ <h1>Oops!</h1>
15
+ <h2>YARD requires JavaScript!</h2>
16
+ </noscript>
17
+ </html>
data/doc/index.html ADDED
@@ -0,0 +1,323 @@
1
+ <!DOCTYPE html>
2
+ <html>
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>
7
+ File: README
8
+
9
+ &mdash; Documentation by YARD 0.9.12
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ pathId = "README";
19
+ relpath = '';
20
+ </script>
21
+
22
+
23
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
24
+
25
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
26
+
27
+
28
+ </head>
29
+ <body>
30
+ <div class="nav_wrap">
31
+ <iframe id="nav" src="class_list.html?1"></iframe>
32
+ <div id="resizer"></div>
33
+ </div>
34
+
35
+ <div id="main" tabindex="-1">
36
+ <div id="header">
37
+ <div id="menu">
38
+
39
+ <a href="_index.html">Index</a> &raquo;
40
+ <span class="title">File: README</span>
41
+
42
+ </div>
43
+
44
+ <div id="search">
45
+
46
+ <a class="full_list_link" id="class_list_link"
47
+ href="class_list.html">
48
+
49
+ <svg width="24" height="24">
50
+ <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
51
+ <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
52
+ <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
53
+ </svg>
54
+ </a>
55
+
56
+ </div>
57
+ <div class="clear"></div>
58
+ </div>
59
+
60
+ <div id="content"><div id='filecontents'><h1>Repository::Support</h1>
61
+
62
+ <p><a href="http://badge.fury.io/rb/repository-support"><img src="https://badge.fury.io/rb/repository-support.svg" alt="Gem Version" /></a>
63
+ <a href="https://codeclimate.com/github/jdickey/repository-support"><img src="https://codeclimate.com/github/jdickey/repository-support/badges/gpa.svg" alt="Code Climate" /></a>
64
+ <a href="https://codeship.com/projects/63652"> <img src="https://codeship.com/projects/224d6180-997e-0132-c9c3-165733f17d49/status?branch=master" alt="Codeship Status for jdickey/repository-support" /></a>
65
+ <a href="https://hakiri.io/github/jdickey/repository-support/master"><img src="https://hakiri.io/github/jdickey/repository-support/master.svg" alt="security" /></a>
66
+ <a href="https://gemnasium.com/jdickey/repository-support"><img src="https://gemnasium.com/jdickey/repository-support.svg" alt="Dependency Status" /></a></p>
67
+
68
+ <h2>Contents</h2>
69
+
70
+ <ul>
71
+ <li><a href="#overview">Overview</a></li>
72
+ <li><a href="#important-legacy-notice">IMPORTANT LEGACY NOTICE</a></li>
73
+ <li><a href="#installation">Installation</a></li>
74
+ <li><a href="#usage">Usage</a>
75
+ <ul>
76
+ <li><a href="#storeresult"><code>StoreResult</code></a>
77
+ <ul>
78
+ <li><a href="#storeresultsuccess"><code>StoreResult::Success</code></a></li>
79
+ <li><a href="#storeresultfailure"><code>StoreResult::Failure</code></a></li>
80
+ </ul>
81
+ </li>
82
+ <li><a href="#errorfactory"><code>ErrorFactory</code></a></li>
83
+ <li><a href="#testattributecontainer"><code>TestAttributeContainer</code></a></li>
84
+ <li><a href="#a-note-on-parameters">A Note on Parameters</a></li>
85
+ </ul>
86
+ </li>
87
+ <li><a href="#contributing">Contributing</a></li>
88
+ <li><a href="#version-history">Version History</a></li>
89
+ <li><a href="#legal">Legal</a></li>
90
+ </ul>
91
+
92
+ <h2 id="overview">Overview</h2>
93
+
94
+ <p>This Gem provides several support classes and modules for
95
+ <a href="https://github.com/jdickey/repository-base"><code>Repository::Base</code></a> and its
96
+ user-created subclasses, which implement the Repository layer of a typical Data
97
+ Mapper pattern architecture.</p>
98
+
99
+ <p>These classes and modules are:</p>
100
+
101
+ <ul>
102
+ <li><code>ErrorFactory</code> provides a single class method, <code>.create</code> which, when supplied with an <code>ActiveModel::Errors</code>-quacking object as a parameter, produces an Array of Hashes containing JSON-compatible error information;</li>
103
+ <li><code>ResultBuilder</code> is a Command-pattern class whose <code>#initialize</code> method takes one parameter and whose <code>#build</code> method evaluates that value. If it is truthy, then <code>#build</code> returns a <code>StoreResult::Success</code> (see below) with that value as its “paylaaod”. If the value is falsy, then <code>#build</code> returns a <code>StoreResult#Failure</code>, yielding the value to a block that returns the payload for the <code>StoreResult</code>.</li>
104
+ <li><code>StoreResult</code> is a simple value object with three accessors for values passed in to the <code>#initialize</code> method: namely <code>#entity</code> (some value object); <code>#success</code> (a Boolean, aliased as <code>#success?</code>); and <code>#errors</code> an Array of error records as created by <code>ErrorFactory.create</code>. It has two subclasses: <code>StoreResult::Success</code> fills in a <code>StoreResult</code> using its single parameter (the entity) and defaults for the other fields; and <code>StoreResult::Failure</code>, which does likewise initialised with an array of error hashes.</li>
105
+ <li><code>TestAttributeContainer</code> is a module that, when used to extend a class, adds an <code>attributes</code> Hash property (reader and writer) to the extending class. While <code>attributes</code> is initially empty, it may be added to either by defining a single key, or by mass-assigning a Hash to <code>attributes</code>. Once an individual “attribute” is defined for a class instance, it can be read from or written to using a direct method on that instance. See the discussion in “Usage” below for more details.</li>
106
+ </ul>
107
+
108
+ <h2 id="important-legacy-notice">IMPORTANT LEGACY NOTICE</h2>
109
+
110
+ <p><strong><em>NOTICE!</em></strong> This Gem was created to support a solo, ad-hoc, early learning experience in what is now known as Clean Architecture. It was part of our first attempt to build an alternative to the ActiveRecord/ActiveModel scheme native to Ruby on Rails.</p>
111
+
112
+ <p>As such, it has been superseded and far outshone by other, team efforts, notably <a href="http://rom-rb.org/">ROM</a> as used with <a href="http://hanamirb.org/">Hanami</a> and <a href="http://trailblazer.to/">Trailblazer</a>. You are <em>strongly advised</em> to examine these and other tools rather than to use this for <em>any</em> new development. The Gem is being republished as an 0.1.0 release purely for internal archaeologigical purposes.</p>
113
+
114
+ <h2 id="installation">Installation</h2>
115
+
116
+ <p>Add this line to your application’s Gemfile:</p>
117
+
118
+ <p><code>ruby
119
+ gem 'repository-support'
120
+ </code></p>
121
+
122
+ <p>And then execute:</p>
123
+
124
+ <pre class="code ruby"><code class="ruby">$ bundle
125
+ </code></pre>
126
+
127
+ <p>Or install it yourself as:</p>
128
+
129
+ <pre class="code ruby"><code class="ruby">$ gem install repository-support
130
+ </code></pre>
131
+
132
+ <h2 id="usage">Usage</h2>
133
+
134
+ <h3 id="storeresult"><code>StoreResult</code></h3>
135
+
136
+ <p><code>StoreReult</code> is used as the return value from all <code>Repository::Base</code> instance
137
+ methods (actions) <em>except</em> <code>#all</code>.</p>
138
+
139
+ <p>If the action implemented by the method was successful, it returns a
140
+ <code>StoreResult</code> where</p>
141
+
142
+ <ul>
143
+ <li>the <code>entity</code> attribute is an entity matching the state of the record persisted or accessed by the action;</li>
144
+ <li>the <code>success</code> attribute (or <code>#success?</code> method) is <code>true</code>; and</li>
145
+ <li>the <code>errors</code> attribute is an empty Array.</li>
146
+ </ul>
147
+
148
+ <p>If the action was unsuccessful, the repository method returns a <code>StoreResult</code>
149
+ where</p>
150
+
151
+ <ul>
152
+ <li>the <code>entity</code> attribute is <code>nil</code>;</li>
153
+ <li>the <code>success</code> attribute (or <code>#success?</code> method) is <code>false</code>; and</li>
154
+ <li>the <code>errors</code> attribute contains one error Hash for each error preventing the action from succeeding.</li>
155
+ </ul>
156
+
157
+ <h4 id="storeresultsuccess"><code>StoreResult::Success</code></h4>
158
+
159
+ <p>This subclass of <code>StoreResult</code> is a convenience for initialising a successful
160
+ <code>StoreResult</code>. Its <code>#initialize</code> method takes a single parameter, the entity to
161
+ be used in the result, with the other fields set as described above for a
162
+ successful result.</p>
163
+
164
+ <h4 id="storeresultfailure"><code>StoreResult::Failure</code></h4>
165
+
166
+ <p>This subclass of <code>StoreResult</code> is a convenience for initialising an unsuccessful
167
+ <code>StoreResult</code>. Its <code>#initialize</code> method takes a single parameter, the Array of
168
+ error hashes to be used in the result, with the other fields set as described
169
+ above for an unsuccessful result.</p>
170
+
171
+ <h3 id="errorfactory"><code>ErrorFactory</code></h3>
172
+
173
+ <p>This class has a single class method, <code>.create</code>. Given a parameter value that
174
+ quacks as an<a href="http://api.rubyonrails.org/classes/ActiveModel/Errors.html"><code>ActiveModel::Errors</code></a>
175
+ instance, it returns an Array where each item is a Hash derived from each error
176
+ reported by the parameter object, or an empty Array if there are no errors. Each
177
+ Hash in the Array has two fields:</p>
178
+
179
+ <ol>
180
+ <li><code>field</code>, which contains the attribute passed to <a href="http://api.rubyonrails.org/classes/ActiveModel/Errors.html#method-i-add"><code>ActiveModel::Errors#add</code></a> <em>as a string</em>; and</li>
181
+ <li><code>message</code>, which contains the message as passed into the same <code>#add</code> call.</li>
182
+ </ol>
183
+
184
+ <p>So, given an <code>ActiveModel::Errors</code> object that resulted from the following code:</p>
185
+
186
+ <p><code>ruby
187
+ errors = ActiveModel::Errors.new self
188
+ # ...
189
+ errors.add :frobulator, 'does not frob'
190
+ errors.add :frobulator, `is busted'
191
+ errors.add :foo, 'is :foo'
192
+ # ...
193
+ error_data = ErrorFactory.create errors
194
+ @logger.log error_data
195
+ </code></p>
196
+
197
+ <p>the value of <code>error_data</code> written to the log would be (formatted for clarity)</p>
198
+
199
+ <p><code>
200
+ [
201
+ {field: 'frobulator', message: 'does not frob'},
202
+ {field: 'frobulator', message: 'is busted'},
203
+ {field: 'foo', 'is :foo'}
204
+ ]
205
+ </code></p>
206
+
207
+ <p>Note that no guarantees are made for ordering, just as seems to be the case for
208
+ <code>ActiveModel::Errors</code>.</p>
209
+
210
+ <h3 id="testattributecontainer"><code>TestAttributeContainer</code></h3>
211
+
212
+ <p>This module implements support for attributes in a way that can be thought of as “halfway between a <a href="http://ruby-doc.org//core-2.1.5/Struct.html"><code>Struct</code></a> and an <a href="http://ruby-doc.org/stdlib-2.1.5/libdoc/ostruct/rdoc/OpenStruct.html"><code>OpenStruct</code></a> or <a href="https://github.com/tomchapin/fancy-open-struct/"><code>FancyOpenStruct</code></a>.”</p>
213
+
214
+ <p>By extending a class with the module and invoking the <code>init_empty_attribute_container</code> class method within that class, a Hash is added as the <code>attributes</code> attribute of each instance of that class. It can be assigned to directly; once having done so, individual “attributes” may be accessed <em>or modified</em> through a method call using the name of the attribute.</p>
215
+
216
+ <p>For example:</p>
217
+
218
+ <p>```ruby
219
+ class Foo
220
+ extend Repository::Support::TestAttributeContainer</p>
221
+
222
+ <p>init_empty_attribute_container
223
+ end</p>
224
+
225
+ <h1 id="interactively">interactively</h1>
226
+ <p>foo = Foo.new
227
+ # =&gt; #<Foo:0x007fd2b4b9da28>
228
+ foo.attributes
229
+ # =&gt; {}
230
+ foo.attributes = { foo: true, bar: 42 }
231
+ # =&gt; :bar=&gt;42
232
+ foo.foo
233
+ # =&gt; true
234
+ foo.foo = :whatever_you_want
235
+ # =&gt; :whatever_you_want
236
+ foo.attributes
237
+ # =&gt; :bar=&gt;42
238
+ foo.quux
239
+ # =&gt; NoMethodError: undefined method `quux' # ...
240
+ foo.attributes[:quux] = 'hello'
241
+ # =&gt; "hello"
242
+ foo.quux
243
+ # =&gt; "hello"
244
+ ```</Foo:0x007fd2b4b9da28></p>
245
+
246
+ <p>To create a new attribute after the container has been set up, assign to a new key in the <code>attributes</code> property Hash. As demonstrated above, the “attribute” can then be accessed or modified by using its name as a reader or writer method name. Without explicitly assigning to <code>attributes</code>, however, undefined methods raise errors as usual.</p>
247
+
248
+ <h3 id="a-note-on-parameters">A Note on Parameters</h3>
249
+
250
+ <p>All <em>public</em> methods having multiple arguments (including <code>#initialize</code>) in each
251
+ of the classes defined above use the keyword-argument specification introduced
252
+ in Ruby 2.0. By removing order dependency of arguments, inadvertent-reordering
253
+ errors are no longer a
254
+ <a href="http://en.wikipedia.org/wiki/Hunt_the_Wumpus">hunt-the-typo</a>
255
+ exercise. This rule <em>does not</em> apply to single-parameter methods, nor to
256
+ <code>private</code> methods.</p>
257
+
258
+ <h2 id="contributing">Contributing</h2>
259
+
260
+ <ol>
261
+ <li>Fork it ( https://github.com/jdickey/repository-support/fork )</li>
262
+ <li>Create your feature branch (<code>git checkout -b my-new-feature</code>)</li>
263
+ <li>Ensure that your changes are completely covered by <em>passing</em> specs, and comply with the <a href="https://github.com/bbatsov/ruby-style-guide">Ruby Style Guide</a> as enforced by <a href="https://github.com/bbatsov/rubocop">RuboCop</a>. To verify this, run <code>bundle exec rake</code>, noting and repairing any lapses in coverage or style violations;</li>
264
+ <li>Commit your changes (<code>git commit -a</code>). Please <em>do not</em> use a single-line commit message (<code>git commit -am "some message"</code>). A good commit message notes what was changed and why in sufficient detail that a relative newcomer to the code can understand your reasoning and your code;</li>
265
+ <li>Push to the branch (<code>git push origin my-new-feature</code>)</li>
266
+ <li>Create a new Pull Request. Describe at some length the rationale for your new feature; your implementation strategy at a higher level than each individual commit message; anything future maintainers should be aware of; and so on. <em>If this is a modification to existing code, reference the open issue being addressed</em>.</li>
267
+ <li>Don’t be discouraged if the PR generates a discussion that leads to further refinement of your PR through additional commits. These should <em>generally</em> be discussed in comments on the PR itself; discussion in the Gitter room (see below) may also be useful;</li>
268
+ <li>If you’ve comments, questions, or just want to talk through your ideas, don’t hesitate to hang out in the <code>Repository::Base</code> <a href="https://gitter.im/jdickey/repository-base">room on Gitter</a>. Ask away!</li>
269
+ </ol>
270
+
271
+ <h2 id="version-history">Version History</h2>
272
+
273
+ <table>
274
+ <thead>
275
+ <tr>
276
+ <th>Version</th>
277
+ <th>Date</th>
278
+ <th>Notes</th>
279
+ </tr>
280
+ </thead>
281
+ <tbody>
282
+ <tr>
283
+ <td>v0.1.0</td>
284
+ <td>2 February 2018</td>
285
+ <td>Changed MRI supported version from 2.2.2 to 2.5.0; <strong>published legacy notice</strong></td>
286
+ </tr>
287
+ <tr>
288
+ <td>v0.0.4</td>
289
+ <td>9 March 2015</td>
290
+ <td>Added experimental, one-off JRuby 9000 support</td>
291
+ </tr>
292
+ <tr>
293
+ <td>v0.0.3</td>
294
+ <td>21 February 2015</td>
295
+ <td>Completed initial feature development</td>
296
+ </tr>
297
+ <tr>
298
+ <td>v0.0.2</td>
299
+ <td>18 February 2015</td>
300
+ <td>Internal; incremental feature development</td>
301
+ </tr>
302
+ <tr>
303
+ <td>v0.0.1</td>
304
+ <td>18 February 2015</td>
305
+ <td>Internal; incremental feature development</td>
306
+ </tr>
307
+ </tbody>
308
+ </table>
309
+
310
+ <h2 id="legal">Legal</h2>
311
+
312
+ <p>This document and the accompanying code are Copyright © 2015-2018 by Jeff Dickey/Seven Sigma Agility, and are released under the terms of the <a href="https://opensource.org/licenses/MIT">MIT License</a>.</p>
313
+ </div></div>
314
+
315
+ <div id="footer">
316
+ Generated on Sun Feb 4 17:26:37 2018 by
317
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
318
+ 0.9.12 (ruby-2.5.0).
319
+ </div>
320
+
321
+ </div>
322
+ </body>
323
+ </html>