@foony/chat 0.2.0 → 0.3.0

package/src/messages.ts

@@ -10,24 +10,136 @@
 import type { Channel, MessageFrame, UnsubscribeFn } from '@foony/realtime';
 import { MESSAGE_EVENT, PAYLOAD_VERSION, type MessagePayload } from './protocol.js';
 import { MessageReconciler } from './reconciler.js';
+import type { ChatStorage } from './storage.js';
 import type { ChatMessageEvent, Message, MessagePage, SendMessageParams, UpdateMessageParams } from './types.js';
 import { newMessageId } from './util.js';
 
 /** Listener invoked for every materialized message change on the room. */
 export type MessageListener = (event: ChatMessageEvent) => void;
 
+/**
+ * How many stored frames a room keeps. Matches a deep scrollback page: anything older is
+ * re-fetchable through `history()` and not worth the disk.
+ */
+const PERSIST_MAX_FRAMES = 300;
+
+/** Delay between an applied frame and the storage write, so bursts save once. */
+const PERSIST_DEBOUNCE_MS = 300;
+
+/** Page size fetched when a stored resume cursor has aged out of retention. */
+const RECOVER_PAGE_LIMIT = 100;
+
+/** Default history page size, matching the server's default. */
+const DEFAULT_HISTORY_LIMIT = 100;
+
 /** The message feature of a {@link Room}. */
 export class Messages {
   private readonly reconciler: MessageReconciler;
   private readonly listeners = new Set<MessageListener>();
   private channelUnsubscribe: UnsubscribeFn | null = null;
 
+  /** Resolves once the stored snapshot (if any) has been replayed and the resume cursor seeded. */
+  private readonly ready: Promise<void>;
+  /** Frames worth persisting (those with a seq), oldest-first after each normalize. */
+  private frameLog: MessageFrame[] = [];
+  /** True when older messages remain on the server below the stored window. */
+  private storedHasMore = false;
+  /** The seeded resume serial, until the first attach reports whether it held. */
+  private seededSerial = 0;
+  private channelStateOff: UnsubscribeFn | null = null;
+  private persistTimer: ReturnType<typeof setTimeout> | null = null;
+  private pendingSubscribe = false;
+
   constructor(
     private readonly channel: Channel,
     private readonly roomName: string,
     private readonly getClientId: () => string | null,
+    private readonly storage: ChatStorage | null = null,
   ) {
     this.reconciler = new MessageReconciler(roomName);
+    this.ready = this.storage ? this.restore() : Promise.resolve();
+  }
+
+  /**
+   * Replay the stored snapshot into the reconciler and seed the channel's resume cursor, so the
+   * first attach replays only the gap. Runs before the first channel subscribe (see
+   * `ensureChannelSubscription`), because a seed after attach is a no-op.
+   */
+  private async restore(): Promise<void> {
+    let state = null;
+    try {
+      state = await this.storage!.load(this.roomName);
+    } catch {
+      return;
+    }
+    if (!state || state.frames.length === 0) {
+      return;
+    }
+    for (const frame of state.frames) {
+      if (frame.name === MESSAGE_EVENT) {
+        this.reconciler.apply(frame);
+      }
+      if (frame.seq !== undefined && frame.seq > 0) {
+        this.frameLog.push(frame);
+      }
+    }
+    this.storedHasMore = state.hasMore;
+    if (state.serial > 0) {
+      this.seededSerial = state.serial;
+      this.channel.resumeFrom(state.serial);
+      this.channelStateOff = this.channel.on((change) => this.onChannelState(change));
+    }
+  }
+
+  /**
+   * The seeded cursor is judged by the first attach: `resumed: false` means the serial aged out
+   * of retention, so the stored copy may be missing messages and is thrown away.
+   */
+  private onChannelState(change: { readonly current: string; readonly resumed: boolean }): void {
+    if (change.current !== 'attached' || this.seededSerial === 0) {
+      return;
+    }
+    this.seededSerial = 0;
+    this.channelStateOff?.();
+    this.channelStateOff = null;
+    if (!change.resumed) {
+      void this.recoverFromLostCursor();
+    }
+  }
+
+  /**
+   * The stored window could not be stitched to the live stream, so drop it and fetch a fresh
+   * page, emitting the result to subscribers like live traffic (their render already happened
+   * from the stale copy).
+   */
+  private async recoverFromLostCursor(): Promise<void> {
+    try {
+      await this.storage!.remove(this.roomName);
+    } catch {
+      // Best effort: a failed remove leaves a stale copy that the next failed resume retries.
+    }
+    this.frameLog = [];
+    this.storedHasMore = true;
+    try {
+      const { messages: frames, more } = await this.channel.history({ limit: RECOVER_PAGE_LIMIT });
+      this.storedHasMore = more;
+      for (const frame of frames) {
+        this.addToFrameLog(frame);
+        if (frame.name !== MESSAGE_EVENT) {
+          continue;
+        }
+        const event = this.reconciler.apply(frame);
+        if (event === null) {
+          continue;
+        }
+        for (const listener of [...this.listeners]) {
+          listener(event);
+        }
+      }
+      this.schedulePersist();
+    } catch {
+      // The room still works live; the next history() call backfills.
+    }
   }
 
   /** Send a new message. Returns the message optimistically; its `id` is stable. */
@@ -98,12 +210,22 @@ export class Messages {
    * `nextCursor`) to page further back.
    */
   async history(params?: { limit?: number; cursor?: number }): Promise<MessagePage> {
+    if (this.storage) {
+      await this.ready;
+      if (params?.cursor === undefined) {
+        const stored = this.storedPage(params?.limit ?? DEFAULT_HISTORY_LIMIT);
+        if (stored) {
+          return stored;
+        }
+      }
+    }
     const { messages: frames, more } = await this.channel.history({
       ...(params?.limit === undefined ? {} : { limit: params.limit }),
       ...(params?.cursor === undefined ? {} : { before: params.cursor }),
     });
     const touched: string[] = [];
     for (const frame of frames) {
+      this.addToFrameLog(frame);
       if (frame.name !== MESSAGE_EVENT) {
         continue;
       }
@@ -113,6 +235,7 @@ export class Messages {
         touched.push(id);
       }
     }
+    this.schedulePersist();
     const messages = touched
       .map((id) => this.reconciler.get(id))
       .filter((message): message is Message => message !== undefined);
@@ -123,20 +246,113 @@ export class Messages {
     };
   }
 
+  /**
+   * Build the newest page from the stored window, or null when the window is too small for the
+   * request (fewer frames than asked and older messages remain on the server).
+   */
+  private storedPage(limit: number): MessagePage | null {
+    this.normalizeFrameLog();
+    if (this.frameLog.length === 0 || (this.frameLog.length < limit && this.storedHasMore)) {
+      return null;
+    }
+    const window = this.frameLog.slice(-limit);
+    const touched: string[] = [];
+    for (const frame of window) {
+      const id = messageIdOf(frame);
+      if (id !== null && !touched.includes(id)) {
+        touched.push(id);
+      }
+    }
+    const messages = touched
+      .map((id) => this.reconciler.get(id))
+      .filter((message): message is Message => message !== undefined);
+    return {
+      messages,
+      hasMore: this.storedHasMore || this.frameLog.length > window.length,
+      ...(window[0]?.seq === undefined ? {} : { nextCursor: window[0].seq }),
+    };
+  }
+
   /** Lazily attach the single channel subscription that feeds the reconciler. */
   private ensureChannelSubscription(): void {
-    if (this.channelUnsubscribe) {
+    if (this.channelUnsubscribe || this.pendingSubscribe) {
       return;
     }
-    this.channelUnsubscribe = this.channel.subscribe(MESSAGE_EVENT, (frame) => {
-      const event = this.reconciler.apply(frame);
-      if (event === null) {
+    if (!this.storage) {
+      this.channelUnsubscribe = this.channel.subscribe(MESSAGE_EVENT, (frame) => this.onLiveFrame(frame));
+      return;
+    }
+    // With storage, the subscribe waits for the restore: the resume seed must be in place
+    // before the attach the subscription triggers, or the server backfills nothing.
+    this.pendingSubscribe = true;
+    void this.ready.then(() => {
+      this.pendingSubscribe = false;
+      if (this.channelUnsubscribe || this.listeners.size === 0) {
         return;
       }
+      this.channelUnsubscribe = this.channel.subscribe(MESSAGE_EVENT, (frame) => this.onLiveFrame(frame));
+    });
+  }
+
+  /** Apply one live frame, fan it out, and keep the stored window fresh. */
+  private onLiveFrame(frame: MessageFrame): void {
+    this.addToFrameLog(frame);
+    const event = this.reconciler.apply(frame);
+    if (event !== null) {
       for (const listener of [...this.listeners]) {
         listener(event);
       }
-    });
+    }
+    this.schedulePersist();
+  }
+
+  /** Track a sequenced frame for persistence. No-op without storage. */
+  private addToFrameLog(frame: MessageFrame): void {
+    if (!this.storage || frame.seq === undefined || frame.seq <= 0) {
+      return;
+    }
+    this.frameLog.push(frame);
+    if (this.frameLog.length > PERSIST_MAX_FRAMES * 2) {
+      this.normalizeFrameLog();
+    }
+  }
+
+  /** Sort, dedupe by seq, and trim the frame log to the newest window. */
+  private normalizeFrameLog(): void {
+    if (this.frameLog.length === 0) {
+      return;
+    }
+    const bySeq = new Map<number, MessageFrame>();
+    for (const frame of this.frameLog) {
+      bySeq.set(frame.seq!, frame);
+    }
+    const sorted = [...bySeq.values()].sort((left, right) => left.seq! - right.seq!);
+    if (sorted.length > PERSIST_MAX_FRAMES) {
+      this.frameLog = sorted.slice(-PERSIST_MAX_FRAMES);
+      this.storedHasMore = true;
+    } else {
+      this.frameLog = sorted;
+    }
+  }
+
+  /** Save the stored window shortly, coalescing bursts into one write. */
+  private schedulePersist(): void {
+    if (!this.storage || this.persistTimer !== null) {
+      return;
+    }
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = null;
+      this.normalizeFrameLog();
+      if (this.frameLog.length === 0) {
+        return;
+      }
+      const serial = this.frameLog[this.frameLog.length - 1]!.seq!;
+      void this.storage!
+        .save(this.roomName, { frames: [...this.frameLog], serial, hasMore: this.storedHasMore })
+        .catch(() => {
+          // Best effort: a lost save costs the next load a server history fetch, nothing more.
+        });
+    }, PERSIST_DEBOUNCE_MS);
   }
 }
 

package/src/room.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Channel, ChannelStateChange, UnsubscribeFn } from '@foony/realtime';
+import type { ChatStorage } from './storage.js';
 import { Messages } from './messages.js';
 import { Occupancy } from './occupancy.js';
 import { Presence } from './presence.js';
@@ -41,8 +42,9 @@ export class Room {
     private readonly channel: Channel,
     getClientId: () => string | null,
     options?: RoomOptions,
+    storage: ChatStorage | null = null,
   ) {
-    this.messages = new Messages(channel, name, getClientId);
+    this.messages = new Messages(channel, name, getClientId, storage);
     this.presence = new Presence(channel);
     this.typing = new Typing(channel, getClientId, options?.typing?.heartbeatThrottleMs);
     this.reactions = new Reactions(channel, getClientId);

package/src/rooms.ts

@@ -7,6 +7,7 @@
 import type { Realtime } from '@foony/realtime';
 import { roomChannelName } from './protocol.js';
 import { Room } from './room.js';
+import type { ChatStorage } from './storage.js';
 import type { RoomOptions } from './types.js';
 
 /** Factory and cache for {@link Room} instances on a {@link ChatClient}. */
@@ -16,6 +17,7 @@ export class Rooms {
   constructor(
     private readonly realtime: Realtime,
     private readonly getClientId: () => string | null,
+    private readonly storage: ChatStorage | null = null,
   ) {}
 
   /** Get (or create) the room named `name`. Stable instance per name. */
@@ -23,7 +25,7 @@ export class Rooms {
     let existing = this.byName.get(name);
     if (!existing) {
       const channel = this.realtime.channels.get(roomChannelName(name), options?.cipher ? { cipher: options.cipher } : undefined);
-      existing = new Room(name, channel, this.getClientId, options);
+      existing = new Room(name, channel, this.getClientId, options, this.storage);
       this.byName.set(name, existing);
     }
     return existing;

package/src/storage.ts

@@ -0,0 +1,80 @@
+/**
+ * Optional message persistence. A {@link ChatStorage} keeps a per-room snapshot between page
+ * loads, so a returning client renders instantly from its own copy and the server replays only
+ * what was missed (via the channel's resume cursor) instead of serving history again.
+ */
+
+import type { MessageFrame } from '@foony/realtime';
+
+/** Snapshot of one room persisted between sessions. */
+export type PersistedRoomState = {
+  /** Raw message frames, oldest-first, replayed through the reconciler on load. */
+  readonly frames: readonly MessageFrame[];
+  /** Newest stored seq, seeded as the resume cursor so the server replays only the gap. */
+  readonly serial: number;
+  /** True when older messages remained on the server below the stored window when saved. */
+  readonly hasMore: boolean;
+};
+
+/** Where room snapshots live. Implementations must tolerate concurrent tabs (last write wins). */
+export type ChatStorage = {
+  /** The stored snapshot for `room`, or null when none exists. */
+  load(room: string): Promise<PersistedRoomState | null>;
+  /** Overwrite `room`'s snapshot. */
+  save(room: string, state: PersistedRoomState): Promise<void>;
+  /** Drop `room`'s snapshot (its resume cursor aged out, or the room was released). */
+  remove(room: string): Promise<void>;
+};
+
+/** Object store holding one record per room inside the IndexedDB database. */
+const STORE = 'rooms';
+
+/**
+ * A {@link ChatStorage} backed by IndexedDB, or null where IndexedDB does not exist (Node,
+ * some webviews) so callers can pass the result straight to `new ChatClient(...)`.
+ *
+ * @example
+ * const chat = new ChatClient(realtime, { storage: indexedDbChatStorage() ?? undefined });
+ */
+export function indexedDbChatStorage(dbName = 'foony-chat'): ChatStorage | null {
+  if (typeof indexedDB === 'undefined') {
+    return null;
+  }
+  const database = openDatabase(dbName);
+  return {
+    async load(room: string): Promise<PersistedRoomState | null> {
+      const db = await database;
+      return await requestOf<PersistedRoomState | undefined>(
+        db.transaction(STORE, 'readonly').objectStore(STORE).get(room),
+      ) ?? null;
+    },
+    async save(room: string, state: PersistedRoomState): Promise<void> {
+      const db = await database;
+      await requestOf(db.transaction(STORE, 'readwrite').objectStore(STORE).put(state, room));
+    },
+    async remove(room: string): Promise<void> {
+      const db = await database;
+      await requestOf(db.transaction(STORE, 'readwrite').objectStore(STORE).delete(room));
+    },
+  };
+}
+
+/** Open (or create) the database with its single room store. */
+function openDatabase(dbName: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(dbName, 1);
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(STORE);
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('indexedDB open failed'));
+  });
+}
+
+/** Promisify one IDBRequest. */
+function requestOf<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('indexedDB request failed'));
+  });
+}