Preload handlers (#667)

* Implement preload handlers config option

* Add S.Infer

* Enable preload_handlers for init templates

* Mention preload in cursor rules

* Fix deleteUnsafe and update tests

* Fix fuel tests

Author: DZakh

codegenerator/cli/npm/envio/evm.schema.json

@@ -106,6 +106,13 @@
         "boolean",
         "null"
       ]
+    },
+    "preload_handlers": {
+      "description": "Makes handlers run twice to enable preload optimisations. Removes handlerWithLoader API, since it's not needed. (recommended, default: false)",
+      "type": [
+        "boolean",
+        "null"
+      ]
     }
   },
   "additionalProperties": false,

codegenerator/cli/npm/envio/fuel.schema.json

@@ -56,6 +56,13 @@
         "boolean",
         "null"
       ]
+    },
+    "preload_handlers": {
+      "description": "Makes handlers run twice to enable preload optimisations. Removes handlerWithLoader API, since it's not needed. (recommended, default: false)",
+      "type": [
+        "boolean",
+        "null"
+      ]
     }
   },
   "additionalProperties": false,

codegenerator/cli/npm/envio/index.d.ts

@@ -95,6 +95,7 @@ export function experimental_createEffect<
 // Important! Should match the index.js file
 export declare namespace S {
   export type Output<T> = Sury.Output<T>;
+  export type Infer<T> = Sury.Output<T>;
   export type Input<T> = Sury.Input<T>;
   export type Schema<Output, Input = unknown> = Sury.Schema<Output, Input>;
   export const string: typeof Sury.string;

codegenerator/cli/npm/envio/src/EventRegister.res

@@ -0,0 +1,92 @@
+type t = {
+  contractName: string,
+  eventName: string,
+  mutable handler: option<Internal.handler>,
+  mutable contractRegister: option<Internal.contractRegister>,
+  mutable eventOptions: option<Internal.eventOptions<Js.Json.t>>,
+}
+
+let getHandler = (t: t) => t.handler
+
+let getContractRegister = (t: t) => t.contractRegister
+
+let getEventFilters = (t: t) => t.eventOptions->Belt.Option.flatMap(value => value.eventFilters)
+
+let isWildcard = (t: t) =>
+  t.eventOptions->Belt.Option.flatMap(value => value.wildcard)->Belt.Option.getWithDefault(false)
+
+let hasRegistration = ({handler, contractRegister}) =>
+  handler->Belt.Option.isSome || contractRegister->Belt.Option.isSome
+
+let make = (~contractName, ~eventName) => {
+  contractName,
+  eventName,
+  handler: None,
+  contractRegister: None,
+  eventOptions: None,
+}
+
+type eventNamespace = {contractName: string, eventName: string}
+exception DuplicateEventRegistration(eventNamespace)
+
+let setEventOptions = (t: t, ~eventOptions, ~logger=Logging.getLogger()) => {
+  switch eventOptions {
+  | Some(value) =>
+    let value =
+      value->(Utils.magic: Internal.eventOptions<'eventFilters> => Internal.eventOptions<Js.Json.t>)
+    switch t.eventOptions {
+    | None => t.eventOptions = Some(value)
+    | Some(existingValue) =>
+      if (
+        existingValue.wildcard !== value.wildcard ||
+          // TODO: Can improve the check by using deepEqual
+          existingValue.eventFilters !== value.eventFilters
+      ) {
+        let eventNamespace = {contractName: t.contractName, eventName: t.eventName}
+        DuplicateEventRegistration(eventNamespace)->ErrorHandling.mkLogAndRaise(
+          ~logger=Logging.createChildFrom(~logger, ~params=eventNamespace),
+          ~msg="Duplicate eventOptions in handlers not allowed",
+        )
+      }
+    }
+  | None => ()
+  }
+}
+
+let setHandler = (t: t, handler, ~eventOptions, ~logger=Logging.getLogger()) => {
+  switch t.handler {
+  | None =>
+    t.handler =
+      handler
+      ->(Utils.magic: Internal.genericHandler<'args> => Internal.handler)
+      ->Some
+  | Some(_) =>
+    let eventNamespace = {contractName: t.contractName, eventName: t.eventName}
+    DuplicateEventRegistration(eventNamespace)->ErrorHandling.mkLogAndRaise(
+      ~logger=Logging.createChildFrom(~logger, ~params=eventNamespace),
+      ~msg="Duplicate registration of event handlers not allowed",
+    )
+  }
+
+  t->setEventOptions(~eventOptions, ~logger)
+}
+
+let setContractRegister = (t: t, contractRegister, ~eventOptions, ~logger=Logging.getLogger()) => {
+  switch t.contractRegister {
+  | None =>
+    t.contractRegister = Some(
+      contractRegister->(
+        Utils.magic: Internal.genericContractRegister<
+          Internal.genericContractRegisterArgs<'event, 'context>,
+        > => Internal.contractRegister
+      ),
+    )
+  | Some(_) =>
+    let eventNamespace = {contractName: t.contractName, eventName: t.eventName}
+    DuplicateEventRegistration(eventNamespace)->ErrorHandling.mkLogAndRaise(
+      ~logger=Logging.createChildFrom(~logger, ~params=eventNamespace),
+      ~msg="Duplicate contractRegister handlers not allowed",
+    )
+  }
+  t->setEventOptions(~eventOptions, ~logger)
+}

codegenerator/cli/npm/envio/src/EventRegister.resi

@@ -0,0 +1,21 @@
+type t
+let make: (~contractName: string, ~eventName: string) => t
+let setHandler: (
+  t,
+  Internal.genericHandler<
+    Internal.genericHandlerArgs<'event, Internal.handlerContext, 'loaderReturn>,
+  >,
+  ~eventOptions: option<Internal.eventOptions<'eventFilters>>,
+  ~logger: Pino.t=?,
+) => unit
+let setContractRegister: (
+  t,
+  Internal.genericContractRegister<Internal.genericContractRegisterArgs<'event, 'context>>,
+  ~eventOptions: option<Internal.eventOptions<'eventFilters>>,
+  ~logger: Pino.t=?,
+) => unit
+let getHandler: t => option<Internal.handler>
+let getContractRegister: t => option<Internal.contractRegister>
+let getEventFilters: t => option<Js.Json.t>
+let isWildcard: t => bool
+let hasRegistration: t => bool

codegenerator/cli/npm/envio/src/Internal.gen.ts

@@ -34,6 +34,14 @@ export type genericHandlerArgs<event,context,loaderReturn> = {
 
 export type genericHandler<args> = (_1:args) => Promise<void>;
 
+export type entityHandlerContext<entity> = {
+  readonly get: (_1:string) => Promise<(undefined | entity)>; 
+  readonly getOrThrow: (_1:string, message:(undefined | string)) => Promise<entity>; 
+  readonly getOrCreate: (_1:entity) => Promise<entity>; 
+  readonly set: (_1:entity) => void; 
+  readonly deleteUnsafe: (_1:string) => void
+};
+
 export type genericHandlerWithLoader<loader,handler,eventFilters> = {
   readonly loader: loader; 
   readonly handler: handler; 
@@ -43,6 +51,13 @@ export type genericHandlerWithLoader<loader,handler,eventFilters> = {
   readonly preRegisterDynamicContracts?: boolean
 };
 
+export type eventOptions<eventFilters> = {
+  readonly wildcard?: boolean; 
+  readonly eventFilters?: eventFilters; 
+  /** @deprecated The option is removed starting from v2.19 since we made the default mode even faster than pre-registration. */
+  readonly preRegisterDynamicContracts?: boolean
+};
+
 export type fuelSupplyParams = { readonly subId: string; readonly amount: bigint };
 
 export type fuelTransferParams = {

codegenerator/cli/npm/envio/src/Internal.res

@@ -16,8 +16,6 @@ type event = genericEvent<eventParams, eventBlock, eventTransaction>
 
 external fromGenericEvent: genericEvent<'a, 'b, 'c> => event = "%identity"
 
-type loaderReturn
-
 @genType
 type genericLoaderArgs<'event, 'context> = {
   event: 'event,
@@ -26,10 +24,6 @@ type genericLoaderArgs<'event, 'context> = {
 @genType
 type genericLoader<'args, 'loaderReturn> = 'args => promise<'loaderReturn>
 
-type loaderContext
-type loaderArgs = genericLoaderArgs<event, loaderContext>
-type loader = genericLoader<loaderArgs, loaderReturn>
-
 @genType
 type genericContractRegisterArgs<'event, 'context> = {
   event: 'event,
@@ -51,8 +45,21 @@ type genericHandlerArgs<'event, 'context, 'loaderReturn> = {
 @genType
 type genericHandler<'args> = 'args => promise<unit>
 
-type handlerContext
-type handlerArgs = genericHandlerArgs<event, handlerContext, loaderReturn>
+@genType
+type entityHandlerContext<'entity> = {
+  get: string => promise<option<'entity>>,
+  getOrThrow: (string, ~message: string=?) => promise<'entity>,
+  getOrCreate: 'entity => promise<'entity>,
+  set: 'entity => unit,
+  deleteUnsafe: string => unit,
+}
+
+type loaderReturn
+type handlerContext = private {isPreload: bool}
+type handlerArgs = {
+  event: event,
+  context: handlerContext,
+}
 type handler = genericHandler<handlerArgs>
 
 @genType
@@ -81,7 +88,6 @@ type eventConfig = private {
   // Usually always false for wildcard events
   // But might be true for wildcard event with dynamic event filter by addresses
   dependsOnAddresses: bool,
-  loader: option<loader>,
   handler: option<handler>,
   contractRegister: option<contractRegister>,
   paramsRawEventSchema: S.schema<eventParams>,
@@ -138,6 +144,16 @@ type eventItem = {
   mutable loggerCache?: Pino.t,
 }
 
+@genType
+type eventOptions<'eventFilters> = {
+  wildcard?: bool,
+  eventFilters?: 'eventFilters,
+  /**
+    @deprecated The option is removed starting from v2.19 since we made the default mode even faster than pre-registration.
+  */
+  preRegisterDynamicContracts?: bool,
+}
+
 @genType
 type fuelSupplyParams = {
   subId: string,

codegenerator/cli/npm/envio/src/bindings/Promise.res

@@ -53,6 +53,8 @@ external race: array<t<'a>> => t<'a> = "race"
 
 external done: promise<'a> => unit = "%ignore"
 
+external ignoreValue: promise<'a> => promise<unit> = "%identity"
+
 external unsafe_async: 'a => promise<'a> = "%identity"
 external unsafe_await: promise<'a> => 'a = "?await"
 

codegenerator/cli/src/cli_args/init_config.rs

@@ -170,6 +170,7 @@ pub mod evm {
                 save_full_history: None,
                 field_selection: None,
                 raw_events: None,
+                preload_handlers: Some(true),
             })
         }
 
@@ -300,6 +301,7 @@ pub mod fuel {
                 output: None,
                 contracts: None,
                 raw_events: None,
+                preload_handlers: Some(true),
                 networks: network_configs,
             }
         }

codegenerator/cli/src/config_parsing/graph_migration/mod.rs

@@ -284,6 +284,7 @@ pub async fn generate_config_from_subgraph_id(
         save_full_history: None,
         field_selection: None,
         raw_events: None,
+        preload_handlers: Some(true),
     };
     let mut networks: Vec<Network> = vec![];