@noverachat/sdk-web 0.3.0 → 0.5.0

package/src/features/message-collection.ts

@@ -0,0 +1,561 @@
+/**
+ * 코어 소유 메시지 상태 — noverachat_dart `MessageCollection`의 TS 미러.
+ *
+ * RoomStore(sdk-react)에 있던 이벤트 반영·낙관적 전송·캐시 hydrate→교체
+ * 로직의 코어 이관본. 바인딩(React·Flutter)은 이 컬렉션을 감싸는 얇은
+ * 접착층이 되고, "캐시는 렌더 힌트, 서버가 항상 이긴다" 같은 불변식은
+ * 코어가 강제한다. diff 병합(mergeDiff)은 `applyFresh`→`mergeFresh`로
+ * 들어온다.
+ */
+
+import type {
+  DeleteScope,
+  MessageIdStr,
+  MessageOut,
+  ReactionEntry,
+  SendFileOptions,
+  WsChatReceive,
+  WsMessageDeleted,
+  WsMessagesCleared,
+  WsMessageUpdated,
+  WsReactionAdded,
+  WsReactionRemoved,
+  WsSyncTick,
+} from "../types.js";
+import type { CachePolicy } from "../cache.js";
+import type { Room } from "./room.js";
+import {
+  chatMessageFromHistory,
+  chatMessageFromLive,
+  pendingChatMessage,
+  pendingFileChatMessage,
+  type ChatMessage,
+} from "../chat-message.js";
+import { EventBus } from "../internal/event-bus.js";
+import { idGreater } from "../internal/compare-id.js";
+
+/**
+ * 컬렉션 상태가 바뀐 이유. 지금 소비자(얇은 래퍼)는 "바뀌었다"만 알면
+ * 되므로 kind만 담는다 — 세밀한 렌더 최적화가 필요해지면 필드를
+ * **추가**(비파괴)로 확장한다.
+ *
+ * - `hydrated`   캐시 스냅샷이 렌더됨 (콜드 스타트 힌트 — 곧 `replaced`가 따라온다)
+ * - `replaced`   API 응답이 스냅샷/기존 페이지를 통째로 대체함 (서버가 이겼다)
+ * - `inserted`   메시지가 추가됨 (라이브 수신·낙관적 버블·스크롤백 페이지)
+ * - `updated`    기존 메시지가 제자리 갱신됨 (수정·삭제 플래그·리액션·ack 플립)
+ * - `watermarks` 읽음 워터마크가 전진함
+ */
+export type CollectionChangeKind =
+  | "hydrated"
+  | "replaced"
+  | "inserted"
+  | "updated"
+  | "watermarks";
+
+/** `MessageCollection`의 `change` 이벤트로 흐르는 변경 통지. */
+export interface CollectionChange {
+  kind: CollectionChangeKind;
+}
+
+interface CollectionEvents {
+  change: CollectionChange;
+}
+
+let uploadSeq = 0;
+
+/**
+ * A `Room`'s message list as owned, live state — the core-side equivalent
+ * of Sendbird's `MessageCollection` (without a local DB).
+ *
+ * Applies the room's events into one `messages` list, drives optimistic
+ * sends, and runs the snapshot-cache contract (`load()` hydrates from cache
+ * instantly, then wholesale-replaces when the API answers). Subscribe with
+ * `on("change", ...)` and re-render `messages` on every event — all state
+ * mutations and change emits are synchronous with the WS dispatch.
+ *
+ * ```ts
+ * const col = chat.room("room_123").collection();
+ * const unsub = col.on("change", () => render(col.messages));
+ * await col.load();
+ * col.send("hello");
+ * col.markRead(col.messages.at(-1)!.id);
+ * // ...
+ * col.dispose(); unsub();
+ * ```
+ */
+export class MessageCollection {
+  private readonly bus = new EventBus<CollectionEvents>();
+  private readonly unsubs: Array<() => void> = [];
+
+  private _messages: ChatMessage[] = [];
+  private _readWatermarks: Record<string, string> = {};
+  private _hasMore = false;
+  private oldestCursor: string | null = null;
+  private loadingMore = false;
+
+  /**
+   * 캐시 스냅샷으로 렌더된 머리쪽 메시지 수 — API 도착 시 이만큼 걷어내고
+   * 통째 교체한다(replaceByApi). 라이브 수신은 리스트 꼬리에 붙으므로
+   * 머리 range 제거로 스냅샷만 정확히 걷힌다.
+   */
+  private hydratedCount = 0;
+
+  constructor(
+    /** The room this collection is bound to. */
+    public readonly room: Room,
+    private readonly policy: CachePolicy = "replaceByApi",
+  ) {
+    this.unsubs.push(
+      room.on("message", (f) => this.onIncoming(f)),
+      room.on("messageUpdated", (f) => this.onUpdated(f)),
+      room.on("messageDeleted", (f) => this.onDeleted(f)),
+      room.on("messagesCleared", (f) => this.onCleared(f)),
+      room.on("reactionAdded", (f) => this.onReactionAdded(f)),
+      room.on("reactionRemoved", (f) => this.onReactionRemoved(f)),
+      room.on("syncTick", (f) => this.onSyncTick(f)),
+    );
+  }
+
+  /** The current messages, oldest first. Treat as read-only. */
+  get messages(): readonly ChatMessage[] {
+    return this._messages;
+  }
+
+  /** True when older history remains — fire `loadMore()` from the top of
+   *  the scroll view. */
+  get hasMore(): boolean {
+    return this._hasMore;
+  }
+
+  /** Per-user read watermarks (`userId` → last read `messageId`), kept live
+   *  from `sync_tick` frames. Treat as read-only. */
+  get readWatermarks(): Readonly<Record<string, string>> {
+    return this._readWatermarks;
+  }
+
+  /** State-change notifications. One event per mutation; re-read `messages`
+   *  (and friends) when it fires. Returns an unsubscribe fn. */
+  on(event: "change", fn: (c: CollectionChange) => void): () => void {
+    return this.bus.on(event, fn);
+  }
+
+  /** Whether `userId` has read `messageId` according to the latest watermark. */
+  isReadBy(userId: string, messageId: string): boolean {
+    const w = this._readWatermarks[userId];
+    if (!w) return false;
+    return !idGreater(messageId, w);
+  }
+
+  /** How many of the given users have read `messageId`. Pass the room's
+   *  member ids (minus the sender) to get a KakaoTalk-style unread count:
+   *  `members.length - readCount(...)`. */
+  readCount(messageId: string, userIds: Iterable<string>): number {
+    let n = 0;
+    for (const u of userIds) if (this.isReadBy(u, messageId)) n++;
+    return n;
+  }
+
+  // ── loading — cache hydrate → API wholesale replace ─────────────
+
+  /**
+   * Load the most recent page of history.
+   *
+   * `ClientOptions.cacheStore`가 주입돼 있으면 캐시 스냅샷을 먼저 렌더한
+   * 뒤(`hydrated`), API 응답 도착 시 스냅샷을 걷어내고 통째로 교체한다
+   * (`replaced`). 스냅샷 렌더 중에는 `hasMore`/스크롤백을 열지 않는다 —
+   * 커서는 API 응답의 것만 신뢰한다.
+   */
+  async load(limit = 50): Promise<void> {
+    const pending = this.room.listRecent(limit); // API를 먼저 띄우고
+    await this.hydrateFromCache(); //               기다리는 동안 캐시를 그린다
+    const page = await pending;
+    this.applyFresh(page);
+  }
+
+  /** Scrollback: load the page of messages older than what's on screen and
+   *  prepend it. No-op while a previous call is in flight or when `hasMore`
+   *  is false. Returns the number of messages added. */
+  async loadMore(limit = 50): Promise<number> {
+    const cursor = this.oldestCursor;
+    if (this.loadingMore || !this._hasMore || cursor == null) return 0;
+    this.loadingMore = true;
+    try {
+      const page = await this.room.listBefore(cursor, limit);
+      this._messages.unshift(...page.items.map(chatMessageFromHistory));
+      this.oldestCursor = page.nextCursor;
+      this._hasMore = page.hasMore;
+      this.emit("inserted");
+      return page.items.length;
+    } finally {
+      this.loadingMore = false;
+    }
+  }
+
+  /** 캐시 스냅샷 즉시 렌더 — 빈 리스트일 때만. 실패는 조용히 무시(캐시는
+   *  힌트일 뿐). */
+  private async hydrateFromCache(): Promise<void> {
+    if (this._messages.length > 0 || this.hydratedCount > 0) return;
+    const cached = await this.room.cachedRecent();
+    if (!cached || cached.items.length === 0 || this._messages.length > 0) {
+      return;
+    }
+    this._messages.unshift(...cached.items.map(chatMessageFromHistory));
+    this.hydratedCount = cached.items.length;
+    this.emit("hydrated");
+  }
+
+  /**
+   * API 최신 페이지를 컬렉션에 반영한다.
+   * replaceByApi(기본)는 스냅샷을 걷어내고 통째 교체하고, mergeDiff는
+   * 스냅샷의 옛 메시지를 보존·병합한다(`mergeFresh`).
+   */
+  private applyFresh(page: {
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+    historyFrom?: number | null;
+  }): void {
+    if (this.policy === "mergeDiff" && this.hydratedCount > 0) {
+      this.mergeFresh(page);
+      return;
+    }
+    if (this.hydratedCount > 0) {
+      this._messages.splice(0, this.hydratedCount); // 스냅샷 통째 폐기 → 서버가 이긴다
+      this.hydratedCount = 0;
+    }
+    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    this.oldestCursor = page.nextCursor;
+    this._hasMore = page.hasMore;
+    this.emit("replaced");
+  }
+
+  /**
+   * diff 병합 — 스냅샷의 옛 메시지를 보존해 fresh 페이지 아래에 잇는다.
+   *
+   * 판정 규칙(서버 계약, 07-23 확정):
+   * - **컷오프분**: `history_from`(히스토리 하한, unix ms)보다 오래된 캐시
+   *   메시지는 재입장 컷/대화 지우기로 볼 수 없게 된 것 → 폐기.
+   * - **삭제분**: fresh 커버 구간(id ≥ fresh 최저 id)에 있는데 fresh에
+   *   없는 캐시 메시지는 그 사이 삭제된 것(타이머 만료 포함) → 폐기.
+   * - **갭 폴백**: 캐시의 최신 메시지가 fresh와 겹치지 않으면 누락 구간이
+   *   있을 수 있으므로 병합하지 않고 통째 교체.
+   *
+   * 겹치는 구간은 항상 fresh가 정답(수정 반영) — 보존되는 건 fresh 범위
+   * **밖**의 옛 메시지뿐이라 "서버가 항상 이긴다" 불변식은 유지된다.
+   */
+  private mergeFresh(page: {
+    items: MessageOut[];
+    nextCursor: MessageIdStr | null;
+    hasMore: boolean;
+    historyFrom?: number | null;
+  }): void {
+    const cachedHead = this._messages.slice(0, this.hydratedCount);
+    this._messages.splice(0, this.hydratedCount);
+    this.hydratedCount = 0;
+
+    const freshIds = new Set(page.items.map((m) => m.messageId));
+    const freshOldest = page.items.length > 0 ? page.items[0]!.messageId : null;
+    const hf = page.historyFrom ?? null;
+
+    // 갭 폴백: 캐시 최신이 fresh에 없으면 연속성 보장 불가 → 통째 교체.
+    // fresh가 방 전체(hasMore=false)인데 범위 밖 캐시가 남는 경우도 유령이므로 교체.
+    const overlaps =
+      cachedHead.length > 0 &&
+      freshOldest != null &&
+      freshIds.has(cachedHead.at(-1)!.id);
+    let preserved: ChatMessage[] = [];
+    if (overlaps && page.hasMore) {
+      preserved = cachedHead.filter((m) => {
+        if (freshIds.has(m.id)) return false; // 겹침 → fresh가 대체
+        if (!idGreater(freshOldest, m.id)) return false; // fresh 구간 내 부재 → 삭제분
+        if (hf != null && m.createdAtMs != null && m.createdAtMs < hf) {
+          return false; // 컷오프분
+        }
+        return true;
+      });
+    }
+
+    this._messages.unshift(...page.items.map(chatMessageFromHistory));
+    this._messages.unshift(...preserved);
+    // 보존분이 있으면 스크롤백 커서를 보존분의 최저 id로 — 중복 로드 방지.
+    this.oldestCursor =
+      preserved.length > 0 ? preserved[0]!.id : page.nextCursor;
+    this._hasMore = page.hasMore;
+    this.emit("replaced");
+  }
+
+  // ── optimistic sends ────────────────────────────────────────────
+
+  /**
+   * Send `text` optimistically: a `sending` bubble appears immediately (one
+   * microtask later — `Room.send` is async), then flips to `sent` (with the
+   * real id) on ack, or `failed` on error. Fire-and-forget: a WS-not-open
+   * failure surfaces as a `failed` bubble rather than a rejected promise.
+   */
+  send(
+    text: string,
+    opts?: {
+      replyToId?: string;
+      customType?: string;
+      customMeta?: Record<string, unknown>;
+    },
+  ): void {
+    void (async () => {
+      let tempId: string;
+      let ackPromise: Promise<string>;
+      try {
+        const sent = await this.room.send({
+          content: text,
+          ...(opts?.replyToId ? { replyToId: opts.replyToId } : {}),
+          ...(opts?.customType ? { customType: opts.customType } : {}),
+          ...(opts?.customMeta ? { customMeta: opts.customMeta } : {}),
+        });
+        tempId = sent.tempId;
+        ackPromise = sent.messageId;
+      } catch {
+        // WS not open — surface a failed bubble rather than throwing into
+        // the void (send() is fire-and-forget).
+        const localId = `failed_${Date.now()}_${uploadSeq++}`;
+        this._messages.push({
+          ...pendingChatMessage({ tempId: localId, content: text, ...opts }),
+          status: "failed",
+        });
+        this.emit("inserted");
+        return;
+      }
+      this._messages.push(pendingChatMessage({ tempId, content: text, ...opts }));
+      this.emit("inserted");
+      this.bindAck(tempId, ackPromise);
+    })();
+  }
+
+  /** Send a file optimistically. A FILE bubble with `uploadProgress`
+   *  appears immediately; progress advances during the S3 upload, then the
+   *  bubble flips to `sent` on ack (or `failed`). Never throws — failures
+   *  surface as the bubble's status. */
+  async sendFile(file: File, opts?: SendFileOptions): Promise<void> {
+    // Local temp id for the optimistic bubble — the real WS temp id only
+    // exists after the upload commits (sendFile resolves then).
+    const localId = `upload_${Date.now()}_${uploadSeq++}`;
+    this._messages.push(
+      pendingFileChatMessage({
+        tempId: localId,
+        name: opts?.name ?? file.name,
+        mime: file.type,
+        size: file.size,
+      }),
+    );
+    this.emit("inserted");
+
+    try {
+      const sent = await this.room.sendFile(file, {
+        ...(opts ?? {}),
+        onProgress: (p) => {
+          this.mutateByTempId(localId, (m) => ({
+            ...m,
+            uploadProgress: p.ratio,
+          }));
+          opts?.onProgress?.(p);
+        },
+      });
+      // Upload committed — bind the bubble to the real file id and ack.
+      this.mutateByTempId(localId, (m) => ({
+        ...m,
+        fileId: sent.fileId,
+        file: m.file ? { ...m.file, id: sent.fileId } : m.file,
+        uploadProgress: null,
+      }));
+      const realId = await sent.messageId;
+      this.mutateByTempId(localId, (m) => ({
+        ...m,
+        id: realId,
+        status: "sent",
+      }));
+    } catch {
+      this.mutateByTempId(localId, (m) => ({
+        ...m,
+        status: "failed",
+        uploadProgress: null,
+      }));
+    }
+  }
+
+  /** Edit a message's content (server-side; peers get `message_updated`).
+   *  The local copy updates optimistically. */
+  async edit(messageId: string, content: string): Promise<void> {
+    await this.room.edit(messageId, { content });
+    this.mutateById(messageId, (m) => ({
+      ...m,
+      content,
+      editedCount: m.editedCount + 1,
+    }));
+  }
+
+  /** Delete a message. `scope: "ALL"` (default) removes it for everyone;
+   *  `"MY"` hides it only for the caller. Local copy flips to deleted. */
+  async delete(messageId: string, scope: DeleteScope = "ALL"): Promise<void> {
+    await this.room.delete(messageId, scope);
+    this.mutateById(messageId, (m) => ({ ...m, isDeleted: true }));
+  }
+
+  /** Add/remove the caller's reaction. Pass `myUserId` so the toggle can
+   *  tell whether the caller already reacted with `key`. The authoritative
+   *  state arrives back via the reaction WS events. */
+  async toggleReaction(
+    messageId: string,
+    key: string,
+    myUserId: string,
+  ): Promise<void> {
+    const m = this._messages.find((x) => x.id === messageId);
+    const mine =
+      m?.reactions.some(
+        (r) => r.key === key && r.userIds.includes(myUserId),
+      ) ?? false;
+    if (mine) {
+      await this.room.unreact(messageId, key);
+    } else {
+      await this.room.react(messageId, key);
+    }
+  }
+
+  /** Mark `messageId` read (debounced inside the SDK). */
+  markRead(messageId: string): void {
+    this.room.markRead(messageId);
+  }
+
+  /** Force-send the pending read watermark now (e.g. on unmount / tab
+   *  backgrounding). */
+  flushMarkRead(): void {
+    this.room.flushMarkRead();
+  }
+
+  /** Unsubscribe from the room and flush the pending read watermark. The
+   *  collection must not be used afterwards. */
+  dispose(): void {
+    this.room.flushMarkRead();
+    for (const u of this.unsubs.splice(0)) u();
+    this.bus.removeAll();
+  }
+
+  // ── event handlers ──────────────────────────────────────────────
+
+  private onIncoming(f: WsChatReceive): void {
+    this._messages.push(chatMessageFromLive(f));
+    this.emit("inserted");
+  }
+
+  private onUpdated(f: WsMessageUpdated): void {
+    this.mutateById(f.message_id, (m) => ({
+      ...m,
+      content: f.content ?? m.content,
+      editedCount: m.editedCount + 1,
+    }));
+  }
+
+  private onDeleted(f: WsMessageDeleted): void {
+    this.mutateById(f.message_id, (m) => ({ ...m, isDeleted: true }));
+  }
+
+  private onCleared(f: WsMessagesCleared): void {
+    // Operator wipe up to (and including) up_to_message_id — flip local
+    // copies. A null cutoff means the whole room was wiped.
+    const upTo = f.up_to_message_id;
+    let changed = false;
+    this._messages = this._messages.map((m) => {
+      if (!m.isDeleted && (upTo == null || !idGreater(m.id, upTo))) {
+        changed = true;
+        return { ...m, isDeleted: true };
+      }
+      return m;
+    });
+    if (changed) this.emit("updated");
+  }
+
+  private onReactionAdded(f: WsReactionAdded): void {
+    this.mutateById(f.message_id, (m) => {
+      const next: ReactionEntry[] = m.reactions.map((r) =>
+        r.key === f.reaction_key
+          ? {
+              key: r.key,
+              userIds: [...new Set([...r.userIds, f.user_id])],
+              updatedAt: f.updated_at,
+            }
+          : r,
+      );
+      if (!next.some((r) => r.key === f.reaction_key)) {
+        next.push({
+          key: f.reaction_key,
+          userIds: [f.user_id],
+          updatedAt: f.updated_at,
+        });
+      }
+      return { ...m, reactions: next };
+    });
+  }
+
+  private onReactionRemoved(f: WsReactionRemoved): void {
+    this.mutateById(f.message_id, (m) => {
+      const next: ReactionEntry[] = [];
+      for (const r of m.reactions) {
+        if (r.key !== f.reaction_key) {
+          next.push(r);
+          continue;
+        }
+        const users = r.userIds.filter((u) => u !== f.user_id);
+        if (users.length > 0) {
+          next.push({ key: r.key, userIds: users, updatedAt: f.updated_at });
+        }
+      }
+      return { ...m, reactions: next };
+    });
+  }
+
+  private onSyncTick(f: WsSyncTick): void {
+    let changed = false;
+    for (const [userId, mid] of Object.entries(f.read_states)) {
+      const cur = this._readWatermarks[userId];
+      if (!cur || idGreater(mid, cur)) {
+        this._readWatermarks[userId] = mid;
+        changed = true;
+      }
+    }
+    if (changed) this.emit("watermarks");
+  }
+
+  // ── helpers ─────────────────────────────────────────────────────
+
+  private bindAck(tempId: string, messageId: Promise<string>): void {
+    messageId
+      .then((realId) => {
+        this.mutateByTempId(tempId, (m) => ({
+          ...m,
+          id: realId,
+          status: "sent",
+        }));
+      })
+      .catch(() => {
+        this.mutateByTempId(tempId, (m) => ({ ...m, status: "failed" }));
+      });
+  }
+
+  private mutateById(id: string, f: (m: ChatMessage) => ChatMessage): void {
+    const i = this._messages.findIndex((m) => m.id === id);
+    if (i === -1) return;
+    this._messages[i] = f(this._messages[i]!);
+    this.emit("updated");
+  }
+
+  private mutateByTempId(
+    tempId: string,
+    f: (m: ChatMessage) => ChatMessage,
+  ): void {
+    const i = this._messages.findIndex((m) => m.tempId === tempId);
+    if (i === -1) return;
+    this._messages[i] = f(this._messages[i]!);
+    this.emit("updated");
+  }
+
+  private emit(kind: CollectionChangeKind): void {
+    this.bus.emit("change", { kind });
+  }
+}