Server: Collections

Collections let you define and expose dynamic groups of records. These groups update automatically when underlying records change, and clients receive diffs of added or removed members.

This is ideal for collaborative apps, dashboards, filtered views, and pagination.

Expose collections

To make a collection subscribable, use exposeCollection(...):

server.exposeCollection("collection:all-tasks", async () => {
  return await server.listRecordsMatching("task:*");
});

listRecordsMatching is a function that takes a Redis glob pattern, and an optional callback (more on that below), and returns the records that match the pattern. For example:

await server.writeRecord("task:1", { taskid: 1 });
await server.writeRecord("task:2", { taskid: 2 });
await server.writeRecord("task:3", { taskid: 3 });
 
const records = await server.listRecordsMatching("task:*");
 
console.log(records);

The above would log:

[
  { taskid: 1, id: 'task:1' },
  { taskid: 2, id: 'task:2' },
  { taskid: 3, id: 'task:3' }
]

The second argument is a resolver that must return an array of records (not just IDs) for the given collection. The resolver runs:

• Immediately when a client subscribes
• Again any time a record changes (added, removed, or updated)

Collections can use dynamic patterns too:

server.exposeCollection(
  /^collection:user:(\d+):tasks$/,
  async (conn: Connection, collectionId: string) => {
    const userId = collectionId.split(":")[2];
    return await server.listRecordsMatching(`user:${userId}:task:*`);
  }
);

Pagination example

You can implement pagination by encoding page numbers in collection names, and making use of the slice, sort, and map options:

server.exposeCollection(
  /^tasks:page:\d+$/,
  async (conn: Connection, collectionId: string) => {
    const pageNum = parseInt(collectionId.split(":")[2]);
    const pageSize = 10;
 
    return await server.listRecordsMatching("task:*", {
      // Transform records for the client (optional - exclude heavy fields)
      map: (record) => ({
        id: record.id,
        title: record.title,
        status: record.status,
        created_at: record.created_at
      }),
 
      // Sort by created_at descending (newest first)
      sort: (a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime(),
 
      // Paginate based on extracted page number
      slice: {
        start: (pageNum - 1) * pageSize,
        count: pageSize
      },
    });
  }
);

Client-side pagination:

Client-side pagination works by subscribing to a single page at a time:

// Subscribe to page 1
await client.subscribeCollection("tasks:page:1", {
  onDiff: ({ added, removed, changed }) => {
    //
  }
});
 
// Unsubscribe from page 1, then subscribe to page 2
await client.unsubscribeCollection("tasks:page:1");
await client.subscribeCollection("tasks:page:2");

Per-connection isolation

The resolver runs for each subscribed connection individually, which enables:

• Connection-specific authorization - each user sees only what they should
• Different views of the same collection - based on user permissions/context
• Proper isolation - each connection maintains its own version and state

server.exposeCollection("collection:user-tasks", async (conn: Connection, collectionId: string) => {
  // Each connection gets its own resolver call
  const userId = conn.metadata?.userId;
  const userRole = conn.metadata?.role;
 
  if (userRole === 'admin') {
    // Admins see all tasks
    return await server.listRecordsMatching("task:*");
  } else {
    // Regular users see only their own tasks
    return await server.listRecordsMatching(`user:${userId}:task:*`);
  }
});

Record changes trigger diffs

Whenever a record is added, removed, or updated, Mesh will:

1. Rerun the resolver for each subscribed connection
2. Compare new and old record IDs for each connection
3. Send a diff to clients where membership changed

Diff format:

• added: Array of full record objects that were added to the collection
• removed: Array of full record objects that were removed from the collection
• changed: Array of full record objects that were changed in the collection

Resync logic

Mesh tracks a version number per collection per connection, starting at version 1. If a client receives a diff with a skipped version (e.g. expected v3, got v5), it auto-resubscribes and fetches the full list again.

This ensures correctness across reconnects, network drops, or inter-instance propagation delays.

Flexible attribute-based filtering

You can expose collections that allow clients to filter records by arbitrary attributes, using a pattern that encodes the filter as part of the collection name. This is useful for building flexible search, filter, or view features.

For example, to let clients subscribe to filtered lists of products:

server.exposeCollection(
  /^collection:products:filter:.+$/,
  async (conn: Connection, collectionId: string) => {
    const [, , , encodedQuery] = collectionId.split(":");
    const filters = JSON.parse(decodeURIComponent(encodedQuery));
    const products = await server.listRecordsMatching("product:*");
 
    return products.filter(product =>
      Object.entries(filters).every(([key, value]) => product[key] === value)
    );
  }
);

On the client, you encode your filter as a JSON object, then subscribe to the filtered collection:

const query = encodeURIComponent(JSON.stringify({ category: "books", inStock: true }));
client.subscribeCollection(`collection:products:filter:${query}`);

This pattern is flexible and can be extended to support multi-field filters, value arrays, partial matching, and more. For example, you could filter by { brand: "Acme", priceRange: [10, 50] } or any other combination of product attributes.

Use cases

• Task lists: real-time filters across shared boards
• Projects: dynamic membership as records are created/deleted
• Views: multi-tenant views per user, team, or org
• Pagination: sort and slice large datasets into pages