@tinkerstack/graphql-annotation 0.0.3 → 0.0.6

package/README.md

@@ -1,138 +1,138 @@
-<center>
-<img src="https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Fcdn.icon-icons.com%2Ficons2%2F2699%2FPNG%2F512%2Fgraphql_logo_icon_171045.png&f=1&nofb=1&ipt=e40678a4804af7f493102aa8bcc97bacbfdfee9dac86e14c75ab7afb00a237b5" height="150px">
-  <h1>GraphQL Annotation</h1>
-  <p>A set of tools for extending GraphQL stitching capabilities through annotations</p>
-</center>
-
----
-
-## Who is this intended for?
-  
-This library is designed to solve a specific scenario in mind:
-
-1. There's a primary `Gateway` and separately developed `SubGateway`s, both of each uses `graphql`.
-2. Front-end or external non-backend consumers interact with `SubGateway` resolvers stitched through `Gateway`
-3. Resolvers at `SubGateway` requires additional resource/guard/processing from `Gateway`.
-4. `SubGateway` team does not have access to `Gateway` nor can they run a local instance.
-5. `SubGateway` team **does not require** `Gateway` features during development, only during deployment.
-
-Available solutions often utilize `Remote-Produce-Calls (RPCs)` libraries to let `SubGateway` invoke `Gateway` methods through HTTP transport, which unfortunately fails point 4 and 5, of which this library answers through `annotations`.
-
-**However**, if `SubGateway` needs to make additional calls to `Gateway` for mutation or other purposes, then this library should only be considered as a mean of optimization and you are better off just running an `RPC` library at the small of performance and back-and-forth.
-
-**TL;DR:** Only use this library if you HAVE TO achieve complete isolation between `Gateway` and `SubGateway` development cycle.
-
-## Usage
-
-You can find examples in `src/examples` for more details. Note that `graphql-annotation` should be replaced with workspace name in internal projects.
-
-```ts
-// gateway
-
-import {
-  GraphQLAnnotationModule, 
-  GraphQLAnnotationSchemaLoader
-} from "graphql-annotation";
-
-@Module({
-  imports: [
-    GraphQLAnnotationModule.forRoot(),
-    GraphQLModule.forRootAsync<ApolloDriverConfig>({
-      driver: ApolloDriver,
-      useFactory: (loader: GraphQLAnnotatedSchemaLoader) => ({
-        async transformSchema(schema) {
-          return stitchSchemas({
-            subschemas: [
-              { schema },
-              {
-                // Load external annotated schemas
-                schema: await loader.load({
-                  example: "http://localhost:3031/graphql",
-                }),
-              },
-            ],
-          });
-        },
-      }),
-      inject: [GraphQLAnnotatedSchemaLoader],
-    }),
-  ],
-})
-export class GatewayAppModule {}
-
-
-// It is recommended that you wrap the `Annotate` decorator in a function and in the gateway to ensure `gateway` team knows that's implemented. `sub-gateway` team could reference this through github submodule.
-
-export type RoleGroups = ("user" | "admin" | "super-admin")[];
-export const ProtectedResolver = (roles: RoleGroups) =>
-  Annotate("protected", { data: { roles } });
-
-export const InjectableArg = (argName: string, resourceType: string) =>
-  Annotate("resource", { data: { resourceType }, parameter: argName });
-
-@Injectable()
-export class ExampleGuard implements CanActivate {
-  canActivate(context: ExecutionContext) {
-    // Do something with your execution context
-    return true;
-  }
-}
-
-@Resolver()
-export class SubgatewayResolver {
-  // NOTE: You can use normal nest and graphql decorators.
-  // Just note that `ResolveAnnotation` must be in a `Resolver`
-
-  @UseGuards(ExampleGuard)
-  @ResolveAnnotation("protected") 
-  verifyUser(context: ExecutionContext, next: () => void) {}
-
-  // If empty would use function name as annotation tag
-  @ResolveAnnotation()
-  resource(
-    // WARN: this is NOT validated like in graphql though
-    @Args("resourceType") resourceType: string,
-    @Context() context: GraphQLExecutionContext,
-  ) {
-    return "this-is-gateway-provided-username";
-  }
-}
-
-// ---------------------------------------------
-
-// sub-gateway
-@Module({
-  imports: [
-    GraphQLModule.forRoot<ApolloDriverConfig>({
-      /* Put your graphql config here*/
-    }),
-    GraphQLAnnotationModule.forRoot({
-      serveAnnotations: true,
-      // Name is only for identification at the time of writing, which does not support annotation filtering.
-      serveConfig: { name: "<subgateway-a>" },
-    }),
-    ExampleProducerModule,
-  ],
-})
-export class SubGatewayAppModule {}
-
-@Resolver()
-export class ExampleProducerResolver {
-  @Query(() => [String])
-  @ProtectedResolver(["admin"])
-  testProtectedQuery() {
-    return ["This resolver should only be available to if guard check passed"];
-  }
-  @Query(() => [String])
-  testQueryWithParam(
-    @InjectableArg("username", "session:username")
-    username: string
-  ) {
-    return [`Received params: ${username}`];
-  }
-  @Query(() => [String])
-  testPublicQuery() {
-    return ["This resolver should be available to everyone"];
-  }
-}
-```
+<center>
+<img src="https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Fcdn.icon-icons.com%2Ficons2%2F2699%2FPNG%2F512%2Fgraphql_logo_icon_171045.png&f=1&nofb=1&ipt=e40678a4804af7f493102aa8bcc97bacbfdfee9dac86e14c75ab7afb00a237b5" height="150px">
+  <h1>GraphQL Annotation</h1>
+  <p>A set of tools for extending GraphQL stitching capabilities through annotations</p>
+</center>
+
+---
+
+## Who is this intended for?
+  
+This library is designed to solve a specific scenario in mind:
+
+1. There's a primary `Gateway` and separately developed `SubGateway`s, both of each uses `graphql`.
+2. Front-end or external non-backend consumers interact with `SubGateway` resolvers stitched through `Gateway`
+3. Resolvers at `SubGateway` requires additional resource/guard/processing from `Gateway`.
+4. `SubGateway` team does not have access to `Gateway` nor can they run a local instance.
+5. `SubGateway` team **does not require** `Gateway` features during development, only during deployment.
+
+Available solutions often utilize `Remote-Produce-Calls (RPCs)` libraries to let `SubGateway` invoke `Gateway` methods through HTTP transport, which unfortunately fails point 4 and 5, of which this library answers through `annotations`.
+
+**However**, if `SubGateway` needs to make additional calls to `Gateway` for mutation or other purposes, then this library should only be considered as a mean of optimization and you are better off just running an `RPC` library at the small of performance and back-and-forth.
+
+**TL;DR:** Only use this library if you HAVE TO achieve complete isolation between `Gateway` and `SubGateway` development cycle.
+
+## Usage
+
+You can find examples in `src/examples` for more details. Note that `graphql-annotation` should be replaced with workspace name in internal projects.
+
+```ts
+// gateway
+
+import {
+  GraphQLAnnotationModule, 
+  GraphQLAnnotationSchemaLoader
+} from "graphql-annotation";
+
+@Module({
+  imports: [
+    GraphQLAnnotationModule.forRoot(),
+    GraphQLModule.forRootAsync<ApolloDriverConfig>({
+      driver: ApolloDriver,
+      useFactory: (loader: GraphQLAnnotatedSchemaLoader) => ({
+        async transformSchema(schema) {
+          return stitchSchemas({
+            subschemas: [
+              { schema },
+              {
+                // Load external annotated schemas
+                schema: await loader.load({
+                  example: "http://localhost:3031/graphql",
+                }),
+              },
+            ],
+          });
+        },
+      }),
+      inject: [GraphQLAnnotatedSchemaLoader],
+    }),
+  ],
+})
+export class GatewayAppModule {}
+
+
+// It is recommended that you wrap the `Annotate` decorator in a function and in the gateway to ensure `gateway` team knows that's implemented. `sub-gateway` team could reference this through github submodule.
+
+export type RoleGroups = ("user" | "admin" | "super-admin")[];
+export const ProtectedResolver = (roles: RoleGroups) =>
+  Annotate("protected", { data: { roles } });
+
+export const InjectableArg = (argName: string, resourceType: string) =>
+  Annotate("resource", { data: { resourceType }, parameter: argName });
+
+@Injectable()
+export class ExampleGuard implements CanActivate {
+  canActivate(context: ExecutionContext) {
+    // Do something with your execution context
+    return true;
+  }
+}
+
+@Resolver()
+export class SubgatewayResolver {
+  // NOTE: You can use normal nest and graphql decorators.
+  // Just note that `ResolveAnnotation` must be in a `Resolver`
+
+  @UseGuards(ExampleGuard)
+  @ResolveAnnotation("protected") 
+  verifyUser(context: ExecutionContext, next: () => void) {}
+
+  // If empty would use function name as annotation tag
+  @ResolveAnnotation()
+  resource(
+    // WARN: this is NOT validated like in graphql though
+    @Args("resourceType") resourceType: string,
+    @Context() context: GraphQLExecutionContext,
+  ) {
+    return "this-is-gateway-provided-username";
+  }
+}
+
+// ---------------------------------------------
+
+// sub-gateway
+@Module({
+  imports: [
+    GraphQLModule.forRoot<ApolloDriverConfig>({
+      /* Put your graphql config here*/
+    }),
+    GraphQLAnnotationModule.forRoot({
+      serveAnnotations: true,
+      // Name is only for identification at the time of writing, which does not support annotation filtering.
+      serveConfig: { name: "<subgateway-a>" },
+    }),
+    ExampleProducerModule,
+  ],
+})
+export class SubGatewayAppModule {}
+
+@Resolver()
+export class ExampleProducerResolver {
+  @Query(() => [String])
+  @ProtectedResolver(["admin"])
+  testProtectedQuery() {
+    return ["This resolver should only be available to if guard check passed"];
+  }
+  @Query(() => [String])
+  testQueryWithParam(
+    @InjectableArg("username", "session:username")
+    username: string
+  ) {
+    return [`Received params: ${username}`];
+  }
+  @Query(() => [String])
+  testPublicQuery() {
+    return ["This resolver should be available to everyone"];
+  }
+}
+```

package/dist/index.d.mts

@@ -58,7 +58,9 @@ declare class GraphQLAnnotatedSchemaLoader {
     private readonly externalContextCreator;
     private _logger;
     constructor(resolverDiscoveryService: ResolverDiscoveryService, metadataScanner: MetadataScanner, externalContextCreator: ExternalContextCreator);
-    load(sources: AnnotationSchemaSources): Promise<GraphQLSchema>;
+    load(sources: AnnotationSchemaSources, opts?: {
+        ignoreMissingSources?: boolean;
+    }): Promise<GraphQLSchema>;
     private discoverAnnotationResolvers;
     private batchLoadSources;
     private loadAnnotations;

package/dist/index.d.ts

@@ -58,7 +58,9 @@ declare class GraphQLAnnotatedSchemaLoader {
     private readonly externalContextCreator;
     private _logger;
     constructor(resolverDiscoveryService: ResolverDiscoveryService, metadataScanner: MetadataScanner, externalContextCreator: ExternalContextCreator);
-    load(sources: AnnotationSchemaSources): Promise<GraphQLSchema>;
+    load(sources: AnnotationSchemaSources, opts?: {
+        ignoreMissingSources?: boolean;
+    }): Promise<GraphQLSchema>;
     private discoverAnnotationResolvers;
     private batchLoadSources;
     private loadAnnotations;

package/dist/index.js

@@ -328,8 +328,10 @@ var GraphQLAnnotatedSchemaLoader = class {
     this.metadataScanner = metadataScanner;
     this.externalContextCreator = externalContextCreator;
   }
-  async load(sources) {
-    const loadedSources = await this.batchLoadSources(sources);
+  async load(sources, opts) {
+    const loadedSources = await this.batchLoadSources(sources, {
+      ignoreMissingSources: opts?.ignoreMissingSources ?? false
+    });
     const schema = (0, import_stitch.stitchSchemas)({
       subschemas: loadedSources.map((s) => s.subschema)
     });
@@ -349,7 +351,7 @@ var GraphQLAnnotatedSchemaLoader = class {
     }
     return annotationResolvers;
   }
-  async batchLoadSources(sources) {
+  async batchLoadSources(sources, opts) {
     const pending = Object.entries(sources).map(async ([name, url]) => {
       const loadId = `${name}@${url}`;
       try {
@@ -371,7 +373,11 @@ var GraphQLAnnotatedSchemaLoader = class {
       }
     });
     const [loaded, failed] = split(await Promise.allSettled(pending), (q) => q.status === "fulfilled");
-    if (failed.length > 0) throw new Error(`Failed to load ${failed.length} schema(s) from sources.`);
+    const shouldThrow = !(opts?.ignoreMissingSources ?? false);
+    if (failed.length > 0) {
+      if (shouldThrow) throw new Error(`Failed to load ${failed.length} schema(s) from sources.`);
+      else this._logger.warn(`Failed to load ${failed.length}, ignoring.`);
+    }
     return loaded.map((l) => l.value);
   }
   async loadAnnotations(url) {

package/dist/index.mjs

@@ -299,8 +299,10 @@ var GraphQLAnnotatedSchemaLoader = class {
     this.metadataScanner = metadataScanner;
     this.externalContextCreator = externalContextCreator;
   }
-  async load(sources) {
-    const loadedSources = await this.batchLoadSources(sources);
+  async load(sources, opts) {
+    const loadedSources = await this.batchLoadSources(sources, {
+      ignoreMissingSources: opts?.ignoreMissingSources ?? false
+    });
     const schema = stitchSchemas({
       subschemas: loadedSources.map((s) => s.subschema)
     });
@@ -320,7 +322,7 @@ var GraphQLAnnotatedSchemaLoader = class {
     }
     return annotationResolvers;
   }
-  async batchLoadSources(sources) {
+  async batchLoadSources(sources, opts) {
     const pending = Object.entries(sources).map(async ([name, url]) => {
       const loadId = `${name}@${url}`;
       try {
@@ -342,7 +344,11 @@ var GraphQLAnnotatedSchemaLoader = class {
       }
     });
     const [loaded, failed] = split(await Promise.allSettled(pending), (q) => q.status === "fulfilled");
-    if (failed.length > 0) throw new Error(`Failed to load ${failed.length} schema(s) from sources.`);
+    const shouldThrow = !(opts?.ignoreMissingSources ?? false);
+    if (failed.length > 0) {
+      if (shouldThrow) throw new Error(`Failed to load ${failed.length} schema(s) from sources.`);
+      else this._logger.warn(`Failed to load ${failed.length}, ignoring.`);
+    }
     return loaded.map((l) => l.value);
   }
   async loadAnnotations(url) {

package/nest-cli.json

@@ -1,9 +1,9 @@
-{
-  "$schema": "https://json.schemastore.org/nest-cli",
-  "collection": "@nestjs/schematics",
-  "sourceRoot": "src",
-  "entryFile": "example/main",
-  "compilerOptions": {
-    "tsConfigPath": "tsconfig.json"
-  }
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "entryFile": "example/main",
+  "compilerOptions": {
+    "tsConfigPath": "tsconfig.json"
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinkerstack/graphql-annotation",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "Better type-safe-able graphql directives",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -14,11 +14,15 @@
     "@graphql-tools/stitch": "^10.1.8",
     "@graphql-tools/utils": "^11.0.0",
     "@graphql-tools/wrap": "^11.1.4",
-    "class-transformer": "^0.5.1",
     "graphql-request": "^7.2.0"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plasteek/tinkerstack.git"
   },
   "peerDependencies": {
     "@nestjs/common": "^10 || ^11",
@@ -40,6 +44,7 @@
     "@nestjs/mapped-types": "^2.1.0",
     "@nestjs/platform-fastify": "^11.1.11",
     "@swc/core": "^1.15.11",
+    "class-transformer": "^0.5.1",
     "class-validator": "^0.14.2",
     "concurrently": "^9.2.1",
     "eslint": "^9.37.0",

package/src/example/consumer/consumer.app.ts

@@ -1,38 +1,38 @@
-import { Module } from "@nestjs/common";
-import { GraphQLModule } from "@nestjs/graphql";
-
-import { ApolloDriver, ApolloDriverConfig } from "@nestjs/apollo";
-import { ExampleConsumerModule } from "./consumer.example";
-import { GraphQLAnnotatedSchemaLoader } from "@/modules/core/annotation.loader";
-import { GraphQLAnnotationModule } from "@/modules/core/annotation.module";
-import { stitchSchemas } from "@graphql-tools/stitch";
-
-@Module({
-  imports: [
-    ExampleConsumerModule,
-    GraphQLAnnotationModule.forRoot(),
-    GraphQLModule.forRootAsync<ApolloDriverConfig>({
-      driver: ApolloDriver,
-      useFactory: (loader: GraphQLAnnotatedSchemaLoader) => ({
-        graphiql: true,
-        playground: true,
-        autoSchemaFile: "./src/example/consumer/consumer.schema.gql",
-        async transformSchema(schema) {
-          return stitchSchemas({
-            subschemas: [
-              { schema },
-              {
-                // Load external annotated schemas
-                schema: await loader.load({
-                  example: "http://localhost:3031/graphql",
-                }),
-              },
-            ],
-          });
-        },
-      }),
-      inject: [GraphQLAnnotatedSchemaLoader],
-    }),
-  ],
-})
-export class ExampleConsumerApp {}
+import { Module } from "@nestjs/common";
+import { GraphQLModule } from "@nestjs/graphql";
+
+import { ApolloDriver, ApolloDriverConfig } from "@nestjs/apollo";
+import { ExampleConsumerModule } from "./consumer.example";
+import { GraphQLAnnotatedSchemaLoader } from "@/modules/core/annotation.loader";
+import { GraphQLAnnotationModule } from "@/modules/core/annotation.module";
+import { stitchSchemas } from "@graphql-tools/stitch";
+
+@Module({
+  imports: [
+    ExampleConsumerModule,
+    GraphQLAnnotationModule.forRoot(),
+    GraphQLModule.forRootAsync<ApolloDriverConfig>({
+      driver: ApolloDriver,
+      useFactory: (loader: GraphQLAnnotatedSchemaLoader) => ({
+        graphiql: true,
+        playground: true,
+        autoSchemaFile: "./src/example/consumer/consumer.schema.gql",
+        async transformSchema(schema) {
+          return stitchSchemas({
+            subschemas: [
+              { schema },
+              {
+                // Load external annotated schemas
+                schema: await loader.load({
+                  example: "http://localhost:3031/graphql",
+                }),
+              },
+            ],
+          });
+        },
+      }),
+      inject: [GraphQLAnnotatedSchemaLoader],
+    }),
+  ],
+})
+export class ExampleConsumerApp {}

package/src/example/consumer/consumer.example.ts

@@ -1,57 +1,57 @@
-import { Annotate, ResolveAnnotation } from "@/modules/core";
-import {
-  CanActivate,
-  ExecutionContext,
-  Injectable,
-  Module,
-  UseGuards,
-} from "@nestjs/common";
-import {
-  Args,
-  Context,
-  GraphQLExecutionContext,
-  Query,
-  Resolver,
-} from "@nestjs/graphql";
-
-// Export for external
-export type RoleGroups = ("user" | "admin" | "super-admin")[];
-export const ProtectedResolver = (roles: RoleGroups) =>
-  Annotate("protected", { data: { roles } });
-export const InjectableArg = (argName: string, resourceType: string) =>
-  Annotate("resource", { data: { resourceType }, parameter: argName });
-
-@Injectable()
-export class ExampleGuard implements CanActivate {
-  canActivate(context: ExecutionContext) {
-    // Do something with your execution context
-    return true;
-  }
-}
-
-@Resolver()
-export class ExampleConsumerResolver {
-  @Query(() => [String])
-  exampleOut() {
-    return ["this is from consumer"];
-  }
-
-  @UseGuards(ExampleGuard)
-  @ResolveAnnotation("protected")
-  verifyUser(context: ExecutionContext, next: () => void) {
-    console.log("I AM HERE");
-  }
-
-  // Should use the name
-  @ResolveAnnotation("resource")
-  resolveResource(
-    @Args("resourceType") resourceType: string,
-    @Context() context: GraphQLExecutionContext,
-  ) {
-    console.log(resourceType);
-    return "this-is-gateway-provided-username";
-  }
-}
-
-@Module({ providers: [ExampleConsumerResolver] })
-export class ExampleConsumerModule {}
+import { Annotate, ResolveAnnotation } from "@/modules/core";
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  Module,
+  UseGuards,
+} from "@nestjs/common";
+import {
+  Args,
+  Context,
+  GraphQLExecutionContext,
+  Query,
+  Resolver,
+} from "@nestjs/graphql";
+
+// Export for external
+export type RoleGroups = ("user" | "admin" | "super-admin")[];
+export const ProtectedResolver = (roles: RoleGroups) =>
+  Annotate("protected", { data: { roles } });
+export const InjectableArg = (argName: string, resourceType: string) =>
+  Annotate("resource", { data: { resourceType }, parameter: argName });
+
+@Injectable()
+export class ExampleGuard implements CanActivate {
+  canActivate(context: ExecutionContext) {
+    // Do something with your execution context
+    return true;
+  }
+}
+
+@Resolver()
+export class ExampleConsumerResolver {
+  @Query(() => [String])
+  exampleOut() {
+    return ["this is from consumer"];
+  }
+
+  @UseGuards(ExampleGuard)
+  @ResolveAnnotation("protected")
+  verifyUser(context: ExecutionContext, next: () => void) {
+    console.log("I AM HERE");
+  }
+
+  // Should use the name
+  @ResolveAnnotation("resource")
+  resolveResource(
+    @Args("resourceType") resourceType: string,
+    @Context() context: GraphQLExecutionContext,
+  ) {
+    console.log(resourceType);
+    return "this-is-gateway-provided-username";
+  }
+}
+
+@Module({ providers: [ExampleConsumerResolver] })
+export class ExampleConsumerModule {}

package/src/example/main.ts

@@ -1,23 +1,23 @@
-import { NestFactory } from "@nestjs/core";
-
-import { FastifyAdapter } from "@nestjs/platform-fastify";
-import { ExampleProducerApp } from "./producer/producer.app";
-import { ConsoleLogger, Type } from "@nestjs/common";
-import { ExampleConsumerApp } from "./consumer/consumer.app";
-
-export async function bootstrap(name: string, module: Type, port: number) {
-  const app = await NestFactory.create(module, new FastifyAdapter(), {
-    logger: new ConsoleLogger({ prefix: name }),
-  });
-  await app.listen(port);
-
-  console.log(
-    `Listening on localhost:${port}. Playground: http://localhost:${port}/graphql`
-  );
-}
-
-async function main() {
-  await bootstrap("example-producer", ExampleProducerApp, 3031);
-  await bootstrap("example-consumer", ExampleConsumerApp, 3030);
-}
-void main();
+import { NestFactory } from "@nestjs/core";
+
+import { FastifyAdapter } from "@nestjs/platform-fastify";
+import { ExampleProducerApp } from "./producer/producer.app";
+import { ConsoleLogger, Type } from "@nestjs/common";
+import { ExampleConsumerApp } from "./consumer/consumer.app";
+
+export async function bootstrap(name: string, module: Type, port: number) {
+  const app = await NestFactory.create(module, new FastifyAdapter(), {
+    logger: new ConsoleLogger({ prefix: name }),
+  });
+  await app.listen(port);
+
+  console.log(
+    `Listening on localhost:${port}. Playground: http://localhost:${port}/graphql`
+  );
+}
+
+async function main() {
+  await bootstrap("example-producer", ExampleProducerApp, 3031);
+  await bootstrap("example-consumer", ExampleConsumerApp, 3030);
+}
+void main();