sql_beautifier 0.1.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cd89341ca715477774f461f2f819550e28aea5b10da268f4cb662079b6d6577
-  data.tar.gz: f9e1cb24ddfcae2290117366a969c14865cb938edb88574cd4e0fd5be1aee439
+  metadata.gz: 6df1f55c9242793101e9f562329763541d56aa4f17f7e3d81a12038ab5b53cca
+  data.tar.gz: 43fea825ac0c4bded07098814a2ed67e5503e1829f3d47cc99a7c989ec0e69d1
 SHA512:
-  metadata.gz: bd61f519fd40401a02d1a8a235a4c4957754f07a0c8862bbfccf464706c0417397c9284215c9c02dadfb21a38e7bd7dc36a0302abf1042fe2931adcf940ae859
-  data.tar.gz: d76dfa235ca58a94733582e52f991c4997dfe5dee336a8dc7adc4937fc89891c76de6e2bb6d06449c241bdcd416ecdb8f137b31fd9a6513cc490a478c890f8b5
+  metadata.gz: d56c72c27d4b71781be0ee83ba44fb3a4e466567c5edbde267c2cfbeb245c81e78bc52a309d27e7dae69a2a7e3cbf1bb3ce55926a266a6c914e822140b6650b7
+  data.tar.gz: 9e2e5118b5b12e52551300e2c0219c6cc42907fdb87fd56a8e6e80e193b212ae36ff87ee48d2a0135dc0140121d145c3f104622a0efbd0a3bbeffe10af378cea

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [X.X.X] - YYYY-MM-DD
 
+## [0.3.0] - 2026-03-27
+
+- Add configuration system with `SqlBeautifier.configure` block and `SqlBeautifier.reset_configuration!`
+- Add configurable keyword case (`:lower` / `:upper`), keyword column width, indent spaces, table name format (`:pascal_case` / `:lowercase`), inline group threshold, and alias strategy (`:initials` / `:none` / callable)
+- Add semicolon stripping in normalizer (trailing `;` removed before formatting)
+- Add comment stripping in normalizer (`--` line comments and `/* */` block comments, string-aware)
+- Add subquery formatting with recursive indentation (`(select ...)` expanded to multiline)
+
+## [0.2.0] - 2026-03-27
+
+- Add JOIN support (inner, left, right, full outer, cross) with formatted continuation lines
+- Add automatic table aliasing using initials (e.g. `users` → `u`, `active_storage_blobs` → `asb`)
+- Add PascalCase table name formatting (e.g. `users` → `Users`, `user_sessions` → `User_Sessions`)
+- Add `table.column` → `alias.column` replacement across full output
+- Add DISTINCT and DISTINCT ON support in SELECT clause
+- Add AND/OR condition formatting in WHERE and HAVING clauses with per-line indentation
+- Add parenthesized condition group handling (inline when short, expanded when long)
+
 ## [0.1.4] - 2026-03-26
 
 - Update `bin/ci` and `bin/release` to use new formatting functions

data/README.md

@@ -41,14 +41,149 @@ select  id,
         name,
         email
 
-from    users
+from    Users u
 
 where   active = true
 
 order by name
 ```
 
-Single-word keywords are lowercased and padded so their clause bodies start at an 8-character column. Multi-word clauses such as `order by` and `group by`, and short clauses like `limit`, use a single space between the keyword and the clause body instead of padding. Each clause is separated by a blank line. Multi-column SELECT lists place each column on its own line with continuation indentation.
+Single-word keywords are lowercased and padded so their clause bodies start at an 8-character column. Multi-word clauses such as `order by` and `group by`, and short clauses like `limit`, use a single space between the keyword and the clause body instead of padding. Clause spacing is compact by default for simple one-column / one-table / one-condition queries, and otherwise uses blank lines between top-level clauses. Multi-column SELECT lists place each column on its own line with continuation indentation. Table names are PascalCased and automatically aliased.
+
+### Table Aliasing
+
+Tables are automatically aliased using their initials. Underscore-separated table names use the first letter of each segment:
+
+| Table Name                 | PascalCase                 | Alias |
+| -------------------------- | -------------------------- | ----- |
+| `users`                    | `Users`                    | `u`   |
+| `active_storage_blobs`     | `Active_Storage_Blobs`     | `asb` |
+| `person_event_invitations` | `Person_Event_Invitations` | `pei` |
+
+All `table.column` references throughout the query are replaced with `alias.column`:
+
+```ruby
+SqlBeautifier.call("SELECT users.id, users.name FROM users WHERE users.active = true")
+```
+
+Produces:
+
+```sql
+select  u.id,
+        u.name
+
+from    Users u
+
+where   u.active = true
+```
+
+When two tables produce the same initials, a counter is appended for disambiguation (e.g. `u1`, `u2`).
+
+### JOINs
+
+JOIN clauses are formatted on continuation-indented lines with PascalCase table names and aliases. Multi-condition JOINs place additional conditions on further-indented lines:
+
+```ruby
+SqlBeautifier.call(<<~SQL)
+  SELECT users.id, orders.total, products.name
+  FROM users
+  INNER JOIN orders ON orders.user_id = users.id
+  INNER JOIN products ON products.id = orders.product_id
+  WHERE users.active = true AND orders.total > 100
+  ORDER BY orders.total DESC
+SQL
+```
+
+Produces:
+
+```sql
+select  u.id,
+        o.total,
+        p.name
+
+from    Users u
+        inner join Orders o on o.user_id = u.id
+        inner join Products p on p.id = o.product_id
+
+where   u.active = true
+        and o.total > 100
+
+order by o.total desc
+```
+
+Supported join types: `inner join`, `left join`, `right join`, `full join`, `left outer join`, `right outer join`, `full outer join`, `cross join`.
+
+### DISTINCT and DISTINCT ON
+
+`DISTINCT` is placed on the `select` line as a modifier, with columns on continuation lines:
+
+```ruby
+SqlBeautifier.call("SELECT DISTINCT id, name, email FROM users")
+```
+
+Produces:
+
+```sql
+select  distinct
+        id,
+        name,
+        email
+
+from    Users u
+```
+
+`DISTINCT ON` preserves the full expression:
+
+```ruby
+SqlBeautifier.call("SELECT DISTINCT ON (user_id) id, name FROM events")
+```
+
+Produces:
+
+```sql
+select  distinct on (user_id)
+        id,
+        name
+
+from    Events e
+```
+
+### WHERE and HAVING Conditions
+
+Multiple conditions in WHERE and HAVING clauses are formatted with each condition on its own line:
+
+```ruby
+SqlBeautifier.call("SELECT * FROM users WHERE active = true AND role = 'admin' AND created_at > '2024-01-01'")
+```
+
+Produces:
+
+```sql
+select  *
+
+from    Users u
+
+where   active = true
+        and role = 'admin'
+        and created_at > '2024-01-01'
+```
+
+Short parenthesized groups stay inline:
+
+```ruby
+SqlBeautifier.call("SELECT * FROM users WHERE active = true AND (role = 'admin' OR role = 'moderator')")
+```
+
+Produces:
+
+```sql
+select  *
+
+from    Users u
+
+where   active = true
+        and (role = 'admin' or role = 'moderator')
+```
 
 ### GROUP BY and HAVING
 
@@ -67,7 +202,7 @@ Produces:
 select  status,
         count(*)
 
-from    users
+from    Users u
 
 group by status
 
@@ -84,11 +219,8 @@ Produces:
 
 ```sql
 select  id
-
-from    users
-
+from    Users u
 order by created_at desc
-
 limit 25
 ```
 
@@ -105,9 +237,10 @@ Produces:
 ```sql
 select  *
 
-from    users
+from    Users u
 
-where   name = 'O''Brien' and status = 'Active'
+where   name = 'O''Brien'
+        and status = 'Active'
 ```
 
 ### Double-Quoted Identifiers
@@ -124,7 +257,88 @@ Produces:
 select  user_id,
         full_name
 
-from    users
+from    Users u
+```
+
+### Subqueries
+
+Subqueries are automatically detected and recursively formatted with indentation:
+
+```ruby
+SqlBeautifier.call("SELECT id FROM users WHERE id IN (SELECT user_id FROM orders WHERE total > 100)")
+```
+
+Produces:
+
+```sql
+select  id
+from    Users u
+where   id in (
+            select  user_id
+            from    Orders o
+            where   total > 100
+        )
+```
+
+Nested subqueries increase indentation at each level.
+
+### Comments and Semicolons
+
+SQL comments (`--` line comments and `/* */` block comments) and trailing semicolons are automatically stripped during normalization. Comments inside string literals are preserved:
+
+```ruby
+SqlBeautifier.call("SELECT id /* primary key */ FROM users -- main table\nWHERE active = true;")
+```
+
+Produces:
+
+```sql
+select  id
+from    Users u
+where   active = true
+```
+
+### Configuration
+
+Customize formatting behavior with `SqlBeautifier.configure`:
+
+```ruby
+SqlBeautifier.configure do |config|
+  config.keyword_case = :upper           # :lower (default), :upper
+  config.keyword_column_width = 10       # default: 8
+  config.indent_spaces = 4               # default: 4
+  config.clause_spacing_mode = :spacious # :compact (default), :spacious
+  config.table_name_format = :lowercase  # :pascal_case (default), :lowercase
+  config.inline_group_threshold = 80     # default: 100
+  config.alias_strategy = :none          # :initials (default), :none, or a callable
+end
+```
+
+#### Clause Spacing Modes
+
+- `:compact` (default) keeps top-level clauses on single newlines only when the query is simple:
+  - exactly one SELECT column
+  - exactly one FROM table (no JOINs)
+  - zero or one top-level WHERE condition
+  - only `select`, `from`, optional `where`, optional `order by`, and optional `limit`
+- `:spacious` always separates top-level clauses with blank lines
+
+Reset to defaults:
+
+```ruby
+SqlBeautifier.reset_configuration!
+```
+
+#### Alias Strategies
+
+- `:initials` (default) — automatic aliases using table initials (`users` → `u`, `active_storage_blobs` → `asb`)
+- `:none` — no automatic aliases (explicit aliases in the SQL are still preserved)
+- Callable — provide a proc/lambda for custom alias generation:
+
+```ruby
+SqlBeautifier.configure do |config|
+  config.alias_strategy = ->(table_name) { "t_#{table_name[0..2]}" }
+end
 ```
 
 ### Callable Interface

data/lib/sql_beautifier/clauses/base.rb

@@ -10,6 +10,16 @@ module SqlBeautifier
       def initialize(value)
         @value = value
       end
+
+      private
+
+      def keyword_prefix
+        Util.keyword_padding(self.class::KEYWORD)
+      end
+
+      def continuation_indent
+        Util.continuation_padding
+      end
     end
   end
 end

data/lib/sql_beautifier/clauses/condition_clause.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  module Clauses
+    class ConditionClause < Base
+      def call
+        return "#{keyword_prefix}#{@value.strip}" unless multiple_conditions?
+
+        formatted_conditions = ConditionFormatter.format(@value, indent_width: SqlBeautifier.config_for(:keyword_column_width))
+        formatted_conditions.sub(continuation_indent, keyword_prefix)
+      end
+
+      private
+
+      def multiple_conditions?
+        Tokenizer.split_top_level_conditions(@value).length > 1
+      end
+    end
+  end
+end

data/lib/sql_beautifier/clauses/from.rb

@@ -3,10 +3,147 @@
 module SqlBeautifier
   module Clauses
     class From < Base
-      KEYWORD_PREFIX = "from    "
+      KEYWORD = "from"
+
+      def self.call(value, table_registry:)
+        new(value, table_registry: table_registry).call
+      end
+
+      def initialize(value, table_registry:)
+        super(value)
+        @table_registry = table_registry
+      end
 
       def call
-        "#{KEYWORD_PREFIX}#{@value.strip}"
+        @lines = []
+
+        join_parts = split_join_parts
+        primary_table_text = join_parts.shift.strip
+        formatted_primary_table_name = format_table_with_alias(primary_table_text)
+        add_line!("#{keyword_prefix}#{formatted_primary_table_name}")
+
+        join_parts.each { |join_part| format_join_part(join_part) }
+
+        @lines.join("\n")
+      end
+
+      private
+
+      def add_line!(line)
+        @lines << line
+      end
+
+      def join_condition_indentation
+        Util.whitespace(SqlBeautifier.config_for(:keyword_column_width) + 4)
+      end
+
+      def format_join_part(join_part)
+        join_keyword, remaining_join_content = extract_join_keyword(join_part)
+        return unless join_keyword && remaining_join_content
+
+        on_keyword_position = Tokenizer.find_top_level_keyword(remaining_join_content, "on")
+
+        if on_keyword_position
+          format_join_with_conditions(join_keyword, remaining_join_content, on_keyword_position)
+        else
+          formatted_table_name = format_table_with_alias(remaining_join_content)
+          add_line!("#{continuation_indent}#{join_keyword} #{formatted_table_name}")
+        end
+      end
+
+      def format_join_with_conditions(join_keyword, join_content, on_keyword_position)
+        table_text = join_content[0...on_keyword_position].strip
+        condition_text = join_content[on_keyword_position..].delete_prefix("on").strip
+        on_conditions = Tokenizer.split_top_level_conditions(condition_text)
+
+        formatted_table_name = format_table_with_alias(table_text)
+        first_condition = on_conditions.first[1]
+        add_line!("#{continuation_indent}#{join_keyword} #{formatted_table_name} on #{first_condition}")
+
+        on_conditions.drop(1).each do |conjunction, additional_condition|
+          add_line!("#{join_condition_indentation}#{conjunction} #{additional_condition}")
+        end
+      end
+
+      def split_join_parts
+        from_content = @value.strip
+        join_keyword_positions = find_all_join_keyword_positions(from_content)
+
+        return [from_content] if join_keyword_positions.empty?
+
+        parts = [from_content[0...join_keyword_positions.first[:position]]]
+
+        join_keyword_positions.each_with_index do |join_info, index|
+          end_position = begin
+            if index + 1 < join_keyword_positions.length
+              join_keyword_positions[index + 1][:position]
+            else
+              from_content.length
+            end
+          end
+
+          parts << from_content[join_info[:position]...end_position]
+        end
+
+        parts
+      end
+
+      def find_all_join_keyword_positions(text)
+        positions = []
+        search_offset = 0
+
+        while search_offset < text.length
+          earliest_match = find_earliest_join_keyword(text, search_offset)
+          break unless earliest_match
+
+          positions << earliest_match
+          search_offset = earliest_match[:position] + earliest_match[:keyword].length
+        end
+
+        positions
+      end
+
+      def find_earliest_join_keyword(text, search_offset)
+        earliest_match = nil
+
+        Constants::JOIN_KEYWORDS_BY_LENGTH.each do |keyword|
+          remaining_text = text[search_offset..]
+          keyword_position = Tokenizer.find_top_level_keyword(remaining_text, keyword)
+          next unless keyword_position
+
+          absolute_position = search_offset + keyword_position
+          next if earliest_match && absolute_position >= earliest_match[:position]
+
+          earliest_match = {
+            position: absolute_position,
+            keyword: keyword,
+          }
+        end
+
+        earliest_match
+      end
+
+      def extract_join_keyword(join_part)
+        trimmed_join_text = join_part.strip
+
+        Constants::JOIN_KEYWORDS_BY_LENGTH.each do |keyword|
+          next unless trimmed_join_text.downcase.start_with?(keyword)
+
+          remaining_join_content = trimmed_join_text[keyword.length..].strip
+
+          return [keyword, remaining_join_content]
+        end
+
+        [nil, nil]
+      end
+
+      def format_table_with_alias(table_text)
+        table_name = Util.first_word(table_text)
+        formatted_table_name = Util.format_table_name(table_name)
+        table_alias = @table_registry.alias_for(table_name)
+        return formatted_table_name unless table_alias
+
+        "#{formatted_table_name} #{table_alias}"
       end
     end
   end

data/lib/sql_beautifier/clauses/group_by.rb

@@ -3,10 +3,10 @@
 module SqlBeautifier
   module Clauses
     class GroupBy < Base
-      KEYWORD_PREFIX = "group by "
+      KEYWORD = "group by"
 
       def call
-        "#{KEYWORD_PREFIX}#{@value.strip}"
+        "#{keyword_prefix}#{@value.strip}"
       end
     end
   end

data/lib/sql_beautifier/clauses/having.rb

@@ -2,12 +2,8 @@
 
 module SqlBeautifier
   module Clauses
-    class Having < Base
-      KEYWORD_PREFIX = "having  "
-
-      def call
-        "#{KEYWORD_PREFIX}#{@value.strip}"
-      end
+    class Having < ConditionClause
+      KEYWORD = "having"
     end
   end
 end

data/lib/sql_beautifier/clauses/limit.rb

@@ -3,10 +3,16 @@
 module SqlBeautifier
   module Clauses
     class Limit < Base
-      KEYWORD_PREFIX = "limit "
+      KEYWORD = "limit"
 
       def call
-        "#{KEYWORD_PREFIX}#{@value.strip}"
+        "#{keyword_prefix}#{@value.strip}"
+      end
+
+      private
+
+      def keyword_prefix
+        "#{Util.format_keyword(KEYWORD)} "
       end
     end
   end

data/lib/sql_beautifier/clauses/order_by.rb

@@ -3,10 +3,10 @@
 module SqlBeautifier
   module Clauses
     class OrderBy < Base
-      KEYWORD_PREFIX = "order by "
+      KEYWORD = "order by"
 
       def call
-        "#{KEYWORD_PREFIX}#{@value.strip}"
+        "#{keyword_prefix}#{@value.strip}"
       end
     end
   end

data/lib/sql_beautifier/clauses/select.rb

@@ -3,18 +3,72 @@
 module SqlBeautifier
   module Clauses
     class Select < Base
-      KEYWORD_PREFIX = "select  "
-      CONTINUATION_INDENT = "        "
+      KEYWORD = "select"
+      DISTINCT_ON_PARENTHESIS_PATTERN = %r{distinct on\s*\(}
+      DISTINCT_ON_PATTERN = %r{distinct on }
+      LEADING_COMMA_PATTERN = %r{\A,\s*}
 
       def call
-        columns = Tokenizer.split_by_top_level_commas(@value)
-        return "#{KEYWORD_PREFIX}#{columns.first.strip}" if columns.length == 1
+        prefix, remaining_columns = extract_prefix
+        columns = Tokenizer.split_by_top_level_commas(remaining_columns)
 
-        column_lines = columns.map { |column| "#{CONTINUATION_INDENT}#{column.strip}" }
-        column_lines[0] = "#{KEYWORD_PREFIX}#{columns.first.strip}"
+        return format_with_prefix(prefix, columns) if prefix
+        return keyword_line(columns.first) if columns.length == 1
+
+        format_columns_list(columns)
+      end
+
+      private
+
+      def keyword_line(column)
+        "#{keyword_prefix}#{column.strip}"
+      end
+
+      def continuation_line(column)
+        "#{continuation_indent}#{column.strip}"
+      end
+
+      def format_with_prefix(prefix, columns)
+        first_line = "#{keyword_prefix}#{prefix}"
+        column_lines = columns.map { |column| continuation_line(column) }
+
+        "#{first_line}\n#{column_lines.join(",\n")}"
+      end
+
+      def format_columns_list(columns)
+        column_lines = columns.map { |column| continuation_line(column) }
+        column_lines[0] = keyword_line(columns.first)
 
         column_lines.join(",\n")
       end
+
+      def extract_prefix
+        stripped_value = @value.strip
+
+        if stripped_value.start_with?("distinct on ")
+          extract_distinct_on_prefix(stripped_value)
+        elsif stripped_value.start_with?("distinct ")
+          remaining_columns = stripped_value.delete_prefix("distinct ").strip
+
+          ["distinct", remaining_columns]
+        else
+          [nil, stripped_value]
+        end
+      end
+
+      def extract_distinct_on_prefix(stripped_value)
+        distinct_on_position = stripped_value.index(DISTINCT_ON_PARENTHESIS_PATTERN) || stripped_value.index(DISTINCT_ON_PATTERN)
+        opening_parenthesis_position = stripped_value.index(Constants::OPEN_PARENTHESIS, distinct_on_position)
+        return [nil, stripped_value] unless opening_parenthesis_position
+
+        closing_parenthesis_position = Tokenizer.find_matching_parenthesis(stripped_value, opening_parenthesis_position)
+        return [nil, stripped_value] unless closing_parenthesis_position
+
+        prefix = stripped_value[0..closing_parenthesis_position]
+        remaining_columns = stripped_value[(closing_parenthesis_position + 1)..].strip.sub(LEADING_COMMA_PATTERN, "")
+
+        [prefix, remaining_columns]
+      end
     end
   end
 end

data/lib/sql_beautifier/clauses/where.rb

@@ -2,12 +2,8 @@
 
 module SqlBeautifier
   module Clauses
-    class Where < Base
-      KEYWORD_PREFIX = "where   "
-
-      def call
-        "#{KEYWORD_PREFIX}#{@value.strip}"
-      end
+    class Where < ConditionClause
+      KEYWORD = "where"
     end
   end
 end