feat: allow to keep channels in certain matching paginators and not in other matching paginators

MartinCupela · MartinCupela · commit aeaa92d9d552 · 2025-11-18T15:27:17.000+01:00
diff --git a/src/ChannelPaginatorsOrchestrator.ts b/src/ChannelPaginatorsOrchestrator.ts
@@ -22,6 +22,52 @@ type EventHandlerContext = ChannelPaginatorsOrchestratorEventHandlerContext;
 
 type SupportedEventType = EventTypes | (string & {});
 
+/**
+ * Resolves which paginators should be the "owners" of a channel
+ * when the channel matches multiple paginator filters.
+ *
+ * Return a set of paginator ids that should keep/own the item.
+ * Returning an empty set means the channel will be removed everywhere.
+ */
+export type PaginatorOwnershipResolver = (args: {
+  channel: Channel;
+  matchingPaginators: ChannelPaginator[];
+}) => string[];
+
+/**
+ * Convenience factory for a priority-based ownership resolver.
+ * - Provide an ordered list of paginator ids from highest to lowest priority.
+ * - If two or more paginators match a channel, the one with the highest priority wins.
+ * - If none of the matching paginator ids are in the priority list, all matches are kept (back-compat).
+ */
+export const createPriorityOwnershipResolver = (
+  priority?: string[],
+): PaginatorOwnershipResolver => {
+  if (!priority) {
+    return ({ matchingPaginators }) => matchingPaginators.map((p) => p.id);
+  }
+  const rank = new Map<string, number>(priority.map((id, index) => [id, index]));
+  return ({ matchingPaginators }) => {
+    if (matchingPaginators.length <= 1) {
+      return matchingPaginators.map((p) => p.id);
+    }
+    // The winner is the first item in the sorted array of matching paginators
+    const winner = [...matchingPaginators].sort((a, b) => {
+      const rankA = rank.get(a.id);
+      const rankB = rank.get(b.id);
+      const valueA = rankA === undefined ? Number.POSITIVE_INFINITY : rankA;
+      const valueB = rankB === undefined ? Number.POSITIVE_INFINITY : rankB;
+      return valueA - valueB;
+    })[0];
+    const winnerValue = rank.get(winner.id);
+    // If no explicit priority is set for any, keep all (preserve current behavior)
+    if (winnerValue === undefined) {
+      return matchingPaginators.map((p) => p.id);
+    }
+    return [winner.id];
+  };
+};
+
 const getCachedChannelFromEvent = (
   event: Event,
   cache: Record<string, Channel>,
@@ -101,25 +147,41 @@ const updateLists: EventHandlerPipelineHandler<EventHandlerContext> = async ({
 
   if (!channel) return;
 
+  const matchingPaginators = orchestrator.paginators.filter((p) =>
+    p.matchesFilter(channel),
+  );
+  const matchingIds = new Set(matchingPaginators.map((p) => p.id));
+
+  const ownerIds = orchestrator.resolveOwnership(channel, matchingPaginators);
+
   orchestrator.paginators.forEach((paginator) => {
-    if (paginator.matchesFilter(channel)) {
-      const channelBoost = paginator.getBoost(channel.cid);
-      if (
-        [
-          'message.new',
-          'notification.message_new',
-          'notification.added_to_channel',
-          'channel.visible',
-        ].includes(event.type) &&
-        (!channelBoost || channelBoost.seq < paginator.maxBoostSeq)
-      ) {
-        paginator.boost(channel.cid, { seq: paginator.maxBoostSeq + 1 });
-      }
-      paginator.ingestItem(channel);
-    } else {
+    if (!matchingIds.has(paginator.id)) {
       // remove if it does not match the filter anymore
       paginator.removeItem({ item: channel });
+      return;
+    }
+
+    // Only if owners are specified, the items is removed from the non-owner matching paginators
+    if (ownerIds.size > 0 && !ownerIds.has(paginator.id)) {
+      // matched, but not selected to own - remove to enforce exclusivity
+      paginator.removeItem({ item: channel });
+      return;
+    }
+
+    // Selected owner: optionally boost then ingest
+    const channelBoost = paginator.getBoost(channel.cid);
+    if (
+      [
+        'message.new',
+        'notification.message_new',
+        'notification.added_to_channel',
+        'channel.visible',
+      ].includes(event.type) &&
+      (!channelBoost || channelBoost.seq < paginator.maxBoostSeq)
+    ) {
+      paginator.boost(channel.cid, { seq: paginator.maxBoostSeq + 1 });
     }
+    paginator.ingestItem(channel);
   });
 };
 
@@ -215,6 +277,13 @@ export type ChannelPaginatorsOrchestratorOptions = {
   client: StreamChat;
   paginators?: ChannelPaginator[];
   eventHandlers?: ChannelPaginatorsOrchestratorEventHandlers;
+  /**
+   * Decide which paginator(s) should own a channel when multiple match.
+   * Defaults to keeping the channel in all matching paginators.
+   * Channels are kept only in the paginators that are listed in the ownershipResolver array.
+   * Empty ownershipResolver array means that the channel is kept in all matching paginators.
+   */
+  ownershipResolver?: PaginatorOwnershipResolver | string[];
 };
 
 export class ChannelPaginatorsOrchestrator extends WithSubscriptions {
@@ -224,6 +293,7 @@ export class ChannelPaginatorsOrchestrator extends WithSubscriptions {
     SupportedEventType,
     EventHandlerPipeline<EventHandlerContext>
   >();
+  protected ownershipResolver?: PaginatorOwnershipResolver;
 
   protected static readonly defaultEventHandlers: ChannelPaginatorsOrchestratorEventHandlers =
     {
@@ -244,10 +314,17 @@ export class ChannelPaginatorsOrchestrator extends WithSubscriptions {
     client,
     eventHandlers,
     paginators,
+    ownershipResolver,
   }: ChannelPaginatorsOrchestratorOptions) {
     super();
     this.client = client;
     this.state = new StateStore({ paginators: paginators ?? [] });
+    if (ownershipResolver) {
+      this.ownershipResolver = Array.isArray(ownershipResolver)
+        ? createPriorityOwnershipResolver(ownershipResolver)
+        : ownershipResolver;
+    }
+
     const finalEventHandlers =
       eventHandlers ?? ChannelPaginatorsOrchestrator.getDefaultHandlers();
     for (const [type, handlers] of Object.entries(finalEventHandlers)) {
@@ -281,6 +358,17 @@ export class ChannelPaginatorsOrchestrator extends WithSubscriptions {
     return out;
   }
 
+  /**
+   * Which paginators should own the channel among the ones that matched.
+   * Default behavior keeps the channel in all matching paginators.
+   */
+  resolveOwnership(
+    channel: Channel,
+    matchingPaginators: ChannelPaginator[],
+  ): Set<string> {
+    return new Set(this.ownershipResolver?.({ channel, matchingPaginators }) ?? []);
+  }
+
   getPaginatorById(id: string) {
     return this.paginators.find((p) => p.id === id);
   }
diff --git a/test/unit/ChannelPaginatorsOrchestrator.test.ts b/test/unit/ChannelPaginatorsOrchestrator.test.ts
@@ -6,7 +6,10 @@ import {
   EventTypes,
   type StreamChat,
 } from '../../src';
-import { ChannelPaginatorsOrchestrator } from '../../src/ChannelPaginatorsOrchestrator';
+import {
+  ChannelPaginatorsOrchestrator,
+  createPriorityOwnershipResolver,
+} from '../../src/ChannelPaginatorsOrchestrator';
 vi.mock('../../src/pagination/utility.queryChannel', async () => {
   return {
     getChannel: vi.fn(async ({ client, id, type }) => {
@@ -24,6 +27,146 @@ describe('ChannelPaginatorsOrchestrator', () => {
     vi.clearAllMocks();
   });
 
+  describe('ownershipResolver', () => {
+    it('keeps channel in all matching paginators by default', async () => {
+      const ch = makeChannel('messaging:100');
+      client.activeChannels[ch.cid] = ch;
+
+      const p1 = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const p2 = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+
+      const orchestrator = new ChannelPaginatorsOrchestrator({
+        client,
+        paginators: [p1, p2],
+      });
+      orchestrator.registerSubscriptions();
+
+      client.dispatchEvent({ type: 'message.new', cid: ch.cid });
+      await vi.waitFor(() => {
+        expect(orchestrator.getPaginatorById(p1.id)).toStrictEqual(p1);
+        expect(orchestrator.getPaginatorById(p2.id)).toStrictEqual(p2);
+        expect(p1.items).toHaveLength(1);
+        expect(p1.items![0]).toStrictEqual(ch);
+        expect(p2.items).toHaveLength(1);
+        expect(p2.items![0]).toStrictEqual(ch);
+      });
+    });
+
+    it('keeps channel only in highest-priority matching paginator when resolver provided', async () => {
+      const pHigh = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const pLow = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const orchestrator = new ChannelPaginatorsOrchestrator({
+        client,
+        paginators: [pLow, pHigh],
+        ownershipResolver: createPriorityOwnershipResolver([pHigh.id, pLow.id]),
+      });
+
+      const ch = makeChannel('messaging:101');
+      client.activeChannels[ch.cid] = ch;
+
+      orchestrator.registerSubscriptions();
+      client.dispatchEvent({ type: 'message.new', cid: ch.cid });
+
+      await vi.waitFor(() => {
+        expect(pHigh.items).toHaveLength(1);
+        expect(pHigh.items![0]).toStrictEqual(ch);
+        expect(pLow.items).toBeUndefined();
+      });
+    });
+
+    it('keeps item in all priority ownership paginators when resolver returns multiple ids', async () => {
+      const pHigh = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const pLow = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const orchestrator = new ChannelPaginatorsOrchestrator({
+        client,
+        paginators: [pLow, pHigh],
+        ownershipResolver: () => [pHigh.id, pLow.id],
+      });
+
+      const ch = makeChannel('messaging:101');
+      client.activeChannels[ch.cid] = ch;
+
+      orchestrator.registerSubscriptions();
+      client.dispatchEvent({ type: 'message.new', cid: ch.cid });
+
+      await vi.waitFor(() => {
+        expect(pHigh.items).toHaveLength(1);
+        expect(pHigh.items![0]).toStrictEqual(ch);
+        expect(pLow.items).toHaveLength(1);
+        expect(pLow.items![0]).toStrictEqual(ch);
+      });
+    });
+
+    it('accepts ownershipResolver as array of ids and applies priority', async () => {
+      const pLow = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const pHigh = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const orchestrator = new ChannelPaginatorsOrchestrator({
+        client,
+        paginators: [pLow, pHigh],
+        ownershipResolver: [pHigh.id, pLow.id],
+      });
+
+      const ch = makeChannel('messaging:102');
+      client.activeChannels[ch.cid] = ch;
+
+      orchestrator.registerSubscriptions();
+      client.dispatchEvent({ type: 'message.new', cid: ch.cid });
+
+      await vi.waitFor(() => {
+        expect(pHigh.items).toHaveLength(1);
+        expect(pHigh.items![0]).toStrictEqual(ch);
+        expect(pLow.items).toBeUndefined();
+      });
+    });
+
+    it('keeps items only in owner paginators if some matching paginators are not listed in ownershipResolver array', async () => {
+      const pLow = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const pHigh = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const orchestrator = new ChannelPaginatorsOrchestrator({
+        client,
+        paginators: [pLow, pHigh],
+        ownershipResolver: [pHigh.id],
+      });
+
+      const ch = makeChannel('messaging:102');
+      client.activeChannels[ch.cid] = ch;
+
+      orchestrator.registerSubscriptions();
+      client.dispatchEvent({ type: 'message.new', cid: ch.cid });
+
+      await vi.waitFor(() => {
+        expect(pHigh.items).toHaveLength(1);
+        expect(pHigh.items![0]).toStrictEqual(ch);
+        expect(pLow.items).toBeUndefined();
+      });
+    });
+
+    it('keeps items only in matching paginators if owner paginators are not matching', async () => {
+      const p1 = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const p2 = new ChannelPaginator({ client, filters: { type: 'messaging' } });
+      const p3 = new ChannelPaginator({ client, filters: { type: 'messagingX' } });
+      const orchestrator = new ChannelPaginatorsOrchestrator({
+        client,
+        paginators: [p1, p2, p3],
+        ownershipResolver: [p3.id],
+      });
+
+      const ch = makeChannel('messaging:102');
+      client.activeChannels[ch.cid] = ch;
+
+      orchestrator.registerSubscriptions();
+      client.dispatchEvent({ type: 'message.new', cid: ch.cid });
+
+      await vi.waitFor(() => {
+        expect(p1.items).toHaveLength(1);
+        expect(p1.items![0]).toStrictEqual(ch);
+        expect(p2.items).toHaveLength(1);
+        expect(p2.items![0]).toStrictEqual(ch);
+        expect(p3.items).toBeUndefined();
+      });
+    });
+  });
+
   describe('constructor', () => {
     it('initiates with default options', () => {
       // @ts-expect-error accessing protected property
@@ -381,7 +524,10 @@ describe('ChannelPaginatorsOrchestrator', () => {
   // Helper to create a minimal channel with needed state
   function makeChannel(cid: string) {
     const [type, id] = cid.split(':');
-    return client.channel(type, id);
+    const channel = client.channel(type, id);
+    channel.data!.type = type;
+    channel.data!.id = id;
+    return channel;
   }
 
   describe.each(['channel.deleted', 'channel.hidden'] as EventTypes[])(
