@speclynx/apidom-datamodel 4.0.3 → 4.0.5

package/src/clone/errors/ShallowCloneError.ts

@@ -1,8 +0,0 @@
-import CloneError from './CloneError.ts';
-
-/**
- * @public
- */
-class ShallowCloneError extends CloneError {}
-
-export default ShallowCloneError;

package/src/clone/index.ts

@@ -1,195 +0,0 @@
-import { clone } from 'ramda';
-
-import ObjectSlice from '../ObjectSlice.ts';
-import KeyValuePair from '../KeyValuePair.ts';
-import Element from '../primitives/Element.ts';
-import MemberElement from '../primitives/MemberElement.ts';
-import { isElement, hasElementSourceMap, hasElementStyle } from '../predicates/index.ts';
-import SourceMapElement from '../elements/SourceMap.ts';
-import DeepCloneError from './errors/DeepCloneError.ts';
-import ShallowCloneError from './errors/ShallowCloneError.ts';
-
-/**
- * @public
- */
-export type FinalCloneTypes = KeyValuePair | ObjectSlice;
-
-/**
- * @public
- */
-export type DeepCloneOptions = {
-  visited?: WeakMap<object, object>;
-};
-
-const cloneDeepElement = (element: Element, options: DeepCloneOptions): Element => {
-  const { visited = new WeakMap<object, object>() } = options;
-  const passThroughOptions = { ...options, visited };
-
-  // detect cycle and return memoized value
-  if (visited.has(element)) {
-    return visited.get(element) as Element;
-  }
-
-  const copy = cloneShallowElement(element);
-  visited.set(element, copy);
-
-  const { content } = element;
-  if (Array.isArray(content)) {
-    copy.content = content.map((el: Element) => cloneDeepElement(el, passThroughOptions));
-  } else if (isElement(content)) {
-    copy.content = cloneDeepElement(content as Element, passThroughOptions);
-  } else if ((content as unknown) instanceof KeyValuePair) {
-    copy.content = cloneDeepKeyValuePair(content as KeyValuePair, passThroughOptions);
-  } else {
-    copy.content = content;
-  }
-
-  return copy;
-};
-
-const cloneDeepKeyValuePair = (kvp: KeyValuePair, options: DeepCloneOptions): KeyValuePair => {
-  const { visited = new WeakMap<object, object>() } = options;
-  const passThroughOptions = { ...options, visited };
-
-  if (visited.has(kvp)) {
-    return visited.get(kvp) as KeyValuePair;
-  }
-
-  const { key, value } = kvp;
-  const keyCopy = key !== undefined ? cloneDeepElement(key, passThroughOptions) : undefined;
-  const valueCopy = value !== undefined ? cloneDeepElement(value, passThroughOptions) : undefined;
-  const copy = new KeyValuePair(keyCopy, valueCopy);
-  visited.set(kvp, copy);
-  return copy;
-};
-
-const cloneDeepObjectSlice = (slice: ObjectSlice, options: DeepCloneOptions): ObjectSlice => {
-  const { visited = new WeakMap<object, object>() } = options;
-  const passThroughOptions = { ...options, visited };
-
-  if (visited.has(slice)) {
-    return visited.get(slice) as ObjectSlice;
-  }
-
-  const items = [...slice].map(
-    (element) => cloneDeepElement(element, passThroughOptions) as MemberElement,
-  );
-  const copy = new ObjectSlice(items);
-  visited.set(slice, copy);
-  return copy;
-};
-
-/**
- * Creates a deep clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
- * Handles cycles by memoizing visited objects.
- * @public
- */
-export const cloneDeep = <T extends Element | FinalCloneTypes>(
-  value: T,
-  options: DeepCloneOptions = {},
-): T => {
-  if (value instanceof KeyValuePair) {
-    return cloneDeepKeyValuePair(value, options) as T;
-  }
-
-  if (value instanceof ObjectSlice) {
-    return cloneDeepObjectSlice(value, options) as T;
-  }
-
-  if (isElement(value)) {
-    return cloneDeepElement(value, options) as T;
-  }
-
-  throw new DeepCloneError("Value provided to cloneDeep function couldn't be cloned", {
-    value,
-  });
-};
-cloneDeep.safe = <T>(value: T): T => {
-  try {
-    return cloneDeep(value as Element | FinalCloneTypes) as T;
-  } catch {
-    return value;
-  }
-};
-
-const cloneShallowKeyValuePair = (keyValuePair: KeyValuePair): KeyValuePair => {
-  const { key, value } = keyValuePair;
-  return new KeyValuePair(key, value);
-};
-
-const cloneShallowObjectSlice = (objectSlice: ObjectSlice): ObjectSlice => {
-  const items = [...objectSlice];
-  return new ObjectSlice(items);
-};
-
-const cloneShallowElement = <T extends Element>(element: T): T => {
-  const Ctor = element.constructor as new () => T;
-  const copy = new Ctor();
-
-  copy.element = element.element;
-
-  if (!element.isMetaEmpty) {
-    copy.meta = element.meta.cloneDeep();
-  }
-
-  if (!element.isAttributesEmpty) {
-    copy.attributes = cloneDeep(element.attributes);
-  }
-
-  if (hasElementSourceMap(element)) {
-    SourceMapElement.transfer(element, copy);
-  }
-
-  if (hasElementStyle(element)) {
-    copy.style = clone(element.style);
-  }
-
-  const { content } = element;
-  if (isElement(content)) {
-    copy.content = cloneShallowElement(content as Element);
-  } else if (Array.isArray(content)) {
-    copy.content = [...content];
-  } else if ((content as unknown) instanceof KeyValuePair) {
-    copy.content = cloneShallowKeyValuePair(content as KeyValuePair);
-  } else {
-    copy.content = content;
-  }
-
-  return copy;
-};
-
-/**
- * Creates a shallow clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
- * The element itself is cloned, but content references are shared.
- * Meta and attributes are deep cloned to preserve semantic information.
- * @public
- */
-export const cloneShallow = <T extends Element | FinalCloneTypes>(value: T): T => {
-  if (value instanceof KeyValuePair) {
-    return cloneShallowKeyValuePair(value) as T;
-  }
-
-  if (value instanceof ObjectSlice) {
-    return cloneShallowObjectSlice(value) as T;
-  }
-
-  if (isElement(value)) {
-    return cloneShallowElement(value) as T;
-  }
-
-  throw new ShallowCloneError("Value provided to cloneShallow function couldn't be cloned", {
-    value,
-  });
-};
-cloneShallow.safe = <T>(value: T): T => {
-  try {
-    return cloneShallow(value as Element | FinalCloneTypes) as T;
-  } catch {
-    return value;
-  }
-};
-
-export { default as CloneError } from './errors/CloneError.ts';
-export type { CloneErrorOptions } from './errors/CloneError.ts';
-export { default as DeepCloneError } from './errors/DeepCloneError.ts';
-export { default as ShallowCloneError } from './errors/ShallowCloneError.ts';

package/src/elements/Annotation.ts

@@ -1,35 +0,0 @@
-import StringElement from '../primitives/StringElement.ts';
-import type Element from '../primitives/Element.ts';
-import type { Meta, Attributes } from '../types.ts';
-
-/**
- * AnnotationElement represents a parsing annotation (warning or error).
- *
- * The annotation's class indicates its severity:
- * - 'warning' - A non-fatal issue
- * - 'error' - A fatal issue
- *
- * @public
- */
-class AnnotationElement extends StringElement {
-  constructor(content?: string, meta?: Meta, attributes?: Attributes) {
-    super(content, meta, attributes);
-    this.element = 'annotation';
-  }
-
-  /**
-   * The annotation code identifying the type of annotation.
-   */
-  get code(): Element | undefined {
-    if (this.hasAttributesProperty('code')) {
-      return this.attributes.get('code') as Element;
-    }
-    return undefined;
-  }
-
-  set code(value: unknown) {
-    this.attributes.set('code', value);
-  }
-}
-
-export default AnnotationElement;

package/src/elements/Comment.ts

@@ -1,16 +0,0 @@
-import StringElement from '../primitives/StringElement.ts';
-import type { Meta, Attributes } from '../types.ts';
-
-/**
- * CommentElement represents a comment in the source document.
- *
- * @public
- */
-class CommentElement extends StringElement {
-  constructor(content?: string, meta?: Meta, attributes?: Attributes) {
-    super(content, meta, attributes);
-    this.element = 'comment';
-  }
-}
-
-export default CommentElement;

package/src/elements/LinkElement.ts

@@ -1,49 +0,0 @@
-import Element, { type Meta, type Attributes } from '../primitives/Element.ts';
-
-/**
- * LinkElement represents a hyperlink in ApiDOM.
- *
- * Hyperlinking MAY be used to link to other resources, provide links to
- * instructions on how to process a given element (by way of a profile or
- * other means), and may be used to provide meta data about the element in
- * which it's found. The meaning and purpose of the hyperlink is defined by
- * the link relation according to RFC 5988.
- *
- * @public
- */
-class LinkElement extends Element {
-  constructor(content?: unknown, meta?: Meta, attributes?: Attributes) {
-    super(content || [], meta, attributes);
-    this.element = 'link';
-  }
-
-  /**
-   * The relation identifier for the link, as defined in RFC 5988.
-   */
-  get relation(): Element | undefined {
-    if (this.hasAttributesProperty('relation')) {
-      return this.attributes.get('relation');
-    }
-    return undefined;
-  }
-
-  set relation(relation: string | Element | undefined) {
-    this.attributes.set('relation', relation);
-  }
-
-  /**
-   * The URI for the given link.
-   */
-  get href(): Element | undefined {
-    if (this.hasAttributesProperty('href')) {
-      return this.attributes.get('href');
-    }
-    return undefined;
-  }
-
-  set href(href: string | Element | undefined) {
-    this.attributes.set('href', href);
-  }
-}
-
-export default LinkElement;

package/src/elements/ParseResult.ts

@@ -1,94 +0,0 @@
-import ArrayElement from '../primitives/ArrayElement.ts';
-import type Element from '../primitives/Element.ts';
-import { includesClasses } from '../predicates/index.ts';
-import type { Meta, Attributes } from '../primitives/Element.ts';
-
-/**
- * ParseResultElement represents the result of parsing a document.
- *
- * Contains the parsed API element, any result elements, and annotations
- * (warnings and errors) from the parsing process.
- *
- * @public
- */
-class ParseResultElement extends ArrayElement {
-  constructor(content?: unknown[], meta?: Meta, attributes?: Attributes) {
-    super(content, meta, attributes);
-    this.element = 'parseResult';
-  }
-
-  /**
-   * The main API element from the parse result.
-   */
-  get api(): Element | undefined {
-    return this.filter((item) => includesClasses(item, ['api'])).first;
-  }
-
-  /**
-   * All result elements from the parse result.
-   */
-  get results(): ArrayElement {
-    return this.filter((item) => includesClasses(item, ['result']));
-  }
-
-  /**
-   * The first result element.
-   */
-  get result(): Element | undefined {
-    return this.results.first;
-  }
-
-  /**
-   * All annotation elements (warnings and errors).
-   */
-  get annotations(): ArrayElement {
-    return this.filter((item) => item.element === 'annotation');
-  }
-
-  /**
-   * All warning annotations.
-   */
-  get warnings(): ArrayElement {
-    return this.filter(
-      (item) => item.element === 'annotation' && includesClasses(item, ['warning']),
-    );
-  }
-
-  /**
-   * All error annotations.
-   */
-  get errors(): ArrayElement {
-    return this.filter((item) => item.element === 'annotation' && includesClasses(item, ['error']));
-  }
-
-  /**
-   * Whether the parse result is empty (contains only annotations).
-   */
-  override get isEmpty(): boolean {
-    return this.reject((item) => item.element === 'annotation').length === 0;
-  }
-
-  /**
-   * Replaces the first result element with the given replacement.
-   * @returns true if replacement was successful, false otherwise
-   */
-  replaceResult(replacement: Element): boolean {
-    const { result } = this;
-
-    if (result === undefined) {
-      return false;
-    }
-
-    const content = this._content as Element[];
-    const searchIndex = content.findIndex((e) => e === result);
-    if (searchIndex === -1) {
-      return false;
-    }
-
-    content[searchIndex] = replacement;
-
-    return true;
-  }
-}
-
-export default ParseResultElement;

package/src/elements/RefElement.ts

@@ -1,33 +0,0 @@
-import Element, { type Meta, type Attributes } from '../primitives/Element.ts';
-
-/**
- * RefElement represents a reference to another element in ApiDOM.
- * @public
- */
-class RefElement extends Element {
-  constructor(content?: unknown, meta?: Meta, attributes?: Attributes) {
-    super(content || [], meta, attributes);
-    this.element = 'ref';
-
-    if (!this.path) {
-      this.path = 'element';
-    }
-  }
-
-  /**
-   * Path of referenced element to transclude instead of element itself.
-   * @defaultValue 'element'
-   */
-  get path(): Element | undefined {
-    if (this.hasAttributesProperty('path')) {
-      return this.attributes.get('path');
-    }
-    return undefined;
-  }
-
-  set path(newValue: string | Element | undefined) {
-    this.attributes.set('path', newValue);
-  }
-}
-
-export default RefElement;

package/src/elements/SourceMap.ts

@@ -1,170 +0,0 @@
-import StringElement from '../primitives/StringElement.ts';
-import type { Meta, Attributes } from '../types.ts';
-
-/**
- * Shape with optional source position properties.
- * @public
- */
-interface SourceMapShape {
-  startLine?: number;
-  startCharacter?: number;
-  startOffset?: number;
-  endLine?: number;
-  endCharacter?: number;
-  endOffset?: number;
-}
-
-/**
- * SourceMapElement stores source position as a compact VLQ-encoded string.
- *
- * The encoded string contains 6 values: startLine, startCharacter, startOffset,
- * endLine, endCharacter, endOffset. All values use UTF-16 code units,
- * compatible with LSP, TextDocument, and JavaScript string indexing.
- *
- * web-tree-sitter automatically provides position data in UTF-16 code units.
- *
- * @public
- */
-class SourceMapElement extends StringElement {
-  constructor(content?: string, meta?: Meta, attributes?: Attributes) {
-    super(content, meta, attributes);
-    this.element = 'sourceMap';
-  }
-
-  /**
-   * Transfers source position properties from one object to another.
-   */
-  static transfer(from: SourceMapShape, to: SourceMapShape): void {
-    to.startLine = from.startLine;
-    to.startCharacter = from.startCharacter;
-    to.startOffset = from.startOffset;
-    to.endLine = from.endLine;
-    to.endCharacter = from.endCharacter;
-    to.endOffset = from.endOffset;
-  }
-
-  /**
-   * Creates a SourceMapElement from source position properties.
-   * Returns undefined if any position property is not a number.
-   * Also assigns position properties to the instance for inspection.
-   */
-  static from(source: SourceMapShape): SourceMapElement | undefined {
-    const { startLine, startCharacter, startOffset, endLine, endCharacter, endOffset } = source;
-
-    if (
-      typeof startLine !== 'number' ||
-      typeof startCharacter !== 'number' ||
-      typeof startOffset !== 'number' ||
-      typeof endLine !== 'number' ||
-      typeof endCharacter !== 'number' ||
-      typeof endOffset !== 'number'
-    ) {
-      return undefined;
-    }
-
-    const packed = packSourceMap([
-      startLine,
-      startCharacter,
-      startOffset,
-      endLine,
-      endCharacter,
-      endOffset,
-    ]);
-
-    const sourceMap = new SourceMapElement(packed);
-    sourceMap.startLine = startLine;
-    sourceMap.startCharacter = startCharacter;
-    sourceMap.startOffset = startOffset;
-    sourceMap.endLine = endLine;
-    sourceMap.endCharacter = endCharacter;
-    sourceMap.endOffset = endOffset;
-
-    return sourceMap;
-  }
-
-  /**
-   * Decodes the VLQ string and applies source position properties to the target.
-   */
-  public applyTo(target: SourceMapShape): void {
-    if (!this.content) return;
-    [
-      target.startLine,
-      target.startCharacter,
-      target.startOffset,
-      target.endLine,
-      target.endCharacter,
-      target.endOffset,
-    ] = unpackSourceMap(this.content as string);
-  }
-}
-
-const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
-
-// Encode one unsigned integer to Base64-VLQ
-function vlqEncodeInt(value: number): string {
-  let vlq = value >>> 0; // ensure unsigned 32-bit
-  let out = '';
-
-  do {
-    let digit = vlq & 31; // 5 bits
-    vlq >>>= 5;
-    if (vlq !== 0) digit |= 32; // continuation bit
-    out += BASE64[digit];
-  } while (vlq !== 0);
-
-  return out;
-}
-
-// Decode one unsigned integer from Base64-VLQ, starting at `index`
-function vlqDecodeInt(str: string, index = 0): { value: number; next: number } {
-  let result = 0;
-  let shift = 0;
-  let i = index;
-
-  while (true) {
-    const ch = str[i++];
-    const digit = BASE64.indexOf(ch);
-    if (digit === -1) throw new Error(`Invalid Base64 VLQ char: ${ch}`);
-
-    const cont = (digit & 32) !== 0;
-    result |= (digit & 31) << shift;
-    shift += 5;
-
-    if (!cont) break;
-  }
-
-  return { value: result >>> 0, next: i };
-}
-
-/**
- * Span of 6 position values: [startLine, startCharacter, startOffset, endLine, endCharacter, endOffset]
- * @public
- */
-type Span6 = [number, number, number, number, number, number];
-
-/**
- * Encodes 6 position values into a compact VLQ string.
- * @public
- */
-function packSourceMap(v: Span6): string {
-  return 'sm1:' + v.map(vlqEncodeInt).join('');
-}
-
-/**
- * Decodes a VLQ string into 6 position values.
- * @public
- */
-function unpackSourceMap(packed: string): Span6 {
-  const s = packed.startsWith('sm1:') ? packed.slice(4) : packed;
-  const out: number[] = [];
-  let i = 0;
-  for (let k = 0; k < 6; k++) {
-    const r = vlqDecodeInt(s, i);
-    out.push(r.value);
-    i = r.next;
-  }
-  return out as Span6;
-}
-
-export default SourceMapElement;
-export type { Span6, SourceMapShape };

package/src/elements/Style.ts

@@ -1,56 +0,0 @@
-import ObjectElement from '../primitives/ObjectElement.ts';
-import type { Meta, Attributes } from '../types.ts';
-
-/**
- * Shape with optional style property.
- * @public
- */
-interface StyleShape {
-  style?: Record<string, unknown>;
-}
-
-/**
- * StyleElement stores format-specific style information for round-trip preservation.
- *
- * The style data is stored as a plain object with format-specific namespaces
- * (e.g., `yaml`, `json`). This element exists only during serialization/deserialization
- * (refract format) - in memory, style lives directly on `element.style`.
- *
- * Follows the same pattern as SourceMapElement with __mappings__.
- *
- * @public
- */
-class StyleElement extends ObjectElement {
-  constructor(content?: Record<string, unknown>, meta?: Meta, attributes?: Attributes) {
-    super(content, meta, attributes);
-    this.element = '__styles__';
-  }
-
-  /**
-   * Transfers style property from one element to another.
-   */
-  static transfer(from: StyleShape, to: StyleShape): void {
-    to.style = from.style;
-  }
-
-  /**
-   * Creates a StyleElement from an element's style property.
-   * Returns undefined if the element has no style.
-   */
-  static from(source: StyleShape): StyleElement | undefined {
-    if (!source.style) {
-      return undefined;
-    }
-    return new StyleElement(source.style);
-  }
-
-  /**
-   * Restores the style property on the target element from this StyleElement.
-   */
-  public applyTo(target: StyleShape): void {
-    target.style = this.toValue() as Record<string, unknown>;
-  }
-}
-
-export default StyleElement;
-export type { StyleShape };