How woylie/flop works
Major Components
• Core Library Modules: At the heart of the project is the “Flop” module (in lib/flop.ex) that ties together functionality for filtering, ordering, and paginating Ecto queries.
• Adapter Layer: Under “lib/flop/adapter”, especially in “ecto” subdirectories, you see the specific adapters (e.g., lib/flop/adapter/ecto.ex and its operators) responsible for integrating Flop with the Ecto database layer.
• Custom Types & Utility Modules: Modules like “lib/flop/custom_types” and modules such as “Flop.Filter”, “Flop.Meta”, “Flop.Schema”, “Flop.Cursor”, “Flop.Validation”, and “Flop.Relay” encapsulate core business logic (validation, pagination meta, filtering operations, and also Relay (cursor based) formatters).
• Configuration/Integration Modules: Configuration files in “config/” and the mix.exs file set up project dependencies and establish default behaviors (for example, linking to a default repo).
• Testing & Support: The “test/” directory shows a detailed test hierarchy for each component (including adapter tests for Ecto on different databases like PostgreSQL and SQLite, custom types tests, etc.) along with support modules which simulate domain models (like pet, owner, vegetable, etc.) to exercise the functionality.
• Documentation & Cheatsheets: The README and the “cheatsheets” directory provide quick reference designs and usage instructions, especially guiding the integration with Phoenix and Absinthe Relay.
Relationships & Interactions
• The core functions (e.g., Flop.validate_and_run/3, Flop.validate/2, Flop.run/3) will be the entry point for any query modification tasks.
• Once parameters are received (either from a Phoenix controller/resolver or directly), the validation modules check and validate the provided parameters.
• Then, the adapter layer (Flop.Adapter.Ecto) is used to transform the validated parameters into appropriate Ecto queries by applying filters, join conditions, ordering, and pagination logic.
• The “Flop.Relay” module comes into play for scenarios that require Relay-compatible pagination, transforming query results into a “connection” response with edges and PageInfo.
• Custom types (defined under lib/flop/custom_types) add flexibility to support additional data types or specialized filtering beyond the built-ins.
• Testing modules simulate various components and scenarios – this verifies that the interactions between the validation, adapter, and the main library are correct across different backends (e.g., PostgreSQL vs. SQLite).
Architectural Patterns & Design Principles
• Separation of Concerns: There is a clear separation between validation (Flop.Validation), query adaptation (Flop.Adapter), and formatting (Flop.Relay). This modular approach makes the library highly reusable and testable.
• Extensibility: The design allows for customizations via user-defined schemas (see Flop.Schema) to explicitly declare which fields are sortable/filterable, and also via custom types to extend beyond the default behavior.
• Integration with Third-Party Systems: The library smoothly integrates with Ecto for DB querying, and with Phoenix/Absinthe (via Flop Phoenix and Flop.Relay) to cater to web applications and GraphQL APIs.
• On the left, show the “Input Layer” (parameter intake, validation modules).
• In the center, the “Business Logic” area including adapters (Ecto integration) and core functions (sorting, filtering, pagination, metadata generation).
• On the right, the “Output Layer” (result formatting via Flop.Relay and any helper utilities for URL generation and UI).