@goast/typescript 0.4.3 → 0.5.0

package/src/src/generators/services/k6-clients/models.ts

@@ -0,0 +1,241 @@
+import type {
+  ApiSchema,
+  ApiService,
+  DefaultGenerationProviderConfig,
+  ExtendedStringCasing,
+  Nullable,
+  OpenApiServicesGenerationProviderContext,
+} from '@goast/core';
+
+import type { ts } from '../../../ast/index.js';
+import type { TypeScriptExportOutput } from '../../../common-results.js';
+import { defaultTypeScriptGeneratorConfig, type TypeScriptGeneratorConfig } from '../../../config.js';
+import type { TypeScriptFileBuilder } from '../../../file-builder.js';
+import type { TypeScriptModelsGeneratorOutput } from '../../models/index.js';
+import type { getReferenceFactories } from './refs.js';
+
+export type TypeScriptK6ClientsGeneratorConfig = TypeScriptGeneratorConfig & {
+  /**
+   * Whether to use strict response types for the services.
+   * If enabled only the status codes are included that are defined in the OpenAPI specification or the `defaultStatusCodeResponseTypes` option.
+   * @default true
+   */
+  strictResponseTypes: boolean;
+
+  /**
+   * The default response types for status codes that are not defined in the OpenAPI specification.
+   * @example
+   * {
+   *   400: {
+   *     parser: 'json',
+   *     type: schemas =>
+   *       schemas.find(s => s.name === 'BadRequestResponse')
+   *         ?? throwExp('BadRequestResponse not found'),
+   *   },
+   *   404: null,
+   *   500: {
+   *     parser: 'json',
+   *     type: ts.refs.any(),
+   *   },
+   * }
+   * @default
+   * {
+   *   401: null,
+   *   403: null,
+   *   500: null,
+   * }
+   */
+  defaultStatusCodeResponseTypes: Record<
+    number,
+    {
+      parser: 'text' | 'json';
+      // deno-lint-ignore ban-types
+      type: Exclude<ts.Type<TypeScriptFileBuilder>, Function> | ((schemas: readonly ApiSchema[]) => ApiSchema);
+    } | null
+  >;
+
+  /**
+   * The possible status codes that any API endpoint can return.
+   * This is only used when `strictResponseTypes` is set to `false`.
+   * @default
+   * [100, 101, 102, 103, 200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451, 500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511]
+   */
+  possibleStatusCodes: number[];
+
+  /**
+   * The casing of the client file names. If nullish, the `fileNameCasing` is used.
+   * @default { casing: 'kebab', suffix: '-client' }
+   */
+  clientFileNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * The casing of the file names for the response models. If nullish, the `fileNameCasing` is used.
+   * @default { casing: 'kebab', suffix: '-responses' }
+   */
+  responseModelFileNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * The casing of the client names. If nullish, the `typeNameCasing` is used.
+   * @default { casing: 'pascal', suffix: 'Client' }
+   */
+  clientNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * The directory where the client files should be saved. The path is relative to the output directory.
+   * @default 'clients'
+   */
+  clientDir: string;
+
+  /**
+   * The directory where the response models should be saved. The path is relative to the output directory.
+   * @default 'models/responses'
+   */
+  responseModelsDir: string;
+
+  /**
+   * The index file where all clients should be exported. The path is relative to the output directory. If nullish, no index file will be generated.
+   * @default 'clients.ts'
+   */
+  clientsIndexFile: Nullable<string>;
+
+  /**
+   * The path to the index file where all response models should be exported. The path is relative to the output directory. If nullish, no index file will be generated.
+   * @default 'responses.ts'
+   */
+  responseModelsIndexFile: Nullable<string>;
+
+  /**
+   * The directory where the utilies should be saved. The path is relative to the output directory.
+   * @default 'utils'
+   */
+  utilsDir: string;
+
+  /**
+   * Whether to generate clients calling the async API of k6.
+   * @default true
+   */
+  async: boolean;
+};
+
+export const defaultTypeScriptK6ClientsGeneratorConfig: DefaultGenerationProviderConfig<
+  TypeScriptK6ClientsGeneratorConfig
+> = {
+  ...defaultTypeScriptGeneratorConfig,
+  importModuleTransformer: 'js-extension',
+
+  strictResponseTypes: true,
+  defaultStatusCodeResponseTypes: {
+    401: null,
+    403: null,
+    500: null,
+  },
+  possibleStatusCodes: [
+    100,
+    101,
+    102,
+    103,
+    200,
+    201,
+    202,
+    203,
+    204,
+    205,
+    206,
+    207,
+    208,
+    226,
+    300,
+    301,
+    302,
+    303,
+    304,
+    305,
+    306,
+    307,
+    308,
+    400,
+    401,
+    402,
+    403,
+    404,
+    405,
+    406,
+    407,
+    408,
+    409,
+    410,
+    411,
+    412,
+    413,
+    414,
+    415,
+    416,
+    417,
+    421,
+    422,
+    423,
+    424,
+    425,
+    426,
+    428,
+    429,
+    431,
+    451,
+    500,
+    501,
+    502,
+    503,
+    504,
+    505,
+    506,
+    507,
+    508,
+    510,
+    511,
+  ],
+
+  clientFileNameCasing: { casing: 'kebab', suffix: '-client' },
+  responseModelFileNameCasing: { casing: 'kebab', suffix: '-responses' },
+  clientNameCasing: { casing: 'pascal', suffix: 'Client' },
+  clientDir: 'clients',
+  responseModelsDir: 'models/responses',
+  clientsIndexFile: 'clients.js',
+  responseModelsIndexFile: 'responses.ts',
+  utilsDir: 'utils',
+  async: true,
+};
+
+export type TypeScriptK6ClientsGeneratorInput = TypeScriptModelsGeneratorOutput;
+
+export type TypeScriptK6ClientsGeneratorOutput = {
+  typescript: {
+    k6Clients: {
+      [serviceId: string]: TypeScriptK6ClientGeneratorOutput;
+    };
+    indexFiles: {
+      k6Clients: Nullable<string>;
+      k6ResponseModels: Nullable<string>;
+    };
+  };
+};
+
+export type TypeScriptK6ClientGeneratorOutput = TypeScriptExportOutput & {
+  responseModels: {
+    [operationId: string]: TypeScriptExportOutput;
+  };
+};
+
+export type TypeScriptK6ClientsGeneratorContext =
+  & OpenApiServicesGenerationProviderContext<
+    TypeScriptK6ClientsGeneratorInput,
+    TypeScriptK6ClientsGeneratorOutput,
+    TypeScriptK6ClientsGeneratorConfig,
+    TypeScriptK6ClientGeneratorOutput
+  >
+  & {
+    refs: ReturnType<typeof getReferenceFactories>;
+  };
+
+export type TypeScriptK6ClientGeneratorContext = TypeScriptK6ClientsGeneratorContext & {
+  readonly service: ApiService;
+};

package/src/src/generators/services/k6-clients/refs.ts

@@ -0,0 +1,15 @@
+import { join, resolve } from 'node:path';
+
+import { ts } from '../../../ast/index.js';
+import type { TypeScriptK6ClientsGeneratorConfig } from './models.js';
+
+export function getReferenceFactories(options: TypeScriptK6ClientsGeneratorConfig): {
+  requestBuilder: ts.ModuleReferenceFactory;
+  httpStatusCode: ts.ModuleReferenceFactory;
+} {
+  const utilsDirPath = resolve(options.outputDir, options.utilsDir);
+  return {
+    requestBuilder: ts.reference.factory('RequestBuilder', join(utilsDirPath, 'request-builder.js')),
+    httpStatusCode: ts.reference.factory('HttpStatusCode', join(utilsDirPath, 'http-status-code.ts')),
+  };
+}

package/src/src/import-collection.test.ts

@@ -0,0 +1,78 @@
+import "../_dnt.test_polyfills.js";
+import type { SourceBuilderOptions } from '@goast/core';
+
+import { expect } from '../deps/jsr.io/@std/expect/1.0.13/mod.js';
+import { beforeEach, describe, it } from '../deps/jsr.io/@std/testing/1.0.9/bdd.js';
+
+import { ImportExportCollection } from './import-collection.js';
+
+describe('ImportExportCollection', () => {
+  let collection: ImportExportCollection;
+  let sourceBuilderOptions: Partial<SourceBuilderOptions>;
+
+  beforeEach(() => {
+    collection = new ImportExportCollection({ importModuleTransformer: 'omit-extension' });
+    sourceBuilderOptions = { newLine: '\n' };
+  });
+
+  describe('addImport', () => {
+    it('should add a new import to the collection', () => {
+      collection.addImport('myImport', 'myModule');
+      expect(collection.hasImports).toBe(true);
+      expect(collection.hasExports).toBe(false);
+      expect(collection.toString(sourceBuilderOptions)).toBe("import { myImport } from 'myModule';\n");
+    });
+
+    it('should add a new import to an existing module', () => {
+      collection.addImport('myImport1', 'myModule');
+      collection.addImport('myImport2', 'myModule');
+      expect(collection.hasImports).toBe(true);
+      expect(collection.hasExports).toBe(false);
+      expect(collection.toString(sourceBuilderOptions)).toBe("import { myImport1, myImport2 } from 'myModule';\n");
+    });
+  });
+
+  describe('addExport', () => {
+    it('should add a new export to the collection', () => {
+      collection.addExport('myExport', 'myModule');
+      expect(collection.hasImports).toBe(false);
+      expect(collection.hasExports).toBe(true);
+      expect(collection.toString(sourceBuilderOptions)).toBe("export { myExport } from 'myModule';\n");
+    });
+
+    it('should add a new export to an existing module', () => {
+      collection.addExport('myExport1', 'myModule');
+      collection.addExport('myExport2', 'myModule');
+      expect(collection.hasImports).toBe(false);
+      expect(collection.hasExports).toBe(true);
+      expect(collection.toString(sourceBuilderOptions)).toBe("export { myExport1, myExport2 } from 'myModule';\n");
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear the collection', () => {
+      collection.addImport('myImport', 'myModule');
+      collection.addExport('myExport', 'myModule');
+      expect(collection.hasImports).toBe(true);
+      expect(collection.hasExports).toBe(true);
+      collection.clear();
+      expect(collection.hasImports).toBe(false);
+      expect(collection.hasExports).toBe(false);
+      expect(collection.toString(sourceBuilderOptions)).toBe('');
+    });
+  });
+
+  describe('toString', () => {
+    it('should return an empty string if the collection is empty', () => {
+      expect(collection.toString(sourceBuilderOptions)).toBe('');
+    });
+
+    it('should return a string representation of the collection', () => {
+      collection.addImport('myImport', 'myModule');
+      collection.addExport('myExport', 'myModule');
+      expect(collection.toString(sourceBuilderOptions)).toBe(
+        "import { myImport } from 'myModule';\n\nexport { myExport } from 'myModule';\n",
+      );
+    });
+  });
+});

package/src/src/import-collection.ts

@@ -0,0 +1,236 @@
+import { extname } from 'node:path';
+
+import { type SourceBuilderOptions, StringBuilder } from '@goast/core';
+
+import type {
+  TypeScriptExportType,
+  TypeScriptImport,
+  TypeScriptImportKind,
+  TypeScriptImportType,
+} from './common-results.js';
+import { defaultTypeScriptGeneratorConfig } from './config.js';
+import { getModulePathRelativeToFile, type ImportModuleTransformer } from './utils.js';
+
+export type ImportExportCollectionOptions = {
+  filePath?: string;
+  importModuleTransformer: ImportModuleTransformer;
+  useSingleQuotes: boolean;
+};
+
+export const defaultImportExportCollectionOptions: ImportExportCollectionOptions = {
+  importModuleTransformer: defaultTypeScriptGeneratorConfig.importModuleTransformer,
+  useSingleQuotes: defaultTypeScriptGeneratorConfig.useSingleQuotes,
+};
+
+export type TypeScriptImportOptions = { type?: TypeScriptImportType };
+export type TypeScriptExportOptions = { type?: TypeScriptExportType };
+
+export class ImportExportCollection {
+  private readonly _imports: Map<string, Set<string>> = new Map();
+  private readonly _typeImports: Map<string, Set<string>> = new Map();
+  private readonly _jsDocImports: Map<string, Set<string>> = new Map();
+  private readonly _exports: Map<string, Set<string>> = new Map();
+  private readonly _typeExports: Map<string, Set<string>> = new Map();
+  private readonly _options: ImportExportCollectionOptions;
+
+  constructor(options?: Partial<ImportExportCollectionOptions>) {
+    this._options = { ...defaultImportExportCollectionOptions, ...options };
+  }
+
+  public get hasImports(): boolean {
+    return this._imports.size > 0 || this._typeImports.size > 0 || this._jsDocImports.size > 0;
+  }
+
+  public get hasExports(): boolean {
+    return this._exports.size > 0 || this._typeExports.size > 0;
+  }
+
+  public get imports(): TypeScriptImport[] {
+    return [
+      ...this.toImport('import', this._imports),
+      ...this.toImport('type-import', this._typeImports),
+      ...this.toImport('js-doc', this._jsDocImports),
+    ];
+  }
+
+  private toImport(type: TypeScriptImportType, map: Map<string, Set<string>>): TypeScriptImport[] {
+    return Array.from(map.entries())
+      .map(([fromModule, importNames]) =>
+        Array.from(importNames).map(
+          (importName) => ({
+            kind: this.getImportKind(fromModule),
+            type,
+            modulePath: fromModule,
+            name: importName,
+          } satisfies TypeScriptImport),
+        )
+      )
+      .flat();
+  }
+
+  public addImport(importName: string, fromModule: string, options?: TypeScriptImportOptions): void {
+    const map = this.getImportMap(options?.type ?? 'import');
+    const existingImport = map.get(fromModule);
+    if (existingImport) {
+      existingImport.add(importName);
+    } else {
+      map.set(fromModule, new Set([importName]));
+    }
+  }
+
+  public addExport(exportName: string, fromModule: string, options?: TypeScriptExportOptions): void {
+    const map = this.getExportMap(options?.type ?? 'export');
+    const existingExport = map.get(fromModule);
+    if (existingExport) {
+      existingExport.add(exportName);
+    } else {
+      map.set(fromModule, new Set([exportName]));
+    }
+  }
+
+  public clear(): void {
+    this._imports.clear();
+    this._typeImports.clear();
+    this._jsDocImports.clear();
+    this._exports.clear();
+    this._typeExports.clear();
+  }
+
+  public toString(options: Partial<SourceBuilderOptions>): string {
+    const builder = new StringBuilder(options);
+    this.writeTo(builder);
+    return builder.toString();
+  }
+
+  public writeTo(builder: StringBuilder) {
+    const { filePath, importModuleTransformer, useSingleQuotes } = this._options;
+    let hasPrevious = false;
+
+    if (this._imports.size > 0) {
+      const sortedImports = this.sortAndResolve(this._imports, filePath, importModuleTransformer);
+      this.writeImportsExports(builder, 'import', sortedImports, { useSingleQuotes });
+      hasPrevious = true;
+    }
+
+    if (this._typeImports.size > 0) {
+      if (hasPrevious) {
+        builder.appendLine();
+      }
+      const sortedImports = this.sortAndResolve(this._typeImports, filePath, importModuleTransformer);
+      this.writeImportsExports(builder, 'import type', sortedImports, { useSingleQuotes });
+      hasPrevious = true;
+    }
+
+    if (this._jsDocImports.size > 0) {
+      if (hasPrevious) {
+        builder.appendLine();
+      }
+      const sortedImports = this.sortAndResolve(this._jsDocImports, filePath, importModuleTransformer);
+      builder.appendLine('/**');
+      this.writeImportsExports(builder, ' * @import', sortedImports, { useSingleQuotes });
+      builder.appendLine(' */');
+      hasPrevious = true;
+    }
+
+    if (this._exports.size > 0) {
+      if (hasPrevious) {
+        builder.appendLine();
+      }
+      const sortedExports = this.sortAndResolve(this._exports, filePath, importModuleTransformer);
+      this.writeImportsExports(builder, 'export', sortedExports, { useSingleQuotes });
+      hasPrevious = true;
+    }
+
+    if (this._typeExports.size > 0) {
+      if (hasPrevious) {
+        builder.appendLine();
+      }
+      const sortedExports = this.sortAndResolve(this._typeExports, filePath, importModuleTransformer);
+      this.writeImportsExports(builder, 'export type', sortedExports, { useSingleQuotes });
+      hasPrevious = true;
+    }
+  }
+
+  protected writeImportsExports(
+    builder: StringBuilder,
+    keyword: 'import' | 'export' | 'import type' | 'export type' | ' * @import',
+    data: (readonly [string, TypeScriptImportKind, string[]])[],
+    options: { useSingleQuotes: boolean },
+  ) {
+    const moduleData: (readonly [string, TypeScriptImportKind, string[]])[] = [];
+    const fileData: (readonly [string, TypeScriptImportKind, string[]])[] = [];
+    for (const x of data) {
+      if (x[1] === 'module') {
+        moduleData.push(x);
+      } else {
+        fileData.push(x);
+      }
+    }
+
+    const quote = options.useSingleQuotes ? "'" : '"';
+
+    for (const [fromModule, _, names] of moduleData) {
+      builder.appendLine(`${keyword} { ${names.join(', ')} } from ${quote}${fromModule}${quote};`);
+    }
+
+    if (moduleData.length > 0 && fileData.length > 0) {
+      builder.appendLine();
+    }
+
+    for (const [fromModule, _, names] of fileData) {
+      builder.appendLine(`${keyword} { ${names.join(', ')} } from ${quote}${fromModule}${quote};`);
+    }
+  }
+
+  protected sortAndResolve(
+    data: Map<string, Set<string>>,
+    filePath: string | undefined,
+    importModuleTransformer: ImportModuleTransformer,
+  ): (readonly [string, TypeScriptImportKind, string[]])[] {
+    return Array.from(data.entries())
+      .sort(([fromModuleA], [fromModuleB]) => fromModuleA.localeCompare(fromModuleB))
+      .map(
+        ([fromModule, names]) =>
+          [...this.resolveModulePath(fromModule, filePath, importModuleTransformer), Array.from(names).sort()] as const,
+      );
+  }
+
+  protected getImportKind(fromModule: string): TypeScriptImportKind {
+    const extName = extname(fromModule).toUpperCase();
+    return extName === '.TS' || extName === '.JS' || extName === '.JSON' ? 'file' : 'module';
+  }
+
+  protected resolveModulePath(
+    fromModule: string,
+    filePath: string | undefined,
+    importModuleTransformer: ImportModuleTransformer,
+  ): [string, TypeScriptImportKind] {
+    const kind = this.getImportKind(fromModule);
+    return [
+      filePath && kind === 'file'
+        ? getModulePathRelativeToFile(filePath, fromModule, importModuleTransformer)
+        : fromModule,
+      kind,
+    ];
+  }
+
+  protected getImportMap(type: TypeScriptImportType): Map<string, Set<string>> {
+    switch (type) {
+      case 'import':
+        return this._imports;
+      case 'type-import':
+        return this._typeImports;
+      case 'js-doc':
+        return this._jsDocImports;
+    }
+  }
+
+  protected getExportMap(type: TypeScriptExportType): Map<string, Set<string>> {
+    switch (type) {
+      case 'export':
+        return this._exports;
+      case 'type-export':
+        return this._typeExports;
+    }
+  }
+}

package/src/src/utils.ts

@@ -0,0 +1,72 @@
+import { dirname, relative } from 'node:path';
+
+import type { Nullable } from '@goast/core';
+
+export type ImportModuleTransformer =
+  | 'omit-extension'
+  | 'with-extension'
+  | 'js-extension'
+  | ((module: string) => string);
+
+function doubleQuotedToSingleQuoted(value: string): string {
+  return `'${value.slice(1, -1).replace(/'/g, "\\'")}'`;
+}
+
+export function toTypeScriptStringLiteral(value: string, useSingleQuotes: boolean): string {
+  return useSingleQuotes ? doubleQuotedToSingleQuoted(JSON.stringify(value)) : JSON.stringify(value);
+}
+
+export function toTypeScriptPropertyName(value: string, useSingleQuotes: boolean): string {
+  if (value.match(/^[a-zA-Z_$][a-zA-Z_$0-9]*$/)) {
+    return value;
+  }
+  return useSingleQuotes ? doubleQuotedToSingleQuoted(JSON.stringify(value)) : JSON.stringify(value);
+}
+
+export function getModulePathRelativeToFile(from: string, to: string, transformer: ImportModuleTransformer): string {
+  return transformModulePath(relative(dirname(from), to).replace(/\\/g, '/'), transformer);
+}
+
+export function getModulePathRelativeToDirectory(
+  from: string,
+  to: string,
+  transformer: ImportModuleTransformer,
+): string {
+  return transformModulePath(relative(from, to).replace(/\\/g, '/'), transformer);
+}
+
+function transformModulePath(modulePath: string, transformer: ImportModuleTransformer) {
+  if (!modulePath.startsWith('.')) {
+    modulePath = `./${modulePath}`;
+  }
+
+  if (transformer === 'omit-extension') {
+    return modulePath.replace(/\.[^/.]+$/, '');
+  } else if (transformer === 'with-extension') {
+    return modulePath;
+  } else if (transformer === 'js-extension') {
+    return modulePath.replace(/\.[^/.]+$/, '.js');
+  } else if (typeof transformer === 'function') {
+    return transformer(modulePath);
+  }
+
+  return modulePath;
+}
+
+export function modifyString<TArgs extends unknown[]>(
+  value: string,
+  modifier: Nullable<string | RegExp | ((value: string, ...args: TArgs) => string)>,
+  ...args: TArgs
+): string {
+  if (typeof modifier === 'string') {
+    return modifier;
+  }
+  if (modifier instanceof RegExp) {
+    const match = value.match(modifier);
+    return match?.[0] ?? value;
+  }
+  if (typeof modifier === 'function') {
+    return modifier(value, ...args);
+  }
+  return value;
+}