refactor(blueprint): restructure blueprint resolver and related components

Refactored blueprint-related code to improve organization and maintainability:
- Moved BlueprintResolver from graphql to services directory
- Updated import paths in composed resolver
- Enhanced BlueprintsEntityService with comprehensive documentation
- Added detailed JSDoc comments for BlueprintsService and BlueprintResolver
- Introduced comprehensive test coverage for BlueprintsService, BlueprintResolver
- Updated Vitest configuration to adjust code coverage thresholds
- Improved error handling to return null for failed resolver queries
- Standardized code structure with other similar resolvers
- Introduced data database test utility for support the more complex interactions. For example the blueprint entityservice which interacts with multiple tables surin some method executions

Author: bitbeckers

src/graphql/schemas/resolvers/blueprintResolver.ts

@@ -9,7 +9,7 @@ import { HyperboardResolver } from "./hyperboardResolver.js";
 import { AllowlistRecordResolver } from "../../../services/graphql/resolvers/allowlistRecordResolver.js";
 import { SalesResolver } from "../../../services/graphql/resolvers/salesResolver.js";
 import { UserResolver } from "./userResolver.js";
-import { BlueprintResolver } from "./blueprintResolver.js";
+import { BlueprintResolver } from "../../../services/graphql/resolvers/blueprintResolver.js";
 import { SignatureRequestResolver } from "./signatureRequestResolver.js";
 import { CollectionResolver } from "./collectionResolver.js";
 

src/graphql/schemas/resolvers/composed.ts

@@ -13,13 +13,36 @@ export type BlueprintUpdate = Updateable<DataDatabase["blueprints"]>;
 
 export type BlueprintAdminSelect = Selectable<DataDatabase["users"]>;
 
+/**
+ * Service for handling blueprint-related database operations.
+ * Provides methods for CRUD operations on blueprints and managing blueprint admins.
+ *
+ * Features:
+ * - Fetch blueprints with filtering and pagination
+ * - Manage blueprint administrators
+ * - Handle blueprint minting and collection updates
+ * - Transaction support for complex operations
+ *
+ * Error Handling:
+ * - All database operations are wrapped in try-catch blocks
+ * - Errors are logged and rethrown for proper error propagation
+ * - Transaction rollback on failure for multi-step operations
+ *
+ * @singleton Marks the class as a singleton for dependency injection
+ */
 @singleton()
 export class BlueprintsService {
   private entityService: EntityService<
     DataDatabase["blueprints"],
     GetBlueprintsArgs
   >;
 
+  /**
+   * Creates a new instance of BlueprintsService.
+   *
+   * @param dbService - Service for database operations
+   * @param usersService - Service for user-related operations
+   */
   constructor(
     @inject(DataKyselyService) private dbService: DataKyselyService,
     @inject(UsersService) private usersService: UsersService,
@@ -31,14 +54,37 @@ export class BlueprintsService {
     >("blueprints", "BlueprintsEntityService", kyselyData);
   }
 
+  /**
+   * Retrieves blueprints based on provided arguments.
+   *
+   * @param args - Query arguments for filtering and pagination
+   * @returns Promise resolving to an object containing:
+   *          - data: Array of matching blueprints
+   *          - count: Total number of matching blueprints
+   * @throws Error if database operation fails
+   */
   async getBlueprints(args: GetBlueprintsArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single blueprint based on provided arguments.
+   *
+   * @param args - Query arguments for filtering
+   * @returns Promise resolving to a single blueprint or undefined if not found
+   * @throws Error if database operation fails
+   */
   async getBlueprint(args: GetBlueprintsArgs) {
     return this.entityService.getSingle(args);
   }
 
+  /**
+   * Retrieves administrators for a specific blueprint.
+   *
+   * @param blueprintId - ID of the blueprint
+   * @returns Promise resolving to an array of admin users
+   * @throws Error if database operation fails
+   */
   async getBlueprintAdmins(blueprintId: number) {
     return await this.dbService
       .getConnection()
@@ -49,7 +95,13 @@ export class BlueprintsService {
       .execute();
   }
 
-  // Mutations
+  /**
+   * Deletes a blueprint by ID.
+   *
+   * @param blueprintId - ID of the blueprint to delete
+   * @returns Promise resolving when deletion is complete
+   * @throws Error if database operation fails
+   */
   async deleteBlueprint(blueprintId: number) {
     return this.dbService
       .getConnection()
@@ -58,6 +110,13 @@ export class BlueprintsService {
       .execute();
   }
 
+  /**
+   * Creates or updates multiple blueprints.
+   *
+   * @param blueprints - Array of blueprints to create or update
+   * @returns Promise resolving to an array of created/updated blueprint IDs
+   * @throws Error if database operation fails
+   */
   async upsertBlueprints(blueprints: BlueprintInsert[]) {
     return this.dbService
       .getConnection()
@@ -75,6 +134,16 @@ export class BlueprintsService {
       .execute();
   }
 
+  /**
+   * Adds an administrator to a blueprint.
+   * Creates the user if they don't exist.
+   *
+   * @param blueprintId - ID of the blueprint
+   * @param adminAddress - Ethereum address of the admin
+   * @param chainId - Chain ID where the admin address is valid
+   * @returns Promise resolving to the created/updated admin record
+   * @throws Error if database operation fails
+   */
   async addAdminToBlueprint(
     blueprintId: number,
     adminAddress: string,
@@ -104,6 +173,22 @@ export class BlueprintsService {
       .executeTakeFirst();
   }
 
+  /**
+   * Mints a blueprint and updates related collections.
+   * This operation:
+   * 1. Gets all blueprint hyperboard metadata
+   * 2. Inserts the new hypercert into collections
+   * 3. Updates hyperboard metadata
+   * 4. Marks the blueprint as minted
+   * 5. Removes the blueprint from collections
+   *
+   * All operations are wrapped in a transaction for atomicity.
+   *
+   * @param blueprintId - ID of the blueprint to mint
+   * @param hypercertId - ID of the newly created hypercert
+   * @returns Promise resolving when all operations are complete
+   * @throws Error if any database operation fails (triggers rollback)
+   */
   async mintBlueprintAndSwapInCollections(
     blueprintId: number,
     hypercertId: string,

src/services/database/entities/BlueprintsEntityService.ts

@@ -0,0 +1,190 @@
+import { Args, FieldResolver, Query, Resolver, Root } from "type-graphql";
+import {
+  Blueprint,
+  GetBlueprintsResponse,
+} from "../../../graphql/schemas/typeDefs/blueprintTypeDefs.js";
+import { GetBlueprintsArgs } from "../../../graphql/schemas/args/blueprintArgs.js";
+import { inject, injectable } from "tsyringe";
+import { BlueprintsService } from "../../database/entities/BlueprintsEntityService.js";
+import { HypercertsService } from "../../database/entities/HypercertsEntityService.js";
+
+/**
+ * GraphQL resolver for Blueprint operations.
+ * Handles queries for blueprints and resolves related fields.
+ *
+ * This resolver provides:
+ * - Query for fetching blueprints with optional filtering
+ * - Field resolution for admins associated with a blueprint
+ * - Field resolution for hypercerts associated with a blueprint
+ *
+ * Error Handling:
+ * All resolvers follow the GraphQL best practice of returning partial data instead of throwing errors.
+ * If an operation fails, it will:
+ * - Log the error internally for monitoring
+ * - Return null/empty data to the client
+ * - Include error information in the GraphQL response errors array
+ *
+ * @injectable Marks the class as injectable for dependency injection with tsyringe
+ * @resolver Marks the class as a GraphQL resolver for the Blueprint type
+ */
+@injectable()
+@Resolver(() => Blueprint)
+class BlueprintResolver {
+  /**
+   * Creates a new instance of BlueprintResolver.
+   *
+   * @param blueprintsService - Service for handling blueprint operations
+   * @param hypercertsService - Service for handling hypercert operations
+   */
+  constructor(
+    @inject(BlueprintsService)
+    private blueprintsService: BlueprintsService,
+    @inject(HypercertsService)
+    private hypercertsService: HypercertsService,
+  ) {}
+
+  /**
+   * Queries blueprints based on provided arguments.
+   * Returns both the matching blueprints and a total count.
+   *
+   * @param args - Query arguments for filtering blueprints
+   * @returns A promise that resolves to an object containing:
+   *          - data: Array of blueprints matching the query
+   *          - count: Total number of matching blueprints
+   *          Returns null if an error occurs
+   *
+   * @example
+   * ```graphql
+   * query {
+   *   blueprints(
+   *     where: {
+   *       id: { eq: "blueprint-1" }
+   *     }
+   *   ) {
+   *     data {
+   *       id
+   *       name
+   *       description
+   *       admins {
+   *         address
+   *         display_name
+   *       }
+   *     }
+   *     count
+   *   }
+   * }
+   * ```
+   */
+  @Query(() => GetBlueprintsResponse)
+  async blueprints(@Args() args: GetBlueprintsArgs) {
+    try {
+      return await this.blueprintsService.getBlueprints(args);
+    } catch (e) {
+      console.error(
+        `[BlueprintResolver::blueprints] Error fetching blueprints: ${(e as Error).message}`,
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Resolves the admins field for a blueprint.
+   * Retrieves the list of administrators associated with the blueprint.
+   *
+   * @param blueprint - The blueprint for which to resolve admins
+   * @returns A promise resolving to:
+   *          - Array of admin users if found
+   *          - Empty array if:
+   *            - No blueprint ID is available
+   *            - An error occurs during retrieval
+   *
+   * @example
+   * ```graphql
+   * query {
+   *   blueprints {
+   *     data {
+   *       id
+   *       admins {
+   *         address
+   *         display_name
+   *         avatar
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  @FieldResolver()
+  async admins(@Root() blueprint: Blueprint) {
+    if (!blueprint.id) {
+      console.warn(
+        `[BlueprintResolver::admins] No blueprint id found for ${blueprint.id}`,
+      );
+      return [];
+    }
+
+    try {
+      return await this.blueprintsService.getBlueprintAdmins(blueprint.id);
+    } catch (e) {
+      console.error(
+        `[BlueprintResolver::admins] Error fetching admins for blueprint ${blueprint.id}: ${(e as Error).message}`,
+      );
+      return [];
+    }
+  }
+
+  /**
+   * Resolves the hypercerts field for a blueprint.
+   * Retrieves the list of hypercerts associated with the blueprint.
+   *
+   * @param blueprint - The blueprint for which to resolve hypercerts
+   * @returns A promise resolving to:
+   *          - Array of hypercerts if found
+   *          - null if:
+   *            - No hypercert IDs are available
+   *            - An error occurs during retrieval
+   *
+   * @example
+   * ```graphql
+   * query {
+   *   blueprints {
+   *     data {
+   *       id
+   *       hypercerts {
+   *         data {
+   *           id
+   *           hypercert_id
+   *           metadata {
+   *             name
+   *             description
+   *           }
+   *         }
+   *       }
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  @FieldResolver()
+  async hypercerts(@Root() blueprint: Blueprint) {
+    if (!blueprint.hypercert_ids?.length) {
+      console.warn(
+        `[BlueprintResolver::hypercerts] No hypercert ids found for blueprint ${blueprint.id}`,
+      );
+      return null;
+    }
+
+    try {
+      return await this.hypercertsService.getHypercerts({
+        where: { hypercert_id: { in: blueprint.hypercert_ids } },
+      });
+    } catch (e) {
+      console.error(
+        `[BlueprintResolver::hypercerts] Error fetching hypercerts for blueprint ${blueprint.id}: ${(e as Error).message}`,
+      );
+      return null;
+    }
+  }
+}
+
+export { BlueprintResolver };