@warlock.js/devtools 5.25.0

package/cjs/index.cjs

@@ -0,0 +1,694 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_core = require("@warlock.js/core");
+let _warlock_js_logger = require("@warlock.js/logger");
+let node_url = require("node:url");
+
+//#region ../devtools/src/n-plus-one.ts
+/** Finds repeated query shapes whose occurrence count reaches the supplied threshold. */
+function detectNPlusOne(queries, threshold) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const query of queries) groups.set(query.shape, [...groups.get(query.shape) ?? [], query]);
+	return [...groups.entries()].filter(([, grouped]) => grouped.length >= threshold).sort(([, left], [, right]) => right.length - left.length).map(([shape, grouped]) => ({
+		type: "n+1",
+		shape,
+		count: grouped.length,
+		message: `N+1: ${grouped.length}× "${truncate(shape, 120)}"`,
+		...mostFrequentCaller(grouped) ? { caller: mostFrequentCaller(grouped) } : {}
+	}));
+}
+function truncate(value, maximum) {
+	return value.length > maximum ? `${value.slice(0, maximum - 1)}…` : value;
+}
+function mostFrequentCaller(queries) {
+	const callers = /* @__PURE__ */ new Map();
+	for (const query of queries) {
+		if (!query.caller) continue;
+		const key = `${query.caller.file}:${query.caller.line}`;
+		const found = callers.get(key);
+		callers.set(key, found ? {
+			...found,
+			count: found.count + 1
+		} : {
+			caller: query.caller,
+			count: 1
+		});
+	}
+	return [...callers.values()].sort((left, right) => right.count - left.count)[0]?.caller;
+}
+
+//#endregion
+//#region ../devtools/src/query-shape.ts
+const numericLiteral = /(?<![\w$])[-+]?(?:\d+(?:\.\d+)?|\.\d+)(?![\w$])/g;
+const quotedLiteral = /'(?:''|[^'])*'/g;
+/** Returns a binding-independent shape for a database query. */
+function queryShape(query) {
+	if (query.driver === "postgres") return (query.sql ?? "").replace(quotedLiteral, "?").replace(numericLiteral, "?").replace(/\s+/g, " ").trim();
+	return `${query.collection ?? ""}.${query.command ?? ""} ${JSON.stringify(normalizeMongoValue(query.pipeline))}`;
+}
+function normalizeMongoValue(value) {
+	if (isMongoLeaf(value)) return "?";
+	if (Array.isArray(value)) {
+		if (value.every(isMongoLeaf)) return ["?"];
+		return value.map(normalizeMongoValue);
+	}
+	const record = value;
+	return Object.fromEntries(Object.keys(record).map((key) => [key, normalizeMongoValue(record[key])]));
+}
+function isMongoLeaf(value) {
+	if (value === null || typeof value !== "object") return true;
+	if (value instanceof Date) return true;
+	const record = value;
+	return typeof record.toHexString === "function" || typeof record.$oid === "string";
+}
+
+//#endregion
+//#region ../devtools/src/collector.ts
+const mailLimit = 100;
+const logLimit = 1e3;
+const backgroundLimit = 500;
+/**
+* Creates the in-memory devtools store.
+*
+* Read methods return shallow structural copies, including copied arrays, so consumers
+* cannot mutate collector-owned arrays. The individual nested entries are retained.
+*/
+function createCollector(options) {
+	const requests = /* @__PURE__ */ new Map();
+	const mails = /* @__PURE__ */ new Map();
+	const logs = [];
+	const background = {
+		queries: [],
+		cache: [],
+		logs: []
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	let querySequence = 0;
+	const emit = (event) => {
+		for (const listener of listeners) try {
+			listener(event);
+		} catch {}
+	};
+	const addBackground = (list, value) => {
+		list.push(value);
+		if (list.length > backgroundLimit) list.shift();
+	};
+	return {
+		startRequest(request) {
+			requests.delete(request.id);
+			requests.set(request.id, {
+				...request,
+				phases: [],
+				queries: [],
+				cache: [],
+				logs: [],
+				mails: [],
+				warnings: []
+			});
+			while (requests.size > options.maxRequests) requests.delete(requests.keys().next().value);
+		},
+		endRequest(id, result) {
+			const request = requests.get(id);
+			if (!request) return;
+			request.status = result.status;
+			request.durationMs = result.durationMs;
+			request.error = result.error;
+			if (result.route !== void 0) request.route = result.route;
+			request.warnings = detectNPlusOne(request.queries, options.nPlusOneThreshold);
+			emit({
+				type: "request",
+				data: summary(request)
+			});
+		},
+		addPhase(requestId, phase) {
+			requests.get(requestId)?.phases.push(phase);
+		},
+		addQuery(requestId, query) {
+			const stored = {
+				...query,
+				id: `q${++querySequence}`,
+				shape: queryShape(query)
+			};
+			const request = requestId ? requests.get(requestId) : void 0;
+			if (request) request.queries.push(stored);
+			else addBackground(background.queries, stored);
+			return stored;
+		},
+		addCacheOperation(requestId, operation) {
+			const request = requestId ? requests.get(requestId) : void 0;
+			if (request) request.cache.push(operation);
+			else addBackground(background.cache, operation);
+		},
+		addLog(requestId, entry) {
+			const request = requestId ? requests.get(requestId) : void 0;
+			if (request) request.logs.push(entry);
+			else addBackground(background.logs, entry);
+			logs.unshift(entry);
+			if (logs.length > logLimit) logs.pop();
+			emit({
+				type: "log",
+				data: entry
+			});
+		},
+		addMail(mail) {
+			mails.delete(mail.id);
+			mails.set(mail.id, mail);
+			while (mails.size > mailLimit) mails.delete(mails.keys().next().value);
+			if (mail.requestId) requests.get(mail.requestId)?.mails.push(mail.id);
+			emit({
+				type: "mail",
+				data: mailSummary(mail)
+			});
+		},
+		listRequests() {
+			return [...requests.values()].reverse().map(summary);
+		},
+		getRequest(id) {
+			const request = requests.get(id);
+			return request && copyRequest(request);
+		},
+		listMails() {
+			return [...mails.values()].reverse().map(mailSummary);
+		},
+		getMail(id) {
+			const mail = mails.get(id);
+			return mail && {
+				...mail,
+				to: [...mail.to],
+				cc: [...mail.cc],
+				bcc: [...mail.bcc],
+				headers: { ...mail.headers },
+				attachments: [...mail.attachments]
+			};
+		},
+		listLogs(filter = {}) {
+			const module = filter.module?.toLowerCase();
+			return logs.filter((entry) => (!filter.level || entry.level === filter.level) && (!module || entry.module.toLowerCase().includes(module))).map((entry) => ({ ...entry }));
+		},
+		getBackground() {
+			return {
+				queries: [...background.queries],
+				cache: [...background.cache],
+				logs: [...background.logs]
+			};
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		clear() {
+			requests.clear();
+			mails.clear();
+			logs.length = 0;
+			background.queries.length = 0;
+			background.cache.length = 0;
+			background.logs.length = 0;
+		}
+	};
+}
+function summary(request) {
+	const { id, method, path, route, status, startedAt, durationMs } = request;
+	return {
+		id,
+		method,
+		path,
+		route,
+		status,
+		startedAt,
+		durationMs,
+		queryCount: request.queries.length,
+		warningCount: request.warnings.length
+	};
+}
+function mailSummary(mail) {
+	const { id, requestId, capturedAt, to, subject } = mail;
+	return {
+		id,
+		requestId,
+		capturedAt,
+		to: [...to],
+		subject
+	};
+}
+function copyRequest(request) {
+	return {
+		...request,
+		phases: [...request.phases],
+		queries: [...request.queries],
+		cache: [...request.cache],
+		logs: [...request.logs],
+		mails: [...request.mails],
+		warnings: [...request.warnings]
+	};
+}
+
+//#endregion
+//#region ../devtools/src/options.ts
+/** Resolves dashboard options and rejects invalid capacity or URL-prefix values. */
+function resolveDevtoolsOptions(options = {}) {
+	const path = (options.path ?? "/__warlock").replace(/\/+$/, "");
+	const maxRequests = options.maxRequests ?? 200;
+	const nPlusOneThreshold = options.nPlusOneThreshold ?? 5;
+	if (!path || !path.startsWith("/")) throw new Error("Devtools option \"path\" must be a non-root path starting with \"/\".");
+	if (maxRequests < 1) throw new Error("Devtools option \"maxRequests\" must be at least 1.");
+	if (nPlusOneThreshold < 2) throw new Error("Devtools option \"nPlusOneThreshold\" must be at least 2.");
+	return {
+		path,
+		maxRequests,
+		nPlusOneThreshold
+	};
+}
+
+//#endregion
+//#region ../devtools/src/current-request-id.ts
+/**
+* The current request's id (core's `request.id`, threaded through
+* `AsyncLocalStorage`), or `undefined` outside a request — sources feed
+* devtools' background bucket in that case.
+*
+* Only ever reached through `./sources/*`, which the connector imports
+* dynamically inside `boot()` — by then core is already running, so this
+* static import never drags core's runtime graph into config-load time (see
+* `devtools-connector.ts`).
+*/
+function currentRequestId() {
+	try {
+		return _warlock_js_core.requestContext.getRequest()?.id;
+	} catch {
+		return;
+	}
+}
+
+//#endregion
+//#region ../devtools/src/sources/cache-source.ts
+/** Cache events the dashboard's waterfall and background bucket care about. */
+const EVENT_TYPES = [
+	"hit",
+	"miss",
+	"set",
+	"removed",
+	"invalidated",
+	"flushed"
+];
+/**
+* Feeds cache hits, misses and mutations, from `@warlock.js/cache`, into the
+* collector. A no-op when `@warlock.js/cache` isn't installed — it is an
+* optional peer.
+*/
+async function attachCacheSource(collector) {
+	let cache;
+	try {
+		({cache} = await import("@warlock.js/cache"));
+	} catch {
+		return () => {};
+	}
+	const handlers = EVENT_TYPES.map((type) => {
+		const handler = (data) => {
+			const operation = {
+				type,
+				driver: data.driver,
+				key: data.key,
+				tags: data.tags,
+				keys: data.keys,
+				at: Date.now(),
+				durationMs: data.durationMs
+			};
+			collector.addCacheOperation(currentRequestId(), operation);
+		};
+		cache.on(type, handler);
+		return {
+			type,
+			handler
+		};
+	});
+	return () => {
+		for (const { type, handler } of handlers) cache.off(type, handler);
+	};
+}
+
+//#endregion
+//#region ../devtools/src/safe-value.ts
+const MAX_DEPTH = 6;
+/**
+* A JSON-safe snapshot of a value devtools keeps for later display.
+*
+* Log contexts and phase attributes are app data: they can hold live objects
+* (a request, its socket) whose graphs are circular and which must not be kept
+* alive by the collector anyway. Plain objects and arrays are copied; anything
+* with a `toJSON()` is serialized through it; other class instances collapse
+* to `[ClassName]`, cycles to `[Circular]`, and nesting past a fixed depth to
+* `[Object]` / `[Array]`.
+*/
+function toSafeValue(value) {
+	return snapshot(value, 0, /* @__PURE__ */ new WeakSet());
+}
+function snapshot(value, depth, seen) {
+	if (value === null || value === void 0) return value;
+	switch (typeof value) {
+		case "string":
+		case "number":
+		case "boolean": return value;
+		case "bigint": return value.toString();
+		case "symbol": return value.toString();
+		case "function": return;
+	}
+	const object = value;
+	if (seen.has(object)) return "[Circular]";
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+	if (value instanceof Error) return {
+		name: value.name,
+		message: value.message
+	};
+	if (depth >= MAX_DEPTH) return Array.isArray(value) ? "[Array]" : "[Object]";
+	seen.add(object);
+	try {
+		if (Array.isArray(value)) return value.map((item) => snapshot(item, depth + 1, seen));
+		const prototype = Object.getPrototypeOf(object);
+		if (prototype !== Object.prototype && prototype !== null) {
+			const toJSON = object.toJSON;
+			if (typeof toJSON === "function") try {
+				return snapshot(toJSON.call(object), depth + 1, seen);
+			} catch {
+				return `[${constructorName(object)}]`;
+			}
+			return `[${constructorName(object)}]`;
+		}
+		const copy = {};
+		for (const [key, entry] of Object.entries(object)) {
+			const safe = snapshot(entry, depth + 1, seen);
+			if (safe !== void 0) copy[key] = safe;
+		}
+		return copy;
+	} finally {
+		seen.delete(object);
+	}
+}
+function constructorName(object) {
+	return object.constructor?.name || "Object";
+}
+
+//#endregion
+//#region ../devtools/src/sources/log-source.ts
+/** `LoggingData.type` includes `fatal`, which devtools folds into `error`. */
+function toDevtoolsLevel(type) {
+	return type === "fatal" ? "error" : type;
+}
+var DevtoolsLogChannel = class extends _warlock_js_logger.LogChannel {
+	constructor(collector) {
+		super();
+		this.collector = collector;
+		this.name = "devtools";
+		this.active = true;
+	}
+	log(data) {
+		if (!this.active) return;
+		const entry = {
+			level: toDevtoolsLevel(data.type),
+			module: data.module,
+			action: data.action,
+			message: data.message,
+			at: Date.now(),
+			context: toSafeValue(data.context)
+		};
+		this.collector.addLog(currentRequestId(), entry);
+	}
+};
+/**
+* Feeds every log entry, from `@warlock.js/logger`, into the collector by
+* registering an additional channel. `Logger` has no way to remove a
+* channel, so the disposer flag-ignores further entries instead — the
+* channel stays registered for the process's lifetime.
+*/
+async function attachLogSource(collector) {
+	const channel = new DevtoolsLogChannel(collector);
+	_warlock_js_logger.log.addChannel(channel);
+	return () => {
+		channel.active = false;
+	};
+}
+
+//#endregion
+//#region ../devtools/src/sources/mail-source.ts
+function addressToString(address) {
+	if (!address) return void 0;
+	return typeof address === "string" ? address : `${address.name} <${address.address}>`;
+}
+function attachmentSize(attachment) {
+	if (typeof attachment.content === "string") return Buffer.byteLength(attachment.content);
+	if (Buffer.isBuffer(attachment.content)) return attachment.content.length;
+}
+function toDevtoolsAttachment(attachment) {
+	return {
+		filename: attachment.filename,
+		contentType: attachment.contentType,
+		size: attachmentSize(attachment)
+	};
+}
+/**
+* Feeds mails captured in development mode, from core's `mailEvents`, into
+* the collector. The captured attachments carry their content, but only
+* metadata is stored — the bytes are never kept.
+*/
+async function attachMailSource(collector) {
+	const { mailEvents } = await import("@warlock.js/core");
+	const subscription = mailEvents.onCaptured((mail) => {
+		const { normalized } = mail;
+		collector.addMail({
+			id: mail.id,
+			requestId: currentRequestId(),
+			capturedAt: mail.timestamp.getTime(),
+			from: addressToString(normalized.from),
+			to: normalized.to,
+			cc: normalized.cc,
+			bcc: normalized.bcc,
+			subject: normalized.subject,
+			html: normalized.html,
+			text: normalized.text,
+			headers: normalized.headers,
+			attachments: normalized.attachments.map(toDevtoolsAttachment)
+		});
+	});
+	return () => subscription.unsubscribe();
+}
+
+//#endregion
+//#region ../devtools/src/caller-location.ts
+const packageDirectory = normalizePath((0, node_url.fileURLToPath)(new URL("../", require("url").pathToFileURL(__filename).href)));
+/** Returns the first non-runtime, non-devtools frame in a V8 stack trace. */
+function captureCallerLocation(stack = (/* @__PURE__ */ new Error()).stack ?? "") {
+	for (const line of stack.split("\n")) {
+		const frame = parseFrame(line);
+		if (!frame || shouldSkip(frame.file)) continue;
+		return frame;
+	}
+}
+function parseFrame(frame) {
+	const [, rawFile, line, column] = frame.match(/\bat\s+(?:.*?\s+\()?(.+?):(\d+):(\d+)\)?\s*$/) ?? [];
+	if (!rawFile || !line || !column) return void 0;
+	return {
+		file: normalizePath(rawFile),
+		line: Number(line),
+		column: Number(column)
+	};
+}
+/** A drive-letter file URL names a Windows path on whichever host decodes it. */
+const WINDOWS_DRIVE_FILE_URL = /^file:\/\/\/[A-Za-z]:/;
+function normalizePath(path) {
+	return (!path.startsWith("file:") ? path : WINDOWS_DRIVE_FILE_URL.test(path) ? (0, node_url.fileURLToPath)(path, { windows: true }) : (0, node_url.fileURLToPath)(path)).replace(/\\/g, "/");
+}
+function shouldSkip(file) {
+	return file.startsWith("node:") || file.includes("/node_modules/") || file.startsWith("internal/") || file.startsWith(packageDirectory);
+}
+
+//#endregion
+//#region ../devtools/src/sources/query-source.ts
+/** Redacts query bindings through the logger's redaction rules. */
+function redactBindings(bindings) {
+	if (!bindings) return bindings;
+	return (0, _warlock_js_logger.applyRedact)({
+		type: "debug",
+		module: "devtools",
+		action: "query",
+		message: void 0,
+		context: { bindings }
+	}, _warlock_js_logger.log.getRedact()).context.bindings;
+}
+/**
+* Feeds every settled database query, from cascade's data source registry,
+* into the collector. A no-op when `@warlock.js/cascade` isn't installed —
+* it is an optional peer.
+*/
+async function attachQuerySource(collector) {
+	let dataSourceRegistry;
+	try {
+		({dataSourceRegistry} = await import("@warlock.js/cascade"));
+	} catch {
+		return () => {};
+	}
+	const listener = (event) => {
+		collector.addQuery(currentRequestId(), {
+			connection: event.connection,
+			driver: event.driver,
+			sql: event.sql,
+			bindings: toSafeValue(redactBindings(event.bindings)),
+			collection: event.collection,
+			command: event.command,
+			pipeline: event.pipeline,
+			startedAt: event.startedAt,
+			durationMs: event.durationMs,
+			rowCount: event.rowCount,
+			error: event.error === void 0 ? void 0 : event.error instanceof Error ? event.error.message : String(event.error),
+			caller: captureCallerLocation()
+		});
+	};
+	dataSourceRegistry.on("query", listener);
+	return () => dataSourceRegistry.off("query", listener);
+}
+
+//#endregion
+//#region ../devtools/src/sources/tracing-source.ts
+/**
+* Feeds request timelines from core's tracing hooks into the collector: one
+* `startRequest`/`endRequest` pair per HTTP request, with every named phase
+* in between. Requests to the dashboard's own path are never recorded, so
+* the dashboard never watches itself.
+*/
+async function attachTracingSource(collector, options) {
+	const { registerTracingHooks } = await import("@warlock.js/core");
+	const isDashboardPath = (path) => path.startsWith(options.path);
+	return registerTracingHooks({
+		onRequestStart(ctx) {
+			if (isDashboardPath(ctx.path)) return;
+			collector.startRequest({
+				id: ctx.requestId,
+				method: ctx.method,
+				path: ctx.path,
+				route: ctx.route,
+				startedAt: performance.timeOrigin + performance.now()
+			});
+		},
+		onPhase(ctx, phase) {
+			if (isDashboardPath(ctx.path)) return;
+			collector.addPhase(ctx.requestId, {
+				name: phase.name,
+				durationMs: phase.durationMs,
+				startedAt: phase.startedAt ?? performance.timeOrigin + performance.now() - phase.durationMs,
+				attrs: phase.attrs === void 0 ? void 0 : toSafeValue(phase.attrs)
+			});
+		},
+		onRequestEnd(ctx, result) {
+			if (isDashboardPath(ctx.path)) return;
+			collector.endRequest(ctx.requestId, {
+				status: result.status,
+				durationMs: result.durationMs,
+				error: result.error === void 0 ? void 0 : result.error instanceof Error ? result.error.message : String(result.error),
+				route: ctx.route
+			});
+		}
+	});
+}
+
+//#endregion
+//#region ../devtools/src/devtools-connector.ts
+/**
+* Boots after the queue connector (priority 11), which is the last
+* built-in/framework connector to claim a priority; devtools has nothing
+* that depends on it, so it simply goes last.
+*/
+const DEVTOOLS_CONNECTOR_PRIORITY = 12;
+/**
+* Construct the devtools connector.
+*
+* Refuses to run outside development: `boot()` checks
+* `Application.runtimeStrategy` and, when it isn't `"development"`, logs one
+* warning and returns without mounting a route or subscribing to anything.
+* In development it attaches every source (tracing, queries, cache, mail,
+* logs), then mounts the dashboard's routes on the HTTP server — before it
+* starts listening, the only point in the boot sequence where mounting is
+* possible (see `queue/src/dashboard-boot.ts` for the same constraint).
+*
+* Apps don't call this: `warlock dev` registers it automatically when the
+* package is installed (`warlock add devtools`). Keep it OUT of
+* `warlock.config.ts` — devtools is a dev dependency, so a production
+* install doesn't have it and a config import of it would fail there.
+*/
+function devtoolsConnector(options = {}) {
+	let active = false;
+	const disposers = [];
+	const connector = {
+		name: "devtools",
+		priority: 12,
+		lifecyclePhase: "late",
+		isActive: () => active,
+		async boot() {
+			const { Application, getHttpServer } = await import("@warlock.js/core");
+			const { log } = await import("@warlock.js/logger");
+			if (Application.runtimeStrategy !== "development") {
+				log.warn("devtools", "disabled", "@warlock.js/devtools only runs in development; it is not mounted");
+				return;
+			}
+			const resolved = resolveDevtoolsOptions(options);
+			const collector = createCollector(resolved);
+			await attachSource(log, "tracing", () => attachTracingSource(collector, resolved));
+			await attachSource(log, "query", () => attachQuerySource(collector));
+			await attachSource(log, "cache", () => attachCacheSource(collector));
+			await attachSource(log, "mail", () => attachMailSource(collector));
+			await attachSource(log, "log", () => attachLogSource(collector));
+			const { mountDevtoolsRoutes } = await Promise.resolve().then(() => require("./server-DHYSVive.cjs"));
+			mountDevtoolsRoutes(getHttpServer(), {
+				collector,
+				options: resolved,
+				isDevelopment: () => Application.runtimeStrategy === "development",
+				explain: (query) => explainQuery(query),
+				listRoutes: () => listRoutes()
+			});
+			disposers.push(collector.subscribe((event) => {
+				if (event.type !== "request" || event.data.warningCount === 0) return;
+				for (const warning of collector.getRequest(event.data.id)?.warnings ?? []) {
+					const where = warning.caller ? ` — ${warning.caller.file}:${warning.caller.line}` : "";
+					log.warn("devtools", "n+1", `${warning.message}${where} (${event.data.method} ${event.data.path})`);
+				}
+			}));
+			active = true;
+			log.info("devtools", "ready", `devtools ready at ${resolved.path}`);
+		},
+		async start() {},
+		async restart() {
+			await connector.shutdown();
+			await connector.start();
+		},
+		async shutdown() {
+			for (const dispose of disposers.splice(0)) dispose();
+			active = false;
+		},
+		shouldRestart: () => false
+	};
+	/** Attaches one source, logging and continuing when it fails to attach. */
+	async function attachSource(logger, name, attach) {
+		try {
+			disposers.push(await attach());
+		} catch (error) {
+			logger.warn("devtools", "source-failed", `devtools' ${name} source failed to attach: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return connector;
+}
+/** Runs `EXPLAIN (FORMAT JSON)` for a stored Postgres query on its own connection. */
+async function explainQuery(query) {
+	const { dataSourceRegistry } = await import("@warlock.js/cascade");
+	const { rows } = await dataSourceRegistry.get(query.connection).raw(`EXPLAIN (FORMAT JSON) ${query.sql}`, query.bindings);
+	return rows;
+}
+/** Lists every registered HTTP route — the same source `warlock routes --json` reads. */
+async function listRoutes() {
+	const { router } = await import("@warlock.js/core");
+	return router.list().map((route) => ({
+		method: route.method.toUpperCase(),
+		path: route.path,
+		name: route.name,
+		middleware: route.middleware?.map((middleware) => middleware.name || "anonymous")
+	}));
+}
+
+//#endregion
+exports.devtoolsConnector = devtoolsConnector;
+//# sourceMappingURL=index.cjs.map