@e22m4u/js-openapi 0.0.5

package/src/oa-document-object/validate-shallow-oa-document.spec.js

@@ -0,0 +1,362 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {OPENAPI_VERSION} from '../oa-specification.js';
+import {validateShallowOADocument} from './validate-shallow-oa-document.js';
+
+const MINIMAL_DOCUMENT = {
+  openapi: OPENAPI_VERSION,
+  info: {title: 'API Documentation', version: '0.0.1'},
+};
+
+describe('validateShallowOADocument', function () {
+  it('should require the first parameter to be an Object', function () {
+    const throwable = v => () => validateShallowOADocument(v);
+    const error = s =>
+      format('OpenAPI Document Object must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable(MINIMAL_DOCUMENT)();
+  });
+
+  it('should require the "openapi" property to be a non-empty String', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        openapi: v,
+      });
+    const error = s =>
+      format(
+        'Property "openapi" must be a non-empty String, but %s was given.',
+        s,
+      );
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable('3.1.0')();
+  });
+
+  it('should require the "info" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        openapi: OPENAPI_VERSION,
+        info: v,
+      });
+    const error = s =>
+      format('Property "info" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({title: 'API Documentation', version: '0.0.1'})();
+  });
+
+  it('should require the "info.title" property to be a non-empty String', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        openapi: OPENAPI_VERSION,
+        info: {
+          title: v,
+          version: '0.0.1',
+        },
+      });
+    const error = s =>
+      format(
+        'Property "info.title" must be a non-empty String, but %s was given.',
+        s,
+      );
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable('API Documentation')();
+  });
+
+  it('should require the "jsonSchemaDialect" property to be a non-empty String', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        jsonSchemaDialect: v,
+      });
+    const error = s =>
+      format(
+        'Property "jsonSchemaDialect" must be a non-empty String, but %s was given.',
+        s,
+      );
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable('https://json-schema.org/draft/2020-12/schema')();
+    throwable(undefined)();
+  });
+
+  it('should require the "servers" property to be an Array', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        servers: v,
+      });
+    const error = s =>
+      format('Property "servers" must be an Array, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable([{url: 'http://localhost'}])();
+    throwable([])();
+  });
+
+  it('should require elements of the "servers" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        servers: [v],
+      });
+    const error = s =>
+      format('Element "servers[0]" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({url: 'http://localhost'})();
+  });
+
+  it('should require the "servers[n].url" property to be a non-empty String', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        servers: [{url: v}],
+      });
+    const error = s =>
+      format(
+        'Property "servers[0].url" must be a non-empty String, ' +
+          'but %s was given.',
+        s,
+      );
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable('http://localhost')();
+  });
+
+  it('should require the "paths" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        paths: v,
+      });
+    const error = s =>
+      format('Property "paths" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({})();
+  });
+
+  it('should require the "webhooks" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        webhooks: v,
+      });
+    const error = s =>
+      format('Property "webhooks" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({})();
+  });
+
+  it('should require the "components" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        components: v,
+      });
+    const error = s =>
+      format('Property "components" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({})();
+  });
+
+  it('should require the "security" property to be an Array', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        security: v,
+      });
+    const error = s =>
+      format('Property "security" must be an Array, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable([{}])();
+    throwable([])();
+  });
+
+  it('should require elements of the "security" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        security: [v],
+      });
+    const error = s =>
+      format('Element "security[0]" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({apiKey: []})();
+    throwable({})();
+  });
+
+  it('should require the "tags" property to be an Array', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        tags: v,
+      });
+    const error = s =>
+      format('Property "tags" must be an Array, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable([{name: 'tag'}])();
+    throwable([])();
+  });
+
+  it('should require elements of the "tags" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        tags: [v],
+      });
+    const error = s =>
+      format('Element "tags[0]" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({name: 'tag'})();
+  });
+
+  it('should require the "tags[n].name" property to be a non-empty String', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        tags: [{name: v}],
+      });
+    const error = s =>
+      format(
+        'Property "tags[0].name" must be a non-empty String, ' +
+          'but %s was given.',
+        s,
+      );
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable({})).to.throw(error('Object'));
+    expect(throwable(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable('tag')();
+  });
+
+  it('should require the "externalDocs" property to be an Object', function () {
+    const throwable = v => () =>
+      validateShallowOADocument({
+        ...MINIMAL_DOCUMENT,
+        externalDocs: v,
+      });
+    const error = s =>
+      format('Property "externalDocs" must be an Object, but %s was given.', s);
+    expect(throwable('str')).to.throw(error('"str"'));
+    expect(throwable('')).to.throw(error('""'));
+    expect(throwable(10)).to.throw(error('10'));
+    expect(throwable(0)).to.throw(error('0'));
+    expect(throwable(true)).to.throw(error('true'));
+    expect(throwable(false)).to.throw(error('false'));
+    expect(throwable([])).to.throw(error('Array'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({url: 'https://example.com'})();
+    throwable(undefined)();
+  });
+});

package/src/oa-document-scope.d.ts

@@ -0,0 +1,52 @@
+import {
+  OADocumentBuilder,
+  OAOperationDefinition,
+} from './oa-document-builder.js';
+
+/**
+ * Document scope options.
+ */
+export type OADocumentScopeOptions = {
+  pathPrefix?: string;
+  tags?: string[];
+};
+
+/**
+ * Document scope.
+ */
+export declare class OADocumentScope {
+  /**
+   * @param builder
+   * @param options
+   */
+  constructor(builder: OADocumentBuilder, options?: OADocumentScopeOptions);
+
+  /**
+   * Get builder.
+   */
+  getBuilder(): OADocumentBuilder;
+
+  /**
+   * Get path prefix.
+   */
+  getPathPrefix(): string;
+
+  /**
+   * Get tags.
+   */
+  getTags(): string[];
+
+  /**
+   * Define operation.
+   *
+   * @param operationDef
+   */
+  defineOperation(operationDef: OAOperationDefinition): this;
+
+  /**
+   * Create scope.
+   *
+   * @param options
+   */
+  createScope(options?: OADocumentScopeOptions): OADocumentScope;
+}

package/src/oa-document-scope.js

@@ -0,0 +1,228 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {OAOperationMethod} from './oa-specification.js';
+import {joinPath, normalizePath} from './utils/index.js';
+import {OADocumentBuilder} from './oa-document-builder.js';
+
+/**
+ * Document scope.
+ */
+export class OADocumentScope {
+  /**
+   * Builder.
+   *
+   * @type {OADocumentBuilder}
+   */
+  _builder;
+
+  /**
+   * Path prefix.
+   *
+   * @type {string}
+   */
+  _pathPrefix;
+
+  /**
+   * Tags.
+   *
+   * @type {string[]}
+   */
+  _tags;
+
+  /**
+   * @param {object} builder
+   * @param {object} [options]
+   */
+  constructor(builder, options = {}) {
+    // builder
+    if (!(builder instanceof OADocumentBuilder)) {
+      throw new InvalidArgumentError(
+        'Parameter "builder" must be an instance of OADocumentBuilder, ' +
+          'but %v was given.',
+        builder,
+      );
+    }
+    // options
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new InvalidArgumentError(
+        'Parameter "options" must be an Object, but %v was given.',
+        options,
+      );
+    }
+    // options.pathPrefix
+    if (options.pathPrefix !== undefined) {
+      if (!options.pathPrefix || typeof options.pathPrefix !== 'string') {
+        throw new InvalidArgumentError(
+          'Property "pathPrefix" must be a non-empty String, ' +
+            'but %v was given.',
+          options.pathPrefix,
+        );
+      }
+    }
+    // options.tags
+    if (options.tags !== undefined) {
+      if (!Array.isArray(options.tags)) {
+        throw new InvalidArgumentError(
+          'Property "tags" must be an Array, but %v was given.',
+          options.tags,
+        );
+      }
+      options.tags.forEach((tag, index) => {
+        if (!tag || typeof tag !== 'string') {
+          throw new InvalidArgumentError(
+            'Element "tags[%d]" must be a non-empty String, but %v was given.',
+            index,
+            tag,
+          );
+        }
+      });
+    }
+    this._builder = builder;
+    this._pathPrefix = normalizePath(options.pathPrefix || '/');
+    this._tags = options.tags || [];
+  }
+
+  /**
+   * Get builder.
+   *
+   * @returns {OADocumentBuilder}
+   */
+  getBuilder() {
+    return this._builder;
+  }
+
+  /**
+   * Get path prefix.
+   *
+   * @returns {string}
+   */
+  getPathPrefix() {
+    return this._pathPrefix;
+  }
+
+  /**
+   * Get tags.
+   *
+   * @returns {string[]}
+   */
+  getTags() {
+    return [...this._tags];
+  }
+
+  /**
+   * Define operation.
+   *
+   * @param {object} operationDef
+   * @returns {this}
+   */
+  defineOperation(operationDef) {
+    if (
+      !operationDef ||
+      typeof operationDef !== 'object' ||
+      Array.isArray(operationDef)
+    ) {
+      throw new InvalidArgumentError(
+        'Operation Definition must be an Object, but %v was given.',
+        operationDef,
+      );
+    }
+    // path
+    if (!operationDef.path || typeof operationDef.path !== 'string') {
+      throw new InvalidArgumentError(
+        'Property "path" must be a non-empty String, but %v was given.',
+        operationDef.path,
+      );
+    }
+    // method
+    if (!operationDef.method || typeof operationDef.method !== 'string') {
+      throw new InvalidArgumentError(
+        'Property "method" must be a non-empty String, but %v was given.',
+        operationDef.method,
+      );
+    }
+    if (!Object.values(OAOperationMethod).includes(operationDef.method)) {
+      throw new InvalidArgumentError(
+        'Property "method" must be one of values: %l, but %v was given.',
+        Object.values(OAOperationMethod),
+      );
+    }
+    // operation
+    if (
+      !operationDef.operation ||
+      typeof operationDef.operation !== 'object' ||
+      Array.isArray(operationDef.operation)
+    ) {
+      throw new InvalidArgumentError(
+        'Property "operation" must be an Object, but %v was given.',
+        operationDef.operation,
+      );
+    }
+    // склеивание пути
+    const fullPath = joinPath(this._pathPrefix, operationDef.path);
+    // создание копии схемы операции
+    // чтобы избежать мутацию аргумента
+    const operation = structuredClone(operationDef.operation);
+    // объединение тегов текущей области
+    // с тегами текущей операции и удаление
+    // дубликатов
+    if (this._tags.length > 0) {
+      operation.tags = [...this._tags, ...(operation.tags || [])];
+      operation.tags = [...new Set(operation.tags)];
+    }
+    // регистрация операции в родительском
+    // экземпляре сборщика документа
+    this._builder.defineOperation({
+      ...operationDef,
+      path: fullPath,
+      operation,
+    });
+    return this;
+  }
+
+  /**
+   * Create scope.
+   *
+   * @param {object} [options]
+   * @returns {OADocumentScope}
+   */
+  createScope(options = {}) {
+    // options
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new InvalidArgumentError(
+        'Parameter "options" must be an Object, but %v was given.',
+        options,
+      );
+    }
+    // options.pathPrefix
+    if (options.pathPrefix !== undefined) {
+      if (!options.pathPrefix || typeof options.pathPrefix !== 'string') {
+        throw new InvalidArgumentError(
+          'Property "pathPrefix" must be a non-empty String, ' +
+            'but %v was given.',
+          options.pathPrefix,
+        );
+      }
+    }
+    // options.tags
+    if (options.tags !== undefined) {
+      if (!Array.isArray(options.tags)) {
+        throw new InvalidArgumentError(
+          'Property "tags" must be an Array, but %v was given.',
+          options.tags,
+        );
+      }
+      options.tags.forEach((tag, index) => {
+        if (!tag || typeof tag !== 'string') {
+          throw new InvalidArgumentError(
+            'Element "tags[%d]" must be a non-empty String, but %v was given.',
+            index,
+            tag,
+          );
+        }
+      });
+    }
+    return new OADocumentScope(this._builder, {
+      pathPrefix: joinPath(this._pathPrefix, options.pathPrefix),
+      tags: [...this._tags, ...(options.tags || [])],
+    });
+  }
+}

package/src/oa-reference-object/index.d.ts

@@ -0,0 +1,3 @@
+export * from './oa-ref.js';
+export * from './is-oa-reference-object.js';
+export * from './resolve-oa-reference-object.js';

package/src/oa-reference-object/index.js

@@ -0,0 +1,3 @@
+export * from './oa-ref.js';
+export * from './is-oa-reference-object.js';
+export * from './resolve-oa-reference-object.js';

package/src/oa-reference-object/is-oa-reference-object.d.ts

@@ -0,0 +1,9 @@
+import {OAReferenceObject} from '../oa-specification.js';
+
+/**
+ * Is OpenAPI Reference Object.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isOAReferenceObject(value: unknown): value is OAReferenceObject;

package/src/oa-reference-object/is-oa-reference-object.js

@@ -0,0 +1,14 @@
+/**
+ * Is OpenAPI Reference Object.
+ *
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function isOAReferenceObject(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    if (value.$ref !== undefined || value.$dynamicRef !== undefined) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/oa-reference-object/is-oa-reference-object.spec.js

@@ -0,0 +1,19 @@
+import {expect} from 'chai';
+import {isOAReferenceObject} from './is-oa-reference-object.js';
+
+describe('isOAReferenceObject', function () {
+  it('should return true when the given value is a reference object', function () {
+    expect(isOAReferenceObject('str')).to.be.false;
+    expect(isOAReferenceObject('')).to.be.false;
+    expect(isOAReferenceObject(10)).to.be.false;
+    expect(isOAReferenceObject(0)).to.be.false;
+    expect(isOAReferenceObject(true)).to.be.false;
+    expect(isOAReferenceObject(false)).to.be.false;
+    expect(isOAReferenceObject({})).to.be.false;
+    expect(isOAReferenceObject([])).to.be.false;
+    expect(isOAReferenceObject(undefined)).to.be.false;
+    expect(isOAReferenceObject(null)).to.be.false;
+    expect(isOAReferenceObject({$ref: '123'})).to.be.true;
+    expect(isOAReferenceObject({$dynamicRef: '123'})).to.be.true;
+  });
+});