Address review: move WhereOperator/GetWhereFilter to index.d.ts, add JSDoc, runtime index check

- Move WhereOperator<T> and GetWhereFilter<E> from Rust-generated envio.d.ts
  to static index.d.ts in envio package as TS generics
- Add JSDoc comments for all WhereOperator fields (_eq, _gt, _lt)
- Generate getWhereFilter for ALL non-derived entity fields (not just indexed)
- Add runtime isIndex check in UserContext.res with user-friendly errors:
  - Derived fields: tells user to use source entity's indexed field
  - Non-indexed fields: tells user to add @index directive with example
- Update Types.ts.hbs to import GetWhereFilter from "envio" package

https://claude.ai/code/session_01FmZW8U8ymXd46zRzJZDhNh

Author: claude

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

@@ -18,6 +18,30 @@ export type { EffectCaller, Address } from "./src/Types.ts";
 /** Utility type to expand/flatten complex types for better IDE display. */
 export type Prettify<T> = { [K in keyof T]: T[K] } & {};
 
+/**
+ * Operator for filtering entity fields in getWhere queries.
+ * Only fields with `@index` in the schema can be queried at runtime.
+ */
+export type WhereOperator<T> = {
+  /** Matches entities where the field equals the given value. */
+  readonly _eq?: T;
+  /** Matches entities where the field is greater than the given value. */
+  readonly _gt?: T;
+  /** Matches entities where the field is less than the given value. */
+  readonly _lt?: T;
+};
+
+/**
+ * Constructs a getWhere filter type from an entity type.
+ * Each field can be filtered using {@link WhereOperator} (`_eq`, `_gt`, `_lt`).
+ *
+ * Note: only fields with `@index` in the schema can be queried at runtime.
+ * Attempting to filter on a non-indexed field will throw a descriptive error.
+ */
+export type GetWhereFilter<E> = {
+  [K in keyof E]?: WhereOperator<E[K]>;
+};
+
 import type {
   effect as Effect,
   effectArgs as EffectArgs,

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

@@ -122,18 +122,22 @@ let getWhereHandler = (params: entityContextParams, filter: Js.Dict.t<Js.Dict.t<
     Js.Exn.raiseError(
       `Invalid field "${dbFieldName}" in context.${entityConfig.name}.getWhere(). The field doesn't exist. ${codegenHelpMessage}`,
     )
-  | Some(field) =>
-    let fieldValueSchema = switch field {
-    | Field({fieldSchema}) => fieldSchema
-    | DerivedFrom(_) => S.string->S.toUnknown
-    }
+  | Some(DerivedFrom(_)) =>
+    Js.Exn.raiseError(
+      `The field "${dbFieldName}" on entity "${entityConfig.name}" is a derived field and cannot be used in getWhere(). Use the source entity's indexed field instead.`,
+    )
+  | Some(Field({isIndex: false})) =>
+    Js.Exn.raiseError(
+      `The field "${dbFieldName}" on entity "${entityConfig.name}" does not have an index. To use it in getWhere(), add the @index directive in your schema.graphql:\n\n  ${dbFieldName}: ... @index\n\nThen run 'pnpm envio codegen' to regenerate.`,
+    )
+  | Some(Field({fieldSchema, isIndex: true})) =>
     LoadLayer.loadByField(
       ~loadManager=params.loadManager,
       ~persistence=params.persistence,
       ~operator,
       ~entityConfig,
       ~fieldName=dbFieldName,
-      ~fieldValueSchema,
+      ~fieldValueSchema=fieldSchema,
       ~inMemoryStore=params.inMemoryStore,
       ~shouldGroup=params.isPreload,
       ~item=params.item,

codegenerator/cli/src/hbs_templating/codegen_templates.rs

@@ -306,10 +306,11 @@ impl EntityRecordTypeTemplate {
 
         let composite_indices = entity.get_composite_indices();
 
-        // Generate getWhereFilter type code for ReScript
+        // Generate getWhereFilter type code for ReScript (all non-derived fields)
+        // Non-indexed fields will throw a user-friendly error at runtime
         let get_where_filter_fields: Vec<String> = params
             .iter()
-            .filter(|p| p.is_queryable_field)
+            .filter(|p| !p.is_derived_field)
             .map(|p| {
                 let (field_name, as_name) = if p.is_entity_field {
                     (
@@ -1810,53 +1811,6 @@ let createTestIndexer: unit => TestIndexer.t<testIndexerProcessConfig> = TestInd
                 )
             });
 
-            // Generate WhereOperator generic type
-            parts.push(
-                "export type WhereOperator<T> = {\n  readonly _eq?: T;\n  readonly _gt?: T;\n  readonly _lt?: T;\n};"
-                    .to_string(),
-            );
-
-            // Generate GetWhereFilter type with per-entity filter definitions
-            let get_where_filter_entries: Vec<String> = entities
-                .iter()
-                .map(|entity| {
-                    let filter_fields: Vec<String> = entity
-                        .params
-                        .iter()
-                        .filter(|param| param.is_queryable_field)
-                        .map(|param| {
-                            let ts_type = param.field_type.to_ts_type_string();
-                            let (field_name, field_type) = if param.is_entity_field {
-                                (
-                                    format!("{}_id", param.field_name.original),
-                                    "string".to_string(),
-                                )
-                            } else {
-                                (param.field_name.original.clone(), ts_type)
-                            };
-                            format!("    {}?: WhereOperator<{}>;", field_name, field_type)
-                        })
-                        .collect();
-                    if filter_fields.is_empty() {
-                        format!("  \"{}\": {{}};", entity.name.capitalized)
-                    } else {
-                        format!(
-                            "  \"{}\": {{\n{}\n  }};",
-                            entity.name.capitalized,
-                            filter_fields.join("\n")
-                        )
-                    }
-                })
-                .collect();
-            parts.push(if get_where_filter_entries.is_empty() {
-                "export type GetWhereFilter = {};".to_string()
-            } else {
-                format!(
-                    "export type GetWhereFilter = {{\n{}\n}};",
-                    get_where_filter_entries.join("\n")
-                )
-            });
-
             parts.join("\n")
         };
 

codegenerator/cli/src/hbs_templating/snapshots/envio__hbs_templating__codegen_templates__test__envio_dts_code_generated_for_evm.snap

@@ -1,6 +1,6 @@
 ---
 source: cli/src/hbs_templating/codegen_templates.rs
-assertion_line: 2471
+assertion_line: 2425
 expression: project_template.envio_dts_code
 ---
 export type EvmChains = {
@@ -31,12 +31,3 @@ export type Entities = {
     readonly "name": string;
   };
 };
-export type WhereOperator<T> = {
-  readonly _eq?: T;
-  readonly _gt?: T;
-  readonly _lt?: T;
-};
-export type GetWhereFilter = {
-  "EmptyEntity": {};
-  "RelatedEntity": {};
-};

codegenerator/cli/src/hbs_templating/snapshots/envio__hbs_templating__codegen_templates__test__envio_dts_code_generated_for_fuel.snap

@@ -1,6 +1,6 @@
 ---
 source: cli/src/hbs_templating/codegen_templates.rs
-assertion_line: 2477
+assertion_line: 2431
 expression: project_template.envio_dts_code
 ---
 export type EvmChains = {};
@@ -19,11 +19,3 @@ export type Entities = {
     readonly "emptyField": string;
   };
 };
-export type WhereOperator<T> = {
-  readonly _eq?: T;
-  readonly _gt?: T;
-  readonly _lt?: T;
-};
-export type GetWhereFilter = {
-  "EmptyEntity": {};
-};

codegenerator/cli/templates/dynamic/codegen/src/Types.ts.hbs

@@ -2,8 +2,8 @@
 // which we can't get using GenType
 // Use @genType.import to link the types back to ReScript code
 
-import type { Logger, IndexerFromConfig, EffectCaller } from "envio";
-import type { EvmChains, EvmContracts, FuelChains, FuelContracts, SvmChains, Entities, GetWhereFilter } from "../envio.d.ts";
+import type { Logger, IndexerFromConfig, EffectCaller, GetWhereFilter } from "envio";
+import type { EvmChains, EvmContracts, FuelChains, FuelContracts, SvmChains, Entities } from "../envio.d.ts";
 
 // Utility type to check if an object type is empty
 type IsEmptyObject<T> = keyof T extends never ? true : false;
@@ -131,7 +131,7 @@ export type HandlerContext = {
      * Supports Hasura-style operators: _eq, _gt, _lt.
      * Currently only one filter field with one operator is supported per call.
      */
-    readonly getWhere: (filter: GetWhereFilter["{{entity.name.capitalized}}"]) => Promise<Entities["{{entity.name.capitalized}}"][]>,
+    readonly getWhere: (filter: GetWhereFilter<Entities["{{entity.name.capitalized}}"]>) => Promise<Entities["{{entity.name.capitalized}}"][]>,
     /**
      * Returns the entity {{entity.name.original}} from the storage by ID.
      * If the entity is not found, creates it using provided parameters and returns it.