@goast/core 0.4.0-beta3 → 0.4.0

package/src/src/transform/helpers.test.ts

@@ -0,0 +1,316 @@
+import "../../_dnt.test_polyfills.js";
+import { expect, fn } from '../../deps/jsr.io/@std/expect/1.0.5/mod.js';
+import { describe, test } from '../../deps/jsr.io/@std/testing/1.0.3/bdd.js';
+import type { OpenApiDocument } from '../parse/openapi-types.js';
+import type { Deref } from '../parse/types.js';
+import type { ApiSchema } from './api-types.js';
+import {
+  determineEndpointName,
+  determineSchemaAccessibility,
+  determineSchemaKind,
+  determineSchemaName,
+  getCustomFields,
+  IdGenerator,
+  transformAdditionalProperties,
+  transformSchemaProperties,
+} from './helpers.js';
+import type { OpenApiTransformerContext } from './types.js';
+
+describe('determineSchemaKind', () => {
+  const ctx = { config: { unknownTypeBehavior: 'keep-unknown' } } as OpenApiTransformerContext;
+
+  test('returns "oneOf" if schema has "oneOf" property', () => {
+    const schema = { oneOf: [{}] };
+    expect(determineSchemaKind(ctx, schema)).toBe('oneOf');
+  });
+
+  test('returns "combined" if schema has "allOf" or "anyOf" property', () => {
+    const schema = { allOf: [{}], anyOf: [{}] };
+    expect(determineSchemaKind(ctx, schema)).toBe('combined');
+  });
+
+  test('returns "multi-type" if schema has "type" property as an array', () => {
+    const schema = { type: ['string', 'number'] };
+    expect(determineSchemaKind(ctx, schema)).toBe('multi-type');
+  });
+
+  test('returns the value of "type" property if it is a string', () => {
+    const schema = { type: 'string' };
+    expect(determineSchemaKind(ctx, schema)).toBe('string');
+  });
+
+  test('returns "unknown" if schema has no recognizable properties', () => {
+    const schema = {};
+    expect(determineSchemaKind(ctx, schema)).toBe('unknown');
+  });
+});
+
+describe('determineSchemaName', () => {
+  test('returns the schema title if it exists', () => {
+    const schema = {
+      title: 'TestSchema',
+      $src: { file: 'my-api.yml', path: '/test/schema', document: {} as Deref<OpenApiDocument>, originalComponent: {} },
+    };
+    expect(determineSchemaName(schema, 'TestId')).toEqual({
+      name: 'TestSchema',
+      isGenerated: false,
+    });
+  });
+
+  test("returns the json schema file name if the schema title doesn't exist", () => {
+    const schema = {
+      $src: { path: '/', file: 'test.json', document: {} as Deref<OpenApiDocument>, originalComponent: {} },
+    };
+    expect(determineSchemaName(schema, 'TestId')).toEqual({
+      name: 'test',
+      isGenerated: true,
+    });
+  });
+
+  test('returns the schema name extracted from $src.path if it starts with "/components/schemas/"', () => {
+    const schema = {
+      $src: {
+        file: 'my-api.yml',
+        path: '/components/schemas/TestSchema',
+        document: {} as Deref<OpenApiDocument>,
+        originalComponent: {},
+      },
+    };
+    expect(determineSchemaName(schema, 'TestId')).toEqual({
+      name: 'TestSchema',
+      isGenerated: false,
+    });
+  });
+
+  test('returns the schema name extracted from $src.path if it starts with "/definitions/"', () => {
+    const schema = {
+      $src: {
+        file: 'my-api.yml',
+        path: '/definitions/TestSchema',
+        document: {} as Deref<OpenApiDocument>,
+        originalComponent: {},
+      },
+    };
+    expect(determineSchemaName(schema, 'TestId')).toEqual({
+      name: 'TestSchema',
+      isGenerated: false,
+    });
+  });
+
+  test('returns a generated name based on the $src.path for response schemas', () => {
+    const schema = {
+      $src: {
+        file: 'my-api.yml',
+        path: '/paths/users/{userId}/email-verification/{token}/get/responses/200/',
+        document: {} as Deref<OpenApiDocument>,
+        originalComponent: {},
+      },
+    };
+    expect(determineSchemaName(schema, 'TestId')).toEqual({
+      name: 'get_users_:userId_email-verification_:token_200_Response',
+      isGenerated: true,
+    });
+  });
+
+  test('returns the provided id if no other name can be determined', () => {
+    const schema = {
+      $src: { file: 'my-api.yml', path: '/test/schema', document: {} as Deref<OpenApiDocument>, originalComponent: {} },
+    };
+    expect(determineSchemaName(schema, 'TestId')).toEqual({ name: 'TestId', isGenerated: true });
+  });
+});
+
+describe('determineSchemaAccessibility', () => {
+  test('returns "readOnly" if "readOnly" property is true and "writeOnly" property is false or undefined', () => {
+    const schema = { readOnly: true };
+    expect(determineSchemaAccessibility(schema)).toBe('readOnly');
+  });
+
+  test('returns "writeOnly" if "writeOnly" property is true and "readOnly" property is false or undefined', () => {
+    const schema = { writeOnly: true };
+    expect(determineSchemaAccessibility(schema)).toBe('writeOnly');
+  });
+
+  test('returns "none" if both "readOnly" and "writeOnly" properties are true', () => {
+    const schema = { readOnly: true, writeOnly: true };
+    expect(determineSchemaAccessibility(schema)).toBe('none');
+  });
+
+  test('returns "all" if neither "readOnly" nor "writeOnly" properties are true', () => {
+    const schema = {};
+    expect(determineSchemaAccessibility(schema)).toBe('all');
+  });
+});
+
+describe('getCustomFields', () => {
+  test('returns an empty object if no custom fields are present', () => {
+    const schema = { type: 'string' };
+    expect(getCustomFields(schema)).toEqual({});
+  });
+
+  test('returns an object containing all custom fields starting with "x-"', () => {
+    const schema = {
+      type: 'string',
+      'x-custom-field-1': 'value1',
+      'x-custom-field-2': 'value2',
+    };
+    expect(getCustomFields(schema)).toEqual({
+      'custom-field-1': 'value1',
+      'custom-field-2': 'value2',
+    });
+  });
+
+  test('returns an object containing only custom fields starting with "x-"', () => {
+    const schema = {
+      type: 'string',
+      'x-custom-field-1': 'value1',
+      'not-a-custom-field': 'value2',
+    };
+    expect(getCustomFields(schema)).toEqual({ 'custom-field-1': 'value1' });
+  });
+
+  test('returns an object with the same values as the original custom fields', () => {
+    const schema = {
+      type: 'string',
+      'x-custom-field-1': { key1: 'value1' },
+      'x-custom-field-2': ['value2'],
+    };
+    expect(getCustomFields(schema)).toEqual({
+      'custom-field-1': { key1: 'value1' },
+      'custom-field-2': ['value2'],
+    });
+  });
+});
+
+describe('determineEndpointName', () => {
+  test('returns the operationId if it exists', () => {
+    const endpointInfo = {
+      method: 'get',
+      path: '/users',
+      operation: { operationId: 'getUserList' },
+    };
+    expect(determineEndpointName(endpointInfo)).toBe('getUserList');
+  });
+
+  test('returns a generated name based on the method and path if operationId is not present', () => {
+    const endpointInfo = { method: 'post', path: '/users/{userId}/comments', operation: {} };
+    expect(determineEndpointName(endpointInfo)).toBe('post_users_:userId_comments');
+  });
+
+  test('replaces path parameters with their names in the generated name', () => {
+    const endpointInfo = {
+      method: 'get',
+      path: '/users/{userId}/comments/{commentId}',
+      operation: {},
+    };
+    expect(determineEndpointName(endpointInfo)).toBe('get_users_:userId_comments_:commentId');
+  });
+
+  test('replaces slashes in the path with underscores in the generated name', () => {
+    const endpointInfo = { method: 'put', path: '/users/{userId}/profile-picture', operation: {} };
+    expect(determineEndpointName(endpointInfo)).toBe('put_users_:userId_profile-picture');
+  });
+});
+
+describe('transformAdditionalProperties', () => {
+  const context = {} as OpenApiTransformerContext;
+
+  test('returns undefined if additionalProperties is undefined or null', () => {
+    const schema1 = { additionalProperties: undefined };
+    const schema2 = { additionalProperties: null };
+    expect(transformAdditionalProperties(context, schema1, () => ({}) as ApiSchema)).toBeUndefined();
+    expect(transformAdditionalProperties(context, schema2, () => ({}) as ApiSchema)).toBeUndefined();
+  });
+
+  test('returns a boolean value if additionalProperties is a boolean value', () => {
+    const schema1 = { additionalProperties: true };
+    const schema2 = { additionalProperties: false };
+    expect(transformAdditionalProperties(context, schema1, () => ({}) as ApiSchema)).toBe(true);
+    expect(transformAdditionalProperties(context, schema2, () => ({}) as ApiSchema)).toBe(false);
+  });
+
+  test('calls transformSchema with the additionalProperties schema if it exists', () => {
+    const schema = { additionalProperties: { type: 'string' } };
+    const transformSchema = fn(() => ({})) as () => ApiSchema;
+    transformAdditionalProperties(context, schema, transformSchema);
+    expect(transformSchema).toHaveBeenCalledWith(context, schema.additionalProperties);
+  });
+
+  test('returns the result of calling transformSchema with the additionalProperties schema if it exists', () => {
+    const schema = { additionalProperties: { type: 'string' } };
+    const transformedSchema = { type: 'string' } as ApiSchema;
+    const transformSchema = fn(() => transformedSchema) as () => ApiSchema;
+    expect(transformAdditionalProperties(context, schema, transformSchema)).toBe(transformedSchema);
+  });
+});
+
+describe('transformSchemaProperties', () => {
+  const context = {} as OpenApiTransformerContext;
+
+  test('returns an empty array if properties is undefined', () => {
+    const schema = {};
+    const transformSchema = fn(() => ({})) as () => ApiSchema;
+    expect(transformSchemaProperties(context, schema, transformSchema).size).toEqual(0);
+  });
+
+  test('calls transformSchema with each property schema and builds an array of ApiSchemaProperties', () => {
+    const schema = {
+      properties: {
+        prop1: { type: 'string' } as ApiSchema,
+        prop2: { type: 'integer' } as ApiSchema,
+      },
+      required: ['prop1'],
+    };
+    const transformedSchema1 = { type: 'string' } as ApiSchema;
+    const transformedSchema2 = { type: 'integer' } as ApiSchema;
+    // deno-lint-ignore no-explicit-any
+    const transformSchema = fn((_: unknown, subSchema: any) =>
+      subSchema.type === 'string' ? transformedSchema1 : transformedSchema2
+    ) as (ctx: OpenApiTransformerContext, schema: ApiSchema) => ApiSchema;
+    const result = transformSchemaProperties(context, schema, transformSchema);
+    expect(Array.from(result.entries())).toEqual([
+      ['prop1', { name: 'prop1', schema: transformedSchema1 }],
+      ['prop2', { name: 'prop2', schema: transformedSchema2 }],
+    ]);
+    expect(transformSchema).toHaveBeenCalledTimes(2);
+    expect(transformSchema).toHaveBeenCalledWith(context, schema.properties.prop1);
+    expect(transformSchema).toHaveBeenCalledWith(context, schema.properties.prop2);
+  });
+
+  test('ignores properties with the name "$src"', () => {
+    const schema = { properties: { prop1: { type: 'string' }, $src: { path: '/test/schema' } } };
+    const transformedSchema1 = { type: 'string' } as ApiSchema;
+    const transformSchema = fn(() => transformedSchema1) as () => ApiSchema;
+    const result = transformSchemaProperties(context, schema, transformSchema);
+    expect(Array.from(result.entries())).toEqual([['prop1', { name: 'prop1', schema: transformedSchema1 }]]);
+    expect(transformSchema).toHaveBeenCalledTimes(1);
+    expect(transformSchema).toHaveBeenCalledWith(context, schema.properties.prop1);
+  });
+});
+
+describe('IdGenerator', () => {
+  test('generates unique ids based on the provided name', () => {
+    const idGenerator = new IdGenerator();
+    const id1 = idGenerator.generateId('test');
+    const id2 = idGenerator.generateId('test');
+    expect(id1).not.toBe(id2);
+  });
+
+  test('generates ids with the format "{name}-{n}"', () => {
+    const idGenerator = new IdGenerator();
+    const id1 = idGenerator.generateId('test');
+    expect(id1).toMatch(/^test-\d+$/);
+  });
+
+  test('increments the id number for each new id generated with the same name', () => {
+    const idGenerator = new IdGenerator();
+    const id1 = idGenerator.generateId('test');
+    const id2 = idGenerator.generateId('test');
+    const id3 = idGenerator.generateId('test2');
+    const id4 = idGenerator.generateId('test');
+    expect(id1).toBe('test-1');
+    expect(id2).toBe('test-2');
+    expect(id3).toBe('test2-1');
+    expect(id4).toBe('test-3');
+  });
+});

package/src/src/transform/helpers.ts

@@ -0,0 +1,211 @@
+import { parse as parsePath } from 'node:path';
+import { isOpenApiObjectProperty } from '../internal-utils.js';
+import type { OpenApiHttpMethod, OpenApiObject } from '../parse/openapi-types.js';
+import type { Deref, DerefSource } from '../parse/types.js';
+import { isNullish } from '../utils/common.utils.js';
+import { getDeepProperty } from '../utils/object.utils.js';
+import type { ApiSchema, ApiSchemaAccessibility, ApiSchemaKind, ApiSchemaProperty } from './api-types.js';
+import type { OpenApiTransformerContext } from './types.js';
+
+export function determineSchemaKind<
+  T extends {
+    oneOf?: unknown;
+    allOf?: unknown;
+    anyOf?: unknown;
+    type?: string | string[];
+    properties?: Record<string, unknown>;
+    additionalProperties?: unknown;
+  },
+>(ctx: OpenApiTransformerContext, schema: T): ApiSchemaKind {
+  if (schema.oneOf) {
+    return 'oneOf';
+  } else if (schema.type !== 'object' && (schema.allOf || schema.anyOf)) {
+    const hasProperties = (schema.properties && Object.keys(schema.properties).length > 0) ||
+      schema.additionalProperties;
+    return hasProperties ? 'object' : 'combined';
+  } else if (Array.isArray(schema.type)) {
+    return 'multi-type';
+  } else if (
+    schema.type === 'object' ||
+    schema.type === 'string' ||
+    schema.type === 'boolean' ||
+    schema.type === 'null' ||
+    schema.type === 'number' ||
+    schema.type === 'integer' ||
+    schema.type === 'array'
+  ) {
+    return schema.type;
+  }
+
+  const treadAsObject = ctx.config.unknownTypeBehavior === 'always-object' ||
+    (ctx.config.unknownTypeBehavior === 'object-if-properties' &&
+      schema.properties &&
+      Object.keys(schema.properties).length > 0);
+
+  return treadAsObject ? 'object' : 'unknown';
+}
+
+export function determineSchemaName(
+  schema: {
+    title?: string;
+    $src: DerefSource<unknown>;
+  },
+  id: string,
+): { name: string; isGenerated: boolean } {
+  if (schema.title) return { name: schema.title, isGenerated: false };
+  if (!schema.$src) {
+    console.log('woot?');
+  }
+
+  if (schema.$src.path === '/') return { name: parsePath(schema.$src.file).name, isGenerated: true };
+
+  const schemaNameMatch = schema.$src.path.match(/(?<=\/components\/schemas\/|\/definitions\/)[^/]+$/i);
+  if (schemaNameMatch) {
+    return { name: schemaNameMatch[0], isGenerated: false };
+  }
+
+  const responseMatch = schema.$src.path.match(/\/paths\/(?<path>.+)\/(?<method>.+)\/responses\/(?<status>\d+)\//);
+  if (responseMatch && responseMatch.groups) {
+    const { path, method, status } = responseMatch.groups;
+    const operation = schema.$src.document.paths?.[path]?.[method as OpenApiHttpMethod] ?? {};
+    return {
+      name: `${determineEndpointName({ method, path: `/${path}`, operation })}_${status}_Response`,
+      isGenerated: true,
+    };
+  }
+
+  const responseCompMatch = schema.$src.path.match(/\/components\/responses\/([^/]+)\/content\/.+\/schema/);
+  if (responseCompMatch) {
+    return {
+      name: responseCompMatch[1].toLowerCase().endsWith('response')
+        ? responseCompMatch[1]
+        : responseCompMatch[1] + 'Response',
+      isGenerated: true,
+    };
+  }
+
+  const requestBodyMatch = schema.$src.path.match(/\/paths\/(?<path>.+)\/(?<method>.+)\/requestBody\//);
+  if (requestBodyMatch && requestBodyMatch.groups) {
+    const { path, method } = requestBodyMatch.groups;
+    const operation = schema.$src.document.paths?.[path]?.[method as OpenApiHttpMethod] ?? {};
+    return { name: `${determineEndpointName({ method, path: `/${path}`, operation })}_Request`, isGenerated: true };
+  }
+
+  const parentSchemaMatch = schema.$src.path.match(/(.*)\/properties\/([^/]*)$/);
+  if (parentSchemaMatch) {
+    const parentSchema = getDeepProperty(schema.$src.document, parentSchemaMatch[1].split('/').filter(Boolean));
+    const parentSchemaName = determineSchemaName(
+      {
+        title: typeof parentSchema === 'object' && parentSchema !== null && 'title' in parentSchema
+          ? String(parentSchema.title)
+          : undefined,
+        $src: {
+          file: schema.$src.file,
+          path: parentSchemaMatch[1],
+          document: schema.$src.document,
+          originalComponent: parentSchema,
+        },
+      },
+      id,
+    );
+    if (!parentSchemaName.isGenerated) {
+      return { name: `${parentSchemaName.name}_${parentSchemaMatch[2]}`, isGenerated: true };
+    }
+  }
+
+  return { name: id, isGenerated: true };
+}
+
+export function determineSchemaAccessibility(schema: {
+  readOnly?: boolean;
+  writeOnly?: boolean;
+}): ApiSchemaAccessibility {
+  if (schema.readOnly === true) {
+    return schema.writeOnly === true ? 'none' : 'readOnly';
+  } else {
+    return schema.writeOnly === true ? 'writeOnly' : 'all';
+  }
+}
+
+export function updateSchemaAccessibility(
+  accessibility: ApiSchemaAccessibility,
+  schema: {
+    readOnly?: boolean;
+    writeOnly?: boolean;
+  },
+): ApiSchemaAccessibility {
+  if (accessibility === 'none') return 'none';
+  if (accessibility === 'readOnly') return schema.writeOnly === true ? 'none' : 'readOnly';
+  if (accessibility === 'writeOnly') return schema.readOnly === true ? 'none' : 'writeOnly';
+  return determineSchemaAccessibility(schema);
+}
+
+type CustomFields<T extends Record<string, unknown>> = {
+  [K in keyof T as K extends `x-${string}` ? K : never]: T[K];
+};
+
+export function getCustomFields<T extends Record<string, unknown>>(schema: T): CustomFields<T> {
+  const result = {} as CustomFields<T>;
+  for (const key in schema) {
+    if (key.startsWith('x-')) {
+      const name = key.substring(2);
+      (result as Record<string, unknown>)[name] = schema[key];
+    }
+  }
+  return result;
+}
+
+export function determineEndpointName(endpointInfo: {
+  method: string;
+  path: string;
+  operation: { operationId?: string };
+}): string {
+  if (endpointInfo.operation.operationId) return endpointInfo.operation.operationId;
+  return endpointInfo.method + endpointInfo.path.replace(/\{([^}]+)\}/g, ':$1').replace(/\//g, '_');
+}
+
+export function transformAdditionalProperties<TAdditionalProperties>(
+  context: OpenApiTransformerContext,
+  schema: {
+    additionalProperties?: TAdditionalProperties;
+  },
+  transformSchema: (
+    context: OpenApiTransformerContext,
+    schema: Exclude<TAdditionalProperties, undefined | boolean>,
+  ) => ApiSchema,
+): boolean | ApiSchema | undefined {
+  if (isNullish(schema.additionalProperties)) return undefined;
+  if (typeof schema.additionalProperties === 'boolean') return schema.additionalProperties;
+  return transformSchema(context, schema.additionalProperties as Exclude<TAdditionalProperties, undefined | boolean>);
+}
+
+export function transformSchemaProperties<TProperties>(
+  context: OpenApiTransformerContext,
+  schema: { properties?: Record<string, TProperties>; required?: string[] },
+  transformSchema: (context: OpenApiTransformerContext, schema: TProperties) => ApiSchema,
+): Map<string, ApiSchemaProperty> {
+  const result = new Map<string, ApiSchemaProperty>();
+  if (!schema.properties) return result;
+  for (const name of Object.keys(schema.properties)) {
+    if (!isOpenApiObjectProperty(name)) continue;
+    result.set(name, {
+      name,
+      schema: transformSchema(context, schema.properties[name]),
+    });
+  }
+  return result;
+}
+
+export class IdGenerator {
+  private readonly _idMap = new Map<string, number>();
+
+  public generateId(name: string): string {
+    const id = this._idMap.get(name) ?? 1;
+    this._idMap.set(name, id + 1);
+    return `${name}-${id}`;
+  }
+}
+
+export function getOpenApiObjectIdentifier(obj: Deref<OpenApiObject<string>>) {
+  return obj.$src.file + '#' + obj.$src.path;
+}

package/src/src/transform/transform-document.ts

@@ -0,0 +1,35 @@
+import type { OpenApiDocument, OpenApiTag } from '../parse/openapi-types.js';
+import type { Deref } from '../parse/types.js';
+import type { ApiService } from './api-types.js';
+import { getOpenApiObjectIdentifier } from './helpers.js';
+import type { OpenApiTransformerContext } from './types.js';
+
+export function transformDocument(context: OpenApiTransformerContext, document: Deref<OpenApiDocument>) {
+  for (const tag of document.tags ?? []) {
+    transformTag(context, tag);
+  }
+}
+
+function transformTag(context: OpenApiTransformerContext, tag: Deref<OpenApiTag>, isReference = false) {
+  const openApiObjectId = getOpenApiObjectIdentifier(tag);
+  const existing = context.transformed.services.get(openApiObjectId);
+  if (existing) return existing;
+
+  const ref = tag.$ref ? transformTag(context, tag.$ref, true) : undefined;
+  const id = context.idGenerator.generateId('service');
+  const service: ApiService = {
+    $src: {
+      ...tag.$src,
+      component: tag,
+    },
+    $ref: ref,
+    id,
+    name: tag.name ?? id,
+    description: tag.description,
+    endpoints: [],
+  };
+
+  context.transformed.services.set(openApiObjectId, service);
+  if (!isReference) context.services.set(service.name, service);
+  return service;
+}