@opra/cli 1.26.2 → 1.26.4

package/README.md

@@ -1,3 +1,126 @@
-# @opra/node-client
+# @opra/cli
 
-OPRA NodeJS Client
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][downloads-url]
+[![CI Tests][ci-test-image]][ci-test-url]
+[![Test Coverage][coveralls-image]][coveralls-url]
+
+`@opra/cli` is a command-line tool for OPRA (Open Protocol for Restfull APIs). It currently features `oprimp`, a
+TypeScript code generator that creates client-side models and API services from an OPRA service.
+
+## Installation
+
+You can install `@opra/cli` globally or as a development dependency in your project.
+
+### Global Installation
+
+```bash
+npm install -g @opra/cli
+```
+
+### Local Installation
+
+```bash
+npm install --save-dev @opra/cli
+```
+
+## CLI Usage: oprimp
+
+The `oprimp` tool generates TypeScript code from an OPRA service URL.
+
+```bash
+oprimp <serviceUrl> <outDir> [options]
+```
+
+### Arguments
+
+- `serviceUrl`: The URL of the OPRA service (e.g., `http://localhost:3000/opra`).
+- `outDir`: The output directory where the generated files will be saved.
+
+### Options
+
+- `--ext`: Adds `.js` extension to imports. This is useful for ESM projects.
+- `--refns`: Exports referenced API documentation with namespaces.
+- `--no-color`: Disables colors in log messages.
+- `-v, --version`: Displays the version number.
+- `-h, --help`: Displays help information.
+
+### Examples
+
+#### Basic Usage
+
+Generate TypeScript code from a local OPRA service:
+
+```bash
+npx oprimp http://localhost:3000/opra ./src/generated
+```
+
+#### ESM Projects
+
+If your project uses ESM and requires file extensions in imports:
+
+```bash
+npx oprimp http://localhost:3000/opra ./src/generated --ext
+```
+
+## Programmatic Usage
+
+You can also use the `TsGenerator` class programmatically in your scripts.
+
+```typescript
+import { TsGenerator } from '@opra/cli';
+
+async function generate() {
+  const generator = new TsGenerator({
+    serviceUrl: 'http://localhost:3000/opra',
+    outDir: './src/generated',
+    importExt: true, // Optional: add .js extensions
+    fileHeader: '/* Generated by OPRA */', // Optional: add a header to files
+  });
+
+  await generator.generate();
+  console.log('Generation completed!');
+}
+
+generate().catch(console.error);
+```
+
+### TsGenerator Options
+
+| Option                | Type      | Description                                                    |
+|-----------------------|-----------|----------------------------------------------------------------|
+| `serviceUrl`          | `string`  | **Required**. The URL of the OPRA service.                     |
+| `outDir`              | `string`  | **Required**. The output directory for the generated files.    |
+| `cwd`                 | `string`  | The current working directory. Defaults to `process.cwd()`.    |
+| `logger`              | `ILogger` | Logger instance for outputting information.                    |
+| `fileHeader`          | `string`  | Optional header text to add to the top of each generated file. |
+| `importExt`           | `boolean` | Whether to add `.js` extension to imports.                     |
+| `referenceNamespaces` | `boolean` | Whether to export references with namespaces.                  |
+
+## Support
+
+You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+
+## Node Compatibility
+
+- node >= 20.x
+
+## License
+
+Available under [MIT](LICENSE) license.
+
+[npm-image]: https://img.shields.io/npm/v/@opra/cli
+
+[npm-url]: https://npmjs.org/package/@opra/cli
+
+[downloads-image]: https://img.shields.io/npm/dm/@opra/cli.svg
+
+[downloads-url]: https://npmjs.org/package/@opra/cli
+
+[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg
+
+[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml
+
+[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=main
+
+[coveralls-url]: https://coveralls.io/github/panates/opra?branch=main

package/code-block.d.ts

@@ -1,5 +1,15 @@
+/**
+ * CodeBlock
+ *
+ * A class representing a block of code, which can be composed of multiple segments.
+ */
 export declare class CodeBlock {
     [index: string]: any;
+    /**
+     * Concatenates all segments of the code block into a single string.
+     *
+     * @returns The full code as a string.
+     */
     toString(): string;
     [Symbol.toStringTag](): string;
 }

package/code-block.js

@@ -1,4 +1,14 @@
+/**
+ * CodeBlock
+ *
+ * A class representing a block of code, which can be composed of multiple segments.
+ */
 export class CodeBlock {
+    /**
+     * Concatenates all segments of the code block into a single string.
+     *
+     * @returns The full code as a string.
+     */
     toString() {
         // if (this.content) return this.content;
         let out = '';

package/file-writer.d.ts

@@ -1,4 +1,15 @@
 import type { IFileWriter } from './interfaces/file-writer.interface.js';
+/**
+ * FileWriter
+ *
+ * Implementation of IFileWriter that uses node:fs to write files.
+ */
 export declare class FileWriter implements IFileWriter {
+    /**
+     * Writes contents to a file.
+     *
+     * @param filename - The path to the file to write.
+     * @param contents - The string content to write to the file.
+     */
     writeFile(filename: string, contents: string): void;
 }

package/file-writer.js

@@ -1,5 +1,16 @@
 import fs from 'node:fs';
+/**
+ * FileWriter
+ *
+ * Implementation of IFileWriter that uses node:fs to write files.
+ */
 export class FileWriter {
+    /**
+     * Writes contents to a file.
+     *
+     * @param filename - The path to the file to write.
+     * @param contents - The string content to write to the file.
+     */
     writeFile(filename, contents) {
         fs.writeFileSync(filename, contents, 'utf-8');
     }

package/interfaces/file-writer.interface.d.ts

@@ -1,3 +1,15 @@
+/**
+ * IFileWriter
+ *
+ * Interface for file writing operations.
+ */
 export interface IFileWriter {
+    /**
+     * Writes contents to a file.
+     *
+     * @param filename - The path to the file to write.
+     * @param contents - The string content to write to the file.
+     * @returns A promise that resolves when the file is written, or void if synchronous.
+     */
     writeFile(filename: string, contents: string): Promise<void> | void;
 }

package/interfaces/logger.interface.d.ts

@@ -1,7 +1,42 @@
+/**
+ * ILogger
+ *
+ * Interface for logging operations within the CLI.
+ */
 export interface ILogger {
+    /**
+     * Logs a general message.
+     *
+     * @param message - The message to log.
+     * @param optionalParams - Additional parameters for the log message.
+     */
     log(message: any, ...optionalParams: any[]): any;
+    /**
+     * Logs an error message.
+     *
+     * @param message - The error message to log.
+     * @param optionalParams - Additional parameters for the error message.
+     */
     error(message: any, ...optionalParams: any[]): any;
+    /**
+     * Logs a warning message.
+     *
+     * @param message - The warning message to log.
+     * @param optionalParams - Additional parameters for the warning message.
+     */
     warn(message: any, ...optionalParams: any[]): any;
+    /**
+     * Logs a debug message.
+     *
+     * @param message - The debug message to log.
+     * @param optionalParams - Additional parameters for the debug message.
+     */
     debug?(message: any, ...optionalParams: any[]): any;
+    /**
+     * Logs a verbose message.
+     *
+     * @param message - The verbose message to log.
+     * @param optionalParams - Additional parameters for the verbose message.
+     */
     verbose?(message: any, ...optionalParams: any[]): any;
 }

package/oprimp-cli.js

@@ -15,7 +15,7 @@ program
     .argument('<serviceUrl>', 'OPRA service url')
     .argument('<outDir>', 'Output directory')
     .option('--ext', 'Adds js extension to imports')
-    .option('--refns', 'Exports references with namespaces')
+    .option('--refns', 'Exports referenced API documentation with namespaces')
     .option('--no-color', 'Disables colors in logs messages')
     .action(async (serviceUrl, outDir, options) => {
     if (!options.color)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opra/cli",
-  "version": "1.26.2",
+  "version": "1.26.4",
   "description": "Opra CLI tools",
   "author": "Panates",
   "license": "MIT",
@@ -15,8 +15,8 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@opra/client": "^1.26.2",
-    "@opra/common": "^1.26.2"
+    "@opra/client": "^1.26.4",
+    "@opra/common": "^1.26.4"
   },
   "type": "module",
   "module": "./index.js",

package/ts-generator/generators/clean-directory.d.ts

@@ -1,2 +1,7 @@
 import type { TsGenerator } from '../ts-generator.js';
+/**
+ * Cleans the output directory.
+ *
+ * @param dirname - The directory to clean.
+ */
 export declare function cleanDirectory(this: TsGenerator, dirname: string): void;

package/ts-generator/generators/clean-directory.js

@@ -1,6 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import colors from 'ansi-colors';
+/**
+ * Cleans the output directory.
+ *
+ * @param dirname - The directory to clean.
+ */
 export function cleanDirectory(dirname) {
     const rootDir = dirname;
     const _cleanDirectory = (targetDir) => {

package/ts-generator/generators/generate-data-type.d.ts

@@ -14,37 +14,89 @@ export type generateDataTypeResult = {
     kind: 'embedded';
     code: string;
 };
+/**
+ * Generates TypeScript code for a given data type.
+ *
+ * @param dataType - The data type to generate code for.
+ * @param intent - The generation intent (root, extends, typeDef).
+ * @param currentFile - The current file being generated.
+ * @returns A promise that resolves to the generation result.
+ * @throws {@link TypeError} If currentFile is not provided for embedded generation.
+ */
 export declare function generateDataType(this: TsGenerator, dataType: DataType, intent: Intent, currentFile?: TsFile): Promise<generateDataTypeResult>;
 /**
+ * Generates the TypeScript type definition for a data type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The data type to generate code for.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
+ * @throws {@link TypeError} If name is required but not provided.
  */
 export declare function _generateTypeCode(this: TsGenerator, currentFile: TsFile, dataType: DataType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 /**
+ * Generates code for an array type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The array data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
+ * @throws {@link TypeError} If array type is attempted to be extended.
  */
 export declare function _generateArrayTypeCode(this: TsGenerator, currentFile: TsFile, dataType: ArrayType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 /**
+ * Generates code for a complex type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The complex data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export declare function _generateComplexTypeCode(this: TsGenerator, currentFile: TsFile, dataType: ComplexType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 /**
+ * Generates code for an enum type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The enum data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export declare function _generateEnumTypeCode(this: TsGenerator, currentFile: TsFile, dataType: EnumType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 /**
+ * Generates code for a mapped type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The mapped data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export declare function _generateMappedTypeCode(this: TsGenerator, currentFile: TsFile, dataType: MappedType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 /**
+ * Generates code for a mixin type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The mixin data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export declare function _generateMixinTypeCode(this: TsGenerator, currentFile: TsFile, dataType: MixinType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 /**
+ * Generates code for a simple type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The simple data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export declare function _generateSimpleTypeCode(this: TsGenerator, currentFile: TsFile, dataType: SimpleType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 /**
+ * Generates code for a union type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The union data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
+ * @throws {@link TypeError} If union type is attempted to be extended.
  */
 export declare function _generateUnionTypeCode(this: TsGenerator, currentFile: TsFile, dataType: UnionType, codeBlock: CodeBlock, intent?: Intent): Promise<void>;
 export {};

package/ts-generator/generators/generate-data-type.js

@@ -12,6 +12,15 @@ const internalTypeNames = [
     'string',
     'object',
 ];
+/**
+ * Generates TypeScript code for a given data type.
+ *
+ * @param dataType - The data type to generate code for.
+ * @param intent - The generation intent (root, extends, typeDef).
+ * @param currentFile - The current file being generated.
+ * @returns A promise that resolves to the generation result.
+ * @throws {@link TypeError} If currentFile is not provided for embedded generation.
+ */
 export async function generateDataType(dataType, intent, currentFile) {
     const doc = dataType.node.getDocument();
     if (doc.id !== this._document?.id) {
@@ -24,7 +33,7 @@ export async function generateDataType(dataType, intent, currentFile) {
             if (dataType instanceof ComplexType &&
                 dataType.ctor === OperationResult) {
                 if (currentFile)
-                    currentFile.addImport('@opra/common', [typeName]);
+                    currentFile.addImport('@opra/common', [typeName], true);
                 return { kind: 'internal', typeName: dataType.name };
             }
             if (internalTypeNames.includes(typeName))
@@ -32,7 +41,7 @@ export async function generateDataType(dataType, intent, currentFile) {
             let file = this._filesMap.get(dataType);
             if (file) {
                 if (currentFile)
-                    currentFile.addImport(file.filename, [typeName]);
+                    currentFile.addImport(file.filename, [typeName], true);
                 return { kind: 'named', file, typeName: dataType.name };
             }
             if (dataType instanceof SimpleType)
@@ -45,7 +54,7 @@ export async function generateDataType(dataType, intent, currentFile) {
             this._filesMap.set(dataType, file);
             if (file.exportTypes.includes(typeName)) {
                 if (currentFile)
-                    currentFile.addImport(file.filename, [typeName]);
+                    currentFile.addImport(file.filename, [typeName], true);
                 return { kind: 'named', file, typeName: dataType.name };
             }
             file.exportTypes.push(typeName);
@@ -62,7 +71,7 @@ export async function generateDataType(dataType, intent, currentFile) {
             codeBlock.type_end = '\n\n';
             typesIndexTs.addExport(file.filename);
             if (currentFile)
-                currentFile.addImport(file.filename, [typeName]);
+                currentFile.addImport(file.filename, [typeName], true);
             return { kind: 'named', file, typeName };
         }
         if (!currentFile)
@@ -77,7 +86,13 @@ export async function generateDataType(dataType, intent, currentFile) {
     }
 }
 /**
+ * Generates the TypeScript type definition for a data type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The data type to generate code for.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
+ * @throws {@link TypeError} If name is required but not provided.
  */
 export async function _generateTypeCode(currentFile, dataType, codeBlock, intent) {
     if (intent === 'root' && !dataType.name) {
@@ -110,7 +125,13 @@ export async function _generateTypeCode(currentFile, dataType, codeBlock, intent
     throw new TypeError(`${dataType.kind} data types can not be directly exported`);
 }
 /**
+ * Generates code for an array type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The array data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
+ * @throws {@link TypeError} If array type is attempted to be extended.
  */
 export async function _generateArrayTypeCode(currentFile, dataType, codeBlock, intent) {
     if (intent === 'extends')
@@ -129,7 +150,12 @@ export async function _generateArrayTypeCode(currentFile, dataType, codeBlock, i
         intent === 'root' ? `type ${dataType.name} = ${out}[]` : `${out}[]`;
 }
 /**
+ * Generates code for a complex type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The complex data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export async function _generateComplexTypeCode(currentFile, dataType, codeBlock, intent) {
     let out = intent === 'root' ? `interface ${dataType.name} ` : '';
@@ -214,7 +240,12 @@ export async function _generateComplexTypeCode(currentFile, dataType, codeBlock,
     codeBlock.typeDef = out + '\b}';
 }
 /**
+ * Generates code for an enum type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The enum data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export async function _generateEnumTypeCode(currentFile, dataType, codeBlock, intent) {
     if (intent === 'root') {
@@ -244,7 +275,12 @@ export async function _generateEnumTypeCode(currentFile, dataType, codeBlock, in
             ')';
 }
 /**
+ * Generates code for a mapped type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The mapped data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export async function _generateMappedTypeCode(currentFile, dataType, codeBlock, intent) {
     let out = intent === 'root' ? `type ${dataType.name} = ` : '';
@@ -304,7 +340,12 @@ export async function _generateMappedTypeCode(currentFile, dataType, codeBlock,
     codeBlock.typeDef = out;
 }
 /**
+ * Generates code for a mixin type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The mixin data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export async function _generateMixinTypeCode(currentFile, dataType, codeBlock, intent) {
     const outArray = [];
@@ -328,7 +369,12 @@ export async function _generateMixinTypeCode(currentFile, dataType, codeBlock, i
         codeBlock.typeDef = outArray.join(' & ');
 }
 /**
+ * Generates code for a simple type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The simple data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
  */
 export async function _generateSimpleTypeCode(currentFile, dataType, codeBlock, intent) {
     if (intent !== 'typeDef' && dataType.properties) {
@@ -343,7 +389,13 @@ export async function _generateSimpleTypeCode(currentFile, dataType, codeBlock,
     codeBlock.typeDef = intent === 'root' ? out + ';' : out;
 }
 /**
+ * Generates code for a union type.
  *
+ * @param currentFile - The current file being generated.
+ * @param dataType - The union data type.
+ * @param codeBlock - The code block to add the generated code to.
+ * @param intent - The generation intent.
+ * @throws {@link TypeError} If union type is attempted to be extended.
  */
 export async function _generateUnionTypeCode(currentFile, dataType, codeBlock, intent) {
     if (intent === 'extends')

package/ts-generator/generators/generate-document.d.ts

@@ -1,5 +1,12 @@
 import { ApiDocument } from '@opra/common';
 import type { TsGenerator } from '../ts-generator.js';
+/**
+ * Generates the document and its references.
+ *
+ * @param document - The document to generate.
+ * @param options - Generation options.
+ * @returns An object containing the generated document and its generator.
+ */
 export declare function generateDocument(this: TsGenerator, document?: string | ApiDocument, options?: {
     typesOnly?: boolean;
 }): Promise<{

package/ts-generator/generators/generate-document.js

@@ -3,6 +3,13 @@ import { OpraHttpClient } from '@opra/client';
 import { BUILTIN, HttpApi } from '@opra/common';
 import colors from 'ansi-colors';
 import { pascalCase } from 'putil-varhelpers';
+/**
+ * Generates the document and its references.
+ *
+ * @param document - The document to generate.
+ * @param options - Generation options.
+ * @returns An object containing the generated document and its generator.
+ */
 export async function generateDocument(document, options) {
     if (!document || typeof document === 'string') {
         if (document) {

package/ts-generator/generators/generate-http-api.d.ts

@@ -1,3 +1,9 @@
 import { HttpApi } from '@opra/common';
 import type { TsGenerator } from '../ts-generator.js';
+/**
+ * Generates TypeScript code for an HTTP API.
+ *
+ * @param api - The HTTP API to generate code for.
+ * @returns A promise that resolves to the generated TsFile.
+ */
 export declare function generateHttpApi(this: TsGenerator, api: HttpApi): Promise<import("../ts-file.js").TsFile>;

package/ts-generator/generators/generate-http-api.js

@@ -3,6 +3,12 @@ import { camelCase, pascalCase } from 'putil-varhelpers';
 import { CodeBlock } from '../../code-block.js';
 import { httpControllerNodeScript } from '../http-controller-node.js';
 import { wrapJSDocString } from '../utils/string-utils.js';
+/**
+ * Generates TypeScript code for an HTTP API.
+ *
+ * @param api - The HTTP API to generate code for.
+ * @returns A promise that resolves to the generated TsFile.
+ */
 export async function generateHttpApi(api) {
     let file = this._filesMap.get(api);
     if (file)

package/ts-generator/generators/generate-http-controller.d.ts

@@ -1,3 +1,9 @@
 import { HttpController } from '@opra/common';
 import type { TsGenerator } from '../ts-generator.js';
+/**
+ * Generates TypeScript code for an HTTP controller.
+ *
+ * @param controller - The HTTP controller to generate code for.
+ * @returns A promise that resolves to the generated TsFile.
+ */
 export declare function generateHttpController(this: TsGenerator, controller: HttpController): Promise<import("../ts-file.js").TsFile>;

package/ts-generator/generators/generate-http-controller.js

@@ -5,21 +5,26 @@ import { camelCase, pascalCase } from 'putil-varhelpers';
 import { CodeBlock } from '../../code-block.js';
 import { locateNamedType } from '../utils/locate-named-type.js';
 import { wrapJSDocString } from '../utils/string-utils.js';
+/**
+ * Generates TypeScript code for an HTTP controller.
+ *
+ * @param controller - The HTTP controller to generate code for.
+ * @returns A promise that resolves to the generated TsFile.
+ */
 export async function generateHttpController(controller) {
     let file = this._filesMap.get(controller);
     if (file)
         return file;
+    /**
+     * Generates parameter documentation for JSDoc.
+     *
+     * @param name - The name of the parameter.
+     * @param type - The data type of the parameter.
+     * @param options - Additional options for the parameter.
+     * @returns A promise that resolves to the documentation string.
+     */
     const generateParamDoc = async (name, type, options) => {
-        let typeDef;
-        if (type) {
-            const xt = await this.generateDataType(type, 'typeDef', file);
-            typeDef = xt.kind === 'embedded' ? 'object' : xt.typeName;
-        }
-        else
-            typeDef = 'any';
-        if (options?.isArray)
-            typeDef += '[]';
-        let out = `\n * @param {${typeDef}} ` + (options?.required ? name : `[${name}]`);
+        let out = `\n * @param - ` + (options?.required ? name : `[${name}]`);
         if (options?.description)
             out += `  - ${wrapJSDocString(options?.description)}`;
         if (type instanceof ComplexType && type.embedded) {
@@ -49,8 +54,7 @@ export async function generateHttpController(controller) {
     classBlock.properties = '';
     const classConstBlock = (classBlock.classConstBlock = new CodeBlock());
     classConstBlock.head = `\n/**
- * @param {OpraHttpClient} client - OpraHttpClient instance to operate
- * @constructor
+ * @param client - OpraHttpClient instance to operate
  */  
 constructor(client: OpraHttpClient) {`;
     classConstBlock.body = `\n\tsuper(client);`;
@@ -69,7 +73,7 @@ constructor(client: OpraHttpClient) {`;
             classConstBlock.body += `\nthis.${property} = new ${childClassName}(client);`;
         }
     }
-    /** Process operations */
+    /* Process operations */
     const mergedControllerParams = [...controller.parameters];
     let _base = controller;
     while (_base.owner instanceof HttpController) {
@@ -107,7 +111,7 @@ constructor(client: OpraHttpClient) {`;
  * @apiUrl ${path.posix.join(this.serviceUrl, operation.getFullUrl())}    
  */\n`;
         operationBlock.head = `${operation.name}(`;
-        /** Process operation parameters */
+        /* Process operation parameters */
         const pathParams = [];
         const queryParams = [];
         const headerParams = [];
@@ -129,7 +133,7 @@ constructor(client: OpraHttpClient) {`;
             queryParams.push(...Object.values(queryParamsMap));
             headerParams.push(...Object.values(headerParamsMap));
         }
-        /** Process path parameters and add as function arguments */
+        /* Process path parameters and add as function arguments */
         let argIndex = 0;
         for (const prm of pathParams) {
             let typeDef;
@@ -145,11 +149,11 @@ constructor(client: OpraHttpClient) {`;
                 operationBlock.head += ', ';
             operationBlock.head += `${prm.name}: ${typeDef}`;
             operationBlock.doc.parameters +=
-                `\n * @param {${typeDef}} ` +
+                `\n * @param ` +
                     (prm.required ? prm.name : `[${prm.name}]`) +
                     (prm.description ? ' - ' + wrapJSDocString(prm.description || '') : '');
         }
-        /** Process requestBody and add as function argument ($body) */
+        /* Process requestBody and add as function argument ($body) */
         let hasBody = false;
         if (operation.requestBody?.content.length) {
             if (argIndex++ > 0)
@@ -157,12 +161,11 @@ constructor(client: OpraHttpClient) {`;
             let typeArr = [];
             for (const content of operation.requestBody.content) {
                 if (content.type) {
-                    /** Generate JSDoc for parameter */
+                    /* Generate JSDoc for parameter */
                     operationBlock.doc.parameters += await generateParamDoc('$body', content.type, {
                         required: operation.requestBody.required,
                         description: content.description || content.type.description,
                     });
-                    /**  */
                     const xt = await this.generateDataType(content.type, 'typeDef', file);
                     let typeDef = xt.kind === 'embedded' ? xt.code : xt.typeName;
                     if (typeDef === 'any') {
@@ -171,11 +174,11 @@ constructor(client: OpraHttpClient) {`;
                     }
                     if (xt.kind === 'named') {
                         if (operation.requestBody.partial) {
-                            file.addImport('ts-gems', ['PartialDTO']);
+                            file.addImport('ts-gems', ['PartialDTO'], true);
                             typeDef = `PartialDTO<${typeDef}>`;
                         }
                         else {
-                            file.addImport('ts-gems', ['DTO']);
+                            file.addImport('ts-gems', ['DTO'], true);
                             typeDef = `DTO<${typeDef}>`;
                         }
                     }
@@ -201,7 +204,7 @@ constructor(client: OpraHttpClient) {`;
             // operationBlock.doc.parameters += `\n * @param {${typeDef}} $body - Http body` + bodyFields;
             hasBody = true;
         }
-        /** process query params */
+        /* process query params */
         const isQueryRequired = queryParams.find(p => p.required);
         const isHeadersRequired = queryParams.find(p => p.required);
         if (queryParams.length) {
@@ -212,7 +215,7 @@ constructor(client: OpraHttpClient) {`;
                     (isHeadersRequired || isQueryRequired ? '' : '?') +
                     ': {\n\t';
             operationBlock.doc.parameters +=
-                '\n * @param {object} $params - Available parameters for the operation';
+                '\n * @param $params - Available parameters for the operation';
             let hasAdditionalFields = false;
             for (const prm of queryParams) {
                 if (typeof prm.name !== 'string') {
@@ -236,7 +239,7 @@ constructor(client: OpraHttpClient) {`;
             }
             operationBlock.head += '\b}\b';
         }
-        /** process header params */
+        /* process header params */
         if (headerParams.length) {
             // eslint-disable-next-line no-useless-assignment
             if (argIndex++ > 0)
@@ -275,11 +278,11 @@ constructor(client: OpraHttpClient) {`;
                     if (isArray)
                         typeDef = typeDef.substring(0, typeDef.length - 2);
                     if (resp.partial) {
-                        file.addImport('ts-gems', ['PartialDTO']);
+                        file.addImport('ts-gems', ['PartialDTO'], true);
                         typeDef = `PartialDTO<${typeDef}>`;
                     }
                     else {
-                        file.addImport('ts-gems', ['DTO']);
+                        file.addImport('ts-gems', ['DTO'], true);
                         typeDef = `DTO<${typeDef}>`;
                     }
                     if (isArray)
@@ -292,7 +295,7 @@ constructor(client: OpraHttpClient) {`;
                 typeIs.is(String(resp.contentType), [MimeTypes.opra_response_json]) &&
                 !(resp.type instanceof ComplexType &&
                     resp.type.base?.ctor === OperationResult)) {
-                file.addImport('@opra/common', ['OperationResult']);
+                file.addImport('@opra/common', ['OperationResult'], true);
                 typeDef = typeDef ? `OperationResult<${typeDef}>` : 'OperationResult';
             }
             typeDef = typeDef || 'undefined';

package/ts-generator/ts-file.d.ts

@@ -1,21 +1,56 @@
 import { CodeBlock } from '../code-block.js';
+/**
+ * TsFile
+ *
+ * A class representing a TypeScript source file, managing its imports, exports, and content.
+ */
 export declare class TsFile {
     readonly filename: string;
+    /** The directory name of the file. */
     readonly dirname: string;
+    /** Map of imports where key is the module path. */
     imports: Record<string, {
         items: string[];
         typeImport?: boolean;
     }>;
+    /** Map of exports where key is the module path. */
     exportFiles: Record<string, {
         filename: string;
         items: string[];
         namespace?: string;
     }>;
+    /** List of types to be exported. */
     exportTypes: string[];
+    /** The code block representing the file's content. */
     code: CodeBlock;
+    /**
+     * Initializes a new TsFile instance.
+     *
+     * @param filename - The name of the file.
+     */
     constructor(filename: string);
+    /**
+     * Adds an import statement to the file.
+     *
+     * @param filename - The module to import from.
+     * @param items - The specific items to import.
+     * @param typeImport - Whether it is a type-only import.
+     */
     addImport(filename: string, items?: string[], typeImport?: boolean): void;
+    /**
+     * Adds an export statement to the file.
+     *
+     * @param filename - The module to export from.
+     * @param types - The specific items to export.
+     * @param namespace - The namespace to export as.
+     */
     addExport(filename: string, types?: string[], namespace?: string): void;
+    /**
+     * Generates the file content as a string.
+     *
+     * @param options - Generation options.
+     * @returns The generated TypeScript code.
+     */
     generate(options?: {
         importExt?: boolean;
     }): string;

package/ts-generator/ts-file.js

@@ -1,13 +1,28 @@
 import path from 'node:path';
 import flattenText from 'putil-flattentext';
 import { CodeBlock } from '../code-block.js';
+/**
+ * TsFile
+ *
+ * A class representing a TypeScript source file, managing its imports, exports, and content.
+ */
 export class TsFile {
     filename;
+    /** The directory name of the file. */
     dirname;
+    /** Map of imports where key is the module path. */
     imports = {};
+    /** Map of exports where key is the module path. */
     exportFiles = {};
+    /** List of types to be exported. */
     exportTypes = [];
+    /** The code block representing the file's content. */
     code = new CodeBlock();
+    /**
+     * Initializes a new TsFile instance.
+     *
+     * @param filename - The name of the file.
+     */
     constructor(filename) {
         this.filename = filename;
         this.dirname = path.dirname(filename);
@@ -15,6 +30,13 @@ export class TsFile {
         this.code.imports = '';
         this.code.exports = '';
     }
+    /**
+     * Adds an import statement to the file.
+     *
+     * @param filename - The module to import from.
+     * @param items - The specific items to import.
+     * @param typeImport - Whether it is a type-only import.
+     */
     addImport(filename, items, typeImport) {
         if (isLocalFile(filename)) {
             filename = path.relative(this.dirname, path.resolve(this.dirname, filename));
@@ -36,6 +58,13 @@ export class TsFile {
                 imp.items.push(x);
         });
     }
+    /**
+     * Adds an export statement to the file.
+     *
+     * @param filename - The module to export from.
+     * @param types - The specific items to export.
+     * @param namespace - The namespace to export as.
+     */
     addExport(filename, types, namespace) {
         if (isLocalFile(filename)) {
             filename = path.relative(this.dirname, path.resolve(this.dirname, filename));
@@ -57,6 +86,12 @@ export class TsFile {
                 this.exportFiles[filename].items.push(x);
         });
     }
+    /**
+     * Generates the file content as a string.
+     *
+     * @param options - Generation options.
+     * @returns The generated TypeScript code.
+     */
     generate(options) {
         this.code.imports = Object.keys(this.imports)
             .sort((a, b) => {

package/ts-generator/ts-generator.d.ts

@@ -9,22 +9,37 @@ import { generateHttpApi } from './generators/generate-http-api.js';
 import { generateHttpController } from './generators/generate-http-controller.js';
 import { TsFile } from './ts-file.js';
 /**
- * @namespace TsGenerator
+ * TsGenerator
+ *
+ * A class responsible for generating TypeScript code from an OPRA API document.
  */
 export declare namespace TsGenerator {
+    /**
+     * Configuration options for TsGenerator.
+     */
     interface Options {
+        /** The URL of the OPRA service. */
         serviceUrl: string;
+        /** The output directory for the generated files. */
         outDir: string;
+        /** The current working directory. Defaults to process.cwd(). */
         cwd?: string;
+        /** Logger instance for outputting information. */
         logger?: ILogger;
+        /** File writer instance. Defaults to FileWriter. */
         writer?: IFileWriter;
+        /** Optional header to add to each generated file. */
         fileHeader?: string;
+        /** Whether to add .js extension to imports. */
         importExt?: boolean;
+        /** Whether to export references with namespaces. */
         referenceNamespaces?: boolean;
     }
 }
 /**
- * @class TsGenerator
+ * TsGenerator
+ *
+ * Main class for managing the TypeScript code generation process.
  */
 export declare class TsGenerator extends EventEmitter {
     protected cleanDirectory: typeof cleanDirectory;
@@ -63,12 +78,32 @@ export declare class TsGenerator extends EventEmitter {
     };
     fileHeader: string;
     /**
+     * Initializes a new TsGenerator instance.
      *
-     * @constructor
+     * @param init - Configuration options.
      */
     constructor(init: TsGenerator.Options);
+    /**
+     * Starts the code generation process.
+     *
+     * @throws {@link Error} If generation fails.
+     */
     generate(): Promise<void>;
+    /**
+     * Retrieves a file from the internal cache by its path.
+     *
+     * @param filePath - The path of the file to retrieve.
+     * @returns The TsFile instance or undefined if not found.
+     */
     protected getFile(filePath: string): TsFile;
+    /**
+     * Adds a new file to the generator or returns an existing one.
+     *
+     * @param filePath - The path of the file to add.
+     * @param returnExists - Whether to return the file if it already exists instead of throwing.
+     * @returns The newly created or existing TsFile instance.
+     * @throws {@link Error} If the file already exists and returnExists is false.
+     */
     protected addFile(filePath: string, returnExists?: boolean): TsFile;
     protected extend(): TsGenerator;
 }

package/ts-generator/ts-generator.js

@@ -11,7 +11,9 @@ import { generateHttpApi } from './generators/generate-http-api.js';
 import { generateHttpController } from './generators/generate-http-controller.js';
 import { TsFile } from './ts-file.js';
 /**
- * @class TsGenerator
+ * TsGenerator
+ *
+ * Main class for managing the TypeScript code generation process.
  */
 export class TsGenerator extends EventEmitter {
     _files = {};
@@ -26,8 +28,9 @@ export class TsGenerator extends EventEmitter {
     options;
     fileHeader;
     /**
+     * Initializes a new TsGenerator instance.
      *
-     * @constructor
+     * @param init - Configuration options.
      */
     constructor(init) {
         super();
@@ -49,6 +52,11 @@ export class TsGenerator extends EventEmitter {
         this.on('warn', (message, ...args) => init.logger?.warn?.(message, ...args));
         this.on('verbose', (message, ...args) => init.logger?.verbose?.(message, ...args));
     }
+    /**
+     * Starts the code generation process.
+     *
+     * @throws {@link Error} If generation fails.
+     */
     async generate() {
         if (this._started)
             return;
@@ -77,9 +85,23 @@ export class TsGenerator extends EventEmitter {
             this.emit('finish');
         }
     }
+    /**
+     * Retrieves a file from the internal cache by its path.
+     *
+     * @param filePath - The path of the file to retrieve.
+     * @returns The TsFile instance or undefined if not found.
+     */
     getFile(filePath) {
         return this._files[filePath];
     }
+    /**
+     * Adds a new file to the generator or returns an existing one.
+     *
+     * @param filePath - The path of the file to add.
+     * @param returnExists - Whether to return the file if it already exists instead of throwing.
+     * @returns The newly created or existing TsFile instance.
+     * @throws {@link Error} If the file already exists and returnExists is false.
+     */
     addFile(filePath, returnExists) {
         if (!(filePath.startsWith('.') || filePath.startsWith('/')))
             filePath = './' + filePath;

package/ts-generator/utils/locate-named-type.d.ts

@@ -1,2 +1,8 @@
 import { DataType } from '@opra/common';
+/**
+ * Locates the first named type in the inheritance chain of a data type.
+ *
+ * @param type - The data type to start from.
+ * @returns The found named DataType instance, or undefined if not found.
+ */
 export declare function locateNamedType(type?: DataType): DataType | undefined;

package/ts-generator/utils/locate-named-type.js

@@ -1,4 +1,10 @@
 import { ComplexType, EnumType, MappedType, SimpleType, } from '@opra/common';
+/**
+ * Locates the first named type in the inheritance chain of a data type.
+ *
+ * @param type - The data type to start from.
+ * @returns The found named DataType instance, or undefined if not found.
+ */
 export function locateNamedType(type) {
     if (!type)
         return;

package/ts-generator/utils/string-utils.d.ts

@@ -1,4 +1,36 @@
+/**
+ * Wraps a string for use in JSDoc comments.
+ *
+ * @param s - The string to wrap.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The wrapped JSDoc string.
+ */
 export declare function wrapJSDocString(s: string, indent?: number, currentColumn?: number): string;
+/**
+ * Wraps a string as a quoted string, potentially splitting it across multiple lines.
+ *
+ * @param s - The string to wrap.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The wrapped quoted string.
+ */
 export declare function wrapQuotedString(s: string, indent?: number, currentColumn?: number): string;
+/**
+ * Wraps an array of strings as a TypeScript array representation.
+ *
+ * @param arr - The array of strings.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The string representation of the array.
+ */
 export declare function wrapStringArray(arr: string[], indent?: number, currentColumn?: number): string;
+/**
+ * Wraps an array of types as a TypeScript union type representation.
+ *
+ * @param arr - The array of type names.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The string representation of the union type.
+ */
 export declare function wrapTypeArray(arr: string[], indent?: number, currentColumn?: number): string;

package/ts-generator/utils/string-utils.js

@@ -1,4 +1,12 @@
 import jsStringEscape from 'js-string-escape';
+/**
+ * Wraps a string for use in JSDoc comments.
+ *
+ * @param s - The string to wrap.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The wrapped JSDoc string.
+ */
 export function wrapJSDocString(s, indent, currentColumn) {
     const arr = (s || '')
         .split(/[ \n\r]/)
@@ -10,6 +18,14 @@ export function wrapJSDocString(s, indent, currentColumn) {
         lineEnd: '',
     });
 }
+/**
+ * Wraps a string as a quoted string, potentially splitting it across multiple lines.
+ *
+ * @param s - The string to wrap.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The wrapped quoted string.
+ */
 export function wrapQuotedString(s, indent, currentColumn) {
     const arr = jsStringEscape(s || '')
         .split(' ')
@@ -23,10 +39,26 @@ export function wrapQuotedString(s, indent, currentColumn) {
         }) +
         "'");
 }
+/**
+ * Wraps an array of strings as a TypeScript array representation.
+ *
+ * @param arr - The array of strings.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The string representation of the array.
+ */
 export function wrapStringArray(arr, indent, currentColumn) {
     const ar1 = arr.map((x, i, a) => "'" + x + "'" + (i < a.length - 1 ? ', ' : ''));
     return '[' + _printLines(ar1, { indent, currentColumn }) + ']';
 }
+/**
+ * Wraps an array of types as a TypeScript union type representation.
+ *
+ * @param arr - The array of type names.
+ * @param indent - The number of spaces for indentation.
+ * @param currentColumn - The current column position.
+ * @returns The string representation of the union type.
+ */
 export function wrapTypeArray(arr, indent, currentColumn) {
     const ar1 = arr.map((x, i, a) => x + (i < a.length - 1 ? ' | ' : ''));
     return _printLines(ar1, { indent, currentColumn });