@aligent/nx-openapi 0.1.3 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligent/nx-openapi",
-  "version": "0.1.3",
+  "version": "2.0.0",
   "type": "commonjs",
   "main": "./src/index.js",
   "typings": "./src/index.d.ts",

package/src/generators/client/client-specific-files/client.ts.template

@@ -0,0 +1,53 @@
+/**
+ * Example client demonstrating how to use the generated API types.
+ * Adjust middlewares usage according to your need.
+ *
+ * - Check out Aligent's middlewares: https://github.com/aligent/microservice-development-utilities
+ * - For more information about openapi-fetch middlewares: https://openapi-ts.dev/openapi-fetch/middleware-auth#middleware
+ */
+import {
+    apiKeyAuthMiddleware,
+    fetchSsmParams,
+    retryMiddleware,
+} from '@aligent/microservice-util-lib';
+import createClient, { Client, ClientOptions } from 'openapi-fetch';
+import { paths } from './generated-types';
+
+export class <%= className %> {
+    private credential: string | null = null;
+    public readonly client: Client<paths, `${string}/${string}`>;
+
+    constructor(options: ClientOptions, credentialPath: string) {
+        this.client = createClient<paths>(options);
+
+        /**
+         * The order in which middleware are registered matters.
+         * - For requests, onRequest() will be called in the order registered
+         * - For responses, onResponse() will be called in reverse order.
+         */
+        this.client.use(
+            apiKeyAuthMiddleware({
+                header: 'Authorization',
+                value: async () => {
+                    if (!this.credential) {
+                        const param = await fetchSsmParams(credentialPath);
+                        if (!param?.Value) {
+                            throw new Error('Unable to fetch API client credential');
+                        }
+
+                        this.credential = param.Value;
+                    }
+
+                    return `Bearer ${this.credential}`;
+                },
+            })
+        );
+
+        this.client.use(
+            retryMiddleware({
+                onRetry: ({ attempt, error }) =>
+                    console.log(`Retrying...${attempt} due to ${String(error)}`),
+            })
+        );
+    }
+}

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

@@ -1 +1,29 @@
-The <%= name %> REST API Client was generated using Nx Generators and openapi-typescript codegen
+# Generated OpenAPI REST API Clients
+
+This folder contains TypeScript API clients generated from OpenAPI specifications using Nx generators and `openapi-typescript`. Each client exposes strongly typed request and response types under `generated-types` and a ready-to-use `openapi-fetch` client class.
+
+## Usage
+- Import the generated client into your code.
+- Instantiate the client with appropriate ClientOptions (base URL, fetch implementation, etc.) and call the typed endpoints.
+
+## Example
+```typescript
+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) },
+    '/my/api/client/access-token/path'
+).client;
+
+// Example of calling a typed endpoint
+async function fetchData() {
+    try {
+        const response = await client.GET('/path/to/endpoint'); // Replace with actual endpoint method
+        console.log(response);
+    } catch (error) {
+        console.error('Error fetching data:', error);
+    }
+}
+
+fetchData();
+```

package/src/generators/client/files/eslint.config.mjs.template

@@ -0,0 +1,3 @@
+import baseConfig from '../eslint.config.mjs';
+
+export default [...baseConfig];

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/src/index.ts.template

@@ -1,22 +1 @@
-// The following is an example file generated to demonstrate how to use your newly generated types
-import { paths } from '../generated';
-import createClient from 'openapi-fetch';
-
-// This type is an example of what is initialised using the types generated in the paths interface which is created when generation occurs.
-// Its worth looking into that paths interface, to see the the types that were generated for your client.
-type ExampleResponse =
-    paths['/customers']['get']['responses']['200']['content']['application/json'];
-
-// Using openapi-fetch we can create a fully typed REST client by passing in paths as a generic.
-// If you wish however, you can use any api client you want (axios, basic fetch etc.) and use the paths separately to maintain type safety in your client.
-const client = createClient<paths>({
-    baseUrl: '',
-    signal: AbortSignal.timeout(10000),
-});
-
-// Client getters are then fully typed. Try deleting '/customers' and seeing what routes you can use!
-const response = client.GET('/customers', {
-    params: {
-        query: {},
-    },
-});
+// When a client is generated, its added as an export to this index file. This makes sure that your entire application has access to all of your clients.

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,35 +5,54 @@ 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/${name}`, skipValidate, override } = 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/${name}`;
-    const schemaDest = `${projectRoot}/schema.${ext}`;
-    const typesDest = `${projectRoot}/generated/index.ts`;
-    const isNewProject = (0, utilities_1.attemptToAddProjectConfiguration)(tree, name, projectRoot);
-    if (!isNewProject && !override) {
-        devkit_1.logger.info(`Project ${name} already exists. Use --override to override the existing schema.`);
-        return;
+    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"`);
     }
-    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}`);
-        // Generate other files
+    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);
-        // Add the project to the tsconfig paths so it can be imported by namespace
-        (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]);
+        }
     }
+    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),
+    });
+    /**
+     * 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`);
+    devkit_1.logger.info(`Next step: Run "nx affected -t lint" to fix any linting issues that may arise from the generated code.`);
 }
 exports.default = clientGenerator;

package/src/generators/client/schema.json

@@ -6,6 +6,7 @@
     "properties": {
         "name": {
             "type": "string",
+            "pattern": "^[a-z0-9-]+$",
             "description": "Name of the api client.",
             "$default": {
                 "$source": "argv",
@@ -37,7 +38,7 @@
         },
         "override": {
             "type": "boolean",
-            "description": "Override existing project schema",
+            "description": "Override existing files during generation",
             "default": false
         }
     },

package/src/helpers/generate-openapi-types.js

@@ -103,7 +103,6 @@ async function copySchema(tree, destination, schemaPath) {
 async function validateSchema(path) {
     let hasError = false;
     try {
-        // TODO: MI-203 - Support private schema endpoint
         const config = await (0, openapi_core_1.loadConfig)();
         const results = await (0, openapi_core_1.lint)({ ref: path, config });
         results.forEach(result => {

package/src/helpers/utilities.d.ts

@@ -1,26 +1,55 @@
 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 - 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 getRootTsConfigPathInTree(tree: Tree): string;
+/**
+ * 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.
  *
- * @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 {boolean} `true` if the project configuration was added successfully, `false` if the project 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 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 attemptToAddProjectConfiguration(tree: Tree, name: string, projectRoot: string): boolean;
+export declare function addTsConfigPath(tree: Tree, tsConfigFile: string, importPath: string, lookupPaths: string[]): void;
 /**
- * Adds a new path mapping to the `paths` property in the root TypeScript configuration file.
+ * 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.
  *
- * 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 referencePath - The referencing path.
+ * @throws - If the import path already exists in the `paths` property.
+ */
+export declare function addTsConfigReference(tree: Tree, tsConfigFile: string, referencePath: string): void;
+/**
+ * Appends a new export statement to the index file.
+ *
+ * This function reads the content of the index file and appends a new export statement
+ * for the specified client.
  *
  * @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 {string} clientName - The name of the client to export.
+ */
+export declare function appendToIndexFile(tree: Tree, projectRoot: string, clientName: string): void;
+/**
+ * Convert a lower-case alphanumeric string (may include hyphens) into a PascalCase string.
+ *
+ * @param input - The input string to convert.
+ * @example:
+ *  - "my-client" -> "MyClient"
  */
-export declare function addTsConfigPath(tree: Tree, importPath: string, lookupPaths: string[]): void;
+export declare function toClassName(input: string): string;

package/src/helpers/utilities.js

@@ -1,36 +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 {boolean} `true` if the project configuration was added successfully, `false` if the project 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, name, projectRoot) {
+function getExistingProject(tree, projectName) {
     try {
-        (0, devkit_1.addProjectConfiguration)(tree, name, {
-            root: projectRoot,
-            projectType: 'library',
-            sourceRoot: `${projectRoot}/src`,
-            targets: {},
-            tags: ['client', name],
-        });
-        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;
     }
 }
 /**
@@ -47,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.
- *
- * 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.
+ * 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.
  *
- * @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 ??= {};
@@ -69,3 +59,54 @@ 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.
+ *
+ * This function reads the content of the index file and appends a new export statement
+ * for the specified client.
+ *
+ * @param {Tree} tree - The file system tree representing the current project.
+ * @param {string} clientName - The name of the client to export.
+ */
+function appendToIndexFile(tree, projectRoot, clientName) {
+    const indexPath = `${projectRoot}/src/index.ts`;
+    const newLine = `export * from "./${clientName}/client";\n`;
+    const indexContent = tree.read(indexPath, 'utf-8');
+    tree.write(indexPath, indexContent + newLine);
+}
+/**
+ * Convert a lower-case alphanumeric string (may include hyphens) into a PascalCase string.
+ *
+ * @param input - The input string to convert.
+ * @example:
+ *  - "my-client" -> "MyClient"
+ */
+function toClassName(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .split('-')
+        .map(c => c.charAt(0).toUpperCase() + c.slice(1))
+        .join('');
+}

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"]
-}