jsonq 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 676bb06e71303384551e79e47c6dae85d27b14b3213a23bb2aea09b8cabdfaa7
+  data.tar.gz: a41e7d14172dfd1ccb3f2127478705bdedc64cd3e08fa3ec1306d6db06076290
+SHA512:
+  metadata.gz: 164edf008bcfc3c4259d33c1938f0503c9f2b95728bc74b1131dfe5b823fe5e814b646b6343eea3ba5bdee6e8cd536b2c90c7bf39aa9569f7ace952463db86df
+  data.tar.gz: 1724bf837a1946aed6e4526ac477c4b9b164c0e48400a70886f02c922ea0598ae5f728aa7fba11856da131d7d65550f03976d86821394b397a3f98597c5b7797

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Marin
+
+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/README.md

@@ -0,0 +1,139 @@
+# jsonq
+
+[![Testing](https://github.com/avo-hq/jsonq/actions/workflows/testing.yml/badge.svg)](https://github.com/avo-hq/jsonq/actions/workflows/testing.yml)
+
+Friendly JSON column queries for ActiveRecord. Use `where` with JSON attributes just like regular columns.
+
+Supports PostgreSQL, MySQL, and SQLite.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "jsonq"
+```
+
+## Getting Started
+
+Add `jsonq_queryable` to your model:
+
+```ruby
+class Plan < ApplicationRecord
+  jsonq_queryable
+
+  store_accessor :metadata, :private_title, :category, :author
+end
+```
+
+Order doesn't matter — `jsonq_queryable` can go before or after `store_accessor`.
+
+Now query JSON attributes with `where`:
+
+```ruby
+Plan.where(private_title: "Draft")
+Plan.where(category: "work", status: "active")
+Plan.where(private_title: ["Draft", "Review"])
+Plan.where(private_title: nil)
+Plan.where.not(category: "archived")
+```
+
+## How It Works
+
+jsonq intercepts ActiveRecord's `PredicateBuilder` to translate JSON attribute names into database-specific path expressions:
+
+```
+Plan.where(private_title: "Draft")
+```
+
+Generates:
+
+```sql
+-- PostgreSQL
+WHERE "plans"."metadata"->>'private_title' = 'Draft'
+
+-- MySQL
+WHERE JSON_UNQUOTE(JSON_EXTRACT("plans"."metadata", '$.private_title')) = 'Draft'
+
+-- SQLite
+WHERE "plans"."metadata"->>'$.private_title' = 'Draft'
+```
+
+## store_accessor Integration
+
+Any `store_accessor` attributes on a native JSON/JSONB column are automatically registered. Declarations before or after `jsonq_queryable` both work.
+
+```ruby
+class Plan < ApplicationRecord
+  jsonq_queryable
+
+  store_accessor :metadata, :private_title, :category
+end
+
+Plan.where(private_title: "Draft")
+```
+
+When a `store_accessor` attribute name collides with a real database column, the real column takes precedence.
+
+Attributes declared with `prefix:` or `suffix:` are registered by their original key name (the JSON key), not the prefixed accessor name. Use `json_attribute` to query by a custom name.
+
+## Standalone DSL
+
+For nested JSON paths or attributes without `store_accessor`, use `json_attribute`:
+
+```ruby
+class Event < ApplicationRecord
+  jsonq_queryable
+
+  json_attribute :metadata, "address.billing.city", as: :billing_city
+  json_attribute :metadata, "organizer.name", as: :organizer_name
+end
+
+Event.where(billing_city: "Paris")
+Event.where(organizer_name: "Alice")
+```
+
+The `as:` option is required.
+
+## Query Support
+
+| Operation   | Example                                  |
+| ----------- | ---------------------------------------- |
+| Equality    | `where(key: "value")`                    |
+| Nil/NULL    | `where(key: nil)`                        |
+| IN (array)  | `where(key: ["a", "b"])`                 |
+| Negation    | `where.not(key: "value")`                |
+| Composition | `where(json_key: "x", real_column: "y")` |
+| Chaining    | `where(key: "x").where(other_key: "y")`  |
+
+## Database Support
+
+- **PostgreSQL** — JSONB and JSON columns
+- **MySQL 5.7+** — JSON columns
+- **SQLite 3.38+** — JSON1 extension
+
+The adapter is detected automatically from the ActiveRecord connection.
+
+## Non-Rails Usage
+
+If you use ActiveRecord without Rails, call `Jsonq.setup!` after establishing a connection:
+
+```ruby
+require "jsonq"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+Jsonq.setup!
+```
+
+## Requirements
+
+- Ruby >= 3.0
+- ActiveRecord >= 7.0
+
+## License
+
+MIT
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/avo-hq/jsonq).

data/lib/jsonq/adapters/abstract_adapter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jsonq
+  module Adapters
+    class AbstractAdapter
+      def build_path_expression(arel_table, column, path)
+        raise NotImplementedError, "#{self.class}#build_path_expression must be implemented"
+      end
+    end
+  end
+end

data/lib/jsonq/adapters/mysql_adapter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Jsonq
+  module Adapters
+    class MysqlAdapter < AbstractAdapter
+      def build_path_expression(arel_table, column, path)
+        json_path = "$.#{path.join(".")}"
+
+        extract = Arel::Nodes::NamedFunction.new(
+          "JSON_EXTRACT",
+          [arel_table[column], Arel::Nodes.build_quoted(json_path)]
+        )
+
+        Arel::Nodes::NamedFunction.new("JSON_UNQUOTE", [extract])
+      end
+    end
+  end
+end

data/lib/jsonq/adapters/postgresql_adapter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Jsonq
+  module Adapters
+    class PostgresqlAdapter < AbstractAdapter
+      def build_path_expression(arel_table, column, path)
+        node = arel_table[column]
+
+        path.each_with_index do |key, index|
+          operator = (index == path.length - 1) ? "->>" : "->"
+          node = Arel::Nodes::InfixOperation.new(operator, node, Arel::Nodes.build_quoted(key))
+        end
+
+        node
+      end
+    end
+  end
+end

data/lib/jsonq/adapters/sqlite_adapter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jsonq
+  module Adapters
+    class SqliteAdapter < AbstractAdapter
+      def build_path_expression(arel_table, column, path)
+        json_path = "$.#{path.join(".")}"
+
+        Arel::Nodes::InfixOperation.new(
+          "->>",
+          arel_table[column],
+          Arel::Nodes.build_quoted(json_path)
+        )
+      end
+    end
+  end
+end

data/lib/jsonq/adapters.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "adapters/abstract_adapter"
+require_relative "adapters/postgresql_adapter"
+require_relative "adapters/mysql_adapter"
+require_relative "adapters/sqlite_adapter"
+
+module Jsonq
+  module Adapters
+    def self.for_connection(connection)
+      case connection.adapter_name
+      when /postg/i
+        PostgresqlAdapter.new
+      when /mysql|trilogy/i
+        MysqlAdapter.new
+      when /sqlite/i
+        SqliteAdapter.new
+      else
+        raise Jsonq::UnsupportedAdapter,
+          "jsonq: unsupported database adapter '#{connection.adapter_name}'. " \
+          "Supported adapters: PostgreSQL, MySQL, SQLite."
+      end
+    end
+  end
+end

data/lib/jsonq/predicate_builder_extension.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Jsonq
+  module PredicateBuilderExtension
+    protected
+
+    def expand_from_hash(attributes, &block)
+      klass = begin
+        @table.send(:klass)
+      rescue
+        nil
+      end
+
+      return super unless klass&.respond_to?(:jsonq_registry) && klass.jsonq_registry.present?
+
+      registry = klass.jsonq_registry
+      jsonq_predicates = []
+      regular_attributes = {}
+
+      attributes.each do |key, value|
+        key_str = key.to_s
+
+        if registry.key?(key_str)
+          mapping = registry[key_str]
+          adapter = Jsonq::Adapters.for_connection(klass.connection)
+          arel_table = klass.arel_table
+          path_expr = adapter.build_path_expression(arel_table, mapping[:column], mapping[:path])
+
+          predicate = case value
+          when Array
+            # Wrap with AND IS NOT NULL so NOT(IN(...) AND IS NOT NULL)
+            # becomes NOT IN(...) OR IS NULL — includes missing keys
+            Arel::Nodes::Grouping.new(
+              path_expr.in(value.map(&:to_s)).and(path_expr.not_eq(nil))
+            )
+          when nil
+            path_expr.eq(nil)
+          else
+            # Wrap with AND IS NOT NULL so NOT(= val AND IS NOT NULL)
+            # becomes != val OR IS NULL — includes missing keys
+            Arel::Nodes::Grouping.new(
+              path_expr.eq(value.to_s).and(path_expr.not_eq(nil))
+            )
+          end
+
+          jsonq_predicates << predicate
+        else
+          regular_attributes[key] = value
+        end
+      end
+
+      result = regular_attributes.empty? ? [] : super(regular_attributes, &block)
+      result + jsonq_predicates
+    end
+  end
+end

data/lib/jsonq/queryable.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Jsonq
+  module Queryable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :jsonq_registry, instance_writer: false, default: {}
+
+      _jsonq_register_store_accessors
+    end
+
+    class_methods do
+      def store_accessor(store_attribute, *keys, prefix: nil, suffix: nil)
+        super
+        _jsonq_register_keys_for_store(store_attribute, keys) if respond_to?(:jsonq_registry)
+      end
+
+      def json_attribute(column, path, as: nil)
+        raise ArgumentError, "jsonq: `as:` option is required for json_attribute" if as.nil?
+
+        column = column.to_s
+        _jsonq_validate_json_column!(column)
+
+        path_parts = path.to_s.split(".")
+        alias_name = as.to_s
+
+        self.jsonq_registry = jsonq_registry.merge(
+          alias_name => {column: column, path: path_parts, source: :json_attribute}
+        )
+      end
+
+      private
+
+      def _jsonq_register_keys_for_store(store_attribute, keys)
+        store_column_str = store_attribute.to_s
+
+        begin
+          _jsonq_validate_json_column!(store_column_str)
+        rescue Jsonq::UnsupportedColumnType
+          raise
+        rescue
+          return
+        end
+
+        new_entries = {}
+        keys.each do |key|
+          key_str = key.to_s
+          next if columns_hash.key?(key_str)
+
+          new_entries[key_str] = {column: store_column_str, path: [key_str], source: :store_accessor}
+        end
+
+        self.jsonq_registry = jsonq_registry.merge(new_entries) if new_entries.any?
+      end
+
+      def _jsonq_register_store_accessors
+        return unless respond_to?(:stored_attributes) && stored_attributes.present?
+
+        stored_attributes.each do |store_column, keys|
+          _jsonq_register_keys_for_store(store_column, keys)
+        end
+      end
+
+      def _jsonq_validate_json_column!(column_name)
+        return unless connected? && table_exists?
+
+        col = columns_hash[column_name]
+        return if col.nil?
+
+        sql_type = col.sql_type.downcase
+        unless sql_type.include?("json")
+          raise Jsonq::UnsupportedColumnType,
+            "jsonq: column '#{column_name}' has type '#{col.sql_type}'. " \
+            "Only native JSON/JSONB columns are supported."
+        end
+      end
+    end
+  end
+
+  module QueryableDsl
+    def jsonq_queryable
+      include Jsonq::Queryable
+    end
+  end
+end

data/lib/jsonq/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Jsonq
+  class Railtie < ::Rails::Railtie
+    initializer "jsonq.active_record" do
+      ActiveSupport.on_load :active_record do
+        ActiveRecord::PredicateBuilder.prepend(Jsonq::PredicateBuilderExtension)
+        ActiveRecord::Base.extend(Jsonq::QueryableDsl)
+      end
+    end
+  end
+end

data/lib/jsonq/version.rb

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

data/lib/jsonq.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "jsonq/version"
+require_relative "jsonq/adapters"
+require_relative "jsonq/queryable"
+require_relative "jsonq/predicate_builder_extension"
+require_relative "jsonq/railtie" if defined?(Rails)
+
+module Jsonq
+  class Error < StandardError; end
+  class UnsupportedColumnType < Error; end
+  class UnsupportedAdapter < Error; end
+
+  def self.setup!
+    ActiveRecord::PredicateBuilder.prepend(Jsonq::PredicateBuilderExtension)
+    ActiveRecord::Base.extend(Jsonq::QueryableDsl)
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: jsonq
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Adrian Marin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Query JSON/JSONB columns using ActiveRecord's where syntax. Works with
+  store_accessor and supports PostgreSQL, MySQL, and SQLite.
+email: adrian@adrianthedev.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/jsonq.rb
+- lib/jsonq/adapters.rb
+- lib/jsonq/adapters/abstract_adapter.rb
+- lib/jsonq/adapters/mysql_adapter.rb
+- lib/jsonq/adapters/postgresql_adapter.rb
+- lib/jsonq/adapters/sqlite_adapter.rb
+- lib/jsonq/predicate_builder_extension.rb
+- lib/jsonq/queryable.rb
+- lib/jsonq/railtie.rb
+- lib/jsonq/version.rb
+homepage: https://github.com/avo-hq/jsonq
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/avo-hq/jsonq
+  source_code_uri: https://github.com/avo-hq/jsonq
+  bug_tracker_uri: https://github.com/avo-hq/jsonq/issues
+  changelog_uri: https://github.com/avo-hq/jsonq/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Friendly JSON column queries for ActiveRecord.
+test_files: []