@loggerjs/browser 0.5.1 → 0.5.3

package/dist/index.cjs

@@ -894,12 +894,96 @@ 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 = 3;
 const ORDER_INDEX_NAME = "createdAtSeq";
+const SESSION_INDEX_NAME = "sessionId";
+const SESSION_ORDER_INDEX_NAME = "sessionIdCreatedAtSeq";
+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();
 }
@@ -965,6 +1049,7 @@ 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;
@@ -972,6 +1057,21 @@ function shouldKeepEntry(entry, options) {
 }
 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,
@@ -1020,12 +1120,17 @@ 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 pendingFlushBatch;
+	let spillDrainPromise;
+	let localStorageSpillClearCandidate;
 	let lastContext;
 	let closed = false;
 	const statsState = {
@@ -1052,13 +1157,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 +1200,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 () => {
@@ -1124,6 +1251,13 @@ function indexedDbTransport(options = {}) {
 						"seq",
 						"id"
 					]);
+					ensureIndex(store, SESSION_INDEX_NAME, "sessionId");
+					ensureIndex(store, SESSION_ORDER_INDEX_NAME, [
+						"sessionId",
+						"createdAt",
+						"seq",
+						"id"
+					]);
 				});
 				request.addEventListener("success", () => {
 					statsState.databaseOpenCount += 1;
@@ -1214,7 +1348,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 +1361,31 @@ function indexedDbTransport(options = {}) {
 		});
 		return entries;
 	});
+	const listSessions = async (sessionQueryOptions = {}) => {
+		const sessions = /* @__PURE__ */ new Map();
+		for (const entry of await getEntries()) {
+			if (!entry.sessionId) continue;
+			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;
+			} else sessions.set(entry.sessionId, {
+				byteLength: entry.byteLength,
+				count: 1,
+				firstSeen: entry.createdAt,
+				lastSeen: entry.createdAt,
+				sessionId: entry.sessionId
+			});
+		}
+		const ordered = [...sessions.values()].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 (sessionQueryOptions.order !== "asc") ordered.reverse();
+		return ordered.slice(0, sessionQueryOptions.limit);
+	};
 	const pruneWithEntries = async () => {
 		const now = Date.now();
 		let entries = await getEntries();
@@ -1282,10 +1441,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,6 +1479,30 @@ 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();
@@ -1307,6 +1514,7 @@ function indexedDbTransport(options = {}) {
 			});
 			statsState.persisted += entries.length;
 			(0, _loggerjs_core.incrementLoggerMetaCounter)("transport.indexeddb.persisted", entries.length);
+			markLocalStorageSpillPersisted(events);
 			await prune();
 			statsState.flushes += 1;
 		} catch (error) {
@@ -1316,6 +1524,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 +1649,13 @@ 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;
+		flushPromise = (async () => {
+			await ensureSpillDrained();
+			await writeBatch(batch);
+		})().finally(() => {
+			if (pendingFlushBatch === batch) pendingFlushBatch = void 0;
 			flushPromise = void 0;
 			if (buffer.length > 0 && !closed) schedule();
 		});
@@ -1336,14 +1668,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",
@@ -1376,6 +1722,7 @@ function indexedDbTransport(options = {}) {
 		async clear() {
 			buffer.length = 0;
 			clearTimer();
+			clearLocalStorageSpill();
 			await withStore("readwrite", (store) => requestToPromise(store.clear()));
 		},
 		async remove(ids) {
@@ -1399,6 +1746,10 @@ function indexedDbTransport(options = {}) {
 				if (event) yield event;
 			}
 		},
+		async sessions(sessionQueryOptions = {}) {
+			await flushPending();
+			return listSessions(sessionQueryOptions);
+		},
 		stats() {
 			return snapshotStats();
 		},
@@ -1406,12 +1757,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 +1789,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 +1923,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 +2063,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 +2135,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 +2208,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",