feat: Support enhanced chat retention options (#111)

* feat: Support enhanced chat retention options

* chore: add changeset for v0.1.4

Author: aaronleopold

.changeset/amber-waves-flow.md

@@ -0,0 +1,6 @@
+---
+'@dittolive/ditto-chat-core': patch
+'@dittolive/ditto-chat-ui': patch
+---
+
+Enhanced message retention capabilities with support for indefinite retention and flexible configuration at global, room, and query levels. Updated Room interface to use RetentionConfig type with retainIndefinitely flag and optional days field. UI components now support passing retention configuration overrides.

sdks/js/ditto-chat-core/src/index.ts

@@ -4,6 +4,7 @@ export * from './types/ChatUser'
 export * from './types/Message'
 export * from './types/MessageWithUser'
 export * from './types/RBAC'
+export * from './types/Retention'
 export * from './types/Room'
 export * from './useChat'
 export { getChatStore, resetChatStore } from './useChat'

sdks/js/ditto-chat-core/src/slices/useMessages.ts

@@ -10,6 +10,7 @@ import { v4 as uuidv4 } from 'uuid'
 import ChatUser from '../types/ChatUser'
 import Message, { Mention, Reaction } from '../types/Message'
 import MessageWithUser from '../types/MessageWithUser'
+import type { RetentionConfig } from '../types/Retention'
 import Room from '../types/Room'
 import { ChatStore, CreateSlice } from '../useChat'
 
@@ -18,15 +19,15 @@ export interface MessageSlice {
   messageObserversByRoom: Record<string, StoreObserver | null>
   messageSubscriptionsByRoom: Record<string, SyncSubscription | null>
   messagesLoading: boolean
-  messagesPublisher: (room: Room, retentionDays?: number) => Promise<void>
+  messagesPublisher: (room: Room, retention?: RetentionConfig) => Promise<void>
   /**
    * Subscribe to messages for a specific room on-demand.
    * Used for generated rooms (comment rooms) that need dynamic subscriptions.
    */
   subscribeToRoomMessages: (
     roomId: string,
     messagesId: string,
-    retentionDays?: number,
+    retention?: RetentionConfig,
   ) => Promise<void>
   /**
    * Unsubscribe from messages for a specific room.
@@ -94,7 +95,7 @@ export const createMessageSlice: CreateSlice<MessageSlice> = (
     ditto,
     userId,
     userCollectionKey,
-    retentionDays: globalRetentionDays,
+    retention: globalRetention,
     notificationHandler,
   },
 ) => {
@@ -407,9 +408,9 @@ export const createMessageSlice: CreateSlice<MessageSlice> = (
      * 5. Triggers notifications for new messages from other users
      *
      * @param room - Room to subscribe to messages for
-     * @param retentionDays - Optional override for message retention period
+     * @param retention - Optional override for message retention configuration
      */
-    async messagesPublisher(room: Room, retentionDays?: number) {
+    async messagesPublisher(room: Room, retention?: RetentionConfig) {
       if (!ditto) {
         return
       }
@@ -419,22 +420,40 @@ export const createMessageSlice: CreateSlice<MessageSlice> = (
         return
       }
 
-      const effectiveRetentionDays =
-        retentionDays ??
-        room.retentionDays ??
-        globalRetentionDays ??
-        DEFAULT_RETENTION_DAYS
-
-      const retentionDate = new Date(
-        Date.now() - effectiveRetentionDays * 24 * 60 * 60 * 1000,
-      )
-      const query = `SELECT * FROM COLLECTION ${room.messagesId} (thumbnailImageToken ATTACHMENT, largeImageToken ATTACHMENT, fileAttachmentToken ATTACHMENT)
-        WHERE roomId = :roomId AND createdOn >= :date AND isArchived = false
-        ORDER BY createdOn ASC`
-
-      const args = {
-        roomId: room._id,
-        date: retentionDate.toISOString(),
+      // Check if retention should be indefinite (priority: param > room > global)
+      const retainIndefinitely =
+        retention?.retainIndefinitely ??
+        room.retention?.retainIndefinitely ??
+        globalRetention?.retainIndefinitely ??
+        false
+
+      let query: string
+      let args: Record<string, string>
+
+      if (retainIndefinitely) {
+        query = `SELECT * FROM COLLECTION ${room.messagesId} (thumbnailImageToken ATTACHMENT, largeImageToken ATTACHMENT, fileAttachmentToken ATTACHMENT)
+          WHERE roomId = :roomId AND isArchived = false
+          ORDER BY createdOn ASC`
+        args = {
+          roomId: room._id,
+        }
+      } else {
+        const effectiveRetentionDays =
+          retention?.days ??
+          room.retention?.days ??
+          globalRetention?.days ??
+          DEFAULT_RETENTION_DAYS
+
+        const retentionDate = new Date(
+          Date.now() - effectiveRetentionDays * 24 * 60 * 60 * 1000,
+        )
+        query = `SELECT * FROM COLLECTION ${room.messagesId} (thumbnailImageToken ATTACHMENT, largeImageToken ATTACHMENT, fileAttachmentToken ATTACHMENT)
+          WHERE roomId = :roomId AND createdOn >= :date AND isArchived = false
+          ORDER BY createdOn ASC`
+        args = {
+          roomId: room._id,
+          date: retentionDate.toISOString(),
+        }
       }
 
       try {
@@ -501,12 +520,12 @@ export const createMessageSlice: CreateSlice<MessageSlice> = (
      *
      * @param roomId - Room ID to subscribe to
      * @param messagesId - Collection ID for messages ("messages" or "dm_messages")
-     * @param retentionDays - Optional message retention override
+     * @param retention - Optional message retention configuration override
      */
     async subscribeToRoomMessages(
       roomId: string,
       messagesId: string,
-      retentionDays?: number,
+      retention?: RetentionConfig,
     ) {
       if (!ditto) {
         return
@@ -517,20 +536,38 @@ export const createMessageSlice: CreateSlice<MessageSlice> = (
         return
       }
 
-      const effectiveRetentionDays =
-        retentionDays ?? globalRetentionDays ?? DEFAULT_RETENTION_DAYS
-
-      const retentionDate = new Date(
-        Date.now() - effectiveRetentionDays * 24 * 60 * 60 * 1000,
-      )
-
-      const query = `SELECT * FROM COLLECTION ${messagesId} (thumbnailImageToken ATTACHMENT, largeImageToken ATTACHMENT, fileAttachmentToken ATTACHMENT)
-        WHERE roomId = :roomId AND createdOn >= :date AND isArchived = false
-        ORDER BY createdOn ASC`
+      // Check if retention should be indefinite (priority: param > global)
+      const retainIndefinitely =
+        retention?.retainIndefinitely ??
+        globalRetention?.retainIndefinitely ??
+        false
+
+      let query: string
+      let args: Record<string, string>
+
+      if (retainIndefinitely) {
+        // Build query without date filter for indefinite retention
+        query = `SELECT * FROM COLLECTION ${messagesId} (thumbnailImageToken ATTACHMENT, largeImageToken ATTACHMENT, fileAttachmentToken ATTACHMENT)
+          WHERE roomId = :roomId AND isArchived = false
+          ORDER BY createdOn ASC`
+        args = {
+          roomId,
+        }
+      } else {
+        // Extract days with priority: param > global > default (30)
+        const effectiveRetentionDays =
+          retention?.days ?? globalRetention?.days ?? DEFAULT_RETENTION_DAYS
 
-      const args = {
-        roomId,
-        date: retentionDate.toISOString(),
+        const retentionDate = new Date(
+          Date.now() - effectiveRetentionDays * 24 * 60 * 60 * 1000,
+        )
+        query = `SELECT * FROM COLLECTION ${messagesId} (thumbnailImageToken ATTACHMENT, largeImageToken ATTACHMENT, fileAttachmentToken ATTACHMENT)
+          WHERE roomId = :roomId AND createdOn >= :date AND isArchived = false
+          ORDER BY createdOn ASC`
+        args = {
+          roomId,
+          date: retentionDate.toISOString(),
+        }
       }
 
       try {

sdks/js/ditto-chat-core/src/slices/useRooms.ts

@@ -9,11 +9,12 @@ import { v4 as uuidv4 } from 'uuid'
 import { StoreApi } from 'zustand'
 
 import ChatUser from '../types/ChatUser'
+import type { RetentionConfig } from '../types/Retention'
 import Room from '../types/Room'
 import { ChatStore, CreateSlice, DittoConfParams } from '../useChat'
 
 export interface CreateRoomOptions {
-  retentionDays?: number
+  retention?: RetentionConfig
   isGenerated?: boolean
 }
 
@@ -112,7 +113,7 @@ function handleRoomsObserverResult(
  * @param params.collectionId - Collection to store the room ("rooms" or "dm_rooms")
  * @param params.messagesId - Collection for the room's messages ("messages" or "dm_messages")
  * @param params.participants - Optional array of user IDs (required for DM rooms)
- * @param params.retentionDays - Optional custom retention period for messages
+ * @param params.retention - Optional custom retention configuration for messages
  * @param params.isGenerated - Optional flag marking room as generated (hidden from main list)
  * @param params.id - Optional custom room ID (defaults to UUID)
  * @returns The created room object, or undefined if creation fails
@@ -124,7 +125,7 @@ async function createRoomBase({
   collectionId,
   messagesId,
   participants = [],
-  retentionDays,
+  retention,
   isGenerated = false,
   id,
 }: {
@@ -134,7 +135,7 @@ async function createRoomBase({
   collectionId: 'rooms' | 'dm_rooms'
   messagesId: 'messages' | 'dm_messages'
   participants?: string[]
-  retentionDays?: number
+  retention?: RetentionConfig
   isGenerated?: boolean
   id?: string
 }) {
@@ -154,7 +155,7 @@ async function createRoomBase({
       createdBy: currentUserId,
       createdOn: new Date().toISOString(),
       participants: participants || undefined,
-      ...(retentionDays !== undefined && { retentionDays }),
+      ...(retention !== undefined && { retention }),
     }
 
     const query = `INSERT INTO \`${collectionId}\` DOCUMENTS (:newDoc) ON ID CONFLICT DO UPDATE`
@@ -201,7 +202,7 @@ export const createRoomSlice: CreateSlice<RoomSlice> = (
      *    - Delegates to createRoomBase with appropriate parameters
      *    - Sets collectionId to "rooms" for regular rooms
      *    - Sets messagesId to "messages" collection
-     *    - Passes through optional retentionDays parameter
+     *    - Passes through optional retention configuration
      *
      * This approach ensures:
      * - RBAC integration prevents unauthorized room creation
@@ -210,7 +211,7 @@ export const createRoomSlice: CreateSlice<RoomSlice> = (
      *
      * @param name - Display name for the new room
      * @param options - Optional configuration for the room
-     * @param options.retentionDays - Optional custom message retention period (overrides global default)
+     * @param options.retention - Optional custom message retention configuration (overrides global default)
      * @param options.isGenerated - Optional flag to mark room as generated (hidden from main list)
      * @returns Promise resolving to the created Room object, or undefined if permission denied
      */
@@ -228,7 +229,7 @@ export const createRoomSlice: CreateSlice<RoomSlice> = (
         name,
         collectionId: 'rooms',
         messagesId: 'messages',
-        retentionDays: options?.retentionDays,
+        retention: options?.retention,
         isGenerated: options?.isGenerated ?? false,
       })
     },

sdks/js/ditto-chat-core/src/types/Retention.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration for message retention policies.
+ *
+ * Retention policies control how long messages are kept in chat rooms.
+ * You can configure retention at three levels:
+ * 1. Global level (via DittoConfParams)
+ * 2. Per-room level (via Room.retention)
+ * 3. Per-query level (via parameter overrides)
+ *
+ * Priority order: query parameter > room config > global config > default (30 days)
+ */
+export type RetentionConfig = {
+  /**
+   * If true, messages are retained indefinitely (no time-based eviction).
+   * When set to true, the `days` field is ignored.
+   */
+  retainIndefinitely: boolean
+
+  /**
+   * Number of days to retain messages.
+   * Only used when `retainIndefinitely` is false.
+   * If not specified, defaults to 30 days.
+   */
+  days?: number
+} | null | undefined

sdks/js/ditto-chat-core/src/types/Room.ts

@@ -1,3 +1,5 @@
+import type { RetentionConfig } from './Retention'
+
 interface Room {
   _id: string
   name: string
@@ -7,7 +9,7 @@ interface Room {
   createdOn: string
   isGenerated: boolean
   participants?: string[]
-  retentionDays?: number
+  retention?: RetentionConfig
 }
 
 export default Room

sdks/js/ditto-chat-core/src/useChat.ts

@@ -18,12 +18,13 @@ import {
 import { createRBACSlice, RBACSlice } from './slices/useRBAC'
 import { createRoomSlice, RoomSlice } from './slices/useRooms'
 import { RBACConfig } from './types/RBAC'
+import type { RetentionConfig } from './types/Retention'
 
 export type DittoConfParams = {
   ditto: Ditto | null
   userId: string
   userCollectionKey: string
-  retentionDays?: number
+  retention?: RetentionConfig
   rbacConfig?: RBACConfig
   notificationHandler?: (title: string, description: string) => void
 }

sdks/js/ditto-chat-core/tests/useMessages.test.ts

@@ -967,8 +967,10 @@ describe('useMessages Slice', () => {
       expect(messages[0].message.text).toBe('Incoming!')
     })
 
-    it('uses custom retention days', async () => {
-      await store.getState().messagesPublisher(mockRoom, 7)
+    it('uses custom retention config', async () => {
+      await store
+        .getState()
+        .messagesPublisher(mockRoom, { retainIndefinitely: false, days: 7 })
 
       expect(mockDitto.sync.registerSubscription).toHaveBeenCalledWith(
         expect.stringContaining(
@@ -981,8 +983,11 @@ describe('useMessages Slice', () => {
       )
     })
 
-    it('uses room retention days', async () => {
-      const roomWithRetention = { ...mockRoom, retentionDays: 14 }
+    it('uses room retention configuration', async () => {
+      const roomWithRetention = {
+        ...mockRoom,
+        retention: { retainIndefinitely: false, days: 14 },
+      }
       mockDitto.store.execute.mockResolvedValueOnce({
         items: [{ value: roomWithRetention }],
       })
@@ -991,6 +996,44 @@ describe('useMessages Slice', () => {
       expect(mockDitto.sync.registerSubscription).toHaveBeenCalled()
     })
 
+    it('supports indefinite retention with retainIndefinitely flag', async () => {
+      mockDitto.sync.registerSubscription.mockClear()
+
+      const roomWithIndefiniteRetention = {
+        ...mockRoom,
+        retention: { retainIndefinitely: true },
+      }
+
+      await store.getState().messagesPublisher(roomWithIndefiniteRetention)
+
+      const calls = mockDitto.sync.registerSubscription.mock.calls
+      const query = calls[calls.length - 1][0]
+      expect(query).not.toContain('createdOn >=')
+      expect(query).toContain('WHERE roomId = :roomId AND isArchived = false')
+    })
+
+    it('supports parameter override for indefinite retention', async () => {
+      mockDitto.sync.registerSubscription.mockClear()
+
+      await store
+        .getState()
+        .messagesPublisher(mockRoom, { retainIndefinitely: true })
+
+      const calls = mockDitto.sync.registerSubscription.mock.calls
+      const query = calls[calls.length - 1][0]
+      expect(query).not.toContain('createdOn >=')
+    })
+
+    it('defaults to 30 days when no retention config provided', async () => {
+      mockDitto.sync.registerSubscription.mockClear()
+
+      await store.getState().messagesPublisher(mockRoom)
+
+      const calls = mockDitto.sync.registerSubscription.mock.calls
+      const query = calls[calls.length - 1][0]
+      expect(query).toContain('createdOn >= :date')
+    })
+
     it('does not create duplicate subscription', async () => {
       mockDitto.sync.registerSubscription.mockClear()