@tinkerstack/graphql-annotation 0.0.0

package/dist/index.mjs

@@ -0,0 +1,484 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/modules/core/annotation.decorators.ts
+import { SetMetadata } from "@nestjs/common";
+import { Args } from "@nestjs/graphql";
+import "reflect-metadata";
+
+// src/modules/core/annotation.constants.ts
+var ANNOTATION_METADATA = "graphql-annotation";
+var ANNOTATION_RESOLVER_METADATA = "graphql-annotation-resolver";
+var GRAPHQL_ANNOTATION_RESOLVER_METADATA = "graphql-annotation-provider";
+
+// src/modules/core/annotation.decorators.ts
+function Annotate(name, opts) {
+  const annotationName = name;
+  const annotationData = opts?.data;
+  return (target, propertyKey, descriptorOrParameterIndex) => {
+    switch (typeof descriptorOrParameterIndex) {
+      // Method
+      case "object": {
+        const descriptor = descriptorOrParameterIndex;
+        _updateAnnotation(descriptor.value ?? target, (meta) => ({
+          ...meta,
+          [annotationName]: {
+            annotation: annotationName,
+            data: annotationData,
+            target: {
+              type: "method",
+              name: propertyKey
+            }
+          }
+        }));
+        break;
+      }
+      // Parameter
+      case "number": {
+        const paramIndex = descriptorOrParameterIndex;
+        const paramName = opts?.parameter;
+        if (!paramName)
+          throw new Error(
+            `Unable to apply annotation "${annotationName}". Parameter name not specified.`
+          );
+        Args(paramName)(target, propertyKey, paramIndex);
+        _updateAnnotation(
+          target.constructor,
+          (meta) => ({
+            ...meta,
+            [`${annotationName}@${paramIndex}`]: {
+              annotation: annotationName,
+              data: annotationData,
+              target: {
+                type: "parameter",
+                paramIndex,
+                paramName
+              }
+            }
+          }),
+          propertyKey
+        );
+        break;
+      }
+      default:
+        throw new Error(
+          `Unable to attach annotation "${name}". Unsupported target.`
+        );
+    }
+  };
+}
+function _updateAnnotation(target, updateFn, propertyKey) {
+  const meta = Reflect.getMetadata(ANNOTATION_METADATA, target) ?? {};
+  if (propertyKey)
+    Reflect.defineMetadata(
+      ANNOTATION_METADATA,
+      updateFn(meta),
+      target,
+      propertyKey
+    );
+  else Reflect.defineMetadata(ANNOTATION_METADATA, updateFn(meta), target);
+}
+function ResolveAnnotation(name) {
+  return (target, property, descriptor) => {
+    SetMetadata(ANNOTATION_RESOLVER_METADATA, {
+      annotation: name ?? property
+    })(target, property, descriptor);
+  };
+}
+
+// src/modules/core/annotation.loader.ts
+import { stitchSchemas } from "@graphql-tools/stitch";
+import { MapperKind, mapSchema } from "@graphql-tools/utils";
+import { FilterRootFields } from "@graphql-tools/wrap";
+import { Injectable as Injectable2, Logger as Logger2 } from "@nestjs/common";
+import {
+  PARAM_ARGS_METADATA
+} from "@nestjs/graphql";
+import { GqlParamtype } from "@nestjs/graphql/dist/enums/gql-paramtype.enum";
+import { GraphQLClient } from "graphql-request";
+
+// src/modules/core/annotation.resolver.ts
+import { Inject, Injectable, Logger } from "@nestjs/common";
+import { Field, ObjectType, Query, Resolver } from "@nestjs/graphql";
+import { GraphQLJSONObject } from "graphql-scalars";
+import "reflect-metadata";
+var GraphQLAnnotationMeta = class {
+  name;
+  resolvers;
+};
+__decorateClass([
+  Field(() => String)
+], GraphQLAnnotationMeta.prototype, "name", 2);
+__decorateClass([
+  Field(() => GraphQLJSONObject, { name: "resolvers" })
+], GraphQLAnnotationMeta.prototype, "resolvers", 2);
+GraphQLAnnotationMeta = __decorateClass([
+  ObjectType()
+], GraphQLAnnotationMeta);
+var GraphQLAnnotationResolver = class {
+  constructor(metadataScanner, resolverDiscoveryService, meta) {
+    this.metadataScanner = metadataScanner;
+    this.resolverDiscoveryService = resolverDiscoveryService;
+    this.meta = meta;
+  }
+  _logger = new Logger("GraphQLAnnotationModule");
+  async getGraphQLAnnotations() {
+    return {
+      ...this.meta,
+      resolvers: this.resolverAnnotations
+    };
+  }
+  resolverAnnotations = {};
+  async onModuleInit() {
+    this.resolverAnnotations = this.compileResolversAnnotations();
+  }
+  compileResolversAnnotations() {
+    const instances = this.resolverDiscoveryService.explore();
+    const resolversAnnotations = {};
+    for (const { instance } of instances)
+      for (const methodName of this.metadataScanner.getAllMethodNames(
+        Object.getPrototypeOf(instance)
+      )) {
+        const annotations = [
+          ...Object.values(
+            Reflect.getMetadata(ANNOTATION_METADATA, instance[methodName]) ?? {}
+          ),
+          ...Object.values(
+            Reflect.getMetadata(
+              ANNOTATION_METADATA,
+              instance.constructor,
+              methodName
+            ) ?? {}
+          )
+        ];
+        if (annotations.length <= 0) continue;
+        resolversAnnotations[methodName] = annotations;
+        this._logger.log(
+          `Discovered annotated resolver "${instance.constructor.name}.${methodName}" with ${annotations.length} annotation(s)`
+        );
+      }
+    return resolversAnnotations;
+  }
+};
+__publicField(GraphQLAnnotationResolver, "QUERY_NAME", "_annotations");
+__decorateClass([
+  Query(() => GraphQLAnnotationMeta, {
+    name: GraphQLAnnotationResolver.QUERY_NAME
+  })
+], GraphQLAnnotationResolver.prototype, "getGraphQLAnnotations", 1);
+GraphQLAnnotationResolver = __decorateClass([
+  Resolver(),
+  Injectable(),
+  __decorateParam(2, Inject(ANNOTATION_RESOLVER_METADATA))
+], GraphQLAnnotationResolver);
+
+// src/modules/core/annotation.utils.ts
+import { buildHTTPExecutor } from "@graphql-tools/executor-http";
+import { schemaFromExecutor } from "@graphql-tools/wrap";
+async function loadGraphQLSchema(url) {
+  const executor = buildHTTPExecutor({
+    endpoint: url
+  });
+  return {
+    schema: await schemaFromExecutor(executor),
+    executor
+    // Has to be included.
+  };
+}
+function split(array, predicate) {
+  const match = [];
+  const rest = [];
+  array.forEach((item) => {
+    const matchedPredicate = predicate(item);
+    const target = matchedPredicate ? match : rest;
+    target.push(item);
+  });
+  return [
+    match,
+    rest
+  ];
+}
+function shallowMerge(objects) {
+  const res = {};
+  objects.forEach((o) => Object.assign(res, o));
+  return res;
+}
+function isPlainObject(obj) {
+  const prototype = Object.getPrototypeOf(obj);
+  return prototype === Object.getPrototypeOf({}) || prototype === null;
+}
+
+// src/modules/core/annotation.loader.ts
+import { instanceToPlain } from "class-transformer";
+var GraphQLAnnotatedSchemaLoader = class {
+  constructor(resolverDiscoveryService, metadataScanner, externalContextCreator) {
+    this.resolverDiscoveryService = resolverDiscoveryService;
+    this.metadataScanner = metadataScanner;
+    this.externalContextCreator = externalContextCreator;
+  }
+  _logger = new Logger2("GraphQLAnnotationModule");
+  async load(sources) {
+    const loadedSources = await this.batchLoadSources(sources);
+    const schema = stitchSchemas({
+      subschemas: loadedSources.map((s) => s.subschema)
+    });
+    const annotations = shallowMerge(
+      loadedSources.map((s) => s.annotation)
+    );
+    const annotationResolvers = await this.discoverAnnotationResolvers();
+    return this.embedAnnotationResolversToSchema(
+      schema,
+      annotations,
+      annotationResolvers
+    );
+  }
+  async discoverAnnotationResolvers() {
+    const annotationResolvers = /* @__PURE__ */ new Map();
+    const paramFactory = new GraphQLAnnotationResolverParamsFactory();
+    const instances = this.resolverDiscoveryService.explore();
+    for (const { instance } of instances)
+      for (const methodName of this.metadataScanner.getAllMethodNames(
+        Object.getPrototypeOf(instance)
+      )) {
+        const resolverMeta = Reflect.getMetadata(
+          ANNOTATION_RESOLVER_METADATA,
+          instance[methodName]
+        );
+        if (!resolverMeta) continue;
+        this._logger.log(
+          `Discovered resolver for annotation "${resolverMeta.annotation}"`
+        );
+        annotationResolvers.set(
+          resolverMeta.annotation,
+          this.externalContextCreator.create(
+            instance,
+            instance[methodName],
+            methodName,
+            PARAM_ARGS_METADATA,
+            paramFactory,
+            void 0,
+            void 0,
+            void 0,
+            "graphql"
+          )
+        );
+      }
+    return annotationResolvers;
+  }
+  async batchLoadSources(sources) {
+    const pending = Object.entries(sources).map(async ([name, url]) => {
+      const loadId = `${name}@${url}`;
+      try {
+        const loaded2 = {
+          id: loadId,
+          url,
+          name,
+          subschema: await loadGraphQLSchema(url),
+          annotation: await this.loadAnnotations(url)
+        };
+        loaded2.subschema.transforms = [
+          new FilterRootFields(
+            (op, fieldName) => !fieldName.endsWith(GraphQLAnnotationResolver.QUERY_NAME)
+          )
+        ];
+        this._logger.log(`Loaded schema for ${loadId}`);
+        return loaded2;
+      } catch (err) {
+        this._logger.error(`Unable to load schema for ${loadId}`);
+        throw err;
+      }
+    });
+    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.`
+      );
+    return loaded.map((l) => l.value);
+  }
+  async loadAnnotations(url) {
+    const client = new GraphQLClient(url);
+    try {
+      const res = await client.rawRequest(`
+        query IntrospectAnnotations {
+          ${GraphQLAnnotationResolver.QUERY_NAME} {
+            name
+            resolvers
+          }
+        }
+      `);
+      this._logger.log(`Loaded annotations for ${url}`);
+      return res.data[GraphQLAnnotationResolver.QUERY_NAME];
+    } catch (err) {
+      this._logger.warn(`Failed to load annotations at ${url}, assuming empty`);
+      return {};
+    }
+  }
+  async embedAnnotationResolversToSchema(schema, annotations, annotationResolvers) {
+    return mapSchema(schema, {
+      [MapperKind.ROOT_FIELD]: (fieldSchema, name, type) => {
+        const fieldAnnotations = (annotations.resolvers[name] ?? []).map((info) => ({
+          ...info,
+          resolver: annotationResolvers.get(info.annotation)
+          // NOTE: should be validated in filter
+        })).filter((info) => {
+          const annotationHasResolver = info.resolver !== void 0;
+          if (!annotationHasResolver)
+            this._logger.warn(
+              `Found unhandled annotation "${info.annotation}", skipping linking process`
+            );
+          return annotationHasResolver;
+        });
+        if (fieldAnnotations.length <= 0) return fieldSchema;
+        for (const annotation of fieldAnnotations)
+          if (annotation.target.type === "parameter" && fieldSchema.args)
+            delete fieldSchema.args[annotation.target.paramName];
+        const defaultResolver = fieldSchema.resolve;
+        fieldSchema.resolve = async function(parent, args, context, info) {
+          const annotationCallbacks = await Promise.all(
+            fieldAnnotations.map(async (annotation) => ({
+              annotation,
+              return: await annotation.resolver(
+                ...[
+                  info.rootValue,
+                  annotation.data,
+                  context,
+                  info
+                ]
+              )
+            }))
+          );
+          const resolvedParams = annotationCallbacks.reduce(
+            (params, call) => {
+              if (call.annotation.target.type !== "parameter") return params;
+              const returnedClassType = typeof call.return === "object" && !isPlainObject(call.return);
+              const returnValue = returnedClassType ? instanceToPlain(call.return) : call.return;
+              params[call.annotation.target.paramName] = returnValue;
+              return params;
+            },
+            {}
+          );
+          return defaultResolver(
+            parent,
+            { ...args, ...resolvedParams },
+            context,
+            info
+          );
+        };
+        return fieldSchema;
+      }
+    });
+  }
+};
+GraphQLAnnotatedSchemaLoader = __decorateClass([
+  Injectable2()
+], GraphQLAnnotatedSchemaLoader);
+var GraphQLAnnotationResolverParamsFactory = class {
+  // This param factory extends graphql's own just with different inputs from annotations instead.
+  // https://github.com/nestjs/graphql/blob/master/packages/graphql/lib/factories/params.factory.ts#L9
+  exchangeKeyForValue(type, possibleKey, argsContext) {
+    if (!argsContext) return null;
+    console.log(type, possibleKey, argsContext);
+    const args = {
+      parentValue: argsContext[0],
+      data: argsContext[1],
+      context: argsContext[2],
+      info: argsContext[3]
+    };
+    switch (type) {
+      case GqlParamtype.ROOT:
+        return args.parentValue;
+      case GqlParamtype.ARGS:
+        return possibleKey && args.data ? args.data[possibleKey] : args.data;
+      case GqlParamtype.CONTEXT:
+        return possibleKey && args.context ? args.context[possibleKey] : args.context;
+      case GqlParamtype.INFO:
+        return possibleKey && args.context ? args.info[possibleKey] : args.info;
+      default:
+        return null;
+    }
+  }
+};
+
+// src/modules/core/annotation.module.ts
+import { Module } from "@nestjs/common";
+import { DiscoveryModule } from "@nestjs/core";
+
+// src/modules/core/resolver.explorer.ts
+import { Injectable as Injectable3 } from "@nestjs/common";
+import { RESOLVER_TYPE_METADATA } from "@nestjs/graphql";
+var ResolverDiscoveryService = class {
+  constructor(discoveryService) {
+    this.discoveryService = discoveryService;
+  }
+  explore() {
+    const wrappedProviders = this.discoveryService.getProviders();
+    return wrappedProviders.flatMap((wrapped) => {
+      const { instance } = wrapped;
+      if (!instance) return [];
+      const isResolver = Reflect.hasMetadata(
+        RESOLVER_TYPE_METADATA,
+        instance.constructor
+      );
+      if (!isResolver) return [];
+      return wrapped;
+    });
+  }
+};
+ResolverDiscoveryService = __decorateClass([
+  Injectable3()
+], ResolverDiscoveryService);
+
+// src/modules/core/annotation.module.ts
+var GraphQLAnnotationModule = class {
+  static forRoot(opts) {
+    if (opts?.serveAnnotations)
+      return {
+        global: true,
+        module: GraphQLAnnotationModule,
+        imports: [DiscoveryModule],
+        providers: [
+          ResolverDiscoveryService,
+          GraphQLAnnotatedSchemaLoader,
+          {
+            provide: ANNOTATION_RESOLVER_METADATA,
+            useValue: opts.serveConfig
+          },
+          GraphQLAnnotationResolver
+        ],
+        exports: [GraphQLAnnotatedSchemaLoader]
+      };
+    return {
+      global: true,
+      module: GraphQLAnnotationModule,
+      imports: [DiscoveryModule],
+      providers: [ResolverDiscoveryService, GraphQLAnnotatedSchemaLoader],
+      exports: [GraphQLAnnotatedSchemaLoader]
+    };
+  }
+};
+GraphQLAnnotationModule = __decorateClass([
+  Module({})
+], GraphQLAnnotationModule);
+export {
+  ANNOTATION_METADATA,
+  ANNOTATION_RESOLVER_METADATA,
+  Annotate,
+  GRAPHQL_ANNOTATION_RESOLVER_METADATA,
+  GraphQLAnnotatedSchemaLoader,
+  GraphQLAnnotationModule,
+  ResolveAnnotation
+};

package/nest-cli.json

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

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@tinkerstack/graphql-annotation",
+  "version": "0.0.0",
+  "description": "Better type-safe-able graphql directives",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "keywords": [],
+  "author": "@plasteek",
+  "license": "MIT",
+  "dependencies": {
+    "@graphql-tools/delegate": "^12.0.4",
+    "@graphql-tools/executor-http": "^3.1.0",
+    "@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"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11",
+    "@nestjs/graphql": "^13",
+    "class-transformer": "^0",
+    "class-validator": "^0",
+    "graphql": "^16",
+    "graphql-scalars": "^1",
+    "reflect-metadata": "^0"
+  },
+  "devDependencies": {
+    "@apollo/server": "^4.12.2",
+    "@as-integrations/fastify": "^3.1.0",
+    "@nestjs/apollo": "^13.2.3",
+    "@nestjs/common": "^11.1.6",
+    "@nestjs/core": "^11.1.3",
+    "@nestjs/graphql": "^13.2.3",
+    "@nestjs/mapped-types": "^2.1.0",
+    "@nestjs/platform-fastify": "^11.1.11",
+    "class-validator": "^0.14.2",
+    "concurrently": "^9.2.1",
+    "eslint": "^9.37.0",
+    "graphql": "^16.12.0",
+    "graphql-scalars": "^1.24.2",
+    "prettier": "^3.6.2",
+    "reflect-metadata": "^0.2.2",
+    "tslib": "^2.8.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "nest start --watch"
+  }
+}

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

@@ -0,0 +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 {}

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

@@ -0,0 +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 {}

package/src/example/consumer/consumer.schema.gql

@@ -0,0 +1,7 @@
+# ------------------------------------------------------
+# THIS FILE WAS AUTOMATICALLY GENERATED (DO NOT MODIFY)
+# ------------------------------------------------------
+
+type Query {
+  exampleOut: [String!]!
+}

package/src/example/main.ts

@@ -0,0 +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();

package/src/example/producer/producer.app.ts

@@ -0,0 +1,22 @@
+import { Module } from "@nestjs/common";
+import { GraphQLModule } from "@nestjs/graphql";
+import { ExampleProducerModule } from "./producer.example";
+
+import { ApolloDriver, ApolloDriverConfig } from "@nestjs/apollo";
+import { GraphQLAnnotationModule } from "@/modules/core/annotation.module";
+
+@Module({
+  imports: [
+    GraphQLModule.forRoot<ApolloDriverConfig>({
+      driver: ApolloDriver,
+      graphiql: true,
+      autoSchemaFile: "./src/example/producer/producer.schema.gql",
+    }),
+    GraphQLAnnotationModule.forRoot({
+      serveAnnotations: true,
+      serveConfig: { name: "producer-example" },
+    }),
+    ExampleProducerModule,
+  ],
+})
+export class ExampleProducerApp {}