@gscdump/lakehouse 4.2.1 → 4.2.2

package/dist/catalog-cache.d.mts

@@ -13,12 +13,14 @@ export interface CatalogCache {
   /** Optional warning sink for best-effort cache driver failures. */
   onError?: (operation: 'get' | 'set' | 'remove', key: string, error: unknown) => void;
 }
+/** Outcome of one cache read, including misses that still permit a fresh load. */
+export type CatalogCacheGetOutcome = 'hit' | 'miss' | 'expired' | 'invalid' | 'error';
 /**
  * Read a cached value. Returns `undefined` on a miss, an expired entry, a
  * malformed box, or any driver error (the cache is best-effort: a read failure
  * degrades to a fresh load, never to an error).
  */
-export declare function cacheGet<T>(cache: CatalogCache, key: string, now: number): Promise<T | undefined>;
+export declare function cacheGet<T>(cache: CatalogCache, key: string, now: number, onOutcome?: (outcome: CatalogCacheGetOutcome) => void): Promise<T | undefined>;
 /**
  * Write a cached value with an embedded expiry and a forwarded driver TTL.
  *

package/dist/catalog-cache.mjs

@@ -6,12 +6,37 @@ function reportCatalogCacheError(cache, operation, key, error) {
 		console.warn(`[gscdump/lakehouse] cache error reporter failed during ${operation} for ${key}`, reportError);
 	}
 }
-async function cacheGet(cache, key, now) {
-	const boxed = await cache.storage.getItem(key).catch((error) => {
+async function cacheGet(cache, key, now, onOutcome) {
+	const reportOutcome = (outcome) => {
+		try {
+			onOutcome?.(outcome);
+		} catch {}
+	};
+	const read = await cache.storage.getItem(key).then((boxed) => ({
+		_tag: "Ok",
+		boxed
+	}), (error) => {
 		reportCatalogCacheError(cache, "get", key, error);
-		return null;
+		return { _tag: "Error" };
 	});
-	if (!boxed || typeof boxed.exp !== "number" || boxed.exp <= now) return void 0;
+	if (read._tag === "Error") {
+		reportOutcome("error");
+		return;
+	}
+	const { boxed } = read;
+	if (!boxed) {
+		reportOutcome("miss");
+		return;
+	}
+	if (typeof boxed.exp !== "number" || boxed.v === void 0) {
+		reportOutcome("invalid");
+		return;
+	}
+	if (boxed.exp <= now) {
+		reportOutcome("expired");
+		return;
+	}
+	reportOutcome("hit");
 	return boxed.v;
 }
 function cachePut(cache, key, value, ttlMs, now) {

package/dist/catalog.d.mts

@@ -93,6 +93,8 @@ export interface ConnectIcebergOptions {
   cache?: CatalogCache;
   /** Injectable clock for the cache TTL. Defaults to `Date.now`. */
   clock?: () => number;
+  /** Optional connection-stage timings. Spans carry no catalog coordinates. */
+  profiler?: QueryProfiler;
 }
 /**
  * Connect to the R2 Data Catalog: a REST catalog context + a signed S3

package/dist/catalog.mjs

@@ -35,6 +35,20 @@ function manifestReadCacheFor(conn, namespace, table, metadata) {
 	}
 	return cache;
 }
+function startConnectSpan(profiler, name) {
+	if (!profiler) return void 0;
+	try {
+		const end = profiler.start(name);
+		if (!end) return void 0;
+		return (meta) => {
+			try {
+				end(meta);
+			} catch {}
+		};
+	} catch {
+		return;
+	}
+}
 let icebirdWriteModule;
 function useIcebirdWriteModule() {
 	icebirdWriteModule ??= import("./_virtual/node_modules/.pnpm/icebird@0.8.30_patch_hash=a400e343a199b1ca18601f96348011745ac6518fc07ffa71d5adfdd2ccc7d14f/node_modules/icebird/src/write/write.mjs");
@@ -49,7 +63,12 @@ async function connectIcebergCatalog(config, opts = {}) {
 	const requestInit = { headers: { Authorization: `Bearer ${config.catalogToken}` } };
 	let catalog;
 	if (opts.cache) {
-		const cached = await cacheGet(opts.cache, catalogConfigKey(config), now);
+		const endCache = startConnectSpan(opts.profiler, "catalog.config.cache");
+		const cacheRead = { outcome: "miss" };
+		const cached = await cacheGet(opts.cache, catalogConfigKey(config), now, (outcome) => {
+			cacheRead.outcome = outcome;
+		});
+		endCache?.({ outcome: cacheRead.outcome === "hit" && !cached ? "invalid" : cacheRead.outcome });
 		if (cached) catalog = Object.freeze({
 			type: "rest",
 			url: cached.url,
@@ -60,11 +79,18 @@ async function connectIcebergCatalog(config, opts = {}) {
 		});
 	}
 	if (!catalog) {
-		catalog = await restCatalogConnect({
-			url: config.catalogUri,
-			warehouse: config.warehouse,
-			requestInit
-		});
+		const endRest = startConnectSpan(opts.profiler, "catalog.config.rest");
+		let restOutcome = "error";
+		try {
+			catalog = await restCatalogConnect({
+				url: config.catalogUri,
+				warehouse: config.warehouse,
+				requestInit
+			});
+			restOutcome = "ok";
+		} finally {
+			endRest?.({ outcome: restOutcome });
+		}
 		if (opts.cache) {
 			const toCache = {
 				url: catalog.url,
@@ -72,7 +98,12 @@ async function connectIcebergCatalog(config, opts = {}) {
 				defaults: catalog.defaults,
 				overrides: catalog.overrides
 			};
-			await cachePut(opts.cache, catalogConfigKey(config), toCache, CATALOG_CONFIG_TTL_MS, now);
+			const endWrite = startConnectSpan(opts.profiler, "catalog.config.write");
+			try {
+				await cachePut(opts.cache, catalogConfigKey(config), toCache, CATALOG_CONFIG_TTL_MS, now);
+			} finally {
+				endWrite?.({ deferred: opts.cache.defer != null });
+			}
 		}
 	}
 	const cacheScope = catalogCacheScope(config);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/lakehouse",
   "type": "module",
-  "version": "4.2.1",
+  "version": "4.2.2",
   "description": "Dataset-agnostic Iceberg lakehouse layer + dataset registry for R2 Data Catalog producers (ADR-0021).",
   "author": {
     "name": "Harlan Wilton",