active_windows 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3591dbeb9c495d128c8fa3fd9f88cdc4be7d6fabad282e48e47a9d3b9e919d7
-  data.tar.gz: ee011c561b8e84a1efe6b6366664616286632ff8facfaa1ff3a1df37a093c434
+  metadata.gz: 941df16a5d0a5717d98f3a22039e21755ba7c4ce3f1ead0fd39020e51e6483d7
+  data.tar.gz: 89ae6524909657f96930364026de99279b17faf03540dcaa102629849e449375
 SHA512:
-  metadata.gz: dc03d55bfc15cf28e76347b6a8f0f04d52a89c24c6b41feb458cff6c8c4694ed1270802710f9686eb68e90f30281f096ef8d0a0fc9c638c356f347aa894015bd
-  data.tar.gz: 92e13ee084266b0fe1a8baf40a5275338d95a07888cca71f44546ef2b518700208c758c2302f1fcb2ff4d32608666652f993a89bc96cbb6e8f692bfaacb46a36
+  metadata.gz: 51ca8df73a2d268462898de6ad0f105400bfb06ae79005c8084d41255427e14463618707967c6208ad0d596c17d61514481e71e0ef9fbdeb03a23dd1d70959da
+  data.tar.gz: 1de89bb61bedbeecba880ec7492a45fd0f257ebe4fa49e185b638de8b65c47879107493c6b427b5e38f63a12097f2cfbaaacbf2f2c4815008d9286aa5d62d171

data/README.md

@@ -80,6 +80,7 @@ Available options:
 | `:as` | `Symbol` | Alias for the result column |
 | `:frame` | `String` | Raw SQL frame clause (e.g. `"ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING"`) |
 | `:value` | `Symbol`, `String`, `Array` | Expression(s) passed as function arguments |
+| `:over` | `Symbol` | Reference to a named window defined via `define:` |
 
 ### Association Names
 
@@ -193,18 +194,74 @@ User.window(:min, :salary).partition_by(:department).as(:min_salary)
 User.window(:max, :salary).partition_by(:department).as(:max_salary)
 ```
 
+### Named Windows
+
+Define a window once and reuse it across multiple functions with `define:` and `over:`:
+
+```ruby
+User.window(
+  define: { w: { partition_by: :department, order_by: :salary } },
+  row_number: { over: :w, as: :rn },
+  rank:       { over: :w, as: :salary_rank },
+  sum:        { value: :salary, over: :w, as: :running_total }
+)
+```
+
+You can define multiple windows and extend them per-function:
+
+```ruby
+User.window(
+  define: {
+    by_dept:  { partition_by: :department },
+    globally: { order_by: :salary }
+  },
+  row_number: { over: :by_dept, order_by: :salary, as: :dept_rn },
+  rank:       { over: :globally, as: :global_rank }
+)
+```
+
+Options on the function (like `order_by:`) are merged with the named definition, so you can share the common parts and specialize per-function.
+
 ### Window Frames
 
-Pass a raw SQL frame clause via the hash API:
+Use a hash DSL to define frame clauses:
 
 ```ruby
+# ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
 User.window(sum: {
   value: :salary,
   partition_by: :department,
   order_by: :hire_date,
-  frame: "ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW",
+  frame: { rows: [:unbounded_preceding, :current_row] },
   as: :running_total
 })
+
+# ROWS BETWEEN 3 PRECEDING AND 1 FOLLOWING
+frame: { rows: [3, -1] }
+
+# RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+frame: { range: [:unbounded_preceding, :unbounded_following] }
+
+# Single bound: ROWS UNBOUNDED PRECEDING
+frame: { rows: :unbounded_preceding }
+```
+
+Available bounds: `:unbounded_preceding`, `:unbounded_following`, `:current_row`, or an integer (positive = PRECEDING, negative = FOLLOWING).
+
+Fluent API:
+
+```ruby
+User.window(:sum, :salary)
+    .partition_by(:department)
+    .order_by(:hire_date)
+    .frame(rows: [:unbounded_preceding, :current_row])
+    .as(:running_total)
+```
+
+Raw SQL strings are also accepted:
+
+```ruby
+frame: "ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW"
 ```
 
 ## Examples

data/docs/REVIEW_AND_PLAN.md

@@ -36,7 +36,9 @@ The gem provides a fluent DSL for SQL window functions in ActiveRecord. Core fun
 - ~~**MySQL compatibility**~~ — Fixed. Aliases now use `klass.connection.quote_column_name` to properly quote reserved words (e.g., `rank`) with backticks on MySQL and double quotes on PostgreSQL/SQLite. Test assertions use adapter-agnostic `q()` and `col()` helpers.
 - ~~**WindowChain `order` naming collision**~~ — Fixed. Renamed to `order_by` to avoid conflict with ActiveRecord's `.order()`. Both fluent (`.order_by(:salary)`) and hash (`order_by: :salary`) APIs use `order_by`. WindowChain delegates `.order()` to the relation for query-level ordering. Uses `method_missing` for full relation method coverage.
 - ~~**Association name resolution**~~ — Added. `belongs_to`: `partition_by(:user)` resolves to `user_id`. Works in both fluent and hash APIs.
-- ~~**Unified `window()` entry point**~~ — Added. `window(:row_number)` returns a WindowChain (fluent), `window(:lag, :salary, 1, 0)` passes function args, `window(row_number: { ... })` is hash API. Single method, three modes. 82 tests, 399 assertions.
+- ~~**Unified `window()` entry point**~~ — Added. `window(:row_number)` returns a WindowChain (fluent), `window(:lag, :salary, 1, 0)` passes function args, `window(row_number: { ... })` is hash API. Single method, three modes.
+- ~~**Named windows**~~ — Added. `define: { w: { partition_by: :department, order_by: :salary } }` with `over: :w` references. Multiple definitions supported. Function-level options merge with the definition.
+- ~~**Frame clause is raw SQL**~~ — Fixed. Hash DSL for frames: `frame: { rows: [:unbounded_preceding, :current_row] }`. Supports `:rows`/`:range`, integer offsets, and all standard bounds. Raw SQL strings still accepted as fallback. 93 tests, 429 assertions.
 
 ---
 

data/lib/active_windows/active_record_extensions.rb

@@ -13,6 +13,7 @@ module ActiveWindows
       @alias_name = nil
       @partition_columns = []
       @order_columns = []
+      @frame = nil
     end
 
     def as(name)
@@ -30,10 +31,16 @@ module ActiveWindows
       self
     end
 
+    def frame(value)
+      @frame = value
+      self
+    end
+
     def to_window_hash
       options = {}
       options[:partition_by] = @partition_columns unless @partition_columns.empty?
       options[:order_by] = @order_columns unless @order_columns.empty?
+      options[:frame] = @frame if @frame
       options[:as] = @alias_name if @alias_name
       options[:value] = @function_args unless @function_args.empty?
       { @function => options }
@@ -65,7 +72,7 @@ module ActiveWindows
   end
 
   module QueryMethods
-    VALID_WINDOW_OPTIONS = %i[value partition_by order_by frame as].freeze
+    VALID_WINDOW_OPTIONS = %i[value partition_by order_by frame as over].freeze
 
     # Fluent: window(:row_number) returns a WindowChain
     # Fluent with args: window(:lag, :salary, 1, 0) returns a WindowChain
@@ -133,10 +140,66 @@ module ActiveWindows
       window.order(*columns.flat_map { |o| arel_order(o) })
     end
 
+    VALID_FRAME_TYPES = %i[rows range].freeze
+    VALID_FRAME_BOUNDS = %i[
+      unbounded_preceding unbounded_following current_row
+    ].freeze
+
     def apply_window_frame(window, frame)
-      return unless frame.is_a?(String)
+      case frame
+      when String
+        window.frame(Arel.sql(frame))
+      when Hash
+        window.frame(build_frame(frame))
+      end
+    end
+
+    def build_frame(frame_hash)
+      type, bounds = frame_hash.first
 
-      window.frame(Arel.sql(frame))
+      unless VALID_FRAME_TYPES.include?(type)
+        raise ArgumentError, "Invalid frame type: #{type}. Use :rows or :range"
+      end
+
+      bounds = Array(bounds)
+
+      frame_class = type == :rows ? Arel::Nodes::Rows : Arel::Nodes::Range
+
+      if bounds.length == 1
+        # Single bound: ROWS <bound>
+        frame_class.new(build_frame_bound(bounds[0]))
+      else
+        # BETWEEN: ROWS BETWEEN <start> AND <end>
+        # Arel doesn't support BETWEEN frames natively, so we build SQL
+        start_sql = frame_bound_sql(bounds[0])
+        end_sql = frame_bound_sql(bounds[1])
+        type_sql = type.to_s.upcase
+        Arel.sql("#{type_sql} BETWEEN #{start_sql} AND #{end_sql}")
+      end
+    end
+
+    def build_frame_bound(bound)
+      case bound
+      when :current_row         then Arel::Nodes::CurrentRow.new
+      when :unbounded_preceding then Arel::Nodes::Preceding.new
+      when :unbounded_following then Arel::Nodes::Following.new
+      when Integer
+        bound >= 0 ? Arel::Nodes::Preceding.new(bound) : Arel::Nodes::Following.new(bound.abs)
+      else
+        raise ArgumentError, "Invalid frame bound: #{bound}"
+      end
+    end
+
+    def frame_bound_sql(bound)
+      case bound
+      when :current_row         then "CURRENT ROW"
+      when :unbounded_preceding then "UNBOUNDED PRECEDING"
+      when :unbounded_following then "UNBOUNDED FOLLOWING"
+      when Integer
+        bound >= 0 ? "#{bound} PRECEDING" : "#{bound.abs} FOLLOWING"
+      else
+        raise ArgumentError, "Invalid frame bound: #{bound}"
+      end
     end
 
     def extract_window_value(value)
@@ -187,16 +250,37 @@ module ActiveWindows
     end
 
     def process_window_args(args)
+      # First pass: collect named window definitions from define: key
+      definitions = {}
+      args.each do |element|
+        next unless element.is_a?(Hash) && element.key?(:define)
+
+        element[:define].each do |name, opts|
+          definitions[name] = opts
+        end
+      end
+
+      # Second pass: build function list, resolving over: references
       args.flat_map do |element|
         case element
         when Hash
-          element.each_value do |v|
-            next unless v.is_a?(Hash)
+          element.except(:define).map do |k, v|
+            next [k, v] unless v.is_a?(Hash)
+
+            # Resolve over: reference to a named window definition
+            if v.key?(:over)
+              window_name = v[:over]
+              definition = definitions[window_name]
+              raise ArgumentError, "Unknown window definition: #{window_name}" unless definition
+
+              v = definition.merge(v.except(:over))
+            end
 
             unsupported = v.keys - VALID_WINDOW_OPTIONS
             raise ArgumentError, "Unsupported window options: #{unsupported.join(', ')}" unless unsupported.empty?
-          end
-          element.map { |k, v| [k, v] }
+
+            [k, v]
+          end.compact
         when WindowChain
           [element.to_window_hash.first]
         else

data/lib/active_windows/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveWindows
-  VERSION = "0.1.8"
+  VERSION = "0.1.10"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_windows
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Andrei Andriichuk