Middlewares

The Middleware function is executed prior before each route call, whether it's a query or mutation, that utilizes the resolver associated with the middleware. The next function within the middleware determines when to proceed to the next middleware in the chain. This mechanism enables you to execute custom logic, perform validation, or modify the context before the resolver is invoked, ensuring consistent behavior and enforcing any necessary preconditions across your application's routes.

import { PtsqServer } from '@ptsq/server';
import express, { Request, Response } from 'express';
import { getUserFromJWT } from './getUserFromJWT';
import { userRouter } from './userRouter';
 
const app = express();
 
const createContext = async ({ req, res }: { req: Request; res: Response }) => {
  const user = await getUserFromJWT(req.cookies.jwt);
 
  return {
    req,
    res,
    user,
  };
};
 
const { resolver, router } = PtsqServer.init({
  ctx: createContext,
}).create();
 
const protectedResolver = resolver.use(({ ctx, next }) => {
  if (!ctx.user) throw new Error('Must be logged in!');
 
  return next({
    ...ctx,
    user: ctx.user,
  });
});
 
resolver.query({
  resolve: async ({
    ctx /* { user: User | null } */,
    input /* undefined */,
  }) => {
    return `Hello, ${ctx.user.name}`;
    // throws Error user can be null
  },
});
 
protectedResolver.query({
  resolve: async ({ ctx /* { user: User } */, input /* undefined */ }) => {
    return `Hello, ${ctx.user.name}`;
  },
});

The next function only returns the passed context. It is only for keeping the context type up to date after e.g. if condition.

Run next function before return

Running the next function before the return statement allows for the execution of subsequent middlewares before the current middleware completes. This capability is particularly useful for tasks such as measuring response times, as it ensures that the next middleware is triggered before the current one finishes processing.

Resolve function always runs as the final middleware in the chain. This ensures that the resolver logic is executed last, allowing for any necessary post-processing or finalization steps before sending the response back to the client.

const measuredResolver = resolver.use(({ ctx, next }) => {
  if (!ctx.user) throw new Error('Must be logged in!');
 
  const timeStart = performance.now();
 
  const resolverResult = next({
    ...ctx,
    user: ctx.user,
  });
 
  const time = performance.now() - timeStart;
 
  console.log('Time to resolve: ', time);
  console.log('The result of resolver is: ', resolverResult);
 
  return resolverResult;
});

Indeed, returning the resolver result is essential not only for inferring the context type but also for passing the result up the middleware chain. This approach enables the nesting of multiple middlewares, with each subsequent middleware potentially modifying the result before passing it further up the chain. This recursive passing of results ensures that each middleware has the opportunity to intercept and process the data, facilitating a flexible and extensible middleware architecture within your application.

The type of middleware response is

type MiddlewareResponse<TContext extends Context> =
  | {
      ok: true;
      data: unknown;
      ctx: TContext;
    }
  | {
      ok: false;
      error: PtsqError;
      ctx: TContext;
    };

so you have to determine if the ok property is true or false to access the data or error.

Arguments validation with middleware

You can validate part of arguments before the middleware definition, so you can access the properties in the middleware.

const protectedResolver = resolver
  .args(
    Type.Object({
      firstName: Type.String(),
    }),
  )
  .use(
    ({
      ctx /* { user: User<any> | null } */,
      input /* { firstName: string } */,
      next,
    }) => {
      if (!ctx.user || ctx.user.firstName !== input.firstName)
        throw new Error('Must be logged in with firstName match!');
 
      return next({
        ctx: {
          user: ctx.user,
        },
      });
    },
  );

Middleware pipes

If middlewares are piped, then all the middlewares run before the route call in piping order.

const protectedResolver = resolver.use(
  ({ ctx /* { user: User<any> | null } */, next }) => {
    if (!ctx.user)
      throw new PtsqError({ code: PtsqErrorCode.UNAUTHORIZED_401 });
 
    return next({
      ctx: {
        user: ctx.user,
      },
    });
  },
);
 
const adminResolver = protectedResolver.use(
  ({ ctx /* { user: User<any> } */, next }) => {
    if (ctx.user.role !== 'admin')
      throw new PtsqError({ code: PtsqErrorCode.FORBIDDEN_403 });
 
    return next({
      ctx: {
        user: ctx.user,
      },
    });
  },
);
 
const deleteOrganization = adminResolver.mutation({
  //...
  resolve: ({ ctx /* { user: User<'admin'> } */, input }) => {
    //...
  },
});

Piping the middleware with another middleware, pass the context returned from the first middleware as an input to the piped (next) middleware.

There is a demonstration of the Middleware types work.

// the mutation without any middleware
Mutation<{ user?: User | null }>;
 
// the first middleware gets the root context and checks if the user is undefined
Middleware<{ user?: User | null }, { user: User | null }>;
 
// the piped middleware gets the result context of the first middleware and checks if the user is null
Middleware<{ user: User | null }, { user: User }>;
 
// the mutation with a resolver that uses the piped middleware
Mutation<{ user: User }>;

Standalone middleware

Standalone middleware allows you to create a middleware that is out of the server.

middleware/isAuthed.ts

import { middleware } from '@ptsq/server';
 
export const isAuthed = middelware<{
  ctx: {
    user?: User;
  };
}>().create(({ ctx /* { user?: User | undefined } */, next }) => {
  if (!ctx.user) throw new PtsqError({ code: PtsqErrorCode.UNAUTHORIZED_401 });
 
  return next({
    user: ctx.user,
  });
});

As you can see we can define which context is required for the standalone middleware, then we can you the middleware as any other middleware.

ptsq.ts

const createContext = async ({ req }: { req: Request }) => {
  const user = await getUserFromJWT(req);
 
  return {
    user,
  };
};
 
export const { resolver, router, serve } = PtsqServer.init({
  ctx: createContext,
});

resolvers/isAuthed.ts

export const isAuthedResolver = resolver.use(isAuthed);

You can also define which input the standalone middleware requires

import { middleware } from '@ptsq/server';
 
export const hasPermission = middelware<{
  ctx: {
    user: User;
  };
  input: {
    roomId: string;
  };
}>(({ input /* { roomId: string } */, ctx /* { user: User } */, next }) => {
  if (!ctx.hasRoomPermissions(input.roomId, ctx.user))
    throw new PtsqError({ code: 'UNAUTHORIZED' });
 
  return next();
});

Server middlewares

You can add middleware to the resolver, which calls them when the query or mutation created by that resolver will be called.

What if you want to run middleware no matter if the route is found or the resolver type (query or mutation) is correctly set?

export const { resolver, router, serve } = PtsqServer.init()
  .use(async ({ next, meta }) => {
    console.log('request: ', meta);
 
    const response = await next();
 
    console.log('response: ', response);
 
    return response;
  })
  .create();

The middleware that the server uses in the example will be called on every request, no matter if the route was found and the resolver type was correctly set.

It is very good for logging and something like that.

Context Compilation