active_fields 1.0.0 → 2.0.0

data/README.md

@@ -4,14 +4,14 @@
 [![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
 
-- **Active Field**: A record with the definition of a custom field.
-- **Active Value**: A record that stores the value of an _Active Field_ for a specific _Customizable_.
-- **Customizable**: A record that has custom fields.
+- **Customizable**: A record that has custom fields (_Entity_).
+- **Active Field**: A record with the definition of a custom field (_Attribute_).
+- **Active Value**: A record that stores the value of an _Active Field_ for a specific _Customizable_ (_Value_).
 
 ## Models Structure
 
@@ -24,11 +24,11 @@ classDiagram
         + string name
         + string type
         + string customizable_type
-        + json default_value
+        + json default_value_meta
         + json options
     }
     class ActiveValue {
-        + json value
+        + json value_meta
     }
     class Customizable {
         // This is your model
@@ -56,85 +56,113 @@ such as booleans, strings, numbers, arrays, etc.
 3. Add the `has_active_fields` method to any models where you want to enable custom fields:
 
     ```ruby
-    class Author < ApplicationRecord
+    class Post < ApplicationRecord
       has_active_fields
     end
     ```
 
-4. Implement the necessary code to work with _Active Fields_.
+4. Run scaffold generator.
 
-    This plugin provides a convenient API and helpers, allowing you to write code that meets your specific needs
+    This plugin provides a convenient API, allowing you to write code that meets your specific needs
     without being forced to use predefined implementations that is hard to extend.
 
-    Generally, you should:
-     - Implement a controller and UI for managing _Active Fields_.
-     - Add inputs for _Active Values_ in _Customizable_ forms and permit their params in the controller.
-
-     To set _Active Values_ for your _Customizable_, use the `active_fields_attributes=` method,
-     that integrates with Rails `fields_for` to generate appropriate form fields.
-     Alternatively, the alias `active_fields=` can be used in contexts without `fields_for`, such as APIs.
-
-     To prepare a collection of _Active Values_ for use with the `fields_for` builder,
-     call the `initialize_active_values` method.
-
-     **Note:** By default, Rails form fields insert an empty string into array (multiple) parameters.
-     You’ll need to handle the removal of these empty strings.
-
-     ```ruby
-     # app/controllers/posts_controller.rb
-     # ...
-
-     def new
-       @post = Post.new
-       @post.initialize_active_values
-     end
-
-     def edit
-       @post.initialize_active_values
-     end
-
-     def post_params
-       permitted_params = params.require(:post).permit(
-         # ...
-         active_fields_attributes: [:name, :value, :_destroy, value: []],
-       )
-       permitted_params[:active_fields_attributes]&.each do |_index, value_attrs|
-         value_attrs[:value] = compact_array_param(value_attrs[:value]) if value_attrs[:value].is_a?(Array)
-       end
-
-       permitted_params
-     end
-
-     def compact_array_param(value)
-       if value.first == ""
-         value[1..-1]
-       else
-         value
-       end
-     end
-     ```
-
-     ```erb
-     # app/views/posts/_form.html.erb
-     # ...
-
-     <%= form.fields_for :active_fields, post.active_values.sort_by(&:active_field_id), include_id: false do |active_fields_form| %>
-       <%= active_fields_form.hidden_field :name %>
-       # Render appropriate Active Value input and (optionally) destroy flag here
-     <% end %>
-
-     # ...
-     ```
-
-    You can find a detailed [example](https://github.com/lassoid/active_fields/blob/main/spec/dummy) 
-    of how to implement this in a full-stack Rails application.
-    Feel free to explore the source code and run it locally:
+    However, for a quick start, you can generate a scaffold by running the following command:
 
     ```shell
-    spec/dummy/bin/setup
-    bin/rails s
+    bin/rails generate active_fields:scaffold
     ```
 
+    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:** 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.
+
+5. Add _Active Fields_ inputs in _Customizables_ forms and permit their params in controllers.
+
+    There are two methods available on _Customizable_ models for retrieving _Active Values_:
+    - `active_values` returns collection of only existing _Active Values_.
+    - `initialize_active_values` builds any missing _Active Values_ and returns the full collection.
+
+    Choose the method that suits your requirements.
+    In most cases, however, `initialize_active_values` is the more suitable option.
+
+    ```erb
+    # app/views/posts/_form.html.erb
+    # ...
+
+    <%= form.fields_for :active_fields, post.initialize_active_values.sort_by(&:active_field_id), include_id: false do |active_fields_form| %>
+      <%= active_fields_form.hidden_field :name %>
+      <%= render_active_value_input(form: active_fields_form, active_value: active_fields_form.object) %>
+    <% end %>
+
+    # ...
+    ```
+
+    Permit the _Active Fields_ attributes in your _Customizables_ controllers:
+
+    ```ruby
+    # app/controllers/posts_controller.rb
+    # ...
+
+    def post_params
+      permitted_params = params.require(:post).permit(
+        # ...
+        active_fields_attributes: [:name, :value, :_destroy, value: []],
+      )
+      permitted_params[:active_fields_attributes]&.each do |_index, value_attrs|
+        value_attrs[:value] = compact_array_param(value_attrs[:value]) if value_attrs[:value].is_a?(Array)
+      end
+    
+      permitted_params
+    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.
+    Alternatively, the alias `active_fields=` can be used in contexts without `fields_for`, such as API controllers.
+
+    **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.
+
+6. Use the `where_active_fields` query method to filter records and add a search form in _Customizables_ index actions.
+
+    ```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:
@@ -251,7 +279,7 @@ classDiagram
 - `name`(`string`)
 - `type`(`string`)
 - `customizable_type`(`string`)
-- `default_value` (`json`)
+- `default_value_meta` (`json`)
 
 ### Field Types Summary
 
@@ -277,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
@@ -336,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`,
@@ -360,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`
@@ -411,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
 
@@ -471,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.
@@ -483,12 +861,10 @@ 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,
@@ -510,7 +886,7 @@ active_field.type # Class name of this Active Field (utilizing STI)
 active_field.customizable_type # Name of the Customizable model this Active Field is registered to
 active_field.name # Identifier of this Active Field, it should be unique in scope of customizable_type
 active_field.default_value_meta # JSON column declaring the default value. Consider using `default_value` instead
-active_field.options # A hash (json) containing type-specific attributes for this Active Field
+active_field.options # JSON column containing type-specific attributes for this Active Field
 
 # Methods:
 active_field.default_value # Default value for all Active Values associated with this Active Field
@@ -521,9 +897,10 @@ 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("Author") # Collection of Active Fields registered for the specified Customizable type
+ActiveFields::Field::Boolean.for("Post") # Collection of Active Fields registered for the specified Customizable type
 ```
 
 ### Values API
@@ -546,13 +923,16 @@ active_value.name # Name of the associated Active Field
 ### Customizable API
 
 ```ruby
-customizable = Author.take
+customizable = Post.take
 
 # Associations:
 customizable.active_values # `has_many` association with Active Values linked to this Customizable
 
 # 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 = [
@@ -577,10 +957,20 @@ customizable.active_fields = [
 # Please use `active_fields_attributes=`/`active_fields=` instead.
 customizable.active_values_attributes = attributes
 
-# Build an Active Value, if it doesn't exist, with the default value for each Active Field.
+# Build not existing Active Values, with the default value for each Active Field.
+# Returns full collection of Active Values.
 # 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_values, customizable.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
@@ -599,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 = Author
-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