@aligent/nx-openapi 1.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/nx-openapi",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "type": "commonjs",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",
@@ -10,7 +10,7 @@
     "directory": "packages/nx-openapi"
   },
   "dependencies": {
-    "@nx/devkit": "20.8.1",
+    "@nx/devkit": "22.4.1",
     "@redocly/openapi-core": "^1.34.2",
     "openapi-typescript": "7.7.3",
     "typescript": "^5.9.3"

package/src/generators/client/files/README.md.template

@@ -8,7 +8,7 @@ This folder contains TypeScript API clients generated from OpenAPI specification
 
 ## Example
 ```typescript
-import { MyApiClient } from '@clients'; // Adjust the import name as necessary
+import { MyApiClient } from 'clients'; // Adjust the import name as necessary
 
 const client = new MyApiClient(
     { baseUrl: 'https://my-api-client.base-url', signal: AbortSignal.timeout(30000) },

package/src/generators/client/files/package.json.template

@@ -0,0 +1,19 @@
+{
+  "name": "clients",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "nx": {
+    "tags": [
+      "scope:libs"
+    ]
+  }
+}

package/src/generators/client/files/tsconfig.json.template

@@ -1,19 +1,6 @@
 {
-    "extends": "../tsconfig.base.json",
-    "compilerOptions": {
-        "forceConsistentCasingInFileNames": true,
-        "strict": true,
-        "importHelpers": true,
-        "noImplicitOverride": true,
-        "noImplicitReturns": true,
-        "noFallthroughCasesInSwitch": true,
-        "noPropertyAccessFromIndexSignature": true
-    },
+    "extends": "@aligent/ts-code-standards/tsconfigs-extend",
     "files": [],
     "include": [],
-    "references": [
-        {
-            "path": "./tsconfig.lib.json"
-        }
-    ]
+    "references": []
 }

package/src/generators/client/generator.js

@@ -5,38 +5,51 @@ const devkit_1 = require("@nx/devkit");
 const generate_openapi_types_1 = require("../../helpers/generate-openapi-types");
 const utilities_1 = require("../../helpers/utilities");
 const VALID_EXTENSIONS = ['yaml', 'yml', 'json'];
+// We also use this as the project root for all generated clients
+const PROJECT_NAME = 'clients';
 async function clientGenerator(tree, options) {
     const { name, schemaPath, importPath = `@clients`, skipValidate, override } = options;
     const ext = schemaPath.split('.').pop() || '';
     if (!VALID_EXTENSIONS.includes(ext)) {
         throw new Error(`Invalid schema file extension: ${ext}`);
     }
-    if (!skipValidate) {
-        const hasError = await (0, generate_openapi_types_1.validateSchema)(schemaPath);
-        if (hasError) {
-            throw new Error('Schema validation failed!');
-        }
+    const hasError = await (0, generate_openapi_types_1.validateSchema)(schemaPath);
+    if (!skipValidate && hasError) {
+        throw new Error('Schema validation failed!');
     }
-    const projectRoot = `clients`;
+    const projectRoot = PROJECT_NAME;
     const apiClientDest = `${projectRoot}/src/${name}`;
     const schemaDest = `${apiClientDest}/schema.${ext}`;
     const typesDest = `${apiClientDest}/generated-types.ts`;
     if (!override && tree.exists(apiClientDest)) {
         throw new Error(`Directory "${name}" already exists. If you want to override the current api client in this directory use "--override"`);
     }
-    const isNewProject = (0, utilities_1.attemptToAddProjectConfiguration)(tree, projectRoot);
-    await (0, generate_openapi_types_1.copySchema)(tree, schemaDest, schemaPath);
-    await (0, generate_openapi_types_1.generateOpenApiTypes)(tree, schemaDest, typesDest);
-    if (isNewProject) {
-        devkit_1.logger.info(`Creating new project at ${projectRoot}`);
+    const existingProject = (0, utilities_1.getExistingProject)(tree, PROJECT_NAME);
+    if (!existingProject) {
+        devkit_1.logger.warn(`Creating new project ${PROJECT_NAME} at ${projectRoot}`);
         (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, './files'), projectRoot, options);
-        (0, utilities_1.addTsConfigPath)(tree, importPath, [(0, devkit_1.joinPathFragments)(projectRoot, './src', 'index.ts')]);
+        const tsConfigFile = (0, utilities_1.getRootTsConfigPathInTree)(tree);
+        if (tsConfigFile === 'tsconfig.json') {
+            (0, utilities_1.addTsConfigReference)(tree, tsConfigFile, `./${projectRoot}`);
+        }
+        else {
+            const lookupPath = (0, devkit_1.joinPathFragments)(projectRoot, './src', 'index.ts');
+            (0, utilities_1.addTsConfigPath)(tree, tsConfigFile, importPath, [lookupPath]);
+        }
     }
-    // Generate the files for the specific new client
+    await (0, generate_openapi_types_1.copySchema)(tree, schemaDest, schemaPath);
+    await (0, generate_openapi_types_1.generateOpenApiTypes)(tree, schemaDest, typesDest);
+    /**
+     * Each time we add new API client, we actually add a new class into `clients` project (if it exists).
+     * This add a new example client class to `apiClientDest` folder
+     */
     (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, './client-specific-files'), apiClientDest, {
         className: (0, utilities_1.toClassName)(name),
     });
-    // Append to index file for imports
+    /**
+     * The `clients` project expose all the API clients via `src/index.ts` file.
+     * As a result, we need to append new client to the list of exporting;
+     */
     (0, utilities_1.appendToIndexFile)(tree, projectRoot, name);
     await (0, devkit_1.formatFiles)(tree);
     devkit_1.logger.info(`Successfully generated ${name} API client`);

package/src/helpers/utilities.d.ts

@@ -1,29 +1,40 @@
 import { Tree } from '@nx/devkit';
 /**
- * Attempts to add a new project configuration to the workspace.
+ * Get existing project by name.
+ * If the project exists, it returns project configuration or undefined otherwise.
  *
- * This function adds a new project configuration to the workspace. If a project with the same name
- * already exists, it returns `false`. If an error occurs for any other reason, the error is re-thrown.
- *
- * @param {Tree} tree - The file system tree representing the current project.
- * @param {string} name - The name of the project to add.
- * @param {string} projectRoot - The root directory of the project.
- * @returns - Whether project configuration was added successfully, or it already exists.
- * @throws {Error} If an error occurs that is not related to the project already existing.
+ * @param tree - The file system tree representing the current project.
+ * @param projectName - The name of the project to add.
+ * @returns - The project configuration.
+ */
+export declare function getExistingProject(tree: Tree, projectName: string): import("@nx/devkit").ProjectConfiguration | undefined;
+/**
+ * The utility functions below are only exported by '@nx/js', not '@nx/devkit'
+ * They're simple so we recreate them here instead of adding '@nx/js' as a dependency
+ * Source: {@link https://github.com/nrwl/nx/blob/master/packages/js/src/utils/typescript/ts-config.ts}
  */
-export declare function attemptToAddProjectConfiguration(tree: Tree, projectRoot: string): boolean;
+export declare function getRootTsConfigPathInTree(tree: Tree): string;
 /**
- * Adds a new path mapping to the `paths` property in the root TypeScript configuration file.
+ * Adds a new path mapping to the `compilerOptions.paths` property in the root TypeScript configuration file.
+ * If the import path already exists, an error is thrown.
  *
- * This function updates the `tsconfig.base.json` or `tsconfig.json` file to include a new path mapping
- * for the specified import path. If the import path already exists, an error is thrown.
+ * @param tree - The file system tree representing the current project.
+ * @param tsConfigFile - The root TypeScript configuration file path.
+ * @param importPath - The import path to add to the `paths` property.
+ * @param lookupPaths - The array of paths to associate with the import path.
+ * @throws - If the import path already exists in the `paths` property.
+ */
+export declare function addTsConfigPath(tree: Tree, tsConfigFile: string, importPath: string, lookupPaths: string[]): void;
+/**
+ * Adds a new referencing path to the `references` property in the root TypeScript configuration file.
+ * If the referencing path already exists, an error is thrown.
  *
- * @param {Tree} tree - The file system tree representing the current project.
- * @param {string} importPath - The import path to add to the `paths` property.
- * @param {string[]} lookupPaths - The array of paths to associate with the import path.
- * @throws {Error} If the import path already exists in the `paths` property.
+ * @param tree - The file system tree representing the current project.
+ * @param tsConfigFile - The root TypeScript configuration file path.
+ * @param referencePath - The referencing path.
+ * @throws - If the import path already exists in the `paths` property.
  */
-export declare function addTsConfigPath(tree: Tree, importPath: string, lookupPaths: string[]): void;
+export declare function addTsConfigReference(tree: Tree, tsConfigFile: string, referencePath: string): void;
 /**
  * Appends a new export statement to the index file.
  *

package/src/helpers/utilities.js

@@ -1,38 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.attemptToAddProjectConfiguration = attemptToAddProjectConfiguration;
+exports.getExistingProject = getExistingProject;
+exports.getRootTsConfigPathInTree = getRootTsConfigPathInTree;
 exports.addTsConfigPath = addTsConfigPath;
+exports.addTsConfigReference = addTsConfigReference;
 exports.appendToIndexFile = appendToIndexFile;
 exports.toClassName = toClassName;
 const devkit_1 = require("@nx/devkit");
 /**
- * Attempts to add a new project configuration to the workspace.
+ * Get existing project by name.
+ * If the project exists, it returns project configuration or undefined otherwise.
  *
- * This function adds a new project configuration to the workspace. If a project with the same name
- * already exists, it returns `false`. If an error occurs for any other reason, the error is re-thrown.
- *
- * @param {Tree} tree - The file system tree representing the current project.
- * @param {string} name - The name of the project to add.
- * @param {string} projectRoot - The root directory of the project.
- * @returns - Whether project configuration was added successfully, or it already exists.
- * @throws {Error} If an error occurs that is not related to the project already existing.
+ * @param tree - The file system tree representing the current project.
+ * @param projectName - The name of the project to add.
+ * @returns - The project configuration.
  */
-function attemptToAddProjectConfiguration(tree, projectRoot) {
+function getExistingProject(tree, projectName) {
     try {
-        (0, devkit_1.addProjectConfiguration)(tree, 'clients', {
-            root: projectRoot,
-            projectType: 'library',
-            sourceRoot: `${projectRoot}/src`,
-            targets: {},
-            tags: ['clients'],
-        });
-        return true;
+        return (0, devkit_1.readProjectConfiguration)(tree, projectName);
     }
-    catch (err) {
-        if (err instanceof Error && err.message.includes('already exists')) {
-            return false;
-        }
-        throw err;
+    catch (error) {
+        devkit_1.logger.debug(`Project ${projectName} doesn't exist`, String(error));
+        return undefined;
     }
 }
 /**
@@ -49,18 +38,17 @@ function getRootTsConfigPathInTree(tree) {
     return 'tsconfig.base.json';
 }
 /**
- * Adds a new path mapping to the `paths` property in the root TypeScript configuration file.
+ * Adds a new path mapping to the `compilerOptions.paths` property in the root TypeScript configuration file.
+ * If the import path already exists, an error is thrown.
  *
- * This function updates the `tsconfig.base.json` or `tsconfig.json` file to include a new path mapping
- * for the specified import path. If the import path already exists, an error is thrown.
- *
- * @param {Tree} tree - The file system tree representing the current project.
- * @param {string} importPath - The import path to add to the `paths` property.
- * @param {string[]} lookupPaths - The array of paths to associate with the import path.
- * @throws {Error} If the import path already exists in the `paths` property.
+ * @param tree - The file system tree representing the current project.
+ * @param tsConfigFile - The root TypeScript configuration file path.
+ * @param importPath - The import path to add to the `paths` property.
+ * @param lookupPaths - The array of paths to associate with the import path.
+ * @throws - If the import path already exists in the `paths` property.
  */
-function addTsConfigPath(tree, importPath, lookupPaths) {
-    (0, devkit_1.updateJson)(tree, getRootTsConfigPathInTree(tree), json => {
+function addTsConfigPath(tree, tsConfigFile, importPath, lookupPaths) {
+    (0, devkit_1.updateJson)(tree, tsConfigFile, json => {
         json.compilerOptions ??= {};
         const c = json.compilerOptions;
         c.paths ??= {};
@@ -71,6 +59,27 @@ function addTsConfigPath(tree, importPath, lookupPaths) {
         return json;
     });
 }
+/**
+ * Adds a new referencing path to the `references` property in the root TypeScript configuration file.
+ * If the referencing path already exists, an error is thrown.
+ *
+ * @param tree - The file system tree representing the current project.
+ * @param tsConfigFile - The root TypeScript configuration file path.
+ * @param referencePath - The referencing path.
+ * @throws - If the import path already exists in the `paths` property.
+ */
+function addTsConfigReference(tree, tsConfigFile, referencePath) {
+    (0, devkit_1.updateJson)(tree, tsConfigFile, json => {
+        json.references ??= [];
+        if (json.references.some((r) => r.path === referencePath)) {
+            throw new Error(`You already have a library using the import path "${referencePath}". Make sure to specify a unique one.`);
+        }
+        json.references.push({
+            path: referencePath,
+        });
+        return json;
+    });
+}
 /**
  * Appends a new export statement to the index file.
  *

package/src/generators/client/files/tsconfig.lib.json.template

@@ -1,9 +0,0 @@
-{
-    "extends": "./tsconfig.json",
-    "compilerOptions": {
-        "outDir": "../../dist/out-tsc",
-        "declaration": true,
-        "types": ["node"]
-    },
-    "include": ["src/**/*.ts"]
-}