refactor(fraction): restructure fraction resolver and related components

Refactored fraction-related code to improve organization and maintainability:
- Moved FractionResolver from graphql to services directory
- Updated import paths in composed resolver
- Relocated fractionResolver from local to services directory
- Enhanced FractionEntityService with comprehensive documentation
- Added detailed JSDoc comments for FractionService and FractionsQueryStrategy
- Introduced comprehensive test coverage for FractionService, FractionsQueryStrategy, and FractionResolver
- Improved type safety and code clarity across related files
- updated error handling to not throw in failed resolved fields queries
- introduced test utils for recurring methods

Author: bitbeckers

src/graphql/schemas/resolvers/composed.ts

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

src/graphql/schemas/resolvers/fractionResolver.ts

@@ -8,15 +8,31 @@ import {
   type EntityService,
 } from "./EntityServiceFactory.js";
 
+/** Type representing a selected fraction record from the database */
 export type FractionSelect = Selectable<CachingDatabase["fractions_view"]>;
 
+/**
+ * Service class for managing fraction entities in the database.
+ * Handles CRUD operations for hypercert fractions, which represent ownership units of hypercerts.
+ *
+ * This service provides methods to:
+ * - Query multiple fractions with filtering and pagination
+ * - Retrieve single fraction records by various criteria
+ *
+ * @injectable
+ */
 @injectable()
 export class FractionService {
+  /** The underlying entity service instance for database operations */
   private entityService: EntityService<
     CachingDatabase["fractions_view"],
     GetFractionsArgs
   >;
 
+  /**
+   * Initializes a new instance of the FractionService.
+   * Creates an EntityService instance for the fractions_view table.
+   */
   constructor() {
     this.entityService = createEntityService<
       CachingDatabase,
@@ -25,10 +41,42 @@ export class FractionService {
     >("fractions_view", "FractionEntityService", kyselyCaching);
   }
 
+  /**
+   * Retrieves multiple fractions based on the provided arguments.
+   *
+   * @param args - Query arguments for filtering fractions
+   * @returns Promise resolving to an object containing:
+   *          - data: Array of fraction records
+   *          - count: Total number of matching records
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * // Get all fractions owned by a specific address
+   * const result = await fractionService.getFractions({
+   *   where: { owner_address: { eq: "0x..." } }
+   * });
+   * ```
+   */
   async getFractions(args: GetFractionsArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single fraction based on the provided arguments.
+   *
+   * @param args - Query arguments for filtering the fraction
+   * @returns Promise resolving to a single fraction record or undefined if not found
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * // Get a specific fraction by ID
+   * const fraction = await fractionService.getFraction({
+   *   where: { units: { eq: 100n } }
+   * });
+   * ```
+   */
   async getFraction(args: GetFractionsArgs) {
     return this.entityService.getSingle(args);
   }

src/services/database/entities/FractionEntityService.ts

@@ -4,13 +4,49 @@ import { CachingDatabase } from "../../../types/kyselySupabaseCaching.js";
 import { QueryStrategy } from "./QueryStrategy.js";
 import { isWhereEmpty } from "../../../lib/strategies/isWhereEmpty.js";
 
+/**
+ * Strategy for building database queries for fractions.
+ * Implements query logic for fraction retrieval and counting.
+ *
+ * This strategy extends the base QueryStrategy to provide fraction-specific query building.
+ * It handles:
+ * - Basic data retrieval from the fractions_view
+ * - Filtering based on metadata relationships
+ * - Counting operations with appropriate joins
+ *
+ * @template CachingDatabase - The database type containing the fractions_view table
+ */
 export class FractionsQueryStrategy extends QueryStrategy<
   CachingDatabase,
   "fractions_view",
   GetFractionsArgs
 > {
   protected readonly tableName = "fractions_view" as const;
 
+  /**
+   * Builds a query to retrieve fraction data.
+   * Handles optional metadata filtering through joins with claims and metadata tables.
+   *
+   * @param db - Kysely database instance
+   * @param args - Optional query arguments for filtering
+   * @returns A query builder for retrieving fraction data
+   *
+   * @example
+   * ```typescript
+   * // Basic query to select all fractions
+   * buildDataQuery(db);
+   * // SELECT * FROM fractions_view
+   *
+   * // Query with metadata filtering
+   * buildDataQuery(db, { where: { metadata: { ... } } });
+   * // SELECT * FROM fractions_view
+   * // WHERE EXISTS (
+   * //   SELECT * FROM claims
+   * //   LEFT JOIN metadata ON metadata.id = fractions_view.claims_id
+   * //   WHERE claims.id = fractions_view.claims_id
+   * // )
+   * ```
+   */
   buildDataQuery(db: Kysely<CachingDatabase>, args?: GetFractionsArgs) {
     if (!args) {
       return db.selectFrom(this.tableName).selectAll();
@@ -30,6 +66,30 @@ export class FractionsQueryStrategy extends QueryStrategy<
       .selectAll(this.tableName);
   }
 
+  /**
+   * Builds a query to count fractions.
+   * Handles optional metadata filtering through joins with claims and metadata tables.
+   *
+   * @param db - Kysely database instance
+   * @param args - Optional query arguments for filtering
+   * @returns A query builder for counting fractions
+   *
+   * @example
+   * ```typescript
+   * // Count all fractions
+   * buildCountQuery(db);
+   * // SELECT COUNT(*) as count FROM fractions_view
+   *
+   * // Count with metadata filtering
+   * buildCountQuery(db, { where: { metadata: { ... } } });
+   * // SELECT COUNT(*) as count FROM fractions_view
+   * // WHERE EXISTS (
+   * //   SELECT * FROM claims
+   * //   LEFT JOIN metadata ON metadata.id = fractions_view.claims_id
+   * //   WHERE claims.id = fractions_view.claims_id
+   * // )
+   * ```
+   */
   buildCountQuery(db: Kysely<CachingDatabase>, args?: GetFractionsArgs) {
     if (!args) {
       return db.selectFrom(this.tableName).select((eb) => {