@goast/core 0.6.0-beta.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goast/core",
-  "version": "0.6.0-beta.2",
+  "version": "0.6.0",
   "description": "A tool designed to transform OpenAPI specifications into various forms with flexibility and extensibility at its core.",
   "author": {
     "name": "Marc Schmidt (MaSch0212)",

package/src/_dnt.shims.ts

@@ -0,0 +1,69 @@
+import { fetch, File, FormData, Headers, Request, Response } from "undici";
+export { fetch, File, FormData, Headers, Request, Response, type BodyInit, type HeadersInit, type ReferrerPolicy, type RequestInit, type RequestCache, type RequestMode, type RequestRedirect, type ResponseInit } from "undici";
+
+const dntGlobals = {
+  fetch,
+  File,
+  FormData,
+  Headers,
+  Request,
+  Response,
+};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+
+function createMergeProxy<T extends object, U extends object>(
+  baseObj: T,
+  extObj: U,
+): Omit<T, keyof U> & U {
+  return new Proxy(baseObj, {
+    get(_target, prop, _receiver) {
+      if (prop in extObj) {
+        return (extObj as any)[prop];
+      } else {
+        return (baseObj as any)[prop];
+      }
+    },
+    set(_target, prop, value) {
+      if (prop in extObj) {
+        delete (extObj as any)[prop];
+      }
+      (baseObj as any)[prop] = value;
+      return true;
+    },
+    deleteProperty(_target, prop) {
+      let success = false;
+      if (prop in extObj) {
+        delete (extObj as any)[prop];
+        success = true;
+      }
+      if (prop in baseObj) {
+        delete (baseObj as any)[prop];
+        success = true;
+      }
+      return success;
+    },
+    ownKeys(_target) {
+      const baseKeys = Reflect.ownKeys(baseObj);
+      const extKeys = Reflect.ownKeys(extObj);
+      const extKeysSet = new Set(extKeys);
+      return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+    },
+    defineProperty(_target, prop, desc) {
+      if (prop in extObj) {
+        delete (extObj as any)[prop];
+      }
+      Reflect.defineProperty(baseObj, prop, desc);
+      return true;
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (prop in extObj) {
+        return Reflect.getOwnPropertyDescriptor(extObj, prop);
+      } else {
+        return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+      }
+    },
+    has(_target, prop) {
+      return prop in extObj || prop in baseObj;
+    },
+  }) as any;
+}

package/src/mod.ts

@@ -0,0 +1,35 @@
+export * from './src/ast/node.js';
+
+export * from './src/codegen/config.js';
+export * from './src/codegen/endpoints-generator.js';
+export * from './src/codegen/generator.js';
+export * from './src/codegen/schemas-generator.js';
+export * from './src/codegen/services-generator.js';
+export * from './src/codegen/types.js';
+
+export * from './src/parse/openapi-types.js';
+export * from './src/parse/parser.js';
+export * from './src/parse/types.js';
+
+export * from './src/transform/api-types.js';
+export * from './src/transform/transformer.js';
+
+export * from './src/utils/api-data.utils.js';
+export * from './src/utils/array.utils.js';
+export * from './src/utils/asset-manager.js';
+export * from './src/utils/class.utils.js';
+export * from './src/utils/common.utils.js';
+export * from './src/utils/endpoint.utils.js';
+export * from './src/utils/error.utils.js';
+export * from './src/utils/factory.js';
+export * from './src/utils/file-system.utils.js';
+export * from './src/utils/generator.utils.js';
+export * from './src/utils/object.utils.js';
+export * from './src/utils/schema.utils.js';
+export * from './src/utils/source-builder.js';
+export * from './src/utils/string-builder/options.js';
+export { type AppendParam, StringBuilder } from './src/utils/string-builder/string-builder.js';
+export * from './src/utils/string-builder/utils.js';
+export * from './src/utils/string.utils.js';
+export * from './src/utils/string.utils.types.js';
+export * from './src/utils/type.utils.js';

package/src/src/ast/node.ts

@@ -0,0 +1,46 @@
+import type { StringBuilder } from '../utils/string-builder/string-builder.js';
+import type { AppendValue } from '../utils/string-builder/utils.js';
+import type { Prettify } from '../utils/type.utils.js';
+
+const NODE_HISTORY_SYMBOL = Symbol('node-history');
+type BuilderWithHistory<T extends StringBuilder = StringBuilder> = T & { [NODE_HISTORY_SYMBOL]?: AstNode[] };
+
+export type AstNodeInject<TBuilder extends StringBuilder, TInjects extends string> = {
+  [K in `${'after' | 'before'}${Capitalize<TInjects>}`]?: AppendValue<TBuilder>;
+};
+
+export type AstNodeOptions<
+  // deno-lint-ignore no-explicit-any
+  TBase extends abstract new (...args: any) => any,
+  // deno-lint-ignore ban-types
+  TExtensions extends object = {},
+> = Prettify<TExtensions & ConstructorParameters<TBase>[0]>;
+
+export abstract class AstNode<TBuilder extends StringBuilder = StringBuilder, TInjects extends string = never> {
+  public inject: AstNodeInject<TBuilder, TInjects | ''>;
+
+  constructor(options: { inject?: AstNode<TBuilder, TInjects>['inject'] }) {
+    this.inject = options.inject ?? {};
+  }
+
+  public write(builder: TBuilder): void {
+    let history = (builder as BuilderWithHistory)[NODE_HISTORY_SYMBOL];
+    if (!history) {
+      history = [];
+      (builder as BuilderWithHistory)[NODE_HISTORY_SYMBOL] = history;
+    }
+
+    history.push(this);
+    builder.append(this.inject.before);
+    this.onWrite(builder);
+    builder.append(this.inject.after);
+    history.pop();
+  }
+
+  protected getParentNode(builder: TBuilder): AstNode | undefined {
+    const history = (builder as BuilderWithHistory)[NODE_HISTORY_SYMBOL];
+    return history?.at(-2);
+  }
+
+  protected abstract onWrite(builder: TBuilder): void;
+}

package/src/src/codegen/config.ts

@@ -0,0 +1,50 @@
+import type { OpenApiParserOptions } from '../parse/types.js';
+import { defaultOpenApiTransformerOptions } from '../transform/types.js';
+import { defaultSourceBuilderOptions, type SourceBuilderOptions } from '../utils/source-builder.js';
+
+export type OpenApiGeneratorConfig =
+  & SourceBuilderOptions
+  & OpenApiParserOptions
+  & {
+    /**
+     * The directory where the generated files should be saved.
+     * @default 'generated'
+     */
+    outputDir: string;
+
+    /**
+     * Whether to clear the output directory before generating the files.
+     * @default true
+     */
+    clearOutputDir: boolean;
+
+    /**
+     * How to handle existing files in the output directory.
+     * - 'override': overwrite existing files.
+     * - 'skip': skip generating files that already exist.
+     * - 'error': throw an error if a file already exists.
+     * - 'count': write to a new path derived by inserting `_1` before the file extension (`_2`, `_3`, ... if that
+     *   path is also taken). A counted file is written under a name no other generated file references. The
+     *   generators compute a schema's file path from its name and use that same path when they emit an import or
+     *   type reference, so the reference still points at the first file written. `'count'` makes a collision
+     *   inspectable instead of fatal; it does not make the output correct. It also has a second failure mode
+     *   unrelated to collisions: with `clearOutputDir: false`, every regeneration finds the previous run's file
+     *   already on disk and counts up again, so re-running the generator against the same output directory silently
+     *   accumulates another `_N` file per schema on every run, forever, with no error to signal it.
+     *
+     * Is is recommended to use `'error'` to prevent issues of two schemas generating the same file and overwriting each other.
+     * If `clearOutputDir` is set to `false`, it is recommended to use `'override'` instead of `'count'` to ensure
+     * that the generated files are up to date without accumulating stale counted copies on every run.
+     * @default 'error'
+     */
+    existingFileBehavior: 'override' | 'skip' | 'error' | 'count';
+  };
+
+export const defaultOpenApiGeneratorConfig: OpenApiGeneratorConfig = {
+  ...defaultSourceBuilderOptions,
+  ...defaultOpenApiTransformerOptions,
+
+  outputDir: 'generated',
+  clearOutputDir: true,
+  existingFileBehavior: 'error',
+};

package/src/src/codegen/endpoints-generator.ts

@@ -0,0 +1,72 @@
+import type { ApiEndpoint } from '../transform/api-types.js';
+import type { MaybePromise } from '../utils/type.utils.js';
+import { type DefaultGenerationProviderConfig, OpenApiGenerationProviderBase } from './generator.js';
+import { addSourceIfTest } from './internal-utils.js';
+import type {
+  AnyConfig,
+  OpenApiGenerationProviderContext,
+  OpenApiGeneratorContext,
+  OpenApiGeneratorInput,
+  OpenApiGeneratorOutput,
+} from './types.js';
+
+export type OpenApiEndpointsGenerationProviderContext<
+  TInput extends OpenApiGeneratorInput,
+  TOutput extends OpenApiGeneratorOutput,
+  TConfig extends AnyConfig,
+  TEndpointOutput extends OpenApiGeneratorOutput,
+> = OpenApiGenerationProviderContext<TInput, TConfig> & {
+  existingEndpointResults: Map<string, TEndpointOutput>;
+  output: TOutput;
+};
+
+export abstract class OpenApiEndpointsGenerationProviderBase<
+  TInput extends OpenApiGeneratorInput,
+  TOutput extends OpenApiGeneratorOutput,
+  TConfig extends AnyConfig,
+  TEndpointOutput extends OpenApiGeneratorOutput,
+  TContext extends OpenApiEndpointsGenerationProviderContext<TInput, TOutput, TConfig, TEndpointOutput>,
+> extends OpenApiGenerationProviderBase<TInput, TOutput, TConfig, TContext> {
+  protected override getProviderContext(
+    context: OpenApiGeneratorContext<TInput>,
+    config: Partial<TConfig> | undefined,
+    defaultConfig: DefaultGenerationProviderConfig<TConfig>,
+  ): OpenApiEndpointsGenerationProviderContext<TInput, TOutput, TConfig, TEndpointOutput> {
+    const ctx = super.getProviderContext(context, config, defaultConfig);
+    return Object.assign(ctx, {
+      existingEndpointResults: new Map<string, TEndpointOutput>(),
+      output: this.initResult(ctx),
+    });
+  }
+
+  protected override async onGenerate(ctx: TContext): Promise<TOutput> {
+    for (const endpoint of ctx.data.endpoints) {
+      await this.getEndpointResult(ctx, endpoint);
+    }
+
+    await this.generateAdditionalFiles(ctx);
+
+    return ctx.output;
+  }
+
+  public async getEndpointResult(ctx: TContext, endpoint: ApiEndpoint): Promise<TEndpointOutput> {
+    const existingResult = ctx.existingEndpointResults.get(endpoint.id);
+    if (existingResult) return existingResult;
+
+    const result = await this.generateEndpoint(ctx, endpoint);
+    addSourceIfTest(ctx.config, result, () => `${endpoint.$src.file}#${endpoint.$src.path}`);
+    this.addEndpointResult(ctx, endpoint, result);
+    return result;
+  }
+
+  protected abstract initResult(ctx: OpenApiGenerationProviderContext<TInput, TConfig>): TOutput;
+
+  protected abstract generateEndpoint(ctx: TContext, endpoint: ApiEndpoint): Promise<TEndpointOutput>;
+
+  protected abstract addEndpointResult(ctx: TContext, endpoint: ApiEndpoint, result: TEndpointOutput): void;
+
+  // deno-lint-ignore no-unused-vars
+  protected generateAdditionalFiles(ctx: TContext): MaybePromise<void> {
+    // Override if needed
+  }
+}

package/src/src/codegen/generator.ts

@@ -0,0 +1,192 @@
+import { resolve } from 'node:path';
+
+
+import fs from 'fs-extra';
+
+import { OpenApiParser } from '../parse/parser.js';
+import type { ApiData } from '../transform/api-types.js';
+import { ActionProvider } from '../utils/action-provider.js';
+import { type DirectoryScanOptions, getFiles } from '../utils/file-system.utils.js';
+import type { EmptyConstructor, Merge } from '../utils/type.utils.js';
+import { defaultOpenApiGeneratorConfig, type OpenApiGeneratorConfig } from './config.js';
+import type {
+  AnyConfig,
+  OpenApiGenerationProvider,
+  OpenApiGenerationProviderContext,
+  OpenApiGenerationProviderFn,
+  OpenApiGeneratorContext,
+  OpenApiGeneratorInput,
+  OpenApiGeneratorOutput,
+} from './types.js';
+
+type OpenApiGenerationProviders = {
+  provider: ActionProvider<OpenApiGenerationProviderFn>;
+  config: AnyConfig | undefined;
+}[];
+
+type VInput<TActual, TExpected> = TExpected extends TActual ? TActual
+  : { __error: 'The current output of the generator does not satisfy the input of this generator.' };
+
+class _OpenApiGenerator<TOutput extends OpenApiGeneratorInput> {
+  private readonly _providers: OpenApiGenerationProviders;
+  private readonly _config: OpenApiGeneratorConfig;
+  private readonly _parser: OpenApiParser;
+
+  constructor(config: OpenApiGeneratorConfig, providers: OpenApiGenerationProviders, parser: OpenApiParser) {
+    this._providers = providers;
+    this._config = config;
+    this._parser = parser;
+  }
+
+  public use<PInput extends OpenApiGeneratorInput, POutput extends OpenApiGeneratorOutput, PConfig extends AnyConfig>(
+    provider: ActionProvider<OpenApiGenerationProviderFn<VInput<PInput, TOutput>, POutput, PConfig>>,
+    config?: Partial<PConfig>,
+  ): _OpenApiGenerator<Merge<[TOutput, POutput]>> {
+    // deno-lint-ignore no-explicit-any
+    this._providers.push({ provider: provider as any, config });
+    return new _OpenApiGenerator<Merge<[TOutput, POutput]>>(this._config, [...this._providers], this._parser);
+  }
+
+  public useType<
+    PInput extends OpenApiGeneratorInput,
+    POutput extends OpenApiGeneratorOutput,
+    PConfig extends AnyConfig,
+  >(
+    type: EmptyConstructor<OpenApiGenerationProvider<VInput<PInput, TOutput>, POutput, PConfig>>,
+    config?: Partial<PConfig>,
+  ): _OpenApiGenerator<Merge<[TOutput, POutput]>> {
+    return this.use(ActionProvider.fromType(type, 'generate'), config);
+  }
+
+  public useFn<PInput extends TOutput, POutput extends OpenApiGeneratorOutput, PConfig extends AnyConfig>(
+    fn: OpenApiGenerationProviderFn<VInput<PInput, TOutput>, POutput, PConfig>,
+    config?: Partial<PConfig>,
+  ): _OpenApiGenerator<Merge<[TOutput, POutput]>> {
+    return this.use(ActionProvider.fromFn(fn), config);
+  }
+
+  public useValue<PInput extends TOutput, POutput extends OpenApiGeneratorOutput, PConfig extends AnyConfig>(
+    value: OpenApiGenerationProvider<VInput<PInput, TOutput>, POutput, PConfig>,
+    config?: Partial<PConfig>,
+  ): _OpenApiGenerator<Merge<[TOutput, POutput]>> {
+    return this.use(ActionProvider.fromValue(value, 'generate'), config);
+  }
+
+  public async generate<T extends ApiData>(data: T): Promise<TOutput> {
+    const absOutputPath = resolve(this._config.outputDir);
+    if (this._config.clearOutputDir) {
+      await fs.emptyDir(absOutputPath);
+    } else {
+      await fs.ensureDir(absOutputPath);
+    }
+
+    this._providers.forEach(({ config }) => {
+      if (config && 'outputDir' in config && config.outputDir && typeof config.outputDir === 'string') {
+        const providerOutputDir = resolve(config.outputDir);
+        if (this._config.clearOutputDir) {
+          fs.emptyDirSync(providerOutputDir);
+        } else {
+          fs.ensureDirSync(providerOutputDir);
+        }
+      }
+    });
+
+    let input = {} as TOutput;
+    for (const generator of this._providers) {
+      const context = {
+        data,
+        input,
+        config: this._config,
+      };
+
+      const result = await generator.provider.run(context, generator.config);
+      if (result) {
+        input = mergeDeep(input, result);
+      }
+    }
+
+    return input;
+  }
+
+  public async parseAndGenerate(...fileNames: (string | string[])[]): Promise<TOutput> {
+    const data = await this._parser.parseApisAndTransform(...fileNames);
+    return await this.generate(data);
+  }
+
+  public async parseAndGenerateFromDir(dir: string, options?: Partial<DirectoryScanOptions>): Promise<TOutput> {
+    const filter = (file: string) =>
+      (file.endsWith('.yml') || file.endsWith('.yaml') || file.endsWith('.json')) && (options?.filter?.(file) ?? true);
+    return this.parseAndGenerate(...(await getFiles(dir, { ...options, filter })));
+  }
+}
+
+// deno-lint-ignore ban-types
+export class OpenApiGenerator extends _OpenApiGenerator<{}> {
+  constructor(config?: Partial<OpenApiGeneratorConfig>) {
+    super(
+      { ...defaultOpenApiGeneratorConfig, ...config },
+      [],
+      new OpenApiParser({ ...defaultOpenApiGeneratorConfig, ...config }),
+    );
+  }
+}
+
+function mergeDeep<T extends Record<string, unknown>, U extends Record<string, unknown>[]>(
+  target: T,
+  ...sources: U
+): T & U[number] {
+  if (!sources.length) return target;
+  const source = sources.shift();
+
+  for (const key in source) {
+    const value = source[key];
+    if (value && typeof value === 'object') {
+      if (!target[key]) Object.assign(target, { [key]: value });
+      else mergeDeep(target[key] as Record<string, unknown>, value as Record<string, unknown>);
+    } else if (Array.isArray(value)) {
+      if (!target[key]) Object.assign(target, { [key]: value });
+      else Object.assign(target, { [key]: [...(target[key] as Iterable<unknown>), ...value] });
+    } else {
+      Object.assign(target, { [key]: value });
+    }
+  }
+
+  return mergeDeep(target, ...sources);
+}
+
+export type DefaultGenerationProviderConfig<T extends AnyConfig> =
+  & Omit<T, keyof OpenApiGeneratorConfig>
+  & Partial<Pick<T, keyof OpenApiGeneratorConfig>>;
+
+export abstract class OpenApiGenerationProviderBase<
+  TInput extends OpenApiGeneratorInput,
+  TOutput extends OpenApiGeneratorOutput,
+  TConfig extends AnyConfig,
+  TContext extends OpenApiGenerationProviderContext<TInput, TConfig>,
+> implements OpenApiGenerationProvider<TInput, TOutput, TConfig> {
+  public async generate(
+    context: OpenApiGeneratorContext<TInput>,
+    config?: Partial<TConfig> | undefined,
+  ): Promise<TOutput> {
+    const ctx = await this.buildContext(context, config);
+    return await this.onGenerate(ctx);
+  }
+
+  protected getProviderContext(
+    context: OpenApiGeneratorContext<TInput>,
+    config: Partial<TConfig> | undefined,
+    defaultConfig: DefaultGenerationProviderConfig<TConfig>,
+  ): OpenApiGenerationProviderContext<TInput, TConfig> {
+    const c = { ...context.config, ...defaultConfig, ...config } as unknown as OpenApiGeneratorConfig & TConfig;
+    return Object.assign(context, {
+      config: c,
+    });
+  }
+
+  protected abstract buildContext(
+    context: OpenApiGeneratorContext<TInput>,
+    config?: Partial<TConfig> | undefined,
+  ): TContext | Promise<TContext>;
+
+  protected abstract onGenerate(ctx: TContext): TOutput | Promise<TOutput>;
+}

package/src/src/codegen/internal-utils.ts

@@ -0,0 +1,6 @@
+// deno-lint-ignore no-explicit-any
+export function addSourceIfTest(config: any, result: any, sourceFn: () => any) {
+  if (config.__test__ && !result.__source__) {
+    result.__source__ = sourceFn();
+  }
+}

package/src/src/codegen/schemas-generator.ts

@@ -0,0 +1,87 @@
+import type { ApiSchema } from '../transform/api-types.js';
+import { getSchemaReference } from '../utils/schema.utils.js';
+import type { MaybePromise } from '../utils/type.utils.js';
+import { type DefaultGenerationProviderConfig, OpenApiGenerationProviderBase } from './generator.js';
+import { addSourceIfTest } from './internal-utils.js';
+import type {
+  AnyConfig,
+  OpenApiGenerationProviderContext,
+  OpenApiGeneratorContext,
+  OpenApiGeneratorInput,
+  OpenApiGeneratorOutput,
+} from './types.js';
+
+export type OpenApiSchemasGenerationProviderContext<
+  TInput extends OpenApiGeneratorInput,
+  TOutput extends OpenApiGeneratorOutput,
+  TConfig extends AnyConfig,
+  TSchemaOutput extends OpenApiGeneratorOutput,
+> = OpenApiGenerationProviderContext<TInput, TConfig> & {
+  existingSchemaResults: Map<string, TSchemaOutput>;
+  output: TOutput;
+};
+
+export abstract class OpenApiSchemasGenerationProviderBase<
+  TInput extends OpenApiGeneratorInput,
+  TOutput extends OpenApiGeneratorOutput,
+  TConfig extends AnyConfig,
+  TSchemaOutput extends OpenApiGeneratorOutput,
+  TContext extends OpenApiSchemasGenerationProviderContext<TInput, TOutput, TConfig, TSchemaOutput>,
+> extends OpenApiGenerationProviderBase<TInput, TOutput, TConfig, TContext> {
+  protected override getProviderContext(
+    context: OpenApiGeneratorContext<TInput>,
+    config: Partial<TConfig> | undefined,
+    defaultConfig: DefaultGenerationProviderConfig<TConfig>,
+  ): OpenApiSchemasGenerationProviderContext<TInput, TOutput, TConfig, TSchemaOutput> {
+    const ctx = super.getProviderContext(context, config, defaultConfig);
+    return Object.assign(ctx, {
+      existingSchemaResults: new Map<string, TSchemaOutput>(),
+      output: this.initResult(ctx),
+    });
+  }
+
+  protected override async onGenerate(ctx: TContext): Promise<TOutput> {
+    for (const schema of ctx.data.schemas) {
+      await this.getSchemaResult(ctx, schema);
+    }
+
+    await this.generateAdditionalFiles(ctx);
+
+    return ctx.output;
+  }
+
+  public async getSchemaResult(ctx: TContext, schema: ApiSchema): Promise<TSchemaOutput> {
+    const existingResult = ctx.existingSchemaResults.get(schema.id);
+    if (existingResult) return existingResult;
+
+    let result: TSchemaOutput;
+    const reference = this.getSchemaReference(ctx, schema);
+    if (reference) {
+      result = await this.getSchemaResult(ctx, reference);
+    } else {
+      result = await this.generateSchema(ctx, schema);
+    }
+
+    addSourceIfTest(ctx.config, result, () => `${schema.$src.file}#${schema.$src.path}`);
+    ctx.existingSchemaResults.set(schema.id, result);
+    this.addSchemaResult(ctx, schema, result);
+    return result;
+  }
+
+  // deno-lint-ignore no-unused-vars
+  protected getSchemaReference(ctx: TContext, schema: ApiSchema): ApiSchema | undefined {
+    const ref = getSchemaReference(schema, ['description']);
+    return ref.id !== schema.id ? ref : undefined;
+  }
+
+  protected abstract initResult(ctx: OpenApiGenerationProviderContext<TInput, TConfig>): TOutput;
+
+  protected abstract generateSchema(ctx: TContext, schema: ApiSchema): MaybePromise<TSchemaOutput>;
+
+  protected abstract addSchemaResult(ctx: TContext, schema: ApiSchema, result: TSchemaOutput): void;
+
+  // deno-lint-ignore no-unused-vars
+  protected generateAdditionalFiles(ctx: TContext): MaybePromise<void> {
+    // Override if needed
+  }
+}

package/src/src/codegen/services-generator.ts

@@ -0,0 +1,77 @@
+import type { ApiService } from '../transform/api-types.js';
+import type { MaybePromise } from '../utils/type.utils.js';
+import { type DefaultGenerationProviderConfig, OpenApiGenerationProviderBase } from './generator.js';
+import { addSourceIfTest } from './internal-utils.js';
+import type {
+  AnyConfig,
+  OpenApiGenerationProviderContext,
+  OpenApiGeneratorContext,
+  OpenApiGeneratorInput,
+  OpenApiGeneratorOutput,
+} from './types.js';
+
+export type OpenApiServicesGenerationProviderContext<
+  TInput extends OpenApiGeneratorInput,
+  TOutput extends OpenApiGeneratorOutput,
+  TConfig extends AnyConfig,
+  TServiceOutput extends OpenApiGeneratorOutput,
+> = OpenApiGenerationProviderContext<TInput, TConfig> & {
+  existingServiceResults: Map<string, TServiceOutput>;
+  output: TOutput;
+};
+
+export abstract class OpenApiServicesGenerationProviderBase<
+  TInput extends OpenApiGeneratorInput,
+  TOutput extends OpenApiGeneratorOutput,
+  TConfig extends AnyConfig,
+  TServiceOutput extends OpenApiGeneratorOutput,
+  TContext extends OpenApiServicesGenerationProviderContext<TInput, TOutput, TConfig, TServiceOutput>,
+> extends OpenApiGenerationProviderBase<TInput, TOutput, TConfig, TContext> {
+  protected override getProviderContext(
+    context: OpenApiGeneratorContext<TInput>,
+    config: Partial<TConfig> | undefined,
+    defaultConfig: DefaultGenerationProviderConfig<TConfig>,
+  ): OpenApiServicesGenerationProviderContext<TInput, TOutput, TConfig, TServiceOutput> {
+    const ctx = super.getProviderContext(context, config, defaultConfig);
+    return Object.assign(ctx, {
+      existingServiceResults: new Map<string, TServiceOutput>(),
+      output: this.initResult(ctx),
+    });
+  }
+
+  protected override async onGenerate(ctx: TContext): Promise<TOutput> {
+    for (const service of ctx.data.services) {
+      await this.getServiceResult(ctx, service);
+    }
+
+    await this.generateAdditionalFiles(ctx);
+
+    return ctx.output;
+  }
+
+  protected async getServiceResult(ctx: TContext, service: ApiService): Promise<TServiceOutput> {
+    const existingResult = ctx.existingServiceResults.get(service.id);
+    if (existingResult) return existingResult;
+
+    const result = await this.generateService(ctx, service);
+
+    addSourceIfTest(
+      ctx.config,
+      result,
+      () => service.$src ? `${service.$src.file}#${service.$src.path}` : `tag:${service.name}`,
+    );
+    this.addServiceResult(ctx, service, result);
+    return result;
+  }
+
+  protected abstract initResult(ctx: OpenApiGenerationProviderContext<TInput, TConfig>): TOutput;
+
+  protected abstract generateService(ctx: TContext, service: ApiService): MaybePromise<TServiceOutput>;
+
+  protected abstract addServiceResult(ctx: TContext, service: ApiService, result: TServiceOutput): void;
+
+  // deno-lint-ignore no-unused-vars
+  protected generateAdditionalFiles(ctx: TContext): MaybePromise<void> {
+    // Override if needed
+  }
+}