@nexus-rpc/gen-core 0.1.0-alpha0

package/dist/utility.js

@@ -0,0 +1,30 @@
+import wordwrap from "wordwrap";
+/**
+ * A helper that proxies an instance and overrides selected methods.
+ * The overrides receive both the original method and its typed parameters.
+ */
+export function proxyWithOverrides(instance, overrides) {
+    return new Proxy(instance, {
+        get(target, property, receiver) {
+            // @ts-expect-error index signature is fine for Proxy
+            const override = overrides[property];
+            if (typeof override === "function") {
+                const original = Reflect.get(target, property, receiver);
+                return function (...arguments_) {
+                    // Call the override, passing original and args
+                    return override.call(this, original.bind(this), ...arguments_);
+                };
+            }
+            return Reflect.get(target, property, receiver);
+        },
+    });
+}
+const wordWrap = wordwrap(90);
+export function splitDescription(string_) {
+    if (!string_) {
+        return undefined;
+    }
+    return wordWrap(string_)
+        .split("\n")
+        .map((l) => l.trim());
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@nexus-rpc/gen-core",
+  "version": "0.1.0-alpha0",
+  "description": "Nexus code generation (core library)",
+  "author": "Temporal Technologies Inc. <sdk@temporal.io>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bugs": {
+    "url": "https://github.com/nexus-rpc/nexus-rpc-gen/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nexus-rpc/nexus-rpc-gen.git",
+    "directory": "src/packages/nexus-rpc-gen-core"
+  },
+  "homepage": "https://github.com/nexus-rpc/nexus-rpc-gen/tree/main/src/packages/nexus-rpc-gen-core",
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "quicktype-core": "^23.2.6",
+    "wordwrap": "^1.0.0",
+    "yaml": "^2.8.1"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "scripts": {}
+}

package/src/definition-schema.ts

@@ -0,0 +1,22 @@
+/* eslint-disable */
+// ⚠️ This file is generated. Do not edit manually.
+
+/**
+ * Definition for Nexus RPC services and operations
+ */
+export interface DefinitionSchema {
+    nexusrpc:  string;
+    services?: { [key: string]: ServiceValue };
+    types?:    { [key: string]: { [key: string]: any } };
+}
+
+export interface ServiceValue {
+    description?: string;
+    operations:   { [key: string]: OperationValue };
+}
+
+export interface OperationValue {
+    description?: string;
+    input?:       { [key: string]: any };
+    output?:      { [key: string]: any };
+}

package/src/generator.ts

@@ -0,0 +1,222 @@
+import {
+  InputData,
+  JSONSchemaInput,
+  JSONSchemaStore,
+  quicktypeMultiFile,
+  Ref,
+  type JSONSchema,
+  type LanguageName,
+  type RendererOptions,
+  type TargetLanguage,
+} from "quicktype-core";
+import type { DefinitionSchema } from "./definition-schema";
+import { PathElementKind } from "quicktype-core/dist/input/PathElement.js";
+import { isPrimitiveTypeKind } from "quicktype-core/dist/Type/index.js";
+
+export interface GeneratorOptions<Lang extends LanguageName = LanguageName> {
+  lang: TargetLanguage;
+  schema: DefinitionSchema;
+  rendererOptions: RendererOptions<Lang>;
+  // Used to help with ideal output filename
+  firstFilenameSansExtensions: string;
+}
+
+export interface PreparedSchema {
+  services: { [key: string]: PreparedService };
+  sharedJsonSchema: { types: { [key: string]: any } };
+  topLevelJsonSchemaTypes: { [key: string]: any };
+  topLevelJsonSchemaLocalRefs: { [key: string]: any };
+}
+
+export interface PreparedService {
+  description?: string;
+  operations: { [key: string]: PreparedOperation };
+}
+
+export interface PreparedOperation {
+  description?: string;
+  input?: PreparedTypeReference;
+  output?: PreparedTypeReference;
+}
+
+export interface PreparedTypeReference {
+  kind: "jsonSchema" | "existing";
+  name: string;
+}
+
+export interface NexusRendererOptions {
+  nexusSchema: PreparedSchema;
+  firstFilenameSansExtensions: string;
+}
+
+export function getNexusRendererOptions(
+  rendererOptions: RendererOptions,
+): NexusRendererOptions {
+  return (rendererOptions as any).nexusOptions;
+}
+
+export class Generator {
+  private readonly options: GeneratorOptions;
+
+  constructor(options: GeneratorOptions) {
+    this.options = options;
+  }
+
+  async generate(): Promise<{ [fileName: string]: string }> {
+    // Prepare schema
+    const schema = this.prepareSchema();
+
+    // Build quicktype input
+    const schemaInput = new JSONSchemaInput(new FetchDisabledSchemaStore());
+    const jsonSchema = {
+      ...schema.sharedJsonSchema,
+      ...schema.topLevelJsonSchemaTypes,
+    };
+    await schemaInput.addSource({
+      // TODO(cretz): Give proper filename name here for proper cross-file referencing
+      name: "__ALL_TYPES__",
+      schema: JSON.stringify(jsonSchema),
+    });
+    // Set the top-level types
+    for (const topLevel of Object.keys(schema.topLevelJsonSchemaTypes)) {
+      schemaInput.addTopLevel(
+        topLevel,
+        Ref.parse(`__ALL_TYPES__#/${topLevel}`),
+      );
+    }
+    for (const [name, reference] of Object.entries(
+      schema.topLevelJsonSchemaLocalRefs,
+    )) {
+      schemaInput.addTopLevel(name, Ref.parse(`__ALL_TYPES__${reference}`));
+    }
+    const inputData = new InputData();
+    inputData.addInput(schemaInput);
+
+    // Update renderer options with the prepared schema
+    const rendererOptions = {
+      nexusOptions: {
+        nexusSchema: schema,
+        firstFilenameSansExtensions: this.options.firstFilenameSansExtensions,
+      },
+      ...this.options.rendererOptions,
+    };
+
+    // Run quicktype and return
+    const returnValue: { [fileName: string]: string } = {};
+    const results = await quicktypeMultiFile({
+      inputData,
+      lang: this.options.lang,
+      rendererOptions,
+    });
+    results.forEach(
+      (contents, fileName) =>
+        (returnValue[fileName] = contents.lines.join("\n")),
+    );
+    return returnValue;
+  }
+
+  private prepareSchema(): PreparedSchema {
+    const schema: PreparedSchema = {
+      services: {},
+      sharedJsonSchema: {
+        types: this.options.schema.types ?? {},
+      },
+      topLevelJsonSchemaTypes: {},
+      topLevelJsonSchemaLocalRefs: {},
+    };
+    for (const [serviceName, service] of Object.entries(
+      this.options.schema.services || {},
+    )) {
+      schema.services[serviceName] = {
+        description: service.description,
+        operations: {},
+      };
+      for (const [operationName, operation] of Object.entries(
+        service.operations,
+      )) {
+        const schemaOp: PreparedOperation = {
+          description: operation.description,
+        };
+        schema.services[serviceName].operations[operationName] = schemaOp;
+        if (operation.input) {
+          schemaOp.input = this.prepareInOutType(
+            schema,
+            serviceName,
+            operationName,
+            operation.input,
+            "Input",
+          );
+        }
+        if (operation.output) {
+          schemaOp.output = this.prepareInOutType(
+            schema,
+            serviceName,
+            operationName,
+            operation.output,
+            "Output",
+          );
+        }
+      }
+    }
+    return schema;
+  }
+
+  private prepareInOutType(
+    schema: PreparedSchema,
+    serviceName: string,
+    operationName: string,
+    opInOut: any,
+    suffix: string,
+  ): PreparedTypeReference {
+    // Check for an existing ref for this specific lang first
+    for (const langName of this.options.lang.names) {
+      if (Object.hasOwn(opInOut, `$${langName.toLowerCase()}Ref`)) {
+        return {
+          kind: "existing",
+          name: opInOut[`$${langName.toLowerCase()}Ref`],
+        };
+      }
+    }
+
+    // If it's a single ref of a local "#" type, just set as reference
+    if (Object.hasOwn(opInOut, "$ref") && opInOut["$ref"].startsWith("#")) {
+      const reference = Ref.parse(opInOut["$ref"]);
+      const other = reference.lookupRef(schema.sharedJsonSchema) as {
+        title?: string;
+      };
+      if (other) {
+        // Default to the title, otherwise last element in path if it's a string key
+        let name = other.title;
+        if (!name) {
+          const lastReferenceElement = reference.path.at(-1);
+          if (lastReferenceElement?.kind == PathElementKind.KeyOrIndex) {
+            name = lastReferenceElement.key;
+          }
+        }
+        // Only ref it if there is a name
+        if (name) {
+          // TODO(cretz): Check that this doesn't clash with something already there
+          schema.topLevelJsonSchemaLocalRefs[name] = opInOut["$ref"];
+          return { kind: "jsonSchema", name };
+        }
+      }
+    }
+    // TODO(cretz): Customization of generated names
+    // TODO(cretz): Remove the service name prefix by default
+    const name = `${serviceName}${operationName[0].toUpperCase()}${operationName.slice(1)}${suffix}`;
+    if (Object.hasOwn(schema.topLevelJsonSchemaTypes, name)) {
+      throw new Error(
+        `Input/output for ${serviceName}.${operationName} would be named ${name} which clashes`,
+      );
+    }
+    schema.topLevelJsonSchemaTypes[name] = opInOut;
+    return { kind: "jsonSchema", name };
+  }
+}
+
+class FetchDisabledSchemaStore extends JSONSchemaStore {
+  fetch(_address: string): Promise<JSONSchema | undefined> {
+    // TODO(cretz): Support this?
+    throw new Error("External $ref unsupported");
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./definition-schema.js";
+export { Generator, type GeneratorOptions } from "./generator.js";
+export { CSharpLanguageWithNexus } from "./language-csharp.js";
+export { GoLanguageWithNexus } from "./language-go.js";
+export { JavaLanguageWithNexus } from "./language-java.js";
+export { PythonLanguageWithNexus } from "./language-python.js";
+export { TypeScriptLanguageWithNexus } from "./language-typescript.js";
+export { parseFiles } from "./parser.js";

package/src/language-csharp.ts

@@ -0,0 +1,190 @@
+import {
+  ConvenienceRenderer,
+  cSharpOptions,
+  CSharpRenderer,
+  CSharpTargetLanguage,
+  systemTextJsonCSharpOptions,
+  SystemTextJsonCSharpRenderer,
+  Type,
+  type LanguageName,
+  type OptionValues,
+  type RenderContext,
+  type RendererOptions,
+  type Sourcelike,
+} from "quicktype-core";
+import { splitDescription } from "./utility.js";
+import {
+  type PreparedService,
+  type PreparedTypeReference,
+} from "./generator.js";
+import { namingFunction } from "quicktype-core/dist/language/CSharp/utils.js";
+import { utf16StringEscape } from "quicktype-core/dist/support/Strings.js";
+import { RenderAdapter, type RenderAccessible } from "./render-adapter.js";
+
+// Change some defaults globally
+cSharpOptions.features.definition.defaultValue = "attributes-only";
+cSharpOptions.framework.definition.defaultValue = "SystemTextJson";
+cSharpOptions.namespace.definition.defaultValue = "NexusServices";
+
+export class CSharpLanguageWithNexus extends CSharpTargetLanguage {
+  protected override makeRenderer<Lang extends LanguageName = "csharp">(
+    renderContext: RenderContext,
+    untypedOptionValues: RendererOptions<Lang>,
+  ): ConvenienceRenderer {
+    const adapter = new CSharpRenderAdapter(
+      super.makeRenderer(renderContext, untypedOptionValues),
+      untypedOptionValues,
+    );
+
+    return adapter.makeRenderer({
+      emitSourceStructure(original, givenOutputFilename) {
+        original(givenOutputFilename);
+        adapter.render.finishFile(adapter.makeFileName());
+      },
+      emitTypesAndSupport(original) {
+        adapter.emitServices();
+        original();
+      },
+      emitUsings(original) {
+        adapter.emitUsings();
+        original();
+      },
+      emitDefaultLeadingComments(original) {
+        adapter.emitDefaultLeadingComments();
+        original();
+      },
+    });
+  }
+}
+
+// emitTypesAndSupport is private, omit before adding
+type CSharpRenderAccessible = Omit<CSharpRenderer, "emitTypesAndSupport"> &
+  RenderAccessible & {
+    readonly _csOptions: OptionValues<typeof cSharpOptions>;
+    csType(
+      t: Type,
+      follow?: (t: Type) => Type,
+      withIssues?: boolean,
+    ): Sourcelike;
+    emitBlock(f: () => void): void;
+    emitDefaultLeadingComments(): void;
+    emitTypesAndSupport(): void;
+    emitUsings(): void;
+  };
+
+class CSharpRenderAdapter extends RenderAdapter<CSharpRenderAccessible> {
+  makeFileName() {
+    // If there is a single service, use that, otherwise use the
+    // filename sans extensions to build it
+    const services = Object.entries(this.schema.services);
+    if (services.length == 1) {
+      return "I" + namingFunction.nameStyle(services[0][0]) + ".cs";
+    }
+    return (
+      namingFunction.nameStyle(
+        this.nexusRendererOptions.firstFilenameSansExtensions,
+      ) + ".cs"
+    );
+  }
+
+  emitDefaultLeadingComments() {
+    // If it's System.Text.Json and not using helpers, we need to emit things
+    if (
+      (this.render as any) instanceof SystemTextJsonCSharpRenderer &&
+      !(
+        this.render._csOptions as OptionValues<
+          typeof systemTextJsonCSharpOptions
+        >
+      ).features.helpers
+    ) {
+      this.render.emitLine("// <auto-generated />");
+      this.render.emitLine("#pragma warning disable CS8618");
+    }
+  }
+
+  emitUsings() {
+    this.render.emitLine("using NexusRpc;");
+  }
+
+  emitServices() {
+    for (const [serviceName, serviceSchema] of Object.entries(
+      this.schema.services,
+    )) {
+      this.emitService(serviceName, serviceSchema);
+    }
+  }
+
+  emitService(serviceName: string, serviceSchema: PreparedService) {
+    // TODO(cretz): Support force-set type name here
+    // TODO(cretz): Support a gen option to not add the "I"
+    // TODO(cretz): Put these I-prefixed names in the forbidden-top-level-names list
+    this.render.ensureBlankLine();
+
+    // Doc
+    this.render.emitDescription(splitDescription(serviceSchema.description));
+
+    const typeName = this.makeServiceTypeName(
+      "I" + namingFunction.nameStyle(serviceName),
+    );
+    this.render.emitLine(
+      "[NexusService",
+      // If the sans-I form doesn't match, set the name explicitly
+      serviceName == typeName.substring(1)
+        ? []
+        : ['("', utf16StringEscape(serviceName), '")'],
+      "]",
+    );
+
+    // Create interface itself
+    this.render.emitLine("public interface ", typeName);
+    const methodNamesInUse = {};
+    this.render.emitBlock(() => {
+      this.render.forEachWithBlankLines(
+        Object.entries(serviceSchema.operations),
+        "interposing",
+        (op, opName, pos) => {
+          // TODO(cretz): Param and return tags
+          this.render.emitDescription(splitDescription(op.description));
+          // Convert the opName to C# style
+          // TODO(cretz): What about reserved words?
+          const methodName = this.makeOperationFunctionName(
+            namingFunction.nameStyle(opName),
+            methodNamesInUse,
+          );
+          // Create the attribute
+          this.render.emitLine(
+            "[NexusOperation",
+            // If the method name doesn't match op name, set explicitly
+            methodName == opName ? [] : ['("', utf16StringEscape(opName), '")'],
+            "]",
+          );
+          const inType = this.getNexusType(op.input);
+          this.render.emitLine(
+            this.getNexusType(op.output) ?? "void",
+            " ",
+            methodName,
+            "(",
+            inType ? [inType, " input"] : [],
+            ");",
+          );
+        },
+      );
+    });
+  }
+
+  getNexusType(
+    reference: PreparedTypeReference | undefined,
+  ): Sourcelike | undefined {
+    if (!reference) {
+      return undefined;
+    } else if (reference.kind == "existing") {
+      return reference.name;
+    } else {
+      const type = this.render.topLevels.get(reference.name);
+      if (!type) {
+        throw new Error(`Unable to find type for ${reference.name}`);
+      }
+      return this.render.csType(type);
+    }
+  }
+}