feat(graphql): add comprehensive support for AllowlistRecord with enhanced querying and resolving

Implemented a complete solution for AllowlistRecord with:
- Updated GraphQL schema to support hypercert relations
- Refactored AllowlistQueryStrategy to handle complex filtering
- Created a new GraphQL resolver with field-level hypercert resolution
- Added comprehensive test coverage for AllowlistRecordService and resolver
- Migrated resolver to a service folder to cleaner organisation of code
- testing all the things

Author: bitbeckers

src/graphql/schemas/args/allowlistRecordArgs.ts

@@ -1,21 +1,21 @@
 import { ArgsType } from "type-graphql";
 import { BaseQueryArgs } from "../../../lib/graphql/BaseQueryArgs.js";
 import { createEntityArgs } from "../../../lib/graphql/createEntityArgs.js";
+import { EntityTypeDefs } from "../typeDefs/typeDefs.js";
+import { WhereFieldDefinitions } from "../../../lib/graphql/whereFieldDefinitions.js";
 
 const {
   WhereInput: AllowlistRecordWhereInput,
   SortOptions: AllowlistRecordSortOptions,
 } = createEntityArgs("AllowlistRecord", {
-  hypercert_id: "string",
-  token_id: "string",
-  leaf: "string",
-  entry: "number",
-  user_address: "string",
-  claimed: "boolean",
-  proof: "stringArray",
-  units: "bigint",
-  total_units: "bigint",
-  root: "string",
+  ...WhereFieldDefinitions.AllowlistRecord.fields,
+  hypercert: {
+    type: "id",
+    references: {
+      entity: EntityTypeDefs.Hypercert,
+      fields: WhereFieldDefinitions.Hypercert.fields,
+    },
+  },
 });
 
 @ArgsType()

src/graphql/schemas/resolvers/allowlistRecordResolver.ts

@@ -6,7 +6,7 @@ import { AttestationResolver } from "./attestationResolver.js";
 import { AttestationSchemaResolver } from "./attestationSchemaResolver.js";
 import { OrderResolver } from "./orderResolver.js";
 import { HyperboardResolver } from "./hyperboardResolver.js";
-import { AllowlistRecordResolver } from "./allowlistRecordResolver.js";
+import { AllowlistRecordResolver } from "../../../services/graphql/resolvers/allowlistRecordResolver.js";
 import { SalesResolver } from "./salesResolver.js";
 import { UserResolver } from "./userResolver.js";
 import { BlueprintResolver } from "./blueprintResolver.js";

src/graphql/schemas/resolvers/composed.ts

@@ -1,6 +1,8 @@
 import { Field, ObjectType } from "type-graphql";
-import { EthBigInt } from "../../scalars/ethBigInt.js";
 import { DataResponse } from "../../../lib/graphql/DataResponse.js";
+import { EthBigInt } from "../../scalars/ethBigInt.js";
+import { Hypercert } from "./hypercertTypeDefs.js";
+
 @ObjectType({
   description: "Records of allow list entries for claimable fractions",
   simpleResolvers: true,
@@ -58,6 +60,12 @@ export class AllowlistRecord {
     description: "The root of the allow list Merkle tree",
   })
   root?: string;
+
+  @Field(() => Hypercert, {
+    nullable: true,
+    description: "The hypercert that the allow list record belongs to",
+  })
+  hypercert?: Hypercert;
 }
 
 @ObjectType()

src/graphql/schemas/typeDefs/allowlistRecordTypeDefs.ts

@@ -21,6 +21,20 @@
  */
 // TODO: key values can be keyof EntityTypeDefs
 export const WhereFieldDefinitions = {
+  AllowlistRecord: {
+    fields: {
+      hypercert_id: "string",
+      token_id: "bigint",
+      leaf: "string",
+      entry: "number",
+      user_address: "string",
+      claimed: "boolean",
+      proof: "stringArray",
+      units: "bigint",
+      total_units: "bigint",
+      root: "string",
+    },
+  },
   Attestation: {
     fields: {
       id: "string",

src/lib/graphql/whereFieldDefinitions.ts

@@ -8,27 +8,39 @@ import {
   type EntityService,
 } from "./EntityServiceFactory.js";
 
-export type AllowlistRecordSelect = Selectable<
-  CachingDatabase["claimable_fractions_with_proofs"]
->;
-export type AllowlistRecordInsert = Insertable<
-  CachingDatabase["claimable_fractions_with_proofs"]
->;
-export type AllowlistRecordUpdate = Updateable<
-  CachingDatabase["claimable_fractions_with_proofs"]
->;
+/** The name of the allowlist records table */
+type TableName = "claimable_fractions_with_proofs";
+/** The type of the allowlist records table */
+type Table = CachingDatabase[TableName];
 
+/** Type representing a selectable record from the claimable_fractions_with_proofs table */
+export type AllowlistRecordSelect = Selectable<Table>;
+
+/** Type representing an insertable record for the claimable_fractions_with_proofs table */
+export type AllowlistRecordInsert = Insertable<Table>;
+
+/** Type representing an updateable record for the claimable_fractions_with_proofs table */
+export type AllowlistRecordUpdate = Updateable<Table>;
+
+/**
+ * Service class for managing allowlist records in the claimable_fractions_with_proofs table.
+ * This service provides methods to query and retrieve allowlist records using the EntityService pattern.
+ *
+ * @injectable
+ */
 @injectable()
 export class AllowlistRecordService {
-  private entityService: EntityService<
-    CachingDatabase["claimable_fractions_with_proofs"],
-    GetAllowlistRecordsArgs
-  >;
+  /** The underlying entity service instance for database operations */
+  private entityService: EntityService<Table, GetAllowlistRecordsArgs>;
 
+  /**
+   * Initializes a new instance of the AllowlistRecordService.
+   * Creates an EntityService instance for the claimable_fractions_with_proofs table.
+   */
   constructor() {
     this.entityService = createEntityService<
       CachingDatabase,
-      "claimable_fractions_with_proofs",
+      TableName,
       GetAllowlistRecordsArgs
     >(
       "claimable_fractions_with_proofs",
@@ -37,10 +49,22 @@ export class AllowlistRecordService {
     );
   }
 
+  /**
+   * Retrieves multiple allowlist records based on the provided arguments.
+   *
+   * @param args - Query arguments for filtering allowlist records
+   * @returns A promise that resolves to an array of allowlist records and a count of total records
+   */
   async getAllowlistRecords(args: GetAllowlistRecordsArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single allowlist record based on the provided arguments.
+   *
+   * @param args - Query arguments for filtering the allowlist record
+   * @returns A promise that resolves to a single allowlist record or null if not found
+   */
   async getAllowlistRecord(args: GetAllowlistRecordsArgs) {
     return this.entityService.getSingle(args);
   }

src/services/database/entities/AllowListRecordEntityService.ts

@@ -1,24 +1,69 @@
 import { Kysely } from "kysely";
+import { GetAllowlistRecordsArgs } from "../../../graphql/schemas/args/allowlistRecordArgs.js";
+import { isWhereEmpty } from "../../../lib/strategies/isWhereEmpty.js";
 import { CachingDatabase } from "../../../types/kyselySupabaseCaching.js";
 import { QueryStrategy } from "./QueryStrategy.js";
 
 /**
- * Strategy for querying allowlist records
- * Implements queries for the claimable_fractions_with_proofs view table
+ * Strategy class for querying allowlist records from the claimable_fractions_with_proofs view table.
+ * This class extends the base QueryStrategy to provide specific implementation for allowlist-related queries.
  */
 export class AllowlistQueryStrategy extends QueryStrategy<
   CachingDatabase,
-  "claimable_fractions_with_proofs"
+  "claimable_fractions_with_proofs",
+  GetAllowlistRecordsArgs
 > {
+  /** The name of the table this strategy queries against */
   protected readonly tableName = "claimable_fractions_with_proofs" as const;
 
-  buildDataQuery(db: Kysely<CachingDatabase>) {
-    return db.selectFrom(this.tableName).selectAll();
+  /**
+   * Builds a query to fetch allowlist records from the database.
+   */
+  buildDataQuery(db: Kysely<CachingDatabase>, args?: GetAllowlistRecordsArgs) {
+    if (!args) {
+      return db.selectFrom(this.tableName).selectAll();
+    }
+
+    return db
+      .selectFrom(this.tableName)
+      .$if(!isWhereEmpty(args.where?.hypercert), (qb) =>
+        qb.where(({ exists, selectFrom }) =>
+          exists(
+            selectFrom("claims").whereRef(
+              "claims.hypercert_id",
+              "=",
+              "claimable_fractions_with_proofs.hypercert_id",
+            ),
+          ),
+        ),
+      )
+      .selectAll(this.tableName);
   }
 
-  buildCountQuery(db: Kysely<CachingDatabase>) {
-    return db.selectFrom(this.tableName).select((eb) => {
-      return eb.fn.countAll().as("count");
-    });
+  /**
+   * Builds a query to count the total number of allowlist records.
+   */
+  buildCountQuery(db: Kysely<CachingDatabase>, args?: GetAllowlistRecordsArgs) {
+    if (!args) {
+      return db.selectFrom(this.tableName).select((eb) => {
+        return eb.fn.countAll().as("count");
+      });
+    }
+    return db
+      .selectFrom(this.tableName)
+      .$if(!isWhereEmpty(args.where?.hypercert), (qb) =>
+        qb.where(({ exists, selectFrom }) =>
+          exists(
+            selectFrom("claims").whereRef(
+              "claims.hypercert_id",
+              "=",
+              "claimable_fractions_with_proofs.hypercert_id",
+            ),
+          ),
+        ),
+      )
+      .select((eb) => {
+        return eb.fn.countAll().as("count");
+      });
   }
 }

src/services/database/strategies/AllowlistQueryStrategy.ts

@@ -0,0 +1,96 @@
+import { inject, injectable } from "tsyringe";
+import { Args, FieldResolver, Query, Resolver, Root } from "type-graphql";
+import { AllowlistRecordService } from "../../database/entities/AllowListRecordEntityService.js";
+import { HypercertsService } from "../../database/entities/HypercertsEntityService.js";
+import { GetAllowlistRecordsArgs } from "../../../graphql/schemas/args/allowlistRecordArgs.js";
+import {
+  AllowlistRecord,
+  GetAllowlistRecordResponse,
+} from "../../../graphql/schemas/typeDefs/allowlistRecordTypeDefs.js";
+
+/**
+ * GraphQL resolver for AllowlistRecord operations.
+ * Handles queries for allowlist records and resolves related fields.
+ *
+ * This resolver provides:
+ * - Query for fetching allowlist records with optional filtering
+ * - Field resolution for the hypercert field, which loads the associated hypercert data
+ *
+ * @injectable Marks the class as injectable for dependency injection with tsyringe
+ * @resolver Marks the class as a GraphQL resolver for the AllowlistRecord type
+ */
+@injectable()
+@Resolver(() => AllowlistRecord)
+class AllowlistRecordResolver {
+  /**
+   * Creates a new instance of AllowlistRecordResolver.
+   *
+   * @param allowlistRecordService - Service for handling allowlist record operations
+   * @param hypercertsService - Service for handling hypercert operations
+   */
+  constructor(
+    @inject(AllowlistRecordService)
+    private allowlistRecordService: AllowlistRecordService,
+    @inject(HypercertsService)
+    private hypercertsService: HypercertsService,
+  ) {}
+
+  /**
+   * Queries allowlist records based on provided arguments.
+   *
+   * @param args - Query arguments for filtering allowlist records
+   * @returns A promise that resolves to an object containing:
+   *          - data: Array of allowlist records matching the query
+   *          - count: Total number of records matching the query
+   *
+   * @example
+   * Query:
+   * ```graphql
+   * query {
+   *   allowlistRecords(where: { hypercert: { hypercert_id: { eq: "123" } } }) {
+   *     data {
+   *       id
+   *       hypercert_id
+   *     }
+   *     count
+   *   }
+   * }
+   * ```
+   */
+  @Query(() => GetAllowlistRecordResponse)
+  async allowlistRecords(@Args() args: GetAllowlistRecordsArgs) {
+    return await this.allowlistRecordService.getAllowlistRecords(args);
+  }
+
+  /**
+   * Resolves the hypercert field for an allowlist record.
+   * This field resolver is called automatically when the hypercert field is requested in a query.
+   *
+   * @param allowlistRecord - The allowlist record for which to resolve the hypercert
+   * @returns A promise that resolves to the associated hypercert data or null if not found
+   *
+   * @example
+   * Query with hypercert field:
+   * ```graphql
+   * query {
+   *   allowlistRecords {
+   *     data {
+   *       id
+   *       hypercert {
+   *         id
+   *         name
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  @FieldResolver()
+  async hypercert(@Root() allowlistRecord: AllowlistRecord) {
+    return await this.hypercertsService.getHypercert({
+      where: { hypercert_id: { eq: allowlistRecord.hypercert_id } },
+    });
+  }
+}
+
+export { AllowlistRecordResolver };