@speclynx/apidom-datamodel 4.0.1 → 4.0.3

package/src/primitives/ArrayElement.mjs

@@ -0,0 +1,148 @@
+import CollectionElement from "./CollectionElement.mjs"; // Re-export types from CollectionElement
+/**
+ * ArrayElement represents an array/collection of elements in ApiDOM.
+ *
+ * @typeParam T - The element type contained in the array, defaults to Element
+ * @public
+ */
+class ArrayElement extends CollectionElement {
+  constructor(content, meta, attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'array';
+  }
+  primitive() {
+    return 'array';
+  }
+
+  /**
+   * Gets the element at the specified index.
+   */
+  get(index) {
+    return this._content[index];
+  }
+
+  /**
+   * Helper for returning the value of an item.
+   */
+  getValue(index) {
+    const item = this.get(index);
+    if (item) {
+      return item.toValue();
+    }
+    return undefined;
+  }
+
+  /**
+   * Sets the element at the specified index, or sets the content if called with one argument.
+   */
+  set(indexOrContent, value) {
+    if (typeof indexOrContent === 'number' && value !== undefined) {
+      this._content[indexOrContent] = this.refract(value);
+    } else {
+      // Delegate to parent set behavior
+      this.content = indexOrContent;
+    }
+    return this;
+  }
+
+  /**
+   * Removes the element at the specified index.
+   */
+  remove(index) {
+    return this._content.splice(index, 1)[0] ?? null;
+  }
+
+  /**
+   * Maps each element using the provided callback function.
+   */
+  map(callback, thisArg) {
+    return this._content.map(callback, thisArg);
+  }
+
+  /**
+   * Maps and then flattens the results.
+   */
+  flatMap(callback, thisArg) {
+    return this._content.flatMap(callback, thisArg);
+  }
+
+  /**
+   * Returns an array containing the truthy results of calling the given transformation.
+   */
+  compactMap(transform, thisArg) {
+    const results = [];
+    for (const element of this._content) {
+      const result = transform.call(thisArg, element);
+      if (result) {
+        results.push(result);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Filters elements using the provided callback.
+   */
+  filter(callback, thisArg) {
+    const filtered = this._content.filter(callback, thisArg);
+    return new this.constructor(filtered);
+  }
+
+  /**
+   * Rejects elements that match the provided callback.
+   */
+  reject(callback, thisArg) {
+    const results = [];
+    for (const element of this._content) {
+      if (!callback.call(thisArg, element)) {
+        results.push(element);
+      }
+    }
+    return new this.constructor(results);
+  }
+
+  /**
+   * Reduces the array to a single value.
+   * This is a reduce function specifically for datamodel arrays and objects.
+   * It allows for returning normal values or datamodel instances.
+   */
+  reduce(callback, initialValue) {
+    let startIndex;
+    let memo;
+
+    // Allows for defining a starting value of the reduce
+    if (initialValue !== undefined) {
+      startIndex = 0;
+      memo = this.refract(initialValue);
+    } else {
+      startIndex = 1;
+      memo = this.first;
+    }
+
+    // Sending each function call to the registry allows for passing datamodel
+    // instances through the function return.
+    for (let i = startIndex; i < this.length; i += 1) {
+      const item = this._content[i];
+      const result = callback(memo, item, i, this);
+      memo = result === undefined ? result : this.refract(result);
+    }
+    return memo;
+  }
+
+  /**
+   * Executes a provided function once for each element.
+   */
+  forEach(callback, thisArg) {
+    this._content.forEach((item, index) => {
+      callback.call(thisArg, item, index);
+    });
+  }
+
+  /**
+   * Returns an empty array element.
+   */
+  empty() {
+    return new this.constructor([]);
+  }
+}
+export default ArrayElement;

package/src/primitives/ArrayElement.ts

@@ -0,0 +1,161 @@
+import CollectionElement from './CollectionElement.ts';
+import type Element from './Element.ts';
+import type { Meta, Attributes } from './Element.ts';
+
+// Re-export types from CollectionElement
+export type { FindCondition, FindOptions } from './CollectionElement.ts';
+
+/**
+ * ArrayElement represents an array/collection of elements in ApiDOM.
+ *
+ * @typeParam T - The element type contained in the array, defaults to Element
+ * @public
+ */
+class ArrayElement<T extends Element = Element> extends CollectionElement<T> {
+  constructor(content?: unknown[], meta?: Meta, attributes?: Attributes) {
+    super(content || [], meta, attributes);
+    this.element = 'array';
+  }
+
+  primitive(): string {
+    return 'array';
+  }
+
+  /**
+   * Gets the element at the specified index.
+   */
+  get(index: number): T | undefined {
+    return this._content[index];
+  }
+
+  /**
+   * Helper for returning the value of an item.
+   */
+  getValue(index: number): unknown {
+    const item = this.get(index);
+
+    if (item) {
+      return item.toValue();
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Sets the element at the specified index, or sets the content if called with one argument.
+   */
+  set(indexOrContent: number | unknown, value?: unknown): this {
+    if (typeof indexOrContent === 'number' && value !== undefined) {
+      this._content[indexOrContent] = this.refract(value) as T;
+    } else {
+      // Delegate to parent set behavior
+      this.content = indexOrContent;
+    }
+    return this;
+  }
+
+  /**
+   * Removes the element at the specified index.
+   */
+  remove(index: number): T | null {
+    return this._content.splice(index, 1)[0] ?? null;
+  }
+
+  /**
+   * Maps each element using the provided callback function.
+   */
+  map<U>(callback: (element: T, index: number, array: T[]) => U, thisArg?: unknown): U[] {
+    return this._content.map(callback, thisArg);
+  }
+
+  /**
+   * Maps and then flattens the results.
+   */
+  flatMap<U>(callback: (element: T, index: number, array: T[]) => U | U[], thisArg?: unknown): U[] {
+    return this._content.flatMap(callback, thisArg);
+  }
+
+  /**
+   * Returns an array containing the truthy results of calling the given transformation.
+   */
+  compactMap<U>(transform: (element: T) => U | undefined | null, thisArg?: unknown): U[] {
+    const results: U[] = [];
+
+    for (const element of this._content) {
+      const result = transform.call(thisArg, element);
+      if (result) {
+        results.push(result);
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Filters elements using the provided callback.
+   */
+  filter(callback: (element: T) => boolean, thisArg?: unknown): ArrayElement<T> {
+    const filtered = this._content.filter(callback, thisArg);
+    return new (this.constructor as new (content: T[]) => ArrayElement<T>)(filtered);
+  }
+
+  /**
+   * Rejects elements that match the provided callback.
+   */
+  reject(callback: (element: T) => boolean, thisArg?: unknown): ArrayElement<T> {
+    const results: T[] = [];
+    for (const element of this._content) {
+      if (!callback.call(thisArg, element)) {
+        results.push(element);
+      }
+    }
+    return new (this.constructor as new (content: T[]) => ArrayElement<T>)(results);
+  }
+
+  /**
+   * Reduces the array to a single value.
+   * This is a reduce function specifically for datamodel arrays and objects.
+   * It allows for returning normal values or datamodel instances.
+   */
+  reduce<U>(callback: (memo: U, item: T, index: number, arr: this) => U, initialValue?: U): U {
+    let startIndex: number;
+    let memo: U;
+
+    // Allows for defining a starting value of the reduce
+    if (initialValue !== undefined) {
+      startIndex = 0;
+      memo = this.refract(initialValue) as unknown as U;
+    } else {
+      startIndex = 1;
+      memo = this.first as unknown as U;
+    }
+
+    // Sending each function call to the registry allows for passing datamodel
+    // instances through the function return.
+    for (let i = startIndex; i < this.length; i += 1) {
+      const item = this._content[i];
+      const result = callback(memo, item, i, this);
+      memo = result === undefined ? result : (this.refract(result) as unknown as U);
+    }
+
+    return memo;
+  }
+
+  /**
+   * Executes a provided function once for each element.
+   */
+  forEach(callback: (element: T, index: number) => void, thisArg?: unknown): void {
+    this._content.forEach((item, index) => {
+      callback.call(thisArg, item, index);
+    });
+  }
+
+  /**
+   * Returns an empty array element.
+   */
+  empty(): this {
+    return new (this.constructor as new (content: unknown[]) => this)([]);
+  }
+}
+
+export default ArrayElement;

package/src/primitives/BooleanElement.cjs

@@ -0,0 +1,20 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _Element = _interopRequireDefault(require("./Element.cjs"));
+/**
+ * BooleanElement represents a boolean value in ApiDOM.
+ * @public
+ */
+class BooleanElement extends _Element.default {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = 'boolean';
+  }
+  primitive() {
+    return 'boolean';
+  }
+}
+var _default = exports.default = BooleanElement;

package/src/primitives/BooleanElement.mjs

@@ -0,0 +1,15 @@
+import Element from "./Element.mjs";
+/**
+ * BooleanElement represents a boolean value in ApiDOM.
+ * @public
+ */
+class BooleanElement extends Element {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = 'boolean';
+  }
+  primitive() {
+    return 'boolean';
+  }
+}
+export default BooleanElement;

package/src/primitives/BooleanElement.ts

@@ -0,0 +1,18 @@
+import Element, { type Meta, type Attributes } from './Element.ts';
+
+/**
+ * BooleanElement represents a boolean value in ApiDOM.
+ * @public
+ */
+class BooleanElement extends Element {
+  constructor(content?: boolean, meta?: Meta, attributes?: Attributes) {
+    super(content, meta, attributes);
+    this.element = 'boolean';
+  }
+
+  primitive(): string {
+    return 'boolean';
+  }
+}
+
+export default BooleanElement;

package/src/primitives/CollectionElement.cjs

@@ -0,0 +1,180 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _Element = _interopRequireDefault(require("./Element.cjs"));
+/**
+ * Condition function for finding elements.
+ * @public
+ */
+
+/**
+ * Options for finding elements.
+ * @public
+ */
+
+/**
+ * CollectionElement is an abstract base class for collection-like elements.
+ * Both ArrayElement and ObjectElement extend this class.
+ *
+ * This class contains the shared functionality between arrays and objects,
+ * while keeping the conflicting methods (get, set, remove, map, filter, etc.)
+ * in the respective subclasses.
+ *
+ * @remarks
+ * This is primarily an implementation detail. Use ArrayElement or ObjectElement directly.
+ *
+ * @typeParam T - The element type contained in the collection, defaults to Element
+ * @public
+ */
+class CollectionElement extends _Element.default {
+  constructor(content, meta, attributes) {
+    super(content || [], meta, attributes);
+  }
+
+  /**
+   * Returns the length of the collection.
+   */
+  get length() {
+    return this._content.length;
+  }
+
+  /**
+   * Returns whether the collection is empty.
+   */
+  get isEmpty() {
+    return this.length === 0;
+  }
+
+  /**
+   * Return the first item in the collection.
+   */
+  get first() {
+    return this._content[0];
+  }
+
+  /**
+   * Return the second item in the collection.
+   */
+  get second() {
+    return this._content[1];
+  }
+
+  /**
+   * Return the last item in the collection.
+   */
+  get last() {
+    return this._content.at(-1);
+  }
+
+  /**
+   * Adds the given elements to the end of the collection.
+   */
+  push(...values) {
+    for (const value of values) {
+      this._content.push(this.refract(value));
+    }
+    return this;
+  }
+
+  /**
+   * Removes the first element from the collection.
+   */
+  shift() {
+    return this._content.shift();
+  }
+
+  /**
+   * Adds the given element to the beginning of the collection.
+   */
+  unshift(value) {
+    this._content.unshift(this.refract(value));
+  }
+
+  /**
+   * Looks for matching children using deep equality.
+   */
+  includes(value) {
+    return this._content.some(element => element.equals(value));
+  }
+
+  /**
+   * Recursively search all descendants using a condition function.
+   */
+  findElements(condition, givenOptions) {
+    const options = givenOptions || {};
+    const recursive = !!options.recursive;
+    const results = options.results === undefined ? [] : options.results;
+    for (let i = 0; i < this._content.length; i += 1) {
+      const item = this._content[i];
+
+      // We use duck-typing here to support any registered class that
+      // may contain other elements.
+
+      const itemWithFindElements = item;
+      if (recursive && typeof itemWithFindElements.findElements === 'function') {
+        itemWithFindElements.findElements(condition, {
+          results,
+          recursive
+        });
+      }
+      if (condition(item, i, undefined)) {
+        results.push(item);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Recursively search all descendants using a condition function.
+   */
+  find(condition) {
+    const results = this.findElements(condition, {
+      recursive: true
+    });
+    return new this.ArrayElement(results);
+  }
+
+  /**
+   * Find elements by their element type name.
+   */
+  findByElement(element) {
+    return this.find(item => item.element === element);
+  }
+
+  /**
+   * Find elements by class name.
+   */
+  findByClass(className) {
+    return this.find(item => {
+      const classes = item.classes;
+      return typeof classes.includes === 'function' && classes.includes(className);
+    });
+  }
+
+  /**
+   * Search the tree recursively and find the element with the matching ID.
+   */
+  getById(id) {
+    return this.find(item => item.id === id).first;
+  }
+
+  /**
+   * Returns an empty collection element.
+   */
+
+  /**
+   * Concatenates two collection elements.
+   */
+  concat(other) {
+    const Ctor = this.constructor;
+    return new Ctor(this._content.concat(other._content));
+  }
+
+  // Iterator support
+  [Symbol.iterator]() {
+    return this._content[Symbol.iterator]();
+  }
+}
+var _default = exports.default = CollectionElement;

package/src/primitives/CollectionElement.mjs

@@ -0,0 +1,173 @@
+import Element from "./Element.mjs";
+/**
+ * Condition function for finding elements.
+ * @public
+ */
+/**
+ * Options for finding elements.
+ * @public
+ */
+/**
+ * CollectionElement is an abstract base class for collection-like elements.
+ * Both ArrayElement and ObjectElement extend this class.
+ *
+ * This class contains the shared functionality between arrays and objects,
+ * while keeping the conflicting methods (get, set, remove, map, filter, etc.)
+ * in the respective subclasses.
+ *
+ * @remarks
+ * This is primarily an implementation detail. Use ArrayElement or ObjectElement directly.
+ *
+ * @typeParam T - The element type contained in the collection, defaults to Element
+ * @public
+ */
+class CollectionElement extends Element {
+  constructor(content, meta, attributes) {
+    super(content || [], meta, attributes);
+  }
+
+  /**
+   * Returns the length of the collection.
+   */
+  get length() {
+    return this._content.length;
+  }
+
+  /**
+   * Returns whether the collection is empty.
+   */
+  get isEmpty() {
+    return this.length === 0;
+  }
+
+  /**
+   * Return the first item in the collection.
+   */
+  get first() {
+    return this._content[0];
+  }
+
+  /**
+   * Return the second item in the collection.
+   */
+  get second() {
+    return this._content[1];
+  }
+
+  /**
+   * Return the last item in the collection.
+   */
+  get last() {
+    return this._content.at(-1);
+  }
+
+  /**
+   * Adds the given elements to the end of the collection.
+   */
+  push(...values) {
+    for (const value of values) {
+      this._content.push(this.refract(value));
+    }
+    return this;
+  }
+
+  /**
+   * Removes the first element from the collection.
+   */
+  shift() {
+    return this._content.shift();
+  }
+
+  /**
+   * Adds the given element to the beginning of the collection.
+   */
+  unshift(value) {
+    this._content.unshift(this.refract(value));
+  }
+
+  /**
+   * Looks for matching children using deep equality.
+   */
+  includes(value) {
+    return this._content.some(element => element.equals(value));
+  }
+
+  /**
+   * Recursively search all descendants using a condition function.
+   */
+  findElements(condition, givenOptions) {
+    const options = givenOptions || {};
+    const recursive = !!options.recursive;
+    const results = options.results === undefined ? [] : options.results;
+    for (let i = 0; i < this._content.length; i += 1) {
+      const item = this._content[i];
+
+      // We use duck-typing here to support any registered class that
+      // may contain other elements.
+
+      const itemWithFindElements = item;
+      if (recursive && typeof itemWithFindElements.findElements === 'function') {
+        itemWithFindElements.findElements(condition, {
+          results,
+          recursive
+        });
+      }
+      if (condition(item, i, undefined)) {
+        results.push(item);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Recursively search all descendants using a condition function.
+   */
+  find(condition) {
+    const results = this.findElements(condition, {
+      recursive: true
+    });
+    return new this.ArrayElement(results);
+  }
+
+  /**
+   * Find elements by their element type name.
+   */
+  findByElement(element) {
+    return this.find(item => item.element === element);
+  }
+
+  /**
+   * Find elements by class name.
+   */
+  findByClass(className) {
+    return this.find(item => {
+      const classes = item.classes;
+      return typeof classes.includes === 'function' && classes.includes(className);
+    });
+  }
+
+  /**
+   * Search the tree recursively and find the element with the matching ID.
+   */
+  getById(id) {
+    return this.find(item => item.id === id).first;
+  }
+
+  /**
+   * Returns an empty collection element.
+   */
+
+  /**
+   * Concatenates two collection elements.
+   */
+  concat(other) {
+    const Ctor = this.constructor;
+    return new Ctor(this._content.concat(other._content));
+  }
+
+  // Iterator support
+  [Symbol.iterator]() {
+    return this._content[Symbol.iterator]();
+  }
+}
+export default CollectionElement;