Contribute to the project
Any kind of contribution is welcome.
start contributing to the project by submitting pull requests
Todos
- ⚡ Add more Examples/use-case to the documentation
- ⚡ Resolve open issues
- ⚡ Improve the documentation site
- ⚡ Improve code documentation (summary)
- ⚡ Add project Security Policy
Documentation
Gridify documentation is powered by vuePress, All the markdown source files are placed in docs directory.
by running the following commands, you can check the documentation site locally:
shell
yarn install
+yarn devshell
npm install
+npm run devHow to contribute
check out the github contributing guide
Contributors
Thank you to everyone who has contributed to the Gridify codebase. We appreciate you!
Using Gridify in API Controllers
When working with ASP.NET APIs, especially when you need to apply string-based filtering conditions, sorting based on field names, or implementing pagination functionality, the Gridify library is a valuable tool. It can be used in any .NET project and with any type of collection, not just limited to ASP.NET projects.
To demonstrate the core concepts of Gridify, let's look at a simple implementation in the following example.
Describing the Scenario
Imagine you have an API that returns a list of users. You want to use this API in your client-side application to display a list of users.
csharp
// UserController
+// ...
+public IEnumerable<User> GetUsers()
+{
+ // context can be Entity Framework, a repository, or whatever.
+ return context.Users.ToList();
+}However, there are a few challenges:
- The end-user may want to sort the list by name, age, or any other property.
- The end-user may want to filter the list by name, age, or any other property.
- Fetching the entire list of users is not efficient, so you need to add pagination.
- Returning a list of page size N is not enough. You also need to know the total number of users.
Implementing these features can be complex and messy. If you want to support multiple properties, you would need to write a lot of code with if-else statements. This is where Gridify comes in.
Solving Problems Using Gridify
With Gridify, you can simplify your code and implement the required features in just a few lines:
csharp
public Paging<User> GetUsers([FromQuery] GridifyQuery query)
+{
+ return context.Users.Gridify(query);
+}Gridify handles all the complexity behind the scenes.
What is the Paging Return Value?
The Paging class is a generic Data Transfer Object (DTO) that has two properties:
csharp
public int Count { get; set; }
+public IEnumerable<T> Data { get; set; }The Count property indicates the total number of records, while the Data property contains the records on the current page.
What is GridifyQuery?
GridifyQuery is a class that represents the query parameters passed to the Gridify method.
Learn more about GridifyQuery.
Sample Request Query String
Please note that this URL is not encoded. Always remember to encode query strings before passing them to your APIs.
http://exampleDomain.com/api/GetUsers?
+ pageSize=100&
+ page=1&
+ orderBy=FirstName&
+ filter=Age>10Alternatively, you can ignore the GridifyQuery and use the default pagination values, which are pageSize=20 and page=1.
http://exampleDomain.com/api/GetUsersMore Information
TIP
- If you want to control which fields are supported for filtering or ordering, you can use the GridifyMapper class.
- All Gridify extension methods accept a
GridifyMapperinstance as a parameter. - If you want to learn more about the filtering and ordering syntax, be sure to read the related documentation.
AutoMapper
Gridify is completely compatible with AutoMapper. Also, these two packages can help each other nicely. We can use Gridify for filtering, sorting, and paging and AutoMapper for the projection.
csharp
// AutoMapper ProjectTo + Filtering Only, example
+var query = personRepo.ApplyFiltering(gridifyQuery);
+var result = query.ProjectTo<PersonDTO>().ToList();csharp
// AutoMapper ProjectTo + Filtering + Ordering + Paging, example
+QueryablePaging<Person> qp = personRepo.GridifyQueryable(gridifyQuery);
+var result = new Paging<Person>(qp.Count, qp.Query.ProjectTo<PersonDTO>().ToList());GridifyTo!
Filtering, Ordering, Paging, and Projection are all done with GridifyTo.
Gridify library does not have a built-in GridifyTo extension method because we don't want to have AutoMapper dependency. but if you are using AutoMapper in your project, I recommend you to add the bellow extension method to your project.
csharp
public static Paging<TDestination> GridifyTo<TSource, TDestination>(
+ this IQueryable<TSource> query, IMapper autoMapper, IGridifyQuery gridifyQuery, IGridifyMapper<TSource> mapper = null)
+{
+ var res = query.GridifyQueryable(gridifyQuery, mapper);
+ return new Paging<TDestination>(res.Count, res.Query.ProjectTo<TDestination>(autoMapper.ConfigurationProvider).ToList());
+}csharp
`,9),p=[n];function k(l,e,r,d,E,g){return a(),s("div",null,p)}const F=i(h,[["render",k]]);export{o as __pageData,F as default};
diff --git a/assets/guide_autoMapper.md.C64WRQ-o.lean.js b/assets/guide_autoMapper.md.C64WRQ-o.lean.js
new file mode 100644
index 00000000..36d96807
--- /dev/null
+++ b/assets/guide_autoMapper.md.C64WRQ-o.lean.js
@@ -0,0 +1 @@
+import{_ as i,c as s,o as a,a4 as t}from"./chunks/framework.Cmp6zcjC.js";const o=JSON.parse('{"title":"AutoMapper","description":"","frontmatter":{},"headers":[],"relativePath":"guide/autoMapper.md","filePath":"guide/autoMapper.md"}'),h={name:"guide/autoMapper.md"},n=t("",9),p=[n];function k(l,e,r,d,E,g){return a(),s("div",null,p)}const F=i(h,[["render",k]]);export{o as __pageData,F as default};
diff --git a/assets/guide_compile.md.oQKQvwx7.js b/assets/guide_compile.md.oQKQvwx7.js
new file mode 100644
index 00000000..8cab1c07
--- /dev/null
+++ b/assets/guide_compile.md.oQKQvwx7.js
@@ -0,0 +1,14 @@
+import{_ as s,c as i,o as t,a4 as a}from"./chunks/framework.Cmp6zcjC.js";const E=JSON.parse('{"title":"Compile and Reuse","description":"","frontmatter":{},"headers":[],"relativePath":"guide/compile.md","filePath":"guide/compile.md"}'),e={name:"guide/compile.md"},n=a(`// only if you have Gridify.EntityFramework package installed.
+public static async Task<Paging<TDestination>> GridifyToAsync<TSource, TDestination>(
+ this IQueryable<TSource> query, IMapper autoMapper, IGridifyQuery gridifyQuery, IGridifyMapper<TSource> mapper = null)
+{
+ var res = await query.GridifyQueryableAsync(gridifyQuery, mapper);
+ return new Paging<TDestination>(res.Count, await res.Query.ProjectTo<TDestination>(autoMapper.ConfigurationProvider).ToListAsync());
+}Compile and Reuse
You can access Gridify generated expressions using the GetFilteringExpression of GridifyQuery or BuildCompiled methods of QueryBuilder class, by storing an expression you can use it multiple times without having any overheads, also if you store a compiled expression you get a massive performance boost.
WARNING
You should only use a compiled expression (delegate) if you are not using Gridify alongside an ORM like Entity-Framework.
csharp
// eg.1 - using GridifyQuery - Compiled - where only
+var gq = new GridifyQuery() { Filter = "name=John" };
+var expression = gq.GetFilteringExpression<Person>();
+var compiledExpression = expression.Compile();
+var result = persons.Where(compiledExpression);csharp
// eg.2 - using QueryBuilder - Compiled - where only
+var compiledExpression = new QueryBuilder<Person>()
+ .AddCondition("name=John")
+ .BuildFilteringExpression()
+ .Compile();
+var result = persons.Where(compiledExpression);csharp
// eg.3 - using QueryBuilder - BuildCompiled
+var func = new QueryBuilder<Person>()
+ .AddCondition("name=John")
+ .BuildCompiled();
+var result = func(persons);Performance
This is the performance improvement example when you use a compiled expression.
| Method | Mean | Ratio | RatioSD | Gen 0 | Gen 1 | Allocated |
|---|---|---|---|---|---|---|
| GridifyCompiled | 1.008 us | 0.001 | 0.00 | 0.1564 | - | 984 B |
| Gridify | 689.329 us | 1.000 | 0.00 | 5.8594 | 2.9297 | 39,924 B |
| NativeLINQ | 736.854 us | 1.019 | 0.01 | 5.8594 | 2.9297 | 37,392 B |
Dependency Injection
Gridify offers a powerful feature that enables you to streamline data mapping and configurations in your application by integrating with the Dependency Injection (DI) container. By registering your mapping profiles with DI, you can achieve cleaner, more maintainable code and improved separation of concerns. This section provides an overview of how to register your GridifyMapper configurations with DI.
Register GridifyMapper with DI
Registering Gridify mapping with DI is a straightforward process. You'll define mapping profiles for your models and then register them in the DI container. Follow these steps to get started:
1. Define Mapping Profiles
Create mapping profiles by inheriting from GridifyMapper<T>, where T represents the type you want to map. Configure your mappings within these profile classes.
Example:
csharp
public class WeatherForecastGridifyMapper : GridifyMapper<WeatherForecast>
+{
+ public WeatherForecastGridifyMapper()
+ {
+ // Define your mappings here
+ AddMap("summary", q => q.Summary);
+ AddMap("temp", q => q.TemperatureC);
+
+ // optionally you can customize the configuration for each mapper
+ Configuration.CaseSensitive = false;
+ Configuration.AllowNullSearch = true;
+ Configuration.IgnoreNotMappedFields = true;
+
+ }
+}2. Register Mapping Profiles
Utilize the AddGridifyMappers extension method available on the IServiceCollection to scan your assembly and register all mapping profiles.
Example:
csharp
using Gridify; // Make sure to include the necessary namespace
+// ...
+
+public void ConfigureServices(IServiceCollection services)
+{
+ // Other service registrations
+
+ services.AddGridifyMappers(typeof(Program).Assembly);
+}3. Inject and Use Mappers
Once you've registered the mapping profiles, you can inject the corresponding IGridifyMapper<T> interfaces into your services or controllers.
Example:
csharp
public class WeatherForecastController : ControllerBase
+{
+ private readonly IGridifyMapper<WeatherForecast> _mapper;
+
+ public WeatherForecastController(IGridifyMapper<WeatherForecast> mapper)
+ {
+ _mapper = mapper;
+ }
+
+ [HttpGet(Name = "GetWeatherForecast")]
+ public Paging<WeatherForecast> Get([FromQuery] GridifyQuery query)
+ {
+ IQueryable<WeatherForecast> result = GetWeatherForecasts();
+
+ // You can pass the mapper to the GridifyExtension
+ return result.Gridify(query, _mapper);
+ }
+}csharp
public class WeatherForecastController : ControllerBase
+{
+ private readonly IGridifyMapper<WeatherForecast> _mapper;
+
+ public WeatherForecastController(IGridifyMapper<WeatherForecast> mapper)
+ {
+ _mapper = mapper;
+ }
+
+ [HttpGet(Name = "GetWeatherForecast")]
+ public IEnumerable<WeatherForecast> Get([FromQuery] GridifyQuery query)
+ {
+ var result = GetWeatherForecasts();
+
+ var queryBuilder = new QueryBuilder<WeatherForecast>()
+ .UseCustomMapper(_mapper)
+ .AddQuery(query);
+
+ return queryBuilder.Build(result);
+ }
+}Extensions
The Gridify library adds the below extension methods to IQueryable objects.
All Gridify extension methods can accept GridifyQuery and GridifyMapper as a parameter. Make sure to check out the documentation of these classes for more information.
TIP
If you want to use Gridify extension methods on an IEnumerable object, use .AsQueryable() first.
ApplyFiltering
You can use this method if you want to only apply filtering on an IQueriable or DbSet.
csharp
var query = personsRepo.ApplyFiltering("name = John");this is completely equivalent to the below LINQ query:
csharp
var query = personsRepo.Where(p => p.Name == "John");In the ApplyFiltering method, we can use a raw string to filter the data, which can be generated dynamically or passed by the end-user for example through an API client or console input, but using the Linq Where method, we always have to hard code the query for the supported fields.
Check out the Filtering Operators section for more information.
ApplyOrdering
You can use this method if you want to only apply ordering on an IQueriable collection or DbSet.
csharp
var query = personsRepo.ApplyOrdering("name, age desc");this is completely equivalent to the below LINQ query:
csharp
var query = personsRepo.OrderBy(x => x.Name).ThenByDescending(x => x.Age);Check out the Ordering section for more information.
ApplyPaging
You can use this method if you want to only apply paging on an IQueryable collection or DbSet.
csharp
var query = personsRepo.ApplyPaging(3, 20);this is completely equivalent to the below LINQ query:
csharp
var query = personsRepo.Skip((3-1) * 20).Take(20);ApplyFilteringAndOrdering
You can use this method if you want to apply filtering and ordering on an IQueryable collection or DbSet. This method accepts IGridifyQuery.
ApplyOrderingAndPaging
You can use this method if you want to apply ordering and paging on an IQueryable collection or DbSet. This method accepts IGridifyQuery.
ApplyFilteringOrderingPaging
You can use this method if you want to apply filtering and ordering and paging on an IQueryable collection or DbSet. This method accepts IGridifyQuery.
GridifyQueryable
Like ApplyFilteringOrderingPaging but it returns a QueryablePaging<T> that has an extra int Count value that can be used for pagination.
Gridify
This is an ALL-IN-ONE package, it accepts IGridifyQuery, applies filtering, ordering, and paging, and returns a Paging<T> object. This method is completely optimized to be used with any Grid component.
Elasticsearch
Gridify.Elasticsearch is an extension of Gridify, that provides an ability to generate Elasticsearch DSL queries.
Gridify.Elasticsearch Package
The Gridify.Elasticsearch package has a bunch of extension methods that allow to convert Gridify filters and sortings to Elasticsearch DSL queries using Elastic.Clients.Elasticsearch .NET client.
Installation
Package Manager
',6),r={class:"language-shell vp-adaptive-theme"},E=s("button",{title:"Copy Code",class:"copy"},null,-1),d=s("span",{class:"lang"},"shell",-1),c={class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0"},g={class:"line"},o=s("span",{style:{"--shiki-light":"#6F42C1","--shiki-dark":"#B392F0"}},"Install-Package",-1),u=s("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}}," Gridify.Elasticsearch",-1),y=s("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}}," -Version",-1),b={style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},F=s("h3",{id:"net-cli",tabindex:"-1"},[e(".NET CLI "),s("a",{class:"header-anchor",href:"#net-cli","aria-label":'Permalink to ".NET CLI"'},"")],-1),m={class:"language-shell vp-adaptive-theme"},C=s("button",{title:"Copy Code",class:"copy"},null,-1),q=s("span",{class:"lang"},"shell",-1),B={class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0"},v={class:"line"},A=i('dotnet add package Gridify.Elasticsearch --version',5),_={style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},f=i(`Configurations
CustomElasticsearchNamingAction
Specifies how field names are inferred from CLR property names. By default, Elastic.Clients.Elasticsearch uses camel-case property names.
- If
null(default behavior) CLR propertyEmailAddresswill be inferred asemailAddressElasticsearch document field name. - If, e.g.,
p => p, the CLR propertyEmailAddresswill be inferred asEmailAddressElasticsearch document field name.
Default
csharp
await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFiltering("emailAddress = test@test.com"));this will make the next Elasticsearch query:
json
GET users/_search
+{
+ "query": {
+ "term": {
+ "emailAddress.keyword": {
+ "value": "test@test.com"
+ }
+ }
+ }
+}Customized:
csharp
GridifyGlobalConfiguration.CustomElasticsearchNamingAction = p => $"_{p}_";
+
+await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFiltering("emailAddress = test@test.com"));this will make the next Elasticsearch query:
json
GET users/_search
+{
+ "query": {
+ "term": {
+ "_EmailAddress_.keyword": {
+ "value": "test@test.com"
+ }
+ }
+ }
+}Examples of usage
Without pre-initialized mapper
csharp
var gq = new GridifyQuery()
+{
+ Filter = "FirstName=John",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+var response = await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyPaging(gq)
+ .ApplyFiltering(gp)
+ .ApplyOrdering(gp));
+
+return response.Documents;json
GET users/_search
+{
+ "query": {
+ "term": {
+ "firstName.keyword": {
+ "value": "John"
+ }
+ }
+ },
+ "from": 0,
+ "size": 20,
+ "sort": [{
+ "age": {
+ "order": "asc"
+ }
+ }]
+}With custom mapping
csharp
var gq = new GridifyQuery()
+{
+ Filter = "name=John, surname=Smith, age=30, totalOrderPrice=45",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+var mapper = new GridifyMapper<User>()
+ .AddMap("name", x => x.FirstName)
+ .AddMap("surname", x => x.LastName)
+ .AddMap("age", x => x.Age)
+ .AddMap("totalOrderPrice", x => x.Order.TotalSum);
+
+var response = await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFilteringOrderingPaging(gq));
+
+return response.Documents;json
GET users/_search
+{
+ "query": {
+ "bool": {
+ "must": [
+ {
+ "term": {
+ "firstName.keyword": {
+ "value": "John"
+ }
+ }
+ },
+ {
+ "term": {
+ "lastName.keyword": {
+ "value": "Smith"
+ }
+ }
+ },
+ {
+ "term": {
+ "age": {
+ "value": 30
+ }
+ }
+ },
+ {
+ "term": {
+ "order.totalSum": {
+ "value": 45
+ }
+ }
+ }
+ ]
+ }
+ },
+ "from": 0,
+ "size": 20,
+ "sort": [{
+ "age": {
+ "order": "asc"
+ }
+ }]
+}With CustomElasticsearchNamingAction initialized
By default, Elasticsearch converts property names to camel-case for document fields. That's Gridify.Elasticsearch extensions work by default. But if it's necessary to apply a custom naming policy, it can also be customized.
csharp
Func<string, string>? namingAction = p => $"_{p}_";
+var mapper = new GridifyMapper<TestClass>(autoGenerateMappings: true)
+{
+ Configuration = { CustomElasticsearchNamingAction = namingAction }
+};
+
+var gq = new GridifyQuery()
+{
+ Filter = "FirstName=John",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+var response = await client.SearchAsync<User>(s => s
+ .Index("users")
+ .ApplyFilteringOrderingPaging(gq));json
GET users/_search
+{
+ "query": {
+ "term": {
+ "_FirstName_.keyword": {
+ "value": "John"
+ }
+ }
+ },
+ "from": 0,
+ "size": 20,
+ "sort": [{
+ "_Age_": {
+ "order": "asc"
+ }
+ }]
+}WARNING
Gridify.Elasticsearch package does not support all of the advanced Gridify features like NestedFiltering
Entity Framework
Gridify.EntityFramework Package
The Gridify.EntityFramework package has two additional GridifyAsync() and GridifyQueryableAsync() methods.
Installation
Package Manager
',5),p={class:"language-shell vp-adaptive-theme"},d=i("button",{title:"Copy Code",class:"copy"},null,-1),k=i("span",{class:"lang"},"shell",-1),y={class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0"},c={class:"line"},m=i("span",{style:{"--shiki-light":"#6F42C1","--shiki-dark":"#B392F0"}},"Install-Package",-1),E=i("span",{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}}," Gridify.EntityFramework",-1),g=i("span",{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"}}," -Version",-1),_={style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},b=i("h3",{id:"net-cli",tabindex:"-1"},[n(".NET CLI "),i("a",{class:"header-anchor",href:"#net-cli","aria-label":'Permalink to ".NET CLI"'},"")],-1),u={class:"language-shell vp-adaptive-theme"},F=i("button",{title:"Copy Code",class:"copy"},null,-1),f=i("span",{class:"lang"},"shell",-1),C={class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0"},w={class:"line"},v=a('dotnet add package Gridify.EntityFramework --version',5),P={style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},T=a(`Compatibility layer
If you want to use gridify with Entity Framework, you should enable the compatibility layer:
csharp
GridifyGlobalConfiguration.EnableEntityFrameworkCompatibilityLayer();Enabling the compatibility layer provides the following features:
- It tweaks the internal expression builder to make it compatible with Entity Framework.
- EF query optimization
- EF ServiceProviderCaching support
- Creates parameterized queries
sql
DECLARE @__Value_0 nvarchar(4000) = N'vahid';
+
+SELECT [u].[Id], [u].[CreateDate], [u].[FkGuid], [u].[Name]
+FROM [Users] AS [u]
+WHERE [u].[Name] = @__Value_0Configuration
EntityFrameworkCompatibilityLayer
Setting this property to true Enables the EntityFramework Compatibility layer to make the generated expressions compatible with entity framework.
- type:
bool - default:
false
EnableEntityFrameworkCompatibilityLayer()
Simply sets the EntityFrameworkCompatibilityLayer property to true.
DisableEntityFrameworkCompatibilityLayer()
Simply sets the EntityFrameworkCompatibilityLayer property to false.
Gridify Client Library
The Gridify Client library is a lightweight JavaScript and TypeScript library designed to simplify the creation of dynamic queries on the client side. This library facilitates the construction of queries that can be seamlessly integrated with your server-side APIs, leveraging the powerful features of Gridify.
Installation
To integrate the Gridify Client library into your project, install it using npm:
shell
npm i gridify-clientGridifyQueryBuilder
The GridifyQueryBuilder interface represents the methods available for constructing dynamic queries using the Gridify Client library.
The following table describes the methods available in the GridifyQueryBuilder interface for constructing dynamic queries.
| Method | Parameter | Description |
|---|---|---|
| setPage | page: number | Set the page number for pagination. |
| setPageSize | pageSize: number | Set the page size for pagination. |
| addOrderBy | field: string, descending?: boolean | Add ordering based on a field. If descending is true, the ordering is in descending order (default is ascending). |
| addCondition | field, operator, value, caseSensitive, escapeValue | Add filtering conditions. caseSensitive and escapeValue are optional parameters. |
| startGroup | - | Start a logical grouping of conditions. |
| endGroup | - | End the current logical group. |
| and | - | Add the logical AND operator. |
| or | - | Add the logical OR operator. |
| build | - | Build and retrieve the constructed query. |
Conditional Operators
We can use the ConditionalOperator enum to access supported operators. we can pass these operators to the second parameter of addCondition method
| Operator | Description |
|---|---|
Equal | Equality |
NotEqual | Inequality |
LessThan | Less Than |
GreaterThan | Greater Than |
GreaterThanOrEqual | Greater Than or Equal |
LessThanOrEqual | Less Than or Equal |
Contains | String Contains (LIKE) |
NotContains | String Does Not Contain (NOT LIKE) |
StartsWith | String Starts With |
NotStartsWith | String Does Not Start With |
EndsWith | String Ends With |
NotEndsWith | String Does Not End With |
Usage Example
Below is a basic example demonstrating the usage of the Gridify Client library in TypeScript. This example constructs a dynamic query for pagination, ordering, and filtering:
ts
import { GridifyQueryBuilder, ConditionalOperator as op } from "gridify-client";
+
+const query = new GridifyQueryBuilder()
+ .setPage(2)
+ .setPageSize(10)
+ .addOrderBy("name", true)
+ .startGroup()
+ .addCondition("age", op.LessThan, 50)
+ .or()
+ .addCondition("name", op.StartsWith, "A")
+ .endGroup()
+ .and()
+ .addCondition("isActive", op.Equal, true)
+ .build();
+
+console.log(query);Output:
json
`,17),d=[n];function l(h,r,p,k,o,E){return t(),s("div",null,d)}const y=i(e,[["render",l]]);export{c as __pageData,y as default};
diff --git a/assets/guide_extensions_gridify-client.md.B5eDeC5h.lean.js b/assets/guide_extensions_gridify-client.md.B5eDeC5h.lean.js
new file mode 100644
index 00000000..51901c09
--- /dev/null
+++ b/assets/guide_extensions_gridify-client.md.B5eDeC5h.lean.js
@@ -0,0 +1 @@
+import{_ as i,c as s,o as t,a4 as a}from"./chunks/framework.Cmp6zcjC.js";const c=JSON.parse('{"title":"Gridify Client Library","description":"","frontmatter":{},"headers":[],"relativePath":"guide/extensions/gridify-client.md","filePath":"guide/extensions/gridify-client.md"}'),e={name:"guide/extensions/gridify-client.md"},n=a("",17),d=[n];function l(h,r,p,k,o,E){return t(),s("div",null,d)}const y=i(e,[["render",l]]);export{c as __pageData,y as default};
diff --git a/assets/guide_filtering.md.3yi-EqLN.js b/assets/guide_filtering.md.3yi-EqLN.js
new file mode 100644
index 00000000..fe3f7da7
--- /dev/null
+++ b/assets/guide_filtering.md.3yi-EqLN.js
@@ -0,0 +1,43 @@
+import{_ as s,c as i,o as a,a4 as t}from"./chunks/framework.Cmp6zcjC.js";const c=JSON.parse('{"title":"Filtering","description":"","frontmatter":{},"headers":[],"relativePath":"guide/filtering.md","filePath":"guide/filtering.md"}'),e={name:"guide/filtering.md"},n=t(`{
+ "page": 2,
+ "pageSize": 10,
+ "orderBy": "name desc",
+ "filter": "(age<50|name^A),isActive=true"
+}Filtering
Gridify supports the following filtering operators:
Conditional Operators
| Name | Operator | Usage example |
|---|---|---|
| Equal | = | "FieldName = Value" |
| NotEqual | != | "FieldName !=Value" |
| LessThan | < | "FieldName < Value" |
| GreaterThan | > | "FieldName > Value" |
| GreaterThanOrEqual | >= | "FieldName >=Value" |
| LessThanOrEqual | <= | "FieldName <=Value" |
| Contains - Like | =* | "FieldName =*Value" |
| NotContains - NotLike | !* | "FieldName !*Value" |
| StartsWith | ^ | "FieldName ^ Value" |
| NotStartsWith | !^ | "FieldName !^ Value" |
| EndsWith | $ | "FieldName $ Value" |
| NotEndsWith | !$ | "FieldName !$ Value" |
TIP
If you don't specify any value after = or != operators, Gridify search for the default and null values.
csharp
var x = personsRepo.ApplyFiltering("name=");this is equivalent to the bellow LINQ query:
csharp
var x = personsRepo.Where(p =>
+ p.Name is null ||
+ p.Name == string.Empty );Special Operators
Logical Operators
Using logical operators we easily can create complex queries.
| Name | Operator | Usage example |
|---|---|---|
| AND | , | "FirstName = Value, LastName = Value2" |
| OR | | | "FirstName=Value|LastName=Value2" |
| Parenthesis | () | "(FirstName=*Jo,Age<30)|(FirstName!=Hn,Age>30)" |
Case Insensitive Operator - /i
The '/i' operator can be use after string values for case insensitive searches. You should only use this operator after the search value.
Example:
csharp
var x = personsRepo.ApplyFiltering("FirstName=John/i");this query matches with JOHN - john - John - jOHn ...
Escaping
Gridify have five special operators , | ( ) /i to handle complex queries and case-insensitive searches. If you want to use these characters in your query values (after conditional operator), you should add a backslash \\ before them. having this regex could be helpful ([(),|]|\\/i).
JavaScript escape example:
javascript
let esc = (v) => v.replace(/([(),|\\\\]|\\/i)/g, '\\\\$1')Csharp escape example:
csharp
var value = "(test,test2)";
+var esc = Regex.Replace(value, "([(),|\\\\]|\\/i)", "\\\\$1" );
+// esc = \\(test\\,test2\\)Using Indexers
Starting from version v2.15.0, Gridify supports filtering on any property that is indexable, including sub-collections, arrays, and dictionaries. This feature allows you to create dynamic and flexible queries for a wide range of data structures.
Passing Index/Key to Sub-Collections, Arrays, and Dictionaries
Gridify enables filtering on elements of sub-collections, arrays, and dictionary properties by specifying the index or key within square brackets [ ].
Here’s an example:
csharp
var gm = new GridifyMapper<TargetType>()
+ .AddMap("arrayProp", (target, index) => target.MyArray[index].Prop)
+ .AddMap("dictProp", (target, key) => target.MyDictionary[key]);
+
+var gq = new GridifyQuery
+{
+ Filter = "arrayProp[8] > 10, dictProp[name] = John"
+};In this example:
arrayProp[8] > 10 filters on the 8th element of an array property. dictProp[name] = John filters on the value associated with the name key in a dictionary property.
This new capability makes Gridify a versatile and robust tool for handling complex data structures in your filtering logic.
Check out Defining Mappings for Indexable Properties for more information.
Custom Operators
Sometimes the default Gridify operators are not enough, For example, if you need an operator for regex matching or when you are using the EntityFramework, you may want to use EF.Functions.FreeText rather than a LIKE with wildcards. In this case, you can define your own operators. (added in v2.6.0)
To define a custom operator, you need to create a class that implements the IGridifyOperator interface. then you need to register it through the global CustomOperators configuration.
TIP
Custom operators must be start with the # character.
- FreeTextOperator Example:
csharp
class FreeTextOperator : IGridifyOperator
+{
+ public string GetOperator() => "#=";
+ public Expression<OperatorParameter> OperatorHandler()
+ {
+ return (prop, value) => EF.Functions.FreeText(prop, value.ToString());
+ }
+}- RegexMatchOperator Example:
csharp
class RegexMatchOperator : IGridifyOperator
+{
+ public string GetOperator() => "#%";
+ public Expression<OperatorParameter> OperatorHandler()
+ {
+ return (prop, value) => Regex.IsMatch(prop.ToString(), value.ToString());
+ }
+}- InOperator Example:
csharp
class InOperator: IGridifyOperator
+{
+ public string GetOperator()
+ {
+ return "#In";
+ }
+
+ public Expression<OperatorParameter> OperatorHandler()
+ {
+ return (prop, value) => value.ToString()
+ .Split(";",StringSplitOptions.RemoveEmptyEntries)
+ .Contains(prop.ToString());
+ }
+}
+
+// usage: .ApplyFiltering("name #In John;David;Felipe")Registration Example:
csharp
`,42),h=[n];function l(p,k,r,d,o,E){return a(),i("div",null,h)}const y=s(e,[["render",l]]);export{c as __pageData,y as default};
diff --git a/assets/guide_filtering.md.3yi-EqLN.lean.js b/assets/guide_filtering.md.3yi-EqLN.lean.js
new file mode 100644
index 00000000..f09f3192
--- /dev/null
+++ b/assets/guide_filtering.md.3yi-EqLN.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a4 as t}from"./chunks/framework.Cmp6zcjC.js";const c=JSON.parse('{"title":"Filtering","description":"","frontmatter":{},"headers":[],"relativePath":"guide/filtering.md","filePath":"guide/filtering.md"}'),e={name:"guide/filtering.md"},n=t("",42),h=[n];function l(p,k,r,d,o,E){return a(),i("div",null,h)}const y=s(e,[["render",l]]);export{c as __pageData,y as default};
diff --git a/assets/guide_getting-started.md.mDab1sVc.js b/assets/guide_getting-started.md.mDab1sVc.js
new file mode 100644
index 00000000..7499b8b7
--- /dev/null
+++ b/assets/guide_getting-started.md.mDab1sVc.js
@@ -0,0 +1 @@
+import{_ as a,c as n,j as i,t,a4 as e,o as l}from"./chunks/framework.Cmp6zcjC.js";const H=JSON.parse('{"title":"Getting Started","description":"","frontmatter":{},"headers":[],"relativePath":"guide/getting-started.md","filePath":"guide/getting-started.md"}'),o={name:"guide/getting-started.md"},r=e(' GridifyGlobalConfiguration.CustomOperators.Register<FreeTextOperator>();
+ GridifyGlobalConfiguration.CustomOperators.Register<RegexMatchOperator>();
+ GridifyGlobalConfiguration.CustomOperators.Register<InOperator>();Getting Started
There are three packages available for gridify in the nuget repository:
TIP
If you are using the Entity Framework in your project, you should install the Gridify.EntityFramework package instead of Gridify.
This package provides the same functionality as the Gridify package but is designed to be more compatible with Entity Framework.
TIP
To use Gridify with Elasticsearch, it's necessary to install Gridify.Elasticsearch.
If you are developing in a JavaScript or TypeScript environment and need to create dynamic queries on the client side for server-side operations, Gridify also offers a lightweight client library. gridify-client
Installation
',11),h={class:"vp-code-group vp-adaptive-theme"},d=e('',1),c={class:"blocks"},p={class:"language-shell vp-adaptive-theme active"},_=i("button",{title:"Copy Code",class:"copy"},null,-1),k=i("span",{class:"lang"},"shell",-1),g={class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0"},u={class:"line"},y=e('dotnet add package Gridify --version',5),f={style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},F={class:"language-shell vp-adaptive-theme"},b=i("button",{title:"Copy Code",class:"copy"},null,-1),m=i("span",{class:"lang"},"shell",-1),C={class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0"},T={class:"line"},v=e('dotnet add package Gridify.EntityFramework --version',5),E={style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},S={class:"language-shell vp-adaptive-theme"},w=i("button",{title:"Copy Code",class:"copy"},null,-1),G=i("span",{class:"lang"},"shell",-1),B={class:"shiki shiki-themes github-light github-dark vp-code",tabindex:"0"},P={class:"line"},A=e('dotnet add package Gridify.Elasticsearch --version',5),I={style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"}},V=e('shell
',1),x=e('npm i gridify-clientNamespace
After installing the package, you can use the Gridify namespace to access the package classes and static Extension methods.
csharp
using Gridify;How to use
There are two ways to start using Gridify:
- Using the Extension methods
- Using QueryBuilder
GridifyGlobalConfiguration
Using this class you can change the default behavior and configuration of the Gridify library.
General configurations
DefaultPageSize
The default page size for the paging methods when no page size is specified.
- type:
int - default:
20
CaseSensitiveMapper
By default mappings are case insensitive. For example, name=John and Name=John are considered equal. You can change this behavior by setting this property to true.
- type:
bool - default:
false - related to: GridifyMapper - CaseSensitive
AllowNullSearch
This option enables the null keyword in filtering operations, for example, name=null searches for all records with a null value for the name field not the string "null". if you need to search for the string "null" you can disable this option.
- type:
bool - default:
true - related to: GridifyMapper - AllowNullSearch
IgnoreNotMappedFields
If true, in filtering and ordering operations, gridify doesn't return any exceptions when a mapping is not defined for the given field.
- type:
bool - default:
false - related to: GridifyMapper - IgnoreNotMappedFields
DisableNullChecks
On nested collections by default gridify adds a null checking condition to prevent the null reference exceptions
e.g () => field != null && field....
some ORMs like NHibernate don't support this. You can disable this behavior by setting this option to true.
- type:
bool - default:
false
CaseInsensitiveFiltering
If true, string comparison operations are case insensitive by default.
- type:
bool - default:
false
DefaultDateTimeKind
By default, Gridify uses the DateTimeKind.Unspecified when parsing dates. You can change this behavior by setting this property to DateTimeKind.Utc or DateTimeKind.Local. This option is useful when you want to use Gridify with a database that requires a specific DateTimeKind, for example when using npgsql and postgresql.
- type:
DateTimeKind - default:
null
CustomOperators
Using the Register method of this property you can add your own custom operators.
csharp
GridifyGlobalConfiguration.CustomOperators.Register<MyCustomOperator>();To learn more about custom operators, see Custom operator
',30),n=[l];function r(s,d,c,p,u,h){return i(),a("div",null,n)}const m=e(t,[["render",r]]);export{g as __pageData,m as default}; diff --git a/assets/guide_gridifyGlobalConfiguration.md.CgHl5As4.lean.js b/assets/guide_gridifyGlobalConfiguration.md.CgHl5As4.lean.js new file mode 100644 index 00000000..6fb7e8c6 --- /dev/null +++ b/assets/guide_gridifyGlobalConfiguration.md.CgHl5As4.lean.js @@ -0,0 +1 @@ +import{_ as e,c as a,o as i,a4 as o}from"./chunks/framework.Cmp6zcjC.js";const g=JSON.parse('{"title":"GridifyGlobalConfiguration","description":"","frontmatter":{},"headers":[],"relativePath":"guide/gridifyGlobalConfiguration.md","filePath":"guide/gridifyGlobalConfiguration.md"}'),t={name:"guide/gridifyGlobalConfiguration.md"},l=o("",30),n=[l];function r(s,d,c,p,u,h){return i(),a("div",null,n)}const m=e(t,[["render",r]]);export{g as __pageData,m as default}; diff --git a/assets/guide_gridifyMapper.md.x8t9gokN.js b/assets/guide_gridifyMapper.md.x8t9gokN.js new file mode 100644 index 00000000..ec366194 --- /dev/null +++ b/assets/guide_gridifyMapper.md.x8t9gokN.js @@ -0,0 +1,54 @@ +import{_ as s,c as i,o as a,a4 as e}from"./chunks/framework.Cmp6zcjC.js";const y=JSON.parse('{"title":"GridifyMapper","description":"","frontmatter":{},"headers":[],"relativePath":"guide/gridifyMapper.md","filePath":"guide/gridifyMapper.md"}'),t={name:"guide/gridifyMapper.md"},n=e(`GridifyMapper
Internally Gridify is using an auto generated mapper that maps your string base field names to actual properties in your entities, but sometimes we don't want to support filtering or sorting on a specific field. If you want to control what field names are mapped to what properties, you can create a custom mapper.
To get a better understanding of how this works, consider the following example:
csharp
// sample Entities
+public class Person
+{
+ public string UserName { get; set; }
+ public string FirstName { get; set; }
+ public string LastName { get; set; }
+ public string Password { get; set; }
+ public Contact Contact { get; set; }
+}
+
+public class Contact
+{
+ public string Address { get; set; }
+ public int PhoneNumber { get; set; }
+}In this example we want to:
- Generate default mappings
- Ignore the
Passwordproperty - Map the
addressandmobileto the Contact property - Make sure the userName value is always lowercase in the search
csharp
var mapper = new GridifyMapper<Person>()
+ .GenerateMappings()
+ .RemoveMap(nameof(Person.Password))
+ .AddMap("address", p => p.Contact.Address)
+ .AddMap("mobile", p => p.Contact.PhoneNumber)
+ .AddMap("userName", p => p.UserName, v => v.ToLower());In the following, we will become more familiar with the above methods
GenerateMappings
This method generates mappings for the properties of the entity, including top-level public properties and properties of nested classes up to the specified nesting depth.
- To generate mappings for top-level public properties only, you can call this method without passing any arguments:
csharp
var mapper = new GridifyMapper<Person>()
+ .GenerateMappings();- To generate mappings with control over nesting depth, you can specify the
maxNestingDepthparameter. This parameter limits how deep the mappings will be generated for nested classes and navigation properties(added in v2.15.0). Set it to 0 for no nesting or a positive value to control the depth(added in v2.11.0):
csharp
var mapper = new GridifyMapper<Person>()
+ // Generates mappings for top-level properties and properties of nested classes up to 2 levels deep.
+ .GenerateMappings(2);TIP
Another alternative to generate default mappings for top-level public properties is by passing true to the GridifyMapper constructor. This generates mappings without considering nesting depth.
csharp
var mapper = new GridifyMapper<Person>(true);
+var mapperWithDepth = new GridifyMapper<Person>(true, 2);RemoveMap
This method removes mapping from the mapper. Usually you will use this method after you have generated the mappings to ignore some properties that you don't want to be supported by Gridify filtering or ordering actions.
AddMap
This method adds a mapping to the mapper.
- the first parameter is the name of the field you want to use in the string query
- the second parameter is a property selector expression
- the third parameter is an optional value convertor expression that you can use to convert user inputs to anything you want
Value convertor
If you need to change your search values before the filtering operation you can use this feature, the third parameter of the GridifyMapper AddMap method accepts a function that you can use to convert the input values.
in the above example we want to convert the userName value to lowercase before the filtering operation.
csharp
mapper = mapper.AddMap("userName", p => p.UserName, value => value.ToLower());HasMap
This method checks if the mapper has a mapping for the given field name.
ClearMaps
This method clears the list of mappings
GetCurrentMaps
This method returns list of current mappings.
GetCurrentMapsByType
This method returns list of current mappings for the given type.
GridifyMapperConfiguration
csharp
var mapperConfig = new GridifyMapperConfiguration()
+{
+ CaseSensitive = false,
+ AllowNullSearch = true,
+ IgnoreNotMappedFields = false
+};
+
+var mapper = new GridifyMapper<Person>(mapperConfig);CaseSensitive
By default mapper is Case-insensitive but you can change this behavior if you need Case-Sensitive mappings.
- Type:
bool - Default:
false
csharp
var mapper = new GridifyMapper<Person>(q => q.CaseSensitive = true);IgnoreNotMappedFields
By setting this to true Gridify don't throw an exception when a field name is not mapped. for instance, in the above example, searching for password will not throw an exception.
- Type:
bool - Default:
false
csharp
var mapper = new GridifyMapper<Person>(q => q.IgnoreNotMappedFields = true);AllowNullSearch
By setting this to false, Gridify don't allow searching on null values using the null keyword for values.
- Type:
bool - Default:
true
csharp
var mapper = new GridifyMapper<Person>(q => q.AllowNullSearch = false);CaseInsensitiveFiltering
If true, string comparison operations are case insensitive by default.
- type:
bool - default:
false
csharp
var mapper = new GridifyMapper<Person>(q => q.CaseInsensitiveFiltering = true);DefaultDateTimeKind
By setting this property to a DateTimeKind value, you can change the default DateTimeKind used when parsing dates.
- type:
DateTimeKind - default:
null
csharp
var mapper = new GridifyMapper<Person>(q => q.DefaultDateTimeKind = DateTimeKind.Utc);Filtering on Nested Collections
You can use LINQ Select and SelectMany methods to filter your data using its nested collections.
In this example, we have 3 nested collections, but filtering will apply to the Property1 of the third level.
csharp
var mapper = new GridifyMapper<Level1>()
+ .AddMap("prop1", l1 => l1.Level2List
+ .SelectMany(l2 => l2.Level3List)
+ .Select(l3 => l3.Property1));
+// ...
+var query = level1List.ApplyFiltering("prop1 = 123", mapper);if you have only two-level nesting, you don't need to use SelectMany.
Defining Mappings for Indexable Properties
Starting from version v2.15.0, GridifyMapper's AddMap method supports filtering on properties that are indexable, such as sub-collections, arrays, and dictionaries. This allows you to create dynamic queries by defining mappings to specific indexes or dictionary keys using square brackets [ ].
Mapping to Array Indexes
You can define a mapping to a specific index in an array or sub-collection by specifying the index within square brackets [ ].\`
csharp
var gm = new GridifyMapper<TargetType>()
+ .AddMap("arrayProp", (target, index) => target.MyArray[index].Prop);
+
+var gq = new GridifyQuery
+{
+ // Filters on the 8th element of an array property
+ Filter = "arrayProp[8] > 10"
+};Mapping to Dictionary Keys
Similarly, you can define a mapping to a specific key in a dictionary or in a navigation property.
csharp
var gm = new GridifyMapper<TargetType>()
+ .AddMap("dictProp", (target, key) => target.MyDictionary[key]);
+
+var gm2 = new GridifyMapper<TargetType>()
+ .AddMap("navProp", (target, key) => target.NavigationProperty.Where(n => n.Key == key).Select(n => n.Value));
+
+var gq = new GridifyQuery
+{
+ // Filters on the value associated with the 'name' key in a dictionary
+ Filter = "dictProp[name] = John"
+};Generic Overload for Non-String Dictionary Keys
If your dictionary key is not a string, you can use the generic overload of the AddMap<T> method to specify the key type.
csharp
var gm = new GridifyMapper<TargetType>()
+ .AddMap<Guid>("dictProp", (target, key) => target.MyDictionary[key]);For more information on filtering using these mappings, refer to the Using Indexers.
GetExpression
This method returns the selector expression that you can use it in LINQ queries.
csharp
Expression<Func<Person, object>> selector = mapper.GetExpression(nameof(Person.Name));GetLambdaExpression
This method returns the selector expression that you can use it in LINQ queries.
csharp
`,77),h=[n];function p(l,k,r,d,g,o){return a(),i("div",null,h)}const c=s(t,[["render",p]]);export{y as __pageData,c as default};
diff --git a/assets/guide_gridifyMapper.md.x8t9gokN.lean.js b/assets/guide_gridifyMapper.md.x8t9gokN.lean.js
new file mode 100644
index 00000000..1806af4f
--- /dev/null
+++ b/assets/guide_gridifyMapper.md.x8t9gokN.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a4 as e}from"./chunks/framework.Cmp6zcjC.js";const y=JSON.parse('{"title":"GridifyMapper","description":"","frontmatter":{},"headers":[],"relativePath":"guide/gridifyMapper.md","filePath":"guide/gridifyMapper.md"}'),t={name:"guide/gridifyMapper.md"},n=e("",77),h=[n];function p(l,k,r,d,g,o){return a(),i("div",null,h)}const c=s(t,[["render",p]]);export{y as __pageData,c as default};
diff --git a/assets/guide_gridifyQuery.md.CEJIRn4b.js b/assets/guide_gridifyQuery.md.CEJIRn4b.js
new file mode 100644
index 00000000..c99ef209
--- /dev/null
+++ b/assets/guide_gridifyQuery.md.CEJIRn4b.js
@@ -0,0 +1,23 @@
+import{_ as s,c as i,o as a,a4 as h}from"./chunks/framework.Cmp6zcjC.js";const o=JSON.parse('{"title":"GridifyQuery","description":"","frontmatter":{},"headers":[],"relativePath":"guide/gridifyQuery.md","filePath":"guide/gridifyQuery.md"}'),n={name:"guide/gridifyQuery.md"},t=h(`LambdaExpression selector = mapper.GetLambdaExpression(nameof(Person.Name));GridifyQuery
GridifyQuery is a simple class for configuring Filtering, Ordering and Paging.
csharp
var gq = new GridifyQuery()
+{
+ Filter = "FirstName=John",
+ Page = 1,
+ PageSize = 20,
+ OrderBy = "Age"
+};
+
+// Apply Filter, Sort and Paging
+Paging<Person> result = personsRepo.Gridify(gq);IsValid
This extension method, checks if the GridifyQuery (Filter, OrderBy) is valid to use with a custom mapper or the auto generated mapper and returns true or false.
csharp
var gq = new GridifyQuery() { Filter = "name=John" , OrderBy = "Age" };
+// true
+bool isValid = gq.IsValid<Person>();csharp
var gq = new GridifyQuery() { Filter = "NonExist=John" , OrderBy = "Age" };
+// false (NonExist is not a property of Person)
+bool isValid = gq.IsValid<Person>();csharp
var gq = new GridifyQuery() { Filter = "@name=!" , OrderBy = "Age" };
+// false (this is not a valid filter)
+bool isValid = gq.IsValid<Person>();Optionally you can pass a custom mapper to check if the GridifyQuery is valid for that mapper.
csharp
var mapper = new GridifyMapper<Person>()
+ .AddMap("name", q => q.Name);
+var gq = new GridifyQuery() { Filter = "name=John" , OrderBy = "Age" };
+
+// false (Age is not mapped)
+bool isValid = gq.IsValid(mapper);GetFilteringExpression
This extension method, creates a lambda expression using the GridifyQuery.Filter property that you can use it in the LINQ Where method to filter the data.
csharp
`,13),k=[t];function l(p,e,r,d,g,E){return a(),i("div",null,k)}const F=s(n,[["render",l]]);export{o as __pageData,F as default};
diff --git a/assets/guide_gridifyQuery.md.CEJIRn4b.lean.js b/assets/guide_gridifyQuery.md.CEJIRn4b.lean.js
new file mode 100644
index 00000000..4657a560
--- /dev/null
+++ b/assets/guide_gridifyQuery.md.CEJIRn4b.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a4 as h}from"./chunks/framework.Cmp6zcjC.js";const o=JSON.parse('{"title":"GridifyQuery","description":"","frontmatter":{},"headers":[],"relativePath":"guide/gridifyQuery.md","filePath":"guide/gridifyQuery.md"}'),n={name:"guide/gridifyQuery.md"},t=h("",13),k=[t];function l(p,e,r,d,g,E){return a(),i("div",null,k)}const F=s(n,[["render",l]]);export{o as __pageData,F as default};
diff --git a/assets/guide_index.md.C2ZxBUIO.js b/assets/guide_index.md.C2ZxBUIO.js
new file mode 100644
index 00000000..4b8e09ac
--- /dev/null
+++ b/assets/guide_index.md.C2ZxBUIO.js
@@ -0,0 +1 @@
+import{_ as t,c as a,o as e,a4 as i}from"./chunks/framework.Cmp6zcjC.js";const c=JSON.parse('{"title":"Introduction","description":"","frontmatter":{},"headers":[],"relativePath":"guide/index.md","filePath":"guide/index.md"}'),d={name:"guide/index.md"},r=i('var gq = new GridifyQuery() { Filter = "name=John" };
+Expression<Func<T, bool>> expression = gq.GetFilteringExpression<Person>();
+var result = personsRepo.Where(expression);Introduction
Greetings!
Gridify is an exceptional dynamic LINQ library designed to simplify the process of converting strings into LINQ queries. It offers remarkable performance and ease-of-use, making it effortless to apply filtering, sorting, and pagination utilizing text-based data.
Features
Here are some notable features of Gridify:
- Fast and user-friendly
- Supports filtering, sorting, and pagination
- Enables conversion from strings to LINQ queries
- Supports nested queries and sub-collections
- Allows mapping from strings to objects
- Supports query compilation
- Supports DocumentDBs
- Compatible with collection indexes
- Custom operators
- Can be used with any collection that supports LINQ
- Compatible with object-mappers like AutoMapper
- Compatible with ORMs, particularly Entity Framework
- Supports Elasticsearch DSL query
- Javascript/Typescript gridify-client
Examples
To provide a better understanding of Gridify's functionality, we have prepared a few examples:
- Using Gridify in API Controllers
- More examples coming soon...
Performance
Filtering is the most expensive feature in Gridify. The following benchmark compares filtering in various popular dynamic LINQ libraries. Interestingly, Gridify outperforms even Native LINQ in terms of speed. It's worth mentioning that other features like Pagination and Sorting in Gridify have minimal impact on performance.
| Method | Mean | Error | StdDev | Ratio | Allocated | Alloc Ratio |
|---|---|---|---|---|---|---|
| Gridify | 599.8 us | 2.76 us | 2.45 us | 0.92 | 36.36 KB | 1.11 |
| Native_LINQ | 649.9 us | 2.55 us | 2.38 us | 1.00 | 32.74 KB | 1.00 |
| DynamicLinq | 734.8 us | 13.90 us | 13.01 us | 1.13 | 119.4 KB | 3.65 |
| Sieve | 1,190.9 us | 7.41 us | 6.93 us | 1.83 | 53.05 KB | 1.62 |
| Fop | 2,637.6 us | 8.59 us | 7.61 us | 4.06 | 321.57 KB | 9.82 |
| CSharp_Scripting | 216,863.8 us | 4,295.66 us | 6,021.92 us | 336.64 | 23660.26 KB | 722.71 |
Details
BenchmarkDotNet v0.13.10, Windows 11 (10.0.22621.2715/22H2/2022Update/SunValley2) 12th Gen Intel Core i7-12800H, 1 CPU, 20 logical and 14 physical cores .NET SDK 8.0.100 [Host] : .NET 8.0.0 (8.0.23.53103), X64 RyuJIT AVX2
This Benchmark is available Here
Ordering
The ordering query expression can be built with a comma-delimited ordered list of field/property names followed by asc or desc keywords.
By default, if you don't add these keywords, Gridify assumes you need Ascending ordering.
csharp
// asc - desc
+var x = personsRepo.ApplyOrdering("Id"); // default ascending its equal to "Id asc"
+var x = personsRepo.ApplyOrdering("Id desc"); // use descending ordering
+
+// multiple orderings example
+var x = personsRepo.ApplyOrdering("Id desc, FirstName asc, LastName");csharp
// asc - desc
+var gq = new GridifyQuery() { OrderBy = "Id" }; // default ascending its equal to "Id asc"
+var gq = new GridifyQuery() { OrderBy = "Id desc" }; // use descending ordering
+
+// multiple orderings example
+var gq = new GridifyQuery() { OrderBy = "Id desc, FirstName asc, LastName" };csharp
var builder = new QueryBuilder<Person>();
+// asc - desc
+builder.AddOrderBy("Id"); // default ascending its equal to "Id asc"
+builder.AddOrderBy("Id desc"); // use descending ordering
+
+// multiple orderings example
+builder.AddOrderBy("Id desc, FirstName asc, LastName");Order By Nullable types
Sometimes we need to order by nullable types, for example:
csharp
personsRepo.OrderBy(p => p.BirthDate.HasValue)to support this behavior, you can use Gridify special characters (? or !) after the property name.
e.g:
To achieve the personsRepo.OrderBy(p => p.BirthDate.HasValue) query, you can use ?:
csharp
var x = personsRepo.ApplyOrdering("BirthDate?");and for personsRepo.OrderBy(p => !p.BirthDate.HasValue), you can use !:
csharp
var x = personsRepo.ApplyOrdering("BirthDate!");WARNING
These nullable characters will only work on the nullable types.
QueryBuilder
The QueryBuilder class is really useful if you want to manually build your query Or when you don't want to use the extension methods.
| Method | Description |
|---|---|
| AddCondition | Adds a string base Filtering query |
| AddOrderBy | Adds a string base Ordering query |
| ConfigurePaging | Configure Page and PageSize |
| AddQuery | Accepts a GridifyQuery object to configure filtering,ordering and paging |
| UseCustomMapper | Accepts a GridifyMapper to use in build methods |
| UseEmptyMapper | Setup an Empty new GridifyMapper without auto generated mappings |
| AddMap | Add a single Map to existing mapper |
| RemoveMap | Remove a single Map from existing mapper |
| ConfigureDefaultMapper | Configuring default mapper when we didn't use AddMapper method |
| IsValid | Validates Condition, OrderBy, Query , Mapper and returns a bool |
| Build | Applies filtering ordering and paging to a queryable context |
| BuildCompiled | Compiles the expressions and returns a delegate for applying filtering ordering and paging to a enumerable collection |
| BuildFilteringExpression | Returns filtering expression that can be compiled for later use for enumerable collections |
| BuildEvaluator | Returns an evaluator delegate that can be use to evaluate an queryable context |
| BuildCompiledEvaluator | Returns an compiled evaluator delegate that can be use to evaluate an enumerable collection |
| BuildWithPaging | Applies filtering ordering and paging to a context, and returns paging result |
| BuildWithPagingCompiled | Compiles the expressions and returns a delegate for applying filtering ordering and paging to a enumerable collection, that returns paging result |
| BuildWithQueryablePaging | Applies filtering ordering and paging to a context, and returns queryable paging result |
| Evaluate | Directly Evaluate a context to check if all conditions are valid or not |
csharp
`,4),r=[d];function n(l,p,o,h,u,g){return i(),e("div",null,r)}const y=t(s,[["render",n]]);export{c as __pageData,y as default};
diff --git a/assets/guide_queryBuilder.md.kmI5FuP-.lean.js b/assets/guide_queryBuilder.md.kmI5FuP-.lean.js
new file mode 100644
index 00000000..75b6a953
--- /dev/null
+++ b/assets/guide_queryBuilder.md.kmI5FuP-.lean.js
@@ -0,0 +1 @@
+import{_ as t,c as e,o as i,a4 as a}from"./chunks/framework.Cmp6zcjC.js";const c=JSON.parse('{"title":"QueryBuilder","description":"","frontmatter":{},"headers":[],"relativePath":"guide/queryBuilder.md","filePath":"guide/queryBuilder.md"}'),s={name:"guide/queryBuilder.md"},d=a("",4),r=[d];function n(l,p,o,h,u,g){return i(),e("div",null,r)}const y=t(s,[["render",n]]);export{c as __pageData,y as default};
diff --git a/assets/index.md.BQScyGp-.js b/assets/index.md.BQScyGp-.js
new file mode 100644
index 00000000..1d187ebc
--- /dev/null
+++ b/assets/index.md.BQScyGp-.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o as a}from"./chunks/framework.Cmp6zcjC.js";const p=JSON.parse('{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Gridify","text":"Documentation","tagline":"A powerful dynamic LINQ library for .NET","actions":[{"theme":"brand","text":"Get Started","link":"/guide/getting-started"},{"theme":"alt","text":"Introduction","link":"/guide/"}]},"features":[{"title":"Simple and Easy to Use","details":"Gridify offers a powerful string-based dynamic LINQ query language that is both simple and easy to use."},{"title":"Exceptional Performance","details":"Gridify has been designed with performance as a top priority and can outperform other dynamic LINQ libraries."},{"title":"Compatibility","details":"Gridify can be seamlessly integrated into any .NET Core or .NET Framework project, ensuring high compatibility. It can also be used alongside Entity Framework and other ORMs."}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}'),i={name:"index.md"};function r(n,o,s,d,l,c){return a(),t("div")}const f=e(i,[["render",r]]);export{p as __pageData,f as default};
diff --git a/assets/index.md.BQScyGp-.lean.js b/assets/index.md.BQScyGp-.lean.js
new file mode 100644
index 00000000..1d187ebc
--- /dev/null
+++ b/assets/index.md.BQScyGp-.lean.js
@@ -0,0 +1 @@
+import{_ as e,c as t,o as a}from"./chunks/framework.Cmp6zcjC.js";const p=JSON.parse('{"title":"","description":"","frontmatter":{"layout":"home","hero":{"name":"Gridify","text":"Documentation","tagline":"A powerful dynamic LINQ library for .NET","actions":[{"theme":"brand","text":"Get Started","link":"/guide/getting-started"},{"theme":"alt","text":"Introduction","link":"/guide/"}]},"features":[{"title":"Simple and Easy to Use","details":"Gridify offers a powerful string-based dynamic LINQ query language that is both simple and easy to use."},{"title":"Exceptional Performance","details":"Gridify has been designed with performance as a top priority and can outperform other dynamic LINQ libraries."},{"title":"Compatibility","details":"Gridify can be seamlessly integrated into any .NET Core or .NET Framework project, ensuring high compatibility. It can also be used alongside Entity Framework and other ORMs."}]},"headers":[],"relativePath":"index.md","filePath":"index.md"}'),i={name:"index.md"};function r(n,o,s,d,l,c){return a(),t("div")}const f=e(i,[["render",r]]);export{p as __pageData,f as default};
diff --git a/assets/inter-italic-cyrillic-ext.r48I6akx.woff2 b/assets/inter-italic-cyrillic-ext.r48I6akx.woff2
new file mode 100644
index 0000000000000000000000000000000000000000..b6b603d596933f026dfecf98550bbe4d0876276b
GIT binary patch
literal 43112
zcmV)0K+eB+Pew8T0RR910H|mH6951J0UBrk0H^f;1ONa400000000000000000000
z0000Qh94W4P8=#fNLE2oicCLERzXsMCvar builder = new QueryBuilder<Person>()
+ .AddCondition("name=John")
+ .AddOrderBy("age, id");
+
+var query = builder.Build(persons);