@goast/typescript 0.4.1-beta1 → 0.4.1

package/src/src/generators/services/fetch-clients/fetch-client-generator.ts

@@ -0,0 +1,267 @@
+import { resolve } from 'node:path';
+
+import {
+  type ApiEndpoint,
+  type ApiSchema,
+  type AppendValueGroup,
+  appendValueGroup,
+  builderTemplate as s,
+  type MaybePromise,
+  toCasing,
+} from '@goast/core';
+
+import { ts } from '../../../ast/index.js';
+import { TypeScriptFileBuilder } from '../../../file-builder.js';
+import { TypeScriptFileGenerator } from '../../file-generator.js';
+import type { TypeScriptFetchClientGeneratorContext, TypeScriptFetchClientGeneratorOutput } from './models.js';
+
+type Context = TypeScriptFetchClientGeneratorContext;
+type Output = TypeScriptFetchClientGeneratorOutput;
+type Builder = TypeScriptFileBuilder;
+
+export interface TypeScriptFetchClientGenerator<TOutput extends Output = Output> {
+  generate(ctx: Context): MaybePromise<TOutput>;
+}
+
+export class DefaultTypeScriptFetchClientGenerator extends TypeScriptFileGenerator<Context, Output>
+  implements TypeScriptFetchClientGenerator {
+  public generate(ctx: Context): MaybePromise<Output> {
+    const result: Output = {};
+
+    if (this.shouldGenerateInterface(ctx)) {
+      const filePath = this.getInterfaceFilePath(ctx);
+      const name = this.getInterfaceName(ctx);
+
+      TypeScriptFileBuilder.generate({
+        logName: `interface ${name}`,
+        filePath,
+        options: ctx.config,
+        generator: (b) => b.append(this.getInterfaceFileContent(ctx)),
+      });
+
+      result.clientInterface = { filePath, component: name };
+    }
+
+    if (this.shouldGenerateClass(ctx)) {
+      const filePath = this.getClassFilePath(ctx);
+      const name = this.getClassName(ctx);
+
+      TypeScriptFileBuilder.generate({
+        logName: `class ${name}`,
+        filePath,
+        options: ctx.config,
+        generator: (b) => b.append(this.getClassFileContent(ctx)),
+      });
+
+      result.client = { filePath, component: name };
+    }
+
+    return result;
+  }
+
+  // #region Interface
+  protected getInterfaceFileContent(ctx: Context): AppendValueGroup<Builder> {
+    return appendValueGroup([this.getInterface(ctx)], '\n');
+  }
+
+  protected getInterface(ctx: Context): ts.Interface<Builder> {
+    return ts.interface(this.getInterfaceName(ctx), {
+      doc: ts.doc({
+        description: ctx.service.description,
+        tags: [
+          ctx.service.endpoints.length === 0 || ctx.service.endpoints.some((x) => !x.deprecated)
+            ? null
+            : ts.docTag('deprecated'),
+        ],
+      }),
+      export: true,
+      members: ctx.service.endpoints.map((endpoint) => this.getInterfaceEndpointMethod(ctx, endpoint)),
+    });
+  }
+
+  protected getInterfaceEndpointMethod(ctx: Context, endpoint: ApiEndpoint): ts.Method<Builder> {
+    const params = endpoint.parameters.filter((x) => x.target === 'path' || x.target === 'query');
+    const bodySchema = endpoint.requestBody?.content[0]?.schema;
+    const responseSchema = this.getResponseSchema(ctx, endpoint);
+    return ts.method(toCasing(endpoint.name, ctx.config.functionNameCasing), {
+      doc: ts.doc({ description: endpoint.description, tags: [endpoint.deprecated ? ts.docTag('deprecated') : null] }),
+      parameters: [
+        params.length > 0
+          ? ts.parameter('params', {
+            description: 'Parameters for the endpoint.',
+            type: ts.objectType({
+              members: params.map((x) =>
+                ts.property(toCasing(x.name, ctx.config.propertyNameCasing), {
+                  doc: ts.doc({ tags: [x.deprecated ? ts.docTag('deprecated') : null] }),
+                  type: this.getSchemaType(ctx, x.schema),
+                  optional: !x.required,
+                })
+              ),
+            }),
+          })
+          : null,
+        bodySchema &&
+        ts.parameter('body', {
+          description: 'Body for the endpoint.',
+          type: this.getSchemaType(ctx, bodySchema),
+        }),
+      ],
+      returnType: ts.refs.promise([ctx.refs.typedResponse([this.getSchemaType(ctx, responseSchema, ts.refs.void_())])]),
+    });
+  }
+  // #endregion
+
+  // #region Class
+  protected getClassFileContent(ctx: Context): AppendValueGroup<Builder> {
+    return appendValueGroup([this.getDefaultOptionsConstant(ctx), this.getClass(ctx)], '\n');
+  }
+
+  protected getDefaultOptionsConstant(ctx: Context): ts.Variable<Builder> {
+    const baseUrl = ctx.service.endpoints.map((x) => x.$src?.document.servers?.find((x) => x.url)?.url).find((x) =>
+      !!x
+    );
+    return ts.variable(this.getDefaultOptionsConstantName(ctx), {
+      export: true,
+      readonly: true,
+      type: ctx.refs.fetchClientOptions(),
+      value: ts.object({
+        members: [baseUrl && ts.property('baseUrl', { value: ts.string(baseUrl) })],
+      }),
+    });
+  }
+
+  protected getClass(ctx: Context): ts.Class<Builder> {
+    return ts.class(this.getClassName(ctx), {
+      doc: ts.doc({
+        description: ctx.service.description,
+        tags: [
+          ctx.service.endpoints.length === 0 || ctx.service.endpoints.some((x) => !x.deprecated)
+            ? null
+            : ts.docTag('deprecated'),
+        ],
+      }),
+      export: true,
+      implements: this.shouldGenerateInterface(ctx)
+        ? [ts.reference(this.getInterfaceName(ctx), this.getInterfaceFilePath(ctx))]
+        : undefined,
+      members: [
+        ts.property('options', {
+          doc: ts.doc({ description: 'Options for the fetch client.' }),
+          accessModifier: 'public',
+          type: ctx.refs.fetchClientOptions(),
+        }),
+        ts.constructor({
+          parameters: [
+            ts.constructorParameter('options', {
+              type: ts.refs.partial([ctx.refs.fetchClientOptions()]),
+              optional: true,
+            }),
+          ],
+          body: appendValueGroup(
+            [s`this.options = { ...${this.getDefaultOptionsConstantName(ctx)}, ...options };`],
+            '\n',
+          ),
+        }),
+        ...ctx.service.endpoints.map((endpoint) => this.getServiceMethod(ctx, endpoint)),
+      ],
+    });
+  }
+
+  protected getServiceMethod(ctx: Context, endpoint: ApiEndpoint): ts.Method<Builder> {
+    const method = this.getInterfaceEndpointMethod(ctx, endpoint);
+    method.accessModifier = 'public';
+    method.body = appendValueGroup(
+      [
+        s`const url = new ${ctx.refs.urlBuilder()}(this.options.baseUrl)${s.indent`
+          .withPath(${ts.string(endpoint.path)})${(b) =>
+          b.forEach(endpoint.parameters, (b, p) => {
+            switch (p.target) {
+              case 'path':
+                b.append(
+                  s<Builder>`\n.withPathParam(${ts.string(p.name)}, params.${
+                    toCasing(p.name, ctx.config.paramNameCasing)
+                  })`,
+                );
+                break;
+              case 'query':
+                b.append(
+                  s<Builder>`\n.withQueryParam(${ts.string(p.name)}, params.${
+                    toCasing(p.name, ctx.config.paramNameCasing)
+                  })`,
+                );
+                break;
+            }
+          })}
+          .build();`}`,
+        s`const response = (this.options.fetch ?? fetch)(url, ${
+          ts.object({
+            members: [
+              ts.property('method', { value: ts.string(toCasing(endpoint.method, 'all-upper')) }),
+              ts.property('headers', { value: 'this.options.headers' }),
+              endpoint.requestBody?.content[0]?.schema ? ts.property('body', { value: 'JSON.stringify(body)' }) : null,
+            ],
+          })
+        });`,
+        s`Object.defineProperty(response, 'isVoidResponse', { value: ${
+          this.getResponseSchema(ctx, endpoint) ? 'false' : 'true'
+        } });`,
+        s`return response as unknown as ${method.returnType ?? 'unknown'};`,
+      ],
+      '\n',
+    );
+    return method;
+  }
+  // #endregion
+
+  protected getSchemaType(ctx: Context, schema: ApiSchema | undefined, fallback?: ts.Type<Builder>): ts.Type<Builder> {
+    const output = schema && ctx.input.typescript.models[schema.id];
+    if (!output) return fallback ?? this.getAnyType(ctx);
+    return (b) => b.appendModelUsage(output);
+  }
+
+  protected shouldGenerateInterface(ctx: Context): boolean {
+    return ctx.config.clientFileKind === 'interface' || ctx.config.clientFileKind === 'class-and-interface';
+  }
+
+  protected shouldGenerateClass(ctx: Context): boolean {
+    return ctx.config.clientFileKind === 'class' || ctx.config.clientFileKind === 'class-and-interface';
+  }
+
+  protected getInterfaceName(ctx: Context): string {
+    return toCasing(ctx.service.name, ctx.config.clientInterfaceNameCasing ?? ctx.config.typeNameCasing);
+  }
+
+  protected getClassName(ctx: Context): string {
+    return toCasing(ctx.service.name, ctx.config.clientNameCasing ?? ctx.config.typeNameCasing);
+  }
+
+  protected getDefaultOptionsConstantName(ctx: Context): string {
+    return toCasing(this.getClassName(ctx) + '-default-options', ctx.config.constantNameCasing);
+  }
+
+  protected getInterfaceFilePath(ctx: Context): string {
+    return resolve(
+      ctx.config.outputDir,
+      ctx.config.clientInterfaceDir ?? ctx.config.clientDir,
+      `${toCasing(ctx.service.name, ctx.config.clientInterfaceFileNameCasing ?? ctx.config.fileNameCasing)}.ts`,
+    );
+  }
+
+  protected getClassFilePath(ctx: Context): string {
+    return resolve(
+      ctx.config.outputDir,
+      ctx.config.clientDir,
+      `${toCasing(ctx.service.name, ctx.config.clientFileNameCasing ?? ctx.config.fileNameCasing)}.ts`,
+    );
+  }
+
+  protected getUtilPath(ctx: Context, fileName: string): string {
+    return resolve(ctx.config.outputDir, ctx.config.utilsDir, fileName);
+  }
+
+  private getResponseSchema(_ctx: Context, endpoint: ApiEndpoint) {
+    const successResponse = endpoint.responses.find((x) => x.statusCode === 200) ??
+      endpoint.responses.find((x) => x.statusCode && x.statusCode > 200 && x.statusCode < 300);
+    return successResponse?.contentOptions?.find((x) => x.schema !== undefined)?.schema;
+  }
+}

package/src/src/generators/services/fetch-clients/fetch-clients-generator.ts

@@ -0,0 +1,163 @@
+import { resolve } from 'node:path';
+
+
+import fs from 'fs-extra';
+
+import {
+  type ApiService,
+  type AppendValueGroup,
+  appendValueGroup,
+  Factory,
+  type MaybePromise,
+  notNullish,
+  type OpenApiGeneratorContext,
+  OpenApiServicesGenerationProviderBase,
+} from '@goast/core';
+
+import { copyAssetFile } from '../../../assets.js';
+import { ts } from '../../../ast/index.js';
+import { TypeScriptFileBuilder } from '../../../file-builder.js';
+import {
+  DefaultTypeScriptFetchClientGenerator,
+  type TypeScriptFetchClientGenerator,
+} from './fetch-client-generator.js';
+import {
+  defaultTypeScriptFetchClientsGeneratorConfig,
+  type TypeScriptFetchClientGeneratorOutput,
+  type TypeScriptFetchClientsGeneratorConfig,
+  type TypeScriptFetchClientsGeneratorContext,
+  type TypeScriptFetchClientsGeneratorInput,
+  type TypeScriptFetchClientsGeneratorOutput,
+} from './models.js';
+import { getReferenceFactories } from './refs.js';
+
+type Input = TypeScriptFetchClientsGeneratorInput;
+type Output = TypeScriptFetchClientsGeneratorOutput;
+type Config = TypeScriptFetchClientsGeneratorConfig;
+type ServiceOutput = TypeScriptFetchClientGeneratorOutput;
+type Context = TypeScriptFetchClientsGeneratorContext;
+
+export class TypeScriptFetchClientsGenerator extends OpenApiServicesGenerationProviderBase<
+  Input,
+  Output,
+  Config,
+  ServiceOutput,
+  Context
+> {
+  private readonly _clientGeneratorFactory: Factory<TypeScriptFetchClientGenerator, []>;
+
+  constructor(clientGeneratorFactory?: Factory<TypeScriptFetchClientGenerator, []>) {
+    super();
+    this._clientGeneratorFactory = clientGeneratorFactory ??
+      Factory.fromValue(new DefaultTypeScriptFetchClientGenerator());
+  }
+
+  protected override initResult(): Output {
+    return {
+      typescript: {
+        clients: {},
+        indexFiles: {
+          clients: undefined,
+          clientInterfaces: undefined,
+        },
+      },
+    };
+  }
+
+  protected override buildContext(
+    context: OpenApiGeneratorContext<Input>,
+    config?: Partial<Config> | undefined,
+  ): Context {
+    const providerContext = this.getProviderContext(context, config, defaultTypeScriptFetchClientsGeneratorConfig);
+    return Object.assign(providerContext, {
+      refs: getReferenceFactories(providerContext.config),
+    });
+  }
+
+  protected override async generateAdditionalFiles(ctx: TypeScriptFetchClientsGeneratorContext): Promise<void> {
+    await this.copyUtilsFiles(ctx);
+    ctx.output.typescript.indexFiles.clients = this.generateIndexFile(ctx);
+    ctx.output.typescript.indexFiles.clientInterfaces = this.generateInterfaceIndexFile(ctx);
+  }
+
+  protected override generateService(ctx: Context, service: ApiService): MaybePromise<ServiceOutput> {
+    const clientGenerator = this._clientGeneratorFactory.create();
+    return clientGenerator.generate({
+      ...ctx,
+      service,
+    });
+  }
+
+  protected override addServiceResult(ctx: Context, service: ApiService, result: ServiceOutput): void {
+    ctx.output.typescript.clients[service.id] = result;
+  }
+
+  protected generateIndexFile(ctx: Context): string | null {
+    const filePath = this.getIndexFilePath(ctx);
+
+    TypeScriptFileBuilder.tryGenerate({
+      logName: 'clients index file',
+      filePath,
+      options: ctx.config,
+      generator: (b) => b.append(this.getIndexFileContent(ctx)),
+    });
+
+    return filePath;
+  }
+
+  protected generateInterfaceIndexFile(ctx: Context): string | null {
+    const filePath = this.getInterfaceIndexFilePath(ctx);
+    const clientsFilePath = this.getIndexFilePath(ctx);
+
+    if (filePath && filePath === clientsFilePath) {
+      return clientsFilePath;
+    }
+
+    TypeScriptFileBuilder.tryGenerate({
+      logName: 'client interfaces index file',
+      filePath,
+      options: ctx.config,
+      generator: (b) => b.append(this.getInterfaceIndexFileContent(ctx)),
+    });
+
+    return filePath;
+  }
+
+  protected getIndexFilePath(ctx: Context): string | null {
+    return ctx.config.clientsIndexFile ? resolve(ctx.config.outputDir, ctx.config.clientsIndexFile) : null;
+  }
+
+  protected getInterfaceIndexFilePath(ctx: Context): string | null {
+    return ctx.config.clientInterfacesIndexFile
+      ? resolve(ctx.config.outputDir, ctx.config.clientInterfacesIndexFile)
+      : null;
+  }
+
+  protected getIndexFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    const cIndexPath = this.getIndexFilePath(ctx);
+    const iIndexPath = this.getInterfaceIndexFilePath(ctx);
+    return appendValueGroup(
+      (iIndexPath && iIndexPath === cIndexPath
+        ? Object.values(ctx.output.typescript.clients).flatMap((c) => [c.client, c.clientInterface])
+        : Object.values(ctx.output.typescript.clients).map((c) => c.client))
+        .filter(notNullish)
+        .map((x) => ts.export(x.component, x.filePath)),
+    );
+  }
+
+  protected getInterfaceIndexFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    return appendValueGroup(
+      Object.values(ctx.output.typescript.clients)
+        .map((c) => c.clientInterface)
+        .filter(notNullish)
+        .map((x) => ts.export(x.component, x.filePath)),
+    );
+  }
+
+  private async copyUtilsFiles(ctx: Context): Promise<void> {
+    const targetDir = resolve(ctx.config.outputDir, ctx.config.utilsDir);
+    await fs.ensureDir(targetDir);
+
+    await copyAssetFile('client/fetch/fetch-client.utils.ts', targetDir);
+  }
+}

package/src/src/generators/services/fetch-clients/index.ts

@@ -0,0 +1,3 @@
+export * from './fetch-client-generator.js';
+export * from './fetch-clients-generator.js';
+export * from './models.js';

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

@@ -0,0 +1,130 @@
+import type {
+  ApiService,
+  DefaultGenerationProviderConfig,
+  ExtendedStringCasing,
+  Nullable,
+  OpenApiServicesGenerationProviderContext,
+} from '@goast/core';
+
+import type { TypeScriptExportOutput } from '../../../common-results.js';
+import { defaultTypeScriptGeneratorConfig, type TypeScriptGeneratorConfig } from '../../../config.js';
+import type { TypeScriptModelsGeneratorOutput } from '../../models/models.js';
+import type { getReferenceFactories } from './refs.js';
+
+export type TypeScriptFetchClientsGeneratorConfig = TypeScriptGeneratorConfig & {
+  /**
+   * 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 client interface file names. If nullish, the `fileNameCasing` is used.
+   * @default { casing: 'kebab', suffix: '-client' }
+   */
+  clientInterfaceFileNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * The casing of the client names. If nullish, the `typeNameCasing` is used.
+   * @default { casing: 'pascal', suffix: 'Client' }
+   */
+  clientNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * The casing of the client interface names. If nullish, the `typeNameCasing` is used.
+   * @default { prefix: 'I', casing: 'pascal', suffix: 'Client' }
+   */
+  clientInterfaceNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * Determines how the client files should be generated.
+   * - `interface` - generates only the interface
+   * - `class` - generates only the class
+   * - `class-and-interface` - generates both the class and the interface
+   * @default 'class'
+   */
+  clientFileKind: 'interface' | 'class' | 'class-and-interface';
+
+  /**
+   * 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 client interface files should be saved. The path is relative to the output directory.
+   * @default 'clients/interfaces'
+   */
+  clientInterfaceDir: Nullable<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 index file where all client interfaces should be exported. The path is relative to the output directory. If nullish, no index file will be generated.
+   * @default 'clients.ts'
+   */
+  clientInterfacesIndexFile: Nullable<string>;
+
+  /**
+   * The directory where the utilies should be saved. The path is relative to the output directory.
+   * @default 'utils'
+   */
+  utilsDir: string;
+};
+
+export const defaultTypeScriptFetchClientsGeneratorConfig: DefaultGenerationProviderConfig<
+  TypeScriptFetchClientsGeneratorConfig
+> = {
+  ...defaultTypeScriptGeneratorConfig,
+
+  clientFileNameCasing: { casing: 'kebab', suffix: '-client' },
+  clientInterfaceFileNameCasing: undefined,
+
+  clientNameCasing: { casing: 'pascal', suffix: 'Client' },
+  clientInterfaceNameCasing: { prefix: 'I', casing: 'pascal', suffix: 'Client' },
+
+  clientFileKind: 'class',
+  clientDir: 'clients',
+  clientInterfaceDir: 'clients/interfaces',
+  clientsIndexFile: 'clients.ts',
+  clientInterfacesIndexFile: 'clients.ts',
+  utilsDir: 'utils',
+};
+
+export type TypeScriptFetchClientsGeneratorInput = TypeScriptModelsGeneratorOutput;
+
+export type TypeScriptFetchClientsGeneratorOutput = {
+  typescript: {
+    clients: {
+      [serviceId: string]: TypeScriptFetchClientGeneratorOutput;
+    };
+    indexFiles: {
+      clients: Nullable<string>;
+      clientInterfaces: Nullable<string>;
+    };
+  };
+};
+
+export type TypeScriptFetchClientGeneratorOutput = {
+  client?: TypeScriptExportOutput;
+  clientInterface?: TypeScriptExportOutput;
+};
+
+export type TypeScriptFetchClientsGeneratorContext =
+  & OpenApiServicesGenerationProviderContext<
+    TypeScriptFetchClientsGeneratorInput,
+    TypeScriptFetchClientsGeneratorOutput,
+    TypeScriptFetchClientsGeneratorConfig,
+    TypeScriptFetchClientGeneratorOutput
+  >
+  & {
+    refs: ReturnType<typeof getReferenceFactories>;
+  };
+
+export type TypeScriptFetchClientGeneratorContext = TypeScriptFetchClientsGeneratorContext & {
+  readonly service: ApiService;
+};

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

@@ -0,0 +1,21 @@
+import { resolve } from 'node:path';
+
+import { ts } from '../../../ast/index.js';
+import type { TypeScriptFetchClientsGeneratorConfig } from './models.js';
+
+// See packages/typescript/assets/client/fetch for reference
+export function getReferenceFactories(options: TypeScriptFetchClientsGeneratorConfig): {
+  typedResponse: ts.GenericModuleReferenceFactory<1>;
+  fetchClientOptions: ts.ModuleReferenceFactory;
+  urlBuilder: ts.ModuleReferenceFactory;
+} {
+  const utilsDirPath = resolve(options.outputDir, options.utilsDir);
+  const fetchClientUtilsPath = resolve(utilsDirPath, 'fetch-client.utils.ts');
+
+  return {
+    // fetch-client.utils.ts
+    typedResponse: ts.reference.genericFactory<1>('TypedResponse', fetchClientUtilsPath, { importType: 'type-import' }),
+    fetchClientOptions: ts.reference.factory('FetchClientOptions', fetchClientUtilsPath, { importType: 'type-import' }),
+    urlBuilder: ts.reference.factory('UrlBuilder', fetchClientUtilsPath),
+  };
+}

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

@@ -0,0 +1,3 @@
+export * from './k6-client-generator.js';
+export * from './k6-clients-generator.js';
+export * from './models.js';