@swagger-api/apidom-parser-adapter-json 0.68.1

package/README.md

@@ -0,0 +1,125 @@
+# @swagger-api/apidom-parser-adapter-json
+
+`@swagger-api/apidom-parser-adapter-json` is a parser adapter for the [JSON format](https://www.json.org/json-en.html).
+
+[CST](https://tree-sitter.github.io/tree-sitter/using-parsers#syntax-nodes) produced by lexical analysis is [syntactically analyzed](https://github.com/swagger-api/apidom/blob/main/packages/apidom-parser-adapter-json/src/syntactic-analysis) and
+ApiDOM structure using [base ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom#base-namespace) is produced.
+
+## Installation
+
+After [prerequisites](https://github.com/swagger-api/apidom/blob/main/README.md#prerequisites) for installing this package are satisfied, you can install it
+via [npm CLI](https://docs.npmjs.com/cli) by running the following command:
+
+```sh
+ $ npm install @swagger-api/apidom-parser-adapter-json
+```
+
+## Parse phases
+
+The parse stage takes JSON string and produces ApiDOM structure using [base ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom#base-namespace).
+There are two phases of parsing: **Lexical Analysis** and **Syntactic Analysis**.
+
+### Lexical Analysis
+
+Lexical Analysis will take a JSON string and turn it into a stream of tokens.
+[tree-sitter](https://www.npmjs.com/package/tree-sitter) / [web-tree-sitter](https://www.npmjs.com/package/web-tree-sitter) is used as an underlying lexical analyzer.
+
+### Syntactic Analysis
+
+Syntactic Analysis will take a stream of tokens and turn it into an ApiDOM representation.
+[CST](https://tree-sitter.github.io/tree-sitter/using-parsers#syntax-nodes) produced by lexical analysis is [syntactically analyzed](https://github.com/swagger-api/apidom/blob/main/packages/apidom-parser-adapter-json/src/syntactic-analysis)
+and ApiDOM structure using [base ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom#base-namespace) is produced.
+
+#### [Direct Syntactical analysis](https://github.com/swagger-api/apidom/blob/main/packages/apidom-parser-adapter-json/src/syntactic-analysis/direct)
+
+This analysis directly turns tree-sitter CST into ApiDOM. Single traversal is required which makes
+it super performant, and it's the default analysis used.
+
+```js
+import { parse } from '@swagger-api/apidom-parser-adapter-json';
+
+const parseResult = await parse('{"prop": "value"}', {
+  syntacticAnalysis: 'direct',
+});
+```
+
+#### [Indirect Syntactic analysis]((https://github.com/swagger-api/apidom/blob/main/packages/apidom-parser-adapter-json/src/syntactic-analysis/indirect))
+
+This analysis turns trees-sitter CST into [JSON AST](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ast#json-ast-nodes) representation.
+Then JSON AST is turned into ApiDOM. Two traversals are required, which makes indirect analysis less performant than direct one.
+Thought less performant, having JSON AST representation allows us to do further complex analysis.
+
+```js
+import { parse } from '@swagger-api/apidom-parser-adapter-json';
+
+const parseResult = await parse('{"prop": "value"}', {
+  syntacticAnalysis: 'indirect',
+});
+```
+
+## Parser adapter API
+
+This parser adapter is fully compatible with parser adapter interface required by [@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser#mounting-parser-adapters)
+and implements all required properties.
+
+### mediaTypes
+
+Defines list of media types that this parser adapter recognizes.
+
+```js
+['application/json']
+```
+
+### detect
+
+[Detection](https://github.com/swagger-api/apidom/blob/main/packages/apidom-parser-adapter-json/src/adapter.ts#L3) is based on using [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) to indicate whether the provided source string is or isn't JSON string.
+
+### namespace
+
+This adapter exposes an instance of [base ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom#base-namespace).
+
+### parse
+
+`parse` function consumes various options as a second argument. Here is a list of these options:
+
+Option | Type | Default | Description
+--- | --- | --- | ---
+<a name="sourceMap"></a>`sourceMap` | `Boolean` | `false` | Indicate whether to generate source maps.
+<a name="syntacticAnalysis"></a>`syntacticAnalysis` | `String` | `direct` | Indicate type of syntactic analysis
+
+All unrecognized arbitrary options will be ignored.
+
+## Usage
+
+This parser adapter can be used directly or indirectly via [@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser).
+
+### Direct usage
+
+During direct usage you don't need to provide `mediaType` as the `parse` function is already pre-bound
+with [supported media types](#mediatypes).
+
+```js
+import { parse, detect } from '@swagger-api/apidom-parser-adapter-json';
+
+// detecting
+await detect('{"prop": "value"}'); // => true
+await detect('test'); // => false
+
+// parsing
+const parseResult = await parse('{"prop": "value"}', { sourceMap: true });
+```
+
+### Indirect usage
+
+You can omit the `mediaType` option here, but please read [Word on detect vs mediaTypes](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser#word-on-detect-vs-mediatypes) before you do so.
+
+```js
+import ApiDOMParser from '@swagger-api/apidom-parser';
+import * as jsonParserAdapter from '@swagger-api/apidom-parser-adapter-json';
+
+const parser = ApiDOMParser();
+
+parser.use(jsonParserAdapter);
+
+const parseResult = await parser.parse('{"prop", "value"}', { mediaType: jsonParserAdapter.mediaTypes.latest('json') });
+```

package/cjs/adapter-browser.cjs

@@ -0,0 +1,46 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault");
+exports.__esModule = true;
+exports.parse = exports.namespace = exports.mediaTypes = exports.detect = void 0;
+var _browser = _interopRequireDefault(require("./lexical-analysis/browser.cjs"));
+exports.lexicalAnalysis = _browser.default;
+var _index = _interopRequireDefault(require("./syntactic-analysis/direct/index.cjs"));
+exports.syntacticAnalysis = _index.default;
+exports.syntacticAnalysisDirect = _index.default;
+var _index2 = _interopRequireDefault(require("./syntactic-analysis/indirect/index.cjs"));
+exports.syntacticAnalysisIndirect = _index2.default;
+var _adapter = require("./adapter.cjs");
+exports.detectionRegExp = _adapter.detectionRegExp;
+exports.mediaTypes = _adapter.mediaTypes;
+exports.namespace = _adapter.namespace;
+const detect = async source => {
+  if (!_adapter.detectionRegExp.test(source)) {
+    return false;
+  }
+  try {
+    const cst = await (0, _browser.default)(source);
+    return cst.rootNode.type !== 'ERROR';
+  } catch {
+    return false;
+  }
+};
+exports.detect = detect;
+const parse = async (source, {
+  sourceMap = false,
+  syntacticAnalysis = 'direct'
+} = {}) => {
+  const cst = await (0, _browser.default)(source);
+  let apiDOM;
+  if (syntacticAnalysis === 'indirect') {
+    apiDOM = (0, _index2.default)(cst, {
+      sourceMap
+    });
+  } else {
+    apiDOM = (0, _index.default)(cst, {
+      sourceMap
+    });
+  }
+  return apiDOM;
+};
+exports.parse = parse;

package/cjs/adapter-node.cjs

@@ -0,0 +1,46 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault");
+exports.__esModule = true;
+exports.parse = exports.namespace = exports.mediaTypes = exports.detect = void 0;
+var _node = _interopRequireDefault(require("./lexical-analysis/node.cjs"));
+exports.lexicalAnalysis = _node.default;
+var _index = _interopRequireDefault(require("./syntactic-analysis/direct/index.cjs"));
+exports.syntacticAnalysis = _index.default;
+exports.syntacticAnalysisDirect = _index.default;
+var _index2 = _interopRequireDefault(require("./syntactic-analysis/indirect/index.cjs"));
+exports.syntacticAnalysisIndirect = _index2.default;
+var _adapter = require("./adapter.cjs");
+exports.detectionRegExp = _adapter.detectionRegExp;
+exports.mediaTypes = _adapter.mediaTypes;
+exports.namespace = _adapter.namespace;
+const detect = async source => {
+  if (!_adapter.detectionRegExp.test(source)) {
+    return false;
+  }
+  try {
+    const cst = await (0, _node.default)(source);
+    return cst.rootNode.type !== 'ERROR';
+  } catch {
+    return false;
+  }
+};
+exports.detect = detect;
+const parse = async (source, {
+  sourceMap = false,
+  syntacticAnalysis = 'direct'
+} = {}) => {
+  const cst = await (0, _node.default)(source);
+  let apiDOM;
+  if (syntacticAnalysis === 'indirect') {
+    apiDOM = (0, _index2.default)(cst, {
+      sourceMap
+    });
+  } else {
+    apiDOM = (0, _index.default)(cst, {
+      sourceMap
+    });
+  }
+  return apiDOM;
+};
+exports.parse = parse;

package/cjs/adapter.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault");
+exports.__esModule = true;
+exports.namespace = exports.mediaTypes = exports.detectionRegExp = void 0;
+var _apidomCore = require("@swagger-api/apidom-core");
+var _mediaTypes = _interopRequireDefault(require("./media-types.cjs"));
+exports.mediaTypes = _mediaTypes.default;
+const namespace = (0, _apidomCore.createNamespace)();
+exports.namespace = namespace;
+const detectionRegExp =
+// eslint-disable-next-line no-control-regex
+/(?<true>^\s*true\s*$)|(?<false>^\s*false\s*$)|(?<null>^\s*null\s*$)|(?<number>^\s*\d+\s*$)|(?<object>^\s*{\s*)|(?<array>^\s*\[\s*)|(?<string>^\s*"(((?=\\)\\(["\\/bfnrt]|u[0-9a-fA-F]{4}))|[^"\\\x00-\x1F\x7F])*"\s*$)/;
+exports.detectionRegExp = detectionRegExp;

package/cjs/lexical-analysis/browser-patch.cjs

@@ -0,0 +1,20 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault");
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _treeSitter = _interopRequireDefault(require("web-tree-sitter/tree-sitter.wasm"));
+// @ts-ignore
+
+// patch fetch() to let emscripten load the WASM file
+const realFetch = globalThis.fetch;
+if ((0, _ramdaAdjunct.isFunction)(realFetch)) {
+  globalThis.fetch = (...args) => {
+    // @ts-ignore
+    if ((0, _ramdaAdjunct.isString)(args[0]) && args[0].endsWith('tree-sitter.wasm')) {
+      // @ts-ignore
+      return realFetch.apply(globalThis, [_treeSitter.default, (0, _ramda.tail)(args)]);
+    }
+    return realFetch.apply(globalThis, args);
+  };
+}

package/cjs/lexical-analysis/browser.cjs

@@ -0,0 +1,42 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault");
+exports.__esModule = true;
+exports.default = void 0;
+require("./browser-patch.cjs");
+var _webTreeSitter = _interopRequireDefault(require("web-tree-sitter"));
+var _treeSitterJson = _interopRequireDefault(require("../../wasm/tree-sitter-json.wasm"));
+// @ts-ignore
+
+let parser = null;
+let parserInitLock = null;
+
+/**
+ * Lexical Analysis of source string using WebTreeSitter.
+ * This is WebAssembly version of TreeSitters Lexical Analysis.
+ *
+ * Given JavaScript doesn't support true parallelism, this
+ * code should be as lazy as possible and temporal safety should be fine.
+ */
+const analyze = async source => {
+  if (parser === null && parserInitLock === null) {
+    // acquire lock
+    parserInitLock = _webTreeSitter.default.init().then(() => _webTreeSitter.default.Language.load(_treeSitterJson.default)).then(jsonLanguage => {
+      const parserInstance = new _webTreeSitter.default();
+      parserInstance.setLanguage(jsonLanguage);
+      return parserInstance;
+    }).finally(() => {
+      // release lock
+      parserInitLock = null;
+    });
+    parser = await parserInitLock;
+  } else if (parser === null && parserInitLock !== null) {
+    // await for lock to be released if there is one
+    parser = await parserInitLock;
+  } else if (parser === null) {
+    throw new Error('Error while initializing web-tree-sitter');
+  }
+  return parser.parse(source);
+};
+var _default = analyze;
+exports.default = _default;

package/cjs/lexical-analysis/node.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault");
+exports.__esModule = true;
+exports.default = void 0;
+var _treeSitter = _interopRequireDefault(require("tree-sitter"));
+var _treeSitterJson = _interopRequireDefault(require("tree-sitter-json"));
+// @ts-ignore
+
+const parser = new _treeSitter.default();
+parser.setLanguage(_treeSitterJson.default);
+
+/**
+ * Lexical Analysis of source string using TreeSitter.
+ * This is Node.js version of TreeSitters Lexical Analysis.
+ */
+const analyze = async source => {
+  return parser.parse(source);
+};
+var _default = analyze;
+exports.default = _default;

package/cjs/media-types.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = exports.JSONMediaTypes = void 0;
+var _apidomCore = require("@swagger-api/apidom-core");
+class JSONMediaTypes extends _apidomCore.MediaTypes {
+  latest() {
+    return this[0];
+  }
+}
+exports.JSONMediaTypes = JSONMediaTypes;
+const mediaTypes = new JSONMediaTypes('application/json');
+var _default = mediaTypes;
+exports.default = _default;

package/cjs/syntactic-analysis/PreOrderCursorChildrenIterator.cjs

@@ -0,0 +1,33 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class PreOrderCursorChildrenIterator {
+  constructor(cursor) {
+    this.cursor = cursor;
+  }
+  createNode() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      children: []
+    };
+  }
+  *[Symbol.iterator]() {
+    // @ts-ignore
+    const method = this[this.cursor.nodeType];
+    const currentNode = (method || this.createNode).call(this);
+    const constructor = this.constructor;
+    if (this.cursor.gotoFirstChild()) {
+      currentNode.children.push(...[...new constructor(this.cursor)]);
+      while (this.cursor.gotoNextSibling()) {
+        currentNode.children.push(...[...new constructor(this.cursor)]);
+      }
+      this.cursor.gotoParent();
+    }
+    yield currentNode;
+  }
+}
+var _default = PreOrderCursorChildrenIterator;
+exports.default = _default;

package/cjs/syntactic-analysis/PreOrderCusrorIterator.cjs

@@ -0,0 +1,31 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class PreOrderCursorIterator {
+  constructor(cursor) {
+    this.cursor = cursor;
+  }
+  createNode() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition
+    };
+  }
+  *[Symbol.iterator]() {
+    // @ts-ignore
+    const method = this[this.cursor.nodeType];
+    const constructor = this.constructor;
+    yield (method || this.createNode).call(this);
+    if (this.cursor.gotoFirstChild()) {
+      yield* new constructor(this.cursor);
+      while (this.cursor.gotoNextSibling()) {
+        yield* new constructor(this.cursor);
+      }
+      this.cursor.gotoParent();
+    }
+  }
+}
+var _default = PreOrderCursorIterator;
+exports.default = _default;

package/cjs/syntactic-analysis/direct/CursorIterator.cjs

@@ -0,0 +1,110 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault");
+exports.__esModule = true;
+exports.default = void 0;
+var _PreOrderCursorChildrenIterator = _interopRequireDefault(require("../PreOrderCursorChildrenIterator.cjs"));
+class CursorIterator extends _PreOrderCursorChildrenIterator.default {
+  document() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      children: []
+    };
+  }
+  object() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      fieldName: this.cursor.currentFieldName,
+      children: []
+    };
+  }
+  array() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      fieldName: this.cursor.currentFieldName,
+      children: []
+    };
+  }
+  pair() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      get keyNode() {
+        return this.children.find(node => node.fieldName === 'key');
+      },
+      get valueNode() {
+        return this.children.find(node => node.fieldName === 'value');
+      },
+      children: []
+    };
+  }
+  string() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      text: this.cursor.nodeText,
+      fieldName: this.cursor.currentFieldName,
+      children: []
+    };
+  }
+  number() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      text: this.cursor.nodeText,
+      fieldName: this.cursor.currentFieldName,
+      children: []
+    };
+  }
+  null() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      fieldName: this.cursor.currentFieldName,
+      children: []
+    };
+  }
+  true() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      fieldName: this.cursor.currentFieldName,
+      children: []
+    };
+  }
+  false() {
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      fieldName: this.cursor.currentFieldName,
+      children: []
+    };
+  }
+  ERROR() {
+    const {
+      currentNode
+    } = this.cursor;
+    return {
+      type: this.cursor.nodeType,
+      startPosition: this.cursor.startPosition,
+      endPosition: this.cursor.endPosition,
+      // @ts-ignore
+      hasError: () => currentNode.hasError(),
+      children: []
+    };
+  }
+}
+var _default = CursorIterator;
+exports.default = _default;