@goast/typescript 0.9.0 → 0.9.1

package/dist/src/import-collection.js

@@ -2,10 +2,29 @@ import { extname } from 'node:path';
 import { compareString, StringBuilder } from '@goast/core';
 import { defaultTypeScriptGeneratorConfig } from './config.js';
 import { getModulePathRelativeToFile } from './utils.js';
+/**
+ * The default options of an `ImportExportCollection`. The transformer and the quote style are taken from
+ * `defaultTypeScriptGeneratorConfig`.
+ */
 export const defaultImportExportCollectionOptions = {
     importModuleTransformer: defaultTypeScriptGeneratorConfig.importModuleTransformer,
     useSingleQuotes: defaultTypeScriptGeneratorConfig.useSingleQuotes,
 };
+/**
+ * Collects the imports and re-exports of a file, and writes them as import and export statements.
+ *
+ * Names are stored per module path, in one map for each form: `import`, `import type` and `@import` names, and the same
+ * for re-exports. Adding a name that is already present has no effect, so each name is written once per module.
+ *
+ * When the statements are written, a project file (a path ending in `.ts`, `.js` or `.json`) is turned into a relative
+ * path from the file that the statements are written to, and transformed with `importModuleTransformer`. A package
+ * name, such as `rxjs`, is written as it is. The statements are written in this order: value imports, type imports, the
+ * `@import` block, value re-exports and type re-exports. Module imports come before file imports, separated by a blank
+ * line.
+ *
+ * `TypeScriptFileBuilder` owns one of these collections. It adds the imports of every `TsReference` node that has a
+ * module or file path, and it passes its own `filePath` and options to the collection.
+ */
 export class ImportExportCollection {
     _imports = new Map();
     _typeImports = new Map();
@@ -13,15 +32,29 @@ export class ImportExportCollection {
     _exports = new Map();
     _typeExports = new Map();
     _options;
+    /**
+     * Initializes a new instance of the ImportExportCollection class.
+     * @param options The options of the collection. Options that are not given use the defaults.
+     */
     constructor(options) {
         this._options = { ...defaultImportExportCollectionOptions, ...options };
     }
+    /**
+     * Gets a value indicating whether at least one import of any form has been added.
+     */
     get hasImports() {
         return this._imports.size > 0 || this._typeImports.size > 0 || this._jsDocImports.size > 0;
     }
+    /**
+     * Gets a value indicating whether at least one re-export of any form has been added.
+     */
     get hasExports() {
         return this._exports.size > 0 || this._typeExports.size > 0;
     }
+    /**
+     * Gets all collected imports as a flat list. The module paths are the unresolved ones, as they were passed to
+     * `addImport`, so they are not yet relative to the file.
+     */
     get imports() {
         return [
             ...this.toImport('import', this._imports),
@@ -39,6 +72,12 @@ export class ImportExportCollection {
         })))
             .flat();
     }
+    /**
+     * Adds a named import from a module or a file. Adding the same name from the same module again has no effect.
+     * @param importName The name to import.
+     * @param fromModule The module name, such as `rxjs`, or the path of the file that exports the name.
+     * @param options The options of the import, such as the import type. Defaults to a value import.
+     */
     addImport(importName, fromModule, options) {
         const map = this.getImportMap(options?.type ?? 'import');
         const existingImport = map.get(fromModule);
@@ -49,6 +88,12 @@ export class ImportExportCollection {
             map.set(fromModule, new Set([importName]));
         }
     }
+    /**
+     * Adds a named re-export from a module or a file. Adding the same name from the same module again has no effect.
+     * @param exportName The name to re-export.
+     * @param fromModule The module name, or the path of the file that exports the name.
+     * @param options The options of the export, such as the export type. Defaults to a value export.
+     */
     addExport(exportName, fromModule, options) {
         const map = this.getExportMap(options?.type ?? 'export');
         const existingExport = map.get(fromModule);
@@ -59,6 +104,9 @@ export class ImportExportCollection {
             map.set(fromModule, new Set([exportName]));
         }
     }
+    /**
+     * Removes all collected imports and re-exports.
+     */
     clear() {
         this._imports.clear();
         this._typeImports.clear();
@@ -66,11 +114,21 @@ export class ImportExportCollection {
         this._exports.clear();
         this._typeExports.clear();
     }
+    /**
+     * Renders the import and export statements as a string.
+     * @param options The options of the builder that the statements are written with.
+     * @returns The import and export statements.
+     */
     toString(options) {
         const builder = new StringBuilder(options);
         this.writeTo(builder);
         return builder.toString();
     }
+    /**
+     * Writes the import and export statements to a builder. The statements are written in the order described for the
+     * class, and the groups are separated by a blank line.
+     * @param builder The builder to write the statements to.
+     */
     writeTo(builder) {
         const { filePath, importModuleTransformer, useSingleQuotes } = this._options;
         let hasPrevious = false;

package/dist/src/utils.d.ts

@@ -1,8 +1,70 @@
 import type { ApiComponent, Nullable } from '@goast/core';
+/**
+ * Describes how the module path of an import from a generated file into a project file is written. The path is always
+ * relative to the importing file and starts with `./` or `../`.
+ * - `'omit-extension'` removes the file extension.
+ * - `'with-extension'` keeps the file extension.
+ * - `'js-extension'` replaces the file extension with `.js`.
+ * - A function receives the relative path and returns the module path to write.
+ * @example
+ * ```ts
+ * // Importing `src/models/user.ts` from `src/services/api.ts` produces:
+ * // 'omit-extension': '../models/user'
+ * // 'with-extension': '../models/user.ts'
+ * // 'js-extension': '../models/user.js'
+ * ```
+ */
 export type ImportModuleTransformer = 'omit-extension' | 'with-extension' | 'js-extension' | ((module: string) => string);
+/**
+ * Converts a string into a TypeScript string literal. The value is escaped the way JSON escapes it, and the literal is
+ * quoted with single quotes if `useSingleQuotes` is set, or with double quotes otherwise.
+ * @param value The string to convert.
+ * @param useSingleQuotes Whether to quote the literal with single quotes.
+ * @returns The string literal, including its quotes.
+ */
 export declare function toTypeScriptStringLiteral(value: string, useSingleQuotes: boolean): string;
+/**
+ * Converts a name into a TypeScript object property name. A name that is a plain identifier is written as it is, and
+ * any other name is written as a string literal.
+ * @param value The property name to convert.
+ * @param useSingleQuotes Whether a string literal is quoted with single quotes.
+ * @returns The property name, quoted if it is not a plain identifier.
+ */
 export declare function toTypeScriptPropertyName(value: string, useSingleQuotes: boolean): string;
+/**
+ * Gets the module path that a file at `from` uses to import the file at `to`. The path is relative to the directory of
+ * `from`, uses forward slashes, and is transformed with `transformer`.
+ * @param from The path of the importing file.
+ * @param to The path of the imported file.
+ * @param transformer The transformer that writes the module path.
+ * @returns The module path, such as `./user` or `../models/user`.
+ */
 export declare function getModulePathRelativeToFile(from: string, to: string, transformer: ImportModuleTransformer): string;
+/**
+ * Gets the module path that imports the file at `to` from the directory `from`. The path is relative to `from`, uses
+ * forward slashes, and is transformed with `transformer`.
+ * @param from The directory that the import is written in.
+ * @param to The path of the imported file.
+ * @param transformer The transformer that writes the module path.
+ * @returns The module path, such as `./user` or `../models/user`.
+ */
 export declare function getModulePathRelativeToDirectory(from: string, to: string, transformer: ImportModuleTransformer): string;
+/**
+ * Applies a modifier to a string. A string modifier replaces the value entirely. A RegExp keeps only the part of the
+ * value that it matches, or leaves the value as it is if it does not match. A function returns its own result for the
+ * value and the extra arguments. A nullish modifier leaves the value as it is.
+ * @template TArgs The types of the extra arguments that are passed to a function modifier.
+ * @param value The string to modify.
+ * @param modifier The modifier to apply.
+ * @param args The extra arguments that are passed to a function modifier.
+ * @returns The modified string.
+ */
 export declare function modifyString<TArgs extends unknown[]>(value: string, modifier: Nullable<string | RegExp | ((value: string, ...args: TArgs) => string)>, ...args: TArgs): string;
+/**
+ * Gets a documentation line that names the source location of a component in its OpenAPI document. The file path is
+ * relative to the current working directory and uses forward slashes.
+ * @template T The type of the value of the component.
+ * @param component The component to get the source location for.
+ * @returns A line that starts with `Source:` and names the file, the line, the column and the path of the component.
+ */
 export declare function getSourceDocLine<T>(component: ApiComponent<T>): string;

package/dist/src/utils.js

@@ -3,18 +3,48 @@ import process from 'node:process';
 function doubleQuotedToSingleQuoted(value) {
     return `'${value.slice(1, -1).replace(/'/g, "\\'")}'`;
 }
+/**
+ * Converts a string into a TypeScript string literal. The value is escaped the way JSON escapes it, and the literal is
+ * quoted with single quotes if `useSingleQuotes` is set, or with double quotes otherwise.
+ * @param value The string to convert.
+ * @param useSingleQuotes Whether to quote the literal with single quotes.
+ * @returns The string literal, including its quotes.
+ */
 export function toTypeScriptStringLiteral(value, useSingleQuotes) {
     return useSingleQuotes ? doubleQuotedToSingleQuoted(JSON.stringify(value)) : JSON.stringify(value);
 }
+/**
+ * Converts a name into a TypeScript object property name. A name that is a plain identifier is written as it is, and
+ * any other name is written as a string literal.
+ * @param value The property name to convert.
+ * @param useSingleQuotes Whether a string literal is quoted with single quotes.
+ * @returns The property name, quoted if it is not a plain identifier.
+ */
 export function toTypeScriptPropertyName(value, useSingleQuotes) {
     if (value.match(/^[a-zA-Z_$][a-zA-Z_$0-9]*$/)) {
         return value;
     }
     return useSingleQuotes ? doubleQuotedToSingleQuoted(JSON.stringify(value)) : JSON.stringify(value);
 }
+/**
+ * Gets the module path that a file at `from` uses to import the file at `to`. The path is relative to the directory of
+ * `from`, uses forward slashes, and is transformed with `transformer`.
+ * @param from The path of the importing file.
+ * @param to The path of the imported file.
+ * @param transformer The transformer that writes the module path.
+ * @returns The module path, such as `./user` or `../models/user`.
+ */
 export function getModulePathRelativeToFile(from, to, transformer) {
     return transformModulePath(relative(dirname(from), to).replace(/\\/g, '/'), transformer);
 }
+/**
+ * Gets the module path that imports the file at `to` from the directory `from`. The path is relative to `from`, uses
+ * forward slashes, and is transformed with `transformer`.
+ * @param from The directory that the import is written in.
+ * @param to The path of the imported file.
+ * @param transformer The transformer that writes the module path.
+ * @returns The module path, such as `./user` or `../models/user`.
+ */
 export function getModulePathRelativeToDirectory(from, to, transformer) {
     return transformModulePath(relative(from, to).replace(/\\/g, '/'), transformer);
 }
@@ -36,6 +66,16 @@ function transformModulePath(modulePath, transformer) {
     }
     return modulePath;
 }
+/**
+ * Applies a modifier to a string. A string modifier replaces the value entirely. A RegExp keeps only the part of the
+ * value that it matches, or leaves the value as it is if it does not match. A function returns its own result for the
+ * value and the extra arguments. A nullish modifier leaves the value as it is.
+ * @template TArgs The types of the extra arguments that are passed to a function modifier.
+ * @param value The string to modify.
+ * @param modifier The modifier to apply.
+ * @param args The extra arguments that are passed to a function modifier.
+ * @returns The modified string.
+ */
 export function modifyString(value, modifier, ...args) {
     if (typeof modifier === 'string') {
         return modifier;
@@ -49,6 +89,13 @@ export function modifyString(value, modifier, ...args) {
     }
     return value;
 }
+/**
+ * Gets a documentation line that names the source location of a component in its OpenAPI document. The file path is
+ * relative to the current working directory and uses forward slashes.
+ * @template T The type of the value of the component.
+ * @param component The component to get the source location for.
+ * @returns A line that starts with `Source:` and names the file, the line, the column and the path of the component.
+ */
 export function getSourceDocLine(component) {
     const file = path.relative(process.cwd(), component.$src.file).replace(/\\/g, '/');
     const { line, col } = component.$src.pos;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goast/typescript",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Provides gOAst generators for generating TypeScript code from OpenAPI specifications.",
   "bugs": {
     "url": "https://github.com/MaSch0212/goast/issues"
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "fs-extra": "^11.3.3",
-    "@goast/core": "^0.7.0"
+    "@goast/core": "^0.7.1"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",