Filterator

API Query Builder for Dart, A powerful and flexible library for constructing structured API queries with support for filtering, ordering, paging, and seamless conversion to API-specific formats.

Features ✨

• Type-safe Query Building: Create complex queries with fluent interface.
• Standard Converters: Convert queries to REST/GraphQL formats.
• Custom Converters: Implement domain-specific serialization.
• Immutable API: All operations return new query instances.
• Nested Filter Groups: Support for AND/OR/NOT logic with unlimited nesting.
• Easily pluggable: into any backend API format (Supy, GraphQL, OData, etc.)

Installation 📦

Add to your pubspec.yaml:

dependencies:
   filterator: ^0.1.3

🚀 Getting Started

Quick Start

Instead of manually constructing queries as raw String or JSON objects, this library introduces a typed query interface that allows you to express complex query logic using fluent, composable functions. This approach offers a safer and more readable API for building queries, while remaining flexible enough to support multiple backends like REST, GraphQL, OData, or any other API format. By defining your queries using this interface (e.g. ApiQuery, where, and, or, ordering, paginate, etc.), you can then pass them through your standardized converter, such as ODataConverter Example, to serialize them into the appropriate format (query parameters, request body, etc.) — fully decoupling query logic from transport format.

🔍 Simple Filters (Short Style)

final query = ApiQuery(
  filtering: and(
    filters: [
      where('email', 'contains', '@example.com'),
      wheres('status', 'in', ['active', 'pending']),
    ],
  ),
);

• ✅ Use where() for single value.
• ✅ Use wheres() for multiple values (like in, notIn)

🧱 Filters (Verbose Object Style)

final query = ApiQuery(
  filtering: and(
    filters: [
      ApiQueryFilter(
        field: 'email',
        operation: QueryOperation.contains,
        value: '@example.com',
      ),
      ApiQueryFilter(
        field: 'status',
        operation: QueryOperation.inList,
        values: ['active', 'pending'],
      ),
    ],
  ),
);

• 🧩 Useful when you need more control or dynamic values.

🔁 Nested Group Filters (AND + OR)

final query = ApiQuery(
  filtering: and(
    filters: [
      where('email', 'contains', '@example.com'),
    ],
    groups: [
      or(
        filters: [
          where('name', 'eq', 'John'),
          where('name', 'eq', 'Jane'),
        ],
      ),
    ],
  ),
);

• ⚖️ Combine conditions: email contains AND (name = John OR name = Jane)

🔃 Ordering Results

final query = ApiQuery(
  ordering: [
    ordering('name', 'asc'),
    ordering('createdAt', 'desc'),
  ],
);

• 🔼 Sort results ascending or descending by any field

📄 Pagination

final query = ApiQuery(
  paging: paginate(limit: 20, offset: 0),
);

• 🔢 Control how many results to fetch and from where to start

🎯 Field Selection

final query = ApiQuery(
  selection: include(['id', 'name', 'status']),
  // or
  // selection: exclude(['internalNotes']),
);

• 📌 Choose what fields to include/exclude in the API response

🧩 Full Example: All Combined

final query = ApiQuery(
  filtering: and(
    filters: [
      where('email', 'contains', '@example.com'),
    ],
    groups: [
      or(
        filters: [
          where('name', 'eq', 'John'),
          where('name', 'eq', 'Jane'),
        ],
      ),
    ],
  ),
  ordering: [ordering('name', 'asc')],
  paging: paginate(limit: 20, offset: 0),
  selection: include(['items']),
);

🔄 Combines filtering, nested groups, ordering, paging, and selection

• Convert to your format

final converter = 
  SupyConverter(query) ,
  ODataConverter(query),
/// or any other customConverter

• Customize your query format

class CustomConverter extends ApiStandardConverter {
  CustomConverter(super.query);

  @override
  Map<String, dynamic> toQueryParameters() {
    final params = <String, dynamic>{};

    /// your custom transformer here. for example
    if (query.filtering != null) {
      params['fields'] = query.filtering!.filters.map((e) => {e.value});
    }
    return params;
  }

  @override
  String toRequestBody() {
    /// your custom transformer here
    return '';
  }
}

• As query parameters (for GET requests)

final params = converter.toQueryParameters();

• As JSON request body (for POST requests)

final body = converter.toRequestBody();

📚 API Reference

• ApiQuery Field Reference Table

• IApiQueryFilteringGroup Properties

• IApiQueryFilter Properties

• IApiQueryOrdering Properties

• IApiQueryPaging Properties

• IApiQuerySelection Properties

🙌 Contributions

Feel free to fork, contribute, or suggest features. PRs are welcome!