Composer middleware

Writing a message takes a lot of processing: mentions, commands, link previews, uploads, polls and more. No single way of doing it fits every app. So a message composer builds its processing from middleware, small handlers that run one after another in chains. You compose the pipeline your app needs by adding, reordering or replacing those handlers.

Middleware and chains

A middleware is an object with an id and a handler for each event it handles. An event is something that happens in the composer and starts processing, such as onChange when the text changes or compose when the user sends. A handler receives the state the event works on, such as the text and the cursor, and four functions. It returns the result of calling one of them:

• next(state) passes a changed state to the next middleware.
• forward() passes the state on unchanged.
• complete(state) stops the chain. The state it's given is the result.
• discard() stops the chain and drops the result. For a message, nothing is sent and MessageComposer.send() returns 'nothing-to-send'. For a text change, the change isn't applied.

The state is a value made for one run of the chain, not the composer's own state. The composer builds it when the event happens, each handler passes on a new one, and the composer uses the one the chain ends with. The text composer saves it as its new state, and the composition chain sends it as the message. A discarded result changes nothing.

The composer keeps one chain of middleware for each kind of processing: text, composition, drafts, polls and uploads, as the table below shows. Each chain lives in a middleware executor, the object that holds the middleware in order, runs them for an event, and has the methods to add, reorder or replace them. When an event happens, the executor runs the chain's handlers for that event one after another, and skips any middleware without one. Each handler receives the state the one before it passed on, and the composer uses the state the chain ends with.

A handler can be async. When the same chain starts again before an earlier run finished, for example on the next keystroke, the earlier run's result is dropped. The upload chains are the exception: they run once per file, side by side, and keep every result.

Chains in a composer

Built-in chains lists the middleware each chain starts with.

Adding middleware

Add middleware in the composer setup function. This one adds the middleware from the example at the top to every channel composer:

import type {
  MessageComposerMiddlewareState,
  MessageCompositionMiddleware,
  MiddlewareHandlerParams,
} from "stream-chat";

// Types `sent_from` in `message.custom`.
declare module "stream-chat" {
  interface CustomMessageData {
    sent_from?: string;
  }
}

const sentFromMiddleware: MessageCompositionMiddleware = {
  id: "my-app/sent-from",
  handlers: {
    compose: ({
      next,
      state,
    }: MiddlewareHandlerParams<MessageComposerMiddlewareState>) =>
      // Change both copies of the message: `message` is what the server receives,
      // `localMessage` is what the message list shows until the server answers.
      next({
        ...state,
        localMessage: {
          ...state.localMessage,
          // custom fields go under property `custom`
          custom: { ...state.localMessage.custom, sent_from: "web" },
        },
        message: {
          ...state.message,
          // custom fields go under property `custom`
          custom: { ...state.message.custom, sent_from: "web" },
        },
      }),
  },
};

// Runs for every composer, existing and created later: when the composer starts its
// subscriptions, and again when the setup function or the `messageComposer` config changes.
// There is one setup function for all composers: calling this again replaces it, so put all
// your composer setup here.
client.config.setSetupFunction("messageComposer", ({ composer }) => {
  // 'channel', 'thread' or 'message' (an edit composer).
  if (composer.contextType !== "channel") return;

  composer.compositionMiddlewareExecutor.insert({
    middleware: [sentFromMiddleware],
    // Add `sent_from` before the message is validated.
    position: {
      before: "stream-io/message-composer-middleware/data-validation",
    },
    // Removes a middleware with the same id first, so running the setup again adds no copy.
    unique: true,
  });

  // The teardown: runs before the setup runs again, and when the composer's subscriptions end.
  return () =>
    composer.compositionMiddlewareExecutor.remove(sentFromMiddleware.id);
});

Custom fields go under custom, as Data conventions explains.

To read the composer's data in a middleware, build the middleware per composer:

import type {
  MessageComposer,
  MessageComposerMiddlewareState,
  MessageCompositionMiddleware,
  MiddlewareHandlerParams,
} from "stream-chat";

// Builds one middleware for one composer, so its handler can read that composer's data.
const createSignatureMiddleware = (
  composer: MessageComposer,
): MessageCompositionMiddleware => ({
  id: "my-app/signature",
  handlers: {
    compose: ({
      forward,
      next,
      state,
    }: MiddlewareHandlerParams<MessageComposerMiddlewareState>) => {
      // Reads this composer's data: no signature on an edit, or on a message without text.
      if (composer.editedMessage || !state.message.text) return forward();

      // Add the signature to both copies of the message.
      const text = `${state.message.text}\n\nSent from the support desk`;
      return next({
        ...state,
        localMessage: { ...state.localMessage, text },
        message: { ...state.message, text },
      });
    },
  },
});

client.config.setSetupFunction("messageComposer", ({ composer }) => {
  // A middleware of its own for each composer the setup runs for.
  const signatureMiddleware = createSignatureMiddleware(composer);

  composer.compositionMiddlewareExecutor.insert({
    middleware: [signatureMiddleware],
    // After the text is added, so `state.message.text` is set.
    position: {
      after: "stream-io/message-composer-middleware/text-composition",
    },
    unique: true,
  });

  return () =>
    composer.compositionMiddlewareExecutor.remove(signatureMiddleware.id);
});

Ordering and replacing middleware

Every executor has the same methods, and a getter that reads its chain:

Two things to watch for:

• The id in position must exist. MiddlewareExecutor.insert({ middleware, position }) adds middleware next to another middleware in the chain. position names that other middleware by its id, as { after: id } or { before: id }. Use an id that's in the chain. Copy it from Built-in chains, or check MiddlewareExecutor.installedMiddleware first.
• MiddlewareExecutor.setOrder(ids) keeps only the ids you list. ids holds the ids of the chain's middleware in the order you want, and the chain is rebuilt from them. Any middleware whose id isn't in ids is removed. For example, calling setOrder() on the text chain with only the commands and mentions ids, in that order, runs commands before mentions. It also removes the pre-validation and command effects middleware. List every id, the built-in ones too.

const executor = channel.messageComposer.textComposer.middlewareExecutor;

const hasMentions = executor.installedMiddleware.some(
  ({ id }) => id === "stream-io/text-composer/mentions-middleware",
);

Messages with a poll

When a new message in a channel holds a poll, the built-in poll-only middleware sends the poll as a message of its own. It completes the chain with a message that carries only poll_id. The text, attachments and quoted message stay in the composer, ready to send as the next message. The poll-only middleware changes only a new message in a channel. When the user edits a message that has a poll, the edit keeps the poll, and the rest of the chain runs as for any message.

Wherever your composition middleware sits in the chain, it can't change the poll message:

• If it sits after the poll-only middleware, it doesn't run.
• If it sits before, what it adds is dropped, because the poll-only middleware replaces the request with one that has only poll_id.

What to do depends on what the poll message needs:

Here is an addSentFromToPollMessages function that keeps the poll-only behaviour and adds custom.sent_from to the poll message. MiddlewareExecutor.replace() puts the new middleware in the place of the built-in one, because it has the same id. Call it in the setup function from Adding middleware, and call the function it returns in that setup function's teardown:

import type { MessageComposer } from "stream-chat";
import {
  createPollOnlyCompositionMiddleware,
  POLL_ONLY_COMPOSITION_MIDDLEWARE_ID,
} from "stream-chat";

// Types `sent_from` in `message.custom`, as in Adding middleware.
declare module "stream-chat" {
  interface CustomMessageData {
    sent_from?: string;
  }
}

/** Keeps sending a poll on its own, with `sent_from`. Returns a function that undoes it. */
export const addSentFromToPollMessages = (composer: MessageComposer) => {
  const executor = composer.compositionMiddlewareExecutor;
  const pollOnly = createPollOnlyCompositionMiddleware(composer);

  executor.replace([
    {
      id: POLL_ONLY_COMPOSITION_MIDDLEWARE_ID,
      handlers: {
        compose: (params) =>
          pollOnly.handlers.compose({
            ...params,
            // The poll message carries only the poll; add the field to both copies.
            complete: (state) =>
              params.complete({
                ...state,
                localMessage: {
                  ...state.localMessage,
                  custom: { ...state.localMessage.custom, sent_from: "web" },
                },
                message: {
                  ...state.message,
                  custom: { ...state.message.custom, sent_from: "web" },
                },
              }),
          }),
      },
    },
  ]);

  return () =>
    executor.replace([createPollOnlyCompositionMiddleware(composer)]);
};

Keeping the content after a send

The configuration parameter messageComposer.retainCompositionOnSubmit lets the composer keep its content after a send. The function is invoked during MessageComposer.send() to determine whether the composer keeps its content or clears. It receives the composer and returns true to keep the content.

By default, it returns true when a new message in a channel carries a poll, while the poll-only middleware is installed. The poll goes out alone, and the text, attachments and quoted message stay for the next message.

To keep the content in other cases, you need two parts:

• Middleware of your own that leaves part of the content out of the message. The function doesn't decide what's sent; middleware does.
• The function, extended to return true for those sends, so the part your middleware left out stays in the composer.

With messageComposer.attachments.pendingUploadsEnabled on, uploads still running at the send stay in the composer and go with the next message.

Without the middleware, true keeps content that was already sent, and the user sends it again. Keep the default's case too, or a poll sent on its own empties the composer:

import { DEFAULT_COMPOSER_CONFIG, type MessageComposer } from "stream-chat";

// Your own check: whether your middleware sends only part of this composer's content.
declare const sendsPartOfTheContent: (composer: MessageComposer) => boolean;

client.config.set({
  messageComposer: {
    retainCompositionOnSubmit: (composer: MessageComposer) =>
      DEFAULT_COMPOSER_CONFIG.retainCompositionOnSubmit(composer) ||
      sendsPartOfTheContent(composer),
  },
});

Effect handlers

Some changes to the text also have to change other parts of the composer. When the user picks a command, for example, the composer takes a snapshot of its attachments, poll and other content, and empties itself. A text middleware can't make such a change while the chain runs. A later middleware may still discard the change, or the next keystroke may start a new run that replaces it. The composer would then be emptied for a change that never happened.

So a middleware doesn't make such a change itself. It adds an effect to state.effects: an object with a type, and any data its handler needs. When the chain's result is applied, the composer saves the text state, then runs the handler registered for each effect's type. A result that's discarded or replaced is never applied, so its effects never run.

When the user picks /giphy from the suggestions, for example, state.effects holds one effect:

import type { MessageComposerEffect } from "stream-chat";

const effects: MessageComposerEffect[] = [
  {
    type: "command.activate",
    // The picked command, from channel.config.availableCommands.
    command: {
      args: "[text]",
      description: "Post a random gif to the channel",
      name: "giphy",
      set: "fun_set",
    },
    // The text and cursor that command.clear puts back: empty for a picked command.
    stateToRestore: { selection: { end: 0, start: 0 }, text: "" },
  },
];

The composer keeps one handler for each effect type. After it saves the text state, it goes through state.effects in order. For each effect, it calls the handler registered for the effect's type with two arguments: the effect and the composer. An effect whose type has no handler is skipped, without an error. Handlers run one after another and aren't awaited, so an async handler's work finishes later, on its own.

The composer has two built-in effects, which make commands work:

Your own effects come from your text middleware, as below.

Use effects in a text middleware of your own when a change should also do something outside the text, such as logging a picked mention or opening a panel. Register a handler with MessageComposer.registerEffectHandler(type, handler), and add effects of that type in the middleware. Registering a handler for a built-in type replaces the built-in one.

import type {
  MiddlewareHandlerParams,
  TextComposerMiddleware,
  TextComposerMiddlewareExecutorState,
} from "stream-chat";

// An effect of your own: a `type` no other effect uses, and the data its handler needs.
type MentionPickedEffect = { type: "my-app/mention.picked"; userId: string };

const mentionEffectsMiddleware: TextComposerMiddleware = {
  id: "my-app/mention-effects",
  handlers: {
    // Nothing to do while the user types.
    onChange: ({ forward }) => forward(),
    onSuggestionItemSelect: ({
      forward,
      next,
      state,
    }: MiddlewareHandlerParams<TextComposerMiddlewareExecutorState>) => {
      // Only a suggestion picked from the `@` list is a mention.
      const selected = state.change?.selectedSuggestion;
      if (state.suggestions?.trigger !== "@" || !selected) return forward();

      // Record the effect instead of acting on the pick here: the pick may still be
      // discarded by a later middleware, or replaced by a newer run.
      const effect: MentionPickedEffect = {
        type: "my-app/mention.picked",
        userId: selected.id,
      };
      // Keep the effects earlier middleware added.
      return next({ ...state, effects: [...(state.effects ?? []), effect] });
    },
  },
};

client.config.setSetupFunction("messageComposer", ({ composer }) => {
  // The composer calls this with each effect of this type, once the pick is applied.
  // Registering the type again replaces the handler.
  composer.registerEffectHandler<MentionPickedEffect>(
    "my-app/mention.picked",
    (effect) => console.log(`Mentioned ${effect.userId}`),
  );

  // Before the mentions middleware, which completes the chain when a mention is picked.
  composer.textComposer.middlewareExecutor.insert({
    middleware: [mentionEffectsMiddleware],
    position: { before: "stream-io/text-composer/mentions-middleware" },
    unique: true,
  });

  return () =>
    composer.textComposer.middlewareExecutor.remove(
      mentionEffectsMiddleware.id,
    );
});

Pitfalls

• Change both message and localMessage. message is what the server receives, and localMessage is what the list shows until the server's copy replaces it. Change only message, and the list shows the old content until the server answers. Change only localMessage, and the change never reaches the server and disappears when its answer arrives.
• A poll is sent on its own. For a new message in a channel, the poll-only middleware sends only the poll, and your composition middleware may not run for it. Messages with a poll explains what that changes and what to do.
• Return what next, forward, complete or discard returns. A handler that returns nothing breaks the chain, and calling next twice throws.
• Don't change state in place. Spread it into a new object, as the examples do.
• One setup function per configuration key. A second client.config.setSetupFunction("messageComposer", …) replaces the first.

Built-in chains

Every composer starts with the chains below. Each table lists the middleware in the order it runs.

Composition

Drafts

Text

The four command middlewares in these chains work together. A composer that shows the command in the text, with no chip, removes all four, as A UI without a command chip shows.

Uploads

Before upload, the chain runs once per file. A discard() leaves the file out.

After upload, a discard() removes the attachment.

Polls

For poll fields, a discard() leaves the poll composer's state as it was.

For poll creation, a discard() creates no poll.

Used in

• Mentions
• Commands and Giphy
• Emoji
• Attachments and uploads
• Attachment actions