@loggerjs/browser 0.5.2 → 0.5.4

package/dist/index.cjs

@@ -894,12 +894,98 @@ function indexedDbBrowserHttpOfflineQueue(options = {}) {
 //#region src/indexeddb-transport.ts
 const DEFAULT_DB_NAME = "loggerjs";
 const DEFAULT_STORE_NAME = "logs";
-const DB_VERSION = 2;
+const DEFAULT_SESSION_CONTEXT_KEY$1 = "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$1,
+		id: normalizeSessionId(session) ?? defaultPageSessionId()
+	};
+	return {
+		contextKey: session?.contextKey ?? DEFAULT_SESSION_CONTEXT_KEY$1,
+		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 : (0, _loggerjs_core.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$1() {
 	return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 }
@@ -942,6 +1028,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;
@@ -965,13 +1054,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 < (0, _loggerjs_core.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,
@@ -986,6 +1129,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", () => {
@@ -1010,6 +1180,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 ?? (0, _loggerjs_core.safeJsonCodec)();
 	const batchSize = normalizePositiveInteger(options.batchSize, 100);
 	const flushIntervalMs = normalizePositiveInteger(options.flushIntervalMs, 1e3);
@@ -1020,12 +1191,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 = {
@@ -1052,13 +1229,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 }
 	});
@@ -1085,6 +1272,18 @@ function indexedDbTransport(options = {}) {
 		(0, _loggerjs_core.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);
+		(0, _loggerjs_core.incrementLoggerMetaCounter)("transport.indexeddb.localstorage_spill.dropped");
+		(0, _loggerjs_core.incrementLoggerMetaCounter)(`transport.indexeddb.localstorage_spill.dropped.${reason}`);
+		spillOptions?.onDrop?.(event, reason);
+	};
 	const resolveIndexedDBFactory = async () => {
 		if (options.indexedDB || !options.storageBucketName) return rootIndexedDB;
 		indexedDBFactoryPromise ??= (async () => {
@@ -1111,7 +1310,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;
@@ -1124,6 +1323,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;
@@ -1134,13 +1344,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) => {
@@ -1157,6 +1367,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;
@@ -1165,25 +1426,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) => {
@@ -1214,7 +1481,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;
@@ -1227,6 +1494,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();
@@ -1282,10 +1563,34 @@ function indexedDbTransport(options = {}) {
 			statsState.lastPruneDurationMs = nowMs$1() - 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,
@@ -1296,17 +1601,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$1();
 		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;
 			(0, _loggerjs_core.incrementLoggerMetaCounter)("transport.indexeddb.persisted", entries.length);
+			markLocalStorageSpillPersisted(events);
 			await prune();
 			statsState.flushes += 1;
 		} catch (error) {
@@ -1316,6 +1654,124 @@ function indexedDbTransport(options = {}) {
 			statsState.lastFlushDurationMs = nowMs$1() - startedAt;
 		}
 	};
+	const stringifySpillPayload = (events) => (0, _loggerjs_core.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;
@@ -1323,7 +1779,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();
 		});
@@ -1336,14 +1800,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",
@@ -1374,16 +1852,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 = {}) {
@@ -1399,6 +1897,10 @@ function indexedDbTransport(options = {}) {
 				if (event) yield event;
 			}
 		},
+		async sessions(sessionQueryOptions = {}) {
+			await flushPending();
+			return listSessions(sessionQueryOptions);
+		},
 		stats() {
 			return snapshotStats();
 		},
@@ -1406,12 +1908,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());
 			});
 		}
 	};
@@ -1438,12 +1940,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 = (0, _loggerjs_core.retryTransport)(remote, {
 		maxRetries: 2,
@@ -1570,6 +2074,7 @@ const ZIP_MAX_UINT32 = 4294967295;
 const LOCAL_FILE_HEADER_SIGNATURE = 67324752;
 const CENTRAL_DIRECTORY_SIGNATURE = 33639248;
 const END_OF_CENTRAL_DIRECTORY_SIGNATURE = 101010256;
+const DEFAULT_SESSION_CONTEXT_KEY = "sessionId";
 let crc32Table;
 function getCrc32Table() {
 	if (crc32Table) return crc32Table;
@@ -1709,6 +2214,56 @@ function normalizeMaxEvents(value) {
 	if (!Number.isFinite(value)) return void 0;
 	return Math.max(0, Math.floor(value));
 }
+function normalizeSessionExportOptions(value, logFileName) {
+	if (!value) return void 0;
+	const options = value === true ? {} : value;
+	return {
+		contextKey: options.contextKey ?? DEFAULT_SESSION_CONTEXT_KEY,
+		directory: options.directory ?? "sessions",
+		fallbackSessionId: options.fallbackSessionId ?? "unknown",
+		logFileName: options.logFileName ?? logFileName
+	};
+}
+function normalizeRecentExportOptions(value, format) {
+	if (!value) return void 0;
+	const options = value === true ? {} : value;
+	return {
+		logFileName: options.logFileName ?? (format === "json" ? "recent.json" : "recent.ndjson"),
+		maxEvents: normalizeMaxEvents(options.maxEvents) ?? 100
+	};
+}
+function logContentForLines(lines, format) {
+	if (format === "json") return `[${lines.join(",")}]`;
+	return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+function eventTimeRange(items) {
+	let from;
+	let to;
+	for (const item of items) {
+		from = from === void 0 ? item.event.time : Math.min(from, item.event.time);
+		to = to === void 0 ? item.event.time : Math.max(to, item.event.time);
+	}
+	return from === void 0 || to === void 0 ? void 0 : {
+		from,
+		to
+	};
+}
+function sessionIdForEvent(event, options) {
+	const value = event.context?.[options.contextKey];
+	return typeof value === "string" && value.length > 0 ? value : options.fallbackSessionId;
+}
+function safeZipPathSegment(value) {
+	const encoded = encodeURIComponent(value).replace(/%/g, "_");
+	if (!encoded || encoded === "." || encoded === "..") return "_";
+	return encoded;
+}
+function sortByEventTime(items) {
+	return [...items].sort((left, right) => {
+		if (left.event.time !== right.event.time) return left.event.time - right.event.time;
+		if (left.event.seq !== right.event.seq) return left.event.seq - right.event.seq;
+		return left.event.id < right.event.id ? -1 : left.event.id > right.event.id ? 1 : 0;
+	});
+}
 function createLogZipBlob(files, options = {}) {
 	const normalizedFiles = createNormalizedZipFiles(files, options);
 	const parts = [];
@@ -1731,27 +2286,72 @@ async function exportLogsToZip(source, options = {}) {
 	const createdAt = options.createdAt ?? Date.now();
 	const logFileName = options.logFileName ?? (format === "json" ? "logs.json" : "logs.ndjson");
 	const maxEvents = normalizeMaxEvents(options.maxEvents);
+	const sessionExportOptions = normalizeSessionExportOptions(options.groupBySession, logFileName);
+	const recentExportOptions = normalizeRecentExportOptions(options.includeRecent, format);
 	const serialize = options.serializeEvent ?? ((event) => (0, _loggerjs_core.safeJsonStringify)(event, options.stringify ?? {}));
-	const lines = [];
+	const exported = [];
 	let skippedCount = 0;
-	let from;
-	let to;
 	for await (const event of resolveSource(source, options.query)) {
-		if (maxEvents !== void 0 && lines.length >= maxEvents) break;
+		if (maxEvents !== void 0 && exported.length >= maxEvents) break;
 		const mapped = options.mapEvent ? options.mapEvent(event) : event;
 		if (!mapped) {
 			skippedCount += 1;
 			continue;
 		}
-		lines.push(serialize(mapped));
-		from = from === void 0 ? mapped.time : Math.min(from, mapped.time);
-		to = to === void 0 ? mapped.time : Math.max(to, mapped.time);
+		exported.push({
+			event: mapped,
+			line: serialize(mapped)
+		});
 	}
 	const files = [{
 		name: logFileName,
-		content: format === "json" ? `[${lines.join(",")}]` : lines.length > 0 ? `${lines.join("\n")}\n` : "",
+		content: logContentForLines(exported.map((item) => item.line), format),
 		lastModified: createdAt
 	}];
+	const sessionManifests = [];
+	if (sessionExportOptions) {
+		const groups = /* @__PURE__ */ new Map();
+		for (const item of exported) {
+			const sessionId = sessionIdForEvent(item.event, sessionExportOptions);
+			const group = groups.get(sessionId) ?? [];
+			group.push(item);
+			groups.set(sessionId, group);
+		}
+		const usedFileNames = new Set(files.map((file) => normalizeZipFileName(file.name)));
+		const sortedGroups = [...groups.entries()];
+		sortedGroups.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+		for (const [sessionId, group] of sortedGroups) {
+			let fileName = normalizeZipFileName(`${sessionExportOptions.directory}/${safeZipPathSegment(sessionId)}/${sessionExportOptions.logFileName}`);
+			let suffix = 1;
+			while (usedFileNames.has(fileName)) {
+				fileName = normalizeZipFileName(`${sessionExportOptions.directory}/${safeZipPathSegment(sessionId)}-${suffix}/${sessionExportOptions.logFileName}`);
+				suffix += 1;
+			}
+			usedFileNames.add(fileName);
+			const orderedGroup = sortByEventTime(group);
+			files.push({
+				name: fileName,
+				content: logContentForLines(orderedGroup.map((item) => item.line), format),
+				lastModified: createdAt
+			});
+			sessionManifests.push({
+				logCount: orderedGroup.length,
+				logFileName: fileName,
+				sessionId,
+				timeRange: eventTimeRange(orderedGroup)
+			});
+		}
+	}
+	let recentLogFileName;
+	if (recentExportOptions) {
+		const recentItems = recentExportOptions.maxEvents <= 0 ? [] : sortByEventTime(exported).slice(-recentExportOptions.maxEvents);
+		recentLogFileName = normalizeZipFileName(recentExportOptions.logFileName);
+		files.push({
+			name: recentLogFileName,
+			content: logContentForLines(recentItems.map((item) => item.line), format),
+			lastModified: createdAt
+		});
+	}
 	if (options.includeManifest ?? true) {
 		const manifest = {
 			schema: "loggerjs.log-export.v1",
@@ -1759,13 +2359,13 @@ async function exportLogsToZip(source, options = {}) {
 			source: options.source,
 			format,
 			logFileName: normalizeZipFileName(logFileName),
-			logCount: lines.length,
+			logCount: exported.length,
 			skippedCount,
 			query: options.query,
-			timeRange: from === void 0 || to === void 0 ? void 0 : {
-				from,
-				to
-			}
+			recentLogFileName,
+			sessionCount: sessionExportOptions ? sessionManifests.length : void 0,
+			sessions: sessionExportOptions ? sessionManifests : void 0,
+			timeRange: eventTimeRange(exported)
 		};
 		files.push({
 			name: options.manifestFileName ?? "manifest.json",