@e22m4u/js-openapi 0.0.5

package/src/oa-specification.js

@@ -0,0 +1,153 @@
+// OpenApi version 3.1.0
+// https://spec.openapis.org/oas/v3.1.0
+
+/**
+ * OpenAPI version.
+ */
+export const OPENAPI_VERSION = '3.1.0';
+
+/**
+ * Operation Method.
+ * https://spec.openapis.org/oas/v3.1.0#path-item-object
+ */
+export const OAOperationMethod = {
+  GET: 'get',
+  PUT: 'put',
+  POST: 'post',
+  DELETE: 'delete',
+  OPTIONS: 'options',
+  HEAD: 'head',
+  PATCH: 'patch',
+  TRACE: 'trace',
+};
+
+/**
+ * Parameter Location.
+ * https://spec.openapis.org/oas/v3.1.0#parameter-locations
+ */
+export const OAParameterLocation = {
+  QUERY: 'query',
+  HEADER: 'header',
+  PATH: 'path',
+  COOKIE: 'cookie',
+};
+
+/**
+ * Parameter Style.
+ * https://spec.openapis.org/oas/v3.1.0#style-values
+ */
+export const OAParameterStyle = {
+  MATRIX: 'matrix',
+  LABEL: 'label',
+  FORM: 'form',
+  SIMPLE: 'simple',
+  SPACE_DELIMITED: 'spaceDelimited',
+  PIPE_DELIMITED: 'pipeDelimited',
+  DEEP_OBJECT: 'deepObject',
+};
+
+/**
+ * Data type.
+ * https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1
+ */
+export const OADataType = {
+  STRING: 'string',
+  NUMBER: 'number',
+  INTEGER: 'integer',
+  BOOLEAN: 'boolean',
+  OBJECT: 'object',
+  ARRAY: 'array',
+  NULL: 'null',
+};
+
+/**
+ * Data type list.
+ * https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-4.2.1
+ */
+export const OA_DATA_TYPE_LIST = Object.values(OADataType);
+
+/**
+ * Data format.
+ * https://spec.openapis.org/oas/v3.1.0#dataTypeFormat
+ */
+export const OADataFormat = {
+  // number
+  INT32: 'int32',
+  INT64: 'int64',
+  FLOAT: 'float',
+  DOUBLE: 'double',
+  // date and time
+  DATE: 'date',
+  DATE_TIME: 'date-time',
+  TIME: 'time',
+  DURATION: 'duration',
+  // binary
+  BYTE: 'byte',
+  BINARY: 'binary',
+  // identifiers and network
+  EMAIL: 'email',
+  IDN_EMAIL: 'idn-email',
+  UUID: 'uuid',
+  HOSTNAME: 'hostname',
+  IDN_HOSTNAME: 'idn-hostname',
+  IPV4: 'ipv4',
+  IPV6: 'ipv6',
+  URI: 'uri',
+  URI_REFERENCE: 'uri-reference',
+  IRI: 'iri',
+  IRI_REFERENCE: 'iri-reference',
+  // extra
+  PASSWORD: 'password',
+  REGEX: 'regex',
+  JSON_POINTER: 'json-pointer',
+  RELATIVE_JSON_POINTER: 'relative-json-pointer',
+};
+
+/**
+ * Media type.
+ * https://spec.openapis.org/oas/v3.1.0#media-types
+ */
+export const OAMediaType = {
+  TEXT_PLAIN: 'text/plain',
+  TEXT_HTML: 'text/html',
+  APPLICATION_XML: 'application/xml',
+  APPLICATION_JSON: 'application/json',
+  MULTIPART_FORM_DATA: 'multipart/form-data',
+};
+
+/**
+ * Security Scheme Type.
+ * https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+ */
+export const OASecuritySchemeType = {
+  API_KEY: 'apiKey',
+  HTTP: 'http',
+  MUTUAL_TLS: 'mutualTLS',
+  OAUTH_2: 'oauth2',
+  OPEN_ID_CONNECT: 'openIdConnect',
+};
+
+/**
+ * Api Key Location.
+ * https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+ */
+export const OAApiKeyLocation = {
+  QUERY: 'query',
+  HEADER: 'header',
+  COOKIE: 'cookie',
+};
+
+/**
+ * Access mode.
+ * https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-01#name-readonly-and-writeonly
+ */
+export const OAAccessMode = {
+  READ: 'read',
+  WRITE: 'write',
+};
+
+/**
+ * Access mode list.
+ * https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-01#name-readonly-and-writeonly
+ */
+export const ACCESS_MODE_LIST = Object.values(OAAccessMode);

package/src/types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Make specific properties optional.
+ */
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

package/src/utils/count-unicode.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Count unicode.
+ *
+ * Подсчет длины строки выполняется с учетом символов, выходящих
+ * за пределы BMP (Basic Multilingual Plane) например, эмодзи
+ * или некоторые иероглифы в JS имеют `.length === 2`,
+ * но должны считаться за один символ.
+ *
+ * @param data
+ */
+export function countUnicode(data: string): number;

package/src/utils/count-unicode.js

@@ -0,0 +1,15 @@
+/**
+ * Count unicode.
+ *
+ * Подсчет длины строки выполняется с учетом символов, выходящих
+ * за пределы BMP (Basic Multilingual Plane) например, эмодзи
+ * или некоторые иероглифы в JS имеют `.length === 2`,
+ * но должны считаться за один символ.
+ *
+ * @param {string} data
+ * @returns {number}
+ */
+export function countUnicode(data) {
+  const matchedChars = String(data).match(/[\s\S]/gu);
+  return Array.isArray(matchedChars) ? matchedChars.length : 0;
+}

package/src/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from './join-path.js';
+export * from './count-unicode.js';
+export * from './normalize-path.js';
+export * from './to-spaced-json.js';
+export * from './to-pascal-case.js';

package/src/utils/index.js

@@ -0,0 +1,5 @@
+export * from './join-path.js';
+export * from './count-unicode.js';
+export * from './normalize-path.js';
+export * from './to-spaced-json.js';
+export * from './to-pascal-case.js';

package/src/utils/join-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Joins URL paths.
+ *
+ * @param segments
+ */
+export declare function joinPath(...segments: (string | number)[]): string;

package/src/utils/join-path.js

@@ -0,0 +1,36 @@
+/**
+ * Joins URL paths.
+ *
+ * @param {...string} segments
+ * @returns {string}
+ */
+export function joinPath(...segments) {
+  // фильтрация пустых значений (null, undefined, "")
+  const parts = segments.filter(seg => seg != undefined && String(seg) !== '');
+  if (parts.length === 0) {
+    return '/';
+  }
+  // простое объединение через разделитель
+  // и замена множественных слешей на один
+  let joined = parts.join('/').replace(/\/+/g, '/');
+  // проверка на наличие протокола в начале строки
+  // RFC 3986: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
+  const protocolRegex = /^([a-z][a-z0-9+.-]*):\//i;
+  const protocolMatch = joined.match(protocolRegex);
+  if (protocolMatch) {
+    // если это URL (есть схема), то восстанавливается
+    // двойной слеш "https:/" -> "https://"
+    joined = joined.replace(protocolRegex, '$1://');
+  } else {
+    // если это не URL, а путь файловой системы или API,
+    // то гарантируется наличие слеша в начале
+    if (!joined.startsWith('/')) {
+      joined = '/' + joined;
+    }
+  }
+  // удаление слеша в конце, если это не корень
+  if (joined.length > 1 && joined.endsWith('/')) {
+    joined = joined.slice(0, -1);
+  }
+  return joined;
+}

package/src/utils/join-path.spec.js

@@ -0,0 +1,104 @@
+import {expect} from 'chai';
+import {joinPath} from './join-path.js';
+
+describe('joinPath', function () {
+  describe('path joining', function () {
+    it('should join multiple segments with a forward slash', function () {
+      const result = joinPath('api', 'v1', 'users');
+      expect(result).to.be.eq('/api/v1/users');
+    });
+
+    it('should always return a path starting with a single forward slash', function () {
+      expect(joinPath('users')).to.be.eq('/users');
+      expect(joinPath('/users')).to.be.eq('/users');
+    });
+
+    it('should remove leading slashes from segments', function () {
+      const result = joinPath('/api', '/v1', '/users');
+      expect(result).to.be.eq('/api/v1/users');
+    });
+
+    it('should remove trailing slashes from segments', function () {
+      const result = joinPath('api/', 'v1/', 'users/');
+      expect(result).to.be.eq('/api/v1/users');
+    });
+
+    it('should handle segments with both leading and trailing slashes', function () {
+      const result = joinPath('/api/', '/v1/', '/users/');
+      expect(result).to.be.eq('/api/v1/users');
+    });
+
+    it('should ignore empty string segments', function () {
+      const result = joinPath('api', '', 'v1', '', 'users');
+      expect(result).to.be.eq('/api/v1/users');
+    });
+
+    it('should ignore null and undefined segments', function () {
+      const result = joinPath('api', null, 'v1', undefined, 'users');
+      expect(result).to.be.eq('/api/v1/users');
+    });
+
+    it('should handle a single segment correctly', function () {
+      expect(joinPath('users')).to.be.eq('/users');
+      expect(joinPath('/users/')).to.be.eq('/users');
+    });
+
+    it('should return a single slash when no segments are provided', function () {
+      const result = joinPath();
+      expect(result).to.be.eq('/');
+    });
+
+    it('should return a single slash if all segments are empty or falsy', function () {
+      const result = joinPath('', null, '', undefined);
+      expect(result).to.be.eq('/');
+    });
+
+    it('should treat a single slash segment as an empty segment', function () {
+      const result = joinPath('api', '/', 'users');
+      expect(result).to.be.eq('/api/users');
+    });
+
+    it('should not add extra slashes if segments are already joined', function () {
+      const result = joinPath('api/v1', 'users');
+      expect(result).to.be.eq('/api/v1/users');
+    });
+
+    it('should convert number arguments to string segments', function () {
+      const result = joinPath(-10, 0, 10);
+      expect(result).to.be.eq('/-10/0/10');
+    });
+
+    it('should remove duplicate slashes', function () {
+      const result = joinPath('/', '//foo//', '///bar///');
+      expect(result).to.be.eq('/foo/bar');
+    });
+  });
+
+  describe('url joining', function () {
+    it('should preserve http:// protocol', function () {
+      const result = joinPath('http://example.com', 'api', 'v1');
+      expect(result).to.be.eq('http://example.com/api/v1');
+    });
+
+    it('should preserve https:// protocol', function () {
+      const result = joinPath('https://api.example.com/', '/users');
+      expect(result).to.be.eq('https://api.example.com/users');
+    });
+
+    it('should handle protocols with extra slashes in segments', function () {
+      const result = joinPath('https://site.com//', '//api//');
+      expect(result).to.be.eq('https://site.com/api');
+    });
+
+    it('should handle custom protocols (e.g. postgres://)', function () {
+      const result = joinPath('postgres://user:pass@localhost', 'db');
+      expect(result).to.be.eq('postgres://user:pass@localhost/db');
+    });
+
+    it('should not add a leading slash if a protocol is present', function () {
+      const result = joinPath('http://localhost');
+      expect(result).to.be.eq('http://localhost');
+      expect(result.startsWith('/')).to.be.false;
+    });
+  });
+});

package/src/utils/normalize-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Normalize path.
+ *
+ * Заменяет любые повторяющиеся слеши на один.
+ * Удаляет пробельные символы в начале и конце.
+ * Удаляет слеш в конце строки.
+ * Гарантирует слеш в начале строки (по умолчанию).
+ *
+ * @param value
+ * @param noStartingSlash
+ */
+export function normalizePath(value: string, noStartingSlash?: boolean): string;

package/src/utils/normalize-path.js

@@ -0,0 +1,22 @@
+/**
+ * Normalize path.
+ *
+ * Заменяет любые повторяющиеся слеши на один.
+ * Удаляет пробельные символы в начале и конце.
+ * Удаляет слеш в конце строки.
+ * Гарантирует слеш в начале строки (по умолчанию).
+ *
+ * @param {string} value
+ * @param {boolean} [noStartingSlash]
+ * @returns {string}
+ */
+export function normalizePath(value, noStartingSlash = false) {
+  if (typeof value !== 'string') {
+    return '/';
+  }
+  const res = value
+    .trim()
+    .replace(/\/+/g, '/')
+    .replace(/(^\/|\/$)/g, '');
+  return noStartingSlash ? res : '/' + res;
+}

package/src/utils/normalize-path.spec.js

@@ -0,0 +1,56 @@
+import {expect} from 'chai';
+import {normalizePath} from './normalize-path.js';
+
+describe('normalizePath', function () {
+  describe('input validation', function () {
+    it('should return a root path "/" if value is null', function () {
+      expect(normalizePath(null)).to.equal('/');
+    });
+
+    it('should return a root path "/" if value is undefined', function () {
+      expect(normalizePath(undefined)).to.equal('/');
+    });
+
+    it('should return a root path "/" if value is a number', function () {
+      expect(normalizePath(123)).to.equal('/');
+    });
+
+    it('should return a root path "/" if value is an object', function () {
+      expect(normalizePath({})).to.equal('/');
+    });
+  });
+
+  describe('path normalization', function () {
+    it('should replace multiple slashes with a single slash', function () {
+      expect(normalizePath('//api///users//')).to.equal('/api/users');
+    });
+
+    it('should trim a given string but preserve whitespace characters', function () {
+      expect(normalizePath(' /my folder/ ')).to.equal('/my folder');
+      expect(normalizePath('path\twith\ntabs')).to.equal('/path\twith\ntabs');
+    });
+
+    it('should remove leading and trailing slashes before applying the final format', function () {
+      expect(normalizePath('/foo/bar/')).to.equal('/foo/bar');
+    });
+
+    it('should handle an empty string by returning "/" by default', function () {
+      expect(normalizePath('')).to.equal('/');
+    });
+  });
+
+  describe('the "noStartingSlash" option', function () {
+    it('should always prepend a leading slash when the option is false', function () {
+      expect(normalizePath('foo/bar', false)).to.equal('/foo/bar');
+    });
+
+    it('should not prepend a leading slash when the option is true', function () {
+      expect(normalizePath('/foo/bar/', true)).to.equal('foo/bar');
+    });
+
+    it('should return an empty string if the input results in an empty path', function () {
+      expect(normalizePath('', true)).to.equal('');
+      expect(normalizePath('///', true)).to.equal('');
+    });
+  });
+});

package/src/utils/to-pascal-case.d.ts

@@ -0,0 +1,6 @@
+/**
+ * To pascal case.
+ *
+ * @param input
+ */
+export declare function toPascalCase(input: string): string;

package/src/utils/to-pascal-case.js

@@ -0,0 +1,26 @@
+/**
+ * To pascal case.
+ *
+ * @param {string} input
+ * @returns {string}
+ */
+export function toPascalCase(input) {
+  if (!input) {
+    return '';
+  }
+  return (
+    input
+      // splits camelCase words into separate words
+      .replace(/([a-z])([A-Z])/g, '$1 $2')
+      // splits numbers and words
+      .replace(/([0-9])([a-zA-Z])/g, '$1 $2')
+      // replaces dashes, underscores, and special characters with spaces
+      .replace(/[-_]+|[^\p{L}\p{N}]/gu, ' ')
+      // converts the entire string to lowercase
+      .toLowerCase()
+      // capitalizes the first letter of each word
+      .replace(/(?:^|\s)(\p{L})/gu, (_, letter) => letter.toUpperCase())
+      // removes all spaces
+      .replace(/\s+/g, '')
+  );
+}

package/src/utils/to-pascal-case.spec.js

@@ -0,0 +1,15 @@
+import {expect} from 'chai';
+import {toPascalCase} from './to-pascal-case.js';
+
+describe('toPascalCase', function () {
+  it('returns a PascalCase string', function () {
+    expect(toPascalCase('hello world')).to.be.eq('HelloWorld');
+    expect(toPascalCase('snake_case')).to.be.eq('SnakeCase');
+    expect(toPascalCase('kebab-case')).to.be.eq('KebabCase');
+    expect(toPascalCase('alreadyCamel')).to.be.eq('AlreadyCamel');
+    expect(toPascalCase('AlreadyPascal')).to.be.eq('AlreadyPascal');
+    expect(toPascalCase(' single word ')).to.be.eq('SingleWord');
+    expect(toPascalCase('')).to.be.eq('');
+    expect(toPascalCase('1number')).to.be.eq('1Number');
+  });
+});

package/src/utils/to-spaced-json.d.ts

@@ -0,0 +1,17 @@
+/**
+ * To spaced JSON options.
+ */
+export type ToSpacedJsonOptions = {
+  truncate?: number;
+};
+
+/**
+ * Функция превращает объект в JSON с пробелами,
+ * но в одну строку.
+ *
+ * @param value
+ */
+export function toSpacedJson(
+  value: unknown,
+  options?: ToSpacedJsonOptions,
+): string;

package/src/utils/to-spaced-json.js

@@ -0,0 +1,27 @@
+/**
+ * Функция превращает объект в JSON с пробелами,
+ * но в одну строку.
+ *
+ * @param {*} value
+ * @param {*} [options]
+ * @returns {string}
+ */
+export function toSpacedJson(value, options = {}) {
+  const stringified = JSON.stringify(value, null, 1);
+  const res = stringified
+    ? stringified
+        .replace(/\n\s*/g, ' ')
+        .replace(/\[\s/g, '[')
+        .replace(/\s\]/g, ']')
+        .replace(/\{\s/g, '{')
+        .replace(/\s\}/g, '}')
+    : 'undefined';
+  if (
+    options.truncate &&
+    typeof options.truncate === 'number' &&
+    res.length > options.truncate
+  ) {
+    return res.slice(0, options.truncate) + '...';
+  }
+  return res;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "es2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "allowJs": true
+  },
+  "include": [
+    "./src/**/*.ts",
+    "./src/**/*.js"
+  ]
+}