@e22m4u/js-openapi 0.0.5

package/eslint.config.js

@@ -0,0 +1,41 @@
+import globals from 'globals';
+import eslintJs from '@eslint/js';
+import eslintJsdocPlugin from 'eslint-plugin-jsdoc';
+import eslintMochaPlugin from 'eslint-plugin-mocha';
+import eslintImportPlugin from 'eslint-plugin-import';
+import eslintPrettierConfig from 'eslint-config-prettier';
+import eslintChaiExpectPlugin from 'eslint-plugin-chai-expect';
+
+export default [{
+  languageOptions: {
+    globals: {
+      ...globals.node,
+      ...globals.es2021,
+      ...globals.mocha,
+    },
+  },
+  plugins: {
+    'jsdoc': eslintJsdocPlugin,
+    'mocha': eslintMochaPlugin,
+    'import': eslintImportPlugin,
+    'chai-expect': eslintChaiExpectPlugin,
+  },
+  rules: {
+    ...eslintJs.configs.recommended.rules,
+    ...eslintPrettierConfig.rules,
+    ...eslintImportPlugin.flatConfigs.recommended.rules,
+    ...eslintMochaPlugin.configs.recommended.rules,
+    ...eslintChaiExpectPlugin.configs['recommended-flat'].rules,
+    ...eslintJsdocPlugin.configs['flat/recommended-error'].rules,
+    'curly': 'error',
+    'no-duplicate-imports': 'error',
+    'import/export': 0,
+    'jsdoc/reject-any-type': 0,
+    'jsdoc/reject-function-type': 0,
+    'jsdoc/require-param-description': 0,
+    'jsdoc/require-returns-description': 0,
+    'jsdoc/require-property-description': 0,
+    'jsdoc/tag-lines': ['error', 'any', {startLines: 1}],
+  },
+  files: ['src/**/*.js'],
+}];

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@e22m4u/js-openapi",
+  "version": "0.0.5",
+  "description": "JavaScript модуль для создания OpenAPI Документа",
+  "author": "Mikhail Evstropov <e22m4u@yandex.ru>",
+  "license": "MIT",
+  "keywords": [
+    "schema",
+    "openapi",
+    "generator"
+  ],
+  "homepage": "https://gitrepos.ru/e22m4u/js-openapi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitrepos.ru/e22m4u/js-openapi.git"
+  },
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "module": "./src/index.js",
+  "main": "./dist/cjs/index.cjs",
+  "exports": {
+    "types": "./src/index.d.ts",
+    "import": "./src/index.js",
+    "require": "./dist/cjs/index.cjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "lint": "tsc && eslint ./src",
+    "lint:fix": "tsc && eslint ./src --fix",
+    "format": "prettier --write \"./src/**/*.{js,ts}\"",
+    "test": "npm run lint && c8 --reporter=text-summary mocha --bail",
+    "test:coverage": "npm run lint && c8 --reporter=text mocha --bail",
+    "build:cjs": "rimraf ./dist/cjs && node build-cjs.js",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@e22m4u/js-format": "~0.3.2",
+    "@e22m4u/js-service": "~0.5.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "~20.3.1",
+    "@commitlint/config-conventional": "~20.3.1",
+    "@eslint/js": "~9.39.2",
+    "@types/chai": "~5.2.3",
+    "@types/mocha": "~10.0.10",
+    "c8": "~10.1.3",
+    "chai": "~6.2.2",
+    "esbuild": "~0.27.2",
+    "eslint": "~9.39.2",
+    "eslint-config-prettier": "~10.1.8",
+    "eslint-plugin-chai-expect": "~3.1.0",
+    "eslint-plugin-import": "~2.32.0",
+    "eslint-plugin-jsdoc": "~62.0.0",
+    "eslint-plugin-mocha": "~11.2.0",
+    "globals": "~17.0.0",
+    "husky": "~9.1.7",
+    "mocha": "~11.7.5",
+    "prettier": "~3.8.0",
+    "rimraf": "~6.1.2",
+    "typescript": "~5.9.3"
+  }
+}

package/src/data-type/index.d.ts

@@ -0,0 +1 @@
+export * from './infer-openapi-data-type.js';

package/src/data-type/index.js

@@ -0,0 +1 @@
+export * from './infer-openapi-data-type.js';

package/src/data-type/infer-openapi-data-type.d.ts

@@ -0,0 +1,30 @@
+import {OADataType} from '../oa-specification.js';
+
+/**
+ * Infer OpenAPI data type.
+ *
+ * @param data
+ */
+export function inferOpenApiDataType(data: unknown): OADataType;
+
+/**
+ * Infer OpenAPI data type.
+ *
+ * @param data
+ * @param returnJsTypeOnFail
+ */
+export function inferOpenApiDataType(
+  data: unknown,
+  returnJsTypeOnFail: true,
+): OADataType | string;
+
+/**
+ * Infer OpenAPI data type.
+ *
+ * @param data
+ * @param returnJsTypeOnFail
+ */
+export function inferOpenApiDataType(
+  data: unknown,
+  returnJsTypeOnFail?: boolean,
+): OADataType | string;

package/src/data-type/infer-openapi-data-type.js

@@ -0,0 +1,38 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {OADataType} from '../oa-specification.js';
+
+/**
+ * Infer OpenAPI data type.
+ *
+ * @param {*} data
+ * @param {boolean} [returnJsTypeOnFail]
+ * @returns {OADataType}
+ */
+export function inferOpenApiDataType(data, returnJsTypeOnFail = false) {
+  if (data === null) {
+    return OADataType.NULL;
+  }
+  if (Array.isArray(data)) {
+    return OADataType.ARRAY;
+  }
+  const jsType = typeof data;
+  switch (jsType) {
+    case 'string':
+      return OADataType.STRING;
+    case 'boolean':
+      return OADataType.BOOLEAN;
+    case 'number':
+      return Number.isInteger(data) ? OADataType.INTEGER : OADataType.NUMBER;
+    case 'bigint':
+      return OADataType.INTEGER;
+    case 'object':
+      return OADataType.OBJECT;
+  }
+  if (returnJsTypeOnFail === true) {
+    return jsType;
+  }
+  throw new InvalidArgumentError(
+    'Unable to infer the data type from %v value.',
+    data,
+  );
+}

package/src/data-validation/data-format-validator-map.d.ts

@@ -0,0 +1,13 @@
+import {OADataFormatValidator} from './data-format-validators.js';
+
+/**
+ * Data format validator map.
+ */
+export type OADataFormatValidatorMap = {
+  [format: string]: OADataFormatValidator | undefined;
+};
+
+/**
+ * Built-in data format validator map.
+ */
+export declare const OA_BUILT_IN_DATA_FORMAT_VALIDATOR_MAP: OADataFormatValidatorMap;

package/src/data-validation/data-format-validator-map.js

@@ -0,0 +1,36 @@
+import {OADataFormat} from '../oa-specification.js';
+
+import {
+  validateUriFormat,
+  validateIpv4Format,
+  validateIpv6Format,
+  validateUuidFormat,
+  validateByteFormat,
+  validateDateFormat,
+  validateInt32Format,
+  validateFloatFormat,
+  validateInt64Format,
+  validateEmailFormat,
+  validateDoubleFormat,
+  validateDateTimeFormat,
+  validateHostnameFormat,
+} from './data-format-validators.js';
+
+/**
+ * Built-in data format validator map.
+ */
+export const OA_BUILT_IN_DATA_FORMAT_VALIDATOR_MAP = {
+  [OADataFormat.INT32]: validateInt32Format,
+  [OADataFormat.INT64]: validateInt64Format,
+  [OADataFormat.FLOAT]: validateFloatFormat,
+  [OADataFormat.DOUBLE]: validateDoubleFormat,
+  [OADataFormat.DATE]: validateDateFormat,
+  [OADataFormat.DATE_TIME]: validateDateTimeFormat,
+  [OADataFormat.BYTE]: validateByteFormat,
+  [OADataFormat.EMAIL]: validateEmailFormat,
+  [OADataFormat.UUID]: validateUuidFormat,
+  [OADataFormat.HOSTNAME]: validateHostnameFormat,
+  [OADataFormat.IPV4]: validateIpv4Format,
+  [OADataFormat.IPV6]: validateIpv6Format,
+  [OADataFormat.URI]: validateUriFormat,
+};

package/src/data-validation/data-format-validator-map.spec.js

@@ -0,0 +1,39 @@
+import {expect} from 'chai';
+import {OADataFormat} from '../oa-specification.js';
+import {OA_BUILT_IN_DATA_FORMAT_VALIDATOR_MAP} from './data-format-validator-map.js';
+
+import {
+  validateUriFormat,
+  validateIpv4Format,
+  validateIpv6Format,
+  validateUuidFormat,
+  validateByteFormat,
+  validateDateFormat,
+  validateInt32Format,
+  validateFloatFormat,
+  validateInt64Format,
+  validateEmailFormat,
+  validateDoubleFormat,
+  validateDateTimeFormat,
+  validateHostnameFormat,
+} from './data-format-validators.js';
+
+describe('OA_BUILT_IN_DATA_FORMAT_VALIDATOR_MAP', function () {
+  it('should map data formats to its corresponding validator function', function () {
+    expect(OA_BUILT_IN_DATA_FORMAT_VALIDATOR_MAP).to.be.eql({
+      [OADataFormat.INT32]: validateInt32Format,
+      [OADataFormat.INT64]: validateInt64Format,
+      [OADataFormat.FLOAT]: validateFloatFormat,
+      [OADataFormat.DOUBLE]: validateDoubleFormat,
+      [OADataFormat.DATE]: validateDateFormat,
+      [OADataFormat.DATE_TIME]: validateDateTimeFormat,
+      [OADataFormat.BYTE]: validateByteFormat,
+      [OADataFormat.EMAIL]: validateEmailFormat,
+      [OADataFormat.UUID]: validateUuidFormat,
+      [OADataFormat.HOSTNAME]: validateHostnameFormat,
+      [OADataFormat.IPV4]: validateIpv4Format,
+      [OADataFormat.IPV6]: validateIpv6Format,
+      [OADataFormat.URI]: validateUriFormat,
+    });
+  });
+});

package/src/data-validation/data-format-validators.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Data format validator.
+ */
+export type OADataFormatValidator = (value: unknown) => boolean;
+
+/**
+ * Validate int32 format.
+ * Signed 32-bit integer.
+ * Range: [-2,147,483,648 to 2,147,483,647]
+ */
+export declare const validateInt32Format: OADataFormatValidator;
+
+/**
+ * Validate int64 format.
+ * Signed 64-bit integer.
+ * Note: JS Numbers lose precision beyond 2^53.
+ * This checks if it's a safe integer in JS context.
+ */
+export declare const validateInt64Format: OADataFormatValidator;
+
+/**
+ * Validate float (32-bit) format.
+ * Standard IEEE 754 single-precision binary floating-point.
+ * Range approx: ±3.4e38.
+ */
+export declare const validateFloatFormat: OADataFormatValidator;
+
+/**
+ * Validate double (64-bit) format.
+ */
+export declare const validateDoubleFormat: OADataFormatValidator;
+
+/**
+ * Validate byte format.
+ * Base64 encoded characters.
+ */
+export declare const validateByteFormat: OADataFormatValidator;
+
+/**
+ * Validate date format.
+ * Full-date notation as defined by RFC 3339, section 5.6 (YYYY-MM-DD).
+ */
+export declare const validateDateFormat: OADataFormatValidator;
+
+/**
+ * Validate date-time format.
+ * The date-time notation as defined by RFC 3339, section 5.6.
+ */
+export declare const validateDateTimeFormat: OADataFormatValidator;
+
+/**
+ * Validate email format.
+ */
+export declare const validateEmailFormat: OADataFormatValidator;
+
+/**
+ * Validate uuid format.
+ */
+export declare const validateUuidFormat: OADataFormatValidator;
+
+/**
+ * Validate ipv4 format.
+ */
+export declare const validateIpv4Format: OADataFormatValidator;
+
+/**
+ * Validate ipv6 format.
+ */
+export declare const validateIpv6Format: OADataFormatValidator;
+
+/**
+ * Validate hostname format.
+ */
+export declare const validateHostnameFormat: OADataFormatValidator;
+
+/**
+ * Validate uri format.
+ */
+export declare const validateUriFormat: OADataFormatValidator;
+
+/**
+ * Validate password format.
+ */
+export declare const validatePasswordFormat: OADataFormatValidator;

package/src/data-validation/data-format-validators.js

@@ -0,0 +1,217 @@
+/////////////////////////////////////////////////
+////////////// Regular Expressions //////////////
+/////////////////////////////////////////////////
+const RX_UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const RX_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const RX_DATE_TIME =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|([+-]\d{2}:?\d{2}))$/i;
+const RX_IPV4 =
+  /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
+const RX_IPV6 =
+  /^((([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])))$/;
+const RX_HOSTNAME =
+  /^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$/;
+const RX_EMAIL =
+  /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+const RX_BASE64 =
+  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/**
+ * Validate int32 format.
+ * Signed 32-bit integer.
+ * Range: [-2,147,483,648 to 2,147,483,647]
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateInt32Format = v => {
+  if (typeof v !== 'number') {
+    return true;
+  }
+  return Number.isInteger(v) && v >= -2147483648 && v <= 2147483647;
+};
+
+/**
+ * Validate int64 format.
+ * Signed 64-bit integer.
+ * This checks if it's a safe integer in JS context.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateInt64Format = v => {
+  if (typeof v !== 'number') {
+    return true;
+  }
+  return Number.isSafeInteger(v);
+};
+
+/**
+ * Validate float (32-bit) format.
+ * Standard IEEE 754 single-precision binary floating-point.
+ * Range approx: ±3.4e38.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateFloatFormat = v => {
+  if (typeof v !== 'number') {
+    return true;
+  }
+  return (
+    !Number.isNaN(v) &&
+    Number.isFinite(v) &&
+    // Math.fround приводит число к 32-битному float,
+    // если результат бесконечен, значит число не влазит в float
+    Number.isFinite(Math.fround(v))
+  );
+};
+
+/**
+ * Validate double (64-bit) format.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateDoubleFormat = v => {
+  if (typeof v !== 'number') {
+    return true;
+  }
+  return !Number.isNaN(v) && Number.isFinite(v);
+};
+
+/**
+ * Validate byte format.
+ * Base64 encoded characters.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateByteFormat = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  return v.length % 4 === 0 && RX_BASE64.test(v);
+};
+
+/**
+ * Validate date format.
+ * Full-date notation as defined by RFC 3339, section 5.6 (YYYY-MM-DD).
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateDateFormat = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  if (!RX_DATE.test(v)) {
+    return false;
+  }
+  // проверка на переполнение дней
+  const [y, m, d] = v.split('-').map(Number);
+  const date = new Date(Date.UTC(y, m - 1, d));
+  return (
+    date.getUTCFullYear() === y &&
+    date.getUTCMonth() === m - 1 &&
+    date.getUTCDate() === d
+  );
+};
+
+/**
+ * Validate date-time format.
+ * The date-time notation as defined by RFC 3339, section 5.6.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateDateTimeFormat = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  return RX_DATE_TIME.test(v) && !isNaN(Date.parse(v));
+};
+
+/**
+ * Validate email format.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateEmailFormat = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  return RX_EMAIL.test(v);
+};
+
+/**
+ * Validate uuid format.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateUuidFormat = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  return RX_UUID.test(v);
+};
+
+/**
+ * Validate ipv4 format.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateIpv4Format = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  return RX_IPV4.test(v);
+};
+
+/**
+ * Validate ipv6 format.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateIpv6Format = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  return RX_IPV6.test(v);
+};
+
+/**
+ * Validate hostname format.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateHostnameFormat = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  return v.length <= 255 && RX_HOSTNAME.test(v);
+};
+
+/**
+ * Validate uri format.
+ *
+ * @param {*} v
+ * @returns {boolean}
+ */
+export const validateUriFormat = v => {
+  if (typeof v !== 'string') {
+    return true;
+  }
+  try {
+    new URL(v);
+    return true;
+  } catch {
+    return false;
+  }
+};

package/src/data-validation/index.d.ts

@@ -0,0 +1,3 @@
+export * from './data-format-validators.js';
+export * from './data-format-validator-map.js';
+export * from './validate-data-with-openapi-schema.js';

package/src/data-validation/index.js

@@ -0,0 +1,3 @@
+export * from './data-format-validators.js';
+export * from './data-format-validator-map.js';
+export * from './validate-data-with-openapi-schema.js';

package/src/data-validation/validate-data-with-openapi-schema.d.ts

@@ -0,0 +1,46 @@
+import {OADataFormatValidatorMap} from './data-format-validator-map.js';
+
+import {
+  OAAccessMode,
+  OASchemaObject,
+  OABooleanSchema,
+} from '../oa-specification.js';
+
+/**
+ * Data validation options.
+ */
+export type OADataValidationOptions = {
+  rootDocument?: object | unknown[];
+  required?: boolean;
+  coerceTypes?: boolean;
+  applyDefaults?: boolean;
+  stripUnknown?: boolean;
+  dataSourceUri?: string;
+  schemaSourceUri?: string;
+  silent?: boolean;
+  accessMode?: OAAccessMode;
+  formatValidators?: OADataFormatValidatorMap;
+  parseJson?: boolean;
+};
+
+/**
+ * Data validation result.
+ */
+export type OADataValidationResult<T> = {
+  isValid: boolean;
+  reason: string;
+  value?: T;
+};
+
+/**
+ * Validate data with OpenAPI Schema.
+ *
+ * @param data
+ * @param schema
+ * @param options
+ */
+export function validateDataWithOpenApiSchema<T = any>(
+  data: unknown,
+  schema: OABooleanSchema | OASchemaObject,
+  options?: OADataValidationOptions,
+): OADataValidationResult<T>;