@speclynx/apidom-datamodel 1.12.2

package/src/primitives/CollectionElement.mjs

@@ -0,0 +1,187 @@
+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 element to the end of the collection.
+   */
+  push(value) {
+    this._content.push(this.refract(value));
+    return this;
+  }
+
+  /**
+   * Alias for push.
+   */
+  add(value) {
+    this.push(value);
+  }
+
+  /**
+   * 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.toValue() === id).first;
+  }
+
+  // Fantasy Land - Monoid
+
+  /**
+   * Returns an empty collection element.
+   */
+
+  'fantasy-land/empty'() {
+    return this.empty();
+  }
+
+  /**
+   * Concatenates two collection elements.
+   */
+  concat(other) {
+    const Ctor = this.constructor;
+    return new Ctor(this._content.concat(other._content));
+  }
+  'fantasy-land/concat'(other) {
+    return this.concat(other);
+  }
+
+  // Iterator support
+  [Symbol.iterator]() {
+    return this._content[Symbol.iterator]();
+  }
+}
+export default CollectionElement;

package/src/primitives/Element.cjs

@@ -0,0 +1,438 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _KeyValuePair = _interopRequireDefault(require("../KeyValuePair.cjs"));
+var _ObjectSlice = _interopRequireDefault(require("../ObjectSlice.cjs"));
+/**
+ * Valid content types for an Element.
+ * @public
+ */
+
+/**
+ * Base Element class that all ApiDOM elements extend.
+ *
+ * Elements are the core building blocks of ApiDOM. Each element has:
+ * - An `element` property identifying its type
+ * - Optional `content` holding the element's value
+ * - Optional `meta` for metadata (id, classes, title, description, links)
+ * - Optional `attributes` for element-specific properties
+ *
+ * @public
+ */
+class Element {
+  /**
+   * The element type identifier.
+   * @internal
+   */
+  _storedElement = 'element';
+
+  /**
+   * The element's content/value.
+   * @internal
+   */
+  _content;
+
+  /**
+   * Metadata about this element.
+   * @internal
+   */
+  _meta;
+
+  /**
+   * Element-specific attributes.
+   * @internal
+   */
+  _attributes;
+
+  /**
+   * Parent element reference (set when tree is frozen).
+   */
+  parent;
+
+  // ============================================================
+  // Prototype-assigned properties (set in elements.ts)
+  // Using 'declare' allows TypeScript to know about these
+  // without generating runtime code.
+  // ============================================================
+
+  /** @internal ObjectElement constructor for creating meta/attributes */
+
+  /** @internal ArrayElement constructor for creating arrays */
+
+  /** @internal MemberElement constructor for creating object members */
+
+  /** @internal RefElement constructor for creating references */
+
+  /** @internal Function to convert values to elements */
+
+  constructor(content, meta, attributes) {
+    if (meta !== undefined) {
+      this.meta = meta;
+    }
+    if (attributes !== undefined) {
+      this.attributes = attributes;
+    }
+    if (content !== undefined) {
+      this.content = content;
+    }
+  }
+
+  // ============================================================
+  // Core Properties
+  // ============================================================
+
+  /**
+   * The element type identifier (e.g., 'string', 'object', 'array').
+   */
+  get element() {
+    return this._storedElement;
+  }
+  set element(value) {
+    this._storedElement = value;
+  }
+
+  /**
+   * The element's content/value.
+   */
+  get content() {
+    return this._content;
+  }
+  set content(value) {
+    // Already an element
+    if (value instanceof Element) {
+      this._content = value;
+      return;
+    }
+
+    // Primitives (inlined for performance - avoids 8 function calls)
+    if (value === null || value === undefined || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint' || typeof value === 'symbol') {
+      this._content = value;
+      return;
+    }
+
+    // KeyValuePair
+    if (value instanceof _KeyValuePair.default) {
+      this._content = value;
+      return;
+    }
+
+    // ObjectSlice - extract elements array
+    if (value instanceof _ObjectSlice.default) {
+      this._content = value.elements;
+      return;
+    }
+
+    // Array - refract each item
+    if (Array.isArray(value)) {
+      this._content = value.map(item => this.refract(item));
+      return;
+    }
+
+    // Plain object - convert to MemberElements
+    if (typeof value === 'object') {
+      this._content = Object.entries(value).map(([key, val]) => new this.MemberElement(key, val));
+      return;
+    }
+    throw new Error(`Cannot set content to value of type ${typeof value}`);
+  }
+
+  /**
+   * Metadata about this element (id, classes, title, description, links).
+   * Lazily creates an ObjectElement if not set.
+   */
+  get meta() {
+    if (!this._meta) {
+      if (this.isFrozen) {
+        const meta = new this.ObjectElement();
+        meta.freeze();
+        return meta;
+      }
+      this._meta = new this.ObjectElement();
+    }
+    return this._meta;
+  }
+  set meta(value) {
+    if (value instanceof Element) {
+      this._meta = value;
+    } else {
+      this.meta.set(value ?? {});
+    }
+  }
+
+  /**
+   * Element-specific attributes.
+   * Lazily creates an ObjectElement if not set.
+   */
+  get attributes() {
+    if (!this._attributes) {
+      if (this.isFrozen) {
+        const attributes = new this.ObjectElement();
+        attributes.freeze();
+        return attributes;
+      }
+      this._attributes = new this.ObjectElement();
+    }
+    return this._attributes;
+  }
+  set attributes(value) {
+    if (value instanceof Element) {
+      this._attributes = value;
+    } else {
+      this.attributes.set(value ?? {});
+    }
+  }
+
+  // ============================================================
+  // Meta Property Shortcuts
+  // ============================================================
+
+  /** Unique identifier for this element. */
+  get id() {
+    return this.getMetaProperty('id', '');
+  }
+  set id(value) {
+    this.setMetaProperty('id', value);
+  }
+
+  /** CSS-like class names. */
+  get classes() {
+    return this.getMetaProperty('classes', []);
+  }
+  set classes(value) {
+    this.setMetaProperty('classes', value);
+  }
+
+  /** Human-readable title. */
+  get title() {
+    return this.getMetaProperty('title', '');
+  }
+  set title(value) {
+    this.setMetaProperty('title', value);
+  }
+
+  /** Human-readable description. */
+  get description() {
+    return this.getMetaProperty('description', '');
+  }
+  set description(value) {
+    this.setMetaProperty('description', value);
+  }
+
+  /** Hyperlinks associated with this element. */
+  get links() {
+    return this.getMetaProperty('links', []);
+  }
+  set links(value) {
+    this.setMetaProperty('links', value);
+  }
+
+  // ============================================================
+  // Tree Navigation
+  // ============================================================
+
+  /** Returns direct children of this element. */
+  get children() {
+    const {
+      _content: content
+    } = this;
+    if (Array.isArray(content)) {
+      return content;
+    }
+    if (content instanceof _KeyValuePair.default) {
+      const children = [];
+      if (content.key) children.push(content.key);
+      if (content.value) children.push(content.value);
+      return children;
+    }
+    if (content instanceof Element) {
+      return [content];
+    }
+    return [];
+  }
+
+  // ============================================================
+  // Freezable Implementation
+  // ============================================================
+
+  /** Whether this element is frozen (immutable). */
+  get isFrozen() {
+    return Object.isFrozen(this);
+  }
+
+  /**
+   * Freezes the element tree, making it immutable.
+   * Sets up parent references for tree traversal.
+   */
+  freeze() {
+    if (this.isFrozen) return;
+
+    // Freeze meta and attributes
+    if (this._meta) {
+      this._meta.parent = this;
+      this._meta.freeze();
+    }
+    if (this._attributes) {
+      this._attributes.parent = this;
+      this._attributes.freeze();
+    }
+
+    // Freeze children
+    for (const child of this.children) {
+      child.parent = this;
+      child.freeze();
+    }
+
+    // Freeze content array if applicable
+    if (Array.isArray(this._content)) {
+      Object.freeze(this._content);
+    }
+    Object.freeze(this);
+  }
+
+  // ============================================================
+  // Cloneable Implementation
+  // ============================================================
+
+  /**
+   * Creates a deep clone of this element.
+   */
+  clone() {
+    const Ctor = this.constructor;
+    const copy = new Ctor();
+    copy.element = this.element;
+    if (this._meta) {
+      copy._meta = this._meta.clone();
+    }
+    if (this._attributes) {
+      copy._attributes = this._attributes.clone();
+    }
+
+    // Clone content based on its type
+    const {
+      _content
+    } = this;
+    if (_content instanceof Element) {
+      copy._content = _content.clone();
+    } else if (_content instanceof _KeyValuePair.default) {
+      copy._content = _content.clone();
+    } else if (Array.isArray(_content)) {
+      copy._content = _content.map(el => el.clone());
+    } else {
+      // Primitives are immutable, assign as-is
+      copy._content = _content;
+    }
+    return copy;
+  }
+
+  // ============================================================
+  // ToValue Implementation
+  // ============================================================
+
+  /**
+   * Converts the element to its JavaScript value representation.
+   */
+  toValue() {
+    const {
+      _content
+    } = this;
+    if (_content instanceof Element) {
+      return _content.toValue();
+    }
+    if (_content instanceof _KeyValuePair.default) {
+      return _content.toValue();
+    }
+    if (Array.isArray(_content)) {
+      return _content.map(el => el.toValue());
+    }
+    return _content;
+  }
+
+  // ============================================================
+  // Equatable Implementation
+  // ============================================================
+
+  /**
+   * Checks deep equality with another value.
+   */
+  equals(value) {
+    return (0, _ramda.equals)(this.toValue(), value);
+  }
+
+  // ============================================================
+  // Element Type
+  // ============================================================
+
+  /**
+   * Returns the primitive type name for this element.
+   * Override in subclasses (e.g., 'string', 'number', 'array').
+   */
+  primitive() {
+    return undefined;
+  }
+
+  // ============================================================
+  // Content Operations
+  // ============================================================
+
+  /**
+   * Sets the content of this element.
+   * @returns this for chaining
+   */
+  set(content) {
+    this.content = content;
+    return this;
+  }
+
+  // ============================================================
+  // Reference Creation
+  // ============================================================
+
+  /**
+   * Creates a RefElement pointing to this element.
+   * @param path - Optional path within the referenced element
+   * @throws Error if this element has no ID
+   */
+  toRef(path) {
+    const idValue = this.id.toValue();
+    if (idValue === '') {
+      throw new Error('Cannot create reference to an element without an ID');
+    }
+    const ref = new this.RefElement(idValue);
+    if (typeof path === 'string') {
+      ref.path = this.refract(path);
+    }
+    return ref;
+  }
+
+  // ============================================================
+  // Protected Helpers
+  // ============================================================
+
+  /**
+   * Gets a meta property, creating it with default value if not present.
+   */
+  getMetaProperty(name, defaultValue) {
+    if (!this.meta.hasKey(name)) {
+      if (this.isFrozen) {
+        const element = this.refract(defaultValue);
+        element.freeze();
+        return element;
+      }
+      this.meta.set(name, defaultValue);
+    }
+    return this.meta.get(name);
+  }
+
+  /**
+   * Sets a meta property.
+   */
+  setMetaProperty(name, value) {
+    this.meta.set(name, value);
+  }
+}
+
+// Re-export types for convenience
+var _default = exports.default = Element;