@e22m4u/js-openapi 0.0.6 → 0.0.8

package/dist/cjs/index.cjs

@@ -73,6 +73,18 @@ var OADocumentObjectValidationError = class extends import_js_format.Errorf {
   static {
     __name(this, "OADocumentObjectValidationError");
   }
+  /**
+   * Instance path.
+   *
+   * @type {string|undefined}
+   */
+  instancePath;
+  /**
+   * Reason.
+   *
+   * @type {string|undefined}
+   */
+  reason;
 };
 
 // src/oa-specification.js
@@ -148,6 +160,7 @@ var OAMediaType = {
   TEXT_HTML: "text/html",
   APPLICATION_XML: "application/xml",
   APPLICATION_JSON: "application/json",
+  APPLICATION_OCTET_STREAM: "application/octet-stream",
   MULTIPART_FORM_DATA: "multipart/form-data"
 };
 var OASecuritySchemeType = {
@@ -1806,7 +1819,7 @@ var OA_DOCUMENT_OBJECT_JSON_SCHEMA_URI = "https://spec.openapis.org/oas/3.1/sche
 ajv.getSchema(OA_DOCUMENT_OBJECT_JSON_SCHEMA_URI);
 
 // src/oa-document-object/validate-oa-document-object.js
-function validateOADocumentObject(data, options = {}) {
+function validateOADocumentObject(instance, options = {}) {
   if (!options || typeof options !== "object" || Array.isArray(options)) {
     throw new import_js_format5.InvalidArgumentError(
       'Parameter "options" must be an Object, but %v was given.',
@@ -1821,30 +1834,35 @@ function validateOADocumentObject(data, options = {}) {
       );
     }
   }
-  if (options.dataSourceUri !== void 0) {
-    if (typeof options.dataSourceUri !== "string") {
+  if (options.sourceUri !== void 0) {
+    if (typeof options.sourceUri !== "string") {
       throw new import_js_format5.InvalidArgumentError(
-        'Option "dataSourceUri" must be a String, but %v was given.',
-        options.dataSourceUri
+        'Option "sourceUri" must be a String, but %v was given.',
+        options.sourceUri
       );
     }
   }
   const validate = ajv.getSchema(
     `${OA_DOCUMENT_OBJECT_JSON_SCHEMA_URI}${options.schemaUri || ""}`
   );
-  const isValid = validate(data);
+  const isValid = validate(instance);
   if (!isValid) {
     const error = validate.errors[0];
     let instancePath = error.instancePath || "";
-    let dataSourceUri = options.dataSourceUri || "";
-    if (!options.schemaUri && !options.dataSourceUri) {
-      dataSourceUri = "#";
+    let sourceUri = options.sourceUri || "";
+    if (!options.schemaUri && !options.sourceUri) {
+      sourceUri = "#";
     }
-    throw new OADocumentObjectValidationError(
+    const sourceUriWithInstancePath = sourceUri && instancePath ? [sourceUri, instancePath].join("/").replace(/\/+/g, "/") : sourceUri + instancePath;
+    const errorReason = error.message.replace(/'/g, '"');
+    const validationError = new OADocumentObjectValidationError(
       "Value at %v %s.",
-      dataSourceUri && error.instancePath ? [dataSourceUri, error.instancePath].join("/").replace(/\/+/g, "/") : dataSourceUri + instancePath,
-      error.message.replace(/'/g, '"')
+      sourceUriWithInstancePath,
+      errorReason
     );
+    validationError.instancePath = error.instancePath;
+    validationError.reason = errorReason;
+    throw validationError;
   }
 }
 __name(validateOADocumentObject, "validateOADocumentObject");
@@ -1997,7 +2015,7 @@ var OADocumentBuilder = class extends import_js_service.Service {
     }
     validateOADocumentObject(component, {
       schemaUri: `#/$defs/${definitionName}`,
-      dataSourceUri: `#/components/${componentsKey}/${escapeJsonPointer(name)}`
+      sourceUri: `#/components/${componentsKey}/${escapeJsonPointer(name)}`
     });
     this._document.components = this._document.components || {};
     this._document.components[componentsKey] = this._document.components[componentsKey] || {};
@@ -2228,7 +2246,7 @@ var OADocumentBuilder = class extends import_js_service.Service {
       }
       validateOADocumentObject(operationDef.operation, {
         schemaUri: "#/$defs/operation",
-        dataSourceUri: `/paths/${escapeJsonPointer(operationDef.path)}/${escapeJsonPointer(operationDef.method)}`
+        sourceUri: `#/paths/${escapeJsonPointer(operationDef.path)}/${escapeJsonPointer(operationDef.method)}`
       });
     }
     const operation = operationDef.operation ? structuredClone(operationDef.operation) : {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e22m4u/js-openapi",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "JavaScript модуль для создания OpenAPI Документа",
   "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
   "license": "MIT",
@@ -36,14 +36,14 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@e22m4u/js-format": "~0.3.2",
+    "@e22m4u/js-format": "~0.4.0",
     "@e22m4u/js-service": "~0.5.1",
-    "ajv": "~8.17.1",
+    "ajv": "~8.18.0",
     "ajv-formats": "~3.0.1"
   },
   "devDependencies": {
-    "@commitlint/cli": "~20.4.1",
-    "@commitlint/config-conventional": "~20.4.1",
+    "@commitlint/cli": "~20.4.2",
+    "@commitlint/config-conventional": "~20.4.2",
     "@eslint/js": "~9.39.2",
     "@types/chai": "~5.2.3",
     "@types/mocha": "~10.0.10",
@@ -54,13 +54,13 @@
     "eslint-config-prettier": "~10.1.8",
     "eslint-plugin-chai-expect": "~3.1.0",
     "eslint-plugin-import": "~2.32.0",
-    "eslint-plugin-jsdoc": "~62.5.4",
+    "eslint-plugin-jsdoc": "~62.7.1",
     "eslint-plugin-mocha": "~11.2.0",
     "globals": "~17.3.0",
     "husky": "~9.1.7",
     "mocha": "~11.7.5",
     "prettier": "~3.8.1",
-    "rimraf": "~6.1.2",
+    "rimraf": "~6.1.3",
     "typescript": "~5.9.3"
   }
 }

package/src/errors/oa-document-object-validation-error.d.ts

@@ -3,4 +3,14 @@ import {Errorf} from '@e22m4u/js-format';
 /**
  * Document object validation error.
  */
-export declare class OADocumentObjectValidationError extends Errorf {}
+export declare class OADocumentObjectValidationError extends Errorf {
+  /**
+   * Instance path.
+   */
+  readonly instancePath?: string;
+
+  /**
+   * Reason.
+   */
+  readonly reason?: string;
+}

package/src/errors/oa-document-object-validation-error.js

@@ -3,4 +3,18 @@ import {Errorf} from '@e22m4u/js-format';
 /**
  * Document object validation error.
  */
-export class OADocumentObjectValidationError extends Errorf {}
+export class OADocumentObjectValidationError extends Errorf {
+  /**
+   * Instance path.
+   *
+   * @type {string|undefined}
+   */
+  instancePath;
+
+  /**
+   * Reason.
+   *
+   * @type {string|undefined}
+   */
+  reason;
+}

package/src/errors/oa-document-object-validation-error.spec.js

@@ -3,8 +3,15 @@ import {Errorf} from '@e22m4u/js-format';
 import {OADocumentObjectValidationError} from './oa-document-object-validation-error.js';
 
 describe('OADocumentObjectValidationError', function () {
-  it('should extend the Errorf class', function () {
-    const error = new OADocumentObjectValidationError();
-    expect(error).to.be.instanceof(Errorf);
+  describe('constructor', function () {
+    it('should extend Errorf class', function () {
+      const error = new OADocumentObjectValidationError();
+      expect(error).to.be.instanceof(Errorf);
+    });
+
+    it('should interpolate the given message with arguments', function () {
+      const error = new OADocumentObjectValidationError('%v and %v', 1, 2);
+      expect(error.message).to.be.eq('1 and 2');
+    });
   });
 });

package/src/oa-document-builder.js

@@ -198,7 +198,7 @@ export class OADocumentBuilder extends Service {
     // validation
     validateOADocumentObject(component, {
       schemaUri: `#/$defs/${definitionName}`,
-      dataSourceUri: `#/components/${componentsKey}/${escapeJsonPointer(name)}`,
+      sourceUri: `#/components/${componentsKey}/${escapeJsonPointer(name)}`,
     });
     this._document.components = this._document.components || {};
     this._document.components[componentsKey] =
@@ -467,7 +467,7 @@ export class OADocumentBuilder extends Service {
       // validation
       validateOADocumentObject(operationDef.operation, {
         schemaUri: '#/$defs/operation',
-        dataSourceUri: `/paths/${escapeJsonPointer(operationDef.path)}/${escapeJsonPointer(operationDef.method)}`,
+        sourceUri: `#/paths/${escapeJsonPointer(operationDef.path)}/${escapeJsonPointer(operationDef.method)}`,
       });
     }
     // создание поверхностной копии определения

package/src/oa-document-builder.spec.js

@@ -1282,7 +1282,10 @@ describe('OADocumentBuilder', function () {
           operation: {parameters: 123},
         });
       };
-      expect(throwable).to.throw(OADocumentObjectValidationError);
+      expect(throwable).to.throw(
+        OADocumentObjectValidationError,
+        'Value at "#/paths/~1/get/parameters" must be array.',
+      );
     });
 
     it('should define the operation object', function () {

package/src/oa-document-object/validate-oa-document-object.d.ts

@@ -3,16 +3,16 @@
  */
 export type OADocumentObjectValidationOptions = {
   schemaUri?: string;
-  dataSourceUri?: string;
+  sourceUri?: string;
 };
 
 /**
  * Validate OADocumentObject.
  *
- * @param data
+ * @param instance
  * @param options
  */
 export function validateOADocumentObject(
-  data: any,
+  instance: any,
   options?: OADocumentObjectValidationOptions,
 ): void;

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

@@ -5,10 +5,19 @@ import {OADocumentObjectValidationError} from '../errors/index.js';
 /**
  * Validate OADocumentObject.
  *
- * @param {*} data
- * @param {*} options
+ * @param {*}      instance  Проверяемый экземпляр.
+ * @param {object} [options] Параметры проверки.
+ * @param {string} [options.schemaUri]
+ *   URI участка JSON-схемы, согласно которому будет
+ *   выполняться проверка (прим. "#/$defs/operation").
+ *   Используется, если нужно проверить часть OpenAPI
+ *   документа, когда в первый аргумент данной функции
+ *   передается только проверяемый участок.
+ * @param {string} [options.sourceUri]
+ *   Строка добавляется префиксом к URI проблемного
+ *   значения в сообщении об ошибке (прим. "#/paths/~1/get").
  */
-export function validateOADocumentObject(data, options = {}) {
+export function validateOADocumentObject(instance, options = {}) {
   if (!options || typeof options !== 'object' || Array.isArray(options)) {
     throw new InvalidArgumentError(
       'Parameter "options" must be an Object, but %v was given.',
@@ -23,31 +32,49 @@ export function validateOADocumentObject(data, options = {}) {
       );
     }
   }
-  if (options.dataSourceUri !== undefined) {
-    if (typeof options.dataSourceUri !== 'string') {
+  if (options.sourceUri !== undefined) {
+    if (typeof options.sourceUri !== 'string') {
       throw new InvalidArgumentError(
-        'Option "dataSourceUri" must be a String, but %v was given.',
-        options.dataSourceUri,
+        'Option "sourceUri" must be a String, but %v was given.',
+        options.sourceUri,
       );
     }
   }
   const validate = ajv.getSchema(
     `${OA_DOCUMENT_OBJECT_JSON_SCHEMA_URI}${options.schemaUri || ''}`,
   );
-  const isValid = validate(data);
+  const isValid = validate(instance);
   if (!isValid) {
     const error = validate.errors[0];
     let instancePath = error.instancePath || '';
-    let dataSourceUri = options.dataSourceUri || '';
-    if (!options.schemaUri && !options.dataSourceUri) {
-      dataSourceUri = '#';
+    let sourceUri = options.sourceUri || '';
+    // если URI схемы и источника экземпляра не определен,
+    // значит ошибка вызвана при проверке целого OpenAPI
+    // документа, и в таком случае, сообщение об ошибке
+    // должно содержать путь экземпляра с префиксом "#",
+    // указывающем на корень документа, пример: "#/info"
+    if (!options.schemaUri && !options.sourceUri) {
+      sourceUri = '#';
     }
-    throw new OADocumentObjectValidationError(
+    // если передан URI источника экземпляра, то значение
+    // объединяется с путем экземпляра косой чертой,
+    // пример: "#/components/schemas/city" + "/type"
+    const sourceUriWithInstancePath =
+      sourceUri && instancePath
+        ? [sourceUri, instancePath].join('/').replace(/\/+/g, '/')
+        : sourceUri + instancePath;
+    const errorReason = error.message.replace(/'/g, '"');
+    // при создании ошибки выполняется интерполяция сообщения,
+    // пример: Value at "#" must have required property "info".
+    const validationError = new OADocumentObjectValidationError(
       'Value at %v %s.',
-      dataSourceUri && error.instancePath
-        ? [dataSourceUri, error.instancePath].join('/').replace(/\/+/g, '/')
-        : dataSourceUri + instancePath,
-      error.message.replace(/'/g, '"'),
+      sourceUriWithInstancePath,
+      errorReason,
     );
+    // в экземпляр ошибки устанавливаются
+    // дополнительные свойства из данных AJV
+    validationError.instancePath = error.instancePath;
+    validationError.reason = errorReason;
+    throw validationError;
   }
 }

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

@@ -1,6 +1,6 @@
 import {expect} from 'chai';
-import {validateOADocumentObject} from './validate-oa-document-object.js';
 import {format} from '@e22m4u/js-format';
+import {validateOADocumentObject} from './validate-oa-document-object.js';
 
 const VALID_DOC_SAMPLE = {
   openapi: '3.1.2',
@@ -44,11 +44,11 @@ describe('validateOADocumentObject', function () {
     throwable(undefined)();
   });
 
-  it('should require the option "dataSourceUri" to be a String', function () {
+  it('should require the option "sourceUri" to be a String', function () {
     const throwable = v => () =>
-      validateOADocumentObject(VALID_DOC_SAMPLE, {dataSourceUri: v});
+      validateOADocumentObject(VALID_DOC_SAMPLE, {sourceUri: v});
     const error = s =>
-      format('Option "dataSourceUri" must be a String, but %s was given.', s);
+      format('Option "sourceUri" must be a String, but %s was given.', s);
     expect(throwable(10)).to.throw(error('10'));
     expect(throwable(0)).to.throw(error('0'));
     expect(throwable(true)).to.throw(error('true'));
@@ -105,13 +105,13 @@ describe('validateOADocumentObject', function () {
     );
   });
 
-  it('should add the "dataSourceUri" option as prefix to the instance path', function () {
+  it('should add the option "sourceUri" as a path prefix to the error message', function () {
     const throwable = () =>
       validateOADocumentObject(
         {type: 123},
         {
           schemaUri: '#/$defs/schema',
-          dataSourceUri: '#/components/schemas/mySchema',
+          sourceUri: '#/components/schemas/mySchema',
         },
       );
     expect(throwable).to.throw(
@@ -119,4 +119,18 @@ describe('validateOADocumentObject', function () {
         'must be equal to one of the allowed values.',
     );
   });
+
+  it('should set the "instancePath" and "reason" properties to the validation error', function () {
+    let isCaught = false;
+    try {
+      validateOADocumentObject({type: 123}, {schemaUri: '#/$defs/schema'});
+    } catch (error) {
+      isCaught = true;
+      expect(error.instancePath).to.be.eql('/type');
+      expect(error.reason).to.be.eq(
+        'must be equal to one of the allowed values',
+      );
+    }
+    expect(isCaught).to.be.true;
+  });
 });

package/src/oa-specification.d.ts

@@ -421,6 +421,7 @@ export declare const OAMediaType: {
   TEXT_HTML: 'text/html';
   APPLICATION_XML: 'application/xml';
   APPLICATION_JSON: 'application/json';
+  APPLICATION_OCTET_STREAM: 'application/octet-stream';
   MULTIPART_FORM_DATA: 'multipart/form-data';
 };
 

package/src/oa-specification.js

@@ -106,6 +106,7 @@ export const OAMediaType = {
   TEXT_HTML: 'text/html',
   APPLICATION_XML: 'application/xml',
   APPLICATION_JSON: 'application/json',
+  APPLICATION_OCTET_STREAM: 'application/octet-stream',
   MULTIPART_FORM_DATA: 'multipart/form-data',
 };