Add docs for glob feature to README (#632)

* Fix directory creating issue with glob; reorder error cases a bit better

* Add glob feature to README

* Improve folder gen

Author: drwpow

.gitignore

@@ -1,6 +1,6 @@
 .cache
 .DS_Store
-**/generated/*.ts
+**/generated/
 coverage
 dist
 node_modules

README.md

@@ -28,20 +28,34 @@ View examples:
 ```bash
 npx openapi-typescript schema.yaml --output schema.ts
 
-# 🤞 Loading spec from tests/v2/specs/stripe.yaml…
+# 🔭 Loading spec from schema.yaml…
 # 🚀 schema.yaml -> schema.ts [250ms]
+
+npx openapi-typescript "specs/**/*.yaml" --output schemas/
+# 🔭 Loading spec from specs/one.yaml…
+# 🔭 Loading spec from specs/two.yaml…
+# 🔭 Loading spec from specs/three.yaml…
+# 🚀 specs/one.yaml -> schemas/specs/one.ts [250ms]
+# 🚀 specs/two.yaml -> schemas/specs/two.ts [250ms]
+# 🚀 specs/three.yaml -> schemas/specs/three.ts [250ms]
 ```
 
+_Note: if generating a single schema, `--output` must be a file (preferably `*.ts`). If using globs, `--output` must be a directory._
+
+_Thanks to [@sharmarajdaksh](https://github.com/sharmarajdaksh) for the glob feature!_
+
 #### ☁️ Reading specs from remote resource
 
 ```bash
 npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts
 
-# 🤞 Loading spec from https://petstore.swagger.io/v2/swagger.json…
+# 🔭 Loading spec from https://petstore.swagger.io/v2/swagger.json…
 # 🚀 https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]
 ```
 
-_Thanks to @psmyrdek for the remote spec feature!_
+_Note: for obvious reasons, globbing doesn’t work for remote schemas_
+
+_Thanks to [@psmyrdek](https://github.com/psmyrdek) for the remote spec feature!_
 
 #### Using in TypeScript
 
@@ -73,37 +87,6 @@ _Thanks to @gr2m for the operations feature!_
 npx openapi-typescript schema.yaml
 ```
 
-#### Generating multiple schemas
-
-In your `package.json`, for each schema you’d like to transform add one `generate:specs:[name]` npm-script. Then combine
-them all into one `generate:specs` script, like so:
-
-```json
-"scripts": {
-  "generate:specs": "npm run generate:specs:one && npm run generate:specs:two && npm run generate:specs:three",
-  "generate:specs:one": "npx openapi-typescript one.yaml -o one.ts",
-  "generate:specs:two": "npx openapi-typescript two.yaml -o two.ts",
-  "generate:specs:three": "npx openapi-typescript three.yaml -o three.ts"
-}
-```
-
-If you use [npm-run-all][npm-run-all], you can shorten this:
-
-```json
-"scripts": {
-  "generate:specs": "run-p generate:specs:*",
-```
-
-You can even specify unique options per-spec, if needed. To generate them all together, run:
-
-```bash
-npm run generate:specs
-```
-
-Rinse and repeat for more specs.
-
-For anything more complicated, or for generating specs dynamically, you can also use the [Node API](#node).
-
 #### CLI Options
 
 | Option                         | Alias | Default  | Description                                                                                             |

bin/cli.js

@@ -94,15 +94,14 @@ async function generateSchema(pathToSpec) {
 
   // output
   if (output === OUTPUT_FILE) {
-    let outputFile = path.resolve(process.cwd(), cli.flags.output);
-
-    // decide filename if outputFile is a directory
-    if (fs.existsSync(outputFile) && fs.lstatSync(outputFile).isDirectory()) {
-      const basename = path.basename(pathToSpec).split(".").slice(0, -1).join(".") + ".ts";
-      outputFile = path.resolve(outputFile, basename);
+    let outputFile = path.resolve(process.cwd(), cli.flags.output); // note: may be directory
+    const isDir = fs.existsSync(outputFile) && fs.lstatSync(outputFile).isDirectory();
+    if (isDir) {
+      const filename = pathToSpec.replace(new RegExp(`${path.extname(pathToSpec)}$`), ".ts");
+      outputFile = path.join(outputFile, filename);
     }
 
-    fs.writeFileSync(outputFile, result, "utf8");
+    await fs.promises.writeFile(outputFile, result, "utf8");
 
     const timeEnd = process.hrtime(timeStart);
     const time = timeEnd[0] + Math.round(timeEnd[1] / 1e6);
@@ -117,53 +116,49 @@ async function generateSchema(pathToSpec) {
 async function main() {
   const output = cli.flags.output ? OUTPUT_FILE : OUTPUT_STDOUT; // FILE or STDOUT
   const pathToSpec = cli.input[0];
-  const inputSpecPaths = await glob(pathToSpec, { filesOnly: true });
 
   if (output === OUTPUT_FILE) {
     console.info(bold(`✨ openapi-typescript ${require("../package.json").version}`)); // only log if we’re NOT writing to stdout
   }
 
+  // error: --raw-schema
   if (cli.flags.rawSchema && !cli.flags.version) {
     throw new Error(`--raw-schema requires --version flag`);
   }
 
+  // handle remote schema, exit
   if (/^https?:\/\//.test(pathToSpec)) {
-    // handle remote resource input and exit
-    return await generateSchema(pathToSpec);
+    if (output !== "." && output === OUTPUT_FILE)
+      await fs.promises.mkdir(path.dirname(cli.flags.output), { recursive: true });
+    await generateSchema(pathToSpec);
+    return;
   }
 
-  //  no matches for glob
-  if (inputSpecPaths.length === 0) {
-    errorAndExit(
-      `❌ Could not find any spec files matching the provided input path glob. Please check that the path is correct.`
-    );
-  }
-
-  if (output === OUTPUT_FILE) {
-    // recursively create parent directories if they don’t exist
-    const parentDirs = cli.flags.output.split(path.sep);
-    for (var i = 1; i < parentDirs.length; i++) {
-      const dir = path.resolve(process.cwd(), ...parentDirs.slice(0, i));
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir);
-      }
-    }
-  }
+  // handle local schema(s)
+  const inputSpecPaths = await glob(pathToSpec, { filesOnly: true });
+  const isGlob = inputSpecPaths.length > 1;
 
-  // if there are multiple specs, ensure that output is a directory
-  if (inputSpecPaths.length > 1 && output === OUTPUT_FILE && !fs.lstatSync(cli.flags.output).isDirectory()) {
-    errorAndExit(
-      `❌ When specifying a glob matching multiple input specs, you must specify a directory for generated type definitions.`
-    );
+  // error: no matches for glob
+  if (inputSpecPaths.length === 0) {
+    errorAndExit(`❌ Could not find any specs matching "${pathToSpec}". Please check that the path is correct.`);
   }
 
-  let result = "";
-  for (const specPath of inputSpecPaths) {
-    // append result returned for each spec
-    result += await generateSchema(specPath);
+  // error: tried to glob output to single file
+  if (isGlob && output === OUTPUT_FILE && fs.existsSync(cli.flags.output) && fs.lstatSync(cli.flags.output).isFile()) {
+    errorAndExit(`❌ Expected directory for --output if using glob patterns. Received "${cli.flags.output}".`);
   }
 
-  return result;
+  // generate schema(s)
+  await Promise.all(
+    inputSpecPaths.map(async (specPath) => {
+      if (cli.flags.output !== "." && output === OUTPUT_FILE) {
+        let outputDir = path.join(process.cwd(), cli.flags.output);
+        if (!isGlob) outputDir = path.dirname(outputDir); // use output dir for glob; use parent dir for single files
+        await fs.promises.mkdir(path.join(outputDir, path.dirname(specPath)), { recursive: true }); // recursively make parent dirs
+      }
+      await generateSchema(specPath);
+    })
+  );
 }
 
 main();

tests/bin/cli.test.ts

@@ -6,39 +6,45 @@ import { execSync } from "child_process";
 // v3/index.test.ts. So this file is mainly for testing other flags.
 
 describe("cli", () => {
-  it("--prettier-config (JSON)", () => {
-    const expected = fs.readFileSync(path.join(__dirname, "expected", "prettier-json.ts"), "utf8");
+  it("--prettier-config (JSON)", async () => {
     execSync(
       `../../bin/cli.js specs/petstore.yaml -o generated/prettier-json.ts --prettier-config fixtures/.prettierrc`,
       { cwd: __dirname }
     );
-    const output = fs.readFileSync(path.join(__dirname, "generated", "prettier-json.ts"), "utf8");
-    expect(output).toBe(expected);
+    const [generated, expected] = await Promise.all([
+      fs.promises.readFile(path.join(__dirname, "generated", "prettier-json.ts"), "utf8"),
+      fs.promises.readFile(path.join(__dirname, "expected", "prettier-json.ts"), "utf8"),
+    ]);
+    expect(generated).toBe(expected);
   });
 
-  it("--prettier-config (.js)", () => {
-    const expected = fs.readFileSync(path.join(__dirname, "expected", "prettier-js.ts"), "utf8");
+  it("--prettier-config (.js)", async () => {
     execSync(
       `../../bin/cli.js specs/petstore.yaml -o generated/prettier-js.ts --prettier-config fixtures/prettier.config.js`,
       { cwd: __dirname }
     );
-    const output = fs.readFileSync(path.join(__dirname, "generated", "prettier-js.ts"), "utf8");
-    expect(output).toBe(expected);
+    const [generated, expected] = await Promise.all([
+      fs.promises.readFile(path.join(__dirname, "generated", "prettier-js.ts"), "utf8"),
+      fs.promises.readFile(path.join(__dirname, "expected", "prettier-js.ts"), "utf8"),
+    ]);
+    expect(generated).toBe(expected);
   });
 
-  it("stdout", () => {
+  it("stdout", async () => {
     const expected = fs.readFileSync(path.join(__dirname, "expected", "stdout.ts"), "utf8");
-    const result = execSync(`../../bin/cli.js specs/petstore.yaml`, { cwd: __dirname });
-    expect(result.toString("utf8")).toBe(expected);
+    const generated = execSync(`../../bin/cli.js specs/petstore.yaml`, { cwd: __dirname });
+    expect(generated.toString("utf8")).toBe(expected);
   });
 
-  it("supports glob paths", () => {
-    const expectedPetstore = fs.readFileSync(path.join(__dirname, "expected", "petstore.ts"), "utf8");
-    const expectedManifold = fs.readFileSync(path.join(__dirname, "expected", "manifold.ts"), "utf8");
+  it("supports glob paths", async () => {
     execSync(`../../bin/cli.js \"specs/*.yaml\" -o generated/`, { cwd: __dirname }); // Quotes are necessary because shells like zsh treats glob weirdly
-    const outputPetstore = fs.readFileSync(path.join(__dirname, "generated", "petstore.ts"), "utf8");
-    const outputManifold = fs.readFileSync(path.join(__dirname, "generated", "manifold.ts"), "utf8");
-    expect(outputPetstore).toBe(expectedPetstore);
-    expect(outputManifold).toBe(expectedManifold);
+    const [generatedPetstore, expectedPetstore, generatedManifold, expectedManifold] = await Promise.all([
+      fs.promises.readFile(path.join(__dirname, "generated", "specs", "petstore.ts"), "utf8"),
+      fs.promises.readFile(path.join(__dirname, "expected", "petstore.ts"), "utf8"),
+      fs.promises.readFile(path.join(__dirname, "generated", "specs", "manifold.ts"), "utf8"),
+      fs.promises.readFile(path.join(__dirname, "expected", "manifold.ts"), "utf8"),
+    ]);
+    expect(generatedPetstore).toBe(expectedPetstore);
+    expect(generatedManifold).toBe(expectedManifold);
   });
 });

tests/v2/index.test.ts

@@ -1,24 +1,26 @@
 import { execSync } from "child_process";
-import { readdirSync, readFileSync } from "fs";
-import { join } from "path";
+import fs from "fs";
+import path from "path";
 
-const schemas = readdirSync(join(__dirname, "specs"));
+const schemas = fs.readdirSync(path.join(__dirname, "specs"));
 
 // simple snapshot tests with valid schemas to make sure it can generally parse & generate output
 describe("cli", () => {
   schemas.forEach((schema) => {
     const output = schema.replace(".yaml", ".ts");
 
-    it(`reads ${schema} spec (v2) from file`, () => {
+    it(`reads ${schema} spec (v2) from file`, async () => {
       execSync(`../../bin/cli.js specs/${schema} -o generated/${output} --prettier-config .prettierrc`, {
         cwd: __dirname,
       });
-      const expected = readFileSync(join(__dirname, "expected", output), "utf8");
-      const generated = readFileSync(join(__dirname, "generated", output), "utf8");
+      const [generated, expected] = await Promise.all([
+        fs.promises.readFile(path.join(__dirname, "generated", output), "utf8"),
+        fs.promises.readFile(path.join(__dirname, "expected", output), "utf8"),
+      ]);
       expect(generated).toBe(expected);
     });
 
-    it(`reads ${schema} spec (v2) from file (immutable types)`, () => {
+    it(`reads ${schema} spec (v2) from file (immutable types)`, async () => {
       const output = schema.replace(".yaml", ".immutable.ts");
 
       execSync(
@@ -28,21 +30,23 @@ describe("cli", () => {
         }
       );
 
-      const expected = readFileSync(join(__dirname, "expected", output), "utf8");
-      const generated = readFileSync(join(__dirname, "generated", output), "utf8");
+      const [generated, expected] = await Promise.all([
+        fs.promises.readFile(path.join(__dirname, "generated", output), "utf8"),
+        fs.promises.readFile(path.join(__dirname, "expected", output), "utf8"),
+      ]);
       expect(generated).toBe(expected);
     });
   });
 
-  it("reads spec (v2) from remote resource", () => {
+  it("reads spec (v2) from remote resource", async () => {
     execSync(
       "../../bin/cli.js https://raw.githubusercontent.com/drwpow/openapi-typescript/main/tests/v2/specs/manifold.yaml -o generated/http.ts",
-      {
-        cwd: __dirname,
-      }
+      { cwd: __dirname }
     );
-    const expected = readFileSync(join(__dirname, "expected", "http.ts"), "utf8");
-    const generated = readFileSync(join(__dirname, "generated", "http.ts"), "utf8");
+    const [generated, expected] = await Promise.all([
+      fs.promises.readFile(path.join(__dirname, "generated", "http.ts"), "utf8"),
+      fs.promises.readFile(path.join(__dirname, "expected", "http.ts"), "utf8"),
+    ]);
     expect(generated).toBe(expected);
   });
 });