diff --git a/README.md b/README.md index 45b08ae8..dcb2ae8a 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ [![Gridify](https://raw.githubusercontent.com/alirezanet/Gridify/master/docs/.vuepress/public/gridify-readme-logo.svg)](https://alirezanet.github.io/Gridify/) ## Introduction + Gridify is a dynamic LINQ library that simplifies the process of converting strings to LINQ queries. With exceptional performance and ease-of-use, Gridify makes it effortless to apply filtering, sorting, and pagination using text-based data. ## Features @@ -32,6 +33,7 @@ Gridify is a dynamic LINQ library that simplifies the process of converting stri - Can be used on every collection that LINQ supports - Compatible with object-mappers like AutoMapper - Compatible with Elasticsearch +- Javascript/Typescript client ## Documentation diff --git a/docs/.vitepress/configs/sidebar.ts b/docs/.vitepress/configs/sidebar.ts index 3c60867b..f6d7505c 100644 --- a/docs/.vitepress/configs/sidebar.ts +++ b/docs/.vitepress/configs/sidebar.ts @@ -31,6 +31,7 @@ export const sidebar: DefaultTheme.Sidebar = { items: [ { text: 'EntityFramework', link: '/guide/extensions/entityframework' }, { text: 'Elasticsearch', link: '/guide/extensions/elasticsearch' }, + { text: 'Gridify Client (JS/TS)', link: '/guide/extensions/gridify-client' }, ] }, { @@ -41,7 +42,7 @@ export const sidebar: DefaultTheme.Sidebar = { { text: 'AutoMapper', link: '/guide/autoMapper' }, ] }, - + ], - + } diff --git a/docs/pages/guide/extensions/gridify-client.md b/docs/pages/guide/extensions/gridify-client.md new file mode 100644 index 00000000..f7a17c12 --- /dev/null +++ b/docs/pages/guide/extensions/gridify-client.md @@ -0,0 +1,88 @@ +# 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-vue +npm i gridify-client +``` + +## GridifyQueryBuilder + +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 +{ + "page": 2, + "pageSize": 10, + "orderBy": "name desc", + "filter": "(age<50|name^A),isActive=true" +} +``` diff --git a/docs/pages/guide/getting-started.md b/docs/pages/guide/getting-started.md index 941825f8..b26b1844 100644 --- a/docs/pages/guide/getting-started.md +++ b/docs/pages/guide/getting-started.md @@ -5,34 +5,54 @@ There are three packages available for gridify in the nuget repository. - [Gridify](https://www.nuget.org/packages/Gridify/) - [Gridify.EntityFramework](https://www.nuget.org/packages/Gridify.EntityFramework/) -- [Gridify.Elasticsearch](https://www.nuget.org/packages/Gridify.Elasticsearch/) ::: tip If you are using the Entity framework in your project, you should install the `Gridify.EntityFramework` package instead of `Gridify`. This package has the same functionality as the `Gridify` package, but it is designed to be more compatible with [Entity Framework](./extensions/entityframework). +::: + +--- +- [Gridify.Elasticsearch](https://www.nuget.org/packages/Gridify.Elasticsearch/) -In order to use Gridify with Elasticsearch it's necessary to install `Gridify.Elasticsearch`. Please read [the separate thread of the documentation](./extensions/elasticsearch). +::: tip +In order to use Gridify with Elasticsearch it's necessary to install [`Gridify.Elasticsearch`](./extensions/elasticsearch). ::: +--- + +If you're developing in a JavaScript or TypeScript environment and need to create dynamic queries on the client side for server-side operations, +Gridify also offer a lightweight client library. [gridify-client](./extensions/gridify-client) + +- [Gridify Client (JS/TS)](https://www.npmjs.com/package/gridify-client) + ## Installation -### Package Manager +:::: code-group -```shell-vue -Install-Package Gridify -Version {{ $version }} +```shell-vue [Gridify] +dotnet add package Gridify --version {{ $version }} ``` -### .NET CLI +```shell-vue [Gridify.EntityFramework] +dotnet add package Gridify.EntityFramework --version {{ $version }} +``` -```shell-vue -dotnet add package Gridify --version {{ $version }} +```shell-vue [Gridify.Elasticsearch] +dotnet add package Gridify.Elasticsearch --version {{ $version }} ``` +```shell-vue [Gridify Client (JS/TS)] +npm i gridify-client +``` + +:::: + ## Namespace After installing the package, you can use the `Gridify` namespace to access the package classes and static Extension methods. + ``` csharp using Gridify; ``` diff --git a/docs/pages/guide/index.md b/docs/pages/guide/index.md index 3d5e1d0e..1e8a29ab 100644 --- a/docs/pages/guide/index.md +++ b/docs/pages/guide/index.md @@ -20,6 +20,7 @@ Here are some notable features of Gridify: - Compatible with object-mappers like AutoMapper - Compatible with ORMs, particularly [Entity Framework](./extensions/entityframework) - Supports [Elasticsearch](./extensions/elasticsearch) DSL query +- Javascript/Typescript [gridify-client](./extensions/gridify-client) ## Examples @@ -35,8 +36,8 @@ The following benchmark compares filtering in various popular dynamic LINQ libra 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 | -|----------------- |-------------:|------------:|------------:|-------:|------------:|------------:| +| 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 |