@goast/typescript 0.8.0-beta.1 → 0.8.0

package/src/src/generators/models/models.ts

@@ -0,0 +1,121 @@
+import type {
+  ApiSchema,
+  DefaultGenerationProviderConfig,
+  ExtendedStringCasing,
+  Nullable,
+  OpenApiSchemasGenerationProviderContext,
+} from '@goast/core';
+
+import { ts } from '../../ast/index.js';
+import type { TypeScriptComponentOutput } from '../../common-results.js';
+import { defaultTypeScriptGeneratorConfig, type TypeScriptGeneratorConfig } from '../../config.js';
+import type { TypeScriptFileBuilder } from '../../file-builder.js';
+
+export type TypeScriptModelGeneratorConfig = TypeScriptGeneratorConfig & {
+  /**
+   * Determines how to generate enums.
+   * - 'union': Generate enums as union types.
+   * - 'prefer-enum': Generate enums as enums if possible, otherwise as union types.
+   * @default 'union'
+   */
+  enumGeneration: 'union' | 'prefer-enum';
+
+  /**
+   * Whether to generate immutable types.
+   * @default false
+   */
+  immutableTypes: boolean;
+
+  /**
+   * Whether to inline unnamed schemas. If false, unnamed schemas will be generated as separate types.
+   * @default true
+   */
+  inlineUnnamedSchemas: boolean;
+
+  /**
+   * The directory where the models should be saved. The path is relative to the output directory.
+   * @default 'models'
+   */
+  modelsDir: string;
+
+  /**
+   * The casing of the model file names. If nullish, the `fileNameCasing` is used.
+   * @default undefined
+   */
+  modelFileNameCasing: Nullable<ExtendedStringCasing>;
+
+  /**
+   * Determines how to declare types.
+   * - 'type': Always declare types as `type`.
+   * - 'prefer-interface': Prefer `interface` over `type` if possible.
+   * @default 'type'
+   */
+  typeDeclaration: 'type' | 'prefer-interface';
+
+  /**
+   * The casing to use for the base type of discriminator schemas.
+   * @default `_<SchemaName>Base`
+   */
+  discriminatorBaseTypeCasing: ExtendedStringCasing;
+
+  /**
+   * The type to use for binary schemas.
+   * @default `ts.refs.blob`
+   */
+  binarySchemaType: () => ts.Type<TypeScriptFileBuilder>;
+};
+
+export type TypeScriptModelsGeneratorConfig = TypeScriptModelGeneratorConfig & {
+  /**
+   * The path to the index file where all models should be exported. If nullish, no index file will be generated.
+   * @default 'models.ts'
+   */
+  modelsIndexFile: Nullable<string>;
+};
+
+export const defaultTypeScriptModelGeneratorConfig: DefaultGenerationProviderConfig<TypeScriptModelGeneratorConfig> = {
+  ...defaultTypeScriptGeneratorConfig,
+
+  enumGeneration: 'union',
+  immutableTypes: false,
+  inlineUnnamedSchemas: true,
+  modelsDir: 'models',
+  modelFileNameCasing: undefined,
+  typeDeclaration: 'type',
+  discriminatorBaseTypeCasing: { casing: 'pascal', prefix: '_', suffix: 'Base' },
+  binarySchemaType: ts.refs.blob,
+};
+
+export const defaultTypeScriptModelsGeneratorConfig: DefaultGenerationProviderConfig<TypeScriptModelsGeneratorConfig> =
+  {
+    ...defaultTypeScriptModelGeneratorConfig,
+
+    modelsIndexFile: 'models.ts',
+  };
+
+// deno-lint-ignore ban-types
+export type TypeScriptModelsGeneratorInput = {};
+
+export type TypeScriptModelsGeneratorOutput = {
+  typescript: {
+    models: {
+      [schemaId: string]: TypeScriptModelGeneratorOutput;
+    };
+    indexFiles: {
+      models: Nullable<string>;
+    };
+  };
+};
+
+export type TypeScriptModelGeneratorOutput = TypeScriptComponentOutput;
+
+export type TypeScriptModelsGeneratorContext = OpenApiSchemasGenerationProviderContext<
+  TypeScriptModelsGeneratorInput,
+  TypeScriptModelsGeneratorOutput,
+  TypeScriptModelsGeneratorConfig,
+  TypeScriptModelGeneratorOutput
+>;
+
+export type TypeScriptModelGeneratorContext = TypeScriptModelsGeneratorContext & {
+  schema: ApiSchema;
+};

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

@@ -0,0 +1,431 @@
+import { resolve } from 'node:path';
+
+import {
+  type ApiComponent,
+  type ApiEndpoint,
+  type ApiResponse,
+  type ApiSchema,
+  type AppendValueGroup,
+  appendValueGroup,
+  type BasicAppendValue,
+  builderTemplate as s,
+  getSourceDisplayName,
+  type MaybePromise,
+  notNullish,
+  type Nullable,
+  toCasing,
+} from '@goast/core';
+
+import { ts } from '../../../ast/index.js';
+import type { TypeScriptExportOutput } from '../../../common-results.js';
+import { TypeScriptFileBuilder } from '../../../file-builder.js';
+import { getSourceDocLine } from '../../../utils.js';
+import { TypeScriptFileGenerator } from '../../file-generator.js';
+import type { TypeScriptAngularServiceGeneratorContext, TypeScriptAngularServiceGeneratorOutput } from './models.js';
+
+type Context = TypeScriptAngularServiceGeneratorContext;
+type Output = TypeScriptAngularServiceGeneratorOutput;
+type Builder = TypeScriptFileBuilder;
+
+export interface TypeScriptAngularServiceGenerator<TOutput extends Output = Output> {
+  generate(ctx: Context): MaybePromise<TOutput>;
+}
+
+export class DefaultTypeScriptAngularServiceGenerator extends TypeScriptFileGenerator<Context, Output>
+  implements TypeScriptAngularServiceGenerator {
+  public generate(ctx: Context): MaybePromise<Output> {
+    const responseModels = this.generateResponseModels(ctx);
+
+    const filePath = this.getServiceFilePath(ctx);
+    const name = this.getServiceClassName(ctx);
+
+    TypeScriptFileBuilder.generate({
+      logName: `service ${name}`,
+      filePath,
+      options: ctx.config,
+      generator: (b) => {
+        ctx.service.endpoints.forEach((endpoint) => {
+          console.log(
+            `  ${getSourceDisplayName(ctx.data, endpoint)} [${toCasing(endpoint.name, ctx.config.functionNameCasing)}]`,
+          );
+        });
+        b.append(this.getServiceFileContent(ctx));
+      },
+    });
+
+    return {
+      filePath,
+      component: name,
+      responseModels,
+    };
+  }
+
+  // #region Response Model
+  protected generateResponseModels(ctx: Context): Record<string, TypeScriptExportOutput> {
+    const result: Record<string, TypeScriptExportOutput> = {};
+    const filePath = this.getResponseModelFilePath(ctx);
+    const builder = new TypeScriptFileBuilder(filePath, ctx.config);
+
+    for (const endpoint of ctx.service.endpoints) {
+      const name = this.getResponseModelName(ctx, endpoint);
+      builder.appendLine(this.getResponseModelFileContent(ctx, endpoint));
+      result[endpoint.id] = { component: name, filePath };
+    }
+
+    builder.writeToFile();
+    return result;
+  }
+
+  protected getResponseModelFileContent(ctx: Context, endpoint: ApiEndpoint): AppendValueGroup<Builder> {
+    const result = appendValueGroup<Builder>([]);
+    const statusCodes = this.getEndpointStatusCodes(ctx, endpoint);
+    let statusCodeType: ts.Reference<Builder>;
+
+    const statusCodesTypeName = toCasing(`${endpoint.name}_StatusCodes`, ctx.config.typeNameCasing);
+    result.values.push(ts.typeAlias(statusCodesTypeName, ts.unionType(Object.keys(statusCodes))));
+    if (ctx.config.strictResponseTypes) {
+      statusCodeType = ts.reference(statusCodesTypeName);
+    } else {
+      statusCodeType = ctx.refs.httpStatusCode();
+    }
+
+    result.values.push(
+      ts.typeAlias(
+        this.getResponseModelName(ctx, endpoint),
+        ts.intersectionType([
+          ts.unionType([
+            ...Object.entries(statusCodes).map(([key, value]) => {
+              const isSuccess = key.startsWith('2');
+              return ts.intersectionType<Builder>([
+                isSuccess
+                  ? ts.refs.angular.httpResponse([value.type])
+                  : ts.refs.omit([ts.refs.angular.httpErrorResponse(), ts.string('error')]),
+                ts.objectType({
+                  members: [
+                    isSuccess ? null : ts.property('error', { type: ts.unionType([value.type, ts.refs.null_()]) }),
+                    ts.property('status', { type: key }),
+                    ts.property('ok', { type: isSuccess ? 'true' : 'false' }),
+                  ],
+                }),
+              ]);
+            }),
+            !ctx.config.strictResponseTypes
+              ? ts.intersectionType([
+                ts.refs.angular.httpResponse([this.getAnyType(ctx)]),
+                ts.objectType({
+                  members: [
+                    ts.property('status', {
+                      type: ts.refs.exclude([ctx.refs.httpStatusCode(), ts.reference(statusCodesTypeName)]),
+                    }),
+                  ],
+                }),
+              ])
+              : null,
+          ]),
+          ts.objectType({ members: [ts.property('status', { type: 'TStatus' })] }),
+        ]),
+        {
+          doc: ts.doc({
+            description: `Response model for operation ${this.getEndpointMethodName(ctx, endpoint)}`,
+            tags: [endpoint.deprecated ? ts.docTag('deprecated') : null],
+          }),
+          export: true,
+          generics: [
+            ts.genericParameter('TStatus', {
+              constraint: statusCodeType,
+              default: statusCodeType,
+            }),
+          ],
+        },
+      ),
+    );
+
+    return result;
+  }
+
+  protected getEndpointStatusCodes(
+    ctx: Context,
+    endpoint: ApiEndpoint,
+  ): Record<number, { parser: 'text' | 'json'; type: ts.Type<Builder> }> {
+    return Object.fromEntries([
+      ...Object.entries(ctx.config.defaultStatusCodeResponseTypes).map(([key, value]) => [
+        key,
+        {
+          parser: value?.parser ?? 'text',
+          type: typeof value?.type === 'function'
+            ? this.getSchemaType(ctx, value.type(ctx.data.schemas))
+            : value ?? this.getAnyType(ctx),
+        },
+      ]),
+      ...endpoint.responses
+        .filter((x) => x.statusCode)
+        .map((x) => [
+          x.statusCode,
+          {
+            parser: this.contentTypeToResponseType(x.contentOptions[0]?.type),
+            type: this.getSchemaType(ctx, x.contentOptions[0]?.schema, this.getAnyType(ctx)),
+          },
+        ]),
+    ]);
+  }
+  // #endregion
+
+  protected getServiceFileContent(ctx: Context): AppendValueGroup<Builder> {
+    const code = appendValueGroup<Builder>([], '\n');
+    for (const endpoint of ctx.service.endpoints) {
+      if (endpoint.parameters.length > 0 || endpoint.requestBody !== undefined) {
+        code.values.push(this.getEndpointParamsType(ctx, endpoint));
+      }
+    }
+    code.values.push(this.getClass(ctx));
+    return code;
+  }
+
+  protected getEndpointParamsType(ctx: Context, endpoint: ApiEndpoint): ts.TypeAlias<Builder> {
+    const type = ts.objectType<Builder>();
+
+    for (const parameter of endpoint.parameters) {
+      const schema = parameter.schema;
+      type.members.push(
+        ts.property(toCasing(parameter.name, ctx.config.propertyNameCasing), {
+          doc: ts.doc({
+            description: this.getDocDescription(ctx, parameter),
+            tags: [parameter.deprecated ? ts.docTag('deprecated') : null],
+          }),
+          type: schema ? (b) => b.appendModelUsage(ctx.input.typescript.models[schema.id]) : this.getAnyType(ctx),
+          optional: !parameter.required,
+        }),
+      );
+    }
+
+    if (endpoint.requestBody !== undefined) {
+      const body = endpoint.requestBody;
+      const schema = body.content[0].schema;
+      type.members.push(
+        ts.property('body', {
+          doc: ts.doc({ description: this.getDocDescription(ctx, body) }),
+          type: schema ? (b) => b.appendModelUsage(ctx.input.typescript.models[schema.id]) : this.getAnyType(ctx),
+          optional: !body.required,
+        }),
+      );
+    }
+
+    return ts.typeAlias(this.getEndpointParamsTypeName(ctx, endpoint), type, {
+      doc: ts.doc({ description: `Parameters for operation ${this.getEndpointMethodName(ctx, endpoint)}` }),
+    });
+  }
+
+  protected getClass(ctx: Context): ts.Class<Builder> {
+    return ts.class<Builder>(this.getServiceClassName(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'),
+        ],
+      }),
+      decorators: [
+        ts.decorator(
+          ts.refs.angular.injectable(),
+          ctx.config.provideKind === 'root' ? [ts.toNode({ providedIn: 'root' })] : [],
+        ),
+      ],
+      export: true,
+      extends: ctx.refs.apiBaseService(),
+      members: [
+        ...ctx.service.endpoints.map((e) =>
+          ts.property(this.getEndpointPathPropertyName(ctx, e), {
+            accessModifier: 'private',
+            static: true,
+            readonly: true,
+            value: ts.string(e.path),
+          })
+        ),
+        ...ctx.service.endpoints.map((e) => this.getEndpointMethod(ctx, e)),
+      ],
+    });
+  }
+
+  protected getEndpointMethod(ctx: Context, endpoint: ApiEndpoint): ts.Method<Builder> {
+    const hasParams = this.hasEndpointParams(ctx, endpoint);
+    const paramsOptional = !endpoint.parameters.some((p) => p.required) && !endpoint.requestBody?.required;
+    const responseModelType = ts.reference(
+      this.getResponseModelName(ctx, endpoint),
+      this.getResponseModelFilePath(ctx),
+      {
+        importType: 'type-import',
+      },
+    );
+    const returnType = ctx.refs.abortablePromise([responseModelType]);
+    const accept = this.getEndpointSuccessResponseType(ctx, endpoint);
+    const responseType = this.contentTypeToResponseType(accept);
+    return ts.method<Builder>(this.getEndpointMethodName(ctx, endpoint), {
+      accessModifier: 'public',
+      parameters: [
+        hasParams
+          ? ts.parameter('params', {
+            optional: paramsOptional,
+            type: ts.reference(this.getEndpointParamsTypeName(ctx, endpoint)),
+          })
+          : null,
+        ts.parameter('context', { optional: true, type: ts.refs.angular.httpContext() }),
+      ],
+      doc: ts.doc({
+        description: this.getDocDescription(ctx, endpoint),
+        tags: [endpoint.deprecated ? ts.docTag('deprecated') : null],
+      }),
+      returnType,
+      body: appendValueGroup(
+        [
+          s`const rb = new ${ctx.refs.requestBuilder()}(this.rootUrl, ${
+            this.getServiceClassName(
+              ctx,
+            )
+          }.${this.getEndpointPathPropertyName(ctx, endpoint)}, '${endpoint.method}');`,
+          hasParams
+            ? (b) =>
+              b.appendIf(paramsOptional, 'if (params) ').parenthesizeIf(
+                paramsOptional,
+                '{}',
+                appendValueGroup(
+                  [
+                    ...endpoint.parameters
+                      .filter((p) => p.target === 'path' || p.target === 'query' || p.target === 'header')
+                      .map((p) => {
+                        const options = ts.object({
+                          members: [
+                            p.style !== undefined ? ts.property('style', { value: ts.string(p.style) }) : null,
+                            p.explode !== undefined ? ts.property('explode', { value: ts.toNode(p.explode) }) : null,
+                          ],
+                        });
+                        return s<Builder>`rb.${p.target}(${ts.string(p.name)}, params.${
+                          toCasing(
+                            p.name,
+                            ctx.config.propertyNameCasing,
+                          )
+                        }, ${options});`;
+                      }),
+                    endpoint.requestBody
+                      ? s`rb.body(params.body, ${ts.string(this.getEndpointRequestContentType(ctx, endpoint))});`
+                      : null,
+                  ],
+                  '\n',
+                ),
+                { multiline: true },
+              )
+            : null,
+          '',
+          s`return ${ctx.refs.waitForResponse([responseModelType])}(${s.indent`
+              this.http.request(rb.build({${s.indent`
+                responseType: ${ts.string(responseType)},
+                accept: ${ts.string(accept)},
+                context,`}
+              })),
+              {${s.indent`
+                errorResponseTypes: ${
+            ts.object({
+              members: [
+                ...Object.entries(this.getEndpointStatusCodes(ctx, endpoint))
+                  .filter(([key]) => !key.startsWith('2'))
+                  .map(([key, value]) => {
+                    return ts.property(key, { value: ts.string(value.parser) });
+                  }),
+              ],
+            })
+          }`}
+              }`}
+            )`,
+        ],
+        '\n',
+      ),
+    });
+  }
+
+  protected getDocDescription<T>(
+    ctx: Context,
+    component: ApiComponent<T> & { description?: string },
+  ): BasicAppendValue<Builder> {
+    const docSegments = [component.description?.trim()];
+
+    if (ctx.config.includeSourceInDocs) {
+      docSegments.push(getSourceDocLine(component));
+    }
+
+    return docSegments.filter(notNullish).join('\n\n');
+  }
+
+  protected getEndpointRequestContentType(ctx: Context, endpoint: ApiEndpoint): string {
+    return ctx.config.defaultRequestContentType ?? endpoint?.requestBody?.content[0].type ?? 'application/json';
+  }
+
+  protected getEndpointSuccessResponseType(ctx: Context, endpoint: ApiEndpoint): string {
+    const response = this.getEndpointSuccessResponse(ctx, endpoint);
+    if (!response) return '*/*';
+
+    if (!ctx.config.defaultSuccessResponseContentType) return response.contentOptions[0]?.type ?? '*/*';
+
+    return (
+      response.contentOptions.find((x) => x.type === ctx.config.defaultSuccessResponseContentType)?.type ??
+        response.contentOptions[0]?.type ??
+        '*/*'
+    );
+  }
+
+  protected getEndpointSuccessResponse(_ctx: Context, endpoint: ApiEndpoint): ApiResponse | undefined {
+    return (
+      endpoint.responses.find((x) => x.statusCode && x.statusCode >= 200 && x.statusCode < 300) ??
+        endpoint.responses.find((x) => x.statusCode === undefined)
+    );
+  }
+
+  protected getServiceClassName(ctx: Context): string {
+    return toCasing(ctx.service.name + '_Service', ctx.config.typeNameCasing);
+  }
+
+  protected getResponseModelName(ctx: Context, endpoint: ApiEndpoint): string {
+    return toCasing(`${this.getEndpointMethodName(ctx, endpoint)}ApiResponse`, ctx.config.typeNameCasing);
+  }
+
+  protected getEndpointParamsTypeName(ctx: Context, endpoint: ApiEndpoint): string {
+    return toCasing(this.getEndpointMethodName(ctx, endpoint) + '_Params', ctx.config.typeNameCasing);
+  }
+
+  protected getEndpointPathPropertyName(ctx: Context, endpoint: ApiEndpoint): string {
+    return toCasing(this.getEndpointMethodName(ctx, endpoint) + '_Path', ctx.config.constantNameCasing);
+  }
+
+  protected getEndpointMethodName(ctx: Context, endpoint: ApiEndpoint): string {
+    return toCasing(endpoint.name, ctx.config.functionNameCasing);
+  }
+
+  protected getServiceFilePath(ctx: Context): string {
+    return resolve(
+      ctx.config.outputDir,
+      ctx.config.servicesDir,
+      `${toCasing(ctx.service.name, ctx.config.serviceFileNameCasing ?? ctx.config.fileNameCasing)}.ts`,
+    );
+  }
+
+  protected getResponseModelFilePath(ctx: Context): string {
+    return resolve(
+      ctx.config.outputDir,
+      ctx.config.responseModelsDir,
+      `${toCasing(ctx.service.name, ctx.config.responseModelFileNameCasing ?? ctx.config.fileNameCasing)}.ts`,
+    );
+  }
+
+  protected hasEndpointParams(_ctx: Context, endpoint: ApiEndpoint): boolean {
+    return endpoint.parameters.length > 0 || endpoint.requestBody !== undefined;
+  }
+
+  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);
+  }
+
+  private contentTypeToResponseType(contentType: Nullable<string>): 'text' | 'json' {
+    return contentType?.includes('json') ? 'json' : 'text';
+  }
+}