active_fields 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd75dc9f715c95766a238fd268c8174c7920e2b64ddce086f4bd7eed9ea2c36a
-  data.tar.gz: 74ba8eaf11a578067d0c45730a59aa60dc23363b9e5ffcce5bfca7795ee12da3
+  metadata.gz: 1d32fccb9d7af7eab0db169ea67d7046e09d6f8eace84e0a2c49f32574377543
+  data.tar.gz: 0fa74f41f48702355d9fc73f64d49389433f03e94b62e5d3e2552fcff01ec7f3
 SHA512:
-  metadata.gz: 4cc1b2984a7912497bc1b26cec3fc793bb897cc813c76440b5a8513834acae27d5c4df5da9c5f87cf9b36ae79351cacb52ab60965195fa6b44ce6ec8fc4f3c4e
-  data.tar.gz: 2f03d79bb28e91af86a99d36ff60a992b14ecf9c13d6d8a13eb92490790c4cd71afb11465173ba8a2a756cc24c3cf50c488a13bc8fca90d619b1079ec88fe216
+  metadata.gz: 6e76f8e6e24e1b65a8d16480b06ce348c0d777dae4be55ec4fd908d82b17752d69866d9e73cee2847dafa1b04800977d34048eac8f0e7efc61644ddc2f30ae07
+  data.tar.gz: 673b3a37fcd8f2a1e0ee0d40bb3f80192d2a24933e097aae4d76d1a34d9fb04850a2b5504d2301b70cdbf2226a43bd96fd0bda0e58314aaf6ff3f54d2b7e0237

data/.rubocop.yml

@@ -1,17 +1,15 @@
-require:
-#  - rubocop-factory_bot
+plugins:
   - rubocop-performance
   - rubocop-rails
   - rubocop-rake
   - rubocop-rspec
-#  - rubocop-rspec_rails
 
 inherit_gem:
   rubocop-shopify: rubocop.yml
 
 AllCops:
   TargetRubyVersion: 3.3
-  TargetRailsVersion: 7.2
+  TargetRailsVersion: 8.0
   NewCops: enable
   Exclude:
     - "spec/dummy/db/schema.rb"
@@ -31,6 +29,9 @@ Style/WordArray:
 Style/MethodCallWithArgsParentheses:
   Enabled: false
 
+Style/SafeNavigationChainLength:
+  Enabled: false
+
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*"

data/CHANGELOG.md

@@ -1,4 +1,29 @@
 ## [Unreleased]
+- Drop support for _Rails_ < 7.1
+- Drop support for _Ruby_ < 3.1 (EOL)
+- Added search functionality
+- Added registry to store relationships between _Customizable_ types and _Active Field_ types
+- Added notes about the necessity of disabling reloading for custom model classes and custom _Active Field_ type models
+to prevent _STI_ (_Single Table Inheritance_) issues
+
+**Breaking changes**:
+- Maximum datetime precision reduced to 6 for all _Ruby_/_Rails_ versions.
+
+    While _Ruby_ allows up to 9 fractional seconds, most databases, including _PostgreSQL_, support only 6.
+    To ensure compatibility and prevent potential issues,
+    we are standardizing the precision to the minimum supported across our technology stack.
+
+- Maximum datetime precision constant relocated.
+
+    The maximum precision value has been moved
+    from `ActiveFields::Casters::DateTimeCaster::MAX_PRECISION` to `ActiveFields::MAX_DATETIME_PRECISION`.
+
+- Maximum decimal precision set to 16383 (2**14 - 1).
+
+    While _Ruby_'s `BigDecimal` class allows extremely high precision,
+    PostgreSQL supports a maximum of 16383 digits after the decimal point.
+    To ensure compatibility, we are capping the precision at this value.
+    The maximum precision value is now accessible via `ActiveFields::MAX_DECIMAL_PRECISION`.
 
 ## [1.1.0] - 2024-09-10
 - Added scaffold generator
@@ -16,11 +41,11 @@
 - Added datetime and datetime array field types
 - Added fields configuration DSL
 - Introduced new _Customizable_ setter for _Active Values_ (`active_fields_attributes=`) with a more convenient syntax
-    to replace the default setter (`active_values_attributes=`) from Rails nested attributes feature.
+    to replace the default setter (`active_values_attributes=`) from _Rails_ nested attributes feature
 
 ## [0.2.0] - 2024-06-13
 
-- Rewritten as a Rails plugin!
+- Rewritten as a _Rails_ plugin!
 - Custom field types support
 - Global configuration options for changing field and value classes
 - Per-model configuration option for enabling specific field types only

data/README.md

@@ -4,7 +4,7 @@
 [![Gem downloads count](https://img.shields.io/gem/dt/active_fields)](https://rubygems.org/gems/active_fields)
 [![Github Actions CI](https://github.com/lassoid/active_fields/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/lassoid/active_fields/actions/workflows/main.yml)
 
-**ActiveFields** is a Rails plugin that implements the Entity-Attribute-Value (EAV) pattern,
+**ActiveFields** is a _Rails_ plugin that implements the _Entity-Attribute-Value_ (_EAV_) pattern,
 enabling the addition of custom fields to any model at runtime without requiring changes to the database schema.
 
 ## Key Concepts
@@ -72,12 +72,10 @@ such as booleans, strings, numbers, arrays, etc.
     bin/rails generate active_fields:scaffold
     ```
 
-    This command generates a controller, routes and views for managing _Active Fields_,
-    along with form inputs for _Active Values_ and some useful helper methods.
+    This command generates a controller, routes, views for managing _Active Fields_,
+    along with form inputs for _Active Values_, search form and some useful helper methods that will be used in next steps.
 
-    **Note:** Don't forget to add available _Customizable_ types in generated _Active Fields_ forms.
-
-    **Note:** The array field helper uses _Stimulus_ for interactivity.
+    **Note:** The array field helper and search form use _Stimulus_ for interactivity.
     If your app doesn't already include _Stimulus_, you can [easily add it](https://github.com/hotwired/stimulus-rails).
     Alternatively, if you prefer not to use _Stimulus_, you should implement your own JavaScript code.
 
@@ -102,7 +100,7 @@ such as booleans, strings, numbers, arrays, etc.
     # ...
     ```
 
-    Finally, permit the _Active Fields_ attributes in your _Customizables_ controllers:
+    Permit the _Active Fields_ attributes in your _Customizables_ controllers:
 
     ```ruby
     # app/controllers/posts_controller.rb
@@ -119,34 +117,52 @@ such as booleans, strings, numbers, arrays, etc.
     
       permitted_params
     end
-
-    # Removes an empty string from the beginning of the array parameter
-    def compact_array_param(value)
-      if value.first == ""
-        value[1..-1]
-      else
-        value
-      end
-    end
     ```
 
     **Note:** Here we use the `active_fields_attributes=` method (as a permitted parameter),
-    that integrates well with Rails `fields_for` to generate appropriate form fields.
+    that integrates well with _Rails_ `fields_for` to generate appropriate form fields.
     Alternatively, the alias `active_fields=` can be used in contexts without `fields_for`, such as API controllers.
 
-    That's it!
-    You can now add _Active Fields_ to _Customizables_ at `http://localhost:3000/active_fields`
-    and fill in _Active Values_ within _Customizable_ forms.
+    **Note:** `compact_array_param` is a helper method, that was added by scaffold generator.
+    It removes an empty string from the beginning of the array parameter.
 
-    You can also explore the [Demo app](https://github.com/lassoid/active_fields/blob/main/spec/dummy)
-    where the plugin is fully integrated into a full-stack Rails application.
-    Feel free to explore the source code and run it locally:
+6. Use the `where_active_fields` query method to filter records and add a search form in _Customizables_ index actions.
 
-    ```shell
-    spec/dummy/bin/setup
-    bin/rails s
+    ```ruby
+    # app/controllers/posts_controller.rb
+    # ...
+    
+    def index
+      @posts = Post.where_active_fields(active_fields_finders_params)
+    end
     ```
 
+    **Note:** `active_fields_finders_params` is a helper method, that was added by scaffold generator. 
+    It permits params from search form.
+
+    ```erb
+    # app/views/posts/index.html.erb
+    # ...
+
+    <%= render_active_fields_finders_form(active_fields: Post.active_fields, url: posts_path) %>
+
+    # ...
+    ```
+
+That's it!
+You can now add _Active Fields_ to _Customizables_ at `http://localhost:3000/active_fields`, 
+fill in _Active Values_ within _Customizable_ forms
+and search _Customizables_ using their index actions.
+
+You can also explore the [Demo app](https://github.com/lassoid/active_fields/blob/main/spec/dummy)
+where the plugin is fully integrated into a full-stack _Rails_ application.
+Feel free to explore the source code and run it locally:
+
+```shell
+spec/dummy/bin/setup
+bin/rails s
+```
+
 ## Field Types
 
 The plugin comes with a structured set of _Active Fields_ types:
@@ -289,6 +305,238 @@ We replace it with `**` for conciseness.
 
 **Note:** Options marked with **\*** are mandatory.
 
+### Search Functionality
+
+**Note:** This feature is compatible with _PostgreSQL_ 17 and above.
+
+The gem provides a built-in search capability. Like _Rails_ nested attributes functionality, it accepts the following argument types:
+
+- An array of hashes.
+
+    ```ruby
+    Post.where_active_fields(
+      [
+        { name: "integer_array", operator: "any_gteq", value: 5 }, # symbol keys
+        { "name" => "text", operator: "=", "value" => "Lasso" }, # string keys
+        { n: "boolean", op: "!=", v: false }, # compact form (string or symbol keys)
+      ],
+    )
+    ```
+
+- A hash of hashes (typically generated by _Rails_ `fields_for` form helper).
+
+    ```ruby
+    Post.where_active_fields(
+      {
+        "0" => { name: "integer_array", operator: "any_gteq", value: 5 },
+        "1" => { "name" => "text", operator: "=", "value" => "Lasso" },
+        "2" => { n: "boolean", op: "!=", v: false },
+      },
+    )
+    ```
+
+- Permitted parameters (can contain either an array of hashes or a hash of hashes).
+
+    ```ruby
+    Post.where_active_fields(permitted_params)
+    ```
+
+Key details:
+- `n`/`name` argument must specify the name of an _Active Field_.
+- `v`/`value` argument will be automatically cast to the appropriate type.
+- `op`/`operator` argument can contain either _operation_ or _operator_.
+
+Supported _operations_ and _operators_ for each _Active Field_ type are listed below.
+
+#### Boolean
+
+| Operation  | Operator | Description                 |
+|------------|----------|-----------------------------|
+| `eq`       | `=`      | Value is equal to given     |
+| `not_eq`   | `!=`     | Value is not equal to given |
+
+#### Date
+
+| Operation  | Operator | Description                             |
+|------------|----------|-----------------------------------------|
+| `eq`       | `=`      | Value is equal to given                 |
+| `not_eq`   | `!=`     | Value is not equal to given             |
+| `gt`       | `>`      | Value is greater than given             |
+| `gteq`     | `>=`     | Value is greater than or equal to given |
+| `lt`       | `<`      | Value is less than given                |
+| `lteq`     | `<=`     | Value is less than or equal to given    |
+
+#### DateArray
+
+| Operation     | Operator | Description                                                    |
+|---------------|----------|----------------------------------------------------------------|
+| `include`     | `\|=`    | Array value includes given element                             |
+| `not_include` | `!\|=`   | Array value doesn't include given element                      |
+| `any_gt`      | `\|>`    | Array value contains an element greater than given             |
+| `any_gteq`    | `\|>=`   | Array value contains an element greater than or equal to given |
+| `any_lt`      | `\|<`    | Array value contains an element less than given                |
+| `any_lteq`    | `\|<=`   | Array value contains an element less than or equal to given    |
+| `all_gt`      | `&>`     | All elements of array value are greater than given             |
+| `all_gteq`    | `&>=`    | All elements of array value are greater than or equal to given |
+| `all_lt`      | `&<`     | All elements of array value are less than given                |
+| `all_lteq`    | `&<=`    | All elements of array value are less than or equal to given    |
+| `size_eq`     | `#=`     | Array value size is equal to given                             |
+| `size_not_eq` | `#!=`    | Array value size is not equal to given                         |
+| `size_gt`     | `#>`     | Array value size is greater than given                         |
+| `size_gteq`   | `#>=`    | Array value size is greater than or equal to given             |
+| `size_lt`     | `#<`     | Array value size is less than given                            |
+| `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
+
+#### DateTime
+
+| Operation  | Operator | Description                             |
+|------------|----------|-----------------------------------------|
+| `eq`       | `=`      | Value is equal to given                 |
+| `not_eq`   | `!=`     | Value is not equal to given             |
+| `gt`       | `>`      | Value is greater than given             |
+| `gteq`     | `>=`     | Value is greater than or equal to given |
+| `lt`       | `<`      | Value is less than given                |
+| `lteq`     | `<=`     | Value is greater than or equal to given |
+
+#### DateTimeArray
+
+| Operation     | Operator | Description                                                    |
+|---------------|----------|----------------------------------------------------------------|
+| `include`     | `\|=`    | Array value includes given element                             |
+| `not_include` | `!\|=`   | Array value doesn't include given element                      |
+| `any_gt`      | `\|>`    | Array value contains an element greater than given             |
+| `any_gteq`    | `\|>=`   | Array value contains an element greater than or equal to given |
+| `any_lt`      | `\|<`    | Array value contains an element less than given                |
+| `any_lteq`    | `\|<=`   | Array value contains an element less than or equal to given    |
+| `all_gt`      | `&>`     | All elements of array value are greater than given             |
+| `all_gteq`    | `&>=`    | All elements of array value are greater than or equal to given |
+| `all_lt`      | `&<`     | All elements of array value are less than given                |
+| `all_lteq`    | `&<=`    | All elements of array value are less than or equal to given    |
+| `size_eq`     | `#=`     | Array value size is equal to given                             |
+| `size_not_eq` | `#!=`    | Array value size is not equal to given                         |
+| `size_gt`     | `#>`     | Array value size is greater than given                         |
+| `size_gteq`   | `#>=`    | Array value size is greater than or equal to given             |
+| `size_lt`     | `#<`     | Array value size is less than given                            |
+| `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
+
+#### Decimal
+
+| Operation  | Operator | Description                             |
+|------------|----------|-----------------------------------------|
+| `eq`       | `=`      | Value is equal to given                 |
+| `not_eq`   | `!=`     | Value is not equal to given             |
+| `gt`       | `>`      | Value is greater than given             |
+| `gteq`     | `>=`     | Value is greater than or equal to given |
+| `lt`       | `<`      | Value is less than given                |
+| `lteq`     | `<=`     | Value is greater than or equal to given |
+
+#### DecimalArray
+
+| Operation     | Operator | Description                                                    |
+|---------------|----------|----------------------------------------------------------------|
+| `include`     | `\|=`    | Array value includes given element                             |
+| `not_include` | `!\|=`   | Array value doesn't include given element                      |
+| `any_gt`      | `\|>`    | Array value contains an element greater than given             |
+| `any_gteq`    | `\|>=`   | Array value contains an element greater than or equal to given |
+| `any_lt`      | `\|<`    | Array value contains an element less than given                |
+| `any_lteq`    | `\|<=`   | Array value contains an element less than or equal to given    |
+| `all_gt`      | `&>`     | All elements of array value are greater than given             |
+| `all_gteq`    | `&>=`    | All elements of array value are greater than or equal to given |
+| `all_lt`      | `&<`     | All elements of array value are less than given                |
+| `all_lteq`    | `&<=`    | All elements of array value are less than or equal to given    |
+| `size_eq`     | `#=`     | Array value size is equal to given                             |
+| `size_not_eq` | `#!=`    | Array value size is not equal to given                         |
+| `size_gt`     | `#>`     | Array value size is greater than given                         |
+| `size_gteq`   | `#>=`    | Array value size is greater than or equal to given             |
+| `size_lt`     | `#<`     | Array value size is less than given                            |
+| `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
+
+#### Enum
+
+| Operation  | Operator | Description                 |
+|------------|----------|-----------------------------|
+| `eq`       | `=`      | Value is equal to given     |
+| `not_eq`   | `!=`     | Value is not equal to given |
+
+#### EnumArray
+
+| Operation     | Operator | Description                                        |
+|---------------|----------|----------------------------------------------------|
+| `include`     | `\|=`    | Array value includes given element                 |
+| `not_include` | `!\|=`   | Array value doesn't include given element          |
+| `size_eq`     | `#=`     | Array value size is equal to given                 |
+| `size_not_eq` | `#!=`    | Array value size is not equal to given             |
+| `size_gt`     | `#>`     | Array value size is greater than given             |
+| `size_gteq`   | `#>=`    | Array value size is greater than or equal to given |
+| `size_lt`     | `#<`     | Array value size is less than given                |
+| `size_lteq`   | `#<=`    | Array value size is less than or equal to given    |
+
+#### Integer
+
+| Operation  | Operator | Description                             |
+|------------|----------|-----------------------------------------|
+| `eq`       | `=`      | Value is equal to given                 |
+| `not_eq`   | `!=`     | Value is not equal to given             |
+| `gt`       | `>`      | Value is greater than given             |
+| `gteq`     | `>=`     | Value is greater than or equal to given |
+| `lt`       | `<`      | Value is less than given                |
+| `lteq`     | `<=`     | Value is greater than or equal to given |
+
+#### IntegerArray
+
+| Operation     | Operator | Description                                                    |
+|---------------|----------|----------------------------------------------------------------|
+| `include`     | `\|=`    | Array value includes given element                             |
+| `not_include` | `!\|=`   | Array value doesn't include given element                      |
+| `any_gt`      | `\|>`    | Array value contains an element greater than given             |
+| `any_gteq`    | `\|>=`   | Array value contains an element greater than or equal to given |
+| `any_lt`      | `\|<`    | Array value contains an element less than given                |
+| `any_lteq`    | `\|<=`   | Array value contains an element less than or equal to given    |
+| `all_gt`      | `&>`     | All elements of array value are greater than given             |
+| `all_gteq`    | `&>=`    | All elements of array value are greater than or equal to given |
+| `all_lt`      | `&<`     | All elements of array value are less than given                |
+| `all_lteq`    | `&<=`    | All elements of array value are less than or equal to given    |
+| `size_eq`     | `#=`     | Array value size is equal to given                             |
+| `size_not_eq` | `#!=`    | Array value size is not equal to given                         |
+| `size_gt`     | `#>`     | Array value size is greater than given                         |
+| `size_gteq`   | `#>=`    | Array value size is greater than or equal to given             |
+| `size_lt`     | `#<`     | Array value size is less than given                            |
+| `size_lteq`   | `#<=`    | Array value size is less than or equal to given                |
+
+#### Text
+
+| Operation         | Operator | Description                                                 |
+|-------------------|----------|-------------------------------------------------------------|
+| `eq`              | `=`      | Value is equal to given                                     |
+| `not_eq`          | `!=`     | Value is not equal to given                                 |
+| `start_with`      | `^`      | Value starts with given substring                           |
+| `end_with`        | `$`      | Value ends with given substring                             |
+| `contain`         | `~`      | Value contains given substring                              |
+| `not_start_with`  | `!^`     | Value doesn't start with given substring                    |
+| `not_end_with`    | `!$`     | Value doesn't end with given substring                      |
+| `not_contain`     | `!~`     | Value doesn't contain given substring                       |
+| `istart_with`     | `^*`     | Value starts with given substring (case-insensitive)        |
+| `iend_with`       | `$*`     | Value ends with given substring (case-insensitive)          |
+| `icontain`        | `~*`     | Value contains given substring (case-insensitive)           |
+| `not_istart_with` | `!^*`    | Value doesn't start with given substring (case-insensitive) |
+| `not_iend_with`   | `!$*`    | Value doesn't end with given substring (case-insensitive)   |
+| `not_icontain`    | `!~*`    | Value doesn't contain given substring (case-insensitive)    |
+
+#### TextArray
+
+| Operation        | Operator | Description                                                 |
+|------------------|----------|-------------------------------------------------------------|
+| `include`        | `\|=`    | Array value includes given element                          |
+| `not_include`    | `!\|=`   | Array value doesn't include given element                   |
+| `any_start_with` | `\|^`    | Array value contains an element starts with given substring |
+| `all_start_with` | `&^`     | All elements of array value starts with given substring     |
+| `size_eq`        | `#=`     | Array value size is equal to given                          |
+| `size_not_eq`    | `#!=`    | Array value size is not equal to given                      |
+| `size_gt`        | `#>`     | Array value size is greater than given                      |
+| `size_gteq`      | `#>=`    | Array value size is greater than or equal to given          |
+| `size_lt`        | `#<`     | Array value size is less than given                         |
+| `size_lteq`      | `#<=`    | Array value size is less than or equal to given             |
+
 ## Configuration
 
 ### Limiting Field Types for a Customizable
@@ -348,6 +596,25 @@ class CustomValue < ApplicationRecord
 end
 ```
 
+**Note:** To avoid _STI_ (_Single Table Inheritance_) issues in environments with code reloading (`config.enable_reloading = true`),
+you should ensure that your custom model classes, along with all their superclasses and mix-ins, are non-reloadable.
+Follow these steps:
+- Move your custom model classes to a separate folder, such as `app/models/active_fields`.
+- If your custom model classes subclass `ApplicationRecord` (or other reloadable class) or mix-in reloadable modules,
+move those superclasses and modules to another folder, such as `app/models/core`.
+- After organizing your files, add the following code to your `config/application.rb`:
+    ```ruby
+    # Disable custom models reloading to avoid STI issues.
+    custom_models_dir = "#{root}/app/models/active_fields"
+    models_core_dir = "#{root}/app/models/core"
+    Rails.autoloaders.main.ignore(custom_models_dir, models_core_dir)
+    Rails.autoloaders.once.collapse(custom_models_dir, models_core_dir)
+    config.autoload_once_paths += [custom_models_dir, models_core_dir]
+    config.eager_load_paths += [custom_models_dir, models_core_dir]
+    ```
+    This configuration disables namespaces for these folders
+    and adds them to `autoload_once_paths`, ensuring they are not reloaded.
+
 ### Adding Custom Field Types
 
 To add a custom _Active Field_ type, create a subclass of the `ActiveFields.config.field_base_class`,
@@ -372,6 +639,9 @@ class IpField < ActiveFields.config.field_base_class
       class_name: "IpCaster",
       options: -> { { strip: strip? } }, # options that will be passed to the caster
     },
+    finder: { # Optional
+      class_name: "IpFinder",
+    },
   )
 
   # Store specific attributes in `options`
@@ -423,12 +693,18 @@ class IpArrayField < ActiveFields.config.field_base_class
     caster: {
       class_name: "IpArrayCaster",
     },
+    finder: { # Optional
+      class_name: "IpArrayFinder",
+    },
   )
   # ...
 end
 ```
 
-For each custom _Active Field_ type, you must define a **validator** and a **caster**:
+**Note:** Similar to custom model classes, you should disable code reloading for custom _Active Field_ type models.
+Place them in the `app/models/active_fields` folder too.
+
+For each custom _Active Field_ type, you must define a **validator**, a **caster** and optionally a **finder**:
 
 #### Validator
 
@@ -483,6 +759,96 @@ class IpCaster < ActiveFields::Casters::BaseCaster
 end
 ```
 
+#### Finder
+
+To create your custom finder, you should define a class that inherits from one of the following base classes:
+- `ActiveFields::Finders::SingularFinder` - for singular values,
+- `ActiveFields::Finders::ArrayFinder` - for array values,
+- `ActiveFields::Finders::BaseCaster` - if you don’t need built-in helper methods.
+
+Finder classes include a DSL for defining search operations and provide helper methods to simplify query building.
+Explore the source code to discover all these methods.
+
+```ruby
+# lib/ip_finder.rb (or anywhere you want)
+class IpFinder < ActiveFields::Finders::SingularFinder
+  operation :eq, operator: "=" do |value|
+    scope.where(eq(casted_value_field("text"), cast(value)))
+    # Equivalent to:
+    # if value.is_a?(TrueClass) || value.is_a?(FalseClass) || value.is_a?(NilClass)
+    #   scope.where("CAST(active_fields_values.value_meta ->> 'const' AS text) IS ?)", cast(value))
+    # else
+    #   scope.where("CAST(active_fields_values.value_meta ->> 'const' AS text) = ?)", cast(value))
+    # end
+  end
+  operation :not_eq, operator: "!=" do |value|
+    scope.where(not_eq(casted_value_field("text"), cast(value)))
+  end
+
+  def cast(value)
+    IpCaster.new.deserialize(value)
+  end
+end
+
+# lib/ip_array_finder.rb (or anywhere you want)
+class IpArrayFinder < ActiveFields::Finders::ArrayFinder
+  operation :include, operator: "|=" do |value|
+    scope.where(value_match_any("==", cast(value)))
+    # Equivalent to:
+    # scope.where("jsonb_path_exists(active_fields_values.value_meta -> 'const', ?, ?)", "$[*] ? (@ == $value)", { value: cast(value) }.to_json)
+  end
+  operation :not_include, operator: "!|=" do |value|
+    scope.where.not(value_match_any("==", cast(value)))
+  end
+  operation :size_eq, operator: "#=" do |value|
+    scope.where(value_size_eq(value))
+    # Equivalent to:
+    # scope.where("jsonb_array_length(active_fields_values.value_meta -> 'const') = ?", value&.to_i)
+  end
+  operation :size_not_eq, operator: "#!=" do |value|
+    scope.where(value_size_not_eq(value))
+  end
+  operation :size_gt, operator: "#>" do |value|
+    scope.where(value_size_gt(value))
+  end
+  operation :size_gteq, operator: "#>=" do |value|
+    scope.where(value_size_gteq(value))
+  end
+  operation :size_lt, operator: "#<" do |value|
+    scope.where(value_size_lt(value))
+  end
+  operation :size_lteq, operator: "#<=" do |value|
+    scope.where(value_size_lteq(value))
+  end
+
+  private
+
+  def cast(value)
+    caster = IpCaster.new
+    caster.serialize(caster.deserialize(value))
+  end
+
+  # This method must be defined to utilize the `value_match_any` and `value_match_all` helper methods in your class.
+  # It should return a valid JSONPath expression for use in PostgreSQL jsonb query functions.
+  def jsonpath(operator) = "$[*] ? (@ #{operator} $value)"
+end
+```
+
+Once defined, every _Active Value_ of this type will support the specified search operations!
+
+```ruby
+# Find customizables
+Author.where_active_fields([
+  { name: "main_ip", operator: "eq", value: "127.0.0.1" },
+  { n: "all_ips", op: "#>=", v: 5 },
+  { name: "all_ips", operator: "|=", value: "0.0.0.0" },
+])
+
+# Find Active Values
+IpFinder.new(active_field: ip_active_field).search(op: "eq", value: "127.0.0.1")
+IpArrayFinder.new(active_field: ip_array_active_field).search(op: "#>=", value: 5)
+```
+
 ### Localization (I18n)
 
 The built-in _validators_ primarily use _Rails_ default error types.
@@ -495,20 +861,16 @@ For an example, refer to the [locale file](https://github.com/lassoid/active_fie
 
 ## Current Restrictions
 
-1. Only _PostgreSQL_ is fully supported.
+1. Only _PostgreSQL_ 17+ is fully supported.
 
     The gem is tested exclusively with _PostgreSQL_. Support for other databases is not guaranteed.
 
-    However, you can give it a try! :)
-
 2. Updating some _Active Fields_ options may be unsafe.
 
     This could cause existing _Active Values_ to become invalid,
     leading to the associated _Customizables_ also becoming invalid,
     which could potentially result in update failures.
 
-3. Only _Zeitwerk_ autoloading mode is supported.
-
 ## API Overview
 
 ### Fields API
@@ -535,6 +897,7 @@ active_field.value_caster_class # Class used for values casting
 active_field.value_caster # Caster object that performs values casting
 active_field.customizable_model # Customizable model class
 active_field.type_name # Identifier of the type of this Active Field (instead of class name)
+active_field.available_customizable_types # Available Customizable types for this Active Field
 
 # Scopes:
 ActiveFields::Field::Boolean.for("Post") # Collection of Active Fields registered for the specified Customizable type
@@ -567,6 +930,9 @@ customizable.active_values # `has_many` association with Active Values linked to
 
 # Methods:
 customizable.active_fields # Collection of Active Fields registered for this record
+Post.active_fields # Collection of Active Fields registered for this model
+Post.allowed_active_fields_type_names # Active Fields type names allowed for this Customizable model
+Post.allowed_active_fields_class_names # Active Fields class names allowed for this Customizable model
 
 # Create, update or destroy Active Values.
 customizable.active_fields_attributes = [
@@ -596,6 +962,15 @@ customizable.active_values_attributes = attributes
 # This method is useful with `fields_for`, allowing you to pass the collection as an argument to render new Active Values:
 # `form.fields_for :active_fields, customizable.initialize_active_values`.
 customizable.initialize_active_values
+
+# Query Customizables by Active Values.
+Post.where_active_fields(
+  [
+    { name: "integer_array", operator: "any_gteq", value: 5 }, # symbol keys
+    { "name" => "text", operator: "=", "value" => "Lasso" }, # string keys
+    { n: "boolean", op: "!=", v: false }, # compact form (string or symbol keys)
+  ],
+)
 ```
 
 ### Global Config
@@ -614,14 +989,12 @@ ActiveFields.config.type_class_names # Registered Active Fields class names
 ActiveFields.config.register_field(:ip, "IpField") # Register a custom Active Field type
 ```
 
-### Customizable Config
+### Registry
 
 ```ruby
-customizable_model = Post
-customizable_model.active_fields_config # Access the Customizable's configuration
-customizable_model.active_fields_config.customizable_model # The Customizable model itself
-customizable_model.active_fields_config.types # Allowed Active Field types (e.g., `[:boolean]`)
-customizable_model.active_fields_config.types_class_names # Allowed Active Field class names (e.g., `[ActiveFields::Field::Boolean]`)
+ActiveFields.registry.add(:boolean, "Post") # Stores relation between Active Field type and customizable type. Please do not use directly.
+ActiveFields.registry.customizable_types_for(:boolean) # Returns Customizable types that allow provided Active Field type name
+ActiveFields.registry.field_type_names_for("Post") # Returns Active Field type names, allowed for given Customizable type
 ```
 
 ## Development

data/app/models/active_fields/field/boolean.rb

@@ -11,6 +11,9 @@ module ActiveFields
         caster: {
           class_name: "ActiveFields::Casters::BooleanCaster",
         },
+        finder: {
+          class_name: "ActiveFields::Finders::BooleanFinder",
+        },
       )
 
       store_accessor :options, :required, :nullable