Add @schema decorator to mark namespaces as GraphQL schemas

Using the `TypeSpec.GraphQL.@schema` decorator on a namespace indicates that the decorated namespace represents a GraphQL schema that should be generated by the GraphQL emitter.

Because this allows for multiple schemas to be specified in a TypeSpec source, our test host is reworked to provide a `GraphQLSchemaRecord` corresponding to each schema produced.

This commit does not actually implement any emitter functionality, but populates a state map that will be used by the emitter in the future.

Author: steverice

packages/graphql/lib/main.tsp

@@ -0,0 +1 @@
+import "./schema.tsp";

packages/graphql/lib/schema.tsp

@@ -0,0 +1,23 @@
+import "../dist/src/lib/schema.js";
+
+using TypeSpec.Reflection;
+
+namespace TypeSpec.GraphQL;
+
+namespace Schema {
+  model SchemaOptions {
+    name?: string;
+  }
+}
+
+/**
+ * Mark this namespace as describing a GraphQL schema and configure schema properties.
+ *
+ * @example
+ *
+ * ```typespec
+ * @schema(name: "MySchema")
+ * namespace MySchema {};
+ * ```
+ */
+extern dec schema(target: Namespace, options?: Schema.SchemaOptions);

packages/graphql/package.json

@@ -20,6 +20,7 @@
   "main": "dist/src/index.js",
   "exports": {
     ".": {
+      "typespec": "./lib/main.tsp",
       "types": "./dist/src/index.d.ts",
       "default": "./dist/src/index.js"
     },
@@ -31,6 +32,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "graphql": {
+    "documents": "test/**/*.{js,ts}"
+  },
+  "dependencies": {
+    "graphql": "^16.9.0"
+  },
   "scripts": {
     "clean": "rimraf ./dist ./temp",
     "build": "tsc",

packages/graphql/src/index.ts

@@ -1,2 +1,3 @@
 export { $onEmit } from "./emitter.js";
 export { $lib } from "./lib.js";
+export { $decorators } from "./tsp-index.js";

packages/graphql/src/lib.ts

@@ -1,5 +1,7 @@
 import { createTypeSpecLibrary, type JSONSchemaType } from "@typespec/compiler";
 
+export const NAMESPACE = "TypeSpec.GraphQL";
+
 export interface GraphQLEmitterOptions {
   /**
    * Name of the output file.
@@ -99,4 +101,4 @@ export const libDef = {
 
 export const $lib = createTypeSpecLibrary(libDef);
 
-export const { reportDiagnostic, createDiagnostic } = $lib;
+export const { reportDiagnostic, createDiagnostic, createStateSymbol } = $lib;

packages/graphql/src/lib/schema.ts

@@ -0,0 +1,105 @@
+import {
+  type DecoratorContext,
+  type DecoratorFunction,
+  type Namespace,
+  type Program,
+  type Type,
+  getTypeName,
+  validateDecoratorUniqueOnNode,
+} from "@typespec/compiler";
+
+import { createStateSymbol, NAMESPACE, reportDiagnostic } from "../lib.js";
+import { useStateMap } from "./state-map.js";
+
+// This will set the namespace for decorators implemented in this file
+export const namespace = NAMESPACE;
+
+export interface SchemaDetails {
+  name?: string;
+}
+
+export interface Schema extends SchemaDetails {
+  type: Namespace;
+}
+
+const [getSchema, setSchema, getSchemaMap] = useStateMap<Namespace, Schema>(
+  createStateSymbol("schemas"),
+);
+
+/**
+ * List all the schemas defined in the TypeSpec program
+ * @param program Program
+ * @returns List of schemas.
+ */
+export function listSchemas(program: Program): Schema[] {
+  return [...getSchemaMap(program).values()];
+}
+
+export {
+  /**
+   * Get the schema information for the given namespace.
+   * @param program Program
+   * @param namespace Schema namespace
+   * @returns Schema information or undefined if namespace is not a schema namespace.
+   */
+  getSchema,
+};
+
+/**
+ * Check if the namespace is defined as a schema.
+ * @param program Program
+ * @param namespace Namespace
+ * @returns Boolean
+ */
+export function isSchema(program: Program, namespace: Namespace): boolean {
+  return getSchemaMap(program).has(namespace);
+}
+
+/**
+ * Mark the given namespace as a schema.
+ * @param program Program
+ * @param namespace Namespace
+ * @param details Schema details
+ */
+export function addSchema(
+  program: Program,
+  namespace: Namespace,
+  details: SchemaDetails = {},
+): void {
+  const schemaMap = getSchemaMap(program);
+  const existing = schemaMap.get(namespace) ?? {};
+  setSchema(program, namespace, { ...existing, ...details, type: namespace });
+}
+
+export const $schema: DecoratorFunction = (
+  context: DecoratorContext,
+  target: Namespace,
+  options: Type,
+) => {
+  validateDecoratorUniqueOnNode(context, target, $schema);
+
+  if (options && options.kind !== "Model") {
+    reportDiagnostic(context.program, {
+      code: "invalid-argument",
+      format: { value: options.kind, expected: "Model" },
+      target: context.getArgumentTarget(0)!,
+    });
+    return;
+  }
+
+  const schemaDetails: SchemaDetails = {};
+  const name = options?.properties.get("name")?.type;
+  if (name) {
+    if (name.kind === "String") {
+      schemaDetails.name = name.value;
+    } else {
+      reportDiagnostic(context.program, {
+        code: "unassignable",
+        format: { sourceType: getTypeName(name), targetType: "String" },
+        target: context.getArgumentTarget(0)!,
+      });
+    }
+  }
+
+  addSchema(context.program, target, schemaDetails);
+};

packages/graphql/src/lib/state-map.ts

@@ -0,0 +1,18 @@
+import type { Type } from "@typespec/compiler";
+import { unsafe_useStateMap, unsafe_useStateSet } from "@typespec/compiler/experimental";
+
+/**
+ * This is a copy of the experimental state-accessor lib from @typespec/compiler
+ */
+
+function createStateSymbol(name: string) {
+  return Symbol.for(`TypeSpec.${name}`);
+}
+
+export function useStateMap<K extends Type, V>(key: string | symbol) {
+  return unsafe_useStateMap<K, V>(typeof key === "string" ? createStateSymbol(key) : key);
+}
+
+export function useStateSet<K extends Type>(key: string | symbol) {
+  return unsafe_useStateSet<K>(typeof key === "string" ? createStateSymbol(key) : key);
+}

packages/graphql/src/schema-emitter.ts

@@ -18,7 +18,7 @@ export function createGraphQLEmitter(
       const filePath = interpolatePath(options.outputFile, { "schema-name": "schema" });
       await emitFile(program, {
         path: filePath,
-        content: "Hello world",
+        content: "",
         newLine: options.newLine,
       });
     }

packages/graphql/src/testing/utils.ts

@@ -0,0 +1,12 @@
+import { GraphQLSchema } from "graphql";
+
+export const EMPTY_SCHEMA = new GraphQLSchema({});
+
+export const EMPTY_SCHEMA_OUTPUT = `#graphql
+type Query {
+  """
+  A placeholder field. If you are seeing this, it means no operations were defined that could be emitted.
+  """
+  _: Boolean
+}
+`;

packages/graphql/src/tsp-index.ts

@@ -0,0 +1,9 @@
+import type { DecoratorImplementations } from "@typespec/compiler";
+import { NAMESPACE } from "./lib.js";
+import { $schema } from "./lib/schema.js";
+
+export const $decorators: DecoratorImplementations = {
+  [NAMESPACE]: {
+    schema: $schema,
+  },
+};