Skip to main content
Version: 2.0.0

Typing indicators and other short-lived signals

Prerequisites

You need a chat app. This guide builds on the one from the chat app tutorial: it uses its user and message tables, and its send_message reducer. If you don't have a chat app yet, follow the tutorial for your language first.

In this guide, you'll show who's typing in the chat, such as "Alice is typing…". Typing signals only matter for a few seconds, so you'll send them through an event table: its rows go to the clients, then the database deletes them.

How it works​

  • A public typing_event event table has one column: the sender.
  • A start_typing reducer inserts a row, with the caller as the sender. When the reducer's transaction commits, SpacetimeDB sends the row to every subscribed client, then deletes it.
  • While the user types, the client calls start_typing, at most once every 2 seconds.
  • Each client keeps a list of who is typing. A user stays in it for 3 seconds after their last signal, or until they send a message. The client shows "Alice is typing…" from that list.

You could store who's typing in a regular table instead, but then you'd have to delete each row once the user stops typing. Typing signals don't need to be stored: a client that connects later doesn't need to know who was typing a second ago. An event table is always empty between transactions, so there's nothing to clean up.

Define the event table​

Add the typing_event table, with the event flag. It's public, so every client can subscribe to it.

const typingEvent = table(
  { name: 'typing_event', public: true, event: true },
  {
    sender: t.identity(),
  }
);

const spacetimedb = schema({ user, message, typingEvent });
export default spacetimedb;

Write the reducer​

Add a start_typing reducer that inserts a row into typing_event. It sets the sender to ctx.sender, so a client can't make it look like someone else is typing.

export const startTyping = spacetimedb.reducer(ctx => {
  ctx.db.typingEvent.insert({ sender: ctx.sender });
});

Show who's typing​

On the client, subscribe to typing_event, along with user and message. The client cache never keeps the rows of an event table, so you can't read them back later: handle each signal in an onInsert callback, when it arrives.

Keep a list of who is typing, and when each of them stops showing as typing:

  • When a signal arrives, set its sender to stop showing 3 seconds from now. Skip your own signals, so you don't see yourself typing.
  • When a message arrives, remove its sender: they're done typing.
  • A few times per second, remove the users whose 3 seconds are up.

Each client uses its own clock for these deadlines, so it doesn't matter if the clocks of the clients and the database disagree. The timeout is longer than the interval between signals, so a user who keeps typing doesn't flicker on and off when a signal arrives a little late.

import type { Identity } from 'spacetimedb';
import { DbConnection, tables } from './module_bindings';

// How long a user shows as typing after their last signal.
const TYPING_TIMEOUT_MS = 3000;

// The users who are typing, by identity, with when they stop showing as typing.
const typingUntil = new Map<string, { identity: Identity; until: number }>();

const conn = DbConnection.builder()
  .withUri('ws://localhost:3000')
  .withDatabaseName('quickstart-chat')
  .onConnect(ctx => {
    ctx.subscriptionBuilder().subscribe([tables.user, tables.message, tables.typingEvent]);
  })
  .build();

conn.db.typingEvent.onInsert((_ctx, typing) => {
  if (typing.sender.isEqual(conn.identity!)) {
    return; // Don't show the user that they're typing.
  }
  typingUntil.set(typing.sender.toHexString(), {
    identity: typing.sender,
    until: Date.now() + TYPING_TIMEOUT_MS,
  });
  showTyping();
});

// A user who sends a message is done typing.
conn.db.message.onInsert((_ctx, message) => {
  if (typingUntil.delete(message.sender.toHexString())) {
    showTyping();
  }
});

// Remove the users whose last signal is too old.
setInterval(() => {
  const now = Date.now();
  let changed = false;
  for (const [key, entry] of typingUntil) {
    if (entry.until <= now) {
      typingUntil.delete(key);
      changed = true;
    }
  }
  if (changed) {
    showTyping();
  }
}, 250);

function nameOf(identity: Identity) {
  return conn.db.user.identity.find(identity)?.name ?? identity.toHexString().substring(0, 8);
}

// The line to show under the messages, such as "Alice is typing…".
function typingLine() {
  const names = Array.from(typingUntil.values(), entry => nameOf(entry.identity));
  if (names.length === 0) {
    return '';
  }
  if (names.length === 1) {
    return `${names[0]} is typing…`;
  }
  if (names.length === 2) {
    return `${names[0]} and ${names[1]} are typing…`;
  }
  return 'Several people are typing…';
}

function showTyping() {
  console.log(typingLine());
}

Signal that the user is typing​

Each time the text in the message box changes, call start_typing, but at most once every 2 seconds. Each call sends a row to every subscribed client, so don't send one per keystroke: one signal every 2 seconds is enough to keep the user showing as typing.

When the user sends their message, forget when you last signaled, so the next keystroke signals right away.

// How often the client signals that the user is typing.
const SIGNAL_INTERVAL_MS = 2000;

// When this client last signaled that the user is typing.
let lastSignal = 0;

// Call this each time the text in the message box changes.
function onMessageBoxChanged(text: string) {
  const now = Date.now();
  if (text.length === 0 || now - lastSignal < SIGNAL_INTERVAL_MS) {
    return;
  }
  lastSignal = now;
  conn.reducers.startTyping({}).catch(console.error);
}

async function sendMessage(text: string) {
  lastSignal = 0;
  try {
    await conn.reducers.sendMessage({ text });
  } catch (error) {
    console.error(`Could not send the message: ${error}`);
  }
}

Clearing the message box doesn't send anything: the other clients stop showing the user as typing 3 seconds after their last signal.

What's next?​

You now show who's typing in the chat:

  • A public event table carries the typing signals. Its rows go to the subscribed clients, and are never stored, so there's nothing to clean up.
  • A reducer sets the sender of each signal itself.
  • Clients send at most one signal every 2 seconds, and show each user as typing for 3 seconds after their last one, or until they send a message.

To adapt it to your app:

  • Chat rooms. Add a room_id column to typing_event, and a room_id argument to start_typing that it checks the caller is in. Clients then show only the signals of the room that's open. With many rooms, subscribe only to the open room's signals, with a query that filters on room_id.
  • Private signals. Event tables can't be used in views, so every client that subscribes to typing_event can receive every signal. That's fine for a chat that everyone can read, but not for a private room or a DM. For those, store who's typing in a private table, give each user the rows they may see through a view, as in Chat rooms and private DMs, and delete old rows with a scheduled reducer.
  • Stop typing right away. To hide the indicator as soon as the user clears the message box, add a typing column to typing_event, and a stop_typing reducer that inserts a row with typing set to false. Clients remove the sender when they receive it.
  • Spam. A client can call start_typing much more often than every 2 seconds. To stop that, store when each user last signaled in a private table, and ignore signals that come too soon. The usernames guide uses the same kind of cooldown for name requests.
  • Other short-lived signals. The same pattern works for anything clients only need to see as it happens: emoji reactions, "Alice joined the chat" notices, pings or sound effects. Give each kind of signal its own event table, with the columns it needs.

To learn more about the features used here, see Event Tables and Reducers.

Next, you can show each user how many messages they haven't read with unread counts and notifications.