docs(filters): document filters match modes

Author: ChronicStone

bun.lockb

@@ -73,20 +73,19 @@ export default defineConfig({
           { text: 'lessThan', link: '/filter-match-modes/less-than' },
           { text: 'lessThanOrEqual', link: '/filter-match-modes/less-than-or-equal' },
           { text: 'exists', link: '/filter-match-modes/exists' },
-          { text: 'objectStringMap', link: '/filter-match-modes/object-string-map' },
           { text: 'arrayLength', link: '/filter-match-modes/array-length' },
           { text: 'objectMatch', link: '/filter-match-modes/object-match' },
         ],
       },
-      {
-        text: 'API Reference',
-        items: [
-          { text: 'Query Function', link: '/api-reference/query-function' },
-          { text: 'QueryParams', link: '/api-reference/query-params' },
-          { text: 'QueryFilter', link: '/api-reference/query-filter' },
-          { text: 'FilterMatchMode', link: '/api-reference/filter-match-mode' },
-        ],
-      },
+      // {
+      //   text: 'API Reference',
+      //   items: [
+      //     { text: 'Query Function', link: '/api-reference/query-function' },
+      //     { text: 'QueryParams', link: '/api-reference/query-params' },
+      //     { text: 'QueryFilter', link: '/api-reference/query-filter' },
+      //     { text: 'FilterMatchMode', link: '/api-reference/filter-match-mode' },
+      //   ],
+      // },
     ],
 
   },

docs/.vitepress/config.ts

@@ -0,0 +1,177 @@
+# Filtering
+
+ArrayQuery provides a powerful and flexible filtering engine that allows you to apply complex conditions to your data. The filtering system supports a wide range of match modes, nested conditions, and logical grouping with built-in array handling.
+
+## Filter Structure
+
+Filters in ArrayQuery can be either an array of individual filter conditions or an array of filter groups. Here's the updated filter structure:
+
+```ts
+export type FilterOptions = Array<QueryFilterGroup> | Array<QueryFilter>
+
+interface QueryFilter {
+  key: string
+  value: any
+  operator?: Operator
+  matchMode: FilterMatchMode
+  params?: ComparatorParams | ObjectMapFilterParams
+}
+
+interface QueryFilterGroup {
+  operator: Operator
+  filters: QueryFilter[]
+}
+
+type Operator = 'AND' | 'OR' | (() => 'AND' | 'OR')
+```
+
+## Basic Usage
+
+Here's a simple example of how to use the filter feature with ArrayQuery:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'John Doe', age: 30, roles: ['admin', 'user'] },
+  { id: 2, name: 'Jane Smith', age: 25, roles: ['user'] },
+  { id: 3, name: 'Bob Johnson', age: 35, roles: ['manager', 'user'] }
+]
+
+const result = query(users, {
+  filter: [
+    { key: 'age', matchMode: 'greaterThan', value: 25 }
+  ]
+})
+```
+
+This query will return users older than 25.
+
+## Advanced Filtering
+
+ArrayQuery supports complex filtering scenarios, including logical groups and built-in array handling.
+
+### Multiple Conditions with Regular Filters
+
+When you use an array of regular filters, all conditions must be met for a row to be included in the result:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'John Doe', age: 30, roles: ['admin', 'user'] },
+  { id: 2, name: 'Jane Smith', age: 25, roles: ['user'] },
+  { id: 3, name: 'Bob Johnson', age: 35, roles: ['manager', 'user'] }
+]
+
+const result = query(users, {
+  filter: [
+    { key: 'age', matchMode: 'greaterThan', value: 25 },
+    { key: 'name', matchMode: 'contains', value: 'John' }
+  ]
+})
+```
+
+This query will return users who are older than 25 AND have 'John' in their name.
+
+### Logical Groups
+
+You can use filter groups to create more complex conditions. When using filter groups, a row will be included if it matches at least one of the groups:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'John Doe', age: 30, roles: ['admin', 'user'] },
+  { id: 2, name: 'Jane Smith', age: 25, roles: ['user'] },
+  { id: 3, name: 'Bob Johnson', age: 35, roles: ['manager', 'user'] },
+  { id: 4, name: 'Alice Williams', age: 65, roles: ['user'] }
+]
+
+const result = query(users, {
+  filter: [
+    {
+      operator: 'AND',
+      filters: [
+        { key: 'age', matchMode: 'greaterThan', value: 18 },
+        { key: 'age', matchMode: 'lessThan', value: 45 }
+      ]
+    },
+    {
+      operator: 'AND',
+      filters: [
+        { key: 'age', matchMode: 'greaterThan', value: 60 },
+        { key: 'age', matchMode: 'lessThan', value: 90 }
+      ]
+    }
+  ]
+})
+```
+
+This example filters users who are either between 18 and 45 years old, OR between 60 and 90 years old. The row will be included if it matches either of these groups.
+
+### Built-in Array Handling
+
+ArrayQuery automatically handles array values in the data. When a filter is applied to a field that contains an array, the filter condition is checked against each element of the array:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'John Doe', age: 30, roles: ['admin', 'user'] },
+  { id: 2, name: 'Jane Smith', age: 25, roles: ['user'] },
+  { id: 3, name: 'Bob Johnson', age: 35, roles: ['manager', 'user'] }
+]
+
+const result = query(users, {
+  filter: [
+    {
+      key: 'roles',
+      matchMode: 'equals',
+      value: 'admin',
+      operator: 'OR'
+    }
+  ]
+})
+```
+
+In this example:
+- For a user with `roles: ['admin', 'manager']`, the filter will return true because at least one element ("admin") matches the condition.
+- The `operator: "OR"` means that if any element in the array matches, the condition is considered true.
+- If `operator: "AND"` was used, all elements in the array would need to match the condition.
+
+### Nested Object Filtering
+
+You can filter based on nested object properties using dot notation:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'John Doe', age: 30, address: { city: 'New York', country: 'USA' } },
+  { id: 2, name: 'Jane Smith', age: 25, address: { city: 'London', country: 'UK' } },
+  { id: 3, name: 'Bob Johnson', age: 35, address: { city: 'Paris', country: 'France' } }
+]
+
+const result = query(users, {
+  filter: [
+    { key: 'address.city', matchMode: 'equals', value: 'New York' }
+  ]
+})
+```
+
+## Match Modes
+
+ArrayQuery supports various match modes for different types of comparisons. Each match mode has its own dedicated documentation page for detailed usage. The available match modes include:
+
+- 'contains'
+- 'between'
+- 'equals'
+- 'notEquals'
+- 'greaterThan'
+- 'greaterThanOrEqual'
+- 'lessThan'
+- 'lessThanOrEqual'
+- 'exists'
+- 'arrayLength'
+- 'objectMatch'

docs/features/filtering.md

@@ -0,0 +1,108 @@
+# Sorting
+
+ArrayQuery provides a flexible sorting capability that allows you to order your data based on one or multiple fields. This feature is crucial for organizing and presenting data in a meaningful way.
+
+## How Sorting Works
+
+The sort feature in ArrayQuery operates based on the `SortOptions` interface:
+
+```ts twoslash
+interface SortOptions {
+  key: string
+  dir: 'asc' | 'desc'
+}
+```
+
+- `key`: The field name to sort by
+- `dir`: The sort direction ('asc' for ascending, 'desc' for descending)
+
+You can provide either a single `SortOptions` object or an array of `SortOptions` to sort by multiple fields.
+
+## Basic Usage
+
+Here's a simple example of how to use the sort feature with ArrayQuery:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'John Doe', age: 30 },
+  { id: 2, name: 'Jane Smith', age: 25 },
+  { id: 3, name: 'Bob Johnson', age: 35 }
+]
+
+const result = query(users, {
+  sort: { key: 'age', dir: 'asc' }
+})
+```
+
+This query will return the following result:
+
+```ts twoslash
+[
+  { id: 2, name: 'Jane Smith', age: 25 },
+  { id: 1, name: 'John Doe', age: 30 },
+  { id: 3, name: 'Bob Johnson', age: 35 }
+]
+```
+
+## Multi-Field Sorting
+
+ArrayQuery supports sorting by multiple fields. The sort options are applied in the order they are provided:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const users = [
+  { id: 1, name: 'John Doe', age: 30 },
+  { id: 2, name: 'Jane Smith', age: 25 },
+  { id: 3, name: 'Martin Sam', age: 35 },
+  { id: 4, name: 'Bob Johnson', age: 35 },
+  { id: 5, name: 'Robert John', age: 28 },
+  { id: 6, name: 'Alice Williams', age: 28 },
+  { id: 7, name: 'Emma Jones', age: 32 }
+]
+
+const result = query(users, {
+  sort: [
+    { key: 'age', dir: 'asc' },
+    { key: 'name', dir: 'asc' }
+  ]
+})
+```
+
+This will return:
+
+```ts twoslash
+[
+  { id: 2, name: 'Jane Smith', age: 25 },
+  { id: 6, name: 'Alice Williams', age: 28 },
+  { id: 5, name: 'Robert John', age: 28 },
+  { id: 1, name: 'John Doe', age: 30 },
+  { id: 7, name: 'Emma Jones', age: 32 },
+  { id: 4, name: 'Bob Johnson', age: 35 },
+  { id: 3, name: 'Martin Sam', age: 35 }
+]
+```
+
+In this example, the data is first sorted by age in ascending order. For entries with the same age, it then sorts by name in ascending order.
+
+## Sorting Nested Fields
+
+You can sort by nested fields using dot notation:
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  { id: 1, name: 'John', scores: { math: 85, science: 92 } },
+  { id: 2, name: 'Jane', scores: { math: 90, science: 88 } },
+  { id: 3, name: 'Bob', scores: { math: 78, science: 95 } }
+]
+
+const result = query(data, {
+  sort: { key: 'scores.math', dir: 'desc' }
+})
+```
+
+This will sort the data based on the math scores in descending order.

docs/features/sorting.md

@@ -0,0 +1,55 @@
+# Array Length Match Mode
+
+The 'arrayLength' match mode checks the length of an array field against a specified value.
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  { id: 1, name: 'John', skills: ['JavaScript', 'TypeScript', 'React'] },
+  { id: 2, name: 'Jane', skills: ['Python', 'Django'] },
+  { id: 3, name: 'Bob', skills: ['Java', 'Spring', 'Hibernate', 'SQL'] }
+]
+
+const result = query(data, {
+  filter: [
+    { key: 'skills', matchMode: 'arrayLength', value: 3 }
+  ]
+})
+```
+
+Output:
+```ts twoslash
+[
+  { id: 1, name: 'John', skills: ['JavaScript', 'TypeScript', 'React'] }
+]
+```
+
+This filter returns all items where the 'skills' array has exactly 3 elements.
+
+You can also use comparison operators with 'arrayLength':
+
+```ts twoslash
+import { query } from '@chronicstone/array-query'
+
+const data = [
+  { id: 1, name: 'John', skills: ['JavaScript', 'TypeScript', 'React'] },
+  { id: 2, name: 'Jane', skills: ['Python', 'Django'] },
+  { id: 3, name: 'Bob', skills: ['Java', 'Spring', 'Hibernate', 'SQL'] }
+]
+
+const result = query(data, {
+  filter: [
+    { key: 'skills', matchMode: 'arrayLength', value: 2 }
+  ]
+})
+```
+
+Output:
+```ts twoslash
+[
+  { id: 2, name: 'Jane', skills: ['Python', 'Django'] },
+]
+```
+
+This filter returns all items where the 'skills' array has more than 2 elements.