envio 3.13.0-rc.0 → 3.14.0

package/src/HandlerLoader.res

@@ -1,20 +1,37 @@
 @module("node:fs/promises")
 external globIterator: string => Utils.asyncIterator<string> = "glob"
 
-// Register tsx for TypeScript handler support
-// Wrapped in try-catch because if tsx is already loaded via --import (e.g., in tests),
-// calling module.register again will throw an error
-try {
-  NodeJs.Module.register("tsx/esm", NodeJs.ImportMeta.url)
-} catch {
-| _ => () // tsx already loaded, ignore
+type tsHooksAddon = {
+  loadTs: string => string,
+  tsResolveCandidates: (string, Null.t<string>) => array<string>,
+  tsNotFoundCandidates: (string, Null.t<string>, string) => array<string>,
 }
 
-// Convert a relative path to a file:// URL for dynamic import
-// Paths are resolved relative to process.cwd() (project root)
-let toImportUrl = (relativePath: string) => {
-  let absolutePath = NodeJs.Path.resolve([NodeJs.Process.cwd(), relativePath])->NodeJs.Path.toString
-  NodeJs.Url.pathToFileURL(absolutePath)->NodeJs.Url.toString
+@module("./TsModuleHooks.mjs")
+external registerTsHooksWith: tsHooksAddon => unit = "register"
+
+// The resolve hook calls into the addon, and loading the addon goes through
+// the resolve hook, so the addon has to be loaded before the hooks exist.
+let registerTsHooks = () => {
+  let addon = Core.getAddon()
+  registerTsHooksWith({
+    loadTs: addon.loadTs,
+    tsResolveCandidates: addon.tsResolveCandidates,
+    tsNotFoundCandidates: addon.tsNotFoundCandidates,
+  })
+}
+
+let isTypeScript = file => /\.m?tsx?$/->RegExp.test(file)
+
+// Paths are relative to the project root, which is the working directory.
+let toAbsolutePath = (file: string) =>
+  NodeJs.Path.resolve([NodeJs.Process.cwd(), file])->NodeJs.Path.toString
+
+let importHandler = async file => {
+  if isTypeScript(file) {
+    Core.getAddon().tsCheckHandlerFormat(toAbsolutePath(file))
+  }
+  await Utils.importPath(toAbsolutePath(file)->NodeJs.Url.pathToFileURL->NodeJs.Url.toString)
 }
 
 let registerContractHandlers = async (~contractName, ~handler: option<string>) => {
@@ -22,7 +39,7 @@ let registerContractHandlers = async (~contractName, ~handler: option<string>) =
   | None => ()
   | Some(handlerPath) =>
     try {
-      let _ = await Utils.importPath(toImportUrl(handlerPath))
+      let _ = await importHandler(handlerPath)
     } catch {
     | exn =>
       let cause = exn->Utils.prettifyExn->Obj.magic
@@ -37,10 +54,9 @@ let registerContractHandlers = async (~contractName, ~handler: option<string>) =
   }
 }
 
-let autoLoadFromSrcHandlers = async (~handlers: string) => {
-  // Relative to cwd (project root)
-  let srcPattern = `./${handlers}/**/*.{js,mjs,ts}`
-  let handlerFiles = try {
+let getAutoLoadFiles = async (~config: Config.t) => {
+  let srcPattern = `./${config.handlers}/**/*.{js,mjs,ts}`
+  try {
     let iterator = globIterator(srcPattern)
     let files = await iterator->Utils.Array.fromAsyncIterator
     // Filter out test and spec files
@@ -54,22 +70,38 @@ let autoLoadFromSrcHandlers = async (~handlers: string) => {
   } catch {
   | exn =>
     JsError.throwWithMessage(
-      `Failed to glob src/handlers directory for auto-loading handlers. Pattern: ${srcPattern}. Before continuing, check that you're using Node.js >=22 version. Error: ${exn
+      `Failed to glob src/handlers directory for auto-loading handlers. Pattern: ${srcPattern}. Error: ${exn
         ->Utils.prettifyExn
         ->Obj.magic}`,
     )
   }
+}
 
-  // Import handler files using absolute file:// URLs resolved from cwd
-  let _ = await handlerFiles
-  ->Array.map(file => {
-    Utils.importPath(toImportUrl(file))->Promise.catch(exn => {
-      let cause = exn->Utils.prettifyExn->Obj.magic
-      Logging.errorWithExn(exn, `Failed to auto-load handler file: ${file}`)
-      JsError.throwWithMessage(`Failed to auto-load handler file: ${file}. Cause: ${cause}`)
-    })
-  })
-  ->Promise.all
+type typeCheckResult = {
+  skipped?: string,
+  errors?: string,
+}
+
+@module("./HandlerTypeCheck.mjs")
+external checkTypesInWorker: (~cwd: string, ~files: array<string>) => promise<typeCheckResult> =
+  "check"
+
+let typeCheck = async (~config: Config.t, ~autoLoadFiles) => {
+  // A contract's `handler:` may also be an auto-loaded file.
+  let files =
+    autoLoadFiles
+    ->Array.concat(config.contractHandlers->Array.filterMap(({handler}) => handler))
+    ->Array.filter(isTypeScript)
+    ->Array.map(toAbsolutePath)
+    ->Utils.Set.fromArray
+    ->Utils.Set.toArray
+  if files->Array.length > 0 {
+    switch await checkTypesInWorker(~cwd=NodeJs.Process.cwd(), ~files) {
+    | {errors} => JsError.throwWithMessage(`Handler files have type errors:\n\n${errors}`)
+    | {skipped} => Logging.warn(skipped)
+    | _ => ()
+    }
+  }
 }
 
 // `Config` holds only event definitions; handler + per-chain `where`
@@ -77,13 +109,23 @@ let autoLoadFromSrcHandlers = async (~handlers: string) => {
 // `HandlerRegister.finishRegistration`. This loads the user handler files
 // (populating the global `HandlerRegister` registry as a side effect) and
 // returns the resulting per-chain registrations.
-let registerAllHandlers = async (~config: Config.t): HandlerRegister.registrationsByChainId => {
+let registerAllHandlers = async (
+  ~config: Config.t,
+  ~autoLoadFiles,
+): HandlerRegister.registrationsByChainId => {
   HandlerRegister.startRegistration(~config)
+  registerTsHooks()
 
-  // Auto-load all .js files from src/handlers directory
-  await autoLoadFromSrcHandlers(~handlers=config.handlers)
+  let _ = await autoLoadFiles
+  ->Array.map(file => {
+    importHandler(file)->Promise.catch(exn => {
+      let cause = exn->Utils.prettifyExn->Obj.magic
+      Logging.errorWithExn(exn, `Failed to auto-load handler file: ${file}`)
+      JsError.throwWithMessage(`Failed to auto-load handler file: ${file}. Cause: ${cause}`)
+    })
+  })
+  ->Promise.all
 
-  // Load contract-specific handlers
   let _ = await config.contractHandlers
   ->Array.map(({name, handler}) => {
     registerContractHandlers(~contractName=name, ~handler)

package/src/HandlerLoader.res.mjs

@@ -1,26 +1,46 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Url from "url";
+import * as Core from "./Core.res.mjs";
 import * as Path from "path";
 import * as Utils from "./Utils.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as Process from "process";
-import * as Nodemodule from "node:module";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
 import * as HandlerRegister from "./HandlerRegister.res.mjs";
 import * as Promises from "node:fs/promises";
+import * as TsModuleHooksMjs from "./TsModuleHooks.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as HandlerTypeCheckMjs from "./HandlerTypeCheck.mjs";
 
-try {
-  Nodemodule.register("tsx/esm", import.meta.url);
-} catch (exn) {
-  
+function registerTsHooksWith(prim) {
+  TsModuleHooksMjs.register(prim);
 }
 
-function toImportUrl(relativePath) {
-  let absolutePath = Path.resolve(Process.cwd(), relativePath);
-  return Url.pathToFileURL(absolutePath).toString();
+function registerTsHooks() {
+  let addon = Core.getAddon();
+  TsModuleHooksMjs.register({
+    loadTs: addon.loadTs,
+    tsResolveCandidates: addon.tsResolveCandidates,
+    tsNotFoundCandidates: addon.tsNotFoundCandidates
+  });
+}
+
+function isTypeScript(file) {
+  return /\.m?tsx?$/.test(file);
+}
+
+function toAbsolutePath(file) {
+  return Path.resolve(Process.cwd(), file);
+}
+
+async function importHandler(file) {
+  if (isTypeScript(file)) {
+    Core.getAddon().tsCheckHandlerFormat(toAbsolutePath(file));
+  }
+  return await import(Url.pathToFileURL(toAbsolutePath(file)).toString());
 }
 
 async function registerContractHandlers(contractName, handler) {
@@ -28,7 +48,7 @@ async function registerContractHandlers(contractName, handler) {
     return;
   }
   try {
-    await import(toImportUrl(handler));
+    await importHandler(handler);
     return;
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
@@ -38,35 +58,61 @@ async function registerContractHandlers(contractName, handler) {
   }
 }
 
-async function autoLoadFromSrcHandlers(handlers) {
-  let srcPattern = `./` + handlers + `/**/*.{js,mjs,ts}`;
-  let handlerFiles;
+async function getAutoLoadFiles(config) {
+  let srcPattern = `./` + config.handlers + `/**/*.{js,mjs,ts}`;
   try {
     let iterator = Promises.glob(srcPattern);
     let files = await Utils.$$Array.fromAsyncIterator(iterator);
-    handlerFiles = files.filter(file => !(file.includes(".test.") || file.includes(".spec.") || file.includes("_test.")));
+    return files.filter(file => !(file.includes(".test.") || file.includes(".spec.") || file.includes("_test.")));
   } catch (raw_exn) {
     let exn = Primitive_exceptions.internalToException(raw_exn);
-    handlerFiles = Stdlib_JsError.throwWithMessage(`Failed to glob src/handlers directory for auto-loading handlers. Pattern: ` + srcPattern + `. Before continuing, check that you're using Node.js >=22 version. Error: ` + Utils.prettifyExn(exn));
+    return Stdlib_JsError.throwWithMessage(`Failed to glob src/handlers directory for auto-loading handlers. Pattern: ` + srcPattern + `. Error: ` + Utils.prettifyExn(exn));
   }
-  await Promise.all(handlerFiles.map(file => Stdlib_Promise.$$catch(import(toImportUrl(file)), exn => {
+}
+
+function checkTypesInWorker(prim0, prim1) {
+  return HandlerTypeCheckMjs.check(prim0, prim1);
+}
+
+async function typeCheck(config, autoLoadFiles) {
+  let files = Array.from(new Set(autoLoadFiles.concat(Stdlib_Array.filterMap(config.contractHandlers, param => param.handler)).filter(isTypeScript).map(toAbsolutePath)));
+  if (files.length === 0) {
+    return;
+  }
+  let match = await HandlerTypeCheckMjs.check(Process.cwd(), files);
+  let skipped = match.skipped;
+  let errors = match.errors;
+  if (errors !== undefined) {
+    return Stdlib_JsError.throwWithMessage(`Handler files have type errors:\n\n` + errors);
+  } else if (skipped !== undefined) {
+    return Logging.warn(skipped);
+  } else {
+    return;
+  }
+}
+
+async function registerAllHandlers(config, autoLoadFiles) {
+  HandlerRegister.startRegistration(config);
+  registerTsHooks();
+  await Promise.all(autoLoadFiles.map(file => Stdlib_Promise.$$catch(importHandler(file), exn => {
     let cause = Utils.prettifyExn(exn);
     Logging.errorWithExn(exn, `Failed to auto-load handler file: ` + file);
     return Stdlib_JsError.throwWithMessage(`Failed to auto-load handler file: ` + file + `. Cause: ` + cause);
   })));
-}
-
-async function registerAllHandlers(config) {
-  HandlerRegister.startRegistration(config);
-  await autoLoadFromSrcHandlers(config.handlers);
   await Promise.all(config.contractHandlers.map(param => registerContractHandlers(param.name, param.handler)));
   return HandlerRegister.finishRegistration(config);
 }
 
 export {
-  toImportUrl,
+  registerTsHooksWith,
+  registerTsHooks,
+  isTypeScript,
+  toAbsolutePath,
+  importHandler,
   registerContractHandlers,
-  autoLoadFromSrcHandlers,
+  getAutoLoadFiles,
+  checkTypesInWorker,
+  typeCheck,
   registerAllHandlers,
 }
-/*  Not a pure module */
+/* url Not a pure module */

package/src/HandlerTypeCheck.mjs

@@ -0,0 +1,14 @@
+import { Worker } from "node:worker_threads";
+
+// The compiler blocks the thread it runs on, so it gets its own and the
+// database setup carries on meanwhile.
+export const check = (cwd, files) =>
+  new Promise((resolve, reject) => {
+    const worker = new Worker(new URL("./HandlerTypeCheckWorker.mjs", import.meta.url), {
+      workerData: { cwd, files },
+    });
+    worker.once("message", resolve);
+    worker.once("error", reject);
+    // Settles nothing once the result has arrived.
+    worker.once("exit", () => reject(new Error("The handler type check exited without a result.")));
+  });

package/src/HandlerTypeCheckWorker.mjs

@@ -0,0 +1,68 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { parentPort, workerData } from "node:worker_threads";
+
+const check = ({ cwd, files }) => {
+  // The ReScript compiler checks a ReScript project's handlers, so it has no
+  // reason to set up TypeScript, and the warning would only be noise there.
+  // `rescript.json` at the root is what makes codegen treat it as ReScript.
+  const skip = (warning) => (existsSync(path.join(cwd, "rescript.json")) ? {} : { skipped: warning });
+
+  let ts;
+  try {
+    // The project's own compiler, so handlers are checked exactly as the
+    // user's editor and `tsc` check them.
+    ts = createRequire(path.join(cwd, "package.json"))("typescript");
+  } catch {
+    return skip("Skipped the handler type check: the project doesn't depend on typescript.");
+  }
+
+  const configPath = ts.findConfigFile(cwd, ts.sys.fileExists);
+  if (configPath === undefined) {
+    return skip(
+      "Skipped the handler type check: no tsconfig.json found. Add one to type-check handlers on start, like the one envio init creates."
+    );
+  }
+
+  const host = {
+    getCanonicalFileName: (file) => file,
+    getCurrentDirectory: () => cwd,
+    getNewLine: () => "\n",
+  };
+  const format = (diagnostics) =>
+    stripVTControlCharacters(ts.formatDiagnosticsWithColorAndContext(diagnostics, host)).trimEnd();
+
+  const parsed = ts.getParsedCommandLineOfConfigFile(
+    configPath,
+    { noEmit: true },
+    {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic: (diagnostic) => {
+        throw new Error(format([diagnostic]));
+      },
+    }
+  );
+
+  // The tsconfig's files are roots, as tsc makes them, since any of them can
+  // declare globals a handler relies on. Only the handlers' errors count.
+  const handlerFiles = files.map((file) => path.resolve(cwd, file));
+  const program = ts.createProgram({
+    rootNames: [...parsed.fileNames, ...handlerFiles],
+    options: parsed.options,
+    projectReferences: parsed.projectReferences,
+  });
+
+  // Every file is a root, so each has a source file. Without one,
+  // `getSemanticDiagnostics` would check the whole program.
+  const diagnostics = handlerFiles
+    .map((file) => program.getSourceFile(file))
+    .flatMap((sourceFile) => [
+      ...program.getSyntacticDiagnostics(sourceFile),
+      ...program.getSemanticDiagnostics(sourceFile),
+    ]);
+  return diagnostics.length === 0 ? {} : { errors: format(diagnostics) };
+};
+
+parentPort.postMessage(check(workerData));

package/src/Internal.res

@@ -491,7 +491,7 @@ type eventConfig = private {
 }
 
 type fuelEventKind =
-  | LogData({logId: string, decode: string => eventParams})
+  | LogData({logId: string, abi: JSON.t})
   | Mint
   | Burn
   | Transfer

package/src/Main.res

@@ -411,8 +411,6 @@ let getGlobalIndexer = (): 'indexer => {
   Utils.Proxy.make(Utils.Object.createNullObject(), traps)->(Utils.magic: {..} => 'indexer)
 }
 
-// The RPC-stripped public config that the storage layer persists in
-// `envio_info` (on initialize) and validates against (on resume).
 let migrate = async (~reset) => {
   let config = Config.load()
   let persistence = PgStorage.makePersistenceFromConfig(~config)
@@ -420,8 +418,8 @@ let migrate = async (~reset) => {
     ~reset,
     ~chainConfigs=config.chainMap->ChainMap.values,
     ~contractMapping=config.contractMapping,
-    ~envioInfo=Config.envioInfo(),
-    ~resetCommand="envio local db-migrate setup",
+    ~envioInfo=config.envioInfo,
+    ~resetCommand="envio local db-migrate setup"->Config.withProjectFlags(~config),
     ~runCommand=None,
     ~lowercaseAddresses=config.lowercaseAddresses,
     // A migration command runs once and exits, with nobody watching it recover:
@@ -466,18 +464,23 @@ exception FatalError(exn)
     | None => PgStorage.makePersistenceFromConfig(~config)
     }
     setGlobalPersistence(persistence)
-    await persistence->Persistence.initForRun(
-      ~config,
-      ~reset,
-      ~isDevelopmentMode,
-      ~requireInitialized=config.isolated,
-    )
+    let autoLoadFiles = await HandlerLoader.getAutoLoadFiles(~config)
+    // A worker's supervisor has checked the handlers already, and the test
+    // indexer leaves type checking to the user's test setup.
+    let typeCheck =
+      isTest || Worker.isEnabled
+        ? Promise.resolve()
+        : HandlerLoader.typeCheck(~config, ~autoLoadFiles)
+    let _ = await Promise.all2((
+      persistence->Persistence.initForRun(~config, ~reset, ~isDevelopmentMode),
+      typeCheck,
+    ))
 
     // Loads user handler files, which register handler/contractRegister/where
     // state into the global `HandlerRegister` registry as a side effect; this
     // returns that state resolved into per-chain registrations. `config` itself
     // is never mutated by registration — it holds only event definitions.
-    let registrationsByChainId = await HandlerLoader.registerAllHandlers(~config)
+    let registrationsByChainId = await HandlerLoader.registerAllHandlers(~config, ~autoLoadFiles)
     let config = if isTest {
       {...config, shouldRollbackOnReorg: false}
     } else {
@@ -535,7 +538,7 @@ exception FatalError(exn)
       ~onError,
     )
     if shouldUseTui {
-      let _rerender = Tui.start(~config, ~getMetrics=() => state->IndexerState.toMetrics)
+      Tui.start(~config, ~getMetrics=() => state->IndexerState.toMetrics)
     }
     Worker.bindRun(
       ~getMetrics=() => state->IndexerState.toMetrics,
@@ -565,6 +568,8 @@ let start = async (
   Worker.config->Option.forEach(({chainIds, isDev}) =>
     Config.prime(Config.getPublicConfigJson()->Config.withCommandFields(~chainIds, ~isDev))
   )
+  // An unsupported Node fails here, before the database is touched.
+  HandlerLoader.registerTsHooks()
   let config = Config.load()
   switch isTest ? None : Supervisor.planForRun(~config) {
   | Some(workers) => await Supervisor.run(~config, ~workers, ~reset)

package/src/Main.res.mjs

@@ -351,7 +351,7 @@ function getGlobalIndexer() {
 async function migrate(reset) {
   let config = Config.load();
   let persistence = PgStorage.makePersistenceFromConfig(config, undefined);
-  await Persistence.init(persistence, ChainMap.values(config.chainMap), config.contractMapping, Config.envioInfo(), "envio local db-migrate setup", undefined, reset, config.lowercaseAddresses, undefined, undefined, "Once");
+  await Persistence.init(persistence, ChainMap.values(config.chainMap), config.contractMapping, config.envioInfo, Config.withProjectFlags("envio local db-migrate setup", config), undefined, reset, config.lowercaseAddresses, undefined, undefined, "Once");
   return await persistence.storage.close();
 }
 
@@ -372,8 +372,13 @@ async function startIndexer(config, persistence, resetOpt, isTestOpt, exitAfterF
   let isDevelopmentMode = !isTest && config.isDev;
   let persistence$1 = persistence !== undefined ? persistence : PgStorage.makePersistenceFromConfig(config, undefined);
   EnvioGlobal.value.persistence = Primitive_option.some(persistence$1);
-  await Persistence.initForRun(persistence$1, config, reset, isDevelopmentMode, config.isolated);
-  let registrationsByChainId = await HandlerLoader.registerAllHandlers(config);
+  let autoLoadFiles = await HandlerLoader.getAutoLoadFiles(config);
+  let typeCheck = isTest || Worker.isEnabled ? Promise.resolve() : HandlerLoader.typeCheck(config, autoLoadFiles);
+  await Promise.all([
+    Persistence.initForRun(persistence$1, config, reset, isDevelopmentMode),
+    typeCheck
+  ]);
+  let registrationsByChainId = await HandlerLoader.registerAllHandlers(config, autoLoadFiles);
   let config$1;
   if (isTest) {
     let newrecord = {...config};
@@ -417,6 +422,7 @@ async function start(persistence, resetOpt, isTestOpt, exitAfterFirstEventBlockO
   let isTest = isTestOpt !== undefined ? isTestOpt : false;
   let exitAfterFirstEventBlock = exitAfterFirstEventBlockOpt !== undefined ? exitAfterFirstEventBlockOpt : false;
   Stdlib_Option.forEach(Worker.config, param => Config.prime(Config.withCommandFields(Config.getPublicConfigJson(), param.chainIds, param.isDev)));
+  HandlerLoader.registerTsHooks();
   let config = Config.load();
   let workers = isTest ? undefined : Supervisor.planForRun(config, undefined);
   if (workers !== undefined) {

package/src/NodeVersion.mjs

@@ -0,0 +1,13 @@
+const MINIMUM = [22, 15, 0];
+
+// The message for a Node.js older than envio supports, or undefined.
+export const unsupportedNodeMessage = () => {
+  const current = process.versions.node;
+  const parts = current.split(".").map(Number);
+  const index = MINIMUM.findIndex((minimum, i) => parts[i] !== minimum);
+  if (index === -1 || parts[index] > MINIMUM[index]) return undefined;
+  return [
+    `envio needs Node.js ${MINIMUM.join(".")} or newer, and this is Node.js ${current}.`,
+    "Install a newer one from https://nodejs.org/en/download, or with your version manager, for example: nvm install --lts",
+  ].join("\n");
+};