@confect/core 10.0.0-next.20 → 10.0.0-next.22

package/src/GroupSpec.ts

@@ -1,5 +1,7 @@
+import * as MiddlewareAttachment from "./MiddlewareAttachment";
 import * as Predicate from "effect/Predicate";
 import * as Record from "effect/Record";
+import * as Result from "effect/Result";
 import type * as FunctionSpec from "./FunctionSpec";
 import type * as MiddlewareSpec from "./MiddlewareSpec";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
@@ -18,7 +20,7 @@ export interface GroupSpec<
   // Subgroups may be of any runtime, independent of this group's own runtime: a
   // group is only a namespace for its children, which are otherwise-independent
   // modules. Functions, by contrast, stay homogeneous (a Node group only accepts
-  // Node actions) — `addFunction` keeps the `<Runtime>` bound below.
+  // Node actions)—`addFunction` keeps the `<Runtime>` bound below.
   Groups_ extends AnyWithProps = never,
   MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec = never,
 > {
@@ -36,6 +38,9 @@ export interface GroupSpec<
     [GroupName in Name<Groups_>]: WithName<Groups_, GroupName>;
   };
   readonly middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
+  readonly middlewareAttachments: ReadonlyArray<
+    MiddlewareAttachment.MiddlewareAttachment<MiddlewareSpecs_>
+  >;
   readonly "~Functions": Functions_;
   readonly "~Groups": Groups_;
 
@@ -72,6 +77,7 @@ export interface GroupSpec<
         Functions_,
         MiddlewareSpecs_
       >,
+    ...options: MiddlewareAttachment.Args<NoInfer<MiddlewareSpec_>>
   ): GroupSpec<
     Runtime,
     Name_,
@@ -154,22 +160,27 @@ export type AddGroups<
 const Proto = {
   [TypeId]: TypeId,
 
+  get middlewareSpecs() {
+    return this.middlewareAttachments.map(({ spec }) => spec);
+  },
+
   addFunction<Function extends FunctionSpec.AnyWithProps>(
     this: Any,
     function_: Function,
   ) {
     const this_ = this as AnyWithProps;
 
-    const overlapping = function_.middlewareSpecs.find(
-      (functionMiddlewareSpec) =>
-        this_.middlewareSpecs.some(
-          (groupMiddlewareSpec) =>
+    const overlapping = function_.middlewareAttachments.find(
+      ({ spec: functionMiddlewareSpec }) =>
+        !("options" in functionMiddlewareSpec) &&
+        this_.middlewareAttachments.some(
+          ({ spec: groupMiddlewareSpec }) =>
             groupMiddlewareSpec.key === functionMiddlewareSpec.key,
         ),
     );
     if (overlapping !== undefined) {
       throw new Error(
-        `Middleware "${overlapping.key}" is attached to both function "${function_.name}" and its group`,
+        `Middleware "${overlapping.spec.key}" is attached to both function "${function_.name}" and its group`,
       );
     }
 
@@ -178,7 +189,7 @@ const Proto = {
       name: this_.name,
       functions: Record.set(this_.functions, function_.name, function_),
       groups: this_.groups,
-      middlewareSpecs: this_.middlewareSpecs,
+      middlewareAttachments: this_.middlewareAttachments,
     });
   },
 
@@ -191,7 +202,7 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: Record.set(this_.groups, group_.name, group_),
-      middlewareSpecs: this_.middlewareSpecs,
+      middlewareAttachments: this_.middlewareAttachments,
     });
   },
 
@@ -204,19 +215,21 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: Record.set(this_.groups, name, withName(name, group_)),
-      middlewareSpecs: this_.middlewareSpecs,
+      middlewareAttachments: this_.middlewareAttachments,
     });
   },
 
   middleware<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec>(
     this: Any,
     middlewareSpec: MiddlewareSpec_,
+    ...options: ReadonlyArray<unknown>
   ) {
     const this_ = this as AnyWithProps;
 
     if (
-      this_.middlewareSpecs.some(
-        (existing) => existing.key === middlewareSpec.key,
+      !("options" in middlewareSpec) &&
+      this_.middlewareAttachments.some(
+        ({ spec }) => spec.key === middlewareSpec.key,
       )
     ) {
       throw new Error(
@@ -226,8 +239,9 @@ const Proto = {
 
     for (const function_ of Object.values(this_.functions)) {
       if (
-        function_.middlewareSpecs.some(
-          (existing) => existing.key === middlewareSpec.key,
+        !("options" in middlewareSpec) &&
+        function_.middlewareAttachments.some(
+          ({ spec }) => spec.key === middlewareSpec.key,
         )
       ) {
         throw new Error(
@@ -241,37 +255,53 @@ const Proto = {
       name: this_.name,
       functions: this_.functions,
       groups: this_.groups,
-      middlewareSpecs: [...this_.middlewareSpecs, middlewareSpec],
+      middlewareAttachments: [
+        ...this_.middlewareAttachments,
+        { spec: middlewareSpec, options: options[0] },
+      ],
     });
   },
-};
+} satisfies ThisType<AnyWithProps>;
 
 const makeProto = <
   Runtime extends RuntimeAndFunctionType.Runtime,
   Name_ extends string,
   Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>,
   Groups_ extends AnyWithPropsWithRuntime<Runtime>,
-  MiddlewareSpecs_ extends MiddlewareSpec.AnyMiddlewareSpec,
+  MiddlewareAttachments_ extends
+    ReadonlyArray<MiddlewareAttachment.MiddlewareAttachment>,
 >({
   runtime,
   name,
   functions,
   groups,
-  middlewareSpecs,
+  middlewareAttachments,
 }: {
   runtime: Runtime;
   name: Name_;
   functions: Record.ReadonlyRecord<string, Functions_>;
   groups: Record.ReadonlyRecord<string, Groups_>;
-  middlewareSpecs: ReadonlyArray<MiddlewareSpecs_>;
-}): GroupSpec<Runtime, Name_, Functions_, Groups_, MiddlewareSpecs_> =>
+  middlewareAttachments: MiddlewareAttachments_;
+}): GroupSpec<
+  Runtime,
+  Name_,
+  Functions_,
+  Groups_,
+  MiddlewareAttachments_[number]["spec"]
+> =>
   Object.assign(Object.create(Proto), {
     runtime,
     name,
     functions,
     groups,
-    middlewareSpecs,
-  }) as GroupSpec<Runtime, Name_, Functions_, Groups_, MiddlewareSpecs_>;
+    middlewareAttachments,
+  }) as GroupSpec<
+    Runtime,
+    Name_,
+    Functions_,
+    Groups_,
+    MiddlewareAttachments_[number]["spec"]
+  >;
 
 export const make = (): GroupSpec<"Convex", ""> =>
   makeProto({
@@ -279,7 +309,7 @@ export const make = (): GroupSpec<"Convex", ""> =>
     name: "",
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 
 export const makeAt = <const Name_ extends string>(
@@ -292,7 +322,7 @@ export const makeAt = <const Name_ extends string>(
     name,
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 };
 
@@ -302,7 +332,7 @@ export const makeNode = (): GroupSpec<"Node", ""> =>
     name: "",
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 
 export const makeNodeAt = <const Name_ extends string>(
@@ -315,7 +345,7 @@ export const makeNodeAt = <const Name_ extends string>(
     name,
     functions: Record.empty(),
     groups: Record.empty(),
-    middlewareSpecs: [],
+    middlewareAttachments: [],
   });
 };
 
@@ -335,6 +365,24 @@ export const withName = <const Name_ extends string>(
     name,
     functions: group_.functions,
     groups: group_.groups,
-    middlewareSpecs: group_.middlewareSpecs,
+    middlewareAttachments: group_.middlewareAttachments,
   });
 };
+
+export const validateMiddleware = (
+  group: AnyWithProps,
+): Result.Result<void, MiddlewareAttachment.ValidationError> =>
+  Result.gen(function* () {
+    yield* MiddlewareAttachment.validateAll(
+      group.middlewareAttachments,
+      `group "${group.name}"`,
+    );
+    for (const function_ of Object.values(group.functions)) {
+      yield* MiddlewareAttachment.validateAll(
+        [...group.middlewareAttachments, ...function_.middlewareAttachments],
+        `function "${function_.name}"`,
+      );
+    }
+    for (const child of Object.values(group.groups))
+      yield* validateMiddleware(child);
+  });

package/src/Identifier.ts

@@ -99,7 +99,7 @@ export const validateConfectFunctionIdentifier = (identifier: string) => {
  * as a `confect/tables/<identifier>.ts` filename).
  *
  * Rules:
- * - Must match `/^[A-Za-z][A-Za-z0-9_]*$/` — letter-leading, alphanumeric plus
+ * - Must match `/^[A-Za-z][A-Za-z0-9_]*$/`—letter-leading, alphanumeric plus
  *   underscore. No `$` (not a valid Convex table name character); no leading
  *   `_` (Convex reserves `_<name>` for its system tables).
  * - Must not be a reserved JavaScript identifier, so the name can also be used

package/src/Lazy.ts

@@ -2,20 +2,19 @@
  * Install a lazy memoised property on `target`. The first access runs
  * `compute()` and replaces the getter with a plain, non-writable data
  * property whose value is the computed result. Subsequent accesses hit
- * the V8 fast path for own data properties — no function call, identical
- * returned reference — so first and second-and-subsequent accesses are
+ * the V8 fast path for own data properties—no function call, identical
+ * returned reference—so first and second-and-subsequent accesses are
  * observably indistinguishable.
  *
  * The replacement property is `enumerable: true` so the lazy property
- * still participates in `Object.keys` / `JSON.stringify` after it
+ * still participates in `Object.keys`/`JSON.stringify` after it
  * materialises, matching the shape of a plain data property. The property
  * is also `enumerable` before materialising, so presence checks
  * (`"key" in target`, `Object.hasOwn(target, key)`) observe it without
  * forcing the computation.
  *
  * This is the single shared implementation consumed across packages (e.g.
- * `@confect/core`'s lazy `FunctionSpec` schemas and lazy `Table` `Fields` /
- * `Doc`), so there is no chance of the two drifting apart.
+ * `@confect/core`'s lazy `FunctionSpec` schemas and lazy `Table` `Fields`/`Doc`), so there is no chance of the two drifting apart.
  */
 export const defineProperty = <T extends object, K extends PropertyKey>(
   target: T,

package/src/MiddlewareAttachment.ts

@@ -0,0 +1,106 @@
+import * as Data from "effect/Data";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import type * as MiddlewareSpec from "./MiddlewareSpec";
+
+export type MiddlewareAttachment<
+  MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec =
+    MiddlewareSpec.AnyMiddlewareSpec,
+> = MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec
+  ? {
+      readonly spec: MiddlewareSpec_;
+      readonly options: [MiddlewareSpec_["~Options"]] extends [never]
+        ? undefined
+        : MiddlewareSpec.Options<MiddlewareSpec_>;
+    }
+  : never;
+
+export type Args<MiddlewareSpec_ extends MiddlewareSpec.AnyMiddlewareSpec> = [
+  MiddlewareSpec_["~Options"],
+] extends [never]
+  ? []
+  : [options: MiddlewareSpec.Options<MiddlewareSpec_>];
+
+export type ValidationError = Data.TaggedEnum<{
+  InvalidOptions: {
+    readonly middlewareKey: string;
+    readonly location: string;
+    readonly attachmentIndex: number;
+  };
+  ConflictingSpecs: {
+    readonly middlewareKey: string;
+    readonly location: string;
+    readonly attachmentIndex: number;
+    readonly previousIndex: number;
+  };
+  EquivalentOptions: {
+    readonly middlewareKey: string;
+    readonly location: string;
+    readonly attachmentIndex: number;
+    readonly previousIndex: number;
+  };
+}>;
+
+export const ValidationError = Data.taggedEnum<ValidationError>();
+
+export const formatValidationError = ValidationError.$match({
+  InvalidOptions: ({ middlewareKey, location, attachmentIndex }) =>
+    `Middleware "${middlewareKey}" has invalid options at attachment ${attachmentIndex + 1} on ${location}`,
+  ConflictingSpecs: ({ middlewareKey, location }) =>
+    `Different middleware specs share key "${middlewareKey}" on ${location}`,
+  EquivalentOptions: ({
+    middlewareKey,
+    location,
+    attachmentIndex,
+    previousIndex,
+  }) =>
+    `Middleware "${middlewareKey}" has equivalent options at attachments ${previousIndex + 1} and ${attachmentIndex + 1} on ${location}`,
+});
+
+export const validateAll = (
+  attachments: ReadonlyArray<MiddlewareAttachment>,
+  location: string,
+): Result.Result<void, ValidationError> => {
+  for (const [index, attachment] of attachments.entries()) {
+    const schema = attachment.spec.options;
+    if (schema !== undefined && !Schema.is(schema)(attachment.options)) {
+      return Result.fail(
+        ValidationError.InvalidOptions({
+          middlewareKey: attachment.spec.key,
+          location,
+          attachmentIndex: index,
+        }),
+      );
+    }
+    const equivalent =
+      schema === undefined ? undefined : Schema.toEquivalence(schema);
+    for (const [previousIndex, previous] of attachments.entries()) {
+      if (previousIndex === index) break;
+      if (previous.spec.key !== attachment.spec.key) continue;
+      if (previous.spec !== attachment.spec) {
+        return Result.fail(
+          ValidationError.ConflictingSpecs({
+            middlewareKey: attachment.spec.key,
+            location,
+            attachmentIndex: index,
+            previousIndex,
+          }),
+        );
+      }
+      if (
+        equivalent === undefined ||
+        equivalent(previous.options, attachment.options)
+      ) {
+        return Result.fail(
+          ValidationError.EquivalentOptions({
+            middlewareKey: attachment.spec.key,
+            location,
+            attachmentIndex: index,
+            previousIndex,
+          }),
+        );
+      }
+    }
+  }
+  return Result.void;
+};

package/src/MiddlewareSpec.ts

@@ -44,25 +44,32 @@ export interface SuccessValue {
  *
  * Mirrors `RpcMiddleware.RpcMiddleware` in Effect.
  */
-export interface MiddlewareImpl<Provides_, E, R> {
+export interface MiddlewareImpl<Provides_, E, R, Options_ = never> {
   (
     effect: Effect.Effect<SuccessValue, E | unhandled, Provides_>,
-    options: MiddlewareOptions,
+    context: MiddlewareOptions<Options_>,
   ): Effect.Effect<SuccessValue, E | unhandled, R>;
 }
 
-export interface MiddlewareOptions {
-  readonly name: string;
-  readonly functionType: FunctionType;
-  readonly functionVisibility: FunctionVisibility;
-  readonly args: unknown;
-}
+export type MiddlewareOptions<Options_ = never> = {
+  readonly invocation: {
+    readonly name: string;
+    readonly functionType: FunctionType;
+    readonly functionVisibility: FunctionVisibility;
+    readonly args: unknown;
+  };
+} & ([Options_] extends [never] ? unknown : { readonly options: Options_ });
 
-export interface AnyMiddlewareImpl extends MiddlewareImpl<any, any, any> {}
+export interface AnyMiddlewareImpl {
+  (
+    effect: Effect.Effect<SuccessValue, any, any>,
+    context: MiddlewareOptions | MiddlewareOptions<unknown>,
+  ): Effect.Effect<SuccessValue, any, any>;
+}
 
 /**
  * The class shape produced by {@link MiddlewareSpec}. Only the static side is ever
- * used — the class is a value-level carrier for the middleware's key, its
+ * used—the class is a value-level carrier for the middleware's key, its
  * declared functionTypes, and its (lazily-evaluated) error schema, plus the
  * type-level `Provides`/`Error` metadata. It is deliberately not a
  * `Context.Tag`: implementations are registered through the group `Registry`
@@ -75,6 +82,7 @@ export interface MiddlewareSpec<
   Requires_,
   ErrorSchema_ extends Schema.Codec<any, any>,
   FunctionTypes_ extends FunctionType,
+  OptionsSchema_ extends Schema.Schema<any> = never,
 > {
   new (_: never): {
     readonly [TypeId]: TypeId;
@@ -84,11 +92,13 @@ export interface MiddlewareSpec<
   readonly key: Key_;
   readonly functionTypes: SupportedFunctionTypes;
   readonly error?: ErrorSchema_;
+  readonly options?: OptionsSchema_;
   readonly "~Provides": Provides_;
   readonly "~Requires": Requires_;
   readonly "~Error": ErrorSchema_;
   readonly "~FunctionTypes": FunctionTypes_;
   readonly "~Self": Self;
+  readonly "~Options": OptionsSchema_;
 }
 
 export interface AnyMiddlewareSpec {
@@ -96,12 +106,24 @@ export interface AnyMiddlewareSpec {
   readonly key: string;
   readonly functionTypes: SupportedFunctionTypes;
   readonly error?: Schema.Codec<any, any>;
+  readonly options?: Schema.Schema<any>;
   readonly "~Provides": any;
   readonly "~Requires": any;
   readonly "~Error": any;
   readonly "~FunctionTypes": FunctionType;
+  readonly "~Options": any;
 }
 
+export type Options<MiddlewareSpec_ extends AnyMiddlewareSpec> =
+  MiddlewareSpec_["~Options"]["Type"];
+
+export type WithoutOptions<MiddlewareSpec_ extends AnyMiddlewareSpec> =
+  MiddlewareSpec_ extends AnyMiddlewareSpec
+    ? [MiddlewareSpec_["~Options"]] extends [never]
+      ? MiddlewareSpec_
+      : never
+    : never;
+
 export type Key<MiddlewareSpec_ extends AnyMiddlewareSpec> =
   MiddlewareSpec_["key"];
 
@@ -160,10 +182,12 @@ export const MiddlewareSpec =
     const Key_ extends string,
     const FunctionTypesConfig_ extends SupportedFunctionTypes,
     ErrorSchema_ extends Schema.Codec<any, any> = never,
+    OptionsSchema_ extends Schema.Schema<any> = never,
   >(
     key: Key_,
     options: {
       readonly error?: () => ErrorSchema_;
+      readonly options?: () => OptionsSchema_;
       readonly functionTypes: FunctionTypesConfig_ &
         ValidateFunctionTypesConfig<FunctionTypesConfig_>;
     },
@@ -173,7 +197,8 @@ export const MiddlewareSpec =
     "provides" extends keyof Config ? Config["provides"] : never,
     "requires" extends keyof Config ? Config["requires"] : never,
     ErrorSchema_,
-    FunctionTypesFromConfig<FunctionTypesConfig_>
+    FunctionTypesFromConfig<FunctionTypesConfig_>,
+    OptionsSchema_
   > => {
     const { query, mutation, action } = options.functionTypes;
     if (!query && !mutation && !action) {
@@ -194,6 +219,9 @@ export const MiddlewareSpec =
     if (options.error !== undefined) {
       Lazy.defineProperty(class_, "error", options.error);
     }
+    if (options.options !== undefined) {
+      Lazy.defineProperty(class_, "options", options.options);
+    }
     return class_;
   };
 
@@ -225,7 +253,7 @@ export const errorSchemas = (
 /**
  * A branded, unconstructible type carrying a spec-authoring error message.
  * Surfaced as (part of) a parameter type so the diagnostic names the exact
- * problem at the `.middleware()` / `.addFunction()` call site.
+ * problem at the `.middleware()`/`.addFunction()` call site.
  */
 export interface AttachmentError<Message extends string> {
   readonly "~@confect/core/MiddlewareSpec/AttachmentError": Message;
@@ -251,12 +279,12 @@ export type ValidateFunction<
         readonly functionProvenance: { readonly _tag: "Convex" };
       }
       ? FunctionTypeOf<FunctionSpec_> extends FunctionTypes<MiddlewareSpec_>
-        ? AttachmentError<`Convex-provenance function "${FunctionSpec_["name"]}" cannot be covered by middleware "${Key<MiddlewareSpec_>}" — attach middleware only to groups whose matching-type functions are all Confect-provenance`>
+        ? AttachmentError<`Convex-provenance function "${FunctionSpec_["name"]}" cannot be covered by middleware "${Key<MiddlewareSpec_>}"—attach middleware only to groups whose matching-type functions are all Confect-provenance`>
         : never
       : [
             Extract<
               FunctionSpec.MiddlewareSpecs<FunctionSpec_>,
-              { readonly key: Key<MiddlewareSpec_> }
+              { readonly key: Key<WithoutOptions<MiddlewareSpec_>> }
             >,
           ] extends [never]
         ? FunctionTypeOf<FunctionSpec_> extends FunctionTypes<MiddlewareSpec_>
@@ -276,13 +304,16 @@ export type ValidateAttach<
   Functions_ extends FunctionSpec.AnyWithProps,
   MiddlewareSpecs_ extends AnyMiddlewareSpec,
 > = [
-  Extract<MiddlewareSpecs_, { readonly key: Key<MiddlewareSpec_> }>,
+  Extract<
+    MiddlewareSpecs_,
+    { readonly key: Key<WithoutOptions<MiddlewareSpec_>> }
+  >,
 ] extends [never]
   ? [Exclude<Requires<MiddlewareSpec_>, Provides<MiddlewareSpecs_>>] extends [
       never,
     ]
     ? ValidationResult<ValidateFunction<Functions_, MiddlewareSpec_>>
-    : AttachmentError<`Middleware "${Key<MiddlewareSpec_>}" requires services that no middleware attached earlier to this group provides — attach the providing middleware first`>
+    : AttachmentError<`Middleware "${Key<MiddlewareSpec_>}" requires services that no middleware attached earlier to this group provides—attach the providing middleware first`>
   : AttachmentError<`Middleware "${Key<MiddlewareSpec_>}" is already attached to this group`>;
 
 export type ValidateAddedFunction<
@@ -304,7 +335,7 @@ type GroupOverlap<
       ? [
           Extract<
             MiddlewareSpecs_,
-            { readonly key: Key<FunctionMiddlewareSpec> }
+            { readonly key: Key<WithoutOptions<FunctionMiddlewareSpec>> }
           >,
         ] extends [never]
         ? never
@@ -316,8 +347,8 @@ type GroupOverlap<
  * The parameter-type validation applied to the group spec at
  * `GroupImpl.make`: every function's attached middleware must have its
  * `requires` services provided by some middleware covering that function
- * (the group's or the function's own). Checked here — with the group fully
- * assembled — rather than at the spec builders, because a function-level
+ * (the group's or the function's own). Checked here—with the group fully
+ * assembled—rather than at the spec builders, because a function-level
  * middleware's `requires` may legitimately be satisfied by a group
  * middleware the function spec never sees, and group attachment is
  * declaratively order-independent with respect to `addFunction`.
@@ -346,9 +377,12 @@ export type ValidateFunctionAttach<
   FunctionProvenance_ extends FunctionProvenance.FunctionProvenance,
   MiddlewareSpecs_ extends AnyMiddlewareSpec,
 > = FunctionProvenance_ extends { readonly _tag: "Convex" }
-  ? AttachmentError<`Plain Convex functions cannot have middleware — their raw handlers are passed through untouched`>
+  ? AttachmentError<`Plain Convex functions cannot have middleware—their raw handlers are passed through untouched`>
   : [
-        Extract<MiddlewareSpecs_, { readonly key: Key<MiddlewareSpec_> }>,
+        Extract<
+          MiddlewareSpecs_,
+          { readonly key: Key<WithoutOptions<MiddlewareSpec_>> }
+        >,
       ] extends [never]
     ? RuntimeAndFunctionType_["functionType"] extends FunctionTypes<MiddlewareSpec_>
       ? unknown

package/src/PaginationOptions.ts

@@ -7,7 +7,7 @@ import * as Schema from "effect/Schema";
  * Use this as the `paginationOpts` field of a paginated query's args schema.
  * Beyond `numItems` and `cursor`, Convex's pagination protocol sends the
  * optional fields (`endCursor`, `id`, `maximumRowsRead`, `maximumBytesRead`)
- * with real requests — most notably `usePaginatedQuery` from `convex/react`
+ * with real requests—most notably `usePaginatedQuery` from `convex/react`
  * always includes `id`, and includes `endCursor` when splitting pages.
  * Declaring them is required for the generated Convex argument validator to
  * accept those requests and for the fields to survive decoding and reach