Support field calls in selection API

Author: shardulbee

packages/api-client-core/src/AnyClient.ts

@@ -1,3 +1,4 @@
+import type { $args } from "./FieldSelection.js";
 import type { GadgetConnection } from "./GadgetConnection.js";
 import type { GadgetTransaction } from "./GadgetTransaction.js";
 import type { InternalModelManager } from "./InternalModelManager.js";
@@ -18,6 +19,7 @@ export interface AnyClient {
   mutate(graphQL: string, variables?: Record<string, any>): Promise<any>;
   transaction<T>(callback: (transaction: GadgetTransaction) => Promise<T>): Promise<T>;
   internal: InternalModelManagerNamespace;
+  $args: typeof $args;
   apiClientCoreVersion?: string;
   [$modelRelationships]?: { [modelName: string]: { [apiIdentifier: string]: { type: string; model: string } } };
 }

packages/api-client-core/src/FieldSelection.ts

@@ -1,7 +1,29 @@
+/**
+ * Symbol key for field arguments in selections.
+ * Using a symbol avoids conflicts with string index signatures.
+ */
+export const $args = Symbol.for("gadget/fieldArgs");
+
+/**
+ * Type for field arguments (e.g., pagination, filtering on a field)
+ */
+export type FieldArgs = Record<string, any>;
+
 /**
  * Represents a list of fields selected from a GraphQL API call. Allows nesting, conditional selection.
  * Example: `{ id: true, name: false, richText: { markdown: true, html: false } }`
+ *
+ * Supports field arguments using the $args symbol:
+ * ```
+ * {
+ *   comments: {
+ *     [$args]: { after: "cursor", first: 10 },
+ *     body: true
+ *   }
+ * }
+ * ```
  **/
 export interface FieldSelection {
+  [$args]?: FieldArgs;
   [key: string]: boolean | null | undefined | FieldSelection;
 }

packages/core/spec/Select-type.spec.ts

@@ -1,6 +1,7 @@
 import type { AssertTrue, IsExact } from "conditional-type-checks";
 import type { DeepFilterNever, Select } from "../src/types.js";
-import type { TestSchema } from "./TestSchema.js";
+import { $args } from "../src/types.js";
+import type { TestSchema, TestSchemaWithFieldCalls } from "./TestSchema.js";
 
 describe("Select<>", () => {
   type _SelectingProperties = AssertTrue<IsExact<Select<TestSchema, { num: true }>, { num: number }>>;
@@ -75,5 +76,13 @@ describe("Select<>", () => {
     >
   >;
 
+  type _fieldCallSelection = Select<
+    TestSchemaWithFieldCalls,
+    { fieldCall: { [$args]: { arg: [1, 2, 3]; limit: 10 }; nestedField1: true; nestedField2: { nestedField3: true } } }
+  >;
+  type _TestSelectingFieldCall = AssertTrue<
+    IsExact<_fieldCallSelection, { fieldCall: { nestedField1: number; nestedField2: { nestedField3: string } } }>
+  >;
+
   test("true", () => undefined);
 });

packages/core/spec/TestSchema.ts

@@ -7,6 +7,17 @@ export type NestedThing = {
   nested: NestedThing;
 };
 
+export type TestSchemaWithFieldCalls = {
+  num: number;
+  str: string;
+  fieldCall: {
+    nestedField1: number;
+    nestedField2: {
+      nestedField3: string;
+    };
+  };
+};
+
 export type TestSchema = {
   num: number;
   str: string;

packages/core/src/types.ts

@@ -115,7 +115,8 @@ type InnerSelect<Schema, Selection extends FieldSelection | null | undefined> =
     : Schema extends null
     ? InnerSelect<Exclude<Schema, null>, Selection> | null
     : {
-        [Key in keyof Selection & keyof Schema]: Selection[Key] extends true
+        // Exclude the $args symbol key - it's for field arguments, not nested selections
+        [Key in Exclude<keyof Selection, typeof $args> & keyof Schema]: Selection[Key] extends true
           ? Schema[Key]
           : Selection[Key] extends FieldSelection
           ? InnerSelect<Schema[Key], Selection[Key]>
@@ -989,10 +990,32 @@ export type ViewResult<F extends ViewFunction<any, any>> = Awaited<
   F extends ViewFunctionWithVariables<any, infer Result> ? Result : F extends ViewFunctionWithoutVariables<infer Result> ? Result : never
 >;
 
+/**
+ * Symbol key for field arguments in selections.
+ * Using a symbol avoids conflicts with string index signatures.
+ */
+export const $args = Symbol.for("gadget/fieldArgs");
+
+/**
+ * Type for field arguments (e.g., pagination, filtering on a field)
+ */
+export type FieldArgs = Record<string, any>;
+
 /**
  * Represents a list of fields selected from a GraphQL API call. Allows nesting, conditional selection.
  * Example: `{ id: true, name: false, richText: { markdown: true, html: false } }`
+ *
+ * Supports field arguments using the $args symbol:
+ * ```
+ * {
+ *   comments: {
+ *     [$args]: { after: "cursor", first: 10 },
+ *     body: true
+ *   }
+ * }
+ * ```
  **/
 export interface FieldSelection {
+  [$args]?: FieldArgs;
   [key: string]: boolean | null | undefined | FieldSelection;
 }