@goast/typescript 0.4.3 → 0.5.0

package/src/src/generators/services/angular-services/angular-services-generator.ts

@@ -0,0 +1,295 @@
+import { resolve } from 'node:path';
+
+
+import fs from 'fs-extra';
+
+import {
+  type ApiService,
+  type AppendValueGroup,
+  appendValueGroup,
+  Factory,
+  type MaybePromise,
+  type OpenApiGeneratorContext,
+  OpenApiServicesGenerationProviderBase,
+  toCasing,
+} from '@goast/core';
+
+import { copyAssetFile } from '../../../assets.js';
+import { ts } from '../../../ast/index.js';
+import { TypeScriptFileBuilder } from '../../../file-builder.js';
+import { modifyString } from '../../../utils.js';
+import {
+  DefaultTypeScriptAngularServiceGenerator,
+  type TypeScriptAngularServiceGenerator,
+} from './angular-service-generator.js';
+import {
+  defaultTypeScriptAngularServicesGeneratorConfig,
+  type TypeScriptAngularServiceGeneratorOutput,
+  type TypeScriptAngularServicesGeneratorConfig,
+  type TypeScriptAngularServicesGeneratorContext,
+  type TypeScriptAngularServicesGeneratorInput,
+  type TypeScriptAngularServicesGeneratorOutput,
+} from './models.js';
+import { getReferenceFactories } from './refs.js';
+
+type Input = TypeScriptAngularServicesGeneratorInput;
+type Output = TypeScriptAngularServicesGeneratorOutput;
+type Config = TypeScriptAngularServicesGeneratorConfig;
+type ServiceOutput = TypeScriptAngularServiceGeneratorOutput;
+type Context = TypeScriptAngularServicesGeneratorContext;
+
+export class TypeScriptAngularServicesGenerator extends OpenApiServicesGenerationProviderBase<
+  Input,
+  Output,
+  Config,
+  ServiceOutput,
+  Context
+> {
+  private readonly _clientGeneratorFactory: Factory<TypeScriptAngularServiceGenerator, []>;
+
+  constructor(clientGeneratorFactory?: Factory<TypeScriptAngularServiceGenerator, []>) {
+    super();
+    this._clientGeneratorFactory = clientGeneratorFactory ??
+      Factory.fromValue(new DefaultTypeScriptAngularServiceGenerator());
+  }
+
+  protected override initResult(): Output {
+    return {
+      typescript: {
+        services: {},
+        indexFiles: { services: undefined, responseModels: undefined },
+      },
+    };
+  }
+
+  protected override buildContext(
+    context: OpenApiGeneratorContext<Input>,
+    config?: Partial<Config> | undefined,
+  ): Context {
+    const providerContext = this.getProviderContext(context, config, defaultTypeScriptAngularServicesGeneratorConfig);
+    return Object.assign(providerContext, {
+      refs: getReferenceFactories(providerContext.config),
+    });
+  }
+
+  protected override async generateAdditionalFiles(ctx: TypeScriptAngularServicesGeneratorContext): Promise<void> {
+    await this.generateUtilsFiles(ctx);
+    ctx.output.typescript.indexFiles = this.generateIndexFiles(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.services[service.id] = result;
+  }
+
+  // #region Utils
+  protected async generateUtilsFiles(ctx: Context): Promise<void> {
+    const targetDir = resolve(ctx.config.outputDir, ctx.config.utilsDir);
+    await fs.ensureDir(targetDir);
+
+    await copyAssetFile('client/angular/request-builder.ts', targetDir, 'Request Builder');
+    await copyAssetFile('client/angular/angular-service.utils.ts', targetDir, 'Angular Service Utils');
+
+    TypeScriptFileBuilder.generate({
+      logName: 'api configuration',
+      filePath: resolve(targetDir, 'api-configuration.ts'),
+      options: ctx.config,
+      generator: (b) => b.append(this.getApiConfigurationFileContent(ctx)),
+    });
+
+    TypeScriptFileBuilder.generate({
+      logName: 'api base service',
+      filePath: resolve(targetDir, 'api-base-service.ts'),
+      options: ctx.config,
+      generator: (b) => b.append(this.getApiBaseServiceFileContent(ctx)),
+    });
+
+    if (!ctx.config.strictResponseTypes) {
+      TypeScriptFileBuilder.generate({
+        logName: 'http status codes',
+        filePath: resolve(targetDir, 'http-status-code.ts'),
+        options: ctx.config,
+        generator: (b) => b.append(this.getHttpStatusCodeFileContent(ctx)),
+      });
+    }
+
+    if (ctx.config.provideKind === 'provide-fn') {
+      TypeScriptFileBuilder.generate({
+        logName: 'providers',
+        filePath: resolve(targetDir, 'provide.ts'),
+        options: ctx.config,
+        generator: (b) => b.append(this.getProvideFnFileContent(ctx)),
+      });
+    }
+  }
+
+  protected getApiConfigurationFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    return appendValueGroup(
+      [
+        ts.class(toCasing(`${ctx.config.domainName ?? ''}ApiConfiguration`, ctx.config.typeNameCasing), {
+          doc: ts.doc({ description: `${ctx.config.domainName ?? 'Global'} API Configuration.` }),
+          decorators: [
+            ts.decorator(ts.refs.angular.injectable(), [
+              ctx.config.provideKind === 'root' ? ts.toNode({ providedIn: 'root' }) : null,
+            ]),
+          ],
+          export: true,
+          members: [
+            ts.property('rootUrl', {
+              accessModifier: 'public',
+              type: ts.refs.string(),
+              value: ts.string(this.getRootUrl(ctx)),
+            }),
+          ],
+        }),
+      ],
+      '\n',
+    );
+  }
+
+  protected getApiBaseServiceFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    return appendValueGroup(
+      [
+        ts.class('ApiBaseService', {
+          doc: ts.doc({ description: 'Base class for API services.' }),
+          export: true,
+          abstract: true,
+          members: [
+            ts.property('config', {
+              accessModifier: 'protected',
+              value: (b) => b.append(ts.refs.angular.inject(), '(', ctx.refs.apiConfiguration(), ')'),
+            }),
+            ts.property('http', {
+              accessModifier: 'protected',
+              value: (b) => b.append(ts.refs.angular.inject(), '(', ts.refs.angular.httpClient(), ')'),
+            }),
+            ts.property('_rootUrl', { accessModifier: 'private', type: ts.refs.string(), value: ts.string('') }),
+            ts.property('rootUrl', {
+              doc: ts.doc({
+                description:
+                  `Gets or sets the root URL for API operations provided by this service.\nFalls back to \`${ctx.refs.apiConfiguration.refName}.rootUrl\` if not set in this service.`,
+              }),
+              accessModifier: 'public',
+              type: ts.refs.string(),
+              get: ts.property.getter({ body: 'return this._rootUrl || this.config.rootUrl;' }),
+              set: ts.property.setter({ body: 'this._rootUrl = value;' }),
+            }),
+          ],
+        }),
+      ],
+      '\n',
+    );
+  }
+
+  protected getHttpStatusCodeFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    return appendValueGroup(
+      [
+        ts.typeAlias('HttpStatusCode', ts.unionType(ctx.config.possibleStatusCodes), {
+          doc: ts.doc({ description: 'The possible status codes that any API endpoint can return.' }),
+          export: true,
+        }),
+      ],
+      '\n',
+    );
+  }
+
+  protected getProvideFnFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    return appendValueGroup(
+      [
+        ts.function(toCasing(`provide_${ctx.config.domainName ?? ''}_Api`, ctx.config.functionNameCasing), {
+          doc: ts.doc({
+            description: 'Provides all the API services' +
+              (ctx.config.domainName ? ` for ${ctx.config.domainName}` : '') + '.',
+          }),
+          export: true,
+          parameters: [ts.parameter('config', { type: ctx.refs.apiConfiguration(), optional: true })],
+          returnType: ts.refs.angular.provider(),
+          body: appendValueGroup([
+            'return ',
+            ts.tuple([
+              (b) =>
+                b.append(
+                  'config ? { provide: ',
+                  ctx.refs.apiConfiguration(),
+                  ', useValue: config } : ',
+                  ctx.refs.apiConfiguration(),
+                ),
+              ...Object.values(ctx.output.typescript.services).map((x) => ts.reference(x.component, x.filePath)),
+            ]),
+            ';',
+          ]),
+        }),
+      ],
+      '\n',
+    );
+  }
+
+  protected getRootUrl(ctx: Context): string {
+    return modifyString<[]>(
+      (ctx.data.services[0].$src ?? ctx.data.services[0].endpoints[0]?.$src)?.document.servers?.[0]?.url ?? '/',
+      ctx.config.rootUrl,
+    );
+  }
+  // #endregion
+
+  // #region Index
+  protected generateIndexFiles(ctx: Context): Output['typescript']['indexFiles'] {
+    const servicesIndexFilePath = this.getServicesIndexFilePath(ctx);
+    const responseModelsIndexFilePath = this.getResponseModelsIndexFilePath(ctx);
+
+    TypeScriptFileBuilder.tryGenerate({
+      logName: 'services index file',
+      filePath: servicesIndexFilePath,
+      options: ctx.config,
+      generator: (b) => b.append(this.getServicesIndexFileContent(ctx)),
+    });
+
+    TypeScriptFileBuilder.tryGenerate({
+      logName: 'response models index file',
+      filePath: responseModelsIndexFilePath,
+      options: ctx.config,
+      generator: (b) => b.append(this.getResponseModelsIndexFileContent(ctx)),
+    });
+
+    return {
+      services: servicesIndexFilePath,
+      responseModels: responseModelsIndexFilePath,
+    };
+  }
+
+  protected getServicesIndexFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    return appendValueGroup([
+      ts.export(ctx.refs.apiConfiguration.refName, ctx.refs.apiConfiguration.moduleNameOrfilePath),
+      ctx.config.provideKind === 'provide-fn'
+        ? ts.export(ctx.refs.provide.refName, ctx.refs.provide.moduleNameOrfilePath)
+        : null,
+      ...Object.values(ctx.output.typescript.services).map((x) => ts.export(x.component, x.filePath)),
+    ]);
+  }
+
+  protected getResponseModelsIndexFileContent(ctx: Context): AppendValueGroup<TypeScriptFileBuilder> {
+    return appendValueGroup(
+      Object.values(ctx.output.typescript.services)
+        .flatMap((x) => Object.values(x.responseModels))
+        .map((x) => ts.export(x.component, x.filePath, { kind: 'type-export' })),
+    );
+  }
+
+  protected getServicesIndexFilePath(ctx: Context): string | null {
+    return ctx.config.servicesIndexFile ? resolve(ctx.config.outputDir, ctx.config.servicesIndexFile) : null;
+  }
+
+  protected getResponseModelsIndexFilePath(ctx: Context): string | null {
+    return ctx.config.responseModelsIndexFile
+      ? resolve(ctx.config.outputDir, ctx.config.responseModelsIndexFile)
+      : null;
+  }
+  // #endregion
+}

package/src/src/generators/services/angular-services/index.ts

@@ -0,0 +1,3 @@
+export * from './angular-service-generator.js';
+export * from './angular-services-generator.js';
+export * from './models.js';

package/src/src/generators/services/angular-services/models.ts

@@ -0,0 +1,277 @@
+import type {
+  ApiEndpoint,
+  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 { TypeScriptModelGeneratorOutput } from '../../models/index.js';
+import type { getReferenceFactories } from './refs.js';
+
+export type TypeScriptAngularServicesGeneratorConfig = TypeScriptGeneratorConfig & {
+  /**
+   * How the services should be provided in the Angular application.
+   * - `root` - provides all the services using `Injectable({ providedIn: 'root' })`
+   * - `provide-fn` - generates a function `provideApiClients` that provides the services
+   * @default 'root'
+   */
+  provideKind: 'root' | 'provide-fn';
+
+  /**
+   * The domain name of the API. Used as a prefix for exported components (e.g. `ApiConfiguration`).
+   * @default undefined
+   */
+  domainName: Nullable<string>;
+
+  /**
+   * 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 default content type which is used for the request. If not defined the first one defined in the OpenApi specification is used.
+   * @default undefined
+   */
+  defaultRequestContentType: Nullable<string>;
+
+  /**
+   * The default content type which is used for the success response. If not defined the first one defined in the OpenApi specification is used.
+   * @default undefined
+   */
+  defaultSuccessResponseContentType: Nullable<string>;
+
+  /**
+   * 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[];
+
+  /**
+   * Explicitly set the root URL of the API. If `undefined`, the root URL is taken from the first `server` in the OpenAPI specification.
+   * @default undefined
+   */
+  rootUrl: Nullable<string | RegExp | ((rootUrl: string) => string)>;
+
+  /**
+   * Modifier that is applied to the path of each endpoint.
+   * @default undefined
+   */
+  pathModifier: Nullable<RegExp | ((path: string, endpoint: ApiEndpoint) => string)>;
+
+  /**
+   * The directory where the services should be saved. The path is relative to the output directory.
+   * @default 'services'
+   */
+  servicesDir: string;
+
+  /**
+   * The casing of the file names for the services. If nullish, the `fileNameCasing` is used.
+   * @default { casing: 'kebab', suffix: '.service' }
+   */
+  serviceFileNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * The path to the index file where all services should be exported. The path is relative to the output directory. If nullish, no index file will be generated.
+   * @default 'services.ts'
+   */
+  servicesIndexFile: Nullable<string>;
+
+  /**
+   * The directory where the response models should be saved. The path is relative to the output directory.
+   * @default 'models/responses'
+   */
+  responseModelsDir: string;
+
+  /**
+   * The casing of the file names for the response models. If nullish, the `fileNameCasing` is used.
+   * @default { casing: 'kebab', suffix: '-responses.model' }
+   */
+  responseModelFileNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * 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;
+};
+
+export const defaultTypeScriptAngularServicesGeneratorConfig: DefaultGenerationProviderConfig<
+  TypeScriptAngularServicesGeneratorConfig
+> = {
+  ...defaultTypeScriptGeneratorConfig,
+
+  provideKind: 'provide-fn',
+  domainName: undefined,
+  strictResponseTypes: true,
+  defaultStatusCodeResponseTypes: {
+    401: null,
+    403: null,
+    500: null,
+  },
+  defaultRequestContentType: undefined,
+  defaultSuccessResponseContentType: undefined,
+  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,
+  ],
+  rootUrl: undefined,
+  pathModifier: undefined,
+
+  servicesDir: 'services',
+  serviceFileNameCasing: { casing: 'kebab', suffix: '.service' },
+  servicesIndexFile: 'services.ts',
+  responseModelsDir: 'models/responses',
+  responseModelFileNameCasing: { casing: 'kebab', suffix: '-responses.model' },
+  responseModelsIndexFile: 'responses.ts',
+  utilsDir: 'utils',
+};
+
+export type TypeScriptAngularServicesGeneratorInput = {
+  typescript: {
+    models: {
+      [schemaId: string]: TypeScriptModelGeneratorOutput;
+    };
+  };
+};
+
+export type TypeScriptAngularServicesGeneratorOutput = {
+  typescript: {
+    services: {
+      [serviceId: string]: TypeScriptAngularServiceGeneratorOutput;
+    };
+    indexFiles: {
+      services: Nullable<string>;
+      responseModels: Nullable<string>;
+    };
+  };
+};
+
+export type TypeScriptAngularServiceGeneratorOutput = TypeScriptExportOutput & {
+  responseModels: {
+    [operationId: string]: TypeScriptExportOutput;
+  };
+};
+
+export type TypeScriptAngularServicesGeneratorContext =
+  & OpenApiServicesGenerationProviderContext<
+    TypeScriptAngularServicesGeneratorInput,
+    TypeScriptAngularServicesGeneratorOutput,
+    TypeScriptAngularServicesGeneratorConfig,
+    TypeScriptAngularServiceGeneratorOutput
+  >
+  & {
+    refs: ReturnType<typeof getReferenceFactories>;
+  };
+
+export type TypeScriptAngularServiceGeneratorContext = TypeScriptAngularServicesGeneratorContext & {
+  readonly service: ApiService;
+};

package/src/src/generators/services/angular-services/refs.ts

@@ -0,0 +1,54 @@
+import { join, resolve } from 'node:path';
+
+import { toCasing } from '@goast/core';
+
+import { ts } from '../../../ast/index.js';
+
+import type { TypeScriptAngularServicesGeneratorConfig } from './models.js';
+
+// See packages/typescript/assets/client/angular for reference
+export function getReferenceFactories(options: TypeScriptAngularServicesGeneratorConfig): {
+  abortablePromise: ts.GenericModuleReferenceFactory<1>;
+  waitForResponse: ts.GenericModuleReferenceFactory<1>;
+  requestBuilder: ts.ModuleReferenceFactory;
+  apiConfiguration: ts.ModuleReferenceFactory;
+  apiBaseService: ts.ModuleReferenceFactory;
+  httpStatusCode: ts.ModuleReferenceFactory;
+  provide: ts.ModuleReferenceFactory;
+} {
+  const utilsDirPath = resolve(options.outputDir, options.utilsDir);
+  return {
+    // angular-service.utils.ts
+    abortablePromise: ts.reference.genericFactory<1>(
+      'AbortablePromise',
+      join(utilsDirPath, 'angular-service.utils.ts'),
+      {
+        importType: 'type-import',
+      },
+    ),
+    waitForResponse: ts.reference.genericFactory<1>('waitForResponse', join(utilsDirPath, 'angular-service.utils.ts')),
+
+    // request-builder.ts
+    requestBuilder: ts.reference.factory('RequestBuilder', join(utilsDirPath, 'request-builder.ts')),
+
+    // api-configuration.ts - generated in angular-services-generator.ts
+    apiConfiguration: ts.reference.factory(
+      toCasing(`${options.domainName ?? ''}ApiConfiguration`, options.typeNameCasing),
+      join(utilsDirPath, 'api-configuration.ts'),
+    ),
+
+    // api-base-service.ts - generated in angular-service-generator.ts
+    apiBaseService: ts.reference.factory('ApiBaseService', join(utilsDirPath, 'api-base-service.ts')),
+
+    // http-status-code.ts - generated in angular-services-generator.ts
+    httpStatusCode: ts.reference.factory('HttpStatusCode', join(utilsDirPath, 'http-status-code.ts'), {
+      importType: 'type-import',
+    }),
+
+    // provide.ts - generated in angular-services-generator.ts
+    provide: ts.reference.factory(
+      toCasing(`provide_${options.domainName ?? ''}_Api`, options.functionNameCasing),
+      join(utilsDirPath, 'provide.ts'),
+    ),
+  };
+}