@swagger-api/apidom-core 0.68.1

package/README.md

@@ -0,0 +1,679 @@
+# @swagger-api/apidom-core
+
+`apidom-core` is a package that contains tools for manipulating the ApiDOM structures.
+
+## Installation
+
+You can install this package via [npm CLI](https://docs.npmjs.com/cli) by running the following command:
+
+```sh
+ $ npm install @swagger-api/apidom-core
+```
+
+---
+
+## Base namespace
+
+Base namespace consists of [four higher order elements](https://github.com/swagger-api/apidom/tree/main/packages/apidom-core/src/elements) implemented on top
+of [primitive ones](https://github.com/refractproject/minim/tree/master/lib/primitives).
+
+```js
+import { createNamespace } from '@swagger-api/apidom-core';
+
+const namespace = createNamespace();
+
+const objectElement = new namespace.elements.Object();
+const commentElement = new namespace.elements.Comment();
+```
+
+It's possible to create namespace instances using another namespaces.
+
+```js
+import { createNamespace } from '@swagger-api/apidom-core';
+import openApi3_1Namespace from '@swagger-api/apidom-ns-openapi-3-1';
+
+const namespace = createNamespace(openApi3_1Namespace);
+
+const objectElement = new namespace.elements.Object();
+const openApiElement = new namespace.elements.OpenApi3_1();
+```
+
+When namespace instance is created in this way, it will extend the base namespace
+with the namespace provided as an argument.
+
+---
+
+## Predicates
+
+This package exposes [predicates](https://github.com/swagger-api/apidom/blob/main/packages/apidom-core/src/predicates/index.ts)
+for all primitive elements and all higher order elements that are part of the base namespace.
+
+```js
+import { CommentElement, isCommentElement } from '@swagger-api/apidom-core';
+
+const commentElement = new CommentElement();
+
+isCommentElement(commentElement); // => true
+```
+
+[Predicate helpers](https://github.com/swagger-api/apidom/blob/main/packages/apidom-core/src/predicates/helpers.ts)
+helps in building predicates for this and other packages.
+
+```js
+import { createPredicate } from '@swagger-api/apidom-core';
+
+const isMyElement = createPredicate(
+  ({ hasBasicElementProps, isElementType, primitiveEq }) => {
+    return (element) =>
+      element instanceof MyElement ||
+      (hasBasicElementProps(element) && isElementType('myElement', element) && primitiveEq('object', element));
+  },
+);
+```
+
+---
+
+## Transcluder
+
+Transclusion is the inclusion of one ApiDOM fragment into another ApiDOM fragment.
+Our [transcluder](https://github.com/swagger-api/apidom/tree/main/packages/apidom-core/src/transcluder) does exactly that and is based on mutating algorithm.
+
+```js
+import { transclude, ArrayElement, NumberElement } from '@swagger-api/apidom-core';
+
+const element = new ArrayElement([1, 2, 3]);
+const search = element.get(1);
+const replace = new NumberElement(4);
+
+transclude(search, replace, element); // => ArrayElement<[1, 4, 3]>
+```
+
+When multiple transclusions are going to be performed use [Transcluder stamp](https://github.com/swagger-api/apidom/blob/main/packages/apidom-core/src/transcluder/Transcluder.ts)
+for optimal performance.
+
+```js
+import { Transcluder, ArrayElement, NumberElement } from '@swagger-api/apidom-core';
+
+const element = new ArrayElement([1, 2, 3]);
+const search = element.get(1);
+const replace = new NumberElement(4);
+const transcluder = Transcluder({ element });
+
+transcluder.transclude(search, replace); // => ArrayElement<[1, 4, 3]>
+```
+
+---
+
+## Deep merging
+
+`deepmerge` functions merged members of two or more ObjectElements deeply
+and handles deep merging of ArrayElements as well. This deep merge implementation
+is a functional equivalent of [deepmerge](https://www.npmjs.com/package/deepmerge)
+that works equivalently on ApiDOM structures.
+
+### API
+
+#### deepmerge(target, source, [options])
+
+Merge two ApiDOM elements target and source deeply, returning a new merged ApiDOM element with the elements
+from both target and source. If an element at the same key is present for both target and source,
+the value from source will appear in the result. Merging creates a new ApiDOM element,
+so that neither target nor source is modified (operation is immutable).
+
+```js
+import { deepmerge, ObjectElement } from '@swagger-api/apidom-core';
+
+const x = new ObjectElement({
+  foo: { bar: 3 },
+  array: [
+    {
+      does: 'work',
+      too: [1, 2, 3],
+    },
+  ],
+});
+
+const y = new ObjectElement({
+  foo: { baz: 4 },
+  quux: 5,
+  array: [
+    {
+      does: 'work',
+      too: [4, 5, 6],
+    },
+    {
+      really: 'yes',
+    },
+  ],
+});
+
+const output = deepmerge(x, y);
+// =>
+// ObjectElement({
+//   foo: ObjectElement({
+//     bar: 3,
+//     baz: 4,
+//   }),
+//   array: ArrayElement([
+//     ObjectElement({
+//       does: 'work',
+//       too: [1, 2, 3],
+//     }),
+//     ObjectElement({
+//       does: 'work',
+//       too: [4, 5, 6],
+//     }),
+//     ObjectElement({
+//       really: 'yes',
+//     }),
+//   ]),
+//   quux: 5,
+// })
+```
+
+#### deepmerge.all([element1, element2, ...], [options])
+
+Merges any number of ApiDOM elements into a single ApiDOM element.
+
+```js
+import { deepmerge, ObjectElement } from '@swagger-api/apidom-core';
+
+const foobar = new ObjectElement({ foo: { bar: 3 } });
+const foobaz = new ObjectElement({ foo: { baz: 4 } });
+const bar = new ObjectElement({ bar: 'yay!' });
+
+const output = deepmerge.all([ foobar, foobaz, bar ]);
+// => ObjectElement({ foo: { bar: 3, baz: 4 }, bar: 'yay!' })
+```
+
+### Options
+
+#### arrayElementMerge
+
+There are multiple ways to merge two ArrayElements, below are a few examples, but you can also create your own custom function.
+
+Your `arrayElementMerge` function will be called with three arguments: a `target` ArrayElement, the `source` ArrayElement,
+and an `options` object.
+
+```js
+import { deepmerge, ArrayElement } from '@swagger-api/apidom-core';
+
+const arrayElementMerge = (destination, source, options) => source;
+
+const target = new ArrayElement([1, 2, 3]);
+const source = new ArrayElement([3, 2, 1]);
+const output = deepmerge(target, source, { arrayElementMerge });
+// => ArrayElement([3, 2, 1]);
+```
+
+#### objectElementMerge
+
+There are multiple ways to merge two ObjectElements, below are a few examples, but you can also create your own custom function.
+
+Your `objectElementMerge` function will be called with three arguments: a `target` ObjectElement, the `source` ObjectElement,
+and an `options` object.
+
+```js
+import { deepmerge, ObjectElement } from '@swagger-api/apidom-core';
+
+const objectElementMerge = (destination, source, options) => source;
+
+const target = new ObjectElement({a: 1, b: 2});
+const source = new ObjectElement({c: 3, d: 4});
+const output = deepmerge(target ,source, { objectElementMerge });
+// => ObjectElement({c: 3, d: 4});
+```
+
+#### isMergeableElement
+
+By default, deepmerge clones every member from ObjectElement and ArrayElement.
+You may not want this, if your ObjectElements are of special types,
+and you want to copy the whole ObjectElement instead of just copying its member.
+
+You can accomplish this by passing in a function for the `isMergeableElement` option.
+
+```js
+import { deepmerge, ObjectElement, isObjectElement } from '@swagger-api/apidom-core';
+
+class CustomObjectElement extends ObjectElement {
+  element = 'custom';
+}
+const instantiatedCustomObjectElement = new CustomObjectElement({ special: 'oh yeah' });
+
+const target = new ObjectElement({
+  someProperty: {
+    cool: 'oh for sure',
+  },
+});
+const source = new ObjectElement({
+  someProperty: instantiatedCustomObjectElement,
+});
+const isMergeableElement = (element: Element) => isObjectElement(element) && !(element instanceof CustomObjectElement);
+
+const output = deepmerge(target, source, {
+  isMergeableElement,
+});
+// output.get('someProperty').get('cool'); // => undefined
+// output.get('someProperty').get('special'); // => 'oh yeah'
+// output.get('someProperty') instanceof CustomObjectElement // => true
+```
+
+#### customMerge
+
+Specifies a function which can be used to override the default merge behavior for a member, based on the key name.
+The `customMerge` function will be passed the key for each member, and should return the function which should
+be used to merge the values for that member.
+It may also return undefined, in which case the default merge behaviour will be used.
+
+```js
+import { deepmerge, ObjectElement } from '@swagger-api/apidom-core';
+
+const alex = new ObjectElement({
+	name: {
+		first: 'Alex',
+		last: 'Alexson'
+	},
+	pets: ['Cat', 'Parrot']
+});
+const tony = new ObjectElement({
+	name: {
+		first: 'Tony',
+		last: 'Tonison'
+	},
+	pets: ['Dog']
+});
+
+const mergeNames = (nameA: ObjectElement, nameB: ObjectElement) =>
+  new StringElement(`${toValue(nameA.get('first'))} and ${toValue(nameB.get('first'))}`);
+const customMerge = (key: Element) => (toValue(key) === 'name' ? mergeNames : undefined);
+
+const output = deepmerge(alex, tony, { customMerge });
+// output.get('name'); // => StrignElement('Alex and Tony')
+// output.get('pets'); // => ArrayElement(['Cat', 'Parrot', 'Dog'])
+```
+
+#### clone
+
+Defaults to `true`.
+
+If `clone` is false then child elements will be copied directly instead of being cloned.
+
+---
+
+## Refractors
+
+Refractor is a special layer inside the base namespace that can transform JavaScript structures
+into generic ApiDOM structures built from elements of this base namespace.
+
+**Refracting JavaScript structures**:
+
+```js
+import { ObjectElement } from '@swagger-api/apidom-core';
+
+const object = {
+    title: 'my title',
+    description: 'my description',
+    version: '0.1.0',
+};
+
+ObjectElement.refract(object); // => ObjectElement({ title, description, version })
+```
+
+```js
+import { CommentElement } from '@swagger-api/apidom-core';
+
+const comment = 'this is comment';
+
+CommentElement.refract(comment); // => CommentElement('this is comment')
+```
+
+### Refractor plugins
+
+Refractors can accept plugins as a second argument of refract static method.
+
+```js
+import { ObjectElement, StringElement } from '@swagger-api/apidom-core';
+
+const object = { a: 'b' };
+
+const plugin = ({ predicates, namespace }) => ({
+  name: 'plugin',
+  pre() {
+      console.dir('runs before traversal');
+  },
+  visitor: {
+    ObjectElement(objectElement) {
+      objectElement.getMember('a').value = new StringElement('c');
+    },
+  },
+  post() {
+      console.dir('runs after traversal');
+  },
+});
+
+ObjectElement.refract(object, { plugins: [plugin] }); // => ObjectElement({ a = 'c' })
+```
+You can define as many plugins as needed to enhance the resulting namespaced ApiDOM structure.
+If multiple plugins with the same visitor method are defined, they run in parallel (just like in Babel).
+
+#### Element identity plugin
+
+`apidom` package comes with `refractorPluginElementIdentity`. When used, this plugin will
+assign unique ID to all elements in ApiDOM tree.
+
+```js
+import { refractorPluginElementIdentity, ObjectElement } from '@swagger-api/apidom-core';
+
+const objectElement = ObjectElement.refract({ a: 'b' }, {
+  plugins: [
+    refractorPluginElementIdentity(),
+  ]
+});
+
+objectElement.id; // 8RaWF9
+objectElement.getMember('a').key.id; // NdHHV7
+objectElement.getMember('a').value.id; // rFGVFP
+```
+
+You can configure the plugin to generate unique IDs in the specific length:
+
+```js
+import { refractorPluginElementIdentity, ObjectElement } from '@swagger-api/apidom-core';
+
+const objectElement = ObjectElement.refract({ a: 'b' }, {
+  plugins: [
+    refractorPluginElementIdentity({ length: 36}),
+  ]
+});
+
+objectElement.id; // OnReGGrO7fMd9ztacvGfwGbOdGKuOFLiQQ1W
+objectElement.getMember('a').key.id; // BN6rHsmqI56SMQ1elshtbgRVECtEWNYS9lmd
+objectElement.getMember('a').value.id; // Ki4tWmf9xw9Lwb8MxkXJq1uONmJrmhXifmsI
+```
+
+#### Semantic element identity plugin
+
+`apidom` package comes with `refractorPluginSemanticElementIdentity`. When used, this plugin will
+assign unique ID to all non-primitive elements in ApiDOM tree. Primitive elements include
+`ObjectElement`, `ArrayElement`, `StringElement`, `BooleanElement`, `NullElement` and `NumberElement`.
+
+```js
+import { refractorPluginSemanticElementIdentity, ObjectElement } from '@swagger-api/apidom-core';
+import { InfoElement } from '@swagger-api/apidom-ns-openapi-3-1';
+
+const infoElement = InfoElement.refract({ title: 'title' });
+const objectElement = ObjectElement.refract({ a: 'b', info: infoElement }, {
+  plugins: [
+    refractorPluginSemanticElementIdentity(),
+  ]
+});
+
+objectElement.id; // ''
+objectElement.getMember('a').key.id; // ''
+objectElement.getMember('a').value.id; // ''
+objectElement.getMember('info').key.id; // ''
+objectElement.getMember('info').value.id; // '8RaWF9'
+```
+
+You can configure the plugin to generate unique IDs in the specific length:
+
+```js
+import { refractorPluginSemanticElementIdentity, ObjectElement } from '@swagger-api/apidom-core';
+import { InfoElement } from '@swagger-api/apidom-ns-openapi-3-1';
+
+const infoElement = InfoElement.refract({ title: 'title' });
+const objectElement = ObjectElement.refract({ a: 'b', info: infoElement }, {
+  plugins: [
+    refractorPluginSemanticElementIdentity({ length: 36 }),
+  ]
+});
+
+objectElement.id; // ''
+objectElement.getMember('a').key.id; // ''
+objectElement.getMember('a').value.id; // ''
+objectElement.getMember('info').key.id; // ''
+objectElement.getMember('info').value.id; // 'OnReGGrO7fMd9ztacvGfwGbOdGKuOFLiQQ1W'
+```
+
+---
+
+## Traversal
+
+`apidom` comes with its own traversal algorithm along with couple of convenient abstractions on top of it.
+
+### visit
+
+[visit](https://github.com/swagger-api/apidom/blob/main/packages/apidom-core/src/traversal/visitor.ts#L104-L103) will walk through an AST using a depth first traversal, calling
+the visitor's enter function at each node in the traversal, and calling the
+leave function after visiting that node and all of its child nodes.
+
+By returning different values from the enter and leave functions, the
+behavior of the visitor can be altered, including skipping over a sub-tree of
+the ApiDOM (by returning false), editing the ApiDOM by returning a value or null
+to remove the value, or to stop the whole traversal by returning [BREAK](https://github.com/swagger-api/apidom/blob/main/packages/apidom-core/src/index.ts#L52).
+
+When using `visit` to edit an ApiDOM, the original ApiDOM will not be modified, and
+a new version of the ApiDOM with the changes applied will be returned from the
+visit function.
+
+```js
+import { visit, ObjectElement, NumberElement } from '@swagger-api/apidom-core';
+
+const visitor = {
+    NumberElement(numberElement) {
+        return new NumberElement(2);
+    },
+};
+const element = new ObjectElement({ a: 1 });
+
+const newElement = visit(element, visitor); // => ObjectElement<{a: 2}>
+```
+
+This function originally comes from [@swagger-api/apidom-ast package](https://github.com/swagger-api/apidom/blob/main/packages/apidom-ast/src/visitor.ts)
+and is originally designed to work with [CST](https://en.wikipedia.org/wiki/Parse_tree). `apidom` package
+imports it, specializes it to work with ApiDOM and re-export it.
+
+All following algorithms are based on `visit` function.
+
+### filter
+
+Finds all elements matching the predicate.
+
+```js
+import { ObjectElement, filter, isNumberElement } from '@swagger-api/apidom-core'
+
+const objElement = new ObjectElement({ a: 'b', c: 2 });
+
+filter(isNumberElement, objElement); // => ArraySlice<[NumberElement<2>]>
+```
+
+### find
+
+Find first element that satisfies the provided predicate.
+
+```js
+import { ObjectElement, find, isMemberElement } from '@swagger-api/apidom-core'
+
+const objElement = new ObjectElement({ a: 'b', c: 2 });
+
+find(isNumberElement, objElement); // => NumberElement<2>
+```
+
+### findAtOffset
+
+ApiDOM nodes can be associated with source maps. This function finds the most inner node at the given offset.
+If includeRightBound is set, also finds nodes that end at the given offset.
+
+```js
+import { findAtOffset } from '@swagger-api/apidom-core'
+
+findAtOffset(3, elementWithSourceMaps); // => returns most inner node at offset 3
+```
+
+### reject
+
+Complement of [filter](#filter).
+
+```js
+import { ArrayElement, reject, isNumberElement } from '@swagger-api/apidom-core'
+
+const arrayElement = new ArrayElement([1, 'a']);
+
+reject(isNumberElement, arrayElement); // => ArraySlice<[StringElement<'a'>]>
+```
+
+### some
+
+Tests whether at least one element passes the predicate.
+
+```js
+import { ArrayElement, some, isNumberElement } from '@swagger-api/apidom-core'
+
+const arrayElement = new ArrayElement([1, 'a']);
+
+some(isNumberElement, arrayElement); // => true
+```
+
+### traverse
+
+Executes the callback on this element and all descendants.
+
+```js
+import { ArrayElement, traverse } from '@swagger-api/apidom-core'
+
+const arrayElement = new ArrayElement([1, 'a']);
+
+traverse(console.dir, arrayElement); // => prints ArrayElement, NumberElement, StringElement in this order
+```
+
+The execution of the callback can be controlled further by providing a predicate.
+
+```js
+import { ArrayElement, traverse, isNumberElement } from '@swagger-api/apidom-core'
+
+const arrayElement = new ArrayElement([1, 'a']);
+
+traverse({ callback: console.dir, predicate: isNumberElement }, arrayElement); // => prints NumberElement<1>
+```
+
+### parents
+
+Computes upwards edges from every child to its parent.
+
+```js
+import { ObjectElement, parents } from '@swagger-api/apidom-core';
+
+const objectElement = new ObjectElement({
+  a: [1, 2, { b: 'c', d: 'e' }],
+});
+
+const parentEdges = parents(objectElement); // => WeakMap<childElement, parentElement>
+```
+
+---
+
+## Transformers
+
+Following functions transforms ApiDOM between its various forms. All transformers (except `toValue`) can accept
+ApiDOM namespace instance as a second argument.
+
+### from
+
+Transforms data to an Element from a particular namespace.
+
+From a [refracted string](https://github.com/refractproject/refract-spec) form:
+
+```js
+import { from } from '@swagger-api/apidom-core';
+
+const refractedString = '{"element":"number","content":1}';
+
+from(refractedString); // => NumberElement<1>
+```
+
+From a [refracted](https://github.com/refractproject/refract-spec) form:
+
+```js
+import { from } from '@swagger-api/apidom-core';
+
+const refracted = { element: 'number', content: 1 };
+
+from(refracted); // => NumberElement<1>
+```
+
+From a JavaScript form:
+
+```js
+import { from } from '@swagger-api/apidom-core';
+
+const javascriptForm = 1;
+
+from(javascriptForm); // => NumberElement<1>
+```
+
+### toValue
+
+Transforms the ApiDOM into JavaScript POJO. This POJO would be the result of interpreting the ApiDOM
+into JavaScript structure. This function can handle cycles in ApiDOM structure.
+
+```js
+import { toValue, ObjectElement } from '@swagger-api/apidom-core';
+
+const objElement = new ObjectElement({ a: 'b' });
+
+toValue(objElement); // => { a: 'b' }
+```
+
+### toJSON
+
+Transforms the ApiDOM into JSON string.
+
+```js
+import { toJSON, ObjectElement } from '@swagger-api/apidom-core';
+
+const objElement = new ObjectElement({ a: 'b' });
+
+toJSON(objElement); // => '{"a":"b"}'
+```
+
+### toYAML
+
+Transforms the ApiDOM into JSON string.
+
+```js
+import { toYAML, ObjectElement } from '@swagger-api/apidom-core';
+
+const objElement = new ObjectElement({ a: 'b' });
+
+toYAML(objElement);
+/**
+ * %YAML 1.2
+ * ---
+ *
+ * "a": "b"
+ */
+```
+
+### dehydrate
+
+Creates a [refract representation](https://github.com/refractproject/refract-spec) of the an Element.
+
+```js
+import { dehyrate, NumberElement } from '@swagger-api/apidom-core';
+
+const numberElement = new NumberElement(1);
+
+dehyrate(numberElement); // => { element: 'number', content: 1 }
+```
+
+### toString
+
+Create a [refracted string](https://github.com/refractproject/refract-spec) representation of an Element.
+
+```js
+import { toString, NumberElement } from '@swagger-api/apidom-core';
+
+const numberElement = new NumberElement(1);
+
+toString(numberElement); // => '{"element":"number","content":1}'
+```