feat(attestation): implement comprehensive attestation resolver and services

Introduced a robust implementation for attestation-related functionality:
- Migrated attestation resolver to services directory for better code organization
- Enhanced HypercertPointer schema validation with improved type handling
- Added comprehensive test coverage for AttestationResolver, AttestationEntityService, and AttestationQueryStrategy
- Implemented advanced parsing and validation for attestation data
- Improved hypercert ID generation with flexible input handling
- Added detailed documentation for resolver methods and services

Author: bitbeckers

package.json

@@ -26,6 +26,7 @@
     "commitlint": "commitlint --config commitlintrc.ts --edit"
   },
   "dependencies": {
+    "@faker-js/faker": "^9.6.0",
     "@graphql-tools/merge": "^9.0.19",
     "@graphql-yoga/plugin-response-cache": "^3.13.0",
     "@hypercerts-org/contracts": "2.0.0-alpha.12",

pnpm-lock.yaml

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

src/graphql/schemas/resolvers/attestationResolver.ts

@@ -11,6 +11,18 @@ import {
 
 export type AttestationSelect = Selectable<CachingDatabase["attestations"]>;
 
+/**
+ * Service for managing attestation entities in the database.
+ * Handles CRUD operations for attestations, including data parsing and validation.
+ *
+ * This service:
+ * - Provides methods for retrieving single or multiple attestations
+ * - Handles parsing of attestation data, particularly bigint conversions
+ * - Uses an EntityService for database operations
+ * - Supports filtering by attestation fields and related entities
+ *
+ * @injectable Marks the class as injectable for dependency injection
+ */
 @injectable()
 export class AttestationService {
   private entityService: EntityService<
@@ -26,6 +38,29 @@ export class AttestationService {
     >("attestations", "AttestationEntityService", kyselyCaching);
   }
 
+  /**
+   * Retrieves multiple attestations based on provided arguments.
+   * Handles filtering and parsing of attestation data.
+   *
+   * @param args - Query arguments for filtering attestations
+   * @returns Promise resolving to:
+   *          - data: Array of attestations with parsed data
+   *          - count: Total number of matching attestations
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * // Get attestations by ID
+   * const result = await attestationService.getAttestations({
+   *   where: { id: { eq: "123" } }
+   * });
+   *
+   * // Get attestations by related schema
+   * const result = await attestationService.getAttestations({
+   *   where: { eas_schema: { id: { eq: "schema-id" } } }
+   * });
+   * ```
+   */
   async getAttestations(args: GetAttestationsArgs) {
     const respone = await this.entityService.getMany(args);
     return {
@@ -37,15 +72,42 @@ export class AttestationService {
     };
   }
 
+  /**
+   * Retrieves a single attestation based on provided arguments.
+   *
+   * @param args - Query arguments for filtering attestations
+   * @returns Promise resolving to:
+   *          - The found attestation if it exists
+   *          - undefined if no attestation matches the query
+   * @throws {Error} If the database query fails
+   *
+   * @example
+   * ```typescript
+   * const attestation = await attestationService.getAttestation({
+   *   where: { id: { eq: "123" } }
+   * });
+   * ```
+   */
   async getAttestation(args: GetAttestationsArgs) {
-    const attestation = await this.entityService.getSingle(args);
-    if (!attestation) {
-      throw new Error("Attestation not found");
-    }
-    return attestation;
+    return await this.entityService.getSingle(args);
   }
 
-  // Parses the attestation.data field to ensure bigints are converted to strings
+  /**
+   * Parses attestation data, converting bigint values to strings.
+   * This is necessary because GraphQL cannot handle bigint values directly.
+   *
+   * @param data - Raw attestation data from the database
+   * @returns Parsed data with bigint values converted to strings
+   *
+   * @example
+   * ```typescript
+   * const parsed = attestationService.parseAttestation({
+   *   token_id: 123456789n,
+   *   other_field: "value"
+   * });
+   * // parsed = { token_id: "123456789", other_field: "value" }
+   * ```
+   */
   parseAttestation(data: Json) {
     // TODO cleaner handling of bigints in created attestations
     if (

src/graphql/schemas/resolvers/composed.ts

@@ -5,8 +5,13 @@ import { QueryStrategy } from "./QueryStrategy.js";
 import { isWhereEmpty } from "../../../lib/strategies/isWhereEmpty.js";
 
 /**
- * Strategy for querying attestations
- * Handles joins with claims, metadata, and supported schemas tables
+ * Strategy for building database queries for attestations.
+ * Implements complex query logic for attestation retrieval, including:
+ * - Joins with related tables (claims, supported_schemas)
+ * - Filtering based on related entities
+ * - Count queries for total matching records
+ *
+ * This strategy extends the base QueryStrategy to provide attestation-specific query building.
  */
 export class AttestationsQueryStrategy extends QueryStrategy<
   CachingDatabase,
@@ -15,6 +20,30 @@ export class AttestationsQueryStrategy extends QueryStrategy<
 > {
   protected readonly tableName = "attestations" as const;
 
+  /**
+   * Builds a query to retrieve attestation data with optional filtering.
+   * Handles complex joins and relationships with other tables.
+   *
+   * @param db - Kysely database instance
+   * @param args - Optional query arguments for filtering
+   * @returns A query builder for retrieving attestation data
+   *
+   * Key features:
+   * - Joins with supported_schemas when eas_schema filter is present
+   * - Joins with claims when hypercert filter is present
+   * - Returns all columns from the attestations table
+   *
+   * @example
+   * ```typescript
+   * // Basic query without filters
+   * buildDataQuery(db);
+   * // SELECT * FROM attestations
+   *
+   * // Query with schema filter
+   * buildDataQuery(db, { where: { eas_schema: { id: { eq: 'schema-id' } } } });
+   * // SELECT * FROM attestations WHERE EXISTS (SELECT * FROM supported_schemas ...)
+   * ```
+   */
   buildDataQuery(db: Kysely<CachingDatabase>, args?: GetAttestationsArgs) {
     if (!args) {
       return db.selectFrom(this.tableName).selectAll();
@@ -46,6 +75,19 @@ export class AttestationsQueryStrategy extends QueryStrategy<
       .selectAll();
   }
 
+  /**
+   * Builds a query to count attestations with optional filtering.
+   * Uses the same filtering logic as buildDataQuery but returns a count.
+   *
+   * @param db - Kysely database instance
+   * @param args - Optional query arguments for filtering
+   * @returns A query builder for counting attestations
+   *
+   * Key features:
+   * - Applies the same joins and filters as buildDataQuery
+   * - Returns a count of matching attestations
+   * - Optimized for counting by selecting only the count
+   */
   buildCountQuery(db: Kysely<CachingDatabase>, args?: GetAttestationsArgs) {
     if (!args) {
       return db.selectFrom(this.tableName).select((eb) => {