odata_query 2.4.0

OData Query Builder is a simple Dart package for building OData query parameter for your REST API.

OData Query Builder

OData Query Builder is a Dart package designed for building OData query strings for REST API endpoints. It provides a clean, declarative API to construct complex queries efficiently.

---

🚀 Features

✔ Build OData Queries: Supports $filter, $orderby, $select, $expand, $top, $skip, and $count.
✔ Programmatic Filter Construction: Build OData filters with logical operators like eq, lt, gt, and, or, not, etc.
✔ URL Encoding: Automatically encodes query parameters for safe use in URLs with toEncodedString().
✔ Map Conversion: Convert query parameters into a Map<String, String> format for flexible API integration.

📚 For detailed OData query options, see:
OData Query Options Overview

---

📌 Examples

🔹 Example 1: Basic Filtering, Sorting, Selecting, Expanding, using .toEncodedString()

final queryString = ODataQuery(
  filter: Filter.and(
    Filter.eq('Name', 'Milk'),
    Filter.lt('Price', 2.55),
  ),
  orderBy: OrderBy.desc('Price'),
  select: ['Name', 'Price'],
  expand: ['Category'],
  top: 10,
  count: true,
).toEncodedString();

// $filter=Name%20eq%20'Milk'%20and%20Price%20lt%202.55&$orderby=Price%20desc&$select=Name%2CPrice&$expand=Category&$top=10&$count=true

---

🔹 Example 2: Filtering with Logical Operators, using .toMap()

ODataQuery(
  filter: Filter.and(
    Filter.or(
      Filter.eq('Category', 'Beverages'),
      Filter.eq('Category', 'Snacks'),
    ),
    Filter.gt('Price', 5),
  ),
  select: ['Name', 'Price', 'Category'],
  expand: ['Supplier', 'Category'],
).toMap();

// {
//   '$filter': "Category eq 'Beverages' or Category eq 'Snacks' and Price gt 5",
//   '$select': 'Name,Price,Category',
//   '$expand': 'Supplier,Category',
// }

---

🔹 Example 3: Nested Query, using .toString()

ODataQuery(
  select: ['Name', 'Price'],
  expand: [
    'Category(${ODataQuery(
      select: ['Type'],
    )};${ODataQuery(
      orderBy: OrderBy.asc('DateCreated'),
    )})',
  ],
).toString();

// $select=Name,Price&$expand=Category($select=Type;$orderby=DateCreated asc)

---

🔹 Example 4: Using inList for Multiple Values

final queryInList = ODataQuery(
  filter: Filter.inList('Name', ['Milk', 'Cheese', 'Donut']),
  select: ['Name', 'Price'],
)

---

🔹 Example 5: Using inCollection for Collection Reference

ODataQuery(
  filter: Filter.inCollection('Name', 'RelevantProductNames'),
  select: ['Name', 'Price'],
)

---

🔹 Example 6: any Filter

ODataQuery(
  filter: Filter.any('Products', 'item', Filter.eq('item/Type', 'Active')),
)

---

🔹 Example 7: all Filter

ODataQuery(
  filter: Filter.all('Products', 'item', Filter.eq('item/Type', 'Active')),
)

---

🔹 Example 8: Using startsWith, endsWith, contains, and not

ODataQuery(
  filter: Filter.or(
    Filter.and(
      Filter.startsWith('Name', 'Choco'),
      Filter.endsWith('Name', 'Bar'),
    ),
    Filter.not(
      Filter.contains('Name', 'Sugar'),
    ),
  ),
)

---

📚 API Overview

ODataQuery Parameters

Parameter	Description
search	Free-text search across multiple fields.
filter	Apply filters using conditions like eq, lt, gt, not.
orderBy	Sort results by ascending (asc) or descending (desc).
select	Choose specific fields to return.
expand	Include related entities in the response.
top	Limit the number of records returned.
skip	Skip a specified number of records (for pagination).
count	Include total count of matching records.

Filter Operators

Operator	Description
eq	Equals (Name eq 'Milk')
ne	Not equals
lt / gt	Less than / Greater than
le / ge	Less than or equal / Greater than or equal
and / or	Combine filters
inList	Check if a value is in a list
inCollection	Check if a value exists in a collection
any / all	Apply filters on collections
not	Negate a condition (not(contains(Name, 'Sugar')))
contains	Check if a value contains a substring (contains(Name, 'Choco'))
startsWith	Check if a value starts with a substring (startswith(Name, 'Choco'))
endsWith	Check if a value ends with a substring (endswith(Name, 'Bar'))

---

🤝 Contributing

Contributions are welcome! Feel free to submit issues or pull requests.