lexxsoft/odata-query

Contents

• Installation
• Usage
• Basic usage
  • Ordering
  • Expanding
  • Limiting
  • Paging
  • Filtering
  • ID
  • Select
  • Count
  • Search
  • File content

Installation

1npm i @lexxsoft/odata-http-query

Usage

Basic usage

1const o: QueryBuilder = new QueryBuilder()

or

1const o: QueryBuilder = QueryBuilder.make()

Or create with flow

1const o: string = QueryBuilder.make()
2    .querySet('lang', 'en')
3    .toString()

Output lang=en

Configuration

QueryBuilder has configuration to customize process.

Markers

QueryBuilder has markers to customize fixed query params. Type for markers shown below:

1type TQueryMarkers = {
2    select: string[] | string,
3    limit: string[] | string,
4    offset: string[] | string,
5    order: string[] | string,
6    expand: string[] | string,
7    search: string[] | string,
8    count: string[] | string,
9    filter: string[] | string,
10}

Markers and corresponding query field

By default, QueryBuilder markers are correspond to OData query field.

1const DefaultQueryMarkers: TQueryMarkers = {
2    limit: ['$top', '$limit'],
3    offset: ['$skip', '$offset'],
4    order: ['$orderby', '$order'],
5    expand: '$expand',
6    select: '$select',
7    filter: '$filter',
8    count: '$count',
9    search: '$search',
10}

Of course, you can customize there names as you need. For flexibility each marker could have alias. Pass them as array to defaults for correct work. Look at example above.

Custom configuration

QueryBuilder configuration type:

1type TQueryBuilderDefaults = {
2    limit?: number,
3    markers?: TQueryMarkers,
4}

Field	Type	Default	Description
limit	Number	undefined	Set limit to use limitation for every builder instance.
markers	TQueryMarkers	DefaultQueryMarkers	Set custom query field name for every marker

Ordering

Use order method to add order query parameters

Note: order method has an alias orderby

1const o = new QueryBuilder('/users')
2o.order(new QueryOrder('name1')).toString()

Output /users?$orderby=name1 asc

Also, you can combine several order conditions

1const o = new QueryBuilder('/users')
2o.order(new QueryOrder('name1')).order(new QueryOrder('name2', QueryOrderDirection.DESC))
3o.toString()

Output /users?$orderby=name1 asc,name2 desc

Expanding

Use expand method to add expand query parameter

1const o = new QueryBuilder('/users')
2o.expand('company').toString()

Output /users?$expand=company

Or combine several expand parameters

1const o = new QueryBuilder('/users')
2o.expand('company').expand('jobtitle').toString()

Output /users?$expand=company,jobtitle

To add counter to expanding parameter, add true as second parameter of expand method

1const o = new QueryBuilder('/users')
2o.expand('emails', true).toString()

Output /users?$expand=company($count=true)

Limiting

For limiting returned data, use limit and offset methods

Note: limit has an alias top offset has aliases skip and shift

1const o = new QueryBuilder('/users')
2o.top(7).skip(4).toString()

Output /users?$top=7&$skip=4

Paging

To limit output data by page, use page method.

1const o = new QueryBuilder('/users')
2o.page(3).toString()

Output /users?$top=10&$skip=20

By default, it has 10 records per page, but you free to change in via QueryBuilder configuration.

1const o = new QueryBuilder('/users', {rowsPerPage: 5})
2o.page(3).toString()

Output /users?$top=5&$skip=10

Filtering

Use filter method to add constrains. QueryBuilder accept only one filter, but you free to use and and or methods of QueryFilter to combine them together.

1const oFilter = new QueryFilter('gender', 'f')
2oFilter.and('age', 16, QueryFilterSign.GT)
3const o = new QueryBuilder('/users')
4o.filter(oFilter).toString()

Output /users?$filter=gender eq f and age gt 16

Filter operations

• EQ
• GT
• GE
• LT
• LE
• NE
• SUBSTRINGOF
• STARTSWITH
• ENDSWITH

Counting

count method will add $count suffix to url

1const o = new QueryBuilder('/users')
2o.count().toString()

Output /users/$count

Of course, you can use count with filter for example.

1const oFilter = new QueryFilter('gender', 'f')
2oFilter.and('age', 16, QueryFilterSign.GT)
3const o = new QueryBuilder('/users')
4o.filter(oFilter).count().toString()

Output /users/$count?$filter=gender eq f and age gt 16

ID

ID is primary key of database. Use id method to create oData request for single entity.

1const o = new QueryBuilder('/users')
2o.id(4).toString()

Output /users(4)

Select

Use select method to constrain returned fields

1const o = new QueryBuilder('/users')
2o.select(['id', 'name']).toString()

Output /users?$select=id,name

Count

Use count method to get request for count value

1const o = new QueryBuilder('/users')
2o.count()

Output `/users/$count

Other-hand, if you want to make request of data with total count, you can use inlineCount method Use count method to get request for count value

1const o = new QueryBuilder('/users')
2o.inlineCount()

Output `/users?$count=true

search

Free-text search parameter, which was added for OData v4.0

1const o = new QueryBuilder('/users')
2o.search('John Doe')

Output `/users?$search=John Doe

File content

Getting the file content is extra path. It will not make effect to real oData server, but you can use it in development as ideology.

File content as-is

To get file content, call asFileContent method

1const o = new QueryBuilder('/files')
2o.id(4).asFileContent().toString()

Output /files(4)/_file

Base64 encoded content

Sometimes needed to get base64 encoded content. Use asFileContentBase64 method to generate path

1const o = new QueryBuilder('/files')
2o.id(4).asFileContentBase64().toString()

Output /files(4)/_file64

Parsing URL

For case if you already have url, and you want to add or change some parameter, you may use parse method, to parse url and get instance of QueryBuilder

1const o = QueryBuilder.parse(`/employee`)
2consle.log(o.toString())

Output /employee

Or, if you use full url

1const o = QueryBuilder.parse(`http://site.com/api/users`)
2consle.log(o.toString())

Output /users

Output is short, because parse method get only script path. To get full url, add true as second parameter, to tell parser save url as is

1const o = QueryBuilder.parse(`http://site.com/api/users`)
2consle.log(o.toString())

Output http://site.com/api/users

Of-cause, you can use this method to parse url with query

1const o = QueryBuilder.parse(`/users?$count=true`)
2consle.log(o.toString())

Output /users?$count=true