feat(attestationschema): restructure attestation schema resolver and related components

Refactored the attestation schema resolver and related components to improve code organization and maintainability:
- Moved AttestationSchemaResolver from graphql to services directory
- Updated import paths in composed resolver and type definitions
- Enhanced type definitions with comprehensive documentation
- Added detailed JSDoc comments for classes and methods
- Introduced comprehensive test coverage for AttestationSchemaService, SupportedSchemasQueryStrategy, and AttestationSchemaResolver
- Improved type safety and code clarity across related files

Author: bitbeckers

src/graphql/schemas/resolvers/attestationSchemaResolver.ts

@@ -3,7 +3,7 @@ import { MetadataResolver } from "./metadataResolver.js";
 import { ContractResolver } from "./contractResolver.js";
 import { FractionResolver } from "./fractionResolver.js";
 import { AttestationResolver } from "../../../services/graphql/resolvers/attestationResolver.js";
-import { AttestationSchemaResolver } from "./attestationSchemaResolver.js";
+import { AttestationSchemaResolver } from "../../../services/graphql/resolvers/attestationSchemaResolver.js";
 import { OrderResolver } from "./orderResolver.js";
 import { HyperboardResolver } from "./hyperboardResolver.js";
 import { AllowlistRecordResolver } from "../../../services/graphql/resolvers/allowlistRecordResolver.js";

src/graphql/schemas/resolvers/composed.ts

@@ -3,17 +3,39 @@ import { DataResponse } from "../../../lib/graphql/DataResponse.js";
 import { GetAttestationsResponse } from "./attestationTypeDefs.js";
 import { AttestationSchemaBaseType } from "./baseTypes/attestationSchemaBaseType.js";
 
+/**
+ * GraphQL object type representing an EAS (Ethereum Attestation Service) schema.
+ * Extends the base type with additional fields for related attestations.
+ *
+ * This type provides:
+ * - All fields from AttestationSchemaBaseType (id, chain_id, schema, resolver, revocable, uid)
+ * - Additional field for accessing related attestations
+ *
+ * @extends {AttestationSchemaBaseType}
+ */
 @ObjectType({
   description: "Supported EAS attestation schemas and their related records",
 })
 export class AttestationSchema extends AttestationSchemaBaseType {
+  /**
+   * Collection of attestations that use this schema.
+   * Includes both the attestation records and a total count.
+   */
   @Field(() => GetAttestationsResponse, {
     description: "List of attestations related to the attestation schema",
   })
   attestations?: GetAttestationsResponse | null;
 }
 
+/**
+ * GraphQL response type for attestation schema queries.
+ * Wraps an array of AttestationSchema objects with pagination information.
+ *
+ * This type provides:
+ * - data: Array of attestation schemas
+ * - count: Total number of schemas matching the query
+ */
 @ObjectType()
-export default class GetAttestationsSchemaResponse extends DataResponse(
+export class GetAttestationsSchemaResponse extends DataResponse(
   AttestationSchema,
 ) {}

src/graphql/schemas/typeDefs/attestationSchemaTypeDefs.ts

@@ -2,27 +2,63 @@ import { Field, ID, ObjectType } from "type-graphql";
 import { EthBigInt } from "../../../scalars/ethBigInt.js";
 import { BasicTypeDef } from "./basicTypeDef.js";
 
+/**
+ * Base GraphQL object type for EAS (Ethereum Attestation Service) schemas.
+ * Provides the core fields that define an attestation schema.
+ *
+ * This type provides:
+ * - Basic identification fields (id from BasicTypeDef)
+ * - Schema-specific fields (chain_id, uid, schema, resolver, revocable)
+ *
+ * Used as a base class for more specific schema types that may add additional fields.
+ *
+ * @extends {BasicTypeDef}
+ */
 @ObjectType({
   description: "Supported EAS attestation schemas and their related records",
 })
 class AttestationSchemaBaseType extends BasicTypeDef {
+  /**
+   * Chain ID where this schema is supported.
+   * Can be represented as a bigint, number, or string.
+   */
   @Field(() => EthBigInt, {
     description:
       "Chain ID of the chains where the attestation schema is supported",
   })
   chain_id?: bigint | number | string;
+
+  /**
+   * Unique identifier for the schema on EAS.
+   * This is different from the database id field.
+   */
   @Field(() => ID, {
     description: "Unique identifier for the attestation schema",
   })
   uid?: string;
+
+  /**
+   * Address of the resolver contract for this schema.
+   * The resolver contract handles the validation and processing of attestations.
+   */
   @Field({
     description: "Address of the resolver contract for the attestation schema",
   })
   resolver?: string;
+
+  /**
+   * Whether attestations using this schema can be revoked.
+   * If true, attesters can revoke their attestations after creation.
+   */
   @Field({
     description: "Whether the attestation schema is revocable",
   })
   revocable?: boolean;
+
+  /**
+   * String representation of the schema definition.
+   * Defines the structure and types of data that can be attested.
+   */
   @Field({
     description: "String representation of the attestation schema",
   })

src/graphql/schemas/typeDefs/baseTypes/attestationSchemaBaseType.ts

@@ -8,17 +8,32 @@ import {
   type EntityService,
 } from "./EntityServiceFactory.js";
 
+/** Type representing a selected attestation schema record from the database */
 export type AttestationSchemaSelect = Selectable<
   CachingDatabase["supported_schemas"]
 >;
 
+/**
+ * Service class for managing attestation schema entities in the database.
+ * Handles CRUD operations for EAS (Ethereum Attestation Service) schemas.
+ *
+ * This service provides methods to:
+ * - Retrieve multiple attestation schemas with filtering and pagination
+ * - Retrieve a single attestation schema by its criteria
+ *
+ * @injectable Marks the class as injectable for dependency injection with tsyringe
+ */
 @injectable()
 export class AttestationSchemaService {
   private entityService: EntityService<
     CachingDatabase["supported_schemas"],
     GetAttestationSchemasArgs
   >;
 
+  /**
+   * Creates a new instance of AttestationSchemaService.
+   * Initializes the underlying entity service for database operations.
+   */
   constructor() {
     this.entityService = createEntityService<
       CachingDatabase,
@@ -27,10 +42,47 @@ export class AttestationSchemaService {
     >("supported_schemas", "AttestationSchemaEntityService", kyselyCaching);
   }
 
+  /**
+   * Retrieves multiple attestation schemas based on provided arguments.
+   *
+   * @param args - Query arguments for filtering and pagination
+   * @returns A promise that resolves to an object containing:
+   *          - data: Array of attestation schemas matching the query
+   *          - count: Total number of matching schemas
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * const result = await service.getAttestationSchemas({
+   *   where: { id: { eq: "schema-id" } }
+   * });
+   * console.log(result.data); // Array of matching schemas
+   * console.log(result.count); // Total count
+   * ```
+   */
   async getAttestationSchemas(args: GetAttestationSchemasArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single attestation schema based on provided arguments.
+   *
+   * @param args - Query arguments for filtering
+   * @returns A promise that resolves to:
+   *          - The matching attestation schema if found
+   *          - undefined if no schema matches the criteria
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * const schema = await service.getAttestationSchema({
+   *   where: { id: { eq: "schema-id" } }
+   * });
+   * if (schema) {
+   *   console.log("Found schema:", schema);
+   * }
+   * ```
+   */
   async getAttestationSchema(args: GetAttestationSchemasArgs) {
     return this.entityService.getSingle(args);
   }

src/services/database/entities/AttestationSchemaEntityService.ts

@@ -3,19 +3,52 @@ import { CachingDatabase } from "../../../types/kyselySupabaseCaching.js";
 import { QueryStrategy } from "./QueryStrategy.js";
 
 /**
- * Strategy for querying supported schemas
- * Handles joins with attestations and eas_schema tables
+ * Strategy for querying supported EAS (Ethereum Attestation Service) schemas.
+ * Provides a simple query interface for the supported_schemas table.
+ *
+ * This strategy extends the base QueryStrategy to provide schema-specific query building.
+ * It handles basic data retrieval and counting operations without complex joins or filtering.
+ *
+ * @template CachingDatabase - The database type containing the supported_schemas table
  */
 export class SupportedSchemasQueryStrategy extends QueryStrategy<
   CachingDatabase,
   "supported_schemas"
 > {
   protected readonly tableName = "supported_schemas" as const;
 
+  /**
+   * Builds a query to retrieve supported schema data.
+   * Returns a simple SELECT query that retrieves all columns from the supported_schemas table.
+   *
+   * @param db - Kysely database instance
+   * @returns A query builder for retrieving supported schema data
+   *
+   * @example
+   * ```typescript
+   * // Basic query to select all supported schemas
+   * buildDataQuery(db);
+   * // SELECT * FROM supported_schemas
+   * ```
+   */
   buildDataQuery(db: Kysely<CachingDatabase>) {
     return db.selectFrom(this.tableName).selectAll();
   }
 
+  /**
+   * Builds a query to count supported schemas.
+   * Returns a simple COUNT query for the supported_schemas table.
+   *
+   * @param db - Kysely database instance
+   * @returns A query builder for counting supported schemas
+   *
+   * @example
+   * ```typescript
+   * // Count all supported schemas
+   * buildCountQuery(db);
+   * // SELECT COUNT(*) as count FROM supported_schemas
+   * ```
+   */
   buildCountQuery(db: Kysely<CachingDatabase>) {
     return db.selectFrom(this.tableName).select((eb) => {
       return eb.fn.countAll().as("count");