Using Middleware for Dependency Injection

Inngest Functions running in the same application often need to share common clients instances such as database clients or third-party libraries.

The following is an example of adding a OpenAI client to all Inngest functions, allowing them immediate access without needing to create the client themselves.

Our custom openaiMiddleware relies on the transformInput hook to mutate the Function's context:

import { InngestMiddleware } from "inngest";
import OpenAI from 'openai';

const openaiMiddleware = new InngestMiddleware({
    name: "OpenAI Middleware",
    init() {
        const openai = new OpenAI({
            apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
        });

        return {
        onFunctionRun(ctx) {
            return {
            transformInput(ctx) {
                return {
                // Anything passed via `ctx` will be merged with the function's arguments
                ctx: {
                    openai,
                },
                };
            },
            };
        },
        };
    },
    });

Our Inngest Functions can now access the OpenAI client through the context:

inngest.createFunction(
   { name: "user-create" },
   { event: "app/user.create" },
   async ({ openai }) => {
       const chatCompletion = await openai.chat.completions.create({
           messages: [{ role: 'user', content: 'Say this is a test' }],
           model: 'gpt-3.5-turbo',
       });

       // ...
   }
);

Explore other examples in the TypeScript SDK Middleware examples page.

Advanced mutation

When middleware runs and transformInput() returns a new ctx, the types and data within that returned ctx are merged on top of the default provided by the library. This means that you can use a few tricks to overwrite data and types safely and more accurately.

For example, here we use a const assertion to infer the literal value of our foo example above.

// In middleware
transformInput() {
    return {
        ctx: {
        foo: "bar",
        } as const,
    };
}

// In a function
async ({ event, foo }) => {
    //          ^? (parameter) foo: "bar"
}

Because the returned ctx object and the default are merged together, sometimes good inferred types are overwritten by more generic types from middleware. A common example of this might be when handling event data in middleware.

To get around this, you can provide the data but omit the type by using an as type assertion. For example, here we use a type assertion to add foo and alter the event data without affecting the type.

async transformInput({ ctx }) {
    const event = await decrypt(ctx.event);

    const newCtx = {
        foo: "bar",
        event,
    };

    return {
        // Don't affect the `event` type
        ctx: newCtx as Omit<typeof newCtx, "event">,
    };
},

Ordering middleware and types

Middleware runs in the order specified when registering it (see Middleware - Lifecycle - Registering and order), which affects typing too.

When inferring a mutated input or output, the SDK will apply changes from each middleware in sequence, just as it will at runtime. This means that for two middlewares that add a foo value to input arguments, the last one to run will be what it seen both in types and at runtime.