refactor(contract): restructure contract resolver and related components

Refactored contract-related code to improve organization and maintainability:
- Moved ContractResolver from graphql to services directory
- Updated import paths in composed resolver
- Modified WhereFieldDefinitions for contract fields so that chain_id is bigint not number
- Enhanced ContractEntityService with comprehensive documentation
- Added detailed JSDoc comments for ContractService and ContractsQueryStrategy
- Updated field types and naming conventions for improved type safety

Author: bitbeckers

src/graphql/schemas/resolvers/composed.ts

@@ -1,6 +1,6 @@
 import { HypercertResolver } from "./hypercertResolver.js";
 import { MetadataResolver } from "./metadataResolver.js";
-import { ContractResolver } from "./contractResolver.js";
+import { ContractResolver } from "../../../services/graphql/resolvers/contractResolver.js";
 import { FractionResolver } from "./fractionResolver.js";
 import { AttestationResolver } from "../../../services/graphql/resolvers/attestationResolver.js";
 import { AttestationSchemaResolver } from "../../../services/graphql/resolvers/attestationSchemaResolver.js";

src/graphql/schemas/resolvers/contractResolver.ts

@@ -77,8 +77,8 @@ export const WhereFieldDefinitions = {
   Contract: {
     fields: {
       id: "string",
-      address: "string",
-      chain_id: "number",
+      contract_address: "string",
+      chain_id: "bigint",
     },
   },
   Fraction: {

src/lib/graphql/whereFieldDefinitions.ts

@@ -8,15 +8,36 @@ import {
   type EntityService,
 } from "./EntityServiceFactory.js";
 
+/** Type representing a selected contract record from the database */
 export type ContractSelect = Selectable<CachingDatabase["contracts"]>;
 
+/**
+ * Service class for managing contract entities in the database.
+ * Handles CRUD operations for contracts deployed on various chains.
+ *
+ * This service provides methods to:
+ * - Retrieve multiple contracts with filtering and pagination
+ * - Retrieve a single contract by its criteria
+ *
+ * Each contract represents a smart contract deployed on a blockchain,
+ * containing information such as:
+ * - Chain ID
+ * - Contract address
+ * - Deployment block number
+ *
+ * @injectable Marks the class as injectable for dependency injection with tsyringe
+ */
 @injectable()
 export class ContractService {
   private entityService: EntityService<
     CachingDatabase["contracts"],
     GetContractsArgs
   >;
 
+  /**
+   * Creates a new instance of ContractService.
+   * Initializes the underlying entity service for database operations.
+   */
   constructor() {
     this.entityService = createEntityService<
       CachingDatabase,
@@ -25,10 +46,53 @@ export class ContractService {
     >("contracts", "ContractEntityService", kyselyCaching);
   }
 
+  /**
+   * Retrieves multiple contracts based on provided arguments.
+   *
+   * @param args - Query arguments for filtering and pagination
+   * @returns A promise that resolves to an object containing:
+   *          - data: Array of contracts matching the query
+   *          - count: Total number of matching contracts
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * const result = await service.getContracts({
+   *   where: {
+   *     chain_id: { eq: "1" },
+   *     contract_address: { eq: "0x..." }
+   *   }
+   * });
+   * console.log(result.data); // Array of matching contracts
+   * console.log(result.count); // Total count
+   * ```
+   */
   async getContracts(args: GetContractsArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single contract based on provided arguments.
+   *
+   * @param args - Query arguments for filtering
+   * @returns A promise that resolves to:
+   *          - The matching contract if found
+   *          - undefined if no contract matches the criteria
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * const contract = await service.getContract({
+   *   where: {
+   *     chain_id: { eq: "1" },
+   *     contract_address: { eq: "0x..." }
+   *   }
+   * });
+   * if (contract) {
+   *   console.log("Found contract:", contract);
+   * }
+   * ```
+   */
   async getContract(args: GetContractsArgs) {
     return this.entityService.getSingle(args);
   }

src/services/database/entities/ContractEntityService.ts

@@ -3,19 +3,52 @@ import { CachingDatabase } from "../../../types/kyselySupabaseCaching.js";
 import { QueryStrategy } from "./QueryStrategy.js";
 
 /**
- * Strategy for querying contracts
- * Handles joins with claims table
+ * Strategy for building database queries for contracts.
+ * Implements query logic for contract retrieval and counting.
+ *
+ * This strategy extends the base QueryStrategy to provide contract-specific query building.
+ * It handles basic data retrieval and counting operations for contracts deployed on various chains.
+ *
+ * @template CachingDatabase - The database type containing the contracts table
  */
 export class ContractsQueryStrategy extends QueryStrategy<
   CachingDatabase,
   "contracts"
 > {
   protected readonly tableName = "contracts" as const;
 
+  /**
+   * Builds a query to retrieve contract data.
+   * Returns a simple SELECT query that retrieves all columns from the contracts table.
+   *
+   * @param db - Kysely database instance
+   * @returns A query builder for retrieving contract data
+   *
+   * @example
+   * ```typescript
+   * // Basic query to select all contracts
+   * buildDataQuery(db);
+   * // SELECT * FROM contracts
+   * ```
+   */
   buildDataQuery(db: Kysely<CachingDatabase>) {
     return db.selectFrom(this.tableName).selectAll(this.tableName);
   }
 
+  /**
+   * Builds a query to count contracts.
+   * Returns a simple COUNT query for the contracts table.
+   *
+   * @param db - Kysely database instance
+   * @returns A query builder for counting contracts
+   *
+   * @example
+   * ```typescript
+   * // Count all contracts
+   * buildCountQuery(db);
+   * // SELECT COUNT(*) as count FROM contracts
+   * ```
+   */
   buildCountQuery(db: Kysely<CachingDatabase>) {
     return db.selectFrom(this.tableName).select((eb) => {
       return eb.fn.countAll().as("count");

src/services/database/strategies/ContractsQueryStrategy.ts

@@ -0,0 +1,77 @@
+import { inject, injectable } from "tsyringe";
+import { Args, Query, Resolver } from "type-graphql";
+import { ContractService } from "../../database/entities/ContractEntityService.js";
+import { GetContractsArgs } from "../../../graphql/schemas/args/contractArgs.js";
+import {
+  Contract,
+  GetContractsResponse,
+} from "../../../graphql/schemas/typeDefs/contractTypeDefs.js";
+
+/**
+ * GraphQL resolver for Contract operations.
+ * Handles queries for contracts deployed on various chains.
+ *
+ * This resolver provides:
+ * - Query for fetching contracts with optional filtering
+ * - Support for pagination and sorting
+ *
+ * Each contract represents a smart contract deployed on a blockchain,
+ * containing information such as:
+ * - Chain ID
+ * - Contract address
+ * - Deployment block number
+ *
+ * @injectable Marks the class as injectable for dependency injection with tsyringe
+ * @resolver Marks the class as a GraphQL resolver for the Contract type
+ */
+@injectable()
+@Resolver(() => Contract)
+class ContractResolver {
+  /**
+   * Creates a new instance of ContractResolver.
+   *
+   * @param contractService - Service for handling contract operations
+   */
+  constructor(
+    @inject(ContractService)
+    private contractService: ContractService,
+  ) {}
+
+  /**
+   * Queries contracts based on provided arguments.
+   * Returns both the matching contracts and a total count.
+   *
+   * @param args - Query arguments for filtering contracts
+   * @returns A promise that resolves to an object containing:
+   *          - data: Array of contracts matching the query
+   *          - count: Total number of matching contracts
+   * @throws {Error} If the contract service query fails
+   *
+   * @example
+   * Query with filtering:
+   * ```graphql
+   * query {
+   *   contracts(
+   *     where: {
+   *       chain_id: { eq: "1" },
+   *       contract_address: { eq: "0x..." }
+   *     }
+   *   ) {
+   *     data {
+   *       id
+   *       chain_id
+   *       contract_address
+   *       start_block
+   *     }
+   *     count
+   *   }
+   * }
+   * ```
+   */
+  @Query(() => GetContractsResponse)
+  async contracts(@Args() args: GetContractsArgs) {
+    return this.contractService.getContracts(args);
+  }
+}
+
+export { ContractResolver };