@e22m4u/js-openapi 0.0.5

package/src/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './oa-data-validation-error.js';

package/src/errors/index.js

@@ -0,0 +1 @@
+export * from './oa-data-validation-error.js';

package/src/errors/oa-data-validation-error.d.ts

@@ -0,0 +1,6 @@
+import {Errorf} from '@e22m4u/js-format';
+
+/**
+ * Data validation error.
+ */
+export class OADataValidationError extends Errorf {}

package/src/errors/oa-data-validation-error.js

@@ -0,0 +1,6 @@
+import {Errorf} from '@e22m4u/js-format';
+
+/**
+ * Data validation error.
+ */
+export class OADataValidationError extends Errorf {}

package/src/errors/oa-data-validation-error.spec.js

@@ -0,0 +1,17 @@
+import {expect} from 'chai';
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {OADataValidationError} from './oa-data-validation-error.js';
+
+describe('OADataValidationError', function () {
+  describe('constructor', function () {
+    it('should interpolate an error message with given arguments', function () {
+      const res = new OADataValidationError('message %v %s', 'str', 10);
+      expect(res.message).to.be.eql('message "str" 10');
+    });
+
+    it('should not extend the InvalidArgumentError class', function () {
+      const res = new OADataValidationError('message');
+      expect(res).to.be.not.instanceOf(InvalidArgumentError);
+    });
+  });
+});

package/src/index.d.ts

@@ -0,0 +1,9 @@
+export * from './errors/index.js';
+export * from './data-type/index.js';
+export * from './oa-specification.js';
+export * from './oa-document-scope.js';
+export * from './json-pointer/index.js';
+export * from './oa-document-builder.js';
+export * from './data-validation/index.js';
+export * from './oa-document-object/index.js';
+export * from './oa-reference-object/index.js';

package/src/index.js

@@ -0,0 +1,9 @@
+export * from './errors/index.js';
+export * from './data-type/index.js';
+export * from './oa-specification.js';
+export * from './oa-document-scope.js';
+export * from './json-pointer/index.js';
+export * from './oa-document-builder.js';
+export * from './data-validation/index.js';
+export * from './oa-document-object/index.js';
+export * from './oa-reference-object/index.js';

package/src/json-pointer/escape-json-pointer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escape JSON Pointer.
+ * Replaces "~" with "~0" and "/" with "~1".
+ *
+ * @param jsonPointer
+ */
+export declare function escapeJsonPointer(jsonPointer: string): string;

package/src/json-pointer/escape-json-pointer.js

@@ -0,0 +1,18 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+
+/**
+ * Escape JSON Pointer.
+ * Replaces "~" with "~0" and "/" with "~1".
+ *
+ * @param {string} jsonPointer
+ * @returns {string}
+ */
+export function escapeJsonPointer(jsonPointer) {
+  if (typeof jsonPointer !== 'string') {
+    throw new InvalidArgumentError(
+      'Parameter "jsonPointer" must be a String, but %v was given.',
+      jsonPointer,
+    );
+  }
+  return jsonPointer.replace(/~/g, '~0').replace(/\//g, '~1');
+}

package/src/json-pointer/escape-json-pointer.spec.js

@@ -0,0 +1,36 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {escapeJsonPointer} from './escape-json-pointer.js';
+
+describe('escapeJsonPointer', function () {
+  it('should require the "jsonPointer" parameter to be a String', function () {
+    const throwable = v => () => escapeJsonPointer(v);
+    const error = s =>
+      format('Parameter "jsonPointer" 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'));
+    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('str')();
+    throwable('')();
+  });
+
+  it('should replace "~" with "~0"', function () {
+    expect(escapeJsonPointer('example~test')).to.eq('example~0test');
+  });
+
+  it('should replace "/" with "~1"', function () {
+    expect(escapeJsonPointer('models/User')).to.eq('models~1User');
+  });
+
+  it('should handle complex strings', function () {
+    expect(escapeJsonPointer('a/b~c')).to.eq('a~1b~0c');
+  });
+
+  it('should do nothing if no special chars are present', function () {
+    expect(escapeJsonPointer('simple')).to.eq('simple');
+  });
+});

package/src/json-pointer/index.d.ts

@@ -0,0 +1,3 @@
+export * from './escape-json-pointer.js';
+export * from './resolve-json-pointer.js';
+export * from './unescape-json-pointer.js';

package/src/json-pointer/index.js

@@ -0,0 +1,3 @@
+export * from './escape-json-pointer.js';
+export * from './resolve-json-pointer.js';
+export * from './unescape-json-pointer.js';

package/src/json-pointer/resolve-json-pointer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve json pointer.
+ *
+ * @param document
+ * @param pointer
+ */
+export function resolveJsonPointer<T = any>(
+  document: object | unknown[],
+  pointer: string,
+): T;

package/src/json-pointer/resolve-json-pointer.js

@@ -0,0 +1,83 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+import {unescapeJsonPointer} from '../json-pointer/index.js';
+
+/**
+ * Регулярное выражение для индексов массива.
+ * RFC 6901: A token that is a decimal number (0, 1, 2...)
+ */
+const ARRAY_INDEX_PATTERN = /^(0|[1-9][0-9]*)$/;
+
+/**
+ * Resolve json pointer.
+ *
+ * @param {object|*[]} document
+ * @param {object} pointer
+ * @returns {*}
+ */
+export function resolveJsonPointer(document, pointer) {
+  if (!document || typeof document !== 'object') {
+    throw new InvalidArgumentError(
+      'Parameter "document" must be an Object or an Array, but %v was given.',
+      document,
+    );
+  }
+  if (typeof pointer !== 'string') {
+    throw new InvalidArgumentError(
+      'JSON pointer must be a String, but %v was given.',
+      pointer,
+    );
+  }
+  // так как пустая строка является указателем
+  // корня документа, то в этом случае возвращается
+  // сам документ без поиска сегмента
+  if (pointer === '') {
+    return document;
+  }
+  // указатель должен начинаться с символа "/",
+  // в противном случае выбрасывается ошибка
+  if (!pointer.startsWith('/')) {
+    throw new InvalidArgumentError(
+      'JSON pointer must start with a forward slash "/", but %v was given.',
+      pointer,
+    );
+  }
+  // если указатель содержит сегменты,
+  // то выполняется их извлечение
+  const pathParts = pointer.substring(1).split('/');
+  let current = document;
+  for (let i = 0, l = pathParts.length; i < l; i++) {
+    const part = pathParts[i];
+    const segment = unescapeJsonPointer(part);
+    // если предыдущий узел является объектом,
+    // то проверяется наличие данного ключа
+    if (
+      current &&
+      typeof current === 'object' &&
+      !Array.isArray(current) &&
+      Object.hasOwn(current, segment) &&
+      current[segment] !== undefined
+    ) {
+      current = current[segment];
+    }
+    // элементы массива должны извлекаться только
+    // по числовым индексам, но исключая индексы
+    // начинающиеся с нуля (но сам ноль допустим)
+    else if (
+      Array.isArray(current) &&
+      ARRAY_INDEX_PATTERN.test(segment) &&
+      current[segment] !== undefined
+    ) {
+      current = current[segment];
+    }
+    // если узел не содержит значения,
+    // то выбрасывается ошибка
+    else {
+      const currentPointer = '/' + pathParts.slice(0, i + 1).join('/');
+      throw new InvalidArgumentError(
+        'Unable to resolve %v in the given document.',
+        currentPointer,
+      );
+    }
+  }
+  return current;
+}

package/src/json-pointer/resolve-json-pointer.spec.js

@@ -0,0 +1,103 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {resolveJsonPointer} from './resolve-json-pointer.js';
+
+describe('resolveJsonPointer', function () {
+  it('should require the parameter "document" to be an Object or an Array', function () {
+    const throwable = v => () => resolveJsonPointer(v, '/0');
+    const error = s =>
+      format(
+        'Parameter "document" 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(undefined)).to.throw(error('undefined'));
+    expect(throwable(null)).to.throw(error('null'));
+    throwable({0: 'bar'})();
+    throwable(['bar'])();
+  });
+
+  it('should require the parameter "pointer" to be a String', function () {
+    const throwable = v => () => resolveJsonPointer({foo: 'bar'}, v);
+    const error = s =>
+      format('JSON pointer 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'));
+    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('/foo')();
+    throwable('')();
+  });
+
+  it('should return the document when an empty string is given', function () {
+    const document = {};
+    const res = resolveJsonPointer(document, '');
+    expect(res).to.be.eq(document);
+  });
+
+  it('should be able to find a node with an empty string key', function () {
+    const node = {foo: 'bar'};
+    const res1 = resolveJsonPointer({'': node}, '/');
+    expect(res1).to.be.eq(node);
+    const res2 = resolveJsonPointer({path: {'': node}}, '/path/');
+    expect(res2).to.be.eq(node);
+  });
+
+  it('should unescape segments of the json pointer', function () {
+    const node = {foo: 'bar'};
+    const res = resolveJsonPointer({'/path': node}, '/~1path');
+    expect(res).to.be.eq(node);
+  });
+
+  it('should return a document node for the segment chain', function () {
+    const node = {foo: 'bar'};
+    const res = resolveJsonPointer({a: {b: {c: node}}}, '/a/b/c');
+    expect(res).to.be.eq(node);
+  });
+
+  it('should resolve an array element when the document is an array', function () {
+    const res = resolveJsonPointer(['foo', 'bar', 'baz'], '/1');
+    expect(res).to.be.eq('bar');
+  });
+
+  it('should be able to walk through an array element', function () {
+    const res = resolveJsonPointer(
+      [{prop: 'foo'}, {prop: 'bar'}, {prop: 'baz'}],
+      '/1/prop',
+    );
+    expect(res).to.be.eq('bar');
+  });
+
+  it('should throw an error when an array index has a zero prefix', function () {
+    const throwable = () => resolveJsonPointer(['foo', 'bar', 'baz'], '/01');
+    expect(throwable).to.throw(
+      'Unable to resolve "/01" in the given document.',
+    );
+  });
+
+  it('should throw an error if a property value is undefined', function () {
+    const node = {foo: undefined};
+    const throwable = () => resolveJsonPointer(node, '/foo');
+    expect(throwable).to.throw(
+      'Unable to resolve "/foo" in the given document.',
+    );
+  });
+
+  it('should return the pointer target when its value is not undefined', function () {
+    const values = ['str', '', 10, 0, true, false, {}, [], null];
+    values.forEach(value => {
+      const document = {foo: value};
+      const res = resolveJsonPointer(document, '/foo');
+      expect(res).to.be.eq(value);
+    });
+  });
+});

package/src/json-pointer/unescape-json-pointer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unescape JSON Pointer.
+ * Replaces "~1" with "/" and "~0" with "~".
+ *
+ * @param {string} jsonPointer
+ * @returns {string}
+ */
+export declare function unescapeJsonPointer(jsonPointer: string): string;

package/src/json-pointer/unescape-json-pointer.js

@@ -0,0 +1,18 @@
+import {InvalidArgumentError} from '@e22m4u/js-format';
+
+/**
+ * Unescape JSON Pointer.
+ * Replaces "~1" with "/" and "~0" with "~".
+ *
+ * @param {string} jsonPointer
+ * @returns {string}
+ */
+export function unescapeJsonPointer(jsonPointer) {
+  if (typeof jsonPointer !== 'string') {
+    throw new InvalidArgumentError(
+      'Parameter "jsonPointer" must be a String, but %v was given.',
+      jsonPointer,
+    );
+  }
+  return jsonPointer.replace(/~1/g, '/').replace(/~0/g, '~');
+}

package/src/json-pointer/unescape-json-pointer.spec.js

@@ -0,0 +1,32 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {unescapeJsonPointer} from './unescape-json-pointer.js';
+
+describe('unescapeJsonPointer', function () {
+  it('should require the "jsonPointer" parameter to be a String', function () {
+    const throwable = v => () => unescapeJsonPointer(v);
+    const error = s =>
+      format('Parameter "jsonPointer" 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'));
+    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('str')();
+    throwable('')();
+  });
+
+  it('should replace "~0" with "~"', function () {
+    expect(unescapeJsonPointer('example~0test')).to.eq('example~test');
+  });
+
+  it('should replace "~1" with "/"', function () {
+    expect(unescapeJsonPointer('models~1User')).to.eq('models/User');
+  });
+
+  it('should handle complex strings', function () {
+    expect(unescapeJsonPointer('a~1b~0c')).to.eq('a/b~c');
+  });
+});