@e22m4u/js-openapi 0.0.5

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

@@ -0,0 +1,11 @@
+import {OAReferenceObject} from '../oa-specification.js';
+
+export declare const oaSchemaRef: (name: string) => OAReferenceObject;
+export declare const oaResponseRef: (name: string) => OAReferenceObject;
+export declare const oaParameterRef: (name: string) => OAReferenceObject;
+export declare const oaExampleRef: (name: string) => OAReferenceObject;
+export declare const oaRequestBodyRef: (name: string) => OAReferenceObject;
+export declare const oaSecuritySchemeRef: (name: string) => OAReferenceObject;
+export declare const oaLinkRef: (name: string) => OAReferenceObject;
+export declare const oaCallbackRef: (name: string) => OAReferenceObject;
+export declare const oaPathItemRef: (name: string) => OAReferenceObject;

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

@@ -0,0 +1,31 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {escapeJsonPointer} from '../json-pointer/index.js';
+
+/**
+ * Create the Reference Object.
+ *
+ * @param {string} name
+ * @param {string} segment
+ * @returns {object}
+ */
+function oaRef(name, segment) {
+  if (!name || typeof name !== 'string') {
+    throw new InvalidArgumentError(
+      'Parameter "name" must be a non-empty String, but %v was given.',
+      name,
+    );
+  }
+  const escapedName = escapeJsonPointer(name);
+  return {$ref: `#/components/${segment}/${escapedName}`};
+}
+
+/* aliases */
+export const oaSchemaRef = name => oaRef(name, 'schemas');
+export const oaResponseRef = name => oaRef(name, 'responses');
+export const oaParameterRef = name => oaRef(name, 'parameters');
+export const oaExampleRef = name => oaRef(name, 'examples');
+export const oaRequestBodyRef = name => oaRef(name, 'requestBodies');
+export const oaSecuritySchemeRef = name => oaRef(name, 'securitySchemes');
+export const oaLinkRef = name => oaRef(name, 'links');
+export const oaCallbackRef = name => oaRef(name, 'callbacks');
+export const oaPathItemRef = name => oaRef(name, 'pathItems');

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

@@ -0,0 +1,56 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+
+import {
+  oaLinkRef,
+  oaSchemaRef,
+  oaExampleRef,
+  oaResponseRef,
+  oaPathItemRef,
+  oaCallbackRef,
+  oaParameterRef,
+  oaRequestBodyRef,
+  oaSecuritySchemeRef,
+} from './oa-ref.js';
+
+const ALIASES_MAP = [
+  [oaSchemaRef, 'schemas'],
+  [oaResponseRef, 'responses'],
+  [oaParameterRef, 'parameters'],
+  [oaExampleRef, 'examples'],
+  [oaRequestBodyRef, 'requestBodies'],
+  [oaSecuritySchemeRef, 'securitySchemes'],
+  [oaLinkRef, 'links'],
+  [oaCallbackRef, 'callbacks'],
+  [oaPathItemRef, 'pathItems'],
+];
+
+describe('oaRef aliases', function () {
+  // eslint-disable-next-line mocha/no-setup-in-describe
+  ALIASES_MAP.forEach(([fn, segment]) => {
+    describe(fn.name, function () {
+      it('should require the "name" parameter to be a none-empty String', function () {
+        const throwable = v => () => fn(v);
+        const error = s =>
+          format(
+            'Parameter "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('name')();
+      });
+
+      it('should return the correct reference', function () {
+        expect(fn('name')).to.be.eql({$ref: `#/components/${segment}/name`});
+      });
+    });
+  });
+});

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

@@ -0,0 +1,18 @@
+import {OAReferenceObject} from '../oa-specification.js';
+
+/**
+ * Разрешает объект ссылки (Reference Object) и возвращает целевое значение.
+ * Функция реализует навигацию по JSON Pointer (RFC 6901) внутри корневого
+ * документа `options.rootDocument`. Утилита находит и возвращает узел, на который
+ * указывает `$ref`.
+ *
+ * - Поддерживает только локальные ссылки, начинающиеся с `#`.
+ * - Нет поддержки $dynamicRef, $anchor и $id.
+ *
+ * @param referenceObj
+ * @param options
+ */
+export function resolveOAReferenceObject<T = any>(
+  referenceObj: OAReferenceObject,
+  options?: {rootDocument?: object | unknown[]},
+): T;

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

@@ -0,0 +1,113 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {resolveJsonPointer} from '../json-pointer/index.js';
+
+/**
+ * Разрешает объект ссылки (Reference Object) и возвращает целевое значение.
+ * Функция реализует навигацию по JSON Pointer (RFC 6901) внутри корневого
+ * документа `options.rootDocument`. Утилита находит и возвращает узел, на который
+ * указывает `$ref`.
+ *
+ * - Поддерживает только локальные ссылки, начинающиеся с `#`.
+ * - Нет поддержки $dynamicRef, $anchor и $id.
+ *
+ * @param {object} referenceObj
+ * @param {object} [options]
+ * @returns {*}
+ */
+export function resolveOAReferenceObject(referenceObj, options = {}) {
+  if (
+    !referenceObj ||
+    typeof referenceObj !== 'object' ||
+    Array.isArray(referenceObj)
+  ) {
+    throw new InvalidArgumentError(
+      'Parameter "referenceObj" must be an Object, but %v was given.',
+      referenceObj,
+    );
+  }
+  // options
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new InvalidArgumentError(
+      'Parameter "options" must be an Object, but %v was given.',
+      options,
+    );
+  }
+  // options.rootDocument
+  if (options.rootDocument !== undefined) {
+    if (!options.rootDocument || typeof options.rootDocument !== 'object') {
+      throw new InvalidArgumentError(
+        'Option "rootDocument" must be an Object or an Array, but %v was given.',
+        options.rootDocument,
+      );
+    }
+  }
+  // $ref
+  if (referenceObj.$ref !== undefined) {
+    if (!referenceObj.$ref || typeof referenceObj.$ref !== 'string') {
+      throw new InvalidArgumentError(
+        'Schema keyword "$ref" must be a non-empty String, ' +
+          'but %v was given.',
+        referenceObj.$ref,
+      );
+    }
+    const refUri = referenceObj.$ref;
+    // если ссылка начинается с корня документа,
+    // то выполняется поиск указанного узла
+    if (refUri.startsWith('#')) {
+      if (!options.rootDocument) {
+        throw new InvalidArgumentError(
+          'Option "rootDocument" is required to resolve the same-document ' +
+            'reference (URI starts with "#").',
+        );
+      }
+      // если URI ссылается на корень документа (символ "#"),
+      // то возвращается корневой узел без поиска сегмента
+      if (refUri === '#') {
+        return options.rootDocument;
+      }
+      // если URI является JSON Pointer (прим. "#/path/to/element")
+      // то выполняется поиск узла согласно сегментам указателя
+      else if (refUri.startsWith('#/')) {
+        return resolveJsonPointer(options.rootDocument, refUri.substring(1));
+      }
+      // так как якорь (прим. "#SomeAnchor") требует обхода всего
+      // документа, в целях улучшения производительности данный
+      // функционал не будет реализован в утилитарной функции
+      throw new InvalidArgumentError(
+        'Anchor reference is not supported, but %v was given.',
+        refUri,
+      );
+    }
+    // удаленный ресурс (прим. "http://example.com/schema")
+    if (refUri.startsWith('http://') || refUri.startsWith('https://')) {
+      // так как разрешение внешних ссылок требует накладных расходов
+      // на производительность и кэширование, данный функционал
+      // не будет реализован в утилитарной функции
+      throw new InvalidArgumentError(
+        'External resource is not supported, but %v was given.',
+        refUri,
+      );
+    }
+    // так как для создания карты идентификаторов требуется обход
+    // всего документа, в целях повышения производительности данный
+    // функционал не будет реализован в утилитарной функции
+    throw new InvalidArgumentError(
+      'Relative reference is not supported, but %v was given.',
+      refUri,
+    );
+  }
+  // $dynamicRef
+  if (referenceObj.$dynamicRef) {
+    // поддержка $dynamicRef требует реализации динамической области
+    // видимости с отслеживанием стека вызовов при обходе схемы,
+    // но данная утилитарная функция выполняется без контекста
+    throw new InvalidArgumentError(
+      'Schema keyword "$dynamicRef" is not supported.',
+    );
+  }
+  // если объект ссылки не имеет свойств
+  // указателей, то выбрасывается ошибка
+  throw new InvalidArgumentError(
+    'Reference object does not have reference properties.',
+  );
+}

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

@@ -0,0 +1,233 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {resolveOAReferenceObject} from './resolve-oa-reference-object.js';
+
+describe('resolveOAReferenceObject', function () {
+  it('should require the parameter "referenceObj" to be an Object', function () {
+    const throwable = v => () =>
+      resolveOAReferenceObject(v, {rootDocument: {}});
+    const error = s =>
+      format(
+        'Parameter "referenceObj" 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({$ref: '#'})();
+  });
+
+  it('should require the parameter "options" to be an Object', function () {
+    const throwable = v => () => resolveOAReferenceObject({$ref: '#'}, v);
+    const error = s =>
+      format('Parameter "options" 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({rootDocument: {}})();
+  });
+
+  it('should require the option "rootDocument" to be an Object or an Array', function () {
+    const throwable = v => () =>
+      resolveOAReferenceObject({$ref: '#'}, {rootDocument: v});
+    const error = s =>
+      format(
+        'Option "rootDocument" must be an Object or 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(null)).to.throw(error('null'));
+    throwable([])();
+    throwable({})();
+  });
+
+  it('should require at least one reference property', function () {
+    const throwable = () => resolveOAReferenceObject({});
+    expect(throwable).to.throw(
+      'Reference object does not have reference properties.',
+    );
+  });
+
+  describe('$ref', function () {
+    it('should require the property "$ref" to be a non-empty String', function () {
+      const throwable = v => () =>
+        resolveOAReferenceObject({$ref: v}, {rootDocument: {}});
+      const error = s =>
+        format(
+          'Schema keyword "$ref" 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('#')();
+    });
+
+    describe('a document reference (URI starts with "#")', function () {
+      it('should require the option "rootDocument" when resolving the same-document', function () {
+        const throwable = v => () => resolveOAReferenceObject({$ref: v});
+        ['#', '#/', '#/path'].forEach(uri => {
+          expect(throwable(uri)).to.throw(
+            'Option "rootDocument" is required to resolve the same-document ' +
+              'reference (URI starts with "#").',
+          );
+        });
+      });
+
+      it('should return the root document when resolving the root reference', function () {
+        const rootDocument = {};
+        const res = resolveOAReferenceObject({$ref: '#'}, {rootDocument});
+        expect(res).to.be.eq(rootDocument);
+      });
+
+      it('should return a node with an empty string key', function () {
+        const node = {foo: 'bar'};
+        const res1 = resolveOAReferenceObject(
+          {$ref: '#/'},
+          {rootDocument: {'': node}},
+        );
+        expect(res1).to.be.eq(node);
+        const res2 = resolveOAReferenceObject(
+          {$ref: '#/path/'},
+          {rootDocument: {path: {'': node}}},
+        );
+        expect(res2).to.be.eq(node);
+      });
+
+      it('should unescape segments of the json pointer', function () {
+        const node = {foo: 'bar'};
+        const res = resolveOAReferenceObject(
+          {$ref: '#/~1path'},
+          {rootDocument: {'/path': node}},
+        );
+        expect(res).to.be.eq(node);
+      });
+
+      it('should resolve a document node by the json pointer with multiple segments', function () {
+        const node = {foo: 'bar'};
+        const res = resolveOAReferenceObject(
+          {$ref: '#/a/b/c'},
+          {rootDocument: {a: {b: {c: node}}}},
+        );
+        expect(res).to.be.eq(node);
+      });
+
+      it('should resolve an array element when the root document is an array', function () {
+        const res = resolveOAReferenceObject(
+          {$ref: '#/1'},
+          {rootDocument: ['foo', 'bar', 'baz']},
+        );
+        expect(res).to.be.eq('bar');
+      });
+
+      it('should be able to walk through an array element', function () {
+        const res = resolveOAReferenceObject(
+          {$ref: '#/1/prop'},
+          {rootDocument: [{prop: 'foo'}, {prop: 'bar'}, {prop: 'baz'}]},
+        );
+        expect(res).to.be.eq('bar');
+      });
+
+      it('should ignore an array index with zero prefix', function () {
+        const throwable = () =>
+          resolveOAReferenceObject(
+            {$ref: '#/01'},
+            {rootDocument: ['foo', 'bar', 'baz']},
+          );
+        expect(throwable).to.throw(
+          'Unable to resolve "/01" in the given document.',
+        );
+      });
+
+      it('should throw an error if a value of the target property is undefined', function () {
+        const node = {foo: undefined};
+        const throwable = () =>
+          resolveOAReferenceObject({$ref: '#/foo'}, {rootDocument: node});
+        expect(throwable).to.throw(
+          'Unable to resolve "/foo" in the given document.',
+        );
+      });
+
+      it('should not throw an error when a value of the target property is defined', function () {
+        const values = ['str', '', 10, 0, true, false, {}, [], null];
+        values.forEach(value => {
+          const rootDocument = {foo: value};
+          const res = resolveOAReferenceObject({$ref: '#/foo'}, {rootDocument});
+          expect(res).to.be.eq(value);
+        });
+      });
+    });
+
+    describe('an anchor reference (example "#SomeAnchor")', function () {
+      it('should throw an error when the URI has an anchor name', function () {
+        const throwable = () =>
+          resolveOAReferenceObject({$ref: '#SomeAnchor'}, {rootDocument: {}});
+        expect(throwable).to.throw(
+          'Anchor reference is not supported, but "#SomeAnchor" was given.',
+        );
+      });
+    });
+
+    describe('an external resource (example "http://example.com")', function () {
+      it('should throw an error when the URI starts with http(s) protocol', function () {
+        const throwable = v => () =>
+          resolveOAReferenceObject({$ref: v}, {rootDocument: {}});
+        ['http://example', 'https://example'].forEach(uri => {
+          expect(throwable(uri)).to.throw(
+            format(
+              'External resource is not supported, but %v was given.',
+              uri,
+            ),
+          );
+        });
+      });
+    });
+
+    describe('a relative reference (example "/path")', function () {
+      it('should throw an error when the URI has a relative reference', function () {
+        const throwable = v => () =>
+          resolveOAReferenceObject({$ref: v}, {rootDocument: {}});
+        ['/path', 'path', './path', '../path'].forEach(uri => {
+          expect(throwable(uri)).to.throw(
+            format(
+              'Relative reference is not supported, but %v was given.',
+              uri,
+            ),
+          );
+        });
+      });
+    });
+  });
+
+  describe('$dynamicRef', function () {
+    it('should throw an error when a dynamic reference is provided', function () {
+      const throwable = () =>
+        resolveOAReferenceObject({$dynamicRef: '#meta'}, {rootDocument: {}});
+      expect(throwable).to.throw(
+        'Schema keyword "$dynamicRef" is not supported.',
+      );
+    });
+  });
+});