@speclynx/apidom-datamodel 3.2.1 → 4.0.1

package/src/primitives/Element.mjs

@@ -1,505 +0,0 @@
-import { equals } from 'ramda';
-import Metadata from "../Metadata.mjs";
-import KeyValuePair from "../KeyValuePair.mjs";
-import ObjectSlice from "../ObjectSlice.mjs"; // shared singleton for frozen elements with no meta — avoids allocation on every access
-const FROZEN_EMPTY_METADATA = Object.freeze(new Metadata());
-
-/**
- * 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 {
-  // ============================================================
-  // Public Properties
-  // ============================================================
-
-  /**
-   * Parent element reference (set when tree is frozen).
-   */
-  parent;
-
-  /**
-   * Format-specific style information for round-trip preservation.
-   * Each format owns its own namespace (e.g., `yaml`, `json`).
-   */
-  style;
-
-  // ============================================================================
-  // Source Position (LSP-compatible, TextDocument-compatible, UTF-16 code units)
-  // web-tree-sitter automatically provides position data in UTF-16 code units.
-  // ============================================================================
-
-  /**
-   * Starting line number (0-based).
-   * Compatible with LSP Position.line.
-   */
-  startLine;
-
-  /**
-   * Starting character offset within the line (0-based, UTF-16 code units).
-   * Compatible with LSP Position.character.
-   */
-  startCharacter;
-
-  /**
-   * Starting offset from beginning of document (UTF-16 code units).
-   * Can be used directly as JavaScript string index.
-   */
-  startOffset;
-
-  /**
-   * Ending line number (0-based).
-   * Compatible with LSP Position.line.
-   */
-  endLine;
-
-  /**
-   * Ending character offset within the line (0-based, UTF-16 code units).
-   * Compatible with LSP Position.character.
-   */
-  endCharacter;
-
-  /**
-   * Ending offset from beginning of document (UTF-16 code units).
-   * Can be used directly as JavaScript string index.
-   */
-  endOffset;
-
-  // ============================================================
-  // Protected Properties
-  // ============================================================
-
-  /**
-   * 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;
-
-  // ============================================================
-  // Prototype-assigned properties (set in registration.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) {
-      this._content = value;
-      return;
-    }
-
-    // ObjectSlice - extract elements array
-    if (value instanceof ObjectSlice) {
-      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 a Metadata instance if not set.
-   */
-  get meta() {
-    if (!this._meta) {
-      if (this.isFrozen) return FROZEN_EMPTY_METADATA;
-      this._meta = new Metadata();
-    }
-    return this._meta;
-  }
-  set meta(value) {
-    if (value instanceof Metadata) {
-      this._meta = value;
-    } else if (value && typeof value === 'object') {
-      const meta = new Metadata();
-      Object.assign(meta, value);
-      this._meta = meta;
-    }
-  }
-
-  /**
-   * 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() {
-    if (!this.hasMetaProperty('id')) {
-      if (this.isFrozen) return '';
-      this.setMetaProperty('id', '');
-    }
-    return this.meta.get('id');
-  }
-  set id(value) {
-    this.setMetaProperty('id', value);
-  }
-
-  /** CSS-like class names. */
-  get classes() {
-    if (!this.hasMetaProperty('classes')) {
-      if (this.isFrozen) return [];
-      this.setMetaProperty('classes', []);
-    }
-    return this.meta.get('classes');
-  }
-  set classes(value) {
-    this.setMetaProperty('classes', value);
-  }
-
-  /** Hyperlinks associated with this element. */
-  get links() {
-    if (!this.hasMetaProperty('links')) {
-      if (this.isFrozen) {
-        const empty = new this.ArrayElement();
-        empty.freeze();
-        return empty;
-      }
-      this.setMetaProperty('links', new this.ArrayElement());
-    }
-    return this.meta.get('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) {
-      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.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);
-  }
-
-  // ============================================================
-  // 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) {
-      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) {
-    const compareTo = value instanceof Element ? value.toValue() : value;
-    return equals(this.toValue(), compareTo);
-  }
-
-  // ============================================================
-  // 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;
-    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;
-  }
-
-  /**
-   * Gets a meta property value.
-   *
-   * When the property doesn't exist:
-   * - With defaultValue: returns the provided default value
-   * - Without defaultValue: returns undefined
-   */
-
-  getMetaProperty(name, defaultValue) {
-    if (!this.hasMetaProperty(name)) {
-      return defaultValue;
-    }
-    return this.meta.get(name);
-  }
-
-  /**
-   * Sets a meta property.
-   */
-  setMetaProperty(name, value) {
-    this.meta.set(name, value);
-  }
-
-  /**
-   * Checks whether a meta property exists.
-   */
-  hasMetaProperty(name) {
-    return this._meta !== undefined && this._meta.hasKey(name);
-  }
-
-  /**
-   * Checks if meta is empty.
-   */
-  get isMetaEmpty() {
-    return this._meta === undefined || this._meta.isEmpty;
-  }
-
-  /**
-   * Gets an attribute property, creating it with default value if not present.
-   */
-  getAttributesProperty(name, defaultValue) {
-    if (!this.hasAttributesProperty(name)) {
-      if (this.isFrozen) {
-        const element = this.refract(defaultValue);
-        element.freeze();
-        return element;
-      }
-      this.attributes.set(name, defaultValue);
-    }
-    return this.attributes.get(name);
-  }
-
-  /**
-   * Sets an attributes property.
-   */
-  setAttributesProperty(name, value) {
-    this.attributes.set(name, value);
-  }
-
-  /**
-   * Checks whether an attributes property exists.
-   */
-  hasAttributesProperty(name) {
-    if (!this.isAttributesEmpty) {
-      return this.attributes.hasKey(name);
-    }
-    return false;
-  }
-
-  /**
-   * Checks if attributes is empty.
-   */
-  get isAttributesEmpty() {
-    return this._attributes === undefined || this.attributes.isEmpty;
-  }
-}
-
-// Re-export types for convenience
-
-export { Metadata };
-export default Element;

package/src/primitives/MemberElement.cjs

@@ -1,58 +0,0 @@
-"use strict";
-
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
-exports.default = void 0;
-var _KeyValuePair = _interopRequireDefault(require("../KeyValuePair.cjs"));
-var _Element = _interopRequireDefault(require("./Element.cjs"));
-/**
- * MemberElement represents a key-value pair member in an ObjectElement.
- *
- * The member's content is always a KeyValuePair containing:
- * - `key`: The key element (typically a StringElement)
- * - `value`: The value element (any Element type)
- *
- * @typeParam K - The key element type, defaults to Element
- * @typeParam V - The value element type, defaults to Element
- * @public
- */
-class MemberElement extends _Element.default {
-  constructor(key, value, meta, attributes) {
-    super(new _KeyValuePair.default(), meta, attributes);
-    this.element = 'member';
-    if (key !== undefined) {
-      this.key = key;
-    }
-
-    // Note: We check arguments.length to distinguish between:
-    // - new MemberElement('key') - value not provided, don't set
-    // - new MemberElement('key', undefined) - value explicitly undefined, set it
-    if (arguments.length >= 2) {
-      this.value = value;
-    }
-  }
-  primitive() {
-    return 'member';
-  }
-
-  /**
-   * The key element of this member.
-   */
-  get key() {
-    return this._content.key;
-  }
-  set key(value) {
-    this._content.key = this.refract(value);
-  }
-
-  /**
-   * The value element of this member.
-   */
-  get value() {
-    return this._content.value;
-  }
-  set value(value) {
-    this._content.value = value === undefined ? undefined : this.refract(value);
-  }
-}
-var _default = exports.default = MemberElement;

package/src/primitives/MemberElement.mjs

@@ -1,53 +0,0 @@
-import KeyValuePair from "../KeyValuePair.mjs";
-import Element from "./Element.mjs";
-/**
- * MemberElement represents a key-value pair member in an ObjectElement.
- *
- * The member's content is always a KeyValuePair containing:
- * - `key`: The key element (typically a StringElement)
- * - `value`: The value element (any Element type)
- *
- * @typeParam K - The key element type, defaults to Element
- * @typeParam V - The value element type, defaults to Element
- * @public
- */
-class MemberElement extends Element {
-  constructor(key, value, meta, attributes) {
-    super(new KeyValuePair(), meta, attributes);
-    this.element = 'member';
-    if (key !== undefined) {
-      this.key = key;
-    }
-
-    // Note: We check arguments.length to distinguish between:
-    // - new MemberElement('key') - value not provided, don't set
-    // - new MemberElement('key', undefined) - value explicitly undefined, set it
-    if (arguments.length >= 2) {
-      this.value = value;
-    }
-  }
-  primitive() {
-    return 'member';
-  }
-
-  /**
-   * The key element of this member.
-   */
-  get key() {
-    return this._content.key;
-  }
-  set key(value) {
-    this._content.key = this.refract(value);
-  }
-
-  /**
-   * The value element of this member.
-   */
-  get value() {
-    return this._content.value;
-  }
-  set value(value) {
-    this._content.value = value === undefined ? undefined : this.refract(value);
-  }
-}
-export default MemberElement;

package/src/primitives/NullElement.cjs

@@ -1,28 +0,0 @@
-"use strict";
-
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-exports.__esModule = true;
-exports.default = void 0;
-var _Element = _interopRequireDefault(require("./Element.cjs"));
-/**
- * NullElement represents a null value in ApiDOM.
- * @public
- */
-class NullElement extends _Element.default {
-  constructor(content, meta, attributes) {
-    super(content ?? null, meta, attributes);
-    this.element = 'null';
-  }
-  primitive() {
-    return 'null';
-  }
-
-  /**
-   * NullElement cannot have its value changed.
-   * @throws Error - NullElement value cannot be modified
-   */
-  set(_content) {
-    throw new Error('Cannot set the value of null');
-  }
-}
-var _default = exports.default = NullElement;

package/src/primitives/NullElement.mjs

@@ -1,23 +0,0 @@
-import Element from "./Element.mjs";
-/**
- * NullElement represents a null value in ApiDOM.
- * @public
- */
-class NullElement extends Element {
-  constructor(content, meta, attributes) {
-    super(content ?? null, meta, attributes);
-    this.element = 'null';
-  }
-  primitive() {
-    return 'null';
-  }
-
-  /**
-   * NullElement cannot have its value changed.
-   * @throws Error - NullElement value cannot be modified
-   */
-  set(_content) {
-    throw new Error('Cannot set the value of null');
-  }
-}
-export default NullElement;

package/src/primitives/NumberElement.cjs

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

package/src/primitives/NumberElement.mjs

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