json2sql 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40d7668af9e81534fea68e0745ccb82901d144b1cd3f8851999442262f6e3167
+  data.tar.gz: d12e2089964c6eecfbd752025f492d56f78bdf72102bb1879d0e57056765ae2a
+SHA512:
+  metadata.gz: 1bdf680bb7009a436cbe5fcdfa70dd6b69036259f61c26b111b72ed3e8d07ed52528b2ffda79d15db4e0a7a6887cfea2e0c99ca504d421ac06c479eb4ac1a2ed
+  data.tar.gz: 7f5187f7f7d1bc36284d7fb11bef6273dba90e4f7deb78cf286909831bd0e62a6a02e1354e6ed193e2f7c631f04ee72f87f16ff41c2a37af2a2e79b9b6adb4f4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tiago da Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/json2sql/delete_model.rb

@@ -0,0 +1,20 @@
+module Json2sql
+  # Builds a DELETE FROM statement for a single table.
+  #
+  # Input Hash:
+  #   "and" => { ... }   – WHERE conditions (required to avoid deleting all rows)
+  #   "or"  => { ... }   – WHERE conditions (OR)
+  class DeleteModel
+    def initialize(sql, table, relation)
+      @sql      = sql
+      @table    = table.to_s
+      @relation = relation
+    end
+
+    def build(params)
+      @sql << "DELETE FROM "
+      @sql << Sanitizer.keyword_wrap(@table)
+      WhereModel.new(@sql, @table, @relation).build(params)
+    end
+  end
+end

data/lib/json2sql/delete_runner.rb

@@ -0,0 +1,42 @@
+module Json2sql
+  # Builds one or more DELETE statements from a Hash of table → params.
+  #
+  # Usage (single deletion):
+  #   sql = Json2sql::DeleteRunner.build(
+  #     "users" => { "and" => { "id" => 42 } }
+  #   )
+  #
+  # Usage (multiple deletions — value is an Array):
+  #   sql = Json2sql::DeleteRunner.build(
+  #     "sessions" => [
+  #       { "and" => { "user_id" => 1 } },
+  #       { "and" => { "user_id" => 2 } }
+  #     ]
+  #   )
+  class DeleteRunner
+    def self.build(input)
+      input    = Json2sql.normalize(input)
+      sql      = +""
+      relation = WhereRelation.none("")
+
+      input.each do |table, value|
+        tbl = table.to_s
+
+        case value
+        when Hash
+          DeleteModel.new(sql, tbl, relation).build(value)
+          sql << ";\n"
+        when Array
+          value.each do |item|
+            next unless item.is_a?(Hash)
+
+            DeleteModel.new(sql, tbl, relation).build(item)
+            sql << ";\n"
+          end
+        end
+      end
+
+      sql
+    end
+  end
+end

data/lib/json2sql/insert_model.rb

@@ -0,0 +1,56 @@
+module Json2sql
+  # Builds an INSERT INTO statement for a single table.
+  #
+  # Input Hash:
+  #   "columns" => { "col_name" => value, ... }
+  #
+  # Values:
+  #   Integer / Float → inserted as raw numbers
+  #   String          → wrapped in single quotes with SQL escaping
+  class InsertModel
+    def initialize(sql, table)
+      @sql   = sql
+      @table = table.to_s
+    end
+
+    def build(params)
+      @sql << "INSERT INTO "
+      @sql << Sanitizer.keyword_wrap(@table)
+      @sql << " ("
+      build_columns(params)
+      @sql << ") VALUES ("
+      build_values(params)
+      @sql << ")"
+    end
+
+    private
+
+    def build_columns(params)
+      columns  = params["columns"]
+      return unless columns.is_a?(Hash)
+
+      separator = false
+      columns.each_key do |key|
+        @sql << ", " if separator
+        separator = true
+        @sql << Sanitizer.keyword_wrap(key.to_s)
+      end
+    end
+
+    def build_values(params)
+      columns  = params["columns"]
+      return unless columns.is_a?(Hash)
+
+      separator = false
+      columns.each_value do |value|
+        @sql << ", " if separator
+        separator = true
+
+        case value
+        when Integer, Float then @sql << value.to_s
+        when String         then @sql << Sanitizer.value_wrap(value)
+        end
+      end
+    end
+  end
+end

data/lib/json2sql/insert_runner.rb

@@ -0,0 +1,41 @@
+module Json2sql
+  # Builds one or more INSERT statements from a Hash of table → params.
+  #
+  # Usage (single row):
+  #   sql = Json2sql::InsertRunner.build(
+  #     "users" => { "columns" => { "name" => "João", "email" => "j@x.com" } }
+  #   )
+  #
+  # Usage (multiple rows — value is an Array):
+  #   sql = Json2sql::InsertRunner.build(
+  #     "tags" => [
+  #       { "columns" => { "name" => "ruby" } },
+  #       { "columns" => { "name" => "rails" } }
+  #     ]
+  #   )
+  class InsertRunner
+    def self.build(input)
+      input = Json2sql.normalize(input)
+      sql   = +""
+
+      input.each do |table, value|
+        tbl = table.to_s
+
+        case value
+        when Hash
+          InsertModel.new(sql, tbl).build(value)
+          sql << ";\n"
+        when Array
+          value.each do |item|
+            next unless item.is_a?(Hash)
+
+            InsertModel.new(sql, tbl).build(item)
+            sql << ";\n"
+          end
+        end
+      end
+
+      sql
+    end
+  end
+end

data/lib/json2sql/sanitizer.rb

@@ -0,0 +1,49 @@
+module Json2sql
+  module Sanitizer
+    # Characters stripped from SQL identifiers (table/column names).
+    KEYWORD_DANGEROUS = /[ `;"'\\]/
+
+    # Removes dangerous characters from an identifier string.
+    def self.keyword(input)
+      input.to_s.gsub(KEYWORD_DANGEROUS, "")
+    end
+
+    # Escapes a value string for safe embedding between SQL quotes.
+    # ' → ''   and   \ → \\
+    def self.value(input)
+      input.to_s.gsub("\\", "\\\\\\\\").gsub("'", "''")
+    end
+
+    # Wraps an identifier in the given quote character (default: backtick).
+    # Dangerous characters inside the identifier are stripped.
+    def self.keyword_wrap(input, wrap = "`")
+      "#{wrap}#{keyword(input)}#{wrap}"
+    end
+
+    # Wraps a value in the given quote character (default: single-quote).
+    # Single quotes and backslashes inside the value are escaped.
+    def self.value_wrap(input, wrap = "'")
+      "#{wrap}#{value(input)}#{wrap}"
+    end
+
+    # Converts a JSON path reference (e.g. "$.users.id") into a
+    # backtick-quoted SQL reference (e.g. "`users`.`id`").
+    # Strips the leading "$." and splits on ".".
+    def self.reference(input)
+      str = input.to_s[2..] # strip leading "$."
+      result = +"`"
+      str.each_char do |c|
+        case c
+        when "."
+          result << "`.`"
+        when " ", "`", ";", '"', "'", "\\"
+          # skip dangerous characters
+        else
+          result << c
+        end
+      end
+      result << "`"
+      result
+    end
+  end
+end

data/lib/json2sql/select_model.rb

@@ -0,0 +1,222 @@
+module Json2sql
+  # Builds a SELECT SQL statement for a single table.
+  #
+  # Input Hash keys (all optional):
+  #   "columns"  => ["id", "name", ...]   – columns to SELECT
+  #   "where"    => { "and" => {...} }    – WHERE conditions (see WhereModel)
+  #   "and"      => {...}                 – shorthand for top-level AND WHERE
+  #   "or"       => {...}                 – shorthand for top-level OR WHERE
+  #   "order"    => { "col" => "asc" }   – ORDER BY
+  #   "limit"    => 10                   – LIMIT
+  #   "offset"   => 20                   – OFFSET
+  #   "options"  => ["total"]            – wrap response with data/total JSON
+  #   "children" => { "table" => {...} } – nested child arrays
+  #   "parents"  => { "table" => {...} } – nested parent objects
+  class SelectModel
+    def initialize(sql, table, relation)
+      @sql      = sql
+      @table    = table.to_s
+      @relation = relation
+    end
+
+    # SELECT COUNT(*) AS `table` FROM `table` WHERE ...
+    def build_query_count(params)
+      @sql << "SELECT COUNT(*) AS "
+      @sql << Sanitizer.keyword_wrap(@table)
+      @sql << " FROM "
+      @sql << Sanitizer.keyword_wrap(@table)
+      WhereModel.new(@sql, @table, @relation).build(params)
+    end
+
+    # Plain SELECT col1, col2 FROM `table` WHERE ... ORDER BY ... LIMIT ... OFFSET ...
+    def build_query_default(params)
+      @sep = false
+      @sql << "SELECT "
+      build_columns_default(params)
+      @sql << " FROM "
+      @sql << Sanitizer.keyword_wrap(@table)
+      WhereModel.new(@sql, @table, @relation).build(params)
+      build_order(params)
+      build_limit(params)
+      build_offset(params)
+    end
+
+    # SELECT JSON_ARRAYAGG(JSON_OBJECT(...)) AS `table`
+    # FROM LATERAL (SELECT * FROM `table` WHERE ... ORDER ... LIMIT ...) AS `table`
+    def build_query_array(params)
+      @sep = false
+      @sql << "SELECT JSON_ARRAYAGG(JSON_OBJECT("
+      build_columns_json(params)
+      build_columns_array(params)
+      build_columns_object(params)
+      @sql << ")) AS "
+      @sql << Sanitizer.keyword_wrap(@table)
+      @sql << " FROM LATERAL (SELECT * FROM "
+      @sql << Sanitizer.keyword_wrap(@table)
+      WhereModel.new(@sql, @table, @relation).build(params)
+      build_order(params)
+      build_limit(params)
+      build_offset(params)
+      @sql << ") AS "
+      @sql << Sanitizer.keyword_wrap(@table)
+    end
+
+    # SELECT JSON_OBJECT(...) AS `table`
+    # FROM LATERAL (SELECT * FROM `table` WHERE ...) AS `table`
+    def build_query_object(params)
+      @sep = false
+      @sql << "SELECT JSON_OBJECT("
+      build_columns_json(params)
+      build_columns_array(params)
+      build_columns_object(params)
+      @sql << ") AS "
+      @sql << Sanitizer.keyword_wrap(@table)
+      @sql << " FROM LATERAL (SELECT * FROM "
+      @sql << Sanitizer.keyword_wrap(@table)
+      WhereModel.new(@sql, @table, @relation).build(params)
+      build_order(params)
+      build_limit(params)
+      build_offset(params)
+      @sql << ") AS "
+      @sql << Sanitizer.keyword_wrap(@table)
+    end
+
+    # Smart dispatcher:
+    #   - no options → build_query_array
+    #   - options includes "total" → wraps with JSON_OBJECT('data', ..., 'total', COUNT(*))
+    def build_query_options(params)
+      options = params["options"]
+
+      unless options.is_a?(Array) && !options.empty?
+        build_query_array(params)
+        return
+      end
+
+      total = options.include?("total")
+
+      @sql << "SELECT JSON_OBJECT('data', ("
+      build_query_array(params)
+      @sql << ")"
+
+      if total
+        @sql << ", 'total', ("
+        build_query_count(params)
+        @sql << ")"
+      end
+
+      @sql << ")"
+    end
+
+    private
+
+    # @sep is a shared separator flag used by build_columns_* to coordinate
+    # comma placement across multiple calls within a single query build.
+
+    # Appends plain column references: `table`.`col`, `table`.`col2`, ...
+    def build_columns_default(params)
+      columns = params["columns"]
+      return unless columns.is_a?(Array)
+
+      columns.each do |column|
+        next unless column.is_a?(String) || column.is_a?(Symbol)
+
+        @sql << ", " if @sep
+        @sep = true
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column.to_s)
+      end
+    end
+
+    # Appends JSON key-value pairs for columns: 'col', `table`.`col`, ...
+    def build_columns_json(params)
+      columns = params["columns"]
+      return unless columns.is_a?(Array)
+
+      columns.each do |column|
+        next unless column.is_a?(String) || column.is_a?(Symbol)
+
+        @sql << ", " if @sep
+        @sep = true
+        col = column.to_s
+        @sql << Sanitizer.keyword_wrap(col, "'")
+        @sql << ", "
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(col)
+      end
+    end
+
+    # Appends nested child arrays (subquery → JSON_ARRAYAGG).
+    # Uses WhereRelation::PARENT because child table references parent.
+    def build_columns_array(params)
+      children = params["children"]
+      return unless children.is_a?(Hash)
+
+      relation = WhereRelation.parent(@table)
+
+      children.each do |key, value|
+        next unless value.is_a?(Hash)
+
+        @sql << ", " if @sep
+        @sep = true
+        tbl = key.to_s
+        @sql << Sanitizer.keyword_wrap(tbl, "'")
+        @sql << ", ("
+        SelectModel.new(@sql, tbl, relation).build_query_options(value)
+        @sql << ")"
+      end
+    end
+
+    # Appends nested parent objects (subquery → JSON_OBJECT, single row).
+    # Uses WhereRelation::CHILD because parent table is referenced from child.
+    def build_columns_object(params)
+      parents = params["parents"]
+      return unless parents.is_a?(Hash)
+
+      relation = WhereRelation.child(@table)
+
+      parents.each do |key, value|
+        next unless value.is_a?(Hash)
+
+        @sql << ", " if @sep
+        @sep = true
+        tbl = key.to_s
+        @sql << Sanitizer.keyword_wrap(tbl, "'")
+        @sql << ", ("
+        SelectModel.new(@sql, tbl, relation).build_query_object(value)
+        @sql << ")"
+      end
+    end
+
+    def build_order(params)
+      order = params["order"]
+      return unless order.is_a?(Hash) && !order.empty?
+
+      @sql << " ORDER BY "
+      glue = false
+
+      order.each do |key, value|
+        @sql << ", " if glue
+        glue = true
+
+        column = key.to_s
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+
+        case value.to_s.downcase
+        when "asc"  then @sql << " ASC"
+        when "desc" then @sql << " DESC"
+        end
+      end
+    end
+
+    def build_limit(params)
+      limit = params["limit"]
+      @sql << " LIMIT #{limit}" if limit.is_a?(Integer)
+    end
+
+    def build_offset(params)
+      offset = params["offset"]
+      @sql << " OFFSET #{offset}" if offset.is_a?(Integer)
+    end
+  end
+end

data/lib/json2sql/select_runner.rb

@@ -0,0 +1,44 @@
+module Json2sql
+  # Builds a top-level SELECT statement from a Hash of table → params.
+  #
+  # Usage:
+  #   sql = Json2sql::SelectRunner.build(
+  #     "users" => {
+  #       "columns" => ["id", "name", "email"],
+  #       "and"     => { "active" => 1, "role" => { "in" => [1, 2] } },
+  #       "order"   => { "created_at" => "desc" },
+  #       "limit"   => 20,
+  #       "offset"  => 0,
+  #       "options" => ["total"]
+  #     }
+  #   )
+  #
+  # Output wraps every table in JSON_OBJECT so the client receives a single
+  # JSON document:
+  #   SELECT JSON_OBJECT('users', (...));
+  class SelectRunner
+    def self.build(input)
+      input    = Json2sql.normalize(input)
+      sql      = +""
+      separator = false
+      relation  = WhereRelation.none("")
+
+      sql << "SELECT JSON_OBJECT("
+
+      input.each do |table, value|
+        next unless value.is_a?(Hash)
+
+        sql << ", " if separator
+        separator = true
+
+        sql << Sanitizer.keyword_wrap(table.to_s, "'")
+        sql << ", ("
+        SelectModel.new(sql, table.to_s, relation).build_query_options(value)
+        sql << ")"
+      end
+
+      sql << ");\n"
+      sql
+    end
+  end
+end

data/lib/json2sql/update_model.rb

@@ -0,0 +1,48 @@
+module Json2sql
+  # Builds an UPDATE statement for a single table.
+  #
+  # Input Hash:
+  #   "columns" => { "col" => value, ... }  – columns to SET
+  #   "and"     => { ... }                  – WHERE conditions
+  #   "or"      => { ... }                  – WHERE conditions (OR)
+  #
+  # Value types follow the same rules as InsertModel.
+  class UpdateModel
+    def initialize(sql, table, relation)
+      @sql      = sql
+      @table    = table.to_s
+      @relation = relation
+    end
+
+    def build(params)
+      @sql << "UPDATE "
+      @sql << Sanitizer.keyword_wrap(@table)
+      @sql << " SET "
+      build_columns(params)
+      WhereModel.new(@sql, @table, @relation).build(params)
+    end
+
+    private
+
+    def build_columns(params)
+      columns   = params["columns"]
+      return unless columns.is_a?(Hash)
+
+      separator = false
+      columns.each do |key, value|
+        @sql << ", " if separator
+        separator = true
+
+        column = key.to_s
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " = "
+
+        case value
+        when Integer, Float then @sql << value.to_s
+        when String         then @sql << Sanitizer.value_wrap(value)
+        end
+      end
+    end
+  end
+end

data/lib/json2sql/update_runner.rb

@@ -0,0 +1,45 @@
+module Json2sql
+  # Builds one or more UPDATE statements from a Hash of table → params.
+  #
+  # Usage (single row):
+  #   sql = Json2sql::UpdateRunner.build(
+  #     "users" => {
+  #       "columns" => { "name" => "Maria", "updated_at" => "2026-04-12" },
+  #       "and"     => { "id" => 42 }
+  #     }
+  #   )
+  #
+  # Usage (multiple rows — value is an Array):
+  #   sql = Json2sql::UpdateRunner.build(
+  #     "settings" => [
+  #       { "columns" => { "value" => "dark" },  "and" => { "key" => "theme" } },
+  #       { "columns" => { "value" => "en" },    "and" => { "key" => "lang" } }
+  #     ]
+  #   )
+  class UpdateRunner
+    def self.build(input)
+      input    = Json2sql.normalize(input)
+      sql      = +""
+      relation = WhereRelation.none("")
+
+      input.each do |table, value|
+        tbl = table.to_s
+
+        case value
+        when Hash
+          UpdateModel.new(sql, tbl, relation).build(value)
+          sql << ";\n"
+        when Array
+          value.each do |item|
+            next unless item.is_a?(Hash)
+
+            UpdateModel.new(sql, tbl, relation).build(item)
+            sql << ";\n"
+          end
+        end
+      end
+
+      sql
+    end
+  end
+end

data/lib/json2sql/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Json2sql
+  VERSION = "1.0.0"
+end

data/lib/json2sql/where_model.rb

@@ -0,0 +1,262 @@
+module Json2sql
+  # Builds a SQL WHERE clause from a Hash describing the conditions.
+  #
+  # Input structure mirrors the JSON format used in the C++ backend:
+  #
+  #   {
+  #     "and" => {
+  #       "name"   => "john",           # implicit LIKE '%john%'
+  #       "age"    => 30,               # implicit equality
+  #       "status" => { "in" => [1,2] },
+  #       "score"  => { ">=" => 4.5 },
+  #       "col"    => { "null" => true },  # IS NULL / IS NOT NULL
+  #       "ref"    => { "=" => "$.table.col" }  # column reference
+  #     },
+  #     "or" => { ... }
+  #   }
+  #
+  # Supported operators: =  <  >  <=  >=  !=  <>
+  #                       in  !in  like  !like
+  # String pseudo-actions: contains (LIKE %v%), first (LIKE v%), last (LIKE %v)
+  class WhereModel
+    def initialize(sql, table, relation)
+      @sql      = sql
+      @table    = table.to_s
+      @relation = relation
+    end
+
+    def build(params)
+      has_relation  = @relation.kind != WhereRelation::NONE
+      has_where_and = params["and"].is_a?(Hash)
+      has_where_or  = params["or"].is_a?(Hash)
+
+      return unless has_relation || has_where_and || has_where_or
+
+      @sql << " WHERE "
+
+      if has_relation
+        @relation.build_table_relation(@sql, @table)
+        @sql << " AND " if has_where_and || has_where_or
+      end
+
+      if has_where_and
+        build_column_group(params["and"], " AND ")
+        return
+      end
+
+      if has_where_or
+        build_column_group(params["or"], " OR ")
+      end
+    end
+
+    private
+
+    # -------------------------------------------------------------------------
+    # Group level
+    # -------------------------------------------------------------------------
+
+    def build_column_group(params, scope)
+      @sql << "("
+      glue = false
+
+      params.each do |key, value|
+        @sql << scope if glue
+        glue = true
+
+        build_column_types(value, scope, key.to_s)
+      end
+
+      @sql << ")"
+    end
+
+    # Dispatch by Ruby type of the value.
+    def build_column_types(params, scope, column)
+      case params
+      when TrueClass, FalseClass
+        build_action_types(params, column, "=")
+      when Integer
+        build_action_types(params, column, "=")
+      when String
+        build_action_types(params, column, "contains")
+      when Hash
+        if column == "and"
+          build_column_group(params, " AND ")
+        elsif column == "or"
+          build_column_group(params, " OR ")
+        else
+          build_action_group(params, scope, column)
+        end
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # Action level
+    # -------------------------------------------------------------------------
+
+    def build_action_group(params, scope, column)
+      glue = false
+
+      params.each do |key, value|
+        @sql << scope if glue
+        glue = true
+
+        build_action_types(value, column, key.to_s)
+      end
+    end
+
+    def build_action_types(params, column, action)
+      if action == "and"
+        build_column_types(params, " AND ", column)
+        return
+      end
+
+      if action == "or"
+        build_column_types(params, " OR ", column)
+        return
+      end
+
+      build_action_values(params, column, action)
+    end
+
+    # -------------------------------------------------------------------------
+    # Value level — emit the actual SQL comparison
+    # -------------------------------------------------------------------------
+
+    def build_action_values(params, column, action) # rubocop:disable Metrics/MethodLength
+      case params
+      when TrueClass, FalseClass
+        # Only "null" → IS NULL / IS NOT NULL. Boolean equality is not emitted
+        # (matches C++ behaviour — use integer 1/0 for boolean equality).
+        if action == "null"
+          action_str = params ? " IS " : " IS NOT "
+          @sql << Sanitizer.keyword_wrap(@table) << "."
+          @sql << Sanitizer.keyword_wrap(column)
+          @sql << action_str << "NULL"
+        end
+
+      when Integer
+        action_name = get_action(action)
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " #{action_name} #{params}"
+
+      when Float
+        action_name = get_action(action)
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " #{action_name} #{params}"
+
+      when String
+        build_action_string(params, column, action)
+
+      when Array
+        action_name = get_action(action)
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " #{action_name} ("
+        build_array(params)
+        @sql << ")"
+
+      when Hash
+        action_name = get_action(action)
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " #{action_name} ("
+        build_object(params)
+        @sql << ")"
+      end
+    end
+
+    def build_action_string(params, column, action)
+      action_name = get_action(action)
+
+      case action_name
+      when "last"
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " LIKE '%" << Sanitizer.value(params) << "'"
+
+      when "first"
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " LIKE '" << Sanitizer.value(params) << "%'"
+
+      when "contains"
+        @sql << Sanitizer.keyword_wrap(@table) << "."
+        @sql << Sanitizer.keyword_wrap(column)
+        @sql << " LIKE '%" << Sanitizer.value(params) << "%'"
+
+      else
+        if params.start_with?("$.")
+          @sql << Sanitizer.keyword_wrap(@table) << "."
+          @sql << Sanitizer.keyword_wrap(column)
+          @sql << " #{action_name} "
+          @sql << Sanitizer.reference(params)
+        else
+          @sql << Sanitizer.keyword_wrap(@table) << "."
+          @sql << Sanitizer.keyword_wrap(column)
+          @sql << " #{action_name} "
+          @sql << Sanitizer.value_wrap(params)
+        end
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # IN-list and subquery helpers
+    # -------------------------------------------------------------------------
+
+    def build_array(array)
+      if array.empty?
+        @sql << "NULL"
+        return
+      end
+
+      glue = false
+      array.each do |item|
+        @sql << ", " if glue
+        glue = true
+
+        case item
+        when Integer, Float then @sql << item.to_s
+        when String         then @sql << Sanitizer.value_wrap(item)
+        end
+      end
+    end
+
+    # Builds a UNION of sub-SELECTs (used when action value is a Hash of tables).
+    def build_object(object)
+      if object.empty?
+        @sql << "NULL"
+        return
+      end
+
+      glue = false
+      relation = WhereRelation.none(@table)
+
+      object.each do |key, value|
+        @sql << " UNION " if glue
+        glue = true
+
+        tbl = key.to_s
+        @sql << "("
+        SelectModel.new(@sql, tbl, relation).build_query_default(value)
+        @sql << ")"
+      end
+    end
+
+    # -------------------------------------------------------------------------
+    # Operator mapping
+    # -------------------------------------------------------------------------
+
+    def get_action(action)
+      case action
+      when "=", "<", ">", "<=", ">=", "!=", "<>" then action
+      when "in"    then "IN"
+      when "!in"   then "NOT IN"
+      when "like"  then "LIKE"
+      when "!like" then "NOT LIKE"
+      else action
+      end
+    end
+  end
+end

data/lib/json2sql/where_relation.rb

@@ -0,0 +1,76 @@
+module Json2sql
+  class WhereRelation
+    NONE   = :none
+    CHILD  = :child
+    PARENT = :parent
+
+    attr_reader :table, :kind
+
+    def initialize(table, kind)
+      @table = table.to_s
+      @kind  = kind
+    end
+
+    # Factory: no relationship (top-level query).
+    def self.none(table)
+      new(table, NONE)
+    end
+
+    # Factory: foreign key is on the child table pointing to the parent.
+    # Produces: `parent`.`child_id` = `current`.`id`
+    def self.child(table)
+      new(table, CHILD)
+    end
+
+    # Factory: foreign key is on the current/parent table pointing to the child.
+    # Produces: `current`.`parent_id` = `parent`.`id`
+    def self.parent(table)
+      new(table, PARENT)
+    end
+
+    # Appends the JOIN condition for this relationship into sql.
+    # +current+ is the name of the table being queried.
+    def build_table_relation(sql, current)
+      current = current.to_s
+
+      if kind == CHILD
+        sql << Sanitizer.keyword_wrap(table)
+        sql << "."
+        sql << build_table_id(current)
+        sql << " = "
+        sql << Sanitizer.keyword_wrap(current)
+        sql << ".`id`"
+        return
+      end
+
+      if kind == PARENT
+        sql << Sanitizer.keyword_wrap(current)
+        sql << "."
+        sql << build_table_id(table)
+        sql << " = "
+        sql << Sanitizer.keyword_wrap(table)
+        sql << ".`id`"
+      end
+    end
+
+    # Converts a (possibly plural) table name to its foreign-key column
+    # name wrapped in backticks.
+    #   "users"      → "`user_id`"
+    #   "categories" → "`category_id`"
+    #   "admins"     → "`admin_id`"
+    def build_table_id(tbl)
+      tbl  = tbl.to_s
+      base = Sanitizer.keyword(tbl)
+
+      name = if base.end_with?("ies")
+               base[0..-4] + "y"
+             elsif base.end_with?("s")
+               base[0..-2]
+             else
+               base
+             end
+
+      "`#{name}_id`"
+    end
+  end
+end

data/lib/json2sql.rb

@@ -0,0 +1,38 @@
+require_relative "json2sql/version"
+require_relative "json2sql/sanitizer"
+require_relative "json2sql/where_relation"
+require_relative "json2sql/where_model"
+require_relative "json2sql/select_model"
+require_relative "json2sql/select_runner"
+require_relative "json2sql/insert_model"
+require_relative "json2sql/insert_runner"
+require_relative "json2sql/update_model"
+require_relative "json2sql/update_runner"
+require_relative "json2sql/delete_model"
+require_relative "json2sql/delete_runner"
+
+# Json2sql — SQL builder that generates MySQL/MariaDB query strings from
+# plain Ruby Hashes (or parsed JSON).
+#
+# All Hash keys may be either Strings or Symbols; they are normalized to
+# Strings internally before processing.
+#
+# Entry points:
+#   Json2sql::SelectRunner.build(hash) → String
+#   Json2sql::InsertRunner.build(hash) → String
+#   Json2sql::UpdateRunner.build(hash) → String
+#   Json2sql::DeleteRunner.build(hash) → String
+module Json2sql
+  # Deep-converts all Hash keys to Strings and recurses into nested Hashes
+  # and Arrays. Leaves all other values (Integers, Strings, etc.) unchanged.
+  def self.normalize(obj)
+    case obj
+    when Hash
+      obj.each_with_object({}) { |(k, v), h| h[k.to_s] = normalize(v) }
+    when Array
+      obj.map { |v| normalize(v) }
+    else
+      obj
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: json2sql
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tiago da Silva
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Pure-Ruby SQL builder. No runtime dependencies. Supports SELECT (with
+  JSON aggregation and nesting), INSERT, UPDATE, and DELETE for MySQL/MariaDB.
+email:
+- tyagoy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- lib/json2sql.rb
+- lib/json2sql/delete_model.rb
+- lib/json2sql/delete_runner.rb
+- lib/json2sql/insert_model.rb
+- lib/json2sql/insert_runner.rb
+- lib/json2sql/sanitizer.rb
+- lib/json2sql/select_model.rb
+- lib/json2sql/select_runner.rb
+- lib/json2sql/update_model.rb
+- lib/json2sql/update_runner.rb
+- lib/json2sql/version.rb
+- lib/json2sql/where_model.rb
+- lib/json2sql/where_relation.rb
+homepage: https://github.com/tyagoy/json2sql
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tyagoy/json2sql
+  source_code_uri: https://github.com/tyagoy/json2sql
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Translates Ruby Hashes (or parsed JSON) into MySQL/MariaDB query strings.
+test_files: []