feat: Enhanced custom methods with @method decorator

- Add @method decorator for configuring custom service methods
- Support different argument signatures (not just data, params)
- Support different HTTP verbs (GET, POST, PUT, PATCH, DELETE)
- Support clean URL paths (e.g., /messages/:id/status)
- Support internal-only methods with external: false
- Add buildMethodConfig() helper for client configuration
- Add InferServiceTypes type helper for typed clients
- Update REST client to support custom method paths and verbs
- Update services and REST client documentation

The @method decorator allows custom methods to be first-class citizens
with flexible signatures, proper HTTP verb mapping, and clean URLs
instead of relying on X-Service-Method headers.

Closes #1976
Replaces #3638

Author: marshallswain

docs/v6-custom-methods-plan.md

@@ -1,7 +1,7 @@
 import { createServer } from 'node:http'
 import { TestService } from './fixture.js'
 
-import { feathers, Application, Params } from '../src/index.js'
+import { feathers, Application, Params, method } from '../src/index.js'
 import { createHandler, SseService } from '../src/http/index.js'
 import { toNodeHandler } from '../src/http/node.js'
 
@@ -107,12 +107,72 @@ export class ResponseTestService {
   }
 }
 
+export class InternalTestService {
+  async find(_params: Params) {
+    return [{ id: 1, name: 'Public' }]
+  }
+
+  @method({ args: ['data', 'params'], external: false })
+  async internalProcess(data: any, _params: Params) {
+    return { processed: data, internal: true }
+  }
+}
+
+export class CustomPathService {
+  messages: { id: string; text: string; status: string }[] = [
+    { id: '1', text: 'Hello', status: 'active' },
+    { id: '2', text: 'World', status: 'archived' }
+  ]
+
+  async find(_params: Params) {
+    return this.messages
+  }
+
+  async get(id: string, _params: Params) {
+    return this.messages.find((m) => m.id === id)
+  }
+
+  @method({ args: ['id', 'params'], http: 'GET', path: ':id/status' })
+  async status(id: string, _params: Params) {
+    const msg = this.messages.find((m) => m.id === id)
+    return { id, status: msg?.status || 'unknown' }
+  }
+
+  @method({ args: ['id', 'params'], http: 'POST', path: ':id/archive' })
+  async archive(id: string, _params: Params) {
+    const msg = this.messages.find((m) => m.id === id)
+    if (msg) {
+      msg.status = 'archived'
+    }
+    return msg
+  }
+
+  @method({ args: ['params'], http: 'GET', path: 'stats' })
+  async stats(_params: Params) {
+    return {
+      total: this.messages.length,
+      active: this.messages.filter((m) => m.status === 'active').length
+    }
+  }
+
+  @method({ args: ['id', 'data', 'params'], http: 'POST', path: ':id/update-status' })
+  async updateStatus(id: string, data: { status: string }, _params: Params) {
+    const msg = this.messages.find((m) => m.id === id)
+    if (msg) {
+      msg.status = data.status
+    }
+    return msg
+  }
+}
+
 export type TestServiceTypes = {
   todos: TestService
   uploads: UploadService
   streaming: StreamingService
   test: ResponseTestService
   sse: SseService
+  internal: InternalTestService
+  custom: CustomPathService
 }
 
 export type TestApplication = Application<TestServiceTypes>
@@ -131,6 +191,8 @@ export function getApp(): TestApplication {
   })
   app.use('test', new ResponseTestService())
   app.use('sse', new SseService())
+  app.use('internal', new InternalTestService())
+  app.use('custom', new CustomPathService())
 
   return app
 }

packages/feathers/fixtures/index.ts

@@ -155,12 +155,12 @@ export class Feathers<Services, Settings>
 
     const {
       params: colonParams,
-      data: { service, params: dataParams }
+      data: { service, params: dataParams, method, httpMethod }
     } = result
 
     const params = dataParams ? { ...dataParams, ...colonParams } : colonParams
 
-    return { service, params }
+    return { service, params, method, httpMethod }
   }
 
   protected _setup() {
@@ -277,6 +277,25 @@ export class Feathers<Services, Settings>
 
     this.routes.insert(path, routerParams)
     this.routes.insert(`${path}/:__id`, routerParams)
+
+    // Register routes for custom method paths
+    const { methodOptions } = serviceOptions
+    for (const [methodName, methodConfig] of Object.entries(methodOptions)) {
+      if (methodConfig.path && methodConfig.external !== false) {
+        // Convert :id in path to :__id for consistency with standard routes
+        const customPath = methodConfig.path.replace(/:id\b/g, ':__id')
+        const fullPath = `${path}/${customPath}`
+
+        this.routes.insert(fullPath, {
+          ...routerParams,
+          method: methodName,
+          httpMethod: methodConfig.http || 'POST'
+        })
+
+        debug(`Registered custom path \`${fullPath}\` for method \`${methodName}\``)
+      }
+    }
+
     this.services[location] = protoService
 
     // If we ran setup already, set this service up explicitly, this will not `await`

packages/feathers/src/application.ts

@@ -210,4 +210,57 @@ describe('fetch REST connector', function () {
   })
 
   clientTests(app, 'todos')
+
+  describe('custom method paths with client config', () => {
+    // Create a client with method configuration
+    const customConnection = fetchClient(fetch, {
+      baseUrl,
+      methods: {
+        custom: {
+          status: { args: ['id', 'params'], http: 'GET', path: ':id/status' },
+          stats: { args: ['params'], http: 'GET', path: 'stats' },
+          archive: { args: ['id', 'params'], http: 'POST', path: ':id/archive' },
+          updateStatus: { args: ['id', 'data', 'params'], http: 'POST', path: ':id/update-status' }
+        }
+      }
+    })
+    const customApp = feathers<TestServiceTypes>().configure(customConnection)
+    const customService = customApp.service('custom') as any
+
+    it('GET :id/status - client uses correct verb and path', async () => {
+      const result = await customService.status('1', {})
+
+      expect(result.id).toBe('1')
+      expect(result.status).toBeDefined()
+    })
+
+    it('GET stats - client calls without id', async () => {
+      const result = await customService.stats({})
+
+      expect(result).toHaveProperty('total')
+      expect(result).toHaveProperty('active')
+    })
+
+    it('POST :id/archive - client sends POST to path', async () => {
+      const result = await customService.archive('1', {})
+
+      expect(result.id).toBe('1')
+    })
+
+    it('POST :id/update-status - client sends id, data, params', async () => {
+      const result = await customService.updateStatus('1', { status: 'updated-via-client' }, {})
+
+      expect(result.id).toBe('1')
+      expect(result.status).toBe('updated-via-client')
+    })
+
+    it('falls back to header-based method when no path config', async () => {
+      // todoService doesn't have method config, so custom methods fall back
+      const todoService = customApp.service('todos') as any
+      const result = await todoService.customMethod({ text: 'Test' }, {})
+
+      expect(result.data.text).toBe('Test')
+      expect(result.method).toBe('customMethod')
+    })
+  })
 })

packages/feathers/src/client/fetch.test.ts

@@ -2,6 +2,10 @@ import { Params, Id, Query, NullableId } from '../declarations.js'
 import { BadRequest, Unavailable, convert, errors } from '../errors.js'
 import { _, stripSlashes } from '../commons.js'
 import { protectedProperties } from '../service.js'
+import type { ClientMethodConfig, ClientMethodsConfig } from '../method.js'
+
+// Re-export for backwards compatibility
+export type { ClientMethodConfig, ClientMethodsConfig }
 
 function toError(error: Error & { code: string }, status?: number) {
   if (error.code === 'ECONNREFUSED') {
@@ -21,6 +25,11 @@ interface FetchClientSettings {
   connection: typeof fetch
   stringify: (query: Query) => string
   events?: string[]
+  /**
+   * Method configuration for custom methods.
+   * Allows the client to use correct HTTP verbs and paths.
+   */
+  methods?: ClientMethodsConfig
 }
 
 export type RequestOptions = Omit<RequestInit, 'body'> & { url: string; body?: unknown }
@@ -31,13 +40,15 @@ export class FetchClient<T = any, D = Partial<T>, P extends Params = FetchClient
   connection: typeof fetch
   stringify: (query: Query) => string
   events?: string[]
+  methods?: ClientMethodsConfig
 
   constructor(settings: FetchClientSettings) {
     this.name = stripSlashes(settings.name)
     this.connection = settings.connection
     this.base = `${settings.baseUrl}/${this.name}`
     this.stringify = settings.stringify
     this.events = settings.events
+    this.methods = settings.methods
   }
 
   makeUrl(query: Query, id?: string | number | null, route?: { [key: string]: string }) {
@@ -113,7 +124,43 @@ export class FetchClient<T = any, D = Partial<T>, P extends Params = FetchClient
     return response.json()
   }
 
-  callCustomMethod(method: string, body: unknown, params: FetchClientParams) {
+  /**
+   * Makes URL for a custom method with a path pattern.
+   * Replaces :id with the id value and other placeholders with route params.
+   */
+  makeCustomUrl(path: string, query: Query, id?: string | number | null, route?: { [key: string]: string }) {
+    // Replace :id with the actual id value
+    let resolvedPath = path
+    if (id !== null && id !== undefined) {
+      resolvedPath = resolvedPath.replace(/:id\b/, encodeURIComponent(String(id)))
+    }
+
+    // Replace other route params
+    if (route) {
+      Object.keys(route).forEach((key) => {
+        resolvedPath = resolvedPath.replace(`:${key}`, route[key])
+      })
+    }
+
+    const url = `${this.base}/${resolvedPath}`
+    return url + this.getQuery(query || {})
+  }
+
+  /**
+   * Calls a custom service method.
+   * If method config is available, uses the correct HTTP verb and path.
+   * Otherwise falls back to POST with X-Service-Method header.
+   */
+  callCustomMethod(method: string, ...args: any[]) {
+    const methodConfig = this.methods?.[method]
+
+    if (methodConfig?.path) {
+      // Use configured HTTP verb and path
+      return this.callWithPath(method, methodConfig, args)
+    }
+
+    // Fall back to header-based custom method (backwards compatible)
+    const [body, params = {}] = args as [unknown, FetchClientParams]
     return this.request(
       {
         url: this.makeUrl(params?.query, null, params?.route),
@@ -127,6 +174,37 @@ export class FetchClient<T = any, D = Partial<T>, P extends Params = FetchClient
     )
   }
 
+  /**
+   * Calls a custom method using the configured path and HTTP verb.
+   */
+  protected callWithPath(_method: string, config: ClientMethodConfig, args: any[]) {
+    const { http = 'POST', path, args: argNames = ['data', 'params'] } = config
+
+    // Build argument map
+    const argMap: { id?: Id; data?: unknown; params?: FetchClientParams } = {}
+    argNames.forEach((name, index) => {
+      if (name === 'id') argMap.id = args[index]
+      else if (name === 'data') argMap.data = args[index]
+      else if (name === 'params') argMap.params = args[index] || {}
+    })
+
+    const params = argMap.params || {}
+    const url = this.makeCustomUrl(path!, params.query, argMap.id, params.route)
+
+    // Only include body for methods that support it
+    const hasBody = ['POST', 'PUT', 'PATCH'].includes(http!)
+    const body = hasBody ? argMap.data : undefined
+
+    return this.request(
+      {
+        url,
+        method: http!,
+        body
+      },
+      params
+    )
+  }
+
   async *handleEventStream(res: Response) {
     const reader = res.body.getReader()
     const decoder = new TextDecoder()
@@ -302,8 +380,9 @@ export class ProxiedFetchClient<
           !prop.startsWith('Symbol(') &&
           !protectedProperties.includes(prop)
         ) {
-          return function (data: any, params?: P) {
-            return target.callCustomMethod(prop, data, params)
+          // Pass all arguments to callCustomMethod
+          return function (...args: any[]) {
+            return target.callCustomMethod(prop, ...args)
           }
         }
 

packages/feathers/src/client/fetch.ts

@@ -1,26 +1,50 @@
 import qs from 'qs'
 import type { Application, Query } from '../declarations.js'
-import { FetchClient, ProxiedFetchClient } from './fetch.js'
+import { FetchClient, ProxiedFetchClient, ClientMethodsConfig } from './fetch.js'
 import { sseClient, SseClientOptions } from './sse.js'
 import { defaultServiceEvents } from '../service.js'
 
 export * from './fetch.js'
 export * from './types.js'
 export * from './sse.js'
 
+/**
+ * Service method configuration for the client.
+ * Maps service names to their method configurations.
+ */
+export type ServiceMethodsConfig = Record<string, ClientMethodsConfig>
+
 export type ClientOptions = {
   baseUrl?: string
   Service?: typeof FetchClient
   stringify?: (query: Query) => string
   sse?: string | SseClientOptions
+  /**
+   * Method configuration for custom methods on each service.
+   * Allows the client to use correct HTTP verbs and paths.
+   *
+   * @example
+   * ```ts
+   * const client = fetchClient(fetch, {
+   *   baseUrl: 'http://localhost:3030',
+   *   methods: {
+   *     messages: {
+   *       status: { args: ['id', 'params'], http: 'GET', path: ':id/status' },
+   *       archive: { args: ['id', 'params'], http: 'POST', path: ':id/archive' }
+   *     }
+   *   }
+   * })
+   * ```
+   */
+  methods?: ServiceMethodsConfig
 }
 
 export function fetchClient(connection: typeof fetch, options: ClientOptions = {}) {
-  const { stringify = qs.stringify, baseUrl = '', Service = ProxiedFetchClient } = options
+  const { stringify = qs.stringify, baseUrl = '', Service = ProxiedFetchClient, methods = {} } = options
   const events = options.sse ? defaultServiceEvents : undefined
   const sseOptions = typeof options.sse === 'string' ? { path: options.sse } : options.sse
   const defaultService = function (name: string) {
-    return new Service({ baseUrl, name, connection, stringify, events })
+    return new Service({ baseUrl, name, connection, stringify, events, methods: methods[name] })
   }
   const initialize = (_app: Application) => {
     const app = _app as Application & { rest: typeof fetch }