nexus-rpc-gen 0.1.0-alpha.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Temporal Technologies Inc. All Rights Reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# nexus-rpc-gen
+
+CLI tool for generating code from NexusRPC definition files. This package provides the command-line interface that uses `@nexus-rpc/gen-core` to generate code in multiple languages.
+
+For installation, usage, and detailed documentation, see the [main repository README](https://github.com/nexus-rpc/nexus-rpc-gen/blob/main/README.md).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import commandLineArgs, {} from "command-line-args";
+import { languageNamed } from "quicktype-core";
+import esMain from "es-main";
+import { CSharpLanguageWithNexus, Generator, GoLanguageWithNexus, JavaLanguageWithNexus, parseFiles, PythonLanguageWithNexus, TypeScriptLanguageWithNexus, } from "@nexus-rpc/gen-core";
+import getUsage, {} from "command-line-usage";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+const supportedLanguages = [
+    new CSharpLanguageWithNexus(),
+    new GoLanguageWithNexus(),
+    new JavaLanguageWithNexus(),
+    new PythonLanguageWithNexus(),
+    // TODO(cretz): new RubyTargetLanguage(),
+    // TODO(cretz): new RustTargetLanguage(),
+    new TypeScriptLanguageWithNexus(),
+];
+const commonOptionDefs = [
+    { name: "help", alias: "h", type: Boolean, description: "Display help." },
+    { name: "lang", description: "The target language." },
+    {
+        name: "out-dir",
+        description: "Out directory. Mutually exclusive with --out-file.",
+    },
+    {
+        name: "out-file",
+        description: "Out file. Mutually exclusive with --out-dir.",
+    },
+    {
+        name: "dry-run",
+        type: Boolean,
+        description: "Dump every file that would be written to stdout instead.",
+    },
+    { name: "files", multiple: true, defaultOption: true },
+];
+async function main(argv) {
+    // Parse args with just lang and files
+    const optionDefs = [...commonOptionDefs];
+    let rawOptions = commandLineArgs(optionDefs, { argv, partial: true });
+    if (rawOptions.help) {
+        printUsage();
+        return;
+    }
+    if (rawOptions.lang == null) {
+        printUsage();
+        throw new Error("--lang required");
+    }
+    else if (!rawOptions.files || !rawOptions.files.length) {
+        printUsage();
+        throw new Error("At least one file required");
+    }
+    else if (rawOptions["out-dir"] && rawOptions["out-file"]) {
+        printUsage();
+        throw new Error("Cannot provide both --out-dir and --out-file");
+    }
+    const lang = languageNamed(rawOptions.lang, supportedLanguages);
+    // Now parse args with language-specific options
+    optionDefs.push(...lang.cliOptionDefinitions.actual);
+    rawOptions = commandLineArgs(optionDefs, { argv });
+    // Parse/validate YAML files
+    const schema = await parseFiles(rawOptions.files);
+    // Convert args to generator options structure
+    const genOptions = {
+        lang,
+        schema,
+        rendererOptions: {},
+        firstFilenameSansExtensions: path
+            .basename(rawOptions.files[0])
+            .split(".")[0],
+    };
+    for (const defn of lang.cliOptionDefinitions.actual) {
+        const untypedRenderOptions = genOptions.rendererOptions;
+        untypedRenderOptions[defn.name] = rawOptions[defn.name];
+    }
+    // Run generator
+    const results = Object.entries(await new Generator(genOptions).generate());
+    // Make result filenames absolute
+    for (let index = 0; index < results.length; index++) {
+        if (rawOptions["out-dir"]) {
+            results[index][0] = path.join(rawOptions["out-dir"], results[index][0]);
+        }
+        else if (!rawOptions["dry-run"] && index > 0) {
+            // Cannot use stdout or out-file in multi-file scenarios
+            throw new Error(`Generated ${results.length} files, must use --out-dir`);
+        }
+        else if (rawOptions["out-file"]) {
+            // Always overwrite filename, and disallow this arg in multi-file scenarios
+            if (index > 0) {
+                throw new Error(`Generated ${results.length} files, cannot provide single-file --out-file, use --out-dir`);
+            }
+            results[index][0] = rawOptions["out-file"];
+        }
+    }
+    // Dump
+    for (const [filePath, fileContents] of results) {
+        // Write with log for dry-run, stdout if no out, and file otherwise
+        if (rawOptions["dry-run"]) {
+            console.log(`--- ${filePath} ---\n${fileContents}\n-------`);
+        }
+        else if (!rawOptions["out-dir"] && !rawOptions["out-file"]) {
+            // Note, validation from before means this only happens on single-file results
+            process.stdout.write(fileContents);
+        }
+        else {
+            // We make dirs lazily in dir-based scenarios
+            if (rawOptions["out-dir"]) {
+                await mkdir(path.dirname(filePath), { recursive: true });
+            }
+            console.log(`Writing ${filePath}`);
+            await writeFile(filePath, fileContents);
+        }
+    }
+}
+function printUsage() {
+    // Show shortest lang form
+    const langNames = supportedLanguages.flatMap((l) => l.names.reduce((a, b) => (a.length <= b.length ? a : b)));
+    // Common sections
+    const tableOptions = {
+        columns: [
+            { name: "option", width: 60 },
+            { name: "description", width: 60 },
+        ],
+    };
+    const sections = [
+        {
+            header: "Synopsis",
+            content: [
+                `$ nexus-rpc-gen [--lang LANG] [--out FILE/DIR] SCHEMA_FILE|URL ...`,
+                "",
+                `  LANG ... ${langNames.join("|")}`,
+            ],
+        },
+        {
+            header: "Description",
+            content: "Generate code from Nexus RPC definition file.",
+        },
+        {
+            header: "Options",
+            optionList: commonOptionDefs,
+            hide: ["files"],
+            tableOptions,
+        },
+    ];
+    // Add per-language sections
+    for (const lang of supportedLanguages) {
+        sections.push({
+            header: `Options for ${lang.displayName}`,
+            optionList: lang.cliOptionDefinitions.display,
+            tableOptions,
+        });
+    }
+    // Dump
+    console.log(getUsage(sections));
+}
+// Node 22.18+ and 24.2+ provides `import.meta.main`, which deprecates the need for
+// this npm library. Bun and Deno have had that API for a long time already. But until
+// we're ready to drop older versions of Node, we need this library to support it.
+if (import.meta.main || esMain(import.meta)) {
+    try {
+        await main(process.argv.slice(2));
+    }
+    catch (error) {
+        if (process.env.NEXUS_IDL_DEBUG) {
+            console.error(error);
+        }
+        else {
+            console.error(`${error}`);
+        }
+        process.exit(1);
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "nexus-rpc-gen",
+  "version": "0.1.0-alpha.3",
+  "description": "Nexus code generation",
+  "author": "Temporal Technologies Inc. <sdk@temporal.io>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": "dist/index.js",
+  "engines": {
+    "node": ">= 18.0.0"
+  },
+  "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"
+  },
+  "homepage": "https://github.com/nexus-rpc/nexus-rpc-gen/tree/main/src/packages/nexus-rpc-gen",
+  "dependencies": {
+    "arg": "^5.0.2",
+    "command-line-args": "^6.0.1",
+    "command-line-usage": "^7.0.3",
+    "es-main": "^1.4.0",
+    "quicktype-core": "^23.2.6",
+    "@nexus-rpc/gen-core": "0.1.0-alpha.3"
+  },
+  "devDependencies": {
+    "@types/command-line-args": "^5.2.3",
+    "@types/command-line-usage": "^5.0.4",
+    "@types/node": "^24.7.0",
+    "quicktype": "^23.2.6",
+    "tsx": "^4.21.0"
+  },
+  "files": [
+    "README.md",
+    "src",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:schema": "tsx scripts/build-schema.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+import commandLineArgs, { type OptionDefinition } from "command-line-args";
+import { languageNamed, type LanguageName } from "quicktype-core";
+import esMain from "es-main";
+import {
+  CSharpLanguageWithNexus,
+  Generator,
+  GoLanguageWithNexus,
+  JavaLanguageWithNexus,
+  parseFiles,
+  PythonLanguageWithNexus,
+  TypeScriptLanguageWithNexus,
+  type GeneratorOptions,
+} from "@nexus-rpc/gen-core";
+import getUsage, { type Section } from "command-line-usage";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const supportedLanguages = [
+  new CSharpLanguageWithNexus(),
+  new GoLanguageWithNexus(),
+  new JavaLanguageWithNexus(),
+  new PythonLanguageWithNexus(),
+  // TODO(cretz): new RubyTargetLanguage(),
+  // TODO(cretz): new RustTargetLanguage(),
+  new TypeScriptLanguageWithNexus(),
+];
+
+const commonOptionDefs = [
+  { name: "help", alias: "h", type: Boolean, description: "Display help." },
+  { name: "lang", description: "The target language." },
+  {
+    name: "out-dir",
+    description: "Out directory. Mutually exclusive with --out-file.",
+  },
+  {
+    name: "out-file",
+    description: "Out file. Mutually exclusive with --out-dir.",
+  },
+  {
+    name: "dry-run",
+    type: Boolean,
+    description: "Dump every file that would be written to stdout instead.",
+  },
+  { name: "files", multiple: true, defaultOption: true },
+];
+
+async function main(argv: string[]) {
+  // Parse args with just lang and files
+  const optionDefs: OptionDefinition[] = [...commonOptionDefs];
+  let rawOptions = commandLineArgs(optionDefs, { argv, partial: true });
+  if (rawOptions.help) {
+    printUsage();
+    return;
+  }
+  if (rawOptions.lang == null) {
+    printUsage();
+    throw new Error("--lang required");
+  } else if (!rawOptions.files || !rawOptions.files.length) {
+    printUsage();
+    throw new Error("At least one file required");
+  } else if (rawOptions["out-dir"] && rawOptions["out-file"]) {
+    printUsage();
+    throw new Error("Cannot provide both --out-dir and --out-file");
+  }
+  const lang = languageNamed(
+    rawOptions.lang as LanguageName,
+    supportedLanguages,
+  );
+
+  // Now parse args with language-specific options
+  optionDefs.push(...lang.cliOptionDefinitions.actual);
+  rawOptions = commandLineArgs(optionDefs, { argv });
+
+  // Parse/validate YAML files
+  const schema = await parseFiles(rawOptions.files);
+
+  // Convert args to generator options structure
+  const genOptions: GeneratorOptions = {
+    lang,
+    schema,
+    rendererOptions: {},
+    firstFilenameSansExtensions: path
+      .basename(rawOptions.files[0])
+      .split(".")[0],
+  };
+  for (const defn of lang.cliOptionDefinitions.actual) {
+    const untypedRenderOptions = genOptions.rendererOptions as Record<
+      typeof defn.name,
+      unknown
+    >;
+    untypedRenderOptions[defn.name] = rawOptions[defn.name];
+  }
+
+  // Run generator
+  const results = Object.entries(await new Generator(genOptions).generate());
+
+  // Make result filenames absolute
+  for (let index = 0; index < results.length; index++) {
+    if (rawOptions["out-dir"]) {
+      results[index][0] = path.join(rawOptions["out-dir"], results[index][0]);
+    } else if (!rawOptions["dry-run"] && index > 0) {
+      // Cannot use stdout or out-file in multi-file scenarios
+      throw new Error(`Generated ${results.length} files, must use --out-dir`);
+    } else if (rawOptions["out-file"]) {
+      // Always overwrite filename, and disallow this arg in multi-file scenarios
+      if (index > 0) {
+        throw new Error(
+          `Generated ${results.length} files, cannot provide single-file --out-file, use --out-dir`,
+        );
+      }
+      results[index][0] = rawOptions["out-file"];
+    }
+  }
+
+  // Dump
+  for (const [filePath, fileContents] of results) {
+    // Write with log for dry-run, stdout if no out, and file otherwise
+    if (rawOptions["dry-run"]) {
+      console.log(`--- ${filePath} ---\n${fileContents}\n-------`);
+    } else if (!rawOptions["out-dir"] && !rawOptions["out-file"]) {
+      // Note, validation from before means this only happens on single-file results
+      process.stdout.write(fileContents);
+    } else {
+      // We make dirs lazily in dir-based scenarios
+      if (rawOptions["out-dir"]) {
+        await mkdir(path.dirname(filePath), { recursive: true });
+      }
+      console.log(`Writing ${filePath}`);
+      await writeFile(filePath, fileContents);
+    }
+  }
+}
+
+function printUsage() {
+  // Show shortest lang form
+  const langNames = supportedLanguages.flatMap((l) =>
+    l.names.reduce((a, b) => (a.length <= b.length ? a : b)),
+  );
+  // Common sections
+  const tableOptions = {
+    columns: [
+      { name: "option", width: 60 },
+      { name: "description", width: 60 },
+    ],
+  };
+  const sections: Section[] = [
+    {
+      header: "Synopsis",
+      content: [
+        `$ nexus-rpc-gen [--lang LANG] [--out FILE/DIR] SCHEMA_FILE|URL ...`,
+        "",
+        `  LANG ... ${langNames.join("|")}`,
+      ],
+    },
+    {
+      header: "Description",
+      content: "Generate code from Nexus RPC definition file.",
+    },
+    {
+      header: "Options",
+      optionList: commonOptionDefs,
+      hide: ["files"],
+      tableOptions,
+    },
+  ];
+  // Add per-language sections
+  for (const lang of supportedLanguages) {
+    sections.push({
+      header: `Options for ${lang.displayName}`,
+      optionList: lang.cliOptionDefinitions.display,
+      tableOptions,
+    });
+  }
+  // Dump
+  console.log(getUsage(sections));
+}
+
+// Node 22.18+ and 24.2+ provides `import.meta.main`, which deprecates the need for
+// this npm library. Bun and Deno have had that API for a long time already. But until
+// we're ready to drop older versions of Node, we need this library to support it.
+if (import.meta.main || esMain(import.meta)) {
+  try {
+    await main(process.argv.slice(2));
+  } catch (error) {
+    if (process.env.NEXUS_IDL_DEBUG) {
+      console.error(error);
+    } else {
+      console.error(`${error}`);
+    }
+    process.exit(1);
+  }
+}