@pmate/chat-sdk 0.12.0-next.6 → 0.12.0-next.8

package/README.md

@@ -142,7 +142,9 @@ The browser entry point is `createChat` from `@pmate/chat-sdk/runtime`:
 ```ts
 const chat = createChat({ appId, accountId, profileId, teamId, token, onError })
 await chat.start()
-const page = await chat.getMessages(threadId, { limit: 50 })
+const page = await chat.getMessages(threadId)
+// SDK owns the page size and history boundary; hosts need not construct a cursor.
+const earlier = await chat.getMessages(threadId, { earlier: true })
 // After an authoritative mutation (e.g. history assignment), await reconciliation.
 // Concurrent refreshes share transport; errors do not masquerade as fresh cache.
 const reconciled = await chat.getMessages(threadId, { refresh: true })
@@ -201,6 +203,11 @@ legacy cleanup happens after durable migration. Normal reads use memory and writ
 are merged into bounded IndexedDB transactions. Cache errors must be surfaced by
 the host, and pending operations are not reported as saved before their promise
 resolves.
+Control-event batches are bounded by both 128 records and 1 MiB per transaction;
+the queue includes in-flight writes and is limited to 4096 records / 8 MiB.
+`transactionBytes` and `queueBytes` can lower these limits. Oversized operations
+fail before changing the memory snapshot. Repeating an in-flight write waits for
+that physical write, including its failure, rather than acknowledging it early.
 
 `DurableChatSender` saves the exact message created by `ChatClient.prepareChat`
 before transmitting it. `retry(hash)` uses `sendPrepared` with the original hash

package/lib/runtime/chatSession.d.ts

@@ -43,6 +43,8 @@ export declare class ChatSession<T extends StoredMessage> {
     private sender;
     private listeners;
     private snapshots;
+    private historyEdges;
+    private earlierReads;
     private off;
     private globalListeners;
     private globalSnapshot?;
@@ -61,9 +63,12 @@ export declare class ChatSession<T extends StoredMessage> {
             timestamp: number;
             id: string;
         };
+        earlier?: boolean;
         all?: boolean;
         refresh?: boolean;
     }): Promise<MessageSnapshot<T>>;
+    private rememberHistoryEdge;
+    private readEarlier;
     private readAll;
     sendMessage(threadId: string, input: {
         to: string;

package/lib/runtime/chatSession.js

@@ -15,6 +15,8 @@ export class ChatSession {
     sender;
     listeners = new Map();
     snapshots = new Map();
+    historyEdges = new Map();
+    earlierReads = new Map();
     off = [];
     globalListeners = new Set();
     globalSnapshot;
@@ -37,7 +39,7 @@ export class ChatSession {
         this.messages = new MessageClient(options.messages);
         this.connection = options.sharedConnection ?? new ChatClient(options.connection);
         this.reading = new ReadingClient({ ...options.reading, storageScope: JSON.stringify([scope.accountId, scope.teamId]) });
-        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
+        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, scope, onError: options.onError, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
         this.sender = new DurableChatSender(this.connection, scope, options.onError);
         this.catchUp = new WindowedTasks(1000, error => { if (!this.closed)
             options.onError(error); });
@@ -81,6 +83,11 @@ export class ChatSession {
         throw new Error("CHAT_SESSION_CLOSED"); }
     async getMessages(threadId, options = {}) {
         this.assertOpen();
+        if (options.earlier) {
+            if (options.before || options.all || options.limit !== undefined || options.refresh)
+                throw new Error("INVALID_MESSAGE_QUERY");
+            return this.readEarlier(threadId);
+        }
         if (options.all && (options.before || options.limit !== undefined))
             throw new Error("INVALID_MESSAGE_QUERY");
         // Explicit authoritative changes (for example history assignment) can invalidate
@@ -92,8 +99,37 @@ export class ChatSession {
         }
         const page = await (options.before ? this.messages.earlier(threadId, options.before, options.limit) : this.messages.read(threadId, options.limit));
         await this.sender.confirm(page.messages.map(message => message.id));
+        const edge = this.historyEdges.get(threadId);
+        if (!options.before && page.complete && (!edge || edge.version !== page.resetVersion))
+            this.rememberHistoryEdge(threadId, page);
         return page;
     }
+    rememberHistoryEdge(threadId, page) {
+        const first = page.messages[0];
+        this.historyEdges.set(threadId, { before: first ? { timestamp: first.timestamp, id: first.id } : undefined, version: page.resetVersion, hasEarlier: page.hasEarlier });
+    }
+    readEarlier(threadId) {
+        const running = this.earlierReads.get(threadId);
+        if (running)
+            return running;
+        const task = (async () => {
+            const recent = await this.getMessages(threadId);
+            if (!recent.complete)
+                throw new Error("MESSAGE_WINDOW_INCOMPLETE");
+            const edge = this.historyEdges.get(threadId);
+            if (!edge.hasEarlier)
+                return { ...recent, messages: [], hasEarlier: false };
+            if (!edge.before)
+                throw new Error("MESSAGE_SYNC_NO_PROGRESS");
+            const page = await this.getMessages(threadId, { before: edge.before });
+            this.assertOpen();
+            this.rememberHistoryEdge(threadId, page);
+            return page;
+        })().finally(() => { if (this.earlierReads.get(threadId) === task)
+            this.earlierReads.delete(threadId); });
+        this.earlierReads.set(threadId, task);
+        return task;
+    }
     async readAll(threadId) {
         for (let attempt = 0; attempt < 3; attempt++) {
             const pages = [];
@@ -231,6 +267,8 @@ export class ChatSession {
             this.listeners.clear();
             this.globalListeners.clear();
             this.snapshots.clear();
+            this.historyEdges.clear();
+            this.earlierReads.clear();
             this.globalSnapshot = undefined;
         })();
     }

package/lib/runtime/messageReaders.d.ts

@@ -1,3 +1,4 @@
+import { type MessageScope } from "./messageStore.js";
 export type MessageReadersPage = {
     appId: string;
     threadId: string;
@@ -21,6 +22,8 @@ export type MessageReadersOptions = {
     token: string;
     hubHttpUrl: string;
     fetch?: typeof fetch;
+    scope?: MessageScope;
+    onError?: (error: unknown) => void;
 };
 export declare class MessageReadersError extends Error {
     readonly status: number;
@@ -32,8 +35,12 @@ export declare class MessageReadersClient {
     private options;
     private pending;
     private lifetime;
+    private cache?;
+    private revoked;
+    private generation;
     constructor(options: MessageReadersOptions);
     getReaders(query: MessageReadersQuery, signal?: AbortSignal): Promise<MessageReadersPage>;
+    private cachedRequest;
     private request;
     close(): void;
 }

package/lib/runtime/messageReaders.js

@@ -1,3 +1,5 @@
+import { IndexedDbResponseCache } from "./responseCache.js";
+import { messageScopeKey } from "./messageStore.js";
 export class MessageReadersError extends Error {
     status;
     forbidden;
@@ -12,7 +14,17 @@ export class MessageReadersClient {
     options;
     pending = new Map();
     lifetime = new AbortController();
-    constructor(options) { this.options = { ...options }; }
+    cache;
+    revoked = false;
+    generation = 0;
+    constructor(options) {
+        this.options = { ...options };
+        if (options.scope) {
+            if (options.scope.appId !== options.appId || options.scope.profileId !== options.profileId)
+                throw new Error("MESSAGE_READERS_SCOPE_MISMATCH");
+            this.cache = new IndexedDbResponseCache(messageScopeKey(options.scope));
+        }
+    }
     getReaders(query, signal) {
         if (this.lifetime.signal.aborted)
             return Promise.reject(new Error("MESSAGE_READERS_CLOSED"));
@@ -24,7 +36,7 @@ export class MessageReadersClient {
         const key = JSON.stringify([input.threadId, input.messageId, input.afterProfileId, input.revision, input.limit]);
         let task = this.pending.get(key);
         if (!task) {
-            task = this.request(input).finally(() => { if (this.pending.get(key) === task)
+            task = this.cachedRequest(input, key).finally(() => { if (this.pending.get(key) === task)
                 this.pending.delete(key); });
             this.pending.set(key, task);
         }
@@ -37,6 +49,47 @@ export class MessageReadersClient {
             task.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
         });
     }
+    async cachedRequest(input, key) {
+        // Keep only the standard SDK window. Arbitrary page sizes must not multiply
+        // durable cache entries. Revision is part of the key, so changed counts do
+        // not reuse a page from a previous membership/read projection.
+        const cache = input.limit === 50 ? this.cache : undefined;
+        if (!cache)
+            return this.request(input);
+        const stored = await cache.read(key).catch(error => { this.options.onError?.(error); return undefined; });
+        if (this.lifetime.signal.aborted)
+            throw new Error("MESSAGE_READERS_CLOSED");
+        const generation = this.generation;
+        const cached = this.revoked ? undefined : stored?.cached;
+        if (cached && (Date.now() - cached.time < 5000 || (typeof navigator !== "undefined" && navigator.onLine === false)))
+            return structuredClone(cached.value);
+        let value;
+        try {
+            value = await this.request(input);
+        }
+        catch (error) {
+            if (error instanceof MessageReadersError && error.forbidden) {
+                this.revoked = true;
+                this.generation++;
+                await this.cache?.invalidate().catch(failure => this.options.onError?.(failure));
+                throw error;
+            }
+            if (cached && !this.revoked && generation === this.generation && !this.lifetime.signal.aborted && (error instanceof TypeError || (error instanceof MessageReadersError && error.status >= 500)))
+                return structuredClone(cached.value);
+            throw error;
+        }
+        if (generation !== this.generation)
+            throw new Error("MESSAGE_READERS_INVALIDATED");
+        this.revoked = false;
+        if (value.resetRequired)
+            await cache?.invalidate().catch(error => this.options.onError?.(error));
+        else if (stored)
+            await cache?.write(key, value, stored.epoch).catch(error => { if (String(error).includes("RESPONSE_CACHE_INVALIDATED"))
+                throw error; this.options.onError?.(error); });
+        if (this.lifetime.signal.aborted)
+            throw new Error("MESSAGE_READERS_CLOSED");
+        return value;
+    }
     async request(input) {
         const { token, fetch: fetcher, hubHttpUrl, appId, profileId } = this.options;
         const controller = new AbortController();
@@ -67,5 +120,5 @@ export class MessageReadersClient {
             this.lifetime.signal.removeEventListener("abort", cancel);
         }
     }
-    close() { this.lifetime.abort(); this.pending.clear(); }
+    close() { this.lifetime.abort(); this.pending.clear(); void this.cache?.close().catch(error => this.options.onError?.(error)); }
 }

package/lib/runtime/recordCache.d.ts

@@ -5,6 +5,8 @@ export type RecordCacheOptions<T> = {
     indexedDB?: IDBFactory;
     name?: string;
     onError?: (error: unknown) => void;
+    transactionBytes?: number;
+    queueBytes?: number;
 };
 /** In-memory control-event index backed by bounded asynchronous IndexedDB batches.
  * Legacy storage is read only during open; the hot path never uses localStorage. */
@@ -23,6 +25,11 @@ export declare class IndexedDbRecordCache<T> {
     private closing;
     private initialized;
     private running?;
+    private activeBytes;
+    private pendingBytes;
+    private activeRecords;
+    private transactionBytes;
+    private queueBytes;
     private channel?;
     private listeners;
     constructor(options: RecordCacheOptions<T>);
@@ -34,7 +41,9 @@ export declare class IndexedDbRecordCache<T> {
     subscribe(listener: () => void): () => void;
     private reload;
     upsert(incoming: T[]): Promise<void>;
+    private bytes;
     private write;
+    private writeBatch;
     flush(): Promise<void>;
     private runFlush;
     close(): Promise<void>;

package/lib/runtime/recordCache.js

@@ -17,17 +17,26 @@ export class IndexedDbRecordCache {
     closing = false;
     initialized = false;
     running;
+    activeBytes = 0;
+    pendingBytes = 0;
+    activeRecords = 0;
+    transactionBytes;
+    queueBytes;
     channel;
     listeners = new Set();
     constructor(options) {
         this.options = options;
+        this.transactionBytes = options.transactionBytes ?? 1_048_576;
+        this.queueBytes = options.queueBytes ?? 8_388_608;
+        if (!Number.isSafeInteger(this.transactionBytes) || this.transactionBytes < 1 || !Number.isSafeInteger(this.queueBytes) || this.queueBytes < this.transactionBytes)
+            throw new Error("INVALID_RECORD_CACHE_BYTE_LIMIT");
         this.db = new Dexie(options.name ?? "pmate-chat-records", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
         this.db.version(1).stores({ records: "[scope+id],scope", metadata: "scope" });
         this.records = this.db.table("records");
         this.metadata = this.db.table("metadata");
         this.tasks = new WindowedTasks(16, error => options.onError?.(error));
         if (typeof BroadcastChannel !== "undefined") {
-            this.channel = new BroadcastChannel(`pmate-chat-records:${options.scope}`);
+            this.channel = new BroadcastChannel(`pmate-chat-records:${options.scope}${this.db.name === "pmate-chat-records" ? "" : `:${this.db.name}`}`);
             this.channel.onmessage = () => this.tasks.schedule("reload", () => this.reload());
         }
     }
@@ -83,30 +92,70 @@ export class IndexedDbRecordCache {
         await this.ready;
         if (this.closed || this.closing)
             throw new Error("RECORD_CACHE_CLOSED");
-        if (incoming.length + this.pending.size > 4096)
+        if (incoming.length > 4096)
             throw new Error("RECORD_CACHE_BACKPRESSURE");
-        let changed = false;
+        // Plan and validate the whole operation before publishing any in-memory state.
+        const staged = new Map();
         for (const value of incoming) {
-            const key = this.options.key(value), old = this.values.get(key), next = this.options.merge(old, value);
+            const key = this.options.key(value), old = staged.get(key) ?? this.values.get(key);
+            const next = this.options.merge(old, value);
             if (JSON.stringify(old) === JSON.stringify(next))
                 continue;
+            if (this.bytes(next) > this.transactionBytes)
+                throw new Error("RECORD_CACHE_RECORD_TOO_LARGE");
+            staged.set(key, structuredClone(next));
+        }
+        let nextBytes = this.pendingBytes, nextRecords = this.pending.size;
+        for (const [key, value] of staged) {
+            const previous = this.pending.get(key);
+            nextBytes += this.bytes(value) - (previous === undefined ? 0 : this.bytes(previous));
+            if (!this.pending.has(key))
+                nextRecords++;
+        }
+        if (nextRecords + this.activeRecords > 4096 || nextBytes + this.activeBytes > this.queueBytes)
+            throw new Error("RECORD_CACHE_BACKPRESSURE");
+        let changed = false;
+        for (const [key, next] of staged) {
             this.values.set(key, next);
             this.pending.set(key, next);
             changed = true;
         }
+        this.pendingBytes = nextBytes;
         if (changed)
             this.snapshotValue = [...this.values.values()];
-        if (!changed && !this.pending.size)
+        if (!changed && !this.pending.size) {
+            await this.running;
             return;
+        }
         const committed = new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
         this.tasks.schedule("write", () => this.flush());
         return committed;
     }
+    bytes(value) { return new TextEncoder().encode(JSON.stringify({ scope: this.options.scope, id: this.options.key(value), value })).byteLength; }
     async write(values) {
+        let batch = [], bytes = 0;
+        for (const value of values) {
+            const size = this.bytes(value);
+            if (size > this.transactionBytes)
+                throw new Error("RECORD_CACHE_RECORD_TOO_LARGE");
+            if (batch.length && (batch.length === 128 || bytes + size > this.transactionBytes)) {
+                await this.writeBatch(batch);
+                batch = [];
+                bytes = 0;
+            }
+            batch.push(value);
+            bytes += size;
+        }
+        if (batch.length)
+            await this.writeBatch(batch);
+    }
+    async writeBatch(values) {
         await this.db.transaction("rw", this.records, async () => {
             const previous = await this.records.bulkGet(values.map(value => [this.options.scope, this.options.key(value)]));
             const records = values.map((value, index) => ({ scope: this.options.scope, id: this.options.key(value), value: this.options.merge(previous[index]?.value, value) }));
             const changed = records.filter((row, index) => JSON.stringify(previous[index]?.value) !== JSON.stringify(row.value));
+            if (changed.reduce((sum, row) => sum + this.bytes(row.value), 0) > this.transactionBytes)
+                throw new Error("RECORD_CACHE_MERGE_TOO_LARGE");
             if (changed.length)
                 await this.records.bulkPut(changed);
         });
@@ -126,8 +175,11 @@ export class IndexedDbRecordCache {
     async runFlush() {
         const values = [...this.pending.values()], waiters = this.waiters.splice(0);
         this.pending.clear();
+        this.pendingBytes = 0;
         if (!values.length)
             return;
+        this.activeBytes = values.reduce((sum, value) => sum + this.bytes(value), 0);
+        this.activeRecords = values.length;
         try {
             for (let offset = 0; offset < values.length; offset += 128)
                 await this.write(values.slice(offset, offset + 128));
@@ -142,9 +194,14 @@ export class IndexedDbRecordCache {
                 const key = this.options.key(value);
                 this.pending.set(key, this.options.merge(value, this.pending.get(key) ?? value));
             }
+            this.pendingBytes = [...this.pending.values()].reduce((sum, value) => sum + this.bytes(value), 0);
             waiters.forEach(waiter => waiter.reject(error));
             throw error;
         }
+        finally {
+            this.activeBytes = 0;
+            this.activeRecords = 0;
+        }
     }
     async close() {
         this.closing = true;

package/lib/runtime/responseCache.d.ts

@@ -0,0 +1,27 @@
+/** Small response windows, isolated by identity. Epochs fence late writes after
+ * access withdrawal. No localStorage or synchronous writes on the read path. */
+export declare class IndexedDbResponseCache<T> {
+    private scope;
+    private db;
+    private rows;
+    private epochs;
+    private pending;
+    private tasks;
+    private running?;
+    private closed;
+    constructor(scope: string, options?: {
+        indexedDB?: IDBFactory;
+        name?: string;
+    });
+    read(key: string): Promise<{
+        epoch: number;
+        cached: {
+            value: T;
+            time: number;
+        } | undefined;
+    }>;
+    write(key: string, value: T, epoch: number): Promise<void>;
+    invalidate(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/runtime/responseCache.js

@@ -0,0 +1,103 @@
+import { Dexie } from "dexie";
+import { WindowedTasks } from "./coalescer.js";
+/** Small response windows, isolated by identity. Epochs fence late writes after
+ * access withdrawal. No localStorage or synchronous writes on the read path. */
+export class IndexedDbResponseCache {
+    scope;
+    db;
+    rows;
+    epochs;
+    pending = [];
+    tasks = new WindowedTasks(16, () => { });
+    running;
+    closed = false;
+    constructor(scope, options = {}) {
+        this.scope = scope;
+        this.db = new Dexie(options.name ?? "pmate-chat-response-windows", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        this.db.version(1).stores({ windows: "[scope+key],scope", epochs: "scope" });
+        this.rows = this.db.table("windows");
+        this.epochs = this.db.table("epochs");
+    }
+    async read(key) {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        return this.db.transaction("r", this.rows, this.epochs, async () => {
+            const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0;
+            const row = await this.rows.get([this.scope, key]);
+            return { epoch, cached: row?.epoch === epoch ? { value: row.value, time: row.time } : undefined };
+        });
+    }
+    write(key, value, epoch) {
+        if (this.closed)
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        const copy = structuredClone(value), bytes = new TextEncoder().encode(JSON.stringify(copy)).byteLength;
+        // Count in-flight data as well as queued data; requests cannot create an
+        // unbounded backlog while IndexedDB is blocked by another tab.
+        if (bytes > 65536 || this.pending.length >= 128 || this.pending.reduce((n, w) => n + w.row.bytes, 0) + bytes > 1048576)
+            return Promise.reject(new Error("RESPONSE_CACHE_BACKPRESSURE"));
+        const promise = new Promise((resolve, reject) => this.pending.push({ row: { scope: this.scope, key, epoch, time: Date.now(), bytes, value: copy }, resolve, reject }));
+        this.tasks.schedule("write", () => this.flush());
+        return promise;
+    }
+    async invalidate() {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        await this.db.transaction("rw", this.rows, this.epochs, async () => {
+            const epoch = ((await this.epochs.get(this.scope))?.epoch ?? 0) + 1;
+            await this.epochs.put({ scope: this.scope, epoch });
+            await this.rows.where("scope").equals(this.scope).delete();
+        });
+    }
+    async flush() {
+        if (this.running) {
+            await this.running;
+            if (this.pending.length)
+                return this.flush();
+            return;
+        }
+        const batch = [...this.pending];
+        if (!batch.length)
+            return;
+        const task = (async () => {
+            try {
+                const accepted = await this.db.transaction("rw", this.rows, this.epochs, async () => {
+                    const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0;
+                    const valid = batch.filter(write => write.row.epoch === epoch);
+                    const unique = new Map(valid.map(write => [write.row.key, write.row]));
+                    await this.rows.bulkPut([...unique.values()]);
+                    const stored = await this.rows.where("scope").equals(this.scope).toArray();
+                    stored.sort((a, b) => b.time - a.time || a.key.localeCompare(b.key));
+                    let bytes = 0;
+                    const evicted = [];
+                    stored.forEach((row, index) => { bytes += row.bytes; if (index >= 256 || bytes > 1048576)
+                        evicted.push([this.scope, row.key]); });
+                    await this.rows.bulkDelete(evicted);
+                    return new Set(valid);
+                });
+                batch.forEach(write => accepted.has(write) ? write.resolve() : write.reject(new Error("RESPONSE_CACHE_INVALIDATED")));
+            }
+            catch (error) {
+                batch.forEach(write => write.reject(error));
+                throw error;
+            }
+            finally {
+                this.pending.splice(0, batch.length);
+            }
+        })().finally(() => { if (this.running === task)
+            this.running = undefined; });
+        this.running = task;
+        return task;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.tasks.close();
+        try {
+            await this.flush();
+        }
+        finally {
+            this.db.close();
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.6",
+  "version": "0.12.0-next.8",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",