@goast/core 0.4.0-beta4 → 0.4.1

package/src/src/collect/collector.ts

@@ -0,0 +1,142 @@
+import type {
+  OpenApiDocument,
+  OpenApiHeader,
+  OpenApiMediaType,
+  OpenApiParameter,
+  OpenApiPathItem,
+  OpenApiRequestBody,
+  OpenApiResponse,
+  OpenApiSchema,
+} from '../parse/openapi-types.js';
+import type { Deref } from '../parse/types.js';
+import { collect, collectRecord } from './helpers.js';
+import type { OpenApiCollectorData } from './types.js';
+
+type Collect<T> = Deref<T> | Deref<T>[] | undefined;
+
+export function collectOpenApi(apis: Deref<OpenApiDocument>[]): OpenApiCollectorData {
+  const data: OpenApiCollectorData = {
+    documents: [],
+    schemas: new Map(),
+    endpoints: new Map(),
+  };
+
+  collectDocument(data, apis);
+
+  return data;
+}
+
+const jsonSchemaProperties = ['$id', 'allOf', 'anyOf', 'oneOf', 'enum', 'not', 'properties', 'title', 'type'];
+
+function collectDocument(data: OpenApiCollectorData, documents: Collect<OpenApiDocument>) {
+  collect(data, documents, (data, document) => {
+    data.documents.push(document);
+    collectPaths(data, document.paths);
+    collectRecord<Deref<OpenApiSchema>>(data, document.components?.schemas, collectSchema);
+    collectRecord<Deref<OpenApiSchema>>(data, document.definitions, collectSchema);
+    collectRecord<Deref<OpenApiParameter>>(data, document.components?.parameters, collectParameter);
+    collectRecord<Deref<OpenApiParameter>>(data, document.parameters, collectParameter);
+    collectRecord<Deref<OpenApiRequestBody>>(data, document.components?.requestBodies, collectRequestBody);
+    collectRecord<Deref<OpenApiResponse>>(data, document.components?.responses, collectResponse);
+    collectRecord<Deref<OpenApiResponse>>(data, document.responses, collectResponse);
+    collectRecord<Deref<OpenApiHeader>>(data, document.components?.headers, collectHeader);
+
+    if (Object.keys(document).some((key) => jsonSchemaProperties.includes(key))) {
+      collectSchema(data, document as Deref<OpenApiSchema>);
+    }
+  });
+}
+
+function collectPaths(data: OpenApiCollectorData, paths: Collect<Record<string, OpenApiPathItem>>) {
+  collect(data, paths, (data, path) => {
+    collectRecord<Deref<OpenApiPathItem>>(data, path, collectPathItem);
+  });
+}
+
+function collectPathItem(data: OpenApiCollectorData, pathItems: Collect<OpenApiPathItem>, path: string) {
+  collect(data, pathItems, (data, pathItem) => {
+    collectParameter(data, pathItem.parameters);
+    for (const m of ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'] as const) {
+      const operation = pathItem[m];
+      if (!operation) continue;
+      const key = `${operation.$src.file}#${operation.$src.path}`;
+      if (data.endpoints.has(key)) continue;
+      data.endpoints.set(key, {
+        path,
+        method: m,
+        pathItem,
+        operation,
+      });
+      collectParameter(data, operation.parameters);
+      collectRequestBody(data, operation.requestBody);
+      collectRecord<Deref<OpenApiResponse>>(data, operation.responses, collectResponse);
+    }
+  });
+}
+
+function collectSchema(data: OpenApiCollectorData, schemas: Collect<OpenApiSchema>) {
+  collect(data, schemas, (data, schema) => {
+    const key = `${schema.$src.file}#${schema.$src.path}`;
+    if (data.schemas.has(key)) return;
+    data.schemas.set(key, schema);
+    collectSchema(data, schema.allOf);
+    collectSchema(data, schema.anyOf);
+    collectSchema(data, schema.oneOf);
+    collectSchema(data, schema.items);
+    collectSchema(data, schema.not);
+    collectRecord<Deref<OpenApiSchema>>(data, schema.properties, collectSchema);
+    collectRecord<Deref<OpenApiSchema>>(data, schema.patternProperties, collectSchema);
+    collectRecord<Deref<OpenApiSchema>>(data, schema.dependencies, collectSchema);
+    collectRecord<Deref<OpenApiSchema>>(data, schema.definitions, collectSchema);
+    if (typeof schema.additionalProperties === 'object') {
+      collectSchema(data, schema.additionalProperties);
+    }
+    if (typeof schema.additionalItems === 'object') {
+      collectSchema(data, schema.additionalItems);
+    }
+    if (typeof schema.discriminator === 'object') {
+      collectRecord<Deref<OpenApiSchema>>(data, schema.discriminator?.mapping, collectSchema);
+    }
+  });
+}
+
+function collectParameter(data: OpenApiCollectorData, parameters: Collect<OpenApiParameter>) {
+  collect(data, parameters, (data, parameter) => {
+    collectSchema(data, parameter.schema);
+  });
+}
+
+function collectMediaType(data: OpenApiCollectorData, mediaTypes: Collect<OpenApiMediaType>) {
+  collect(data, mediaTypes, (data, mediaType) => {
+    collectSchema(data, mediaType.schema);
+  });
+}
+
+function collectRequestBody(data: OpenApiCollectorData, requestBody: Collect<OpenApiRequestBody>) {
+  collect(data, requestBody, (data, requestBody) => {
+    collectRecord<Deref<OpenApiMediaType>>(data, requestBody.content, collectMediaType);
+  });
+}
+
+function isSchema(obj: Record<string, unknown>): obj is Deref<OpenApiSchema> {
+  return obj && typeof obj === 'object' && obj['type'] !== undefined;
+}
+
+function collectResponse(data: OpenApiCollectorData, responses: Collect<OpenApiResponse>) {
+  collect(data, responses, (data, responses) => {
+    collectRecord<Deref<OpenApiMediaType>>(data, responses.content, collectMediaType);
+    collect(data, responses.headers, (data, header) => {
+      if (isSchema(header)) {
+        collectSchema(data, header);
+      } else {
+        collectHeader(data, header);
+      }
+    });
+  });
+}
+
+function collectHeader(data: OpenApiCollectorData, headers: Collect<OpenApiHeader>) {
+  collect(data, headers, (data, headers) => {
+    collectSchema(data, headers.schema);
+  });
+}

package/src/src/collect/helpers.test.ts

@@ -0,0 +1,91 @@
+// deno-lint-ignore-file no-explicit-any
+import "../../_dnt.test_polyfills.js";
+
+import { expect, fn } from '../../deps/jsr.io/@std/expect/1.0.12/mod.js';
+import { beforeEach, describe, it, test } from '../../deps/jsr.io/@std/testing/1.0.9/bdd.js';
+import { collect, collectRecord } from './helpers.js';
+import type { OpenApiCollectorData } from './types.js';
+
+describe('collect', () => {
+  const data = {} as OpenApiCollectorData;
+  let testFunc: (data: OpenApiCollectorData, obj: object) => void;
+
+  beforeEach(() => {
+    testFunc = fn(() => {}) as any;
+  });
+
+  test('collect should handle null and undefined input', () => {
+    collect(data, null, testFunc);
+    collect(data, undefined, testFunc);
+    expect(testFunc).toHaveBeenCalledTimes(0);
+  });
+
+  test('collect should handle single non-array input', () => {
+    const obj = { 'x-id': 'test' };
+    collect(data, obj, testFunc);
+    expect(testFunc).toHaveBeenCalledTimes(1);
+    expect(testFunc).toHaveBeenCalledWith(data, obj);
+  });
+
+  test('collect should handle array input', () => {
+    const obj = [{ 'x-id': 'foo' }, { 'x-id': 'bar' }, { 'x-id': 'baz' }];
+    collect(data, obj, testFunc);
+    expect(testFunc).toHaveBeenCalledTimes(3);
+    expect(testFunc).toHaveBeenCalledWith(data, obj[0]);
+    expect(testFunc).toHaveBeenCalledWith(data, obj[1]);
+    expect(testFunc).toHaveBeenCalledWith(data, obj[2]);
+  });
+
+  test('collect should handle array input with null or undefined values', () => {
+    const obj = [{ 'x-id': 'foo' }, null, { 'x-id': 'bar' }, undefined, { 'x-id': 'baz' }];
+    collect(data, obj, testFunc);
+    expect(testFunc).toHaveBeenCalledTimes(3);
+    expect(testFunc).toHaveBeenCalledWith(data, obj[0]);
+    expect(testFunc).toHaveBeenCalledWith(data, obj[2]);
+    expect(testFunc).toHaveBeenCalledWith(data, obj[4]);
+  });
+
+  test('collect should not call func for null or undefined array elements', () => {
+    const obj = [null, undefined];
+    collect(data, obj, testFunc);
+    expect(testFunc).toHaveBeenCalledTimes(0);
+  });
+});
+
+describe('collectRecord', () => {
+  const data = {} as OpenApiCollectorData;
+  let testFunc: (data: OpenApiCollectorData, obj: object) => void;
+
+  beforeEach(() => {
+    testFunc = fn(() => {}) as any;
+  });
+
+  it('should not call the provided function if the input object is undefined', () => {
+    collectRecord(data, undefined, testFunc);
+    expect(testFunc).not.toHaveBeenCalled();
+  });
+
+  it('should call the provided function for each non-null and non-undefined value in the input object', () => {
+    const obj = {
+      a: { 'x-id': 1 },
+      b: null,
+      c: undefined,
+      d: { 'x-id': 2 },
+    };
+    collectRecord(data, obj, testFunc);
+    expect(testFunc).toHaveBeenCalledTimes(2);
+    expect(testFunc).toHaveBeenCalledWith(data, obj.a, 'a');
+    expect(testFunc).toHaveBeenCalledWith(data, obj.d, 'd');
+  });
+
+  it('should not call the provided function for keys starting with "$" or "x-"', () => {
+    const obj = {
+      a: { 'x-id': 1 },
+      $b: { 'x-id': 2 },
+      'x-c': { 'x-id': 3 },
+    };
+    collectRecord(data, obj, testFunc);
+    expect(testFunc).toHaveBeenCalledTimes(1);
+    expect(testFunc).toHaveBeenCalledWith(data, obj.a, 'a');
+  });
+});

package/src/src/collect/helpers.ts

@@ -0,0 +1,36 @@
+import { isOpenApiObjectProperty } from '../internal-utils.js';
+import type { Nullable } from '../utils/type.utils.js';
+import type { OpenApiCollectorData } from './types.js';
+
+export function collect<T extends Record<`x-${string}`, unknown>>(
+  data: OpenApiCollectorData,
+  obj: Nullable<T | Nullable<T>[]>,
+  func: (data: OpenApiCollectorData, obj: NonNullable<T>) => void,
+) {
+  if (!obj) return;
+  if (Array.isArray(obj)) {
+    for (const o of obj) {
+      if (!o) continue;
+      if (o['x-ignore']) continue;
+      func(data, o);
+    }
+  } else {
+    if (obj['x-ignore']) return;
+    func(data, obj);
+  }
+}
+
+export function collectRecord<T extends Record<`x-${string}`, unknown>>(
+  data: OpenApiCollectorData,
+  obj: Nullable<Record<string, Nullable<T>>>,
+  func: (data: OpenApiCollectorData, obj: NonNullable<T>, key: string) => void,
+) {
+  if (!obj) return;
+  for (const key in obj) {
+    if (!isOpenApiObjectProperty(key)) continue;
+    const value = obj[key];
+    if (!value) continue;
+    if (value['x-ignore']) continue;
+    func(data, value, key);
+  }
+}

package/src/src/collect/types.ts

@@ -0,0 +1,21 @@
+import type {
+  OpenApiDocument,
+  OpenApiHttpMethod,
+  OpenApiOperation,
+  OpenApiPathItem,
+  OpenApiSchema,
+} from '../parse/openapi-types.js';
+import type { Deref } from '../parse/types.js';
+
+export type OpenApiCollectorEndpointInfo = {
+  path: string;
+  method: OpenApiHttpMethod;
+  pathItem: Deref<OpenApiPathItem>;
+  operation: Deref<OpenApiOperation>;
+};
+
+export type OpenApiCollectorData = {
+  documents: Deref<OpenApiDocument>[];
+  schemas: Map<string, Deref<OpenApiSchema>>;
+  endpoints: Map<string, OpenApiCollectorEndpointInfo>;
+};

package/src/src/internal-utils.ts

@@ -0,0 +1,5 @@
+export function isOpenApiObjectProperty<T extends string>(
+  propertyName: T,
+): propertyName is Exclude<T, `$${string}` | `x-${string}`> {
+  return !propertyName.startsWith('$') && !propertyName.startsWith('x-');
+}

package/src/src/parse/deref-proxy.ts

@@ -0,0 +1,64 @@
+import { isNullish } from '../utils/common.utils.js';
+import type { OpenApiObject } from './openapi-types.js';
+import type { Deref, DerefSource } from './types.js';
+
+export function createDerefProxy<T extends OpenApiObject<string>>(
+  obj: T,
+  source: DerefSource<T>,
+  ref?: Deref<T>,
+): Deref<T> {
+  return new Proxy(obj, new DerefProxyHandler(source, ref)) as Deref<T>;
+}
+
+const propertiesNotDerivedFromRef: PropertyKey[] = ['title'];
+
+class DerefProxyHandler<T extends OpenApiObject<string>> implements ProxyHandler<T> {
+  private readonly _overwrittenValues: Record<PropertyKey, unknown> = {};
+
+  constructor(
+    private readonly _source: DerefSource<T>,
+    private _ref?: Deref<T>,
+  ) {}
+
+  public get(target: T, prop: PropertyKey): unknown {
+    if (prop === '$ref') {
+      return this._ref;
+    } else if (prop === '$src') {
+      return this._source;
+    }
+
+    if (this._overwrittenValues[prop] !== undefined) {
+      return this._overwrittenValues[prop];
+    }
+    if ((target as Record<PropertyKey, unknown>)[prop] !== undefined) {
+      return (target as Record<PropertyKey, unknown>)[prop];
+    }
+
+    return propertiesNotDerivedFromRef.includes(prop)
+      ? undefined
+      : (this._ref as Record<PropertyKey, unknown> | undefined)?.[prop];
+  }
+
+  public set(_target: T, prop: PropertyKey, value: unknown): boolean {
+    if (prop === '$ref' && (typeof value === 'object' || typeof value === 'undefined')) {
+      this._ref = !value ? undefined : (value as Deref<T>);
+      return true;
+    }
+    if (prop === '$src') {
+      return false;
+    }
+
+    this._overwrittenValues[prop] = value;
+    return true;
+  }
+
+  public has(target: T, prop: PropertyKey): boolean {
+    return prop in target || (!isNullish(this._ref) && prop in this._ref);
+  }
+
+  public ownKeys(target: T): ArrayLike<string | symbol> {
+    return Array.from(
+      new Set([...Object.keys(target), ...(!isNullish(this._ref) ? Object.keys(this._ref) : []), '$ref', '$src']),
+    );
+  }
+}