docs: update query builder docs

Author: farnabaz

docs/content/docs/3.utils/1.query-collection.md

@@ -26,8 +26,15 @@ const { data: page } = await useAsyncData(route.path, () => {
 
 ```ts
 function queryCollection<T extends keyof Collections>(collection: T): CollectionQueryBuilder<Collections[T]>
-```
 
+interface CollectionQueryBuilder<T> {
+  where(field: keyof T | string, operator: SQLOperator, value?: unknown): CollectionQueryBuilder<T>
+  andWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>
+  orWhere(groupFactory: QueryGroupFunction<T>): CollectionQueryBuilder<T>
+  order(field: keyof T, direction: 'ASC' | 'DESC'): CollectionQueryBuilder<T>
+  // ... other methods
+}
+```
 
 ### `queryCollection(collection: CollectionName)`
 
@@ -66,6 +73,73 @@ const { data } = await useAsyncData(route.path, () => {
 })
 ```
 
+### `where(field: keyof Collection | string, operator: SqlOperator, value?: unknown)`
+
+Add a condition to the query to filter results based on a specific field.
+
+- Parameters:
+  - `field`: The field to filter on
+  - `operator`: The SQL operator to use for comparison. Possible values include:
+    - `'='`: Equal to
+    - `'>'`: Greater than
+    - `'<'`: Less than
+    - `'<>'`: Not equal to
+    - `'in'`: In a list of values
+    - `'BETWEEN'`: Between two values
+    - `'NOT BETWEEN'`: Not between two values
+    - `'IS NULL'`: Is null
+    - `'IS NOT NULL'`: Is not null
+    - `'LIKE'`: Matches a pattern
+    - `'NOT LIKE'`: Does not match a pattern
+  - `value`: The value to compare against. The type depends on the operator used.
+
+```ts
+const route = useRoute()
+const { data } = await useAsyncData(route.path, () => {
+  return queryCollection('docs')
+    .where('date', '<', '2024-04-04')
+    .all()
+})
+```
+
+### `andWhere(groupFactory: QueryGroupFunction<Collection>)`
+
+Add an AND condition group to the query. This allows for more complex query conditions.
+
+- Parameter:
+  - `groupFactory`: A function that receives a query builder and can add multiple conditions that will be grouped together with AND
+
+```ts
+const { data } = await useAsyncData('recent-docs', () => {
+  return queryCollection('docs')
+    .where('published', '=', true)
+    .andWhere(query => {
+      query.where('date', '>', '2024-01-01')
+          .where('category', '=', 'news')
+    })
+    .all()
+})
+```
+
+### `orWhere(groupFactory: QueryGroupFunction<Collection>)`
+
+Add an OR condition group to the query. This allows for alternative conditions.
+
+- Parameter:
+  - `groupFactory`: A function that receives a query builder and can add multiple conditions that will be grouped together with OR
+
+```ts
+const { data } = await useAsyncData('featured-docs', () => {
+  return queryCollection('docs')
+    .where('published', '=', true)
+    .orWhere(query => {
+      query.where('featured', '=', true)
+          .where('priority', '>', 5)
+    })
+    .all()
+})
+```
+
 ### `order(field: keyof Collection, direction: 'ASC' | DESC)`
 
 Order the query results based on a specific field.
@@ -101,8 +175,6 @@ const { data } = await useAsyncData(route.path, () => {
 
 ### `skip(skip: number)`
 
-### `skip(skip: number)`
-
 Skip a specified number of results in the query.
 
 - Parameter:
@@ -118,38 +190,8 @@ const { data } = await useAsyncData(route.path, () => {
 })
 ```
 
-### `where(field: keyof Collection, operator: SqlOperator, value?: unkown)`
-
-Add a condition to the query to filter results based on a specific field.
-
-- Parameters:
-  - `field`: The field to filter on.
-  - `operator`: The SQL operator to use for comparison. Possible values include:
-    - `'='`: Equal to
-    - `'>'`: Greater than
-    - `'<'`: Less than
-    - `'<>'`: Not equal to
-    - `'in'`: In a list of values
-    - `'BETWEEN'`: Between two values
-    - `'NOT BETWEEN'`: Not between two values
-    - `'IS NULL'`: Is null
-    - `'IS NOT NULL'`: Is not null
-    - `'LIKE'`: Matches a pattern
-    - `'NOT LIKE'`: Does not match a pattern
-  - `value`: The value to compare against. The type depends on the operator used.
-
-```ts
-const route = useRoute()
-const { data } = await useAsyncData(route.path, () => {
-  return queryCollection('docs')
-    .where('date', '<', '2024-04-04')
-    .all()
-})
-```
-
 ### `all()`
 
-
 Execute the query and return all matching results.
 
 - Returns: A Promise that resolves to an array of all matching documents.
@@ -161,10 +203,8 @@ const { data } = await useAsyncData(route.path, () => {
 })
 ```
 
-
 ### `first()`
 
-
 Execute the query and return the first matching result.
 
 - Returns: A Promise that resolves to the first matching document, or `null` if no documents match.

docs/content/docs/3.utils/2.query-collection-navigation.md

@@ -6,18 +6,31 @@ description: 'The queryCollectionNavigation composable generates the navigation
 ## Type
 
 ```ts
-function queryCollectionNavigation<T extends keyof PageCollections>(collection: T, fields?: Array<keyof PageCollections[T]>): Promise<ContentNavigationItem[]>
+function queryCollectionNavigation<T extends keyof PageCollections>(
+  collection: T, 
+  fields?: Array<keyof PageCollections[T]>
+): ChainablePromise<T, ContentNavigationItem[]>
+
+interface ChainablePromise<T extends keyof PageCollections, R> extends Promise<R> {
+  where(field: keyof PageCollections[T] | string, operator: SQLOperator, value?: unknown): ChainablePromise<T, R>
+  andWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
+  orWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
+  order(field: keyof PageCollections[T], direction: 'ASC' | 'DESC'): ChainablePromise<T, R>
+}
 ```
 
 ## Usage
 
 Use the auto-imported `queryCollectionNavigation` to generate a navigation tree for a specific collection. This is particularly useful for creating dynamic navigation menus or sidebars based on your content structure.
 
+The function returns a chainable promise that allows you to add additional query conditions:
 
 ```vue [pages/[...slug\\].vue]
 <script setup lang="ts">
 const { data } = await useAsyncData('navigation', () => {
   return queryCollectionNavigation('docs')
+    .where('published', '==', true)
+    .order('date', 'DESC')
 })
 </script>
 ```
@@ -32,6 +45,59 @@ Generate a navigation tree for the specified collection.
   - `collection`: The key of the defined collection in `content.config.ts`.
   - `extraFields`: (Optional) An array of additional fields to include in the navigation items. (By default `title` and `path` are included in the navigation items.)
 
-- Returns: A Promise that resolves to a navigation tree structure.
+- Returns: A chainable promise that resolves to a navigation tree structure. The promise includes methods for adding query conditions:
+  - `where(field, operator, value)`: Add a WHERE condition
+  - `andWhere(groupFactory)`: Add a grouped AND condition
+  - `orWhere(groupFactory)`: Add a grouped OR condition
+  - `order(field, direction)`: Add an ORDER BY clause
 
 The navigation tree is generated based on the directory structure and ordering happens based on files [ordering](/docs/collections/types#ordering-files)
+
+## Examples
+
+Basic usage without additional query conditions:
+
+```vue [pages/[...slug].vue]
+<script setup lang="ts">
+const { data } = await useAsyncData('navigation', () => {
+  return queryCollectionNavigation('docs')
+})
+</script>
+
+<template>
+  <nav>
+    <ul v-if="data">
+      <li v-for="item in data" :key="item.path">
+        <NuxtLink :to="item.path">{{ item.title }}</NuxtLink>
+      </li>
+    </ul>
+  </nav>
+</template>
+```
+
+Example with additional query conditions and extra fields:
+
+```vue [pages/[...slug].vue]
+<script setup lang="ts">
+const { data } = await useAsyncData('navigation', () => {
+  return queryCollectionNavigation('docs', ['description', 'badge'])
+    .where('draft', '==', false)
+    .where('partial', '==', false)
+    .order('title', 'ASC')
+})
+</script>
+
+<template>
+  <nav>
+    <ul v-if="data">
+      <li v-for="item in data" :key="item.path">
+        <NuxtLink :to="item.path">
+          {{ item.title }}
+          <span v-if="item.badge" class="badge">{{ item.badge }}</span>
+        </NuxtLink>
+        <p v-if="item.description">{{ item.description }}</p>
+      </li>
+    </ul>
+  </nav>
+</template>
+```

docs/content/docs/3.utils/3.query-collection-item-surroundings.md

@@ -6,17 +6,32 @@ description: 'The queryCollectionItemSurroundings composable looks for sibling c
 ## Type
 
 ```ts
-function queryCollectionItemSurroundings<T extends keyof PageCollections>(collection: T, path: string, opts?: SurroundOptions<keyof PageCollections[T]>): Promise<ContentNavigationItem[]>
+function queryCollectionItemSurroundings<T extends keyof PageCollections>(
+  collection: T, 
+  path: string, 
+  opts?: SurroundOptions<keyof PageCollections[T]>
+): ChainablePromise<T, ContentNavigationItem[]>
+
+interface ChainablePromise<T extends keyof PageCollections, R> extends Promise<R> {
+  where(field: keyof PageCollections[T] | string, operator: SQLOperator, value?: unknown): ChainablePromise<T, R>
+  andWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
+  orWhere(groupFactory: QueryGroupFunction<PageCollections[T]>): ChainablePromise<T, R>
+  order(field: keyof PageCollections[T], direction: 'ASC' | 'DESC'): ChainablePromise<T, R>
+}
 ```
 
 ## Usage
 
 Use the auto-imported `queryCollectionItemSurroundings` to find the previous and next items relative to a specific content item in a collection. This is particularly useful for creating navigation between related content pages.
 
-```vue [pages/[...slug\\].vue]
+The function returns a chainable promise that allows you to add additional query conditions:
+
+```vue [pages/[...slug].vue]
 <script setup lang="ts">
 const { data } = await useAsyncData('surround', () => {
   return queryCollectionItemSurroundings('docs', '/foo')
+    .where('published', '==', true)
+    .order('date', 'DESC')
 })
 </script>
 ```
@@ -35,16 +50,42 @@ Find the surrounding items (previous and next) for a specific content item in a
     - `after`: (Optional) The number of items to fetch after the current item. Default is 1.
     - `fields`: (Optional) An array of additional fields to include in the surrounding items.
 
-- Returns: A Promise that resolves to an array containing the surrounding items. The array will have the following structure:
-  - `[previousItem, nextItem]` if using default options.
-  - `[...previousItems, ...nextItems]` if using custom `before` and `after` values.
+- Returns: A chainable promise that resolves to an array containing the surrounding items. The promise includes methods for adding query conditions:
+  - `where(field, operator, value)`: Add a WHERE condition
+  - `andWhere(groupFactory)`: Add a grouped AND condition
+  - `orWhere(groupFactory)`: Add a grouped OR condition
+  - `order(field, direction)`: Add an ORDER BY clause
+
+The final result will be an array with the following structure:
+  - `[previousItem, nextItem]` if using default options
+  - `[...previousItems, ...nextItems]` if using custom `before` and `after` values
 
 Each item in the array is of type `ContentNavigationItem` or `null` if there is no item in that position.
 
-## Example
+## Examples
 
-Here's an example of how to use `queryCollectionItemSurroundings` to create a simple navigation between content pages:
+Basic usage without additional query conditions:
+
+```vue [pages/[...slug].vue]
+<script setup lang="ts">
+const { data } = await useAsyncData('surround', () => {
+  return queryCollectionItemSurroundings('docs', '/foo')
+})
+</script>
+
+<template>
+  <div class="flex justify-between">
+    <NuxtLink v-if="data?.[0]" :to="data[0]._path">
+      ← {{ data[0].title }}
+    </NuxtLink>
+    <NuxtLink v-if="data?.[1]" :to="data[1]._path">
+      {{ data[1].title }} →
+    </NuxtLink>
+  </div>
+</template>
+```
 
+Example with additional query conditions:
 
 ```vue [pages/[...slug\\].vue]
 <script setup lang="ts">
@@ -54,6 +95,9 @@ const { data } = await useAsyncData('surround', () => {
     after: 1,
     fields: ['badge', 'description']
   })
+    .where('_draft', '==', false)
+    .where('_partial', '==', false)
+    .order('date', 'DESC')
 })
 </script>
 ```