feat: add result hooks

docs/content/3.composables/1.query-content.md

@@ -243,3 +243,40 @@ const count = await queryContent('articles')
 // Returns
 5 // number of articles
 ```
+
+## `resultHook(hook)`
+
+- `hook`
+  - Type: `(content: T) => HT`
+  - **Required**
+
+Add a hook for to be executed on the results of the content query.
+
+This hook is useful for simple transforms of returned content or validation of returned data with libraries such as `zod`.
+
+```ts
+// Some example front-matter on a content page
+const articleSchema = z.object({
+  navigation: z.object({
+    nextBtn: z.string()
+  })
+})
+
+// Validate each returned article
+const articles = await queryContent('articles')
+  .resultHook(c => articleSchema.parse(c))
+  .find()
+```
+
+You can also use `resultHook(hook)` to augment the returned content with new fields.
+
+```ts
+// Count of articles
+const articles = await queryContent('articles')
+  .resultHook(c => {
+    ...c,
+    newField: 'some-data'
+  })
+  .find()
+```
+

src/runtime/query/query.ts

@@ -28,7 +28,18 @@ export function createQuery <T = ParsedContent> (fetcher: ContentQueryFetcher<T>
     }
   }
 
+  const resultHooks: ((v: any) => any)[] = []
+
+  const resolveResultHooks = (result: any) => {
+    let res = result
+    for (const h of resultHooks) {
+      res = h(res)
+    }
+    return res
+  }
+
   const resolveResult = (result: any) => {
+    let ret = result
     if (opts.legacy) {
       if (result?.surround) {
         return result.surround
@@ -46,10 +57,18 @@ export function createQuery <T = ParsedContent> (fetcher: ContentQueryFetcher<T>
         }
       }
 
-      return result?._path || Array.isArray(result) || !Object.prototype.hasOwnProperty.call(result, 'result') ? result : result?.result
+      ret = result?._path || Array.isArray(result) || !Object.prototype.hasOwnProperty.call(result, 'result') ? result : result?.result
+    }
+
+    if (Array.isArray(ret)) {
+      return ret.map(r => resolveResultHooks(r))
+    }
+
+    if (ret?._path) {
+      return resolveResultHooks(ret)
     }
 
-    return result
+    return ret
   }
 
   const query: any = {
@@ -71,7 +90,9 @@ export function createQuery <T = ParsedContent> (fetcher: ContentQueryFetcher<T>
     // locale
     locale: (_locale: string) => query.where({ _locale }),
     withSurround: $set('surround', (surroundQuery, options) => ({ query: surroundQuery, ...options })),
-    withDirConfig: () => $set('dirConfig')(true)
+    withDirConfig: () => $set('dirConfig')(true),
+    // hooks
+    resultHook: <HT>(h: (v: any) => HT) => { resultHooks.push(h); return query as ContentQueryBuilder<HT> }
   }
 
   if (opts.legacy) {

src/runtime/types/index.d.ts

@@ -491,6 +491,11 @@ export interface QueryBuilder<T = ParsedContentMeta> {
    */
   locale(locale: string): QueryBuilder<T>
 
+  /**
+   * Add result hook to returned content
+   */
+  resultHook<HT>(hook: (content: T) => HT): QueryBuilder<HT>
+
   /**
    * Retrieve query builder params
    * @internal

test/features/query/query.test.ts

@@ -329,4 +329,17 @@ describe('Database Provider', () => {
       expect(item._deleted).toBeUndefined()
     })
   })
+
+  test('Result Hook transform return', async () => {
+    const query = createQuery(pipelineFetcher, { legacy: true })
+      .where({ id: { $in: [1, 2] } })
+      .resultHook((c) => { return { transformedPath: c._path, exampleExtraField: 'hello' } })
+    const result = await query.find()
+
+    result.forEach((item: any) => {
+      expect(Object.keys(item)).toMatchObject(['transformedPath', 'exampleExtraField'])
+      assert(item.exampleExtraField === 'hello')
+      expect(item.id).toBeUndefined()
+    })
+  })
 })