@tinkerstack/graphql-annotation 0.0.0

package/.turbo/turbo-build.log

@@ -0,0 +1,22 @@
+
+> @tinkerstack/graphql-annotation@1.0.0 build C:\Users\mori\Documents\Work\tinkerstack\packages\graphql-annotation
+> tsup
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.build.json
+CLI tsup v8.5.1
+CLI Using tsup config: C:\Users\mori\Documents\Work\tinkerstack\packages\graphql-annotation\tsup.config.ts
+CLI Target: es2022
+CLI Cleaning output folder
+ESM Build start
+CJS Build start
+ESM You have emitDecoratorMetadata enabled but @swc/core was not installed, skipping swc plugin
+CJS You have emitDecoratorMetadata enabled but @swc/core was not installed, skipping swc plugin
+ESM dist\index.mjs 15.83 KB
+ESM ⚡️ Build success in 36ms
+CJS dist\index.js 17.66 KB
+CJS ⚡️ Build success in 35ms
+DTS Build start
+DTS ⚡️ Build success in 1773ms
+DTS dist\index.d.mts 2.89 KB
+DTS dist\index.d.ts  2.89 KB

package/README.md

@@ -0,0 +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"];
+  }
+}
+```

package/dist/index.d.mts

@@ -0,0 +1,76 @@
+import { DiscoveryService, MetadataScanner, ExternalContextCreator } from '@nestjs/core';
+import { GraphQLSchema } from 'graphql';
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+import { DynamicModule } from '@nestjs/common';
+
+declare function Annotate(name: string, opts?: {
+    data?: Record<string, any>;
+    parameter?: undefined;
+}): MethodDecorator;
+declare function Annotate(name: string, opts: {
+    data?: Record<string, any>;
+    parameter: string;
+}): ParameterDecorator & MethodDecorator;
+declare function ResolveAnnotation(): MethodDecorator;
+declare function ResolveAnnotation(annotation: string): MethodDecorator;
+
+declare const ANNOTATION_METADATA = "graphql-annotation";
+interface MethodInfo {
+    type: "method";
+    name: string;
+}
+interface ParameterInfo {
+    type: "parameter";
+    paramIndex: number;
+    paramName: string;
+}
+type AnnotationTarget = MethodInfo | ParameterInfo;
+interface AnnotationInfo<T = unknown> {
+    annotation: string;
+    target: AnnotationTarget;
+    data: T;
+}
+declare const ANNOTATION_RESOLVER_METADATA = "graphql-annotation-resolver";
+interface AnnotationResolverMetadata {
+    annotation: string;
+}
+type SourceName = string;
+type RemoteURL = string;
+type AnnotationSchemaSources = Record<SourceName, RemoteURL>;
+type ResolverName = string;
+type GraphQLResolversAnnotations = Record<ResolverName, AnnotationInfo[]>;
+declare const GRAPHQL_ANNOTATION_RESOLVER_METADATA = "graphql-annotation-provider";
+type GraphQLAnnotationResolverMetadata = {
+    name: string;
+};
+
+declare class ResolverDiscoveryService {
+    private readonly discoveryService;
+    constructor(discoveryService: DiscoveryService);
+    explore(): InstanceWrapper[];
+}
+
+declare class GraphQLAnnotatedSchemaLoader {
+    private readonly resolverDiscoveryService;
+    private readonly metadataScanner;
+    private readonly externalContextCreator;
+    private _logger;
+    constructor(resolverDiscoveryService: ResolverDiscoveryService, metadataScanner: MetadataScanner, externalContextCreator: ExternalContextCreator);
+    load(sources: AnnotationSchemaSources): Promise<GraphQLSchema>;
+    private discoverAnnotationResolvers;
+    private batchLoadSources;
+    private loadAnnotations;
+    private embedAnnotationResolversToSchema;
+}
+
+declare class GraphQLAnnotationModule {
+    static forRoot(opts?: {
+        serveAnnotations?: false;
+    }): DynamicModule;
+    static forRoot(opts: {
+        serveAnnotations: true;
+        serveConfig: GraphQLAnnotationResolverMetadata;
+    }): DynamicModule;
+}
+
+export { ANNOTATION_METADATA, ANNOTATION_RESOLVER_METADATA, Annotate, type AnnotationInfo, type AnnotationResolverMetadata, type AnnotationSchemaSources, type AnnotationTarget, GRAPHQL_ANNOTATION_RESOLVER_METADATA, GraphQLAnnotatedSchemaLoader, GraphQLAnnotationModule, type GraphQLAnnotationResolverMetadata, type GraphQLResolversAnnotations, type MethodInfo, type ParameterInfo, ResolveAnnotation, type ResolverName };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { DiscoveryService, MetadataScanner, ExternalContextCreator } from '@nestjs/core';
+import { GraphQLSchema } from 'graphql';
+import { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+import { DynamicModule } from '@nestjs/common';
+
+declare function Annotate(name: string, opts?: {
+    data?: Record<string, any>;
+    parameter?: undefined;
+}): MethodDecorator;
+declare function Annotate(name: string, opts: {
+    data?: Record<string, any>;
+    parameter: string;
+}): ParameterDecorator & MethodDecorator;
+declare function ResolveAnnotation(): MethodDecorator;
+declare function ResolveAnnotation(annotation: string): MethodDecorator;
+
+declare const ANNOTATION_METADATA = "graphql-annotation";
+interface MethodInfo {
+    type: "method";
+    name: string;
+}
+interface ParameterInfo {
+    type: "parameter";
+    paramIndex: number;
+    paramName: string;
+}
+type AnnotationTarget = MethodInfo | ParameterInfo;
+interface AnnotationInfo<T = unknown> {
+    annotation: string;
+    target: AnnotationTarget;
+    data: T;
+}
+declare const ANNOTATION_RESOLVER_METADATA = "graphql-annotation-resolver";
+interface AnnotationResolverMetadata {
+    annotation: string;
+}
+type SourceName = string;
+type RemoteURL = string;
+type AnnotationSchemaSources = Record<SourceName, RemoteURL>;
+type ResolverName = string;
+type GraphQLResolversAnnotations = Record<ResolverName, AnnotationInfo[]>;
+declare const GRAPHQL_ANNOTATION_RESOLVER_METADATA = "graphql-annotation-provider";
+type GraphQLAnnotationResolverMetadata = {
+    name: string;
+};
+
+declare class ResolverDiscoveryService {
+    private readonly discoveryService;
+    constructor(discoveryService: DiscoveryService);
+    explore(): InstanceWrapper[];
+}
+
+declare class GraphQLAnnotatedSchemaLoader {
+    private readonly resolverDiscoveryService;
+    private readonly metadataScanner;
+    private readonly externalContextCreator;
+    private _logger;
+    constructor(resolverDiscoveryService: ResolverDiscoveryService, metadataScanner: MetadataScanner, externalContextCreator: ExternalContextCreator);
+    load(sources: AnnotationSchemaSources): Promise<GraphQLSchema>;
+    private discoverAnnotationResolvers;
+    private batchLoadSources;
+    private loadAnnotations;
+    private embedAnnotationResolversToSchema;
+}
+
+declare class GraphQLAnnotationModule {
+    static forRoot(opts?: {
+        serveAnnotations?: false;
+    }): DynamicModule;
+    static forRoot(opts: {
+        serveAnnotations: true;
+        serveConfig: GraphQLAnnotationResolverMetadata;
+    }): DynamicModule;
+}
+
+export { ANNOTATION_METADATA, ANNOTATION_RESOLVER_METADATA, Annotate, type AnnotationInfo, type AnnotationResolverMetadata, type AnnotationSchemaSources, type AnnotationTarget, GRAPHQL_ANNOTATION_RESOLVER_METADATA, GraphQLAnnotatedSchemaLoader, GraphQLAnnotationModule, type GraphQLAnnotationResolverMetadata, type GraphQLResolversAnnotations, type MethodInfo, type ParameterInfo, ResolveAnnotation, type ResolverName };