awesome_jsonb_translate 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39b49ed73ec225353feccc26d5e50c09fe720e9aff66c9383b5a33556b1a5feb
-  data.tar.gz: c9cc4f921001e6061dead270ed74101d730c2af0fce84179c5b9010d637b46e9
+  metadata.gz: d81ced6cfae9bbcf7aaf22dd231827333f59947fbe614312940b1a58ed5ddbd9
+  data.tar.gz: e6ad24b4afff672e784204523050684eaabb8424d95f4cb7286e57bfd1483704
 SHA512:
-  metadata.gz: 191e83f00570548e09bfdc8b3e32f9907ad203abd55c0bb5bc1d534fdd5784e6e557eb87bf84bf784419a5ab180a62d7b7217c64d47a3b1edfe5d8e11ce8f28e
-  data.tar.gz: bbc7445c9877381c5fe04a3b02d67e4473cf8b942421c860d6dcf48c7769d37fa69e9f4b4651f9b4a74867ab3e4d3a30f95f6f6d4ece7c8cef1482baf92e4801
+  metadata.gz: e1f1c95edd20c951ef43d669e4ba8f09b439ece16fab7f9c6d3f7626bf378ada3066690fa0084d5293a4029ffd876137644f014d012b723e1b6aea557a97344b
+  data.tar.gz: 11e2c1c76892384196f9aad8ad0fec6e8f53cfe3d340a29fd87fe822cd9b660a66a801f13455822e23ee1d3d964d08dece2d8b3390c3ffb43e48757f95e3a3d9

data/README.md

@@ -10,6 +10,7 @@ This gem uses PostgreSQL's JSONB datatype and ActiveRecord models to translate m
 
 ## Features
 
+- [x] `v0.2.0` Support for raw JSONB syntax in find_by queries
 - [x] `v0.1.3` Fix redundant fallbacks when translation is nil
 
 ## Requirements
@@ -95,6 +96,8 @@ p.title_de = 'Aktualisierter Deutscher Titel'
 
 ### Querying by Translated Value (JSONB-aware)
 
+**Hash-based queries (recommended for most use cases):**
+
 ```ruby
 # Find records by current locale value
 Page.find_by(title_en: 'English title')
@@ -109,6 +112,35 @@ Page.find_by(title_en: 'English title', author: 'John')
 Page.where("title->>'en' = ?", 'English title').where(author: 'John')
 ```
 
+**Raw JSONB syntax queries (for advanced use cases):**
+
+You can also use raw PostgreSQL JSONB syntax directly with `find_by`:
+
+```ruby
+# Direct JSONB query syntax
+Page.find_by("title->>'en' = ?", 'English title')
+
+# Complex JSONB queries with operators
+Page.find_by("title->>'en' ILIKE ?", '%title%')
+
+# Case-insensitive search
+Page.find_by("LOWER(title->>'en') = ?", 'english title')
+```
+
+**Important:** Raw SQL string syntax is only supported with `find_by`. The methods `find_or_initialize_by` and `find_or_create_by` require hash-based syntax because they need to know which attributes to set when creating/initializing new records.
+
+For these methods, use hash syntax with translated accessors:
+```ruby
+# Correct - uses hash syntax
+Page.find_or_initialize_by(title_en: 'English title')
+Page.find_or_create_by(title_de: 'Deutscher Titel')
+
+# Incorrect - string syntax not supported
+# Page.find_or_create_by("title->>'en' = ?", 'English title')  # Will not work
+```
+
+When using raw JSONB syntax with `find_by`, the gem delegates to ActiveRecord's native query methods, giving you full access to PostgreSQL's JSONB operators and functions.
+
 ### Finding or Initializing Records
 
 ```ruby

data/lib/awesome_jsonb_translate/active_record.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module AwesomeJsonbTranslate
+  # Extends ActiveRecord models with translation capabilities using PostgreSQL JSONB columns
   module ActiveRecord
     def translates(*attrs)
       include InstanceMethods
@@ -63,6 +64,7 @@ module AwesomeJsonbTranslate
       end
     end
 
+    # Provides instance methods for reading and writing translations
     module InstanceMethods
       def translated?(attr_name, locale = I18n.locale)
         value = read_translation_without_fallback(attr_name, locale)
@@ -110,9 +112,12 @@ module AwesomeJsonbTranslate
       end
     end
 
+    # Overrides ActiveRecord finder methods to support querying by translated attributes
     module FindByMethods
       # Override find_by to handle translated attributes
-      def find_by(attributes)
+      def find_by(attributes, *args)
+        return super unless attributes.is_a?(Hash)
+
         # Check if any of the keys represent translated attributes
         has_translated_attrs = attributes.keys.any? do |key|
           translated_accessors.include?(key.to_sym)
@@ -154,7 +159,9 @@ module AwesomeJsonbTranslate
       end
 
       # Override find_or_initialize_by to handle translated attributes
-      def find_or_initialize_by(attributes)
+      def find_or_initialize_by(attributes, &block)
+        return super unless attributes.is_a?(Hash)
+
         result = find_by(attributes)
         return result if result
 
@@ -165,7 +172,9 @@ module AwesomeJsonbTranslate
       end
 
       # Override find_or_create_by to handle translated attributes
-      def find_or_create_by(attributes)
+      def find_or_create_by(attributes, &block)
+        return super unless attributes.is_a?(Hash)
+
         result = find_by(attributes)
         return result if result
 

data/lib/awesome_jsonb_translate/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AwesomeJsonbTranslate
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'
 end

data/lib/awesome_jsonb_translate.rb

@@ -4,6 +4,6 @@ require 'active_record'
 require 'awesome_jsonb_translate/version'
 require 'awesome_jsonb_translate/active_record'
 
+# Provides PostgreSQL JSONB-based translation functionality for ActiveRecord models
 module AwesomeJsonbTranslate
-  # Just serve as a namespace
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: awesome_jsonb_translate
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Nick Ostrovsky
 bindir: bin
 cert_chain: []
-date: 2025-04-29 00:00:00.000000000 Z
+date: 2025-11-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -37,48 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: pg
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: This gem uses PostgreSQL's JSONB datatype to store and retrieve translations
   for ActiveRecord models without extra columns or tables
 email:
@@ -108,7 +66,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="