Managing API Logic Pipelines with FeathersJS Hooks

The Problem: Logic Leakage in Service Methods

In many API frameworks, the service or controller method becomes a dumping ground for every requirement associated with a request. You start with a simple database query, but quickly add JWT verification, input sanitization, permission checks, and response formatting. This results in "fat" methods where the actual data operation is buried under fifty lines of boilerplate.

When this logic is repeated across multiple services—such as ensuring a user is authenticated before accessing both /messages and /profiles—you create a maintenance burden. A change in your authentication logic requires manual updates in every single service method.

FeathersJS solves this using Hooks. Hooks are middleware-like functions that intercept service calls. By moving cross-cutting concerns into a pipeline, your service methods remain lean adapters focused solely on data persistence, while your business rules live in reusable, testable functions.

The Hook Lifecycle and State Management

FeathersJS categorizes hooks based on when they execute relative to the service method. Choosing the correct stage is essential for security and data integrity.

• Before Hooks: Execute before the service method hits the database. These are used for authentication, validating context.data, and injecting default values.
• After Hooks: Execute after the database returns a result. These are used to scrub sensitive fields (like passwords) or trigger side effects like sending emails.
• Error Hooks: Execute if any previous stage throws an exception. These allow you to map internal database errors to user-friendly API responses.

The context object is the primary vehicle for state. It contains params (request metadata), data (the payload for create/patch), and result (the data returned from the service). Any modification to context in a before hook is passed down the chain to the service method.

Implementing a Centralized Auth and Validation Pipeline

To maintain a clean architecture, define hooks as standalone functions. This allows you to compose different pipelines for different services using the same logic.

Example Implementation

The following example demonstrates a pipeline for a users service. This assumes a FeathersJS environment where the @feathersjs/authentication package is configured.

// hooks/validate-user.js
// A reusable validation hook
export const validateUser = async (context) => {
  const { data } = context;
  if (!data || !data.email || !data.email.includes('@')) {
    // Throwing an error here stops the chain and triggers the error hook
    throw new Error('A valid email address is required');
  }
  return context;
};

// services/users/users.hooks.js
import { authenticate } from '@feathersjs/authentication';
import { validateUser } from '../../hooks/validate-user';

export default {
  before: {
    // 'all' applies to find, get, create, update, patch, remove
    all: [authenticate('jwt')],
    create: [validateUser],
    update: [validateUser],
  },
  after: {
    all: [async (context) => {
      // Ensure we handle both single objects (get/create) and arrays (find)
      if (Array.isArray(context.result)) {
        context.result = context.result.map(user => {
          const { internalSecret, ...userWithoutSecret } = user;
          return userWithoutSecret;
        });
      } else if (context.result) {
        const { internalSecret, ...userWithoutSecret } = context.result;
        context.result = userWithoutSecret;
      }
      return context;
    }]
  }
};

Verification and Diagnostics

To verify the pipeline is functioning, run these checks using a client like curl or Postman. Run these against your local server (e.g., http://localhost:3030) with the necessary permissions for the executing user.

1. Auth Check: Send a POST to /users without an Authorization header. Expected: 401 Unauthorized.
2. Validation Check: Send a POST with a valid JWT but {"email": "invalid-email"}. Expected: Error response containing "A valid email address is required".
3. Data Leak Check: Send a GET request for a user. Expected: The response body should contain user details but must not contain the internalSecret field.

Trade-offs: The Complexity of "Invisible" Logic

While hooks decouple logic, they introduce a risk of "invisible flow." Because the execution sequence is defined in an array rather than a linear function, it can be difficult to trace how a piece of data was modified.

The Order Dependency Risk: If Hook A normalizes a string to lowercase and Hook B performs a case-sensitive check, swapping their order in the hooks.js array will break the application without triggering a syntax error.

Mitigation: Keep hooks single-purpose. If a hook does more than one thing (e.g., validates and authenticates), split it. If a pipeline exceeds five hooks, document the sequence explicitly in the service file to avoid debugging fatigue.

Actionable Closing

To reduce service bloat, identify one repetitive check in your codebase—such as verifying a user's role or trimming whitespace from input strings. Extract that logic into a standalone hook function and apply it to your services. This shifts your architecture from a collection of monolithic scripts to a modular, maintainable pipeline.