Skip to content

Commit fefc9d4

Browse files
neomasterhubneomasterhub
committed
docs: Improve Readme.md for v1
1 parent 6121c5f commit fefc9d4

16 files changed

Lines changed: 166 additions & 187 deletions

‎Docs/readme/advantages.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
## 🤩 Advantages
1+
## 🤩 Advantages<a name="advantages"/>
22

33
1. **Friendliness**
44

55
JSON is a simple and widely known format, easy to read not only for developers.
66

77
1. **Broad applicability**
88

9-
JSON-based filters can be used in tests, described in specifications, test plans, and other technical documentation, lowering the entry barrier for readers.
9+
JSON-based filters can be used in tests, specifications, test plans, and other technical documentation, lowering the entry barrier for readers.
1010

1111
1. **Universality**
1212

@@ -22,13 +22,13 @@
2222

2323
1. **Simplicity**
2424

25-
Install the NuGet package and pass JSON filters into `Where()` and other LINQ methods. This enables not a minimal subset, but the full filtering functionality.
25+
Install the NuGet package and pass JSON filters into `Where()` and other filtering methods. This enables not a minimal subset, but the full functionality.
2626

2727
**No need to:**
2828

29-
- Register anything in `Program.cs`
30-
- Create schemas, separate DTOs, filters, resolvers, etc.
31-
- Generate a schema for the client
29+
- Register anything in `Program.cs`.
30+
- Create schemas, framework-specific DTOs, filters, resolvers, etc.
31+
- Generate a schema for the client.
3232

3333
Everything required for filtering is already contained in the DTOs.
3434

‎Docs/readme/configuration.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
## 🎛 Configuration
1+
## 🎛 Configuration<a name="configuration"/>
22

33
You can define your own settings via `JsonLinq.Configure()`.
4-
To reset the configuration - necessary for testing - call `JsonLinq.ResetConfiguration()`.
4+
To reset the configuration, call `JsonLinq.ResetConfiguration()`.
5+
This is necessary for testing.
56

67
```csharp
78
JsonLinq.Configure(options =>
@@ -13,7 +14,7 @@ JsonLinq.Configure(options =>
1314
options.FieldPropertyName = "🍁";
1415
options.ValuePropertyName = "🍬";
1516

16-
// Operator definitions and synonyms
17+
// Operator definitions and aliases
1718
options.OperatorMapper = ExpressionOperatorMapper.OnDefault()
1819
.AddAlias("does not contain", "!contains");
1920

@@ -25,11 +26,10 @@ JsonLinq.Configure(options =>
2526
});
2627
```
2728

28-
The JSON filter structure settings seem interesting.
29+
The JSON filter structure settings are relevant.
2930
<br>For example, adding syntactic sugar:
30-
<br>`"Logic": "&&", "Rules": [...]` -> `"&&": [...]`
31-
<br>Or fixing the property order to support [TONL][tonl] filters.
32-
33-
This may be implemented in future versions.
31+
<br>`"Logic": "&&", "Rules": [...]` → `"&&": [...]`
32+
<br>Or specifying the property order to support [TONL][tonl] filters.
33+
<br>This may be implemented in future versions.
3434

3535
[tonl]: https://tonl.dev

‎Docs/readme/demos.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## 🔬 Demos and Experiments
1+
## 🔬 Demos and Experiments<a name="demos"/>
22

33
This repository includes the [JsonToLinq.Demo][demo-project] project with **working examples**.
44
You are welcome to submit a PR with your own examples, bug reports, or new features.

‎Docs/readme/limitations.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,26 @@
1-
## 🚧 Limitations
1+
## 🚧 Limitations<a name="limitations"/>
22

33
1. **No IDE syntax highlighting for JSON filter arguments in LINQ methods**
44

55
The library targets `netstandard2.1`, which does not support `StringSyntaxAttribute`.
6-
Care is needed when writing filters manually. In practice, this is not critical, as filters typically come from client applications.
6+
Care is needed when writing filters manually.
7+
In practice, this is not critical, as filters typically come from client applications.
78

89
1. **No IntelliSense for JSON filters**
910

1011
Without suggestions, it is harder to ensure filter correctness.
1112

1213
1. **Aggregate fields are not supported**
1314

14-
For now, it is recommended to use **flat DTOs** or **database views**.
15+
For now, it is recommended to use **flat DTOs** and **database views**.
1516

1617
```json
1718
{
1819
"Rules": [
19-
{ "Field": "✅ department_id", "Operator": "=", "Value": 123 },
20-
{ "Field": "❌ department.id", "Operator": "=", "Value": 123 }
20+
{ "Field": "✅ user_id", "Operator": "=", "Value": 123 },
21+
{ "Field": "❌ user.id", "Operator": "=", "Value": 123 }
2122
]
2223
}
2324
```
2425

25-
These features may be implemented in future versions...
26+
These features may be implemented in future versions.

‎Docs/readme/operators.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
## 🛠️ Operators
1+
## 🛠️ Operators<a name="operators"/>
22

3-
1. Built-in operators and their handling logic are encapsulated in the `ExpressionOperatorMapper` class.
4-
1. The mapping between operators and their processing methods is available via the `ExpressionOperatorMapper.Pairs` property.
3+
1. Built-in operators and their handling logic
4+
are encapsulated in the `ExpressionOperatorMapper` class.
5+
1. The mapping between operators and their processing methods
6+
is available via the `ExpressionOperatorMapper.Pairs` property.
57
1. Operator keys are case-sensitive.
68

79
### 📌 Built-in Operators
@@ -48,7 +50,7 @@
4850

4951
#### The word `not`
5052

51-
The word `not` is a synonym for `!`.
53+
The word `not` is alias for `!`.
5254

5355
It improves readability but is not suitable for all operators:
5456

@@ -125,7 +127,7 @@ new ExpressionOperatorMapper()
125127
.Add("y z", ...).WithNot() // "~ y z"
126128
```
127129

128-
#### SQL operators
130+
#### SQL Operators
129131

130132
The library is built on `netstandard2.1` and **does not depend on EF** or any other ORM.
131133
To perform case-insensitive string comparisons,

‎Docs/readme/potential.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
1-
## 🔮 Potential
1+
## 🔮 Potential<a name="potential"/>
22

3-
Filtering is just the first stage in the development of JSON-LINQ infrastructure.
3+
Filtering is just the first stage in the development of **JSON-LINQ infrastructure**.
44
Possible future directions include:
55

6-
1. Data selection - JSON for `Select()`
6+
1. Data selecting - JSON for `Select()`
77
1. Data grouping - JSON for `GroupBy()`
88
1. GraphQL engine using standard JSON (as opposed to HotChocolate)
99
1. Server-side equivalents of RxJS/NgRx for reactive data processing
10-
1. Interactive query-building studios - visual builders with *canvas*, *drag-and-drop*, *flowcharts*, *node-based UI*, *etc.*
10+
1. Interactive query-building studios - visual builders with
11+
*canvas*, *drag-and-drop*, *flowcharts*, *node-based UI*, *etc.*
1112
1. Semantic search and NLP
1213
1. A new standard for data exchange between services

‎Docs/readme/quick-start.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
## 🚀 Quick Start
1+
## 🚀 Quick Start<a name="quick-start"/>
22

33
1. Install the [NuGet package][package].
4-
1. Pass JSON text into `Where()` or other filtering methods.
4+
1. Pass JSON filter into `Where()` or other filtering methods.
55
1. To use with `IQueryable`, first create a predicate via `JsonLinq.ParseFilterExpression()`.
66

77
```csharp

‎Docs/readme/shields.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@
22

33
<div align="center">
44

5-
[![License](https://img.shields.io/badge/🧾License-MIT-green?style=flat)](https://opensource.org/licenses/MIT)
5+
[![License](https://img.shields.io/badge/🧾&nbsp;License-MIT-green?style=flat)](https://opensource.org/licenses/MIT)
66
[![Telegram Channel](https://img.shields.io/badge/Telegram-Neomaster-2CA5E0?style=flat&logo=telegram)](https://t.me/neomaster_dev)
7-
[![.NET Version](https://img.shields.io/badge/.NET_Standard-2.1-blueviolet?style=flat&logo=dotnet)](#)
7+
![.NET Version](https://img.shields.io/badge/.NET_Standard-2.1-blueviolet?style=flat&logo=dotnet)
8+
[![Habr](https://img.shields.io/badge/Habr-Article-629fbc?style=flat&logo=habr&logoColor=white)](https://habr.com/ru/articles/982300)
89
[![NuGet](https://img.shields.io/nuget/v/JsonToLinq.svg?label=NuGet&logo=nuget&logoColor=white&labelColor=gray&color=blue)](https://www.nuget.org/packages/JsonToLinq)
910

1011
</div>

‎Docs/readme/table-of-content.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Table of Content
2+
3+
1. [Advantages](#advantages)
4+
1. [Quick Start](#quick-start)
5+
1. [Operators](#operators)
6+
1. [Configuration](#configuration)
7+
1. [Testing](#testing)
8+
1. [Demos and Experiments](#demos)
9+
1. [Limitations](#limitations)
10+
1. [Potential](#potential)

‎Docs/readme/template-nuget.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
{title}
22
{tldr}
3+
{table-of-content}
34
{advantages}
45
{quick-start}
56
{operators}
67
{configuration}
78
{testing}
8-
{demos}
99
{limitations}
1010
{potential}

0 commit comments

Comments
 (0)