@goast/typescript 0.4.1-beta1 → 0.4.1

package/src/src/file-builder.ts

@@ -0,0 +1,136 @@
+import { dirname } from 'node:path';
+
+
+import fs from 'fs-extra';
+
+import { type AppendParam, type AppendValue, isAppendValue, type Nullable, SourceBuilder } from '@goast/core';
+
+import { TsNode } from './ast/node.js';
+import { defaultTypeScriptGeneratorConfig, type TypeScriptGeneratorConfig } from './config.js';
+import type { TypeScriptModelGeneratorOutput } from './generators/index.js';
+import {
+  ImportExportCollection,
+  type TypeScriptExportOptions,
+  type TypeScriptImportOptions,
+} from './import-collection.js';
+
+export type TypeScriptAppends<TAdditionalAppends> = TsNode<TypeScriptFileBuilder> | TAdditionalAppends;
+export type TypeScriptAppendParam<TBuilder extends TypeScriptFileBuilder, TAdditionalAppends> = AppendParam<
+  TBuilder,
+  TypeScriptAppends<TAdditionalAppends>
+>;
+
+export function isTypeScriptAppendValue<TBuilder extends TypeScriptFileBuilder = TypeScriptFileBuilder>(
+  value: unknown,
+): value is AppendValue<TBuilder> {
+  return isAppendValue(value) || value instanceof TsNode;
+}
+
+export class TypeScriptFileBuilder<TAdditionalAppends = never>
+  extends SourceBuilder<TypeScriptAppends<TAdditionalAppends>> {
+  public readonly filePath: string | undefined;
+  public readonly imports: ImportExportCollection;
+
+  public override get options(): TypeScriptGeneratorConfig {
+    return super.options as TypeScriptGeneratorConfig;
+  }
+
+  constructor(filePath?: string, options?: TypeScriptGeneratorConfig) {
+    super(options ?? defaultTypeScriptGeneratorConfig);
+    this.filePath = filePath;
+    this.imports = new ImportExportCollection({
+      filePath: filePath,
+      importModuleTransformer: this.options.importModuleTransformer,
+      useSingleQuotes: this.options.useSingleQuotes,
+    });
+  }
+
+  public addImport(name: string, moduleNameOrfilePath: string, options?: TypeScriptImportOptions): this {
+    this.imports.addImport(name, moduleNameOrfilePath, options);
+    return this;
+  }
+
+  public addExport(name: string, filePath: string, options?: TypeScriptExportOptions): this {
+    this.imports.addExport(name, filePath, options);
+    return this;
+  }
+
+  public override clear(): void {
+    super.clear();
+    this.imports.clear();
+  }
+
+  public override toString(addPadding: boolean = true): string {
+    const builder = new SourceBuilder(this.options);
+    if (this.filePath?.match(/\.[cm]?js$/)) {
+      builder.appendLine('// @ts-check');
+    }
+
+    builder.ensurePreviousLineEmpty();
+    this.imports.writeTo(builder);
+
+    const baseString = super.toString();
+    if (baseString && addPadding) {
+      builder.ensurePreviousLineEmpty();
+    }
+
+    builder.append(baseString);
+
+    if (addPadding) {
+      builder.ensureCurrentLineEmpty();
+    }
+
+    return builder.toString();
+  }
+
+  protected override appendSingle(value: TypeScriptAppendParam<this, TAdditionalAppends>) {
+    super.appendSingle(value);
+    if (value instanceof TsNode) {
+      value.write(this);
+    }
+  }
+
+  public appendModelUsage(type: TypeScriptModelGeneratorOutput, options?: TypeScriptImportOptions): this {
+    this.append(type.component);
+    for (const i of type.imports) {
+      this.addImport(i.name, i.modulePath, { ...i, ...options });
+    }
+    return this;
+  }
+
+  public writeToFile(filePath?: string): void {
+    if (!filePath) filePath = this.filePath;
+    if (!filePath) throw new Error('File path is required');
+    fs.ensureDirSync(dirname(filePath));
+    fs.writeFileSync(filePath, this.toString());
+  }
+
+  public static generate(options: {
+    filePath: string;
+    logName?: Nullable<string>;
+    options?: TypeScriptGeneratorConfig;
+    generator: (builder: TypeScriptFileBuilder) => void;
+  }): void {
+    TypeScriptFileBuilder.tryGenerate(options);
+  }
+
+  public static tryGenerate({
+    filePath,
+    generator,
+    options,
+    logName,
+  }: {
+    filePath: Nullable<string>;
+    logName?: Nullable<string>;
+    options?: TypeScriptGeneratorConfig;
+    generator: (builder: TypeScriptFileBuilder) => void;
+  }) {
+    if (!filePath) return;
+    if (logName) {
+      console.log(`Generating ${logName} to ${filePath}...`);
+    }
+    const builder = new TypeScriptFileBuilder(filePath, options);
+    generator(builder);
+    builder.writeToFile();
+  }
+}

package/src/src/generators/file-generator.ts

@@ -0,0 +1,15 @@
+import type { MaybePromise, OpenApiGenerationProviderContext, OpenApiGeneratorInput, SourceBuilder } from '@goast/core';
+
+import { ts } from '../ast/index.js';
+import type { TypeScriptGeneratorConfig } from '../config.js';
+
+export abstract class TypeScriptFileGenerator<
+  TContext extends OpenApiGenerationProviderContext<OpenApiGeneratorInput, TypeScriptGeneratorConfig>,
+  TOutput,
+> {
+  public abstract generate(context: TContext): MaybePromise<TOutput>;
+
+  protected getAnyType(context: TContext): ts.Reference<SourceBuilder> {
+    return context.config.preferUnknown ? ts.refs.unknown() : ts.refs.any();
+  }
+}

package/src/src/generators/index.ts

@@ -0,0 +1,6 @@
+export * from './file-generator.js';
+export * from './models/index.js';
+export * from './services/angular-services/index.js';
+export * from './services/easy-network-stub/index.js';
+export * from './services/fetch-clients/index.js';
+export * from './services/k6-clients/index.js';

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

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

package/src/src/generators/models/model-generator.ts

@@ -0,0 +1,469 @@
+import { resolve } from 'node:path';
+
+import {
+  type ApiSchema,
+  type AppendValue,
+  type AppendValueGroup,
+  appendValueGroup,
+  type ArrayLikeApiSchema,
+  type CombinedLikeApiSchema,
+  getSchemaReference,
+  type MaybePromise,
+  notNullish,
+  type Nullable,
+  type ObjectLikeApiSchema,
+  resolveAnyOfAndAllOf,
+  type StringLikeApiSchema,
+  toCasing,
+} from '@goast/core';
+
+import { ts } from '../../ast/index.js';
+import type { TypeScriptComponentOutputKind } from '../../common-results.js';
+import { TypeScriptFileBuilder } from '../../file-builder.js';
+import { TypeScriptFileGenerator } from '../file-generator.js';
+import type { TypeScriptModelGeneratorContext, TypeScriptModelGeneratorOutput } from './models.js';
+
+type Context = TypeScriptModelGeneratorContext;
+type Output = TypeScriptModelGeneratorOutput;
+type Builder = TypeScriptFileBuilder;
+
+export interface TypeScriptModelGenerator<TOutput extends Output = Output> {
+  generate(ctx: Context): MaybePromise<TOutput>;
+}
+
+export class DefaultTypeScriptModelGenerator extends TypeScriptFileGenerator<Context, Output>
+  implements TypeScriptModelGenerator {
+  public generate(ctx: Context): MaybePromise<Output> {
+    if (this.shouldGenerateTypeDeclaration(ctx, ctx.schema)) {
+      const name = this.getDeclarationTypeName(ctx, ctx.schema);
+      const filePath = this.getFilePath(ctx, ctx.schema);
+
+      const fileContent = this.getFileContent(ctx);
+      TypeScriptFileBuilder.generate({
+        logName: `model ${name}`,
+        filePath,
+        options: ctx.config,
+        generator: (b) => b.append(fileContent),
+      });
+
+      const exports = fileContent.values.filter(
+        (x): x is AppendValue<Builder> & { name: string; export: true } =>
+          typeof x === 'object' && x !== null && 'export' in x && x.export === true && 'name' in x,
+      );
+      const node = exports.find((x) => x.name === name);
+      return {
+        component: name,
+        filePath,
+        imports: [
+          {
+            kind: 'file',
+            name,
+            modulePath: filePath,
+            type: node instanceof ts.Interface || node instanceof ts.TypeAlias ? 'type-import' : 'import',
+          },
+        ],
+        additionalExports: exports
+          .filter((x) => x.name !== name)
+          .map(
+            (x) => ({
+              name: x.name,
+              type: x instanceof ts.TypeAlias || x instanceof ts.Interface ? 'type-export' : 'export',
+            } as const),
+          ),
+        kind: this.getNodeKind(node),
+      };
+    } else {
+      const builder = new TypeScriptFileBuilder(undefined, ctx.config);
+      builder.append(this.getType(ctx, ctx.schema));
+      const imports = builder.imports.imports;
+      builder.imports.clear();
+      return { component: builder.toString(false), imports };
+    }
+  }
+
+  protected getNodeKind(node: unknown): TypeScriptComponentOutputKind | undefined {
+    if (node instanceof ts.Interface) return 'interface';
+    if (node instanceof ts.TypeAlias) return 'type';
+    if (node instanceof ts.Enum) return 'enum';
+    if (node instanceof ts.Class) return 'class';
+    return undefined;
+  }
+
+  protected getFileContent(ctx: Context): AppendValueGroup<Builder> {
+    const content = appendValueGroup<Builder>([], '\n');
+    const interfaceSchema = this.resolveInterfaceSchema(ctx);
+    if (interfaceSchema) {
+      content.values.push(this.getInterface(ctx, interfaceSchema));
+    } else if (
+      ctx.config.enumGeneration !== 'union' &&
+      ctx.schema.kind === 'string' &&
+      ctx.schema.enum !== undefined &&
+      ctx.schema.enum.length > 0
+    ) {
+      content.values.push(this.getEnum(ctx));
+    } else if (ctx.schema.discriminator && Object.keys(ctx.schema.discriminator.mapping).length > 0) {
+      content.values.push(
+        ts.typeAlias(
+          this.getDiscriminatorTypeName(ctx, ctx.schema),
+          ts.unionType(Object.keys(ctx.schema.discriminator.mapping).map((x) => ts.string(x))),
+        ),
+        ts.typeAlias(
+          this.getBaseTypeName(ctx, ctx.schema),
+          this.getType(ctx, ctx.schema, { skipSchemas: true }) ?? this.getAnyType(ctx),
+          { export: true },
+        ),
+        this.getTypeAlias(ctx, ctx.schema),
+      );
+    } else {
+      content.values.push(this.getTypeAlias(ctx, ctx.schema));
+      if (ctx.schema.enum) {
+        content.values.push(this.getEnumValuesVariable(ctx, ctx.schema));
+      }
+    }
+    return content;
+  }
+
+  protected getEnum(ctx: Context): ts.Enum<Builder> {
+    return ts.enum(this.getDeclarationTypeName(ctx, ctx.schema), {
+      doc: ts.doc({
+        description: ctx.schema.description,
+        tags: [ctx.schema.deprecated ? ts.docTag('deprecated') : null],
+      }),
+      export: true,
+      members: (ctx.schema.enum?.map((x) => String(x)) ?? []).map((x) =>
+        ts.enumValue(toCasing(x, ctx.config.enumValueNameCasing), { value: ts.string(x) })
+      ),
+    });
+  }
+
+  protected getInterface(ctx: Context, schema: ObjectLikeApiSchema): ts.Interface<Builder> {
+    return ts.interface(this.getDeclarationTypeName(ctx, ctx.schema), {
+      export: true,
+      doc: ts.doc({
+        description: schema.description,
+        tags: [ctx.schema.deprecated ? ts.docTag('deprecated') : null],
+      }),
+      members: [...this.getProperties(ctx, schema), this.getIndexer(ctx, schema)],
+    });
+  }
+
+  protected getTypeAlias(ctx: Context, schema: ApiSchema): ts.TypeAlias<Builder> {
+    const hasDiscriminator = schema.discriminator && Object.keys(schema.discriminator.mapping).length > 0;
+    const result = ts.typeAlias<Builder>(
+      this.getDeclarationTypeName(ctx, schema),
+      (hasDiscriminator ? this.getDiscriminatorType(ctx, schema) : this.getType(ctx, schema, { skipSchemas: true })) ??
+        this.getAnyType(ctx),
+      {
+        export: true,
+        doc: ts.doc({
+          description: schema.description,
+          tags: [ctx.schema.deprecated ? ts.docTag('deprecated') : null],
+        }),
+      },
+    );
+
+    if (hasDiscriminator) {
+      const propertyValue = this.getDiscriminatorTypeName(ctx, ctx.schema);
+      result.generics.push(
+        ts.genericParameter(this.getDiscriminatorGenericParamName(ctx, schema), {
+          constraint: propertyValue,
+          default: propertyValue,
+        }),
+      );
+    }
+
+    const inheritedSchemas = this.getInheritedSchemas(ctx, schema);
+    if (inheritedSchemas.length > 0) {
+      const fixedProperties = inheritedSchemas.reduce((p, c) => {
+        const mappingValues = Object.entries(c.discriminator.mapping)
+          .filter(([_, value]) => value.id === schema.id)
+          .map(([key]) => ts.string(key));
+        if (c.discriminator.propertyName in p) {
+          p[c.discriminator.propertyName].types.push(...mappingValues);
+        } else {
+          p[c.discriminator.propertyName] = ts.unionType(mappingValues);
+        }
+        return p;
+      }, {} as Record<string, ts.UnionType<Builder>>);
+      result.type = ts.intersectionType([
+        ts.refs.omit([result.type, ts.unionType(Object.keys(fixedProperties).map((x) => ts.string(x)))]),
+        ts.objectType({
+          members: Object.entries(fixedProperties).map(([key, value]) =>
+            ts.property(key, { type: value, readonly: ctx.config.immutableTypes })
+          ),
+        }),
+      ]);
+    }
+
+    return result;
+  }
+
+  protected getEnumValuesVariable(ctx: Context, schema: ApiSchema): ts.Variable<Builder> {
+    const enumTypeName = this.getDeclarationTypeName(ctx, schema);
+    const values = schema.enum?.map((x) => ts.toNode(x)) ?? [];
+    return ts.variable(toCasing(`${enumTypeName}-Values`, ctx.config.constantNameCasing), {
+      doc: ts.doc({
+        description: `All possible values of the enum \`${enumTypeName}\`.`,
+      }),
+      export: true,
+      readonly: true,
+      value: ts.tuple(values, { asConst: true }),
+    });
+  }
+
+  protected getIndexer(ctx: Context, schema: ObjectLikeApiSchema): ts.Indexer<Builder> | null {
+    return schema.additionalProperties
+      ? ts.indexer(
+        ts.refs.string(),
+        (schema.additionalProperties === true ? null : this.getType(ctx, schema.additionalProperties)) ??
+          this.getAnyType(ctx),
+        { readonly: ctx.config.immutableTypes },
+      )
+      : null;
+  }
+
+  protected getProperties(ctx: Context, schema: ObjectLikeApiSchema): ts.Property<Builder>[] {
+    return Array.from(schema.properties.values()).map((property) => {
+      return ts.property(property.name, {
+        doc: ts.doc({
+          description: property.schema.description,
+          tags: [property.schema.deprecated ? ts.docTag('deprecated') : null],
+        }),
+        readonly: ctx.config.immutableTypes,
+        optional: !schema.required.has(property.name),
+        type: ts.unionType([this.getType(ctx, property.schema), property.schema.nullable ? 'null' : null]),
+      });
+    });
+  }
+
+  protected getType(
+    ctx: Context,
+    schema: Nullable<ApiSchema>,
+    options?: { skipSchemas?: boolean; useBaseType?: boolean },
+  ): ts.Type<Builder> | null {
+    if (!schema) return this.getAnyType(ctx);
+
+    schema = getSchemaReference(schema, ['description']);
+
+    if (options?.useBaseType && ctx.schema.inheritedSchemas.some((x) => x.id === schema.id)) {
+      return ts.reference(this.getBaseTypeName(ctx, schema), this.getFilePath(ctx, schema), {
+        importType: 'type-import',
+      });
+    }
+
+    if (!options?.skipSchemas && this.shouldGenerateTypeDeclaration(ctx, schema)) {
+      if (schema.id === ctx.schema.id) {
+        return null;
+      }
+      return ts.reference(this.getDeclarationTypeName(ctx, schema), this.getFilePath(ctx, schema), {
+        importType: 'type-import',
+      });
+    }
+
+    if (schema.enum) {
+      return ts.unionType(schema.enum.map((x) => ts.toNode(x)));
+    }
+
+    switch (schema.kind) {
+      case 'boolean':
+        return 'boolean';
+      case 'integer':
+      case 'number':
+        return 'number';
+      case 'string':
+        return this.getStringType(ctx, schema);
+      case 'null':
+        return 'null';
+      case 'unknown':
+        return this.getAnyType(ctx);
+      case 'array':
+        return this.getArrayType(ctx, schema);
+      case 'object':
+        return this.getObjectType(ctx, schema);
+      case 'combined':
+        return this.getCombinedType(ctx, schema);
+      case 'multi-type':
+        return this.getMultiType(ctx, schema);
+      case 'oneOf':
+        return this.getOneOfType(ctx, schema);
+      default:
+        return this.getAnyType(ctx);
+    }
+  }
+
+  protected getStringType(_ctx: Context, schema: StringLikeApiSchema): ts.Type<Builder> {
+    if (schema.format === 'binary') {
+      return ts.refs.blob();
+    }
+    return 'string';
+  }
+
+  protected getArrayType(ctx: Context, schema: ArrayLikeApiSchema): ts.Type<Builder> {
+    return ts.arrayType(this.getType(ctx, schema.items) ?? this.getAnyType(ctx), {
+      readonly: ctx.config.immutableTypes,
+    });
+  }
+
+  protected getObjectType(ctx: Context, schema: ObjectLikeApiSchema): ts.Type<Builder> {
+    const parts = [
+      schema.properties.size > 0 ? ts.objectType({ members: this.getProperties(ctx, schema) }) : null,
+      schema.additionalProperties ? ts.objectType({ members: [this.getIndexer(ctx, schema)] }) : null,
+      schema.allOf.length > 0 || schema.anyOf.length > 0 ? this.getCombinedType(ctx, schema) : null,
+    ].filter(notNullish);
+    if (parts.length === 0) {
+      parts.push(
+        ts.objectType({
+          members: [ts.indexer(ts.refs.string(), ts.refs.never(), { readonly: ctx.config.immutableTypes })],
+        }),
+      );
+    }
+    return ts.intersectionType(parts);
+  }
+
+  protected getDiscriminatorType(ctx: Context, schema: ApiSchema): ts.Type<Builder> {
+    if (schema.discriminator && Object.keys(schema.discriminator.mapping).length > 0) {
+      const discriminator = schema.discriminator;
+      return ts.intersectionType([
+        this.getBaseTypeName(ctx, schema as ApiSchema),
+        ts.lookupType(
+          ts.objectType({
+            members: Object.entries(discriminator.mapping).map(([key, value]) =>
+              ts.property(key, {
+                type: ts.intersectionType([
+                  ts.objectType({
+                    members: [
+                      ts.property(discriminator.propertyName, {
+                        type: ts.string(key),
+                        readonly: ctx.config.immutableTypes,
+                      }),
+                    ],
+                  }),
+                  this.getType(ctx, value),
+                ]),
+              })
+            ),
+          }),
+          this.getDiscriminatorGenericParamName(ctx, schema as ApiSchema),
+        ),
+      ]);
+    } else {
+      return ts.refs.unknown();
+    }
+  }
+
+  protected getCombinedType(ctx: Context, schema: CombinedLikeApiSchema): ts.Type<Builder> {
+    if (schema.allOf.length === 0 && schema.anyOf.length === 0) {
+      return this.getAnyType(ctx);
+    }
+    const useBaseType = schema.id === ctx.schema.id;
+    return ts.intersectionType([
+      ...schema.allOf.map((x) => this.getType(ctx, x, { useBaseType })),
+      ...schema.anyOf.map((x) => ts.reference('Partial', null, { generics: [this.getType(ctx, x, { useBaseType })] })),
+    ]);
+  }
+
+  protected getOneOfType(ctx: Context, schema: ApiSchema<'oneOf'>): ts.Type<Builder> {
+    if (schema.oneOf.length === 0) {
+      return this.getAnyType(ctx);
+    }
+    return ts.unionType(schema.oneOf.map((x) => this.getType(ctx, x)));
+  }
+
+  protected getMultiType(ctx: Context, schema: ApiSchema<'multi-type'>): ts.Type<Builder> {
+    if (schema.type.length === 0) {
+      return this.getAnyType(ctx);
+    }
+    return ts.unionType(
+      schema.type.map((x) => {
+        switch (x) {
+          case 'string':
+            return this.getStringType(ctx, schema);
+          case 'number':
+          case 'integer':
+            return 'number';
+          case 'boolean':
+            return 'boolean';
+          case 'null':
+            return 'null';
+          case 'array':
+            return this.getArrayType(ctx, schema);
+          case 'object':
+            return this.getObjectType(ctx, schema);
+          default:
+            return 'never';
+        }
+      }),
+    );
+  }
+
+  protected shouldGenerateTypeDeclaration(ctx: Context, schema: ApiSchema): boolean {
+    // All named schemas should have its own type declaration
+    if (!schema.isNameGenerated) {
+      return true;
+    }
+
+    // All enum types should have its own type declaration
+    if (schema.enum !== undefined && schema.enum.length > 0) {
+      return true;
+    }
+
+    // All primitive types already exist and do not need its own type declaration
+    if (
+      schema.kind !== 'array' &&
+      schema.kind !== 'combined' &&
+      schema.kind !== 'multi-type' &&
+      schema.kind !== 'object' &&
+      schema.kind !== 'oneOf'
+    ) {
+      return false;
+    }
+
+    // Dynamically generated schemas do not have its own type declaration
+    if (!ctx.data.schemas.some((x) => x.id === schema.id)) {
+      return false;
+    }
+
+    // For all other types, check if the user has enabled inline unnamed schemas
+    return !ctx.config.inlineUnnamedSchemas;
+  }
+
+  protected resolveInterfaceSchema(ctx: Context): ApiSchema<'object'> | undefined {
+    if (
+      ctx.config.typeDeclaration === 'prefer-interface' &&
+      (ctx.schema.kind === 'object' || ctx.schema.kind === 'combined')
+    ) {
+      return resolveAnyOfAndAllOf(ctx.schema, true);
+    }
+    return undefined;
+  }
+
+  protected getDeclarationTypeName(ctx: Context, schema: ApiSchema): string {
+    return toCasing(schema.name, ctx.config.typeNameCasing);
+  }
+
+  protected getDiscriminatorGenericParamName(ctx: Context, schema: ApiSchema): string {
+    return toCasing(schema.discriminator?.propertyName, ctx.config.genericParamNameCasing);
+  }
+
+  protected getDiscriminatorTypeName(ctx: Context, schema: ApiSchema): string {
+    return toCasing(schema.name + '_Discriminator', ctx.config.typeNameCasing);
+  }
+
+  protected getBaseTypeName(ctx: Context, schema: ApiSchema): string {
+    return toCasing(schema.name + '_Base', ctx.config.typeNameCasing);
+  }
+
+  protected getInheritedSchemas(ctx: Context, schema: ApiSchema): ApiSchema['inheritedSchemas'] {
+    return schema.inheritedSchemas
+      .filter((schema) => this.shouldGenerateTypeDeclaration(ctx, schema) && !schema.isNameGenerated)
+      .filter((item, index, self) => self.indexOf(item) === index);
+  }
+
+  protected getFilePath(ctx: Context, schema: ApiSchema): string {
+    return resolve(
+      ctx.config.outputDir,
+      ctx.config.modelsDir,
+      `${toCasing(schema.name, ctx.config.modelFileNameCasing ?? ctx.config.fileNameCasing)}.ts`,
+    );
+  }
+}