active_windows 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78306f0ad28382b0fd83cc679dcfd418fc72a5e0c0a26e1e812ab0cdf3a289e2
-  data.tar.gz: a155a298bc07f13ead19b25764df4256996b995918b2362f518512066cccb4f8
+  metadata.gz: a3591dbeb9c495d128c8fa3fd9f88cdc4be7d6fabad282e48e47a9d3b9e919d7
+  data.tar.gz: ee011c561b8e84a1efe6b6366664616286632ff8facfaa1ff3a1df37a093c434
 SHA512:
-  metadata.gz: 2c2bb59c2105382c024acc58192266edd835c08422bc6a13221d480f634320185395af8eb3a742ff92a53ca123ed4775d50b765da48e7d9256f1f5ba3f397044
-  data.tar.gz: d9821806ab2b43d4ce12955f7311d0582b1312f76dd126255465c088e3a1bd9417c1d4fb870fc6a986361229e984253ffd6d67e587c001234a157a38a82ba545
+  metadata.gz: dc03d55bfc15cf28e76347b6a8f0f04d52a89c24c6b41feb458cff6c8c4694ed1270802710f9686eb68e90f30281f096ef8d0a0fc9c638c356f347aa894015bd
+  data.tar.gz: 92e13ee084266b0fe1a8baf40a5275338d95a07888cca71f44546ef2b518700208c758c2302f1fcb2ff4d32608666652f993a89bc96cbb6e8f692bfaacb46a36

data/README.md

@@ -1,16 +1,18 @@
+[![Gem Version](https://badge.fury.io/rb/active_windows.svg)](https://badge.fury.io/rb/active_windows)
+
 # ActiveWindows
 
 A Ruby DSL for SQL window functions in ActiveRecord. Write expressive window function queries using a fluent, chainable interface instead of raw SQL.
 
 ```ruby
 # Fluent API
-User.row_number.partition_by(:department).order_by(:salary).as(:rank)
+User.window(:row_number).partition_by(:department).order_by(:salary).as(:rank)
 
 # Hash API
-User.window(row_number: { partition: :department, order_by: :salary, as: :rank })
+User.window(row_number: { partition_by: :department, order_by: :salary, as: :rank })
 
 # Both produce:
-# SELECT "users".*, ROW_NUMBER() OVER (PARTITION BY "users"."department" ORDER BY "users"."salary") AS rank
+# SELECT "users".*, ROW_NUMBER() OVER (PARTITION BY "users"."department" ORDER BY "users"."salary") AS "rank"
 # FROM "users"
 ```
 
@@ -41,34 +43,31 @@ ActiveWindows provides two equivalent APIs: a **fluent API** with chainable meth
 
 ### Fluent API
 
-Every window function method returns a chainable object with `.partition_by()`, `.order_by()`, and `.as()`:
+`window(:function_name, *args)` returns a chainable object with `.partition_by()`, `.order_by()`, and `.as()`:
 
 ```ruby
-User.row_number.partition_by(:department).order_by(:salary).as(:rank)
+User.window(:row_number).partition_by(:department).order_by(:salary).as(:rank)
+
+# Functions with arguments:
+User.window(:lag, :salary, 1, 0).order_by(:hire_date).as(:prev_salary)
+User.window(:ntile, 4).order_by(:salary).as(:quartile)
 ```
 
 All three chain methods are optional. `.order_by()` sets the window's `ORDER BY`, while ActiveRecord's `.order()` controls the query-level `ORDER BY`. You can use both together:
 
 ```ruby
-User.row_number.order_by(:salary).as(:rn).order(:name)
+User.window(:row_number).order_by(:salary).as(:rn).order(:name)
 # Window:  OVER (ORDER BY salary)
 # Query:   ORDER BY name
 ```
 
-Order can be mixed freely:
-
-```ruby
-User.row_number.as(:rn).order_by(:created_at)
-User.dense_rank.order_by(:score).as(:position)
-```
-
 ### Hash API
 
 Pass one or more window function definitions as a hash:
 
 ```ruby
 User.window(
-  row_number: { partition: :department, order_by: :salary, as: :rank }
+  row_number: { partition_by: :department, order_by: :salary, as: :rank }
 )
 ```
 
@@ -76,7 +75,7 @@ Available options:
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `:partition` | `Symbol`, `Array` | Column(s) for `PARTITION BY` |
+| `:partition_by` | `Symbol`, `Array` | Column(s) for `PARTITION BY` |
 | `:order_by` | `Symbol`, `Array` | Column(s) for `ORDER BY` |
 | `:as` | `Symbol` | Alias for the result column |
 | `:frame` | `String` | Raw SQL frame clause (e.g. `"ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING"`) |
@@ -84,28 +83,15 @@ Available options:
 
 ### Association Names
 
-You can use association names instead of raw column names. ActiveWindows automatically resolves them:
-
-**`belongs_to`** — resolves to the foreign key on the current table:
+You can use `belongs_to` association names instead of foreign key columns. ActiveWindows automatically resolves them:
 
 ```ruby
 # These are equivalent:
-Order.row_number.partition_by(:user).order_by(:amount).as(:rn)
-Order.row_number.partition_by(:user_id).order_by(:amount).as(:rn)
+Order.window(:row_number).partition_by(:user).order_by(:amount).as(:rn)
+Order.window(:row_number).partition_by(:user_id).order_by(:amount).as(:rn)
 
 # Works in the hash API too:
-Order.window(row_number: { partition: :user, order_by: :amount, as: :rn })
-```
-
-**`has_one`** — auto-joins the associated table and references its primary key:
-
-```ruby
-# User has_one :profile
-# Automatically joins profiles and partitions by profiles.id
-User.row_number.partition_by(:profile).order_by(:salary).as(:rn)
-
-# Equivalent to:
-User.joins(:profile).row_number.partition_by("profiles.id").order_by(:salary).as(:rn)
+Order.window(row_number: { partition_by: :user, order_by: :amount, as: :rn })
 ```
 
 ### Chaining with ActiveRecord
@@ -114,7 +100,7 @@ Window functions integrate naturally with standard ActiveRecord methods:
 
 ```ruby
 User.where(active: true)
-    .row_number
+    .window(:row_number)
     .partition_by(:department)
     .order_by(:salary)
     .as(:rank)
@@ -134,7 +120,7 @@ When no `.select()` is specified, `*` is automatically included so all model col
 Window function values are accessible as attributes on the returned records:
 
 ```ruby
-results = User.row_number.partition_by(:department).order_by(:salary).as(:rank)
+results = User.window(:row_number).partition_by(:department).order_by(:salary).as(:rank)
 
 results.each do |user|
   puts "#{user.name}: rank #{user.attributes['rank']}"
@@ -147,66 +133,64 @@ end
 
 ```ruby
 # ROW_NUMBER() - sequential integer within partition
-User.row_number.partition_by(:department).order_by(:salary).as(:rn)
+User.window(:row_number).partition_by(:department).order_by(:salary).as(:rn)
 
 # RANK() - rank with gaps for ties
-User.rank.partition_by(:department).order_by(:salary).as(:salary_rank)
+User.window(:rank).partition_by(:department).order_by(:salary).as(:salary_rank)
 
 # DENSE_RANK() - rank without gaps for ties
-User.dense_rank.partition_by(:department).order_by(:salary).as(:dense_salary_rank)
+User.window(:dense_rank).partition_by(:department).order_by(:salary).as(:dense_salary_rank)
 
 # PERCENT_RANK() - relative rank as a fraction (0 to 1)
-User.percent_rank.order_by(:salary).as(:percentile)
+User.window(:percent_rank).order_by(:salary).as(:percentile)
 
 # CUME_DIST() - cumulative distribution (fraction of rows <= current row)
-User.cume_dist.order_by(:salary).as(:cumulative)
+User.window(:cume_dist).order_by(:salary).as(:cumulative)
 
 # NTILE(n) - divide rows into n roughly equal buckets
-User.ntile(4).order_by(:salary).as(:quartile)
+User.window(:ntile, 4).order_by(:salary).as(:quartile)
 ```
 
 ### Value Functions
 
 ```ruby
 # LAG(column, offset, default) - value from a preceding row
-User.lag(:salary).order_by(:hire_date).as(:prev_salary)
-User.lag(:salary, 2).order_by(:hire_date).as(:two_back)         # custom offset
-User.lag(:salary, 1, 0).order_by(:hire_date).as(:prev_or_zero)  # with default
+User.window(:lag, :salary).order_by(:hire_date).as(:prev_salary)
+User.window(:lag, :salary, 2).order_by(:hire_date).as(:two_back)         # custom offset
+User.window(:lag, :salary, 1, 0).order_by(:hire_date).as(:prev_or_zero)  # with default
 
 # LEAD(column, offset, default) - value from a following row
-User.lead(:salary).order_by(:hire_date).as(:next_salary)
-User.lead(:salary, 2, 0).order_by(:hire_date).as(:two_ahead)
+User.window(:lead, :salary).order_by(:hire_date).as(:next_salary)
+User.window(:lead, :salary, 2, 0).order_by(:hire_date).as(:two_ahead)
 
 # FIRST_VALUE(column) - first value in the window frame
-User.first_value(:name).partition_by(:department).order_by(:salary).as(:lowest_paid)
+User.window(:first_value, :name).partition_by(:department).order_by(:salary).as(:lowest_paid)
 
 # LAST_VALUE(column) - last value in the window frame
-User.last_value(:name).partition_by(:department).order_by(:salary).as(:highest_paid)
+User.window(:last_value, :name).partition_by(:department).order_by(:salary).as(:highest_paid)
 
 # NTH_VALUE(column, n) - nth value in the window frame
-User.nth_value(:name, 2).partition_by(:department).order_by(:salary).as(:second_lowest)
+User.window(:nth_value, :name, 2).partition_by(:department).order_by(:salary).as(:second_lowest)
 ```
 
 ### Aggregate Window Functions
 
-Prefixed with `window_` to avoid conflicts with ActiveRecord's built-in aggregate methods:
-
 ```ruby
 # SUM(column) OVER(...)
-User.window_sum(:salary).partition_by(:department).as(:dept_total)
+User.window(:sum, :salary).partition_by(:department).as(:dept_total)
 
 # AVG(column) OVER(...)
-User.window_avg(:salary).partition_by(:department).as(:dept_avg)
+User.window(:avg, :salary).partition_by(:department).as(:dept_avg)
 
 # COUNT(column) OVER(...)
-User.window_count(:id).partition_by(:department).as(:dept_size)
-User.window_count.partition_by(:department).as(:dept_size)  # COUNT(*)
+User.window(:count, :id).partition_by(:department).as(:dept_size)
+User.window(:count, "*").partition_by(:department).as(:dept_size)  # COUNT(*)
 
 # MIN(column) OVER(...)
-User.window_min(:salary).partition_by(:department).as(:min_salary)
+User.window(:min, :salary).partition_by(:department).as(:min_salary)
 
 # MAX(column) OVER(...)
-User.window_max(:salary).partition_by(:department).as(:max_salary)
+User.window(:max, :salary).partition_by(:department).as(:max_salary)
 ```
 
 ### Window Frames
@@ -216,7 +200,7 @@ Pass a raw SQL frame clause via the hash API:
 ```ruby
 User.window(sum: {
   value: :salary,
-  partition: :department,
+  partition_by: :department,
   order_by: :hire_date,
   frame: "ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW",
   as: :running_total
@@ -228,7 +212,7 @@ User.window(sum: {
 ### Rank employees by salary within each department
 
 ```ruby
-User.rank
+User.window(:rank)
     .partition_by(:department)
     .order_by(:salary)
     .as(:salary_rank)
@@ -248,7 +232,7 @@ User.window(sum: {
 ### Compare each salary to the department average
 
 ```ruby
-users = User.window_avg(:salary).partition_by(:department).as(:dept_avg)
+users = User.window(:avg, :salary).partition_by(:department).as(:dept_avg)
 
 users.each do |user|
   diff = user.salary - user.attributes["dept_avg"].to_f
@@ -259,7 +243,7 @@ end
 ### Find the previous and next hire in each department
 
 ```ruby
-User.lag(:name)
+User.window(:lag, :name)
     .partition_by(:department)
     .order_by(:hire_date)
     .as(:previous_hire)
@@ -268,7 +252,7 @@ User.lag(:name)
 ### Divide employees into salary quartiles
 
 ```ruby
-User.ntile(4).order_by(:salary).as(:quartile)
+User.window(:ntile, 4).order_by(:salary).as(:quartile)
 ```
 
 ### Rank users by total order amount (with joins)
@@ -285,7 +269,7 @@ User.joins(:orders)
 ```ruby
 # Rank orders by amount within each user
 Order.joins(:user)
-     .row_number
+     .window(:row_number)
      .partition_by("users.id")
      .order_by(amount: :desc)
      .as(:order_rank)
@@ -293,7 +277,7 @@ Order.joins(:user)
 # Number each user's orders chronologically
 Order.joins(:user)
      .select("orders.*, users.name AS user_name")
-     .row_number
+     .window(:row_number)
      .partition_by(:user_id)
      .order_by(:created_at)
      .as(:order_number)
@@ -307,7 +291,7 @@ Order.joins(:user)
      .where(users: { department: "Engineering" })
      .window(sum: {
        value: :amount,
-       partition: :user_id,
+       partition_by: :user_id,
        order_by: :created_at,
        frame: "ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW",
        as: :running_total

data/docs/REVIEW_AND_PLAN.md

@@ -2,7 +2,7 @@
 
 ## Overall Assessment
 
-The gem provides a fluent DSL for SQL window functions in ActiveRecord. Core functionality is implemented and tested, with 16 window functions available via both fluent and hash APIs. 67 tests passing with 328 assertions. CI runs against SQLite, PostgreSQL, and MySQL.
+The gem provides a fluent DSL for SQL window functions in ActiveRecord. Core functionality is implemented and tested, with 16 window functions available via fluent, `window(:symbol)`, and hash APIs. 82 tests passing with 399 assertions. CI runs against SQLite, PostgreSQL, and MySQL.
 
 ---
 
@@ -26,7 +26,7 @@ The gem provides a fluent DSL for SQL window functions in ActiveRecord. Core fun
 - ~~**RuboCop dependency**~~ — Removed.
 - ~~**LICENSE**~~ — Cleaned up. Full name, no year, `.txt` extension removed.
 - ~~**Boilerplate files**~~ — Removed. `CHANGELOG.md`, `CODE_OF_CONDUCT.md`, `bin/console`, `bin/setup`, `sig/active_windows.rbs`.
-- ~~**Ordering direction**~~ — Fixed. Supports `order(salary: :desc)`, `order({ col: :asc }, { col: :desc })`, and hash API `order: { salary: :desc }`.
+- ~~**Ordering direction**~~ — Fixed. Supports `order_by(salary: :desc)`, `order_by({ col: :asc }, { col: :desc })`, and hash API `order_by: { salary: :desc }`.
 - ~~**Gemfile/gemspec duplication**~~ — Fixed. Dev gems (`minitest`, `rake`) defined only in Gemfile under `test, development` group. No more bundler override warnings.
 - ~~**Cross-platform lockfile**~~ — Fixed. Added `aarch64-linux`, `arm-linux`, `arm64-darwin`, `x86_64-darwin`, `x86_64-linux` platforms.
 - ~~**Multiple window functions in one call**~~ — Tested. Single `window()` with multiple keys and chaining separate `window()` calls both work.
@@ -34,8 +34,9 @@ The gem provides a fluent DSL for SQL window functions in ActiveRecord. Core fun
 - ~~**PostgreSQL CI**~~ — Added. GitHub Actions workflow tests against PostgreSQL 17 with service container.
 - ~~**MySQL CI**~~ — Added. GitHub Actions workflow tests against MySQL 8.0 with service container.
 - ~~**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 `window_order` to avoid conflict with ActiveRecord's `.order()`. WindowChain now delegates `.order()` to the relation for query-level ordering. Uses `method_missing` for full relation method coverage.
-- ~~**Association name resolution**~~ — Added. `partition_by(:user)` automatically resolves to `user_id` via `belongs_to` reflection. Works in both fluent and hash APIs. 74 tests, 355 assertions.
+- ~~**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.
 
 ---
 

data/lib/active_windows/active_record_extensions.rb

@@ -32,7 +32,7 @@ module ActiveWindows
 
     def to_window_hash
       options = {}
-      options[:partition] = @partition_columns unless @partition_columns.empty?
+      options[:partition_by] = @partition_columns unless @partition_columns.empty?
       options[:order_by] = @order_columns unless @order_columns.empty?
       options[:as] = @alias_name if @alias_name
       options[:value] = @function_args unless @function_args.empty?
@@ -65,23 +65,24 @@ module ActiveWindows
   end
 
   module QueryMethods
-    VALID_WINDOW_OPTIONS = %i[value partition order_by frame as].freeze
+    VALID_WINDOW_OPTIONS = %i[value partition_by order_by frame as].freeze
 
-    # Non-mutating: returns a new relation with window function projections
+    # Fluent: window(:row_number) returns a WindowChain
+    # Fluent with args: window(:lag, :salary, 1, 0) returns a WindowChain
+    # Hash: window(row_number: { partition: :department, order_by: :salary, as: :rank })
     def window(*args)
       raise ArgumentError, "wrong number of arguments (given 0, expected 1+)" if args.empty?
 
+      # Fluent API: window(:function_name, *function_args)
+      if args.first.is_a?(Symbol) && (args.length == 1 || !args[1].is_a?(Hash))
+        function_name = args.shift
+        return WindowChain.new(function_name, spawn, function_args: args.map(&:to_s))
+      end
+
+      # Hash API
       processed = process_window_args(args)
 
       result = spawn
-
-      # Auto-join has_one associations referenced in partition/order
-      joins_needed = processed.flat_map do |_name, options|
-        next [] unless options.is_a?(Hash)
-        association_joins_for(options[:partition]) + association_joins_for(options[:order_by])
-      end.uniq
-      result = result.joins(*joins_needed) if joins_needed.any?
-
       arel_nodes = processed.map { |name, options| build_window_function(name, options || {}) }
 
       # Ensure we keep all columns alongside the window function columns
@@ -89,83 +90,12 @@ module ActiveWindows
       result.select(*arel_nodes)
     end
 
-    # Ranking window functions
-    def row_number
-      WindowChain.new(:row_number, spawn)
-    end
-
-    def rank
-      WindowChain.new(:rank, spawn)
-    end
-
-    def dense_rank
-      WindowChain.new(:dense_rank, spawn)
-    end
-
-    def percent_rank
-      WindowChain.new(:percent_rank, spawn)
-    end
-
-    def cume_dist
-      WindowChain.new(:cume_dist, spawn)
-    end
-
-    def ntile(num_buckets)
-      WindowChain.new(:ntile, spawn, function_args: [num_buckets.to_s])
-    end
-
-    # Value window functions
-    def lag(column, offset = 1, default = nil)
-      args = [column.to_s, offset.to_s]
-      args << default.to_s unless default.nil?
-      WindowChain.new(:lag, spawn, function_args: args)
-    end
-
-    def lead(column, offset = 1, default = nil)
-      args = [column.to_s, offset.to_s]
-      args << default.to_s unless default.nil?
-      WindowChain.new(:lead, spawn, function_args: args)
-    end
-
-    def first_value(column)
-      WindowChain.new(:first_value, spawn, function_args: [column.to_s])
-    end
-
-    def last_value(column)
-      WindowChain.new(:last_value, spawn, function_args: [column.to_s])
-    end
-
-    def nth_value(column, n)
-      WindowChain.new(:nth_value, spawn, function_args: [column.to_s, n.to_s])
-    end
-
-    # Aggregate window functions
-    def window_sum(column)
-      WindowChain.new(:sum, spawn, function_args: [column.to_s])
-    end
-
-    def window_avg(column)
-      WindowChain.new(:avg, spawn, function_args: [column.to_s])
-    end
-
-    def window_count(column = "*")
-      WindowChain.new(:count, spawn, function_args: [column.to_s])
-    end
-
-    def window_min(column)
-      WindowChain.new(:min, spawn, function_args: [column.to_s])
-    end
-
-    def window_max(column)
-      WindowChain.new(:max, spawn, function_args: [column.to_s])
-    end
-
     private
 
     def build_window_function(name, options)
       window = Arel::Nodes::Window.new
 
-      apply_window_partition(window, options[:partition])
+      apply_window_partition(window, options[:partition_by])
       apply_window_order(window, options[:order_by])
       apply_window_frame(window, options[:frame]) if options[:frame]
 
@@ -237,22 +167,11 @@ module ActiveWindows
       reflection = klass.reflect_on_association(name_sym)
       if reflection&.macro == :belongs_to
         klass.arel_table[reflection.foreign_key.to_sym]
-      elsif reflection&.macro == :has_one
-        reflection.klass.arel_table[reflection.klass.primary_key.to_sym]
       else
         klass.arel_table[name_sym]
       end
     end
 
-    def association_joins_for(columns)
-      Array(columns).filter_map do |col|
-        next unless col.is_a?(Symbol) || col.is_a?(String)
-
-        reflection = klass.reflect_on_association(col.to_sym)
-        col.to_sym if reflection&.macro == :has_one
-      end
-    end
-
     def arel_order(expr)
       case expr
       when Arel::Nodes::Node, Arel::Nodes::SqlLiteral

data/lib/active_windows/version.rb

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

data/lib/active_windows.rb

@@ -7,9 +7,5 @@ require "active_windows/railtie" if defined?(Rails::Railtie)
 module ActiveWindows
   class Error < StandardError; end
 
-  QUERY_METHODS = %i[
-    window row_number rank dense_rank percent_rank cume_dist ntile
-    lag lead first_value last_value nth_value
-    window_sum window_avg window_count window_min window_max
-  ].freeze
+  QUERY_METHODS = %i[window].freeze
 end

metadata

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