@goast/kotlin 0.7.0 → 0.7.1

package/dist/src/import-collection.d.ts

@@ -1,19 +1,83 @@
 import { type SourceBuilderOptions, StringBuilder } from '@goast/core';
 import type { KotlinImport } from './common-results.ts';
+/**
+ * The options of an `ImportCollection`.
+ */
 export type ImportCollectionOptions = {
+    /**
+     * The imports to leave out when the collection is written. An entry ending in `.*` excludes a whole package, and any
+     * other entry excludes a single type by its fully qualified name.
+     * @default defaultKotlinGeneratorConfig.globalImports
+     * @see KotlinGeneratorConfig.globalImports
+     */
     globalImports: string[];
 };
+/**
+ * The options that an `ImportCollection` falls back to for any option that is not given. Its `globalImports` is the
+ * default of `defaultKotlinGeneratorConfig`.
+ * @see defaultKotlinGeneratorConfig
+ */
 export declare const defaultImportCollectionOptions: ImportCollectionOptions;
+/**
+ * Collects the types that a generated Kotlin file imports and writes them as `import` statements.
+ *
+ * Each type is stored once per package. When written, the imports are sorted by their full path, ignoring case, and
+ * imports whose path starts with `kotlin.`, `java.` or `javax.` come after all others. Imports that match
+ * `globalImports` are not written, but the `imports` getter still returns them.
+ * @see ImportCollectionOptions
+ * @see KotlinFileBuilder
+ */
 export declare class ImportCollection {
     private readonly _imports;
     private readonly _options;
+    /**
+     * Initializes a new instance of the ImportCollection class.
+     * @param options The options to use for this instance. Options that are not given keep their defaults.
+     */
     constructor(options?: Partial<ImportCollectionOptions>);
+    /**
+     * Gets a value indicating whether any import has been added. This includes imports that `globalImports` leaves out
+     * when the collection is written.
+     */
     get hasImports(): boolean;
+    /**
+     * Gets all added imports, one entry per type with its package. Unlike `writeTo`, this does not apply `globalImports`.
+     * @returns The added imports, grouped by package in the order in which the first import of each package was added.
+     */
     get imports(): KotlinImport[];
+    /**
+     * Adds the import of a type from a package. Nothing is added when `fromModule` is empty.
+     * @param importName The name of the type, such as `List`.
+     * @param fromModule The package the type is declared in, such as `kotlin.collections`.
+     */
     addImport(importName: string, fromModule: string): void;
+    /**
+     * Adds the import described by a `KotlinImport`. Nothing is added when its `packageName` is missing.
+     * @param importObj The import to add.
+     */
     addImport(importObj: KotlinImport): void;
+    /**
+     * Adds several imports, one after the other, as `addImport` does for each of them.
+     * @param imports The imports to add.
+     */
     addImports(imports: KotlinImport[]): void;
+    /**
+     * Removes all added imports.
+     */
     clear(): void;
+    /**
+     * Gets the import statements as text. This is the same text that `writeTo` appends.
+     * @param options The options of the string builder that builds the text, such as the line break characters.
+     * @returns The import statements, one per line. Empty when no import is left to write.
+     */
     toString(options?: Partial<SourceBuilderOptions>): string;
+    /**
+     * Appends one `import` statement per line to the builder, in the order described on `ImportCollection`. Writes
+     * nothing when no import is left after filtering.
+     *
+     * An import is left out when its package is listed in `globalImports` as an entry ending in `.*`, or when its full
+     * path (`package.Type`) is listed as an entry without that suffix.
+     * @param builder The builder to append the import statements to.
+     */
     writeTo(builder: StringBuilder): void;
 }

package/dist/src/import-collection.js

@@ -1,17 +1,43 @@
 import { compareString, StringBuilder } from '@goast/core';
 import { defaultKotlinGeneratorConfig } from './config.js';
+/**
+ * The options that an `ImportCollection` falls back to for any option that is not given. Its `globalImports` is the
+ * default of `defaultKotlinGeneratorConfig`.
+ * @see defaultKotlinGeneratorConfig
+ */
 export const defaultImportCollectionOptions = {
     globalImports: defaultKotlinGeneratorConfig.globalImports,
 };
+/**
+ * Collects the types that a generated Kotlin file imports and writes them as `import` statements.
+ *
+ * Each type is stored once per package. When written, the imports are sorted by their full path, ignoring case, and
+ * imports whose path starts with `kotlin.`, `java.` or `javax.` come after all others. Imports that match
+ * `globalImports` are not written, but the `imports` getter still returns them.
+ * @see ImportCollectionOptions
+ * @see KotlinFileBuilder
+ */
 export class ImportCollection {
     _imports = new Map();
     _options;
+    /**
+     * Initializes a new instance of the ImportCollection class.
+     * @param options The options to use for this instance. Options that are not given keep their defaults.
+     */
     constructor(options = {}) {
         this._options = { ...defaultImportCollectionOptions, ...options };
     }
+    /**
+     * Gets a value indicating whether any import has been added. This includes imports that `globalImports` leaves out
+     * when the collection is written.
+     */
     get hasImports() {
         return this._imports.size > 0;
     }
+    /**
+     * Gets all added imports, one entry per type with its package. Unlike `writeTo`, this does not apply `globalImports`.
+     * @returns The added imports, grouped by package in the order in which the first import of each package was added.
+     */
     get imports() {
         return Array.from(this._imports.entries())
             .map(([fromPackage, importNames]) => Array.from(importNames).map((importName) => ({
@@ -34,19 +60,39 @@ export class ImportCollection {
             this._imports.set(fromModule, new Set([importName]));
         }
     }
+    /**
+     * Adds several imports, one after the other, as `addImport` does for each of them.
+     * @param imports The imports to add.
+     */
     addImports(imports) {
         for (const importObj of imports) {
             this.addImport(importObj);
         }
     }
+    /**
+     * Removes all added imports.
+     */
     clear() {
         this._imports.clear();
     }
+    /**
+     * Gets the import statements as text. This is the same text that `writeTo` appends.
+     * @param options The options of the string builder that builds the text, such as the line break characters.
+     * @returns The import statements, one per line. Empty when no import is left to write.
+     */
     toString(options) {
         const builder = new StringBuilder(options);
         this.writeTo(builder);
         return builder.toString();
     }
+    /**
+     * Appends one `import` statement per line to the builder, in the order described on `ImportCollection`. Writes
+     * nothing when no import is left after filtering.
+     *
+     * An import is left out when its package is listed in `globalImports` as an entry ending in `.*`, or when its full
+     * path (`package.Type`) is listed as an entry without that suffix.
+     * @param builder The builder to append the import statements to.
+     */
     writeTo(builder) {
         if (this._imports.size > 0) {
             const globalPackages = this._options.globalImports

package/dist/src/types.d.ts

@@ -1,4 +1,8 @@
 import type { ApiParameter } from '@goast/core';
+/**
+ * An API parameter that can carry the form part it is sent as in a `multipart/form-data` request body.
+ * @see ApiParameter
+ */
 export type ApiParameterWithMultipartInfo = ApiParameter & {
     multipart?: {
         name: string;

package/dist/src/utils.d.ts

@@ -1,7 +1,59 @@
 import type { ApiComponent, ApiSchema, Nullable } from '@goast/core';
+/**
+ * Converts a string to a Kotlin string literal. Double quotes, backslashes and dollar signs are escaped, and line
+ * breaks and tabs are written as escape sequences. A nullish or empty value becomes `""`.
+ * @param value The string to convert.
+ * @returns The string literal, including its surrounding double quotes.
+ * @example
+ * ```ts
+ * toKotlinStringLiteral('say "hi" $x'); // => "say \"hi\" \$x"
+ * ```
+ */
 export declare function toKotlinStringLiteral(value: Nullable<string>): string;
+/**
+ * Gets a name that can be used as a Kotlin property name. A name that consists only of letters, digits, `_` and `$`,
+ * and does not start with a digit, is returned unchanged. Any other name is wrapped in backticks. Reserved words are
+ * not detected.
+ * @param value The name to convert.
+ * @returns The name, wrapped in backticks if it contains other characters.
+ * @example
+ * ```ts
+ * toKotlinPropertyName('firstName'); // => firstName
+ * toKotlinPropertyName('first-name'); // => `first-name`
+ * ```
+ */
 export declare function toKotlinPropertyName(value: string): string;
+/**
+ * Modifies a string with a modifier. A string modifier replaces the value. A regular expression replaces the value with
+ * its first match, or keeps the value when nothing matches. A function returns the new value. Without a modifier, the
+ * value is returned unchanged.
+ * @template TArgs The types of the extra arguments that are passed to a modifier function.
+ * @param value The value to modify.
+ * @param modifier The replacement string, the regular expression, or the function that computes the new value.
+ * @param args The extra arguments that are passed to a modifier function.
+ * @returns The modified string.
+ */
 export declare function modifyString<TArgs extends unknown[]>(value: string, modifier: string | RegExp | ((value: string, ...args: TArgs) => string) | undefined, ...args: TArgs): string;
+/**
+ * Gets a documentation line that names the OpenAPI source of a component, such as
+ * `Source: openapi/pet.yaml:12:3 (#/components/schemas/Pet)`. The file path is relative to the working directory and
+ * uses forward slashes.
+ * @template T The OpenAPI object type the component was transformed from.
+ * @param component The component whose source is named.
+ * @returns The source line.
+ */
 export declare function getSourceDocLine<T>(component: ApiComponent<T>): string;
+/**
+ * Gets a schema if it is a string schema with at least one enum value.
+ * @param schema The schema to check.
+ * @returns The schema, or `undefined` if it is not a string schema with enum values.
+ */
 export declare function getStringEnumSchema(schema: Nullable<ApiSchema>): ApiSchema<'string'> | undefined;
+/**
+ * Gets the string enum schema of the items of an array schema.
+ * @param schema The schema to check.
+ * @returns The enum schema of the array items, or `undefined` if the schema is not an array whose items are a string
+ * enum.
+ * @see getStringEnumSchema
+ */
 export declare function getArrayItemStringEnumSchema(schema: Nullable<ApiSchema>): ApiSchema<'string'> | undefined;

package/dist/src/utils.js

@@ -1,5 +1,15 @@
 import path from 'node:path';
 import process from 'node:process';
+/**
+ * Converts a string to a Kotlin string literal. Double quotes, backslashes and dollar signs are escaped, and line
+ * breaks and tabs are written as escape sequences. A nullish or empty value becomes `""`.
+ * @param value The string to convert.
+ * @returns The string literal, including its surrounding double quotes.
+ * @example
+ * ```ts
+ * toKotlinStringLiteral('say "hi" $x'); // => "say \"hi\" \$x"
+ * ```
+ */
 export function toKotlinStringLiteral(value) {
     if (!value) {
         return '""';
@@ -11,12 +21,34 @@ export function toKotlinStringLiteral(value) {
         .replace(/\t/g, '\\t');
     return `"${escaped}"`;
 }
+/**
+ * Gets a name that can be used as a Kotlin property name. A name that consists only of letters, digits, `_` and `$`,
+ * and does not start with a digit, is returned unchanged. Any other name is wrapped in backticks. Reserved words are
+ * not detected.
+ * @param value The name to convert.
+ * @returns The name, wrapped in backticks if it contains other characters.
+ * @example
+ * ```ts
+ * toKotlinPropertyName('firstName'); // => firstName
+ * toKotlinPropertyName('first-name'); // => `first-name`
+ * ```
+ */
 export function toKotlinPropertyName(value) {
     if (value.match(/^[a-zA-Z_$][a-zA-Z_$0-9]*$/)) {
         return value;
     }
     return `\`${value}\``;
 }
+/**
+ * Modifies a string with a modifier. A string modifier replaces the value. A regular expression replaces the value with
+ * its first match, or keeps the value when nothing matches. A function returns the new value. Without a modifier, the
+ * value is returned unchanged.
+ * @template TArgs The types of the extra arguments that are passed to a modifier function.
+ * @param value The value to modify.
+ * @param modifier The replacement string, the regular expression, or the function that computes the new value.
+ * @param args The extra arguments that are passed to a modifier function.
+ * @returns The modified string.
+ */
 export function modifyString(value, modifier, ...args) {
     if (typeof modifier === 'string') {
         return modifier;
@@ -30,14 +62,34 @@ export function modifyString(value, modifier, ...args) {
     }
     return value;
 }
+/**
+ * Gets a documentation line that names the OpenAPI source of a component, such as
+ * `Source: openapi/pet.yaml:12:3 (#/components/schemas/Pet)`. The file path is relative to the working directory and
+ * uses forward slashes.
+ * @template T The OpenAPI object type the component was transformed from.
+ * @param component The component whose source is named.
+ * @returns The source line.
+ */
 export function getSourceDocLine(component) {
     const file = path.relative(process.cwd(), component.$src.file).replace(/\\/g, '/');
     const { line, col } = component.$src.pos;
     return `Source: ${file}:${line}:${col} (${component.$src.path})`;
 }
+/**
+ * Gets a schema if it is a string schema with at least one enum value.
+ * @param schema The schema to check.
+ * @returns The schema, or `undefined` if it is not a string schema with enum values.
+ */
 export function getStringEnumSchema(schema) {
     return schema?.kind === 'string' && schema.enum?.length ? schema : undefined;
 }
+/**
+ * Gets the string enum schema of the items of an array schema.
+ * @param schema The schema to check.
+ * @returns The enum schema of the array items, or `undefined` if the schema is not an array whose items are a string
+ * enum.
+ * @see getStringEnumSchema
+ */
 export function getArrayItemStringEnumSchema(schema) {
     return schema?.kind === 'array' ? getStringEnumSchema(schema.items) : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goast/kotlin",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Provides gOAst generators for generating Kotlin code from OpenAPI specifications.",
   "bugs": {
     "url": "https://github.com/MaSch0212/goast/issues"
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "http-status-codes": "^2.3.0",
-    "@goast/core": "^0.7.0"
+    "@goast/core": "^0.7.1"
   },
   "devDependencies": {
     "@goast/test-harness": "0.0.0"