lopata 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "lopata",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"type": "module",
 	"license": "MIT",
 	"repository": {

package/src/plugin.ts

@@ -15,7 +15,21 @@ import { globalEnv } from './env'
 import { getActiveExecutionContext } from './execution-context'
 import { getActiveContext } from './tracing/context'
 import { instrumentBinding } from './tracing/instrument'
-import { addSpanEvent, setSpanAttribute, startSpan } from './tracing/span'
+import { addSpanEvent, persistError, setSpanAttribute, startSpan } from './tracing/span' // ─── Userland tracing API ────────────────────────────────────────────
+ // Exposes a lightweight global that user code can call to create custom
+// spans visible in the Lopata dashboard.  In production (without Lopata)
+// the global is simply absent, so the user's thin wrapper becomes a no-op.
+;(globalThis as any).__lopata = {
+	trace<T>(name: string, attrsOrFn: Record<string, unknown> | (() => T | Promise<T>), maybeFn?: () => T | Promise<T>): Promise<T> {
+		const fn = typeof attrsOrFn === 'function' ? attrsOrFn : maybeFn!
+		const attributes = typeof attrsOrFn === 'function' ? undefined : attrsOrFn
+		return startSpan({ name, attributes }, fn)
+	},
+	setAttribute: setSpanAttribute,
+	addEvent(name: string, message?: string, attrs?: Record<string, unknown>): void {
+		addSpanEvent(name, 'info', message ?? '', attrs)
+	},
+}
 
 // Register global `caches` object (CacheStorage) with tracing
 const rawCacheStorage = new SqliteCacheStorage(getDatabase())
@@ -151,6 +165,10 @@ for (const method of consoleMethods) {
 		if (!ctx) return
 		const message = args.map(formatConsoleArg).join(' ')
 		addSpanEvent(`console.${method}`, method, message)
+		if (method === 'error') {
+			const errorArg = args.find((a) => a instanceof Error)
+			persistError(errorArg ?? new Error(message), 'console.error')
+		}
 	}
 }
 

package/src/tracing/global.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lopata userland tracing API.
+ *
+ * Available on `globalThis.__lopata` when running under Lopata dev server.
+ * In production (Cloudflare Workers) the global is `undefined` — wrap calls
+ * in a thin helper that falls back to a no-op:
+ *
+ * ```ts
+ * // app/lib/trace.ts
+ * type TraceFn = <T>(name: string, fn: () => T | Promise<T>) => Promise<T>
+ *
+ * export const trace: TraceFn = (name, fn) =>
+ *   globalThis.__lopata?.trace(name, fn) ?? fn()
+ *
+ * export const setAttribute = (key: string, value: unknown) =>
+ *   globalThis.__lopata?.setAttribute(key, value)
+ *
+ * export const addEvent = (name: string, message?: string) =>
+ *   globalThis.__lopata?.addEvent(name, message)
+ * ```
+ *
+ * Add this file to your tsconfig types to get autocomplete:
+ * ```json
+ * { "compilerOptions": { "types": ["lopata/src/tracing/global"] } }
+ * ```
+ */
+
+interface LopataTracing {
+	/**
+	 * Create a traced span around `fn`. The span is visible in the Lopata
+	 * dashboard and becomes a child of the currently active span (if any).
+	 */
+	trace<T>(name: string, fn: () => T | Promise<T>): Promise<T>
+	/**
+	 * Create a traced span with custom attributes.
+	 */
+	trace<T>(name: string, attrs: Record<string, unknown>, fn: () => T | Promise<T>): Promise<T>
+
+	/**
+	 * Set an attribute on the currently active span.
+	 */
+	setAttribute(key: string, value: unknown): void
+
+	/**
+	 * Add an event (log entry) to the currently active span.
+	 */
+	addEvent(name: string, message?: string, attrs?: Record<string, unknown>): void
+}
+
+declare var __lopata: LopataTracing | undefined