feathersjs · fratzinger · Feb 16, 2026 · Feb 16, 2026 · Feb 16, 2026 · Feb 16, 2026
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -109,10 +109,9 @@ export default defineConfig({
           .map((x) => ({
             text: x.title,
             link: x.path,
-          }))
+          })),
       },
       { text: 'Utility Types', link: '/utility-types' },
-
     ],
     nav: [
       {
@@ -161,7 +160,8 @@ export default defineConfig({
                     resolve(__dirname, `../../src/${category}/index.ts`),
                   ]
                   return acc
-                }, {} as Record<string, string[]>
+                },
+                {} as Record<string, string[]>,
               ),
             },
           },

diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -25,9 +25,9 @@ export default {
     app.component('PredicatesTable', PredicatesTable)
     app.component('TransformersTable', TransformersTable)
     app.component('GuardsTable', GuardsTable)
-    app.component("HooksTable", HooksTable)
-    app.component("UtilsTable", UtilsTable)
+    app.component('HooksTable', HooksTable)
+    app.component('UtilsTable', UtilsTable)
 
-    app.component("Chip", Chip)
+    app.component('Chip', Chip)
   },
 } satisfies Theme
diff --git a/src/hooks/create-related/create-related.hook.test.ts b/src/hooks/create-related/create-related.hook.test.ts
@@ -1,4 +1,4 @@
-import assert from 'node:assert'
+import { expect } from 'vitest'
 import { feathers } from '@feathersjs/feathers'
 import { MemoryService } from '@feathersjs/memory'
 import { createRelated } from './create-related.hook.js'
@@ -28,6 +28,127 @@
   }
 }
 
+type User = {
+  id: number
+  name: string
+}
+
+type Todo = {
+  id: number
+  title: string
+  userId: number
+}
+
+const mockAppStronglyTyped = (_options?: MockAppOptions) => {
+  const options = Object.assign({}, defaultOptions, _options)
+  const app = feathers<{
+    users: MemoryService<User>
+    todos: MemoryService<Todo>
+  }>()
+
+  app.use('users', new MemoryService<User>({ startId: 1, multi: true }))
+  app.use(
+    'todos',
+    new MemoryService<Todo>({ startId: 1, multi: options.multi }),
+  )
+
+  const usersService = app.service('users')
+  const todosService = app.service('todos')
+
+  return {
+    app,
+    todosService,
+    usersService,
+  }
+}
+
+describe('hook - createRelated (type tests)', function () {
+  it('errors on wrong service name', function () {
+    const { app } = mockAppStronglyTyped()
+
+    app.service('users').hooks({
+      after: {
+        create: [
+          createRelated({
+            // @ts-expect-error - 'nonexistent' is not a valid service name
+            service: 'nonexistent',
+            data: (item) => [{ title: 'test', userId: item.id }],
+          }),
+        ],
+      },
+    })
+  })
+
+  it('item in data function is properly typed', function () {
+    const { app } = mockAppStronglyTyped()
+
+    app.service('users').hooks({
+      after: {
+        create: [
+          createRelated({
+            service: 'todos',
+            data: (item) => {
+              const name: string = item.name
+              // @ts-expect-error - 'nonExistentProp' does not exist on User
+              const bad = item.nonExistentProp
+              return [{ title: name, userId: item.id }]
+            },
+          }),
+        ],
+      },
+    })
+  })
+
+  it('data can return a single object', function () {
+    const { app } = mockAppStronglyTyped()
+
+    app.service('users').hooks({
+      after: {
+        create: [
+          createRelated({
+            service: 'todos',
+            data: (item) => ({ title: 'test', userId: item.id }),
+          }),
+        ],
+      },
+    })
+  })
+
+  it('data can return an array', function () {
+    const { app } = mockAppStronglyTyped()
+
+    app.service('users').hooks({
+      after: {
+        create: [
+          createRelated({
+            service: 'todos',
+            data: (item) => [
+              { title: 'test1', userId: item.id },
+              { title: 'test2', userId: item.id },
+            ],
+          }),
+        ],
+      },
+    })
+  })
+
+  it('data return type must match target service', function () {
+    const { app } = mockAppStronglyTyped()
+
+    app.service('users').hooks({
+      after: {
+        create: [
+          createRelated({
+            service: 'todos',
+            // @ts-expect-error - wrong data shape for todos service
+            data: (item) => [{ wrongField: 'test' }],
+          }),
+        ],
+      },
+    })
+  })
+})
+
 describe('hook - createRelated', function () {
   it('creates single item for single item', async function () {
     const { app, todosService } = mockApp()
@@ -37,7 +158,7 @@
        create: [
          createRelated({
            service: 'todos',
            data: (item, context) => ({
              title: 'First issue',
              userId: item.id,
            }),
@@ -46,13 +167,13 @@
      },
    })

    const user = await app.service('users').create({
      name: 'John Doe',
    })
 
     const todos = await todosService.find({ query: {} })
 
-    assert.deepStrictEqual(todos, [{ id: 1, title: 'First issue', userId: 1 }])
+    expect(todos).toStrictEqual([{ id: 1, title: 'First issue', userId: 1 }])
   })
 
   it('can use context in data function', async function () {
@@ -72,13 +193,13 @@
      },
    })

    const user = await app.service('users').create({
      name: 'John Doe',
    })
 
     const todos = await todosService.find({ query: {} })
 
-    assert.deepStrictEqual(todos, [{ id: 1, title: 'users', userId: 1 }])
+    expect(todos).toStrictEqual([{ id: 1, title: 'users', userId: 1 }])
   })
 
   it('creates multiple items for multiple items', async function () {
@@ -89,7 +210,7 @@
        create: [
          createRelated({
            service: 'todos',
            data: (item, context) => ({
              title: item.name,
              userId: item.id,
            }),
@@ -98,13 +219,13 @@
      },
    })

    const users = await app
      .service('users')
      .create([{ name: 'user1' }, { name: 'user2' }, { name: 'user3' }])
 
     const todos = await todosService.find({ query: { $sort: { userId: 1 } } })
 
-    assert.deepStrictEqual(todos, [
+    expect(todos).toStrictEqual([
       { id: 1, title: 'user1', userId: 1 },
       { id: 2, title: 'user2', userId: 2 },
       { id: 3, title: 'user3', userId: 3 },
@@ -119,7 +240,7 @@
        create: [
          createRelated({
            service: 'todos',
            data: (item, context) => ({
              title: item.name,
              userId: item.id,
            }),
@@ -130,15 +251,15 @@
     })
 
     // @ts-expect-error - does not have options
-    assert.strictEqual(todosService.options.multi, false)
+    expect(todosService.options.multi).toBe(false)
 
     const users = await app
       .service('users')
       .create([{ name: 'user1' }, { name: 'user2' }, { name: 'user3' }])
 
     const todos = await todosService.find({ query: { $sort: { userId: 1 } } })
 
-    assert.deepStrictEqual(todos, [
+    expect(todos).toStrictEqual([
       { id: 1, title: 'user1', userId: 1 },
       { id: 2, title: 'user2', userId: 2 },
       { id: 3, title: 'user3', userId: 3 },
@@ -153,7 +274,7 @@
        create: [
          createRelated({
            service: 'todos',
            data: (item, context) => [
              {
                title: 1,
                userId: item.id,
@@ -174,12 +295,49 @@
 
     const todos = await todosService.find({ query: {} })
 
-    assert.deepStrictEqual(todos, [
+    expect(todos).toStrictEqual([
       { id: 1, title: 1, userId: 1 },
       { id: 2, title: 2, userId: 1 },
     ])
   })
 
+  it('creates multiple data for multiple records', async function () {
+    const { app, todosService } = mockApp()
+
+    app.service('users').hooks({
+      after: {
+        create: [
+          createRelated({
+            service: 'todos',
+            data: (item, context) => [
+              {
+                title: `${item.name}-a`,
+                userId: item.id,
+              },
+              {
+                title: `${item.name}-b`,
+                userId: item.id,
+              },
+            ],
+          }),
+        ],
+      },
+    })
+
+    const users = await app
+      .service('users')
+      .create([{ name: 'user1' }, { name: 'user2' }])
+
+    const todos = await todosService.find({ query: { $sort: { id: 1 } } })
+
+    expect(todos).toStrictEqual([
+      { id: 1, title: 'user1-a', userId: 1 },
+      { id: 2, title: 'user1-b', userId: 1 },
+      { id: 3, title: 'user2-a', userId: 2 },
+      { id: 4, title: 'user2-b', userId: 2 },
+    ])
+  })
+
   it('can pass an array', async function () {
     const { app, todosService } = mockApp()
 
@@ -216,7 +374,7 @@
 
     const todos = await todosService.find({ query: {} })
 
-    assert.deepStrictEqual(todos, [
+    expect(todos).toStrictEqual([
       { id: 1, title: 1, userId: 1 },
       { id: 2, title: 2, userId: 1 },
     ])
@@ -230,7 +388,7 @@
         create: [
           createRelated({
             service: 'todos',
-            data: (item, context) => null as any,
+            data: (item, context) => undefined,
           }),
         ],
       },
@@ -242,6 +400,6 @@
 
     const todos = await todosService.find({ query: {} })
 
-    assert.deepStrictEqual(todos, [])
+    expect(todos).toStrictEqual([])
   })
 })
diff --git a/src/hooks/create-related/create-related.hook.ts b/src/hooks/create-related/create-related.hook.ts
@@ -1,9 +1,15 @@
 import type { HookContext, NextFunction } from '@feathersjs/feathers'
 import { checkContext, getResultIsArray } from '../../utils/index.js'
 import type { MaybeArray, Promisable } from '../../internal.utils.js'
+import type { InferCreateDataSingle } from '../../utility-types/infer-service-methods.js'
+import type { ResultSingleHookContext } from '../../utility-types/hook-context.js'
 
-export interface CreateRelatedOptions<S = Record<string, any>> {
-  service: keyof S
+export interface CreateRelatedOptions<
+  H extends HookContext = HookContext,
+  Services extends H['app']['services'] = H['app']['services'],
+  S extends keyof Services = keyof Services,
+> {
+  service: S
   /**
    * Is relevant when the current context result is an array.
    *
@@ -15,8 +21,16 @@ export interface CreateRelatedOptions<S = Record<string, any>> {
   multi?: boolean
   /**
    * A function that returns the data to be created in the related service.
+   *
+   * Receives the current item from the context result and the full hook context as arguments.
+   * Can return a single data object, an array of data objects, or a promise that resolves to either.
+   *
+   * If the function returns undefined, no related record will be created for that item.
    */
-  data: (item: any, context: HookContext) => Promisable<Record<string, any>>
+  data: (
+    item: ResultSingleHookContext<H>,
+    context: H,
+  ) => Promisable<MaybeArray<InferCreateDataSingle<Services[S]>> | undefined>
 }
 
 /**
@@ -37,10 +51,9 @@ export interface CreateRelatedOptions<S = Record<string, any>> {
  *
  * @see https://utils.feathersjs.com/hooks/create-related.html
  */
-export function createRelated<
-  S = Record<string, any>,
-  H extends HookContext = HookContext,
->(options: MaybeArray<CreateRelatedOptions<S>>) {
+export function createRelated<H extends HookContext = HookContext>(
+  options: MaybeArray<CreateRelatedOptions<H>>,
+) {
   return async (context: H, next?: NextFunction) => {
     checkContext(context, ['after', 'around'], ['create'], 'createRelated')
 
@@ -58,7 +71,9 @@ export function createRelated<
 
         const dataToCreate = (
           await Promise.all(result.map(async (item) => data(item, context)))
-        ).filter((x) => !!x)
+        )
+          .flat()
+          .filter((x) => !!x)
 
         if (!dataToCreate || dataToCreate.length <= 0) {
           return context
@@ -67,11 +82,15 @@ export function createRelated<
         if (multi || dataToCreate.length === 1) {
           await context.app
             .service(service as string)
-            .create(dataToCreate.length === 1 ? dataToCreate[0] : dataToCreate)
+            .create(
+              dataToCreate.length === 1
+                ? (dataToCreate[0] as any)
+                : (dataToCreate as any),
+            )
         } else {
           await Promise.all(
             dataToCreate.map(async (item) =>
-              context.app.service(service as string).create(item),
+              context.app.service(service as string).create(item as any),
             ),
           )
         }