refactor(metadata): document metadata resolver and update metadata-related services

Restructured metadata-related components to improve code organization:
- Removed MetadataResolver from graphql schemas
- Updated HypercertsEntityService to include metadata retrieval methods
- Modified MetadataQueryStrategy to simplify query generation
- Updated import paths in composed resolver and other resolvers
- Removed hypercert-specific filtering from metadata query strategy
- Relocated metadata-related methods to HypercertsService
- Updated test cases to reflect new metadata retrieval approach

Author: bitbeckers

src/graphql/schemas/args/metadataArgs.ts

@@ -2,18 +2,10 @@ import { ArgsType } from "type-graphql";
 import { BaseQueryArgs } from "../../../lib/graphql/BaseQueryArgs.js";
 import { createEntityArgs } from "../../../lib/graphql/createEntityArgs.js";
 import { WhereFieldDefinitions } from "../../../lib/graphql/whereFieldDefinitions.js";
-import { EntityTypeDefs } from "../typeDefs/typeDefs.js";
 
 const { WhereInput: MetadataWhereInput, SortOptions: MetadataSortOptions } =
   createEntityArgs("Metadata", {
     ...WhereFieldDefinitions.Metadata.fields,
-    hypercerts: {
-      type: "id",
-      references: {
-        entity: EntityTypeDefs.Hypercert,
-        fields: WhereFieldDefinitions.Hypercert.fields,
-      },
-    },
   });
 
 @ArgsType()

src/graphql/schemas/resolvers/composed.ts

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

src/graphql/schemas/resolvers/hyperboardResolver.ts

@@ -122,12 +122,12 @@ class HyperboardResolver {
                   where: { hypercert_id: { in: hypercertIds } },
                 })
                 .then((res) => res.data),
-              this.metadataService.getMetadata({
-                where: { hypercerts: { hypercert_id: { in: hypercertIds } } },
+              this.hypercertsService.getHypercertMetadataSets({
+                hypercert_ids: hypercertIds,
               }),
             ]);
 
-          const metadataByUri = _.keyBy(metadata.data, "uri");
+          const metadataByUri = _.keyBy(metadata, "uri");
 
           // get blueprints
           const collectionBlueprints =

src/graphql/schemas/resolvers/metadataResolver.ts

@@ -4,7 +4,6 @@ import { Args, FieldResolver, Query, Resolver, Root } from "type-graphql";
 import { getAddress } from "viem";
 import { HypercertsService } from "../../../services/database/entities/HypercertsEntityService.js";
 import { MarketplaceOrdersService } from "../../../services/database/entities/MarketplaceOrdersEntityService.js";
-import { MetadataService } from "../../../services/database/entities/MetadataEntityService.js";
 import { Database } from "../../../types/supabaseData.js";
 import { addPriceInUsdToOrder } from "../../../utils/addPriceInUSDToOrder.js";
 import { getHypercertTokenId } from "../../../utils/tokenIds.js";
@@ -19,8 +18,6 @@ class OrderResolver {
     private marketplaceOrdersService: MarketplaceOrdersService,
     @inject(HypercertsService)
     private hypercertService: HypercertsService,
-    @inject(MetadataService)
-    private metadataService: MetadataService,
   ) {}
 
   @Query(() => GetOrdersResponse)
@@ -112,12 +109,8 @@ class OrderResolver {
           hypercert_id: { eq: formattedHypercertId },
         },
       }),
-      this.metadataService.getMetadataSingle({
-        where: {
-          hypercerts: {
-            hypercert_id: { eq: formattedHypercertId },
-          },
-        },
+      this.hypercertService.getHypercertMetadata({
+        hypercert_id: formattedHypercertId,
       }),
     ]);
 

src/graphql/schemas/resolvers/orderResolver.ts

@@ -1,6 +1,6 @@
-import { Selectable } from "kysely";
-import { injectable } from "tsyringe";
-import { kyselyCaching } from "../../../client/kysely.js";
+import { Expression, Selectable, SqlBool } from "kysely";
+import { inject, injectable } from "tsyringe";
+import { CachingKyselyService, kyselyCaching } from "../../../client/kysely.js";
 import { GetHypercertsArgs } from "../../../graphql/schemas/args/hypercertsArgs.js";
 import { CachingDatabase } from "../../../types/kyselySupabaseCaching.js";
 import {
@@ -17,7 +17,10 @@ export class HypercertsService {
     GetHypercertsArgs
   >;
 
-  constructor() {
+  constructor(
+    @inject(CachingKyselyService)
+    private cachingKyselyService: CachingKyselyService,
+  ) {
     this.entityService = createEntityService<
       CachingDatabase,
       "claims",
@@ -32,4 +35,56 @@ export class HypercertsService {
   async getHypercert(args: GetHypercertsArgs) {
     return this.entityService.getSingle(args);
   }
+
+  async getHypercertMetadata(args: {
+    claims_id?: string;
+    hypercert_id?: string;
+  }) {
+    const result = this.cachingKyselyService
+      .getConnection()
+      .selectFrom("metadata")
+      .leftJoin("claims", "metadata.uri", "claims.uri")
+      .selectAll("metadata")
+      .where((eb) => {
+        const ors: Expression<SqlBool>[] = [];
+
+        if (args.claims_id) {
+          ors.push(eb("claims.id", "=", args.claims_id));
+        }
+
+        if (args.hypercert_id) {
+          ors.push(eb("claims.hypercert_id", "=", args.hypercert_id));
+        }
+
+        return eb.or(ors);
+      })
+      .executeTakeFirst();
+
+    return result;
+  }
+
+  async getHypercertMetadataSets(args: {
+    claims_ids?: string[];
+    hypercert_ids?: string[];
+  }) {
+    return this.cachingKyselyService
+      .getConnection()
+      .selectFrom("metadata")
+      .leftJoin("claims", "metadata.uri", "claims.uri")
+      .selectAll("metadata")
+      .where((eb) => {
+        const ors: Expression<SqlBool>[] = [];
+
+        if (args.claims_ids) {
+          ors.push(eb("claims.id", "in", args.claims_ids));
+        }
+
+        if (args.hypercert_ids) {
+          ors.push(eb("claims.hypercert_id", "in", args.hypercert_ids));
+        }
+
+        return eb.or(ors);
+      })
+      .execute();
+  }
 }

src/services/database/entities/HypercertsEntityService.ts

@@ -10,6 +10,22 @@ import {
 
 export type MetadataSelect = Selectable<CachingDatabase["metadata"]>;
 
+/**
+ * Service for handling metadata operations in the system.
+ * Provides methods for retrieving metadata records with support for filtering and relationships.
+ *
+ * Metadata represents descriptive information about hypercerts, including:
+ * - Basic information (name, description)
+ * - Work and impact timeframes
+ * - Contributors and rights
+ * - External references (URLs, URIs)
+ * - Custom properties
+ *
+ * This service uses an EntityService for database operations, providing:
+ * - Consistent error handling
+ * - Type safety through Kysely
+ * - Caching support
+ */
 @injectable()
 export class MetadataService {
   private entityService: EntityService<
@@ -25,10 +41,47 @@ export class MetadataService {
     >("metadata", "MetadataEntityService", kyselyCaching);
   }
 
+  /**
+   * Retrieves multiple metadata records based on provided arguments.
+   *
+   * @param args - Query arguments for filtering metadata records
+   * @returns A promise resolving to:
+   *          - data: Array of metadata records matching the criteria
+   *          - count: Total number of matching records
+   *
+   * @example
+   * ```typescript
+   * const result = await metadataService.getMetadata({
+   *   where: {
+   *     hypercerts: {
+   *       id: { eq: "some-hypercert-id" }
+   *     }
+   *   }
+   * });
+   * ```
+   */
   async getMetadata(args: GetMetadataArgs) {
     return this.entityService.getMany(args);
   }
 
+  /**
+   * Retrieves a single metadata record based on provided arguments.
+   * Useful when you expect exactly one matching record.
+   *
+   * @param args - Query arguments for filtering metadata records
+   * @returns A promise resolving to:
+   *          - The matching metadata record if found
+   *          - undefined if no matching record exists
+   *
+   * @example
+   * ```typescript
+   * const metadata = await metadataService.getMetadataSingle({
+   *   where: {
+   *     uri: { eq: "ipfs://..." }
+   *   }
+   * });
+   * ```
+   */
   async getMetadataSingle(args: GetMetadataArgs) {
     return this.entityService.getSingle(args);
   }

src/services/database/entities/MetadataEntityService.ts

@@ -1,6 +1,5 @@
 import { Kysely } from "kysely";
 import { GetMetadataArgs } from "../../../graphql/schemas/args/metadataArgs.js";
-import { isWhereEmpty } from "../../../lib/strategies/isWhereEmpty.js";
 import { CachingDatabase } from "../../../types/kyselySupabaseCaching.js";
 import { MetadataSelect } from "../entities/MetadataEntityService.js";
 import { QueryStrategy } from "./QueryStrategy.js";
@@ -27,8 +26,24 @@ const supportedColumns = [
 type MetadataSelection = Omit<MetadataSelect, "image">;
 
 /**
- * Strategy for querying metadata
- * Handles joins with claims table and selects all columns except for the image column
+ * Strategy for building database queries for metadata records.
+ * Implements query logic for metadata retrieval and counting.
+ *
+ * This strategy handles:
+ * - Basic metadata queries without filtering
+ * - Selective column fetching (excludes large fields like 'image' by default)
+ *
+ * The strategy is designed to work with the metadata table schema:
+ * - id: Unique identifier
+ * - name: Hypercert name
+ * - description: Detailed description
+ * - work_scope, impact_scope: Scope definitions
+ * - timeframe fields: Work and impact time ranges
+ * - uri: IPFS or other content identifier
+ * - properties: Additional custom properties
+ *
+ * Note: This strategy provides direct table access only. Any relationship
+ * filtering (e.g., hypercert relationships) should be handled at the service level.
  */
 export class MetadataQueryStrategy extends QueryStrategy<
   CachingDatabase,
@@ -38,33 +53,39 @@ export class MetadataQueryStrategy extends QueryStrategy<
 > {
   protected readonly tableName = "metadata" as const;
 
-  buildDataQuery(db: Kysely<CachingDatabase>, args?: GetMetadataArgs) {
-    if (!args) {
-      return db.selectFrom(this.tableName).select(supportedColumns);
-    }
-
-    return db
-      .selectFrom(this.tableName)
-      .$if(!isWhereEmpty(args.where?.hypercerts), (qb) =>
-        qb.innerJoin("claims", "claims.uri", "metadata.uri"),
-      )
-      .select(supportedColumns);
+  /**
+   * Builds a query to retrieve metadata records.
+   * Returns all records with supported columns.
+   *
+   * @param db - Kysely database instance
+   * @returns A query builder for retrieving metadata data
+   *
+   * @example
+   * ```typescript
+   * buildDataQuery(db);
+   * // SELECT supported_columns FROM metadata
+   * ```
+   */
+  buildDataQuery(db: Kysely<CachingDatabase>) {
+    return db.selectFrom(this.tableName).select(supportedColumns);
   }
 
-  buildCountQuery(db: Kysely<CachingDatabase>, args?: GetMetadataArgs) {
-    if (!args) {
-      return db.selectFrom(this.tableName).select((eb) => {
-        return eb.fn.countAll().as("count");
-      });
-    }
-
-    return db
-      .selectFrom(this.tableName)
-      .$if(!isWhereEmpty(args.where?.hypercerts), (qb) =>
-        qb.innerJoin("claims", "claims.uri", "metadata.uri"),
-      )
-      .select((eb) => {
-        return eb.fn.countAll().as("count");
-      });
+  /**
+   * Builds a query to count metadata records.
+   * Returns total count of all records.
+   *
+   * @param db - Kysely database instance
+   * @returns A query builder for counting metadata records
+   *
+   * @example
+   * ```typescript
+   * buildCountQuery(db);
+   * // SELECT COUNT(*) as count FROM metadata
+   * ```
+   */
+  buildCountQuery(db: Kysely<CachingDatabase>) {
+    return db.selectFrom(this.tableName).select((eb) => {
+      return eb.fn.countAll().as("count");
+    });
   }
 }

src/services/database/strategies/MetadataQueryStrategy.ts

@@ -290,8 +290,8 @@ class AttestationResolver {
 
       if (!attested_hypercert_id) return null;
 
-      return await this.metadataService.getMetadataSingle({
-        where: { hypercerts: { hypercert_id: { eq: attested_hypercert_id } } },
+      return await this.hypercertService.getHypercertMetadata({
+        hypercert_id: attested_hypercert_id,
       });
     } catch (e) {
       console.error(