inquery 1.0.11 → 1.1.0

data/doc/Inquery/Query.html

@@ -6,7 +6,7 @@
 <title>
   Class: Inquery::Query
   
-    &mdash; Documentation by YARD 0.9.27
+    &mdash; Documentation by YARD 0.9.37
   
 </title>
 
@@ -104,7 +104,31 @@
   
 </div>
 
-<div id="subclasses">
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+    
+<p>Base query class that encapsulates database queries in reusable classes.</p>
+
+<p>Subclasses must implement the ‘call’ method to define the query logic. Optionally, override ‘process’ to transform the query results.</p>
+
+<p>Example:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>FetchActiveUsers</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="../Inquery.html" title="Inquery (module)">Inquery</a></span></span><span class='op'>::</span><span class='const'>Query</span>
+  <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
+    <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>active:</span> <span class='kw'>true</span><span class='rparen'>)</span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+
+<span class='const'>FetchActiveUsers</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span> <span class='comment'># =&gt; Returns active users
+</span></code></pre>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><div id="subclasses">
   <h2>Direct Known Subclasses</h2>
   <p class="children"><span class='object_link'><a href="Query/Chainable.html" title="Inquery::Query::Chainable (class)">Chainable</a></span></p>
 </div>
@@ -147,7 +171,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Returns the value of attribute params.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Returns the value of attribute params.</p>
 </div></span>
   
 </li>
@@ -183,7 +208,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Instantiates the query class using the given arguments and runs <code>call</code> on it.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Instantiates the query class with the given params and executes only the ‘call’ method, skipping post-processing.</p>
 </div></span>
   
 </li>
@@ -206,7 +232,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Instantiates the query class using the given arguments and runs <code>call</code> and <code>process</code> on it.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Instantiates the query class with the given params and executes both ‘call’ and ‘process’ methods.</p>
 </div></span>
   
 </li>
@@ -238,7 +265,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Override this method to perform the actual query.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Override this method in subclasses to define the query logic.</p>
 </div></span>
   
 </li>
@@ -247,7 +275,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#connection-instance_method" title="#connection (instance method)">#<strong>connection</strong>  &#x21d2; Object </a>
+      <a href="#connection-instance_method" title="#connection (instance method)">#<strong>connection</strong>  &#x21d2; ActiveRecord::ConnectionAdapters::AbstractAdapter </a>
     
 
     
@@ -261,7 +289,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Provides a connection to the database.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Returns the database connection to use for this query.</p>
 </div></span>
   
 </li>
@@ -286,7 +315,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Instantiates the query class and validates the given params hash (if there was a validation schema specified).</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Initializes a new query instance with the given parameters.</p>
 </div></span>
   
 </li>
@@ -295,7 +325,7 @@
         <li class="public ">
   <span class="summary_signature">
     
-      <a href="#osparams-instance_method" title="#osparams (instance method)">#<strong>osparams</strong>  &#x21d2; Object </a>
+      <a href="#osparams-instance_method" title="#osparams (instance method)">#<strong>osparams</strong>  &#x21d2; MethodAccessibleHash </a>
     
 
     
@@ -309,7 +339,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Returns a copy of the query&#39;s params, wrapped in an OpenStruct object for easyer access.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Returns the query params wrapped in a MethodAccessibleHash for convenient access using dot notation.</p>
 </div></span>
   
 </li>
@@ -332,7 +363,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Override this method to perform an optional result postprocessing.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Override this method in subclasses to transform the query results.</p>
 </div></span>
   
 </li>
@@ -355,7 +387,8 @@
   
 
   
-    <span class="summary_desc"><div class='inline'><p>Runs both <code>call</code> and <code>process</code>.</p>
+    <span class="summary_desc"><div class='inline'>
+<p>Executes the query by calling ‘call’ and then ‘process’.</p>
 </div></span>
   
 </li>
@@ -392,14 +425,56 @@
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Instantiates the query class and validates the given params hash (if there
-was a validation schema specified).</p>
+    
+<p>Initializes a new query instance with the given parameters.</p>
+
+<p>If a schema is defined using ‘schema’ or ‘schema3’, the params will be validated against it before the query is executed.</p>
 
 
   </div>
 </div>
 <div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
   
+    <li>
+      
+        <span class='name'>params</span>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>{}</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>Parameters for the query</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+<p class="tag_title">Raises:</p>
+<ul class="raise">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Schemacop::Exceptions::ValidationError</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>if params don’t match schema</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -407,16 +482,16 @@ was a validation schema specified).</p>
       <pre class="lines">
 
 
-22
-23
-24
-25
-26
-27
-28</pre>
+52
+53
+54
+55
+56
+57
+58</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 22</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 52</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span> <span class='op'>=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>
   <span class='ivar'>@params</span> <span class='op'>=</span> <span class='id identifier rubyid_params'>params</span>
@@ -448,7 +523,8 @@ was a validation schema specified).</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Returns the value of attribute params.</p>
+    
+<p>Returns the value of attribute params.</p>
 
 
   </div>
@@ -462,12 +538,12 @@ was a validation schema specified).</p>
       <pre class="lines">
 
 
-6
-7
-8</pre>
+19
+20
+21</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 6</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 19</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_params'>params</span>
   <span class='ivar'>@params</span>
@@ -495,14 +571,70 @@ was a validation schema specified).</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Instantiates the query class using the given arguments
-and runs <code>call</code> on it.</p>
+    
+<p>Instantiates the query class with the given params and executes only the ‘call’ method, skipping post-processing.</p>
 
 
   </div>
 </div>
 <div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>args</span>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>Parameters to pass to the query</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The raw query results</p>
+</div>
+      
+    </li>
   
+</ul>
+<p class="tag_title">Raises:</p>
+<ul class="raise">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Schemacop::Exceptions::ValidationError</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>if params don’t match schema</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -510,12 +642,12 @@ and runs <code>call</code> on it.</p>
       <pre class="lines">
 
 
-16
-17
-18</pre>
+41
+42
+43</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 16</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 41</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_call'>call</span>
@@ -536,14 +668,72 @@ and runs <code>call</code> on it.</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Instantiates the query class using the given arguments
-and runs <code>call</code> and <code>process</code> on it.</p>
+    
+<p>Instantiates the query class with the given params and executes both ‘call’ and ‘process’ methods.</p>
+
+<p>This is the primary way to execute queries. It runs the query logic defined in ‘call’ and then passes the results through ‘process’ for any post-processing.</p>
 
 
   </div>
 </div>
 <div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>args</span>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>Parameters to pass to the query</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The processed query results</p>
+</div>
+      
+    </li>
+  
+</ul>
+<p class="tag_title">Raises:</p>
+<ul class="raise">
   
+    <li>
+      
+      
+        <span class='type'>(<tt>Schemacop::Exceptions::ValidationError</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>if params don’t match schema</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -551,12 +741,12 @@ and runs <code>call</code> and <code>process</code> on it.</p>
       <pre class="lines">
 
 
-10
-11
-12</pre>
+31
+32
+33</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 10</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 31</span>
 
 <span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_run'>run</span>
@@ -583,13 +773,50 @@ and runs <code>call</code> and <code>process</code> on it.</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Override this method to perform the actual query.</p>
+    
+<p>Override this method in subclasses to define the query logic.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>Query results (typically an ActiveRecord::Relation)</p>
+</div>
+      
+    </li>
+  
+</ul>
+<p class="tag_title">Raises:</p>
+<ul class="raise">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>NotImplementedError</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>if not overridden in subclass</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -597,12 +824,12 @@ and runs <code>call</code> and <code>process</code> on it.</p>
       <pre class="lines">
 
 
-36
-37
-38</pre>
+71
+72
+73</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 36</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 71</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
   <span class='id identifier rubyid_fail'>fail</span> <span class='const'>NotImplementedError</span>
@@ -615,7 +842,7 @@ and runs <code>call</code> and <code>process</code> on it.</p>
       <div class="method_details ">
   <h3 class="signature " id="connection-instance_method">
   
-    #<strong>connection</strong>  &#x21d2; <tt>Object</tt> 
+    #<strong>connection</strong>  &#x21d2; <tt>ActiveRecord::ConnectionAdapters::AbstractAdapter</tt> 
   
 
   
@@ -623,14 +850,29 @@ and runs <code>call</code> and <code>process</code> on it.</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Provides a connection to the database. May be overridden if a different
-connection is desired. Defaults to <code>ActiveRecord::Base.connection</code>.</p>
+    
+<p>Returns the database connection to use for this query.</p>
+
+<p>Override this method if you need to use a different connection than the default ActiveRecord connection.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>ActiveRecord::ConnectionAdapters::AbstractAdapter</tt>)</span>
+      
+      
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -638,12 +880,12 @@ connection is desired. Defaults to <code>ActiveRecord::Base.connection</code>.</
       <pre class="lines">
 
 
-53
-54
-55</pre>
+106
+107
+108</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 53</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 106</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_connection'>connection</span>
   <span class='const'>ActiveRecord</span><span class='op'>::</span><span class='const'>Base</span><span class='period'>.</span><span class='id identifier rubyid_connection'>connection</span>
@@ -656,7 +898,7 @@ connection is desired. Defaults to <code>ActiveRecord::Base.connection</code>.</
       <div class="method_details ">
   <h3 class="signature " id="osparams-instance_method">
   
-    #<strong>osparams</strong>  &#x21d2; <tt>Object</tt> 
+    #<strong>osparams</strong>  &#x21d2; <tt><span class='object_link'><a href="MethodAccessibleHash.html" title="Inquery::MethodAccessibleHash (class)">MethodAccessibleHash</a></span></tt> 
   
 
   
@@ -664,14 +906,40 @@ connection is desired. Defaults to <code>ActiveRecord::Base.connection</code>.</
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Returns a copy of the query&#39;s params, wrapped in an OpenStruct object for
-easyer access.</p>
+    
+<p>Returns the query params wrapped in a MethodAccessibleHash for convenient access using dot notation.</p>
+
+<p>Example:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_schema3'>schema3</span> <span class='lbrace'>{</span> <span class='id identifier rubyid_str!'>str!</span> <span class='symbol'>:name</span> <span class='rbrace'>}</span>
+<span class='kw'>def</span> <span class='id identifier rubyid_call'>call</span>
+  <span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_where'>where</span><span class='lparen'>(</span><span class='label'>name:</span> <span class='id identifier rubyid_osparams'>osparams</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span> <span class='comment'># Access via dot notation
+</span><span class='kw'>end</span>
+</code></pre>
 
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt><span class='object_link'><a href="MethodAccessibleHash.html" title="Inquery::MethodAccessibleHash (class)">MethodAccessibleHash</a></span></tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>Params with method access</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -679,15 +947,15 @@ easyer access.</p>
       <pre class="lines">
 
 
-47
-48
-49</pre>
+96
+97
+98</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 47</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 96</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_osparams'>osparams</span>
-  <span class='ivar'>@osparams</span> <span class='op'>||=</span> <span class='const'>OpenStruct</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='rparen'>)</span>
+  <span class='ivar'>@osparams</span> <span class='op'>||=</span> <span class='const'><span class='object_link'><a href="MethodAccessibleHash.html" title="Inquery::MethodAccessibleHash (class)">MethodAccessibleHash</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="MethodAccessibleHash.html#initialize-instance_method" title="Inquery::MethodAccessibleHash#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='rparen'>)</span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -705,13 +973,54 @@ easyer access.</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Override this method to perform an optional result postprocessing.</p>
+    
+<p>Override this method in subclasses to transform the query results.</p>
+
+<p>By default, returns the results unchanged. Common uses include converting to JSON, counting records, or extracting specific fields.</p>
 
 
   </div>
 </div>
 <div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>results</span>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The results from the ‘call’ method</p>
+</div>
+      
+    </li>
   
+</ul>
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The processed results</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -719,12 +1028,12 @@ easyer access.</p>
       <pre class="lines">
 
 
-41
-42
-43</pre>
+82
+83
+84</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 41</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 82</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_process'>process</span><span class='lparen'>(</span><span class='id identifier rubyid_results'>results</span><span class='rparen'>)</span>
   <span class='id identifier rubyid_results'>results</span>
@@ -745,13 +1054,32 @@ easyer access.</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Runs both <code>call</code> and <code>process</code>.</p>
+    
+<p>Executes the query by calling ‘call’ and then ‘process’.</p>
 
 
   </div>
 </div>
 <div class="tags">
   
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Object</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'>
+<p>The processed query results</p>
+</div>
+      
+    </li>
+  
+</ul>
 
 </div><table class="source_code">
   <tr>
@@ -759,12 +1087,12 @@ easyer access.</p>
       <pre class="lines">
 
 
-31
-32
-33</pre>
+63
+64
+65</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 31</span>
+      <pre class="code"><span class="info file"># File 'lib/inquery/query.rb', line 63</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_run'>run</span>
   <span class='id identifier rubyid_process'>process</span><span class='lparen'>(</span><span class='id identifier rubyid_call'>call</span><span class='rparen'>)</span>
@@ -779,9 +1107,9 @@ easyer access.</p>
 </div>
 
       <div id="footer">
-  Generated on Thu Aug 24 11:11:23 2023 by
-  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.9.27 (ruby-3.0.1).
+  Generated on Mon Jan  5 14:06:48 2026 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.37 (ruby-3.3.5).
 </div>
 
     </div>