Merge pull request #263 from hypercerts-org/feat/refactor_supabase_services

Refactor supabase services

Author: bitbeckers

README.md

@@ -28,10 +28,10 @@ The API implements a fallback to the first available RPC. You can set the RPCs i
 
 ### Supabase
 
-* Install Docker
-* `git submodule init`
-* `git submodule update --remote`
-* `pnpm supabase:start:all`
+- Install Docker
+- `git submodule init`
+- `git submodule update --remote`
+- `pnpm supabase:start:all`
 
 This will spin up 2 Supabase instances in Docker, one for the indexer service (caching) and one for the data service (static data) which are both exposed by the API.
 
@@ -43,21 +43,21 @@ From both instances, you can get their respective keys and add them to the env v
 
 This will run a live production instance by running `swc` to compile the code and `nodemon` to restart the server on changes.
 
-You can then find the API at `localhost:4000/spec` (Swagger instance) and the GraphQL at `localhost:4000/v1/graphql`
+You can then find the API at `localhost:4000/spec` (Swagger instance) and the GraphQL at `localhost:4000/v2/graphql`
 
 ## Deployments
 
 Production: `https://api.hypercerts.org/`
 Staging: `https://staging-api.hypercerts.org`
 
 `/spec` - Swagger instance documenting the API and exposing a playground to experiment with the endpoints
-`/v1/graphql` - GraphQL API to access hypercerts data like claims, fractions, attestations, allow lists
+`/v2/graphql` - GraphQL API to access hypercerts data like claims, fractions, attestations, allow lists
 
 ## Scripts
 
 - `dev`: Starts the development server using `nodemon`, which will automatically restart the server whenever you save a file that the server uses.
 - `build`: Denerates the OpenAPI specification and routes using `tsoa`, and then compiles the TypeScript code into JavaScript using `swc`. The compiled code is output to the `dist` directory.
-- `start`: Starts the application in production mode. 
+- `start`: Starts the application in production mode.
 - `lint`: Runs `eslint` on the codebase to check for linting errors.
 - `test`: Runs tests using `vitest`
 
@@ -86,38 +86,38 @@ The API also provides an upload and validation endpoint for hypercert and allow
 graph TB
     Client[Client Applications]
     API[Hypercerts API :4000]
-    
+
     subgraph "API Endpoints"
         Swagger["/spec\nSwagger Documentation"]
-        GraphQL["/v1/graphql\nGraphQL Endpoint"]
+        GraphQL["/v2/graphql\nGraphQL Endpoint"]
         Upload["Upload & Validation\nEndpoints"]
     end
-    
+
     subgraph "Data Services"
         Static[("Static Data Service\n(Supabase DB)\n- User Data\n- Collections\n- Signed Orders")]
         Indexer[("Indexer Service\n(Supabase DB)\n- On-chain Data\n- IPFS Data")]
     end
-    
+
     subgraph "External Services"
         IPFS[(IPFS\nMetadata Storage)]
         Blockchain[(Blockchain\nSupported Chains)]
         EAS[(EAS\nAttestations)]
     end
-    
+
     Client --> API
     API --> Swagger
     API --> GraphQL
     API --> Upload
-    
+
     GraphQL --> Static
     GraphQL --> Indexer
     Upload --> IPFS
-    
+
     Indexer --> Blockchain
     Indexer --> IPFS
     Indexer --> EAS
-    
+
     class Swagger,GraphQL,Upload apiEndpoint;
     class Static,Indexer database;
     class IPFS,Blockchain,EAS external;
-```
+```

docs/DEVELOPMENT.md

@@ -0,0 +1,176 @@
+# Development Guide: Implementing a New Entity
+
+This guide explains how to implement a new entity in the Hypercerts API, from type definition to resolver implementation.
+
+## Overview
+
+The Hypercerts API uses a modular architecture where each entity follows a consistent pattern:
+
+1. Type Definition
+2. Query Arguments
+3. Entity Service
+4. Resolver
+
+## Step-by-Step Implementation
+
+### 1. Define Entity Types
+
+Create a new file in `src/graphql/schemas/typeDefs/` for your entity types:
+
+```typescript
+// src/graphql/schemas/typeDefs/yourEntityTypeDefs.ts
+import { Field, ObjectType } from "type-graphql";
+import { BaseEntity } from "./baseTypes.js";
+
+@ObjectType()
+export class YourEntity extends BaseEntity {
+  @Field(() => String)
+  name: string;
+
+  @Field(() => String, { nullable: true })
+  description?: string;
+
+  // Add other fields as needed
+}
+
+@ObjectType()
+export class GetYourEntitiesResponse {
+  @Field(() => [YourEntity])
+  data: YourEntity[];
+
+  @Field(() => Int)
+  count: number;
+}
+```
+
+### 2. Define Query Arguments
+
+Create a new file in `src/graphql/schemas/args/` for your query arguments:
+
+```typescript
+// src/graphql/schemas/args/yourEntityArgs.ts
+import { ArgsType } from "type-graphql";
+import { createEntityArgs } from "../../../lib/graphql/createEntityArgs.js";
+import { EntityTypeDefs } from "../typeDefs/typeDefs.js";
+
+// Define your entity fields
+const fields = {
+  name: "string",
+  description: "string",
+  // Add other fields as needed
+} as const;
+
+// Create query arguments
+export const { WhereInput, SortOptions } = createEntityArgs(
+  "YourEntity" as EntityTypeDefs,
+  fields,
+);
+
+@ArgsType()
+export class GetYourEntitiesArgs {
+  first?: number;
+  offset?: number;
+  where?: typeof WhereInput;
+  sortBy?: typeof SortOptions;
+}
+```
+
+### 3. Create Entity Service
+
+Create a new file in `src/services/database/entities/` for your entity service:
+
+```typescript
+// src/services/database/entities/YourEntityService.ts
+import { injectable } from "tsyringe";
+import { createEntityService } from "./EntityServiceFactory.js";
+import { GetYourEntitiesArgs } from "../../../graphql/schemas/args/yourEntityArgs.js";
+import { YourEntity } from "../../../graphql/schemas/typeDefs/yourEntityTypeDefs.js";
+
+@injectable()
+export class YourEntityService {
+  private service = createEntityService<YourEntity, GetYourEntitiesArgs>(
+    "your_entity_table",
+    {
+      // Add any custom query modifiers if needed
+    },
+  );
+
+  async getYourEntities(args: GetYourEntitiesArgs) {
+    return this.service.getMany(args);
+  }
+
+  async getYourEntity(args: GetYourEntitiesArgs) {
+    return this.service.getSingle(args);
+  }
+}
+```
+
+### 4. Implement Resolver
+
+Create a new file in `src/graphql/schemas/resolvers/` for your resolver:
+
+```typescript
+// src/graphql/schemas/resolvers/yourEntityResolver.ts
+import { inject, injectable } from "tsyringe";
+import { Args, Query, Resolver } from "type-graphql";
+import { YourEntityService } from "../../../services/database/entities/YourEntityService.js";
+import { GetYourEntitiesArgs } from "../args/yourEntityArgs.js";
+import {
+  GetYourEntitiesResponse,
+  YourEntity,
+} from "../typeDefs/yourEntityTypeDefs.js";
+
+@injectable()
+@Resolver(() => YourEntity)
+class YourEntityResolver {
+  constructor(
+    @inject(YourEntityService)
+    private yourEntityService: YourEntityService,
+  ) {}
+
+  @Query(() => GetYourEntitiesResponse)
+  async yourEntities(@Args() args: GetYourEntitiesArgs) {
+    return this.yourEntityService.getYourEntities(args);
+  }
+}
+```
+
+### 5. Register the Resolver
+
+Add your resolver to the list of resolvers in `src/graphql/schemas/resolvers/index.ts`:
+
+```typescript
+export * from "./yourEntityResolver.js";
+```
+
+## Best Practices
+
+1. **Type Safety**: Always use TypeScript's type system to ensure type safety across your implementation.
+2. **Consistent Naming**: Follow the existing naming conventions in the codebase.
+3. **Error Handling**: Implement proper error handling in your service and resolver methods.
+4. **Testing**: Write unit tests for your new entity implementation.
+5. **Documentation**: Add JSDoc comments to document your types, methods, and classes.
+
+## Example Implementation
+
+For a complete example, you can look at the implementation of existing entities like `Contract`, `Metadata`, or `AttestationSchema` in the codebase.
+
+## Common Pitfalls
+
+1. **Type Registration**: Ensure all your types are properly registered in the GraphQL schema.
+2. **Dependency Injection**: Use the `@injectable()` and `@inject()` decorators correctly.
+3. **Query Arguments**: Make sure your query arguments match the expected structure.
+4. **Database Schema**: Ensure your database table matches the entity structure.
+
+## Testing Your Implementation
+
+1. Start the development server: `pnpm dev`
+2. Access the GraphQL playground at `http://localhost:4000/v2/graphql`
+3. Test your queries and mutations
+4. Run the test suite: `pnpm test`
+
+## Additional Resources
+
+- [TypeGraphQL Documentation](https://typegraphql.com/)
+- [Kysely Documentation](https://kysely.dev/docs/intro)
+- [Supabase Documentation](https://supabase.com/docs)

eslint.config.js

@@ -9,4 +9,14 @@ export default tseslint.config(
       "@typescript-eslint/no-extraneous-class": "off",
     },
   },
+  {
+    files: ["**/*.test.ts"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_" },
+      ],
+    },
+  },
 );

package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "nodemon",
-    "build": "rimraf dist && tsoa spec-and-routes && swc src --out-dir dist --copy-files",
+    "build": "rimraf dist && tsoa spec-and-routes && tsc && swc src --out-dir dist --copy-files",
     "start": "node -r dotenv/config dist/src/index.js",
     "integration": "concurrently -c \"green,blue\" --names \"CACHE,DATA\"  \"pnpm --dir ./lib/hypercerts-indexer run dev\" \"pnpm run dev\"",
     "supabase:reset:all": "concurrently -c \"blue,green\" --names \"DATA,CACHE\" \"npm run supabase:reset:data\" \"npm run supabase:reset:cache\"",
@@ -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",
@@ -53,6 +54,7 @@
     "@web3-storage/w3up-client": "^16.0.0",
     "axios": "^1.6.5",
     "cors": "^2.8.5",
+    "date-fns": "^4.1.0",
     "ethers": "^6.12.2",
     "express": "^4.19.2",
     "file-type": "^19.6.0",
@@ -99,6 +101,9 @@
     "@sentry/types": "^8.2.1",
     "@swc/cli": "^0.3.12",
     "@swc/core": "^1.4.15",
+    "@swc/helpers": "^0.5.15",
+    "@swc/jest": "^0.2.37",
+    "@types/better-sqlite3": "^7.6.12",
     "@types/body-parser": "^1.19.5",
     "@types/mime-types": "^2.1.4",
     "@types/multer": "^1.4.12",
@@ -107,6 +112,7 @@
     "@types/sinon": "^17.0.2",
     "@types/swagger-ui-express": "^4.1.6",
     "@vitest/coverage-v8": "^2.1.8",
+    "better-sqlite3": "^11.8.1",
     "chai": "^5.0.0",
     "chai-assertions-count": "^1.0.2",
     "concurrently": "^8.2.2",
@@ -119,6 +125,7 @@
     "multiformats": "^13.0.0",
     "node-mocks-http": "^1.14.1",
     "nodemon": "^3.0.3",
+    "pg-mem": "^3.0.5",
     "prettier": "3.3.2",
     "rimraf": "^5.0.5",
     "sinon": "^17.0.1",
@@ -129,6 +136,7 @@
     "typedoc": "^0.26.5",
     "typescript": "5.5.3",
     "typescript-eslint": "^7.7.0",
+    "unplugin-swc": "^1.5.1",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^2.1.8",
     "vitest-mock-extended": "^2.0.2"