@loggerjs/browser 0.5.1 → 0.5.3

package/dist/offline-first-transport.cjs

@@ -3,12 +3,96 @@ let _loggerjs_core = require("@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 = 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,
+		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 : (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() {
 	return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
 }
@@ -74,6 +158,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;
@@ -81,6 +166,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,
@@ -129,12 +229,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 = {
@@ -161,13 +266,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 }
 	});
@@ -194,6 +309,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 () => {
@@ -233,6 +360,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;
@@ -323,7 +457,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;
@@ -336,6 +470,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();
@@ -391,10 +550,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,
@@ -405,6 +588,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();
@@ -416,6 +623,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) {
@@ -425,6 +633,124 @@ function indexedDbTransport(options = {}) {
 			statsState.lastFlushDurationMs = nowMs() - 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;
@@ -432,7 +758,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();
 		});
@@ -445,14 +777,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",
@@ -485,6 +831,7 @@ function indexedDbTransport(options = {}) {
 		async clear() {
 			buffer.length = 0;
 			clearTimer();
+			clearLocalStorageSpill();
 			await withStore("readwrite", (store) => requestToPromise(store.clear()));
 		},
 		async remove(ids) {
@@ -508,6 +855,10 @@ function indexedDbTransport(options = {}) {
 				if (event) yield event;
 			}
 		},
+		async sessions(sessionQueryOptions = {}) {
+			await flushPending();
+			return listSessions(sessionQueryOptions);
+		},
 		stats() {
 			return snapshotStats();
 		},
@@ -515,12 +866,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());
 			});
 		}
 	};
@@ -547,12 +898,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,