@loggerjs/browser 0.5.2 → 0.5.4

package/dist/offline-first-transport.js

@@ -1,13 +1,99 @@
-import { incrementLoggerMetaCounter, recordToEvent, retryTransport, safeJsonCodec, toLevelValue } from "@loggerjs/core";
+import { incrementLoggerMetaCounter, recordToEvent, retryTransport, safeJsonCodec, safeJsonStringify, toLevelValue } from "@loggerjs/core";
 //#region src/indexeddb-transport.ts
 const DEFAULT_DB_NAME = "loggerjs";
 const DEFAULT_STORE_NAME = "logs";
-const DB_VERSION = 2;
+const DEFAULT_SESSION_CONTEXT_KEY = "sessionId";
+const DEFAULT_SPILL_MAX_ENTRIES = 200;
+const DEFAULT_SPILL_MAX_BYTES = 512 * 1024;
+const DEFAULT_SPILL_MAX_ORIGIN_BYTES = 5 * 1024 * 1024;
+const DB_VERSION = 4;
 const ORDER_INDEX_NAME = "createdAtSeq";
+const SESSION_INDEX_NAME = "sessionId";
+const SESSION_ORDER_INDEX_NAME = "sessionIdCreatedAtSeq";
+const SESSION_STORE_SUFFIX = "__sessions";
+const SESSION_LAST_SEEN_INDEX_NAME = "lastSeenSessionId";
+const SPILL_SCHEMA = "loggerjs.indexeddb-spill.v1";
 function normalizePositiveInteger(value, fallback) {
 	if (value === void 0 || !Number.isFinite(value)) return fallback;
 	return Math.max(0, Math.floor(value));
 }
+let fallbackSessionSeq = 0;
+function defaultPageSessionId() {
+	const randomUUID = globalThis.crypto?.randomUUID;
+	if (randomUUID) return randomUUID.call(globalThis.crypto);
+	return `${Date.now().toString(36)}-${(fallbackSessionSeq++).toString(36)}`;
+}
+function normalizeSessionId(value) {
+	if (typeof value !== "string") return void 0;
+	const normalized = value.trim();
+	return normalized.length > 0 ? normalized : void 0;
+}
+function normalizeSessionOptions(session) {
+	if (session === false) return void 0;
+	if (typeof session === "string") return {
+		contextKey: DEFAULT_SESSION_CONTEXT_KEY,
+		id: normalizeSessionId(session) ?? defaultPageSessionId()
+	};
+	return {
+		contextKey: session?.contextKey ?? DEFAULT_SESSION_CONTEXT_KEY,
+		getId: session?.getId,
+		id: normalizeSessionId(session?.id) ?? defaultPageSessionId()
+	};
+}
+function resolveLocalStorage(storage) {
+	if (storage) return storage;
+	try {
+		return globalThis.localStorage;
+	} catch {
+		return;
+	}
+}
+function normalizeLocalStorageSpillOptions(spill, dbName, storeName) {
+	if (!spill) return void 0;
+	const storage = resolveLocalStorage(spill.storage);
+	if (!storage) return void 0;
+	const namespace = spill.namespace ?? `${dbName}:${storeName}`;
+	return {
+		drainOnCreate: spill.drainOnCreate ?? true,
+		key: `loggerjs:spill:v1:${namespace}`,
+		maxBytes: normalizePositiveInteger(spill.maxBytes, DEFAULT_SPILL_MAX_BYTES),
+		maxEntries: normalizePositiveInteger(spill.maxEntries, DEFAULT_SPILL_MAX_ENTRIES),
+		maxOriginBytes: normalizePositiveInteger(spill.maxOriginBytes, DEFAULT_SPILL_MAX_ORIGIN_BYTES),
+		minLevelValue: spill.minLevel === void 0 ? void 0 : toLevelValue(spill.minLevel),
+		onDrop: spill.onDrop,
+		spillOnPageHide: spill.spillOnPageHide ?? true,
+		storage
+	};
+}
+function storageByteLength(key, value) {
+	return 2 * (key.length + value.length);
+}
+function estimateLocalStorageBytes(storage) {
+	try {
+		let total = 0;
+		for (let index = 0; index < storage.length; index += 1) {
+			const key = storage.key(index);
+			if (key === null) continue;
+			total += storageByteLength(key, storage.getItem(key) ?? "");
+		}
+		return total;
+	} catch {
+		return;
+	}
+}
+function isQuotaExceededError(error) {
+	return typeof DOMException !== "undefined" && error instanceof DOMException && (error.name === "QuotaExceededError" || error.name === "NS_ERROR_DOM_QUOTA_REACHED");
+}
+function isSpillLogEvent(value) {
+	if (!value || typeof value !== "object") return false;
+	const event = value;
+	return typeof event.id === "string" && typeof event.time === "number" && typeof event.seq === "number" && typeof event.level === "number" && typeof event.levelName === "string" && typeof event.logger === "string" && typeof event.message === "string";
+}
+function parseSpillPayload(raw) {
+	const parsed = JSON.parse(raw);
+	if (parsed.schema !== SPILL_SCHEMA || !Array.isArray(parsed.entries)) return void 0;
+	return parsed.entries.filter(isSpillLogEvent);
+}
 function nowMs() {
 	return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 }
@@ -50,6 +136,9 @@ function indexExists(store, name) {
 function ensureIndex(store, name, keyPath) {
 	if (!indexExists(store, name)) store.createIndex(name, keyPath);
 }
+function sessionStoreNameFor(storeName) {
+	return `${storeName}${SESSION_STORE_SUFFIX}`;
+}
 function getStoreIndex(store, name) {
 	const maybeStore = store;
 	if (typeof maybeStore.index !== "function" || !indexExists(store, name)) return void 0;
@@ -73,13 +162,67 @@ function decodeEntry(entry, codec) {
 function shouldKeepEntry(entry, options) {
 	if (options.from !== void 0 && entry.createdAt < options.from) return false;
 	if (options.to !== void 0 && entry.createdAt > options.to) return false;
+	if (options.sessionId !== void 0 && entry.sessionId !== options.sessionId) return false;
 	if (options.minLevel !== void 0 && entry.level < toLevelValue(options.minLevel)) return false;
 	if (options.logger !== void 0 && entry.logger !== options.logger) return false;
 	if (options.type !== void 0 && entry.type !== options.type) return false;
 	return true;
 }
+function addSessionSummary(sessions, entry) {
+	if (!entry.sessionId) return;
+	const current = sessions.get(entry.sessionId);
+	if (current) {
+		current.firstSeen = Math.min(current.firstSeen, entry.createdAt);
+		current.lastSeen = Math.max(current.lastSeen, entry.createdAt);
+		current.count += 1;
+		current.byteLength += entry.byteLength;
+		return;
+	}
+	sessions.set(entry.sessionId, {
+		byteLength: entry.byteLength,
+		count: 1,
+		firstSeen: entry.createdAt,
+		lastSeen: entry.createdAt,
+		sessionId: entry.sessionId
+	});
+}
+function mergeSessionSummary(current, incoming) {
+	if (!current) return incoming;
+	return {
+		byteLength: current.byteLength + incoming.byteLength,
+		count: current.count + incoming.count,
+		firstSeen: Math.min(current.firstSeen, incoming.firstSeen),
+		lastSeen: Math.max(current.lastSeen, incoming.lastSeen),
+		sessionId: incoming.sessionId
+	};
+}
+function orderSessions(sessions, order = "desc") {
+	const sorted = [...sessions].sort((left, right) => {
+		if (left.lastSeen !== right.lastSeen) return left.lastSeen - right.lastSeen;
+		return left.sessionId < right.sessionId ? -1 : left.sessionId > right.sessionId ? 1 : 0;
+	});
+	if (order === "asc") return sorted;
+	const reversed = [];
+	for (let index = sorted.length - 1; index >= 0; index -= 1) reversed.push(sorted[index]);
+	return reversed;
+}
 function orderRangeForQuery(options) {
 	if (typeof IDBKeyRange === "undefined") return void 0;
+	if (options.sessionId !== void 0) {
+		const lower = [
+			options.sessionId,
+			options.from ?? Number.MIN_SAFE_INTEGER,
+			Number.MIN_SAFE_INTEGER,
+			""
+		];
+		const upper = [
+			options.sessionId,
+			options.to ?? Number.MAX_SAFE_INTEGER,
+			Number.MAX_SAFE_INTEGER,
+			"￿"
+		];
+		return IDBKeyRange.bound(lower, upper);
+	}
 	const lower = options.from === void 0 ? void 0 : [
 		options.from,
 		Number.MIN_SAFE_INTEGER,
@@ -94,6 +237,33 @@ function orderRangeForQuery(options) {
 	if (lower) return IDBKeyRange.lowerBound(lower);
 	if (upper) return IDBKeyRange.upperBound(upper);
 }
+function orderRangeForSessionId(sessionId) {
+	if (typeof IDBKeyRange === "undefined") return void 0;
+	return IDBKeyRange.bound([
+		sessionId,
+		Number.MIN_SAFE_INTEGER,
+		Number.MIN_SAFE_INTEGER,
+		""
+	], [
+		sessionId,
+		Number.MAX_SAFE_INTEGER,
+		Number.MAX_SAFE_INTEGER,
+		"￿"
+	]);
+}
+function migrateSessionSummaries(logStore, sessionStore) {
+	const summaries = /* @__PURE__ */ new Map();
+	const request = logStore.openCursor();
+	request.addEventListener("success", () => {
+		const cursor = request.result;
+		if (!cursor) {
+			for (const summary of summaries.values()) sessionStore.put(summary);
+			return;
+		}
+		addSessionSummary(summaries, cursor.value);
+		cursor.continue();
+	});
+}
 function iterateCursor(request, visit) {
 	return new Promise((resolve, reject) => {
 		request.addEventListener("success", () => {
@@ -118,6 +288,7 @@ function iterateCursor(request, visit) {
 function indexedDbTransport(options = {}) {
 	const dbName = options.dbName ?? DEFAULT_DB_NAME;
 	const storeName = options.storeName ?? DEFAULT_STORE_NAME;
+	const sessionStoreName = sessionStoreNameFor(storeName);
 	const codec = options.codec ?? safeJsonCodec();
 	const batchSize = normalizePositiveInteger(options.batchSize, 100);
 	const flushIntervalMs = normalizePositiveInteger(options.flushIntervalMs, 1e3);
@@ -128,12 +299,18 @@ function indexedDbTransport(options = {}) {
 	const flushOnPageHide = options.flushOnPageHide ?? true;
 	const durability = options.durability ?? "default";
 	const rootIndexedDB = options.indexedDB ?? globalThis.indexedDB;
+	const sessionOptions = normalizeSessionOptions(options.session);
+	const spillOptions = normalizeLocalStorageSpillOptions(options.localStorageSpill, dbName, storeName);
 	const transactionOptions = durability === "default" ? void 0 : { durability };
 	const buffer = [];
 	let dbPromise;
 	let indexedDBFactoryPromise;
 	let timer;
 	let flushPromise;
+	let clearPromise;
+	let pendingFlushBatch;
+	let spillDrainPromise;
+	let localStorageSpillClearCandidate;
 	let lastContext;
 	let closed = false;
 	const statsState = {
@@ -160,13 +337,23 @@ function indexedDbTransport(options = {}) {
 		storageBucketFallbacks: 0,
 		transactionOptionFallbacks: 0,
 		errors: 0,
-		errorsByOperation: {}
+		errorsByOperation: {},
+		localStorageSpillWrites: 0,
+		localStorageSpillEntries: 0,
+		localStorageSpillDrains: 0,
+		localStorageSpillDrainedEntries: 0,
+		localStorageSpillDropped: 0,
+		localStorageSpillDroppedByReason: {},
+		localStorageSpillErrors: 0,
+		localStorageSpillErrorsByOperation: {}
 	};
 	const snapshotStats = () => ({
 		...statsState,
 		bufferDepth: buffer.length,
 		droppedByReason: { ...statsState.droppedByReason },
 		errorsByOperation: { ...statsState.errorsByOperation },
+		localStorageSpillDroppedByReason: { ...statsState.localStorageSpillDroppedByReason },
+		localStorageSpillErrorsByOperation: { ...statsState.localStorageSpillErrorsByOperation },
 		pendingFlush: flushPromise !== void 0,
 		persistedDroppedByReason: { ...statsState.persistedDroppedByReason }
 	});
@@ -193,6 +380,18 @@ function indexedDbTransport(options = {}) {
 		incrementLoggerMetaCounter(`transport.indexeddb.persisted.dropped.${reason}`);
 		options.onPersistedDrop?.(entry, reason);
 	};
+	const reportSpillError = (error, operation) => {
+		statsState.localStorageSpillErrors += 1;
+		incrementRecord(statsState.localStorageSpillErrorsByOperation, operation);
+		reportInternalError(error, `localstorage-spill-${operation}`);
+	};
+	const dropSpillEvent = (event, reason) => {
+		statsState.localStorageSpillDropped += 1;
+		incrementRecord(statsState.localStorageSpillDroppedByReason, reason);
+		incrementLoggerMetaCounter("transport.indexeddb.localstorage_spill.dropped");
+		incrementLoggerMetaCounter(`transport.indexeddb.localstorage_spill.dropped.${reason}`);
+		spillOptions?.onDrop?.(event, reason);
+	};
 	const resolveIndexedDBFactory = async () => {
 		if (options.indexedDB || !options.storageBucketName) return rootIndexedDB;
 		indexedDBFactoryPromise ??= (async () => {
@@ -219,7 +418,7 @@ function indexedDbTransport(options = {}) {
 			if (!idb) throw new Error("IndexedDB is not available for indexedDbTransport");
 			return new Promise((resolve, reject) => {
 				const request = idb.open(dbName, DB_VERSION);
-				request.addEventListener("upgradeneeded", () => {
+				request.addEventListener("upgradeneeded", (event) => {
 					const db = request.result;
 					const store = db.objectStoreNames.contains(storeName) ? request.transaction?.objectStore(storeName) : db.createObjectStore(storeName, { keyPath: "id" });
 					if (!store) return;
@@ -232,6 +431,17 @@ function indexedDbTransport(options = {}) {
 						"seq",
 						"id"
 					]);
+					ensureIndex(store, SESSION_INDEX_NAME, "sessionId");
+					ensureIndex(store, SESSION_ORDER_INDEX_NAME, [
+						"sessionId",
+						"createdAt",
+						"seq",
+						"id"
+					]);
+					const sessionStore = db.objectStoreNames.contains(sessionStoreName) ? request.transaction?.objectStore(sessionStoreName) : db.createObjectStore(sessionStoreName, { keyPath: "sessionId" });
+					if (!sessionStore) return;
+					ensureIndex(sessionStore, SESSION_LAST_SEEN_INDEX_NAME, ["lastSeen", "sessionId"]);
+					if (event.oldVersion < 4) migrateSessionSummaries(store, sessionStore);
 				});
 				request.addEventListener("success", () => {
 					statsState.databaseOpenCount += 1;
@@ -242,13 +452,13 @@ function indexedDbTransport(options = {}) {
 		});
 		return dbPromise;
 	};
-	const createTransaction = (db, mode) => {
-		if (mode !== "readwrite" || !transactionOptions) return db.transaction(storeName, mode);
+	const createTransaction = (db, mode, stores = storeName) => {
+		if (mode !== "readwrite" || !transactionOptions) return db.transaction(stores, mode);
 		try {
-			return db.transaction(storeName, mode, transactionOptions);
+			return db.transaction(stores, mode, transactionOptions);
 		} catch {
 			statsState.transactionOptionFallbacks += 1;
-			return db.transaction(storeName, mode);
+			return db.transaction(stores, mode);
 		}
 	};
 	const withStore = async (mode, run) => {
@@ -265,6 +475,57 @@ function indexedDbTransport(options = {}) {
 			throw error;
 		}
 	};
+	const withLogAndSessionStores = async (mode, run) => {
+		const tx = createTransaction(await openDb(), mode, [storeName, sessionStoreName]);
+		const settled = transactionToPromise(tx);
+		try {
+			const result = await run(tx.objectStore(storeName), tx.objectStore(sessionStoreName), tx);
+			await settled;
+			return result;
+		} catch (error) {
+			if (tx.error === null) try {
+				tx.abort();
+			} catch {}
+			throw error;
+		}
+	};
+	const withSessionStore = async (mode, run) => {
+		const tx = createTransaction(await openDb(), mode, sessionStoreName);
+		const settled = transactionToPromise(tx);
+		try {
+			const result = await run(tx.objectStore(sessionStoreName), tx);
+			await settled;
+			return result;
+		} catch (error) {
+			if (tx.error === null) try {
+				tx.abort();
+			} catch {}
+			throw error;
+		}
+	};
+	const mergeSessionSummaries = async (sessionStore, entries) => {
+		const summaries = /* @__PURE__ */ new Map();
+		for (const entry of entries) addSessionSummary(summaries, entry);
+		for (const summary of summaries.values()) {
+			const current = await requestToPromise(sessionStore.get(summary.sessionId));
+			await requestToPromise(sessionStore.put(mergeSessionSummary(current, summary)));
+		}
+	};
+	const rebuildSessionSummaries = async (store, sessionStore, sessionIds) => {
+		if (sessionIds.size === 0) return;
+		const index = getStoreIndex(store, SESSION_ORDER_INDEX_NAME);
+		for (const sessionId of sessionIds) {
+			const summaries = /* @__PURE__ */ new Map();
+			const range = orderRangeForSessionId(sessionId);
+			await iterateCursor(index && range ? index.openCursor(range) : store.openCursor(), (cursor) => {
+				const entry = cursor.value;
+				if (entry.sessionId === sessionId) addSessionSummary(summaries, entry);
+			});
+			const summary = summaries.get(sessionId);
+			if (summary) await requestToPromise(sessionStore.put(summary));
+			else await requestToPromise(sessionStore.delete(sessionId));
+		}
+	};
 	const getEntries = async () => orderEntries(await withStore("readonly", (store) => requestToPromise(store.getAll())));
 	const countEntries = async () => withStore("readonly", (store) => {
 		const maybeStore = store;
@@ -273,25 +534,31 @@ function indexedDbTransport(options = {}) {
 	});
 	const deleteEntries = async (entries, reason) => {
 		if (entries.length === 0) return;
-		await withStore("readwrite", async (store) => {
+		await withLogAndSessionStores("readwrite", async (store, sessionStore) => {
+			const affectedSessionIds = /* @__PURE__ */ new Set();
 			for (const entry of entries) {
 				await requestToPromise(store.delete(entry.id));
+				if (entry.sessionId) affectedSessionIds.add(entry.sessionId);
 				dropPersistedEntry(entry, reason);
 			}
+			await rebuildSessionSummaries(store, sessionStore, affectedSessionIds);
 		});
 	};
-	const deleteByCursor = async (reason, openCursor, shouldDelete) => withStore("readwrite", async (store) => {
+	const deleteByCursor = async (reason, openCursor, shouldDelete) => withLogAndSessionStores("readwrite", async (store, sessionStore) => {
 		const request = openCursor(store);
 		if (!request) return void 0;
 		let deleted = 0;
+		const affectedSessionIds = /* @__PURE__ */ new Set();
 		await iterateCursor(request, (cursor) => {
 			const entry = cursor.value;
 			if (!shouldDelete(entry, deleted)) return false;
 			cursor.delete();
 			deleted += 1;
+			if (entry.sessionId) affectedSessionIds.add(entry.sessionId);
 			dropPersistedEntry(entry, reason);
 			return true;
 		});
+		await rebuildSessionSummaries(store, sessionStore, affectedSessionIds);
 		return deleted;
 	});
 	const deleteExpiredByCursor = async (cutoff) => {
@@ -322,7 +589,7 @@ function indexedDbTransport(options = {}) {
 		return total;
 	});
 	const queryEntriesByCursor = async (queryOptions) => withStore("readonly", async (store) => {
-		const index = getStoreIndex(store, ORDER_INDEX_NAME);
+		const index = getStoreIndex(store, queryOptions.sessionId === void 0 ? ORDER_INDEX_NAME : SESSION_ORDER_INDEX_NAME);
 		if (!index) return void 0;
 		const entries = [];
 		const limit = queryOptions.limit;
@@ -335,6 +602,20 @@ function indexedDbTransport(options = {}) {
 		});
 		return entries;
 	});
+	const listSessions = async (sessionQueryOptions = {}) => {
+		const limit = sessionQueryOptions.limit;
+		if (limit !== void 0 && limit <= 0) return [];
+		return withSessionStore("readonly", async (sessionStore) => {
+			const sessions = [];
+			const index = getStoreIndex(sessionStore, SESSION_LAST_SEEN_INDEX_NAME);
+			if (!index) return orderSessions(await requestToPromise(sessionStore.getAll()), sessionQueryOptions.order).slice(0, limit);
+			await iterateCursor(index.openCursor(void 0, sessionQueryOptions.order === "asc" ? "next" : "prev"), (cursor) => {
+				sessions.push(cursor.value);
+				return limit === void 0 || sessions.length < limit;
+			});
+			return sessions;
+		});
+	};
 	const pruneWithEntries = async () => {
 		const now = Date.now();
 		let entries = await getEntries();
@@ -390,10 +671,34 @@ function indexedDbTransport(options = {}) {
 			statsState.lastPruneDurationMs = nowMs() - startedAt;
 		}
 	};
+	const sessionIdForEvent = (event) => {
+		if (!sessionOptions) return void 0;
+		return normalizeSessionId(sessionOptions.getId?.(event)) ?? normalizeSessionId(event.context?.[sessionOptions.contextKey]) ?? sessionOptions.id;
+	};
+	const eventWithSessionContext = (event, sessionId) => {
+		if (!sessionId || !sessionOptions?.contextKey) return event;
+		if (event.context?.[sessionOptions.contextKey] === sessionId) return event;
+		return {
+			...event,
+			context: {
+				...event.context,
+				[sessionOptions.contextKey]: sessionId
+			}
+		};
+	};
+	const eventWithResolvedSession = (event) => {
+		const sessionId = sessionIdForEvent(event);
+		return {
+			event: eventWithSessionContext(event, sessionId),
+			sessionId
+		};
+	};
 	const eventToEntry = (event) => {
-		const payload = codec.encode(event);
+		const resolved = eventWithResolvedSession(event);
+		const payload = codec.encode(resolved.event);
 		return {
 			id: event.id,
+			sessionId: resolved.sessionId,
 			seq: event.seq,
 			createdAt: event.time,
 			level: event.level,
@@ -404,17 +709,50 @@ function indexedDbTransport(options = {}) {
 			payload
 		};
 	};
+	const clearLocalStorageSpill = (expectedValue) => {
+		if (!spillOptions) return false;
+		try {
+			if (expectedValue !== void 0 && spillOptions.storage.getItem(spillOptions.key) !== expectedValue) return false;
+			spillOptions.storage.removeItem(spillOptions.key);
+			if (expectedValue === void 0 || localStorageSpillClearCandidate?.value === expectedValue) localStorageSpillClearCandidate = void 0;
+			return true;
+		} catch (error) {
+			reportSpillError(error, "clear");
+			return false;
+		}
+	};
+	const rememberLocalStorageSpill = (value, events) => {
+		localStorageSpillClearCandidate = {
+			pendingIds: new Set(events.map((event) => event.id)),
+			value
+		};
+	};
+	const markLocalStorageSpillPersisted = (events) => {
+		const candidate = localStorageSpillClearCandidate;
+		if (!candidate || events.length === 0) return;
+		for (const event of events) candidate.pendingIds.delete(event.id);
+		if (candidate.pendingIds.size === 0) clearLocalStorageSpill(candidate.value);
+	};
 	const writeBatch = async (events) => {
 		if (events.length === 0) return;
 		const startedAt = nowMs();
 		statsState.lastFlushBatchSize = events.length;
 		const entries = events.map(eventToEntry);
 		try {
-			await withStore("readwrite", (store) => {
-				for (const entry of entries) store.put(entry);
+			await withLogAndSessionStores("readwrite", async (store, sessionStore) => {
+				const rebuildSessionIds = /* @__PURE__ */ new Set();
+				for (const entry of entries) {
+					const existing = await requestToPromise(store.get(entry.id));
+					if (existing?.sessionId) rebuildSessionIds.add(existing.sessionId);
+					if (existing && entry.sessionId) rebuildSessionIds.add(entry.sessionId);
+					await requestToPromise(store.put(entry));
+				}
+				await rebuildSessionSummaries(store, sessionStore, rebuildSessionIds);
+				await mergeSessionSummaries(sessionStore, entries.filter((entry) => !entry.sessionId || !rebuildSessionIds.has(entry.sessionId)));
 			});
 			statsState.persisted += entries.length;
 			incrementLoggerMetaCounter("transport.indexeddb.persisted", entries.length);
+			markLocalStorageSpillPersisted(events);
 			await prune();
 			statsState.flushes += 1;
 		} catch (error) {
@@ -424,6 +762,124 @@ function indexedDbTransport(options = {}) {
 			statsState.lastFlushDurationMs = nowMs() - startedAt;
 		}
 	};
+	const stringifySpillPayload = (events) => safeJsonStringify({
+		createdAt: Date.now(),
+		entries: events,
+		schema: SPILL_SCHEMA
+	}, { maxArrayLength: spillOptions?.maxEntries ?? DEFAULT_SPILL_MAX_ENTRIES });
+	const spillStorageBudget = (currentValue) => {
+		if (!spillOptions) return 0;
+		const ownBytes = currentValue ? storageByteLength(spillOptions.key, currentValue) : 0;
+		const originBytes = estimateLocalStorageBytes(spillOptions.storage);
+		if (originBytes === void 0) return spillOptions.maxBytes;
+		return Math.max(0, Math.min(spillOptions.maxBytes, spillOptions.maxOriginBytes - originBytes + ownBytes));
+	};
+	const pendingEventsForSpill = () => {
+		const events = [...pendingFlushBatch ?? [], ...buffer];
+		const seen = /* @__PURE__ */ new Set();
+		const deduped = [];
+		for (const event of events) {
+			if (seen.has(event.id)) continue;
+			seen.add(event.id);
+			if (spillOptions?.minLevelValue !== void 0 && event.level < spillOptions.minLevelValue) continue;
+			deduped.push(eventWithResolvedSession(event).event);
+		}
+		return deduped;
+	};
+	const trimSpillEventsToBudget = (events, budget) => {
+		if (!spillOptions) return void 0;
+		while (events.length > spillOptions.maxEntries) {
+			const dropped = events.shift();
+			if (dropped) dropSpillEvent(dropped, "max-entries");
+		}
+		while (events.length > 0) {
+			const value = stringifySpillPayload(events);
+			if (storageByteLength(spillOptions.key, value) <= budget) return value;
+			const dropped = events.shift();
+			if (dropped) dropSpillEvent(dropped, "max-bytes");
+		}
+	};
+	const writeLocalStorageSpill = () => {
+		if (!spillOptions) return;
+		const pendingEvents = pendingEventsForSpill();
+		if (pendingEvents.length === 0) return;
+		try {
+			const currentValue = spillOptions.storage.getItem(spillOptions.key);
+			let events = pendingEvents;
+			if (currentValue) {
+				const merged = /* @__PURE__ */ new Map();
+				try {
+					for (const event of parseSpillPayload(currentValue) ?? []) merged.set(event.id, event);
+				} catch {}
+				for (const event of pendingEvents) merged.set(event.id, event);
+				events = [...merged.values()];
+			}
+			const budget = spillStorageBudget(currentValue);
+			const value = trimSpillEventsToBudget(events, budget);
+			if (!value) return;
+			try {
+				spillOptions.storage.setItem(spillOptions.key, value);
+			} catch (error) {
+				if (!isQuotaExceededError(error)) throw error;
+				while (events.length > 0) {
+					const dropped = events.shift();
+					if (dropped) dropSpillEvent(dropped, "quota");
+					const retryValue = trimSpillEventsToBudget(events, budget);
+					if (!retryValue) return;
+					try {
+						spillOptions.storage.setItem(spillOptions.key, retryValue);
+						rememberLocalStorageSpill(retryValue, events);
+						statsState.localStorageSpillWrites += 1;
+						statsState.localStorageSpillEntries += events.length;
+						return;
+					} catch (retryError) {
+						if (!isQuotaExceededError(retryError)) throw retryError;
+					}
+				}
+				return;
+			}
+			rememberLocalStorageSpill(value, events);
+			statsState.localStorageSpillWrites += 1;
+			statsState.localStorageSpillEntries += events.length;
+		} catch (error) {
+			reportSpillError(error, "write");
+		}
+	};
+	const drainLocalStorageSpill = async () => {
+		if (!spillOptions) return;
+		let raw;
+		try {
+			raw = spillOptions.storage.getItem(spillOptions.key);
+		} catch (error) {
+			reportSpillError(error, "read");
+			return;
+		}
+		if (!raw) return;
+		let events;
+		try {
+			events = parseSpillPayload(raw);
+		} catch (error) {
+			reportSpillError(error, "parse");
+			clearLocalStorageSpill();
+			return;
+		}
+		if (!events || events.length === 0) {
+			clearLocalStorageSpill();
+			return;
+		}
+		await writeBatch(events);
+		clearLocalStorageSpill(raw);
+		statsState.localStorageSpillDrains += 1;
+		statsState.localStorageSpillDrainedEntries += events.length;
+	};
+	const ensureSpillDrained = async () => {
+		const promise = spillDrainPromise;
+		if (!promise) return;
+		await promise;
+	};
+	if (spillOptions?.drainOnCreate) spillDrainPromise = drainLocalStorageSpill().catch((error) => reportSpillError(error, "drain")).finally(() => {
+		spillDrainPromise = void 0;
+	});
 	const clearTimer = () => {
 		if (timer) clearTimeout(timer);
 		timer = void 0;
@@ -431,7 +887,15 @@ function indexedDbTransport(options = {}) {
 	const flushPending = async () => {
 		if (flushPromise) return flushPromise;
 		clearTimer();
-		flushPromise = writeBatch(buffer.splice(0, buffer.length)).finally(() => {
+		const batch = buffer.splice(0, buffer.length);
+		pendingFlushBatch = batch;
+		const clearBarrier = clearPromise;
+		flushPromise = (async () => {
+			await clearBarrier;
+			await ensureSpillDrained();
+			await writeBatch(batch);
+		})().finally(() => {
+			if (pendingFlushBatch === batch) pendingFlushBatch = void 0;
 			flushPromise = void 0;
 			if (buffer.length > 0 && !closed) schedule();
 		});
@@ -444,14 +908,28 @@ function indexedDbTransport(options = {}) {
 		}, flushIntervalMs);
 	};
 	const onPageHide = () => {
-		flushPending().catch((error) => reportInternalError(error, "pagehide-flush"));
+		if (spillOptions?.spillOnPageHide) writeLocalStorageSpill();
+		if (flushOnPageHide) flushPending().catch((error) => reportInternalError(error, "pagehide-flush"));
 	};
 	const onVisibilityChange = () => {
-		if (typeof document !== "undefined" && document.visibilityState === "hidden") flushPending().catch((error) => reportInternalError(error, "visibility-flush"));
+		if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+			if (spillOptions?.spillOnPageHide) writeLocalStorageSpill();
+			if (flushOnPageHide) flushPending().catch((error) => reportInternalError(error, "visibility-flush"));
+		}
+	};
+	const addVisibilityChangeListener = () => {
+		if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+			document.addEventListener("visibilitychange", onVisibilityChange);
+			return () => document.removeEventListener("visibilitychange", onVisibilityChange);
+		}
+		if (typeof globalThis.addEventListener !== "function") return void 0;
+		globalThis.addEventListener("visibilitychange", onVisibilityChange);
+		return () => globalThis.removeEventListener?.("visibilitychange", onVisibilityChange);
 	};
-	if (flushOnPageHide) {
+	let removeVisibilityChangeListener;
+	if (flushOnPageHide || spillOptions?.spillOnPageHide) {
 		globalThis.addEventListener?.("pagehide", onPageHide);
-		globalThis.addEventListener?.("visibilitychange", onVisibilityChange);
+		removeVisibilityChangeListener = addVisibilityChangeListener();
 	}
 	return {
 		name: options.name ?? "indexeddb",
@@ -482,16 +960,36 @@ function indexedDbTransport(options = {}) {
 			return await countEntries() ?? (await getEntries()).length;
 		},
 		async clear() {
+			if (clearPromise) return clearPromise;
+			const inFlightFlush = flushPromise;
+			const inFlightDrain = spillDrainPromise;
 			buffer.length = 0;
 			clearTimer();
-			await withStore("readwrite", (store) => requestToPromise(store.clear()));
+			clearLocalStorageSpill();
+			clearPromise = (async () => {
+				await inFlightFlush;
+				await inFlightDrain;
+				await withLogAndSessionStores("readwrite", async (store, sessionStore) => {
+					await requestToPromise(store.clear());
+					await requestToPromise(sessionStore.clear());
+				});
+			})().finally(() => {
+				clearPromise = void 0;
+			});
+			return clearPromise;
 		},
 		async remove(ids) {
 			await flushPending();
 			const items = typeof ids === "string" ? [ids] : ids;
 			if (items.length === 0) return;
-			await withStore("readwrite", async (store) => {
-				for (const id of items) await requestToPromise(store.delete(id));
+			await withLogAndSessionStores("readwrite", async (store, sessionStore) => {
+				const affectedSessionIds = /* @__PURE__ */ new Set();
+				for (const id of items) {
+					const entry = await requestToPromise(store.get(id));
+					if (entry?.sessionId) affectedSessionIds.add(entry.sessionId);
+					await requestToPromise(store.delete(id));
+				}
+				await rebuildSessionSummaries(store, sessionStore, affectedSessionIds);
 			});
 		},
 		async *query(queryOptions = {}) {
@@ -507,6 +1005,10 @@ function indexedDbTransport(options = {}) {
 				if (event) yield event;
 			}
 		},
+		async sessions(sessionQueryOptions = {}) {
+			await flushPending();
+			return listSessions(sessionQueryOptions);
+		},
 		stats() {
 			return snapshotStats();
 		},
@@ -514,12 +1016,12 @@ function indexedDbTransport(options = {}) {
 			closed = true;
 			clearTimer();
 			globalThis.removeEventListener?.("pagehide", onPageHide);
-			globalThis.removeEventListener?.("visibilitychange", onVisibilityChange);
-			const flushed = flushPending();
-			const promise = dbPromise;
-			dbPromise = void 0;
-			return flushed.finally(() => {
-				promise?.then((db) => db.close());
+			removeVisibilityChangeListener?.();
+			removeVisibilityChangeListener = void 0;
+			return flushPending().finally(() => {
+				const promise = dbPromise;
+				dbPromise = void 0;
+				return promise?.then((db) => db.close());
 			});
 		}
 	};
@@ -546,12 +1048,14 @@ function isBrowserOnline(options) {
 function offlineFirstTransport(remote, options = {}) {
 	const name = options.name ?? `offline-first(${remote.name ?? "transport"})`;
 	const replayBatchSize = normalizeBatchSize(options.replayBatchSize);
+	const queueOptions = options.queueOptions;
 	const queue = options.queue ?? indexedDbTransport({
 		dbName: "loggerjs-offline",
 		flushIntervalMs: 0,
 		name: `${name}:queue`,
 		storeName: "offline-events",
-		...options.queueOptions
+		...queueOptions,
+		session: queueOptions?.session ?? false
 	});
 	const reliableRemote = retryTransport(remote, {
 		maxRetries: 2,