Clientside queries with extensive filtering and typesafe joins
This lib only generates the query string, so you need to use it with your own implementation of http request. There is no need to scaffold any pre build model.
- Filtering with
filter
- Ordering with
orderBy
- Selecting with
select
- Expanding with
expand
- Expanding with
groupBy
- Paginating with
paginate
- Development
Every query exposes a method called filter
. This method accepts a function as parameter that builds an expersion.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.filter(u => u.id.equals(1))
.toString()
// result: $filter=id eq 1
Note that the parameter u
is not a User
type but FilterBuider<User>
. The FilterBuider
will exposes all properties from T
as FilterBuilderType
to provide all filter functions based on its property type which can be:
FilterCollection
FilterString
FilterNumber
FilterBoolean
FilterDate
FilterBuilder
Check out all the available methods here.
export type FilterBuider<T> = {
[P in keyof T]: FilterBuilderType<T[P]>
}
You can modify/combine expresions using not()
, and()
and or()
.
.filter(u => u.username.contains('dave').not()) //where the username doest not contain dave
.filter(u => u.emailActivaed.equals(true).and(u.username.contains('dave')))
Calling filter
multiple times will merge the experions in a bigger expersion using the and
operator. In this example you will get the users where "the id is not equal to 1 AND the username start with 'harry'".
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.filter(u => u.id.notEquals(1))
.filter(u => u.username.startsWith('Harry'))
.toString()
// result: $filter=id eq 1 and startswith(username, 'Harry')
More filter examples:
odataQuery<User>().filter(u => not(u.id.equals(1))) //where the id is not 1
// result: $filter=id ne 1
odataQuery<User>().filter(u => u.id.equals(1).and(
u.username.startsWith('Harry') //where the id is 1 AND the username starts with 'harry'
)))
// result: $filter=id eq 1 and startswith(username, 'harry')
odataQuery<User>().filter(u => u.id.equals(1).or(
u.username.startsWith('Harry') //where the id is 1 OR the username starts with 'harry'
)))
// result: $filter=id eq 1 or startswith(username, 'harry')
odataQuery<User>().filter(u => u.email.startswith(u.name)) //You can also use properties of the same type instead of just values
// result: $filter=startswith(email, name)
You can also use "key selector" passing the property key at the first parameter.
odataQuery<User>().filter('id', id => id.equals(1))
// result: $filter=id eq 1
select
is used to select a set of properties of your model:
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>().select('id', 'username')
// result: $select=id,username
orderby
is used to order the result of your query. This method accepts a lamda to that return the property on witch you want to order.
odataQuery<User>().orderBy(u => u.id)
// result: $orderby=id
It is posible to order on relations:
odataQuery<User>().select('username').orderBy(u => u.address.city)
// result: $select=username;$orderby=address/city
You can set the order mode by calling Desc
or Asc
.
odataQuery<User>().orderBy(u => u.id.desc())
// result: $orderby=id desc
You can also orderBy
with key string.
odataQuery<User>().orderBy('id', 'desc')
// result: $orderby=id desc
expand
is used to load the relationships of the model within the current query. This query can be used to filter, expand and select on the relation you are including.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.expand('blogs')
.toString()
// result: $expand=blogs
All the query methods are available inside an "expand" call.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.expand('blogs', q =>
q
.select('id', 'title')
.filter(b => b.public.equals(true))
.orderBy('id')
.paginate(0, 10)
)
.toString()
// result: $expand=blogs($skip=0;$top=10;$orderby=id;$select=id,title;$filter=public eq true)
It's possible to nest "expand" calls inside each other.
import { odataQuery } from "odata-fluent-query";
odataQuery<User>()
.expand('blogs', q => q
.select('id', 'title')
.expand('reactions' q => q.select('id', 'title')
))
.toString();
// result: $expand=blogs($select=id,title;$expand=reactions($select=id,title))
groupBy
uses odata $apply
method to gruop data by property with optional aggregations.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.groupBy(['email'])
.toString()
// result: $apply=groupby((email))
It's posible to apply custom aggregations.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.groupBy(['email', 'surname'], a =>
a.countdistinct('id', 'all').max('phoneNumbers', 'test')
)
.toString()
// result: $apply=groupby((email, surname), aggregate(id with countdistinct as all, phoneNumbers with max as test))
paginate
applies $top
, $skip
and $count
automatically.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.paginate(10)
.toString()
// result: $top=10&$count=true
Skip and top.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.paginate(25, 5)
.toString()
// result: $skip=125&$top=25&$count=true
Using object and setting count
to false.
import { odataQuery } from 'odata-fluent-query'
odataQuery<User>()
.paginate({ page: 5, pagesize: 25, count: false })
.toString()
// result: $skip=125&$top=25
Dependencies are managed by using npm
. To install all the dependencies run:
npm
To build the project run:
npm build
The output files will be placed in the build
directory. This project contains unittest using jest
and ts-jest
. They are placed in the test
directory. To run all the test run:
npm run test
After this you can open coverage/lcov-report/index.html
in your browser to see all the details about you tests. To publish the package you can run:
npm publish