@thru/indexer 0.2.32 → 0.2.34

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { PgTableWithColumns, PgColumn } from 'drizzle-orm/pg-core';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { z } from 'zod';
-import { Filter, Event, AccountState, ChainClientFactory } from '@thru/replay';
+import { Filter, Event, AccountState, ChainClientFactory, ReplayLogger } from '@thru/replay';
 
 /**
  * Schema type definitions with improved type safety.
@@ -817,6 +817,8 @@ interface IndexerConfig {
     pageSize?: number;
     /** Log level (default: "info") */
     logLevel?: "debug" | "info" | "warn" | "error";
+    /** Optional structured logger for runtime, processor, and replay lifecycle logs. */
+    logger?: ReplayLogger;
     /** Human-readable endpoint label included in normalized stream errors */
     endpointLabel?: string;
     /** Initial supervisor restart backoff in milliseconds (default: 1000) */
@@ -886,11 +888,13 @@ interface IndexerResult {
  */
 declare class Indexer {
     private config;
+    private logger;
     private abortController;
     private running;
     private shutdownRequested;
     private startedAtMs;
     private streamStatuses;
+    private streamHealthStates;
     constructor(config: IndexerConfig);
     /**
      * Check if the checkpoint table exists in the database.
@@ -926,6 +930,9 @@ declare class Indexer {
     private statusKey;
     private statusFor;
     private resultForStream;
+    private setStreamState;
+    private streamLogFields;
+    private emitHealthTransitions;
     private createObserver;
     private runEventStreamSupervisor;
     private runAccountStreamSupervisor;

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { pgTable, timestamp, text, bigint, boolean, integer, index } from 'drizzle-orm/pg-core';
 import { z } from 'zod';
-import { createConsoleLogger, createEventReplay, createAccountsByOwnerReplay, AccountView } from '@thru/replay';
+import { createEventReplay, createAccountsByOwnerReplay, AccountView } from '@thru/replay';
 import { eq, sql } from 'drizzle-orm';
 import { encodeAddress } from '@thru/sdk/helpers';
 
@@ -299,6 +299,54 @@ function getSchemaExports(config) {
   return exports;
 }
 
+// src/runtime/logger.ts
+var LEVELS = ["debug", "info", "warn", "error"];
+function shouldLog(level, minimum) {
+  return LEVELS.indexOf(level) >= LEVELS.indexOf(minimum);
+}
+function writeConsole(prefix, level, message, meta) {
+  const text3 = `[${prefix}] ${message}`;
+  if (meta && Object.keys(meta).length > 0) {
+    if (level === "error") {
+      console.error(text3, meta);
+    } else if (level === "warn") {
+      console.warn(text3, meta);
+    } else {
+      console.log(text3, meta);
+    }
+    return;
+  }
+  if (level === "error") {
+    console.error(text3);
+  } else if (level === "warn") {
+    console.warn(text3);
+  } else {
+    console.log(text3);
+  }
+}
+function createScopedLogger(options) {
+  const minimum = options.level ?? "info";
+  const bindings = options.bindings ?? {};
+  const log = (level, message, meta) => {
+    if (!shouldLog(level, minimum)) {
+      return;
+    }
+    const hasMeta = meta !== void 0 && Object.keys(meta).length > 0;
+    const fields = { ...bindings, ...meta ?? {} };
+    if (options.logger) {
+      options.logger[level](message, fields);
+    } else {
+      writeConsole(options.prefix, level, message, hasMeta ? fields : void 0);
+    }
+  };
+  return {
+    debug: (message, meta) => log("debug", message, meta),
+    info: (message, meta) => log("info", message, meta),
+    warn: (message, meta) => log("warn", message, meta),
+    error: (message, meta) => log("error", message, meta)
+  };
+}
+
 // src/streams/processor.ts
 var StreamBatcher = class {
   currentSlot = null;
@@ -358,14 +406,21 @@ async function runEventStreamProcessor(stream, options, abortSignal) {
     safetyMargin = 64,
     pageSize = 512,
     logLevel = "info",
+    logger: baseLogger,
     validateParse = false,
     observer
   } = options;
-  const log = (level, msg) => {
-    if (logLevel === "debug" || level !== "debug") {
-      console.log(`[${stream.name}] ${msg}`);
+  const logger = createScopedLogger({
+    logger: baseLogger,
+    level: logLevel,
+    prefix: stream.name,
+    bindings: {
+      component: "indexer-stream",
+      stream: stream.name,
+      kind: "event"
     }
-  };
+  });
+  const log = (level, msg, meta) => logger[level](msg, meta);
   log("info", `Starting stream processor: ${stream.description}`);
   const checkpoint = await getCheckpoint(db, stream.name);
   const startSlot = checkpoint ? checkpoint.slot : defaultStartSlot;
@@ -377,13 +432,6 @@ async function runEventStreamProcessor(stream, options, abortSignal) {
     "info",
     `Starting from slot ${startSlot}${checkpoint ? " (resuming)" : " (fresh start)"}`
   );
-  const logger = logLevel === "debug" ? createConsoleLogger(stream.name) : {
-    debug: () => {
-    },
-    info: (msg) => log("info", msg),
-    warn: (msg) => log("warn", msg),
-    error: (msg) => log("error", msg)
-  };
   const replay = createEventReplay({
     clientFactory,
     startSlot,
@@ -392,7 +440,8 @@ async function runEventStreamProcessor(stream, options, abortSignal) {
     pageSize,
     filter: stream.getFilter(),
     logger,
-    resubscribeOnEnd: true
+    resubscribeOnEnd: true,
+    signal: abortSignal
   });
   const batcher = new StreamBatcher();
   const stats = {
@@ -610,20 +659,21 @@ function defineAccountStream(definition) {
     api: definition.api
   };
 }
-function shouldLog(level, minLevel) {
-  const levels = ["debug", "info", "warn", "error"];
-  return levels.indexOf(level) >= levels.indexOf(minLevel);
-}
 async function runAccountStreamProcessor(stream, options, abortSignal) {
-  const { clientFactory, db, logLevel = "info", validateParse = false, observer } = options;
+  const { clientFactory, db, logLevel = "info", logger: baseLogger, validateParse = false, observer } = options;
   const checkpointName = `account:${stream.name}`;
-  const log = (level, msg, meta) => {
-    if (shouldLog(level, logLevel)) {
-      {
-        console.log(`[account-stream:${stream.name}] ${msg}`);
-      }
+  const logger = createScopedLogger({
+    logger: baseLogger,
+    level: logLevel,
+    prefix: `account-stream:${stream.name}`,
+    bindings: {
+      component: "indexer-stream",
+      stream: stream.name,
+      kind: "account",
+      checkpoint_name: checkpointName
     }
-  };
+  });
+  const log = (level, msg, meta) => logger[level](msg, meta);
   const stats = {
     accountsProcessed: 0,
     accountsUpdated: 0,
@@ -642,18 +692,6 @@ async function runAccountStreamProcessor(stream, options, abortSignal) {
   if (stream.expectedSize) {
     log("info", `Expected data size: ${stream.expectedSize} bytes`);
   }
-  const replayLogger = logLevel === "debug" ? {
-    debug: (msg) => log("debug", msg),
-    info: (msg) => log("info", msg),
-    warn: (msg) => log("warn", msg),
-    error: (msg) => log("error", msg)
-  } : {
-    debug: () => {
-    },
-    info: (msg) => log("info", msg),
-    warn: (msg) => log("warn", msg),
-    error: (msg) => log("error", msg)
-  };
   let lastProcessedSlot = minUpdatedSlot ?? 0n;
   try {
     const replay = createAccountsByOwnerReplay({
@@ -662,7 +700,8 @@ async function runAccountStreamProcessor(stream, options, abortSignal) {
       view: AccountView.FULL,
       dataSizes: stream.dataSizes ?? (stream.expectedSize ? [stream.expectedSize] : void 0),
       minUpdatedSlot,
-      logger: replayLogger,
+      logger,
+      signal: abortSignal,
       onBackfillComplete: (highestSlot) => {
         log(
           "info",
@@ -868,11 +907,13 @@ function isRetryablePhase(phase) {
 // src/runtime/indexer.ts
 var Indexer = class {
   config;
+  logger;
   abortController = null;
   running = false;
   shutdownRequested = false;
   startedAtMs = null;
   streamStatuses = /* @__PURE__ */ new Map();
+  streamHealthStates = /* @__PURE__ */ new Map();
   constructor(config) {
     this.config = {
       defaultStartSlot: 0n,
@@ -884,6 +925,12 @@ var Indexer = class {
       streamStaleMs: 3e5,
       ...config
     };
+    this.logger = createScopedLogger({
+      logger: this.config.logger,
+      level: this.config.logLevel,
+      prefix: "indexer",
+      bindings: { component: "indexer-runtime" }
+    });
     this.initializeStreamStatuses();
   }
   /**
@@ -898,14 +945,14 @@ var Indexer = class {
     } catch (err) {
       const message = err instanceof Error ? err.cause instanceof Error ? err.cause.message : err.message : String(err);
       if (message.includes("does not exist") || message.includes("relation")) {
-        console.warn(
-          `[indexer] WARNING: Checkpoint table "indexer_checkpoints" not found.
-[indexer] Make sure to export checkpointTable from your Drizzle schema:
+        this.logger.warn(
+          `Checkpoint table "indexer_checkpoints" not found.
+Make sure to export checkpointTable from your Drizzle schema:
 
   // db/schema.ts
   export { checkpointTable } from "@thru/indexer";
 
-[indexer] Then run: pnpm drizzle-kit push (or generate + migrate)
+Then run: pnpm drizzle-kit push (or generate + migrate)
 `
         );
       }
@@ -942,15 +989,14 @@ var Indexer = class {
       validateParse,
       endpointLabel,
       supervisorInitialBackoffMs = 1e3,
-      supervisorMaxBackoffMs = 3e4
+      supervisorMaxBackoffMs = 3e4,
+      logger
     } = this.config;
-    console.log("[indexer] Starting indexer...");
-    console.log(
-      `[indexer] Running ${eventStreams.length} event stream(s): ${eventStreams.map((s) => s.name).join(", ") || "none"}`
-    );
-    console.log(
-      `[indexer] Running ${accountStreams.length} account stream(s): ${accountStreams.map((s) => s.name).join(", ") || "none"}`
-    );
+    this.logger.info("Starting indexer", {
+      event: "indexer.started",
+      event_streams: eventStreams.map((stream) => stream.name),
+      account_streams: accountStreams.map((stream) => stream.name)
+    });
     try {
       const supervisorOptions = {
         endpointLabel,
@@ -965,6 +1011,7 @@ var Indexer = class {
           safetyMargin,
           pageSize,
           logLevel,
+          logger,
           validateParse
         }, supervisorOptions)
       );
@@ -973,6 +1020,7 @@ var Indexer = class {
           clientFactory,
           db,
           logLevel,
+          logger,
           validateParse
         }, supervisorOptions)
       );
@@ -981,7 +1029,9 @@ var Indexer = class {
         eventStreams: eventStreams.map((stream) => this.resultForStream(stream.name)),
         accountStreams: accountStreams.map((stream) => this.resultForStream(stream.name))
       };
-      console.log("[indexer] All streams stopped.");
+      this.logger.info("All indexer streams stopped", {
+        event: "indexer.stopped"
+      });
       return result;
     } finally {
       this.running = false;
@@ -997,14 +1047,20 @@ var Indexer = class {
    */
   stop() {
     if (!this.running || !this.abortController) {
-      console.log("[indexer] Not running");
+      this.logger.info("Indexer is not running", {
+        event: "indexer.stop.noop"
+      });
       return;
     }
     if (this.shutdownRequested) {
-      console.log("[indexer] Force shutdown...");
+      this.logger.warn("Force shutting down indexer", {
+        event: "indexer.force_shutdown"
+      });
       process.exit(1);
     }
-    console.log("[indexer] Shutdown requested, finishing current batches...");
+    this.logger.info("Indexer shutdown requested", {
+      event: "indexer.shutdown_requested"
+    });
     this.shutdownRequested = true;
     this.abortController.abort();
   }
@@ -1025,6 +1081,7 @@ var Indexer = class {
       return stream;
     });
     const healthy = this.running && !this.shutdownRequested && streams.length > 0 && streams.every((stream) => stream.state === "running" && !stream.stale);
+    this.emitHealthTransitions(streams, now);
     return {
       running: this.running,
       shutdownRequested: this.shutdownRequested,
@@ -1036,6 +1093,7 @@ var Indexer = class {
   }
   initializeStreamStatuses() {
     this.streamStatuses = /* @__PURE__ */ new Map();
+    this.streamHealthStates = /* @__PURE__ */ new Map();
     for (const stream of this.config.eventStreams ?? []) {
       this.streamStatuses.set(this.statusKey("event", stream.name), this.createInitialStreamStatus("event", stream.name));
     }
@@ -1077,6 +1135,84 @@ var Indexer = class {
       status: "fulfilled"
     };
   }
+  setStreamState(status, nextState, meta = {}) {
+    const previousState = status.state;
+    status.state = nextState;
+    if (previousState === nextState) {
+      return;
+    }
+    this.logger.info("Indexer stream state changed", {
+      event: "indexer.stream.state_changed",
+      stream: status.name,
+      kind: status.kind,
+      previous_state: previousState,
+      next_state: nextState,
+      restart_count: status.restartCount,
+      ...meta
+    });
+  }
+  streamLogFields(stream) {
+    return {
+      stream: stream.name,
+      kind: stream.kind,
+      state: stream.state,
+      stale: stream.stale,
+      checkpoint_slot: stream.checkpointSlot,
+      last_processed_slot: stream.lastProcessedSlot,
+      last_event_at: stream.lastEventAt,
+      restart_count: stream.restartCount,
+      last_error_at: stream.lastErrorAt,
+      last_error: stream.lastError
+    };
+  }
+  emitHealthTransitions(streams, nowMs) {
+    if (!this.running || this.shutdownRequested) {
+      return;
+    }
+    for (const stream of streams) {
+      const key = this.statusKey(stream.kind, stream.name);
+      const unhealthy = stream.state !== "running" || stream.stale;
+      const previous = this.streamHealthStates.get(key);
+      const initialStarting = !previous && stream.state === "starting" && stream.restartCount === 0 && !stream.lastError;
+      if (initialStarting) {
+        this.streamHealthStates.set(key, {
+          unhealthy: false,
+          unhealthySinceMs: null
+        });
+        continue;
+      }
+      if (unhealthy && previous?.unhealthy !== true) {
+        this.streamHealthStates.set(key, {
+          unhealthy: true,
+          unhealthySinceMs: nowMs
+        });
+        this.logger.warn("Indexer stream unhealthy", {
+          event: "indexer.stream.unhealthy",
+          reason: stream.stale ? "stale" : "state",
+          ...this.streamLogFields(stream)
+        });
+        continue;
+      }
+      if (!unhealthy && previous?.unhealthy === true) {
+        this.streamHealthStates.set(key, {
+          unhealthy: false,
+          unhealthySinceMs: null
+        });
+        this.logger.info("Indexer stream recovered", {
+          event: "indexer.stream.recovered",
+          unhealthy_duration_ms: previous.unhealthySinceMs === null ? null : nowMs - previous.unhealthySinceMs,
+          ...this.streamLogFields(stream)
+        });
+        continue;
+      }
+      if (!previous) {
+        this.streamHealthStates.set(key, {
+          unhealthy,
+          unhealthySinceMs: unhealthy ? nowMs : null
+        });
+      }
+    }
+  }
   createObserver(kind, name, endpointLabel) {
     const status = this.statusFor(kind, name);
     let startSlot = null;
@@ -1085,7 +1221,10 @@ var Indexer = class {
       onStart: (info) => {
         startSlot = info.startSlot ?? null;
         checkpointSlot = info.checkpointSlot ?? null;
-        status.state = "running";
+        this.setStreamState(status, "running", {
+          start_slot: startSlot?.toString(),
+          checkpoint_slot: checkpointSlot?.toString() ?? null
+        });
         status.checkpointSlot = checkpointSlot === null ? null : checkpointSlot.toString();
         status.lastStartedAt = (/* @__PURE__ */ new Date()).toISOString();
       },
@@ -1157,23 +1296,26 @@ var Indexer = class {
     const status = this.statusFor(kind, name);
     while (!this.abortController?.signal.aborted) {
       const observer = this.createObserver(kind, name, options.endpointLabel);
-      status.state = attempt === 0 ? "starting" : "retrying";
+      this.setStreamState(status, attempt === 0 ? "starting" : "retrying", {
+        attempt
+      });
       status.lastStartedAt = (/* @__PURE__ */ new Date()).toISOString();
       try {
         const summary = await runOnce(observer);
         if (this.abortController?.signal.aborted) {
-          status.state = "stopped";
-          console.log(`[indexer] ${kind} stream "${name}" stopped: ${summary}`);
+          this.setStreamState(status, "stopped", { summary });
           return;
         }
         throw new Error(`${kind} stream "${name}" completed unexpectedly: ${summary}`);
       } catch (error) {
         if (this.abortController?.signal.aborted) {
-          status.state = "stopped";
+          this.setStreamState(status, "stopped");
           return;
         }
         status.restartCount++;
-        status.state = "retrying";
+        this.setStreamState(status, "retrying", {
+          restart_count: status.restartCount
+        });
         status.lastErrorAt = (/* @__PURE__ */ new Date()).toISOString();
         if (!status.lastError || status.lastError.phase === "supervisor") {
           status.lastError = normalizeIndexerError({
@@ -1185,15 +1327,21 @@ var Indexer = class {
           });
         }
         const backoffMs = this.supervisorBackoffMs(attempt, options.initialBackoffMs, options.maxBackoffMs);
-        console.error(
-          `[indexer] ${kind} stream "${name}" failed; restarting in ${backoffMs}ms:`,
-          error
-        );
+        this.logger.warn("Indexer stream supervisor restarting", {
+          event: "indexer.stream.supervisor_restart",
+          stream: name,
+          kind,
+          backoff_ms: backoffMs,
+          attempt: attempt + 1,
+          restart_count: status.restartCount,
+          error,
+          last_error: status.lastError
+        });
         attempt++;
         await this.delay(backoffMs, this.abortController.signal);
       }
     }
-    status.state = "stopped";
+    this.setStreamState(status, "stopped");
   }
   supervisorBackoffMs(attempt, initialMs, maxMs) {
     const base = Math.min(maxMs, initialMs * Math.pow(2, attempt));