@speclynx/apidom-datamodel 1.12.2 → 2.0.0

package/types/apidom-datamodel.d.ts

@@ -1,3 +1,24 @@
+import type { ApiDOMErrorOptions } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+
+/**
+ * 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
+ */
+export declare class AnnotationElement extends StringElement {
+    constructor(content?: string, meta?: Meta, attributes?: Attributes);
+    /**
+     * The annotation code identifying the type of annotation.
+     */
+    get code(): Element_2 | undefined;
+    set code(value: unknown);
+}
+
 /**
  * ArrayElement represents an array/collection of elements in ApiDOM.
  *
@@ -5,8 +26,6 @@
  * @public
  */
 export declare class ArrayElement<T extends Element_2 = Element_2> extends CollectionElement<T> {
-    static empty<T extends Element_2 = Element_2>(): ArrayElement<T>;
-    static 'fantasy-land/empty'<T extends Element_2 = Element_2>(): ArrayElement<T>;
     constructor(content?: unknown[], meta?: Meta, attributes?: Attributes);
     primitive(): string;
     /**
@@ -58,11 +77,7 @@ export declare class ArrayElement<T extends Element_2 = Element_2> extends Colle
     /**
      * Returns an empty array element.
      */
-    empty(): ArrayElement<T>;
-    'fantasy-land/map'(transform: (element: T) => T): ArrayElement<T>;
-    'fantasy-land/chain'(transform: (element: T) => ArrayElement<T>): ArrayElement<T>;
-    'fantasy-land/filter'(callback: (element: T) => boolean): ArrayElement<T>;
-    'fantasy-land/reduce'<U>(transform: (acc: U, element: T) => U, initialValue: U): U;
+    empty(): this;
 }
 
 /**
@@ -83,13 +98,41 @@ export declare class BooleanElement extends Element_2 {
 }
 
 /**
- * Type for cloneable objects.
+ * Creates a deep clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
+ * Handles cycles by memoizing visited objects.
  * @public
  */
-export declare interface Cloneable<T> {
-    clone(): T;
+export declare const cloneDeep: {
+    <T extends Element_2 | FinalCloneTypes>(value: T, options?: DeepCloneOptions): T;
+    safe<T>(value: T): T;
+};
+
+/**
+ * @public
+ */
+export declare class CloneError extends ApiDOMStructuredError {
+    readonly value: unknown;
+    constructor(message?: string, structuredOptions?: CloneErrorOptions);
 }
 
+/**
+ * @public
+ */
+export declare interface CloneErrorOptions extends ApiDOMErrorOptions {
+    readonly value: unknown;
+}
+
+/**
+ * Creates a shallow clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
+ * The element itself is cloned, but content references are shared (except for
+ * meta and attributes which are deep cloned to preserve semantic information).
+ * @public
+ */
+export declare const cloneShallow: {
+    <T extends Element_2 | FinalCloneTypes>(value: T): T;
+    safe<T>(value: T): T;
+};
+
 /**
  * CollectionElement is an abstract base class for collection-like elements.
  * Both ArrayElement and ObjectElement extend this class.
@@ -128,13 +171,9 @@ export declare abstract class CollectionElement<T extends Element_2 = Element_2>
      */
     get last(): T | undefined;
     /**
-     * Adds the given element to the end of the collection.
+     * Adds the given elements to the end of the collection.
      */
-    push(value: unknown): this;
-    /**
-     * Alias for push.
-     */
-    add(value: unknown): void;
+    push(...values: unknown[]): this;
     /**
      * Removes the first element from the collection.
      */
@@ -170,16 +209,36 @@ export declare abstract class CollectionElement<T extends Element_2 = Element_2>
     /**
      * Returns an empty collection element.
      */
-    abstract empty(): CollectionElement<T>;
-    'fantasy-land/empty'(): CollectionElement<T>;
+    abstract empty(): this;
     /**
      * Concatenates two collection elements.
      */
-    concat(other: CollectionElement<T>): CollectionElement<T>;
-    'fantasy-land/concat'(other: CollectionElement<T>): CollectionElement<T>;
+    concat(other: CollectionElement<T>): this;
     [Symbol.iterator](): IterableIterator<T>;
 }
 
+/**
+ * CommentElement represents a comment in the source document.
+ *
+ * @public
+ */
+export declare class CommentElement extends StringElement {
+    constructor(content?: string, meta?: Meta, attributes?: Attributes);
+}
+
+/**
+ * @public
+ */
+export declare class DeepCloneError extends CloneError {
+}
+
+/**
+ * @public
+ */
+export declare type DeepCloneOptions = {
+    visited?: WeakMap<object, object>;
+};
+
 /**
  * Tuple of detection test and element class.
  * @public
@@ -203,7 +262,41 @@ export declare type DetectionTest = (value: unknown) => boolean;
  *
  * @public
  */
-declare class Element_2 implements Cloneable<Element_2>, ToValue, Equatable, Freezable {
+declare class Element_2 implements ToValue, Equatable, Freezable {
+    /**
+     * Parent element reference (set when tree is frozen).
+     */
+    parent?: Element_2;
+    /**
+     * Starting line number (0-based).
+     * Compatible with LSP Position.line.
+     */
+    startLine?: number;
+    /**
+     * Starting character offset within the line (0-based, UTF-16 code units).
+     * Compatible with LSP Position.character.
+     */
+    startCharacter?: number;
+    /**
+     * Starting offset from beginning of document (UTF-16 code units).
+     * Can be used directly as JavaScript string index.
+     */
+    startOffset?: number;
+    /**
+     * Ending line number (0-based).
+     * Compatible with LSP Position.line.
+     */
+    endLine?: number;
+    /**
+     * Ending character offset within the line (0-based, UTF-16 code units).
+     * Compatible with LSP Position.character.
+     */
+    endCharacter?: number;
+    /**
+     * Ending offset from beginning of document (UTF-16 code units).
+     * Can be used directly as JavaScript string index.
+     */
+    endOffset?: number;
     /**
      * The element type identifier.
      * @internal
@@ -224,10 +317,6 @@ declare class Element_2 implements Cloneable<Element_2>, ToValue, Equatable, Fre
      * @internal
      */
     protected _attributes?: Element_2;
-    /**
-     * Parent element reference (set when tree is frozen).
-     */
-    parent?: Element_2;
     /** @internal ObjectElement constructor for creating meta/attributes */
     ObjectElement: new (content?: Record<string, unknown>) => ObjectElement;
     /** @internal ArrayElement constructor for creating arrays */
@@ -267,17 +356,11 @@ declare class Element_2 implements Cloneable<Element_2>, ToValue, Equatable, Fre
     get id(): Element_2;
     set id(value: Element_2 | string);
     /** CSS-like class names. */
-    get classes(): Element_2;
-    set classes(value: Element_2 | unknown[]);
-    /** Human-readable title. */
-    get title(): Element_2;
-    set title(value: Element_2 | string);
-    /** Human-readable description. */
-    get description(): Element_2;
-    set description(value: Element_2 | string);
+    get classes(): ArrayElement;
+    set classes(value: ArrayElement | unknown[]);
     /** Hyperlinks associated with this element. */
-    get links(): Element_2;
-    set links(value: Element_2 | unknown[]);
+    get links(): ArrayElement;
+    set links(value: ArrayElement | unknown[]);
     /** Returns direct children of this element. */
     get children(): Element_2[];
     /** Whether this element is frozen (immutable). */
@@ -287,10 +370,6 @@ declare class Element_2 implements Cloneable<Element_2>, ToValue, Equatable, Fre
      * Sets up parent references for tree traversal.
      */
     freeze(): void;
-    /**
-     * Creates a deep clone of this element.
-     */
-    clone(): Element_2;
     /**
      * Converts the element to its JavaScript value representation.
      */
@@ -318,11 +397,35 @@ declare class Element_2 implements Cloneable<Element_2>, ToValue, Equatable, Fre
     /**
      * Gets a meta property, creating it with default value if not present.
      */
-    protected getMetaProperty(name: string, defaultValue: unknown): Element_2;
+    getMetaProperty(name: string, defaultValue: unknown): Element_2;
     /**
      * Sets a meta property.
      */
-    protected setMetaProperty(name: string, value: unknown): void;
+    setMetaProperty(name: string, value: unknown): void;
+    /**
+     * Has meta property.
+     */
+    hasMetaProperty(name: string): boolean;
+    /**
+     * Checks if meta is empty.
+     */
+    get isMetaEmpty(): boolean;
+    /**
+     * Gets an attribute property, creating it with default value if not present.
+     */
+    getAttributesProperty(name: string, defaultValue: unknown): Element_2;
+    /**
+     * Sets an attributes property.
+     */
+    setAttributesProperty(name: string, value: unknown): void;
+    /**
+     * Has attributes property.
+     */
+    hasAttributesProperty(name: string): boolean;
+    /**
+     * Checks if attributes is empty.
+     */
+    get isAttributesEmpty(): boolean;
 }
 export { Element_2 as Element }
 
@@ -355,6 +458,11 @@ export declare interface Equatable {
     equals(value: unknown): boolean;
 }
 
+/**
+ * @public
+ */
+export declare type FinalCloneTypes = KeyValuePair | ObjectSlice;
+
 /**
  * Condition function for finding elements.
  * @public
@@ -379,6 +487,98 @@ export declare interface Freezable {
     readonly isFrozen: boolean;
 }
 
+/**
+ * Checks if an element has complete source position information.
+ * Returns true only if all 6 position properties are numbers.
+ * @public
+ */
+export declare const hasElementSourceMap: <T extends Element_2>(element: T) => boolean;
+
+/**
+ * @public
+ */
+export declare const includesClasses: <T extends Element_2>(element: T, classes: string[]) => boolean;
+
+/**
+ * @public
+ */
+export declare const includesSymbols: <T extends Element_2>(element: T, symbols: string[]) => boolean;
+
+/**
+ * @public
+ */
+export declare const isAnnotationElement: (element: unknown) => element is AnnotationElement;
+
+/**
+ * @public
+ */
+export declare const isArrayElement: (element: unknown) => element is ArrayElement;
+
+/**
+ * @public
+ */
+export declare const isBooleanElement: (element: unknown) => element is BooleanElement;
+
+/**
+ * @public
+ */
+export declare const isCommentElement: (element: unknown) => element is CommentElement;
+
+/**
+ * @public
+ */
+export declare const isElement: (element: unknown) => element is Element_2;
+
+/**
+ * @public
+ */
+export declare const isLinkElement: (element: unknown) => element is LinkElement;
+
+/**
+ * @public
+ */
+export declare const isMemberElement: (element: unknown) => element is MemberElement;
+
+/**
+ * @public
+ */
+export declare const isNullElement: (element: unknown) => element is NullElement;
+
+/**
+ * @public
+ */
+export declare const isNumberElement: (element: unknown) => element is NumberElement;
+
+/**
+ * @public
+ */
+export declare const isObjectElement: (element: unknown) => element is ObjectElement;
+
+/**
+ * @public
+ */
+export declare const isParseResultElement: (element: unknown) => element is ParseResultElement;
+
+/**
+ * @public
+ */
+export declare const isPrimitiveElement: (element: unknown) => element is PrimitiveElement;
+
+/**
+ * @public
+ */
+export declare const isRefElement: (element: unknown) => element is RefElement;
+
+/**
+ * @public
+ */
+export declare const isSourceMapElement: (element: unknown) => element is SourceMapElement;
+
+/**
+ * @public
+ */
+export declare const isStringElement: (element: unknown) => element is StringElement;
+
 /**
  * JSONSerialiser handles serialization and deserialization of ApiDOM elements
  * to and from JSON Refract format.
@@ -410,14 +610,10 @@ export declare class JSONSerialiser {
  * @typeParam V - Value element type
  * @public
  */
-export declare class KeyValuePair<K extends Element_2 = Element_2, V extends Element_2 = Element_2> implements Cloneable<KeyValuePair<K, V>> {
+export declare class KeyValuePair<K extends Element_2 = Element_2, V extends Element_2 = Element_2> {
     key: K | undefined;
     value: V | undefined;
     constructor(key?: K, value?: V);
-    /**
-     * Creates a deep clone of the KeyValuePair.
-     */
-    clone(): KeyValuePair<K, V>;
     /**
      * Converts to a plain JavaScript object representation.
      */
@@ -682,7 +878,7 @@ export declare class ObjectElement<K extends Element_2 = Element_2, V extends El
     /**
      * Returns an empty object element.
      */
-    empty(): ObjectElement<K, V>;
+    empty(): this;
 }
 
 /**
@@ -772,10 +968,6 @@ export declare class ObjectSlice {
      * @param member - The member element to add
      */
     push(member: MemberElement): this;
-    /**
-     * Creates a deep clone of the ObjectSlice.
-     */
-    clone(): ObjectSlice;
     /**
      * Determines whether the slice includes a member with the given key value.
      * @param keyValue - The key value to search for
@@ -800,6 +992,56 @@ export declare type ObjectSliceCallback<U> = (value: Element_2, key: Element_2,
  */
 export declare type ObjectSliceForEachCallback = (value: Element_2, key: Element_2, member: MemberElement, index: number) => void;
 
+/**
+ * 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
+ */
+export declare class ParseResultElement extends ArrayElement {
+    constructor(content?: unknown[], meta?: Meta, attributes?: Attributes);
+    /**
+     * The main API element from the parse result.
+     */
+    get api(): Element_2 | undefined;
+    /**
+     * All result elements from the parse result.
+     */
+    get results(): ArrayElement;
+    /**
+     * The first result element.
+     */
+    get result(): Element_2 | undefined;
+    /**
+     * All annotation elements (warnings and errors).
+     */
+    get annotations(): ArrayElement;
+    /**
+     * All warning annotations.
+     */
+    get warnings(): ArrayElement;
+    /**
+     * All error annotations.
+     */
+    get errors(): ArrayElement;
+    /**
+     * Whether the parse result is empty (contains only annotations).
+     */
+    get isEmpty(): boolean;
+    /**
+     * Replaces the first result element with the given replacement.
+     * @returns true if replacement was successful, false otherwise
+     */
+    replaceResult(replacement: Element_2): boolean;
+}
+
+/**
+ * @public
+ */
+export declare type PrimitiveElement = ObjectElement | ArrayElement | BooleanElement | NumberElement | StringElement | NullElement | MemberElement;
+
 /**
  * Primitive JavaScript values that can be element content.
  * @public
@@ -863,6 +1105,60 @@ export declare interface SerializedKeyValuePair {
     value?: SerializedElement;
 }
 
+/**
+ * @public
+ */
+export declare class ShallowCloneError extends CloneError {
+}
+
+/**
+ * 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
+ */
+export declare class SourceMapElement extends StringElement {
+    constructor(content?: string, meta?: Meta, attributes?: Attributes);
+    /**
+     * Transfers source position properties from one object to another.
+     */
+    static transfer(from: SourceMapShape, to: SourceMapShape): void;
+    /**
+     * 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;
+    /**
+     * Decodes the VLQ string and applies source position properties to the target.
+     */
+    applyTo(target: SourceMapShape): void;
+}
+
+/**
+ * Shape with optional source position properties.
+ * @public
+ */
+export declare interface SourceMapShape {
+    startLine?: number;
+    startCharacter?: number;
+    startOffset?: number;
+    endLine?: number;
+    endCharacter?: number;
+    endOffset?: number;
+}
+
+/**
+ * Span of 6 position values: [startLine, startCharacter, startOffset, endLine, endCharacter, endOffset]
+ * @public
+ */
+export declare type Span6 = [number, number, number, number, number, number];
+
 /**
  * StringElement represents a string value in ApiDOM.
  * @public